Skip to content

Sorting cCJGrid Data

Simple grids (cCJGrid) and data-aware grids (cDbCJGrid) with a static datasource (pbStaticData = true) can sort the grid rows using the data in any column, including hidden columns. The rows can be sorted in ascending or descending order. The sorting is performed by sorting the data that has been loaded in the datasource, then the grid is refreshed using the new row order in the datasource.

If you set pbHeaderReorders to True, clicking the mouse in a column header triggers the grid to sort the rows around the clicked column. If pbHeaderTogglesDirection is also True, then each click on the currently sorted column reverses the sort order.

The column's peDataType property determines how the column values are sorted. For example, if peDataType = Ascii_Window, the following values (1, 9, 10, 2, 100) would be sorted as (1, 10, 100, 2, 9). If peDataType = 0 (i.e., Number data type), then the values would be sorted as (1, 2, 9, 10, 100).

Use Get piSortColumn to retrieve the piColumnId of the column the grid is currently sorted around. This property returns -1 if the datasource has not been sorted. This property is set whenever the datasource is sorted.

To programmatically sort the grid around a grid column, send SortGridByColumn to the grid object, passing the column object handle and the desired sort order.

Column Sort Rules

Each column object can define a set of column sort rules. Whenever a grid is sorted around a column (via SortGridByColumn), that column's sort rules are applied. By default, a column's sort rules state that the data is to be sorted using the data in that column, using the column's data type (peDataType) to determine the precedence.

To customize the sort rules for a column, you should augment the column's ColumnSortRules function. The return value of this function is the structured data type tGridSortRules.

By default, ColumnSortRules returns a single column segment based on the column. The function looks like this:

Function ColumnSortRules Returns tGridSortRules
    tGridSortRules SortRules
    Get piColumnId to SortRules.Rules[0].iColumn
    Get peDataType to SortRules.Rules[0].eDataType
    Function_Return SortRules
End_Function

The bDescending member of the tGridSortRules struct is not specified, but the effective value would be False in this case.

Sorting by Multiple Columns

Often a column contains multiple instances of the same value. For example, a "country name" column from a list of customer addresses. In this case, you may want to introduce secondary or tertiary sort orders to sort rows where the country name is the same. This is done by adding more elements to the tGridSortRules.Rules array.

The following example demonstrates how to add the "state" and "city" columns as secondary and tertiary sort orders for a "country name" column:

Object oCountryCol is a cCJGridColumn
    Set piWidth to 61
    Set psCaption to "Country"

    Function ColumnSortRules Returns tGridSortRules
        tGridSortRules SortRules
        Forward Get ColumnSortRules to SortRules
        // add secondary & tertiary (city & country) sort segments.
        Get piColumnId of oStateCol to SortRules.Rules[1].iColumn
        Get peDataType of oStateCol to SortRules.Rules[1].eDataType
        Get piColumnId of oCityCol to SortRules.Rules[2].iColumn
        Get peDataType of oCityCol to SortRules.Rules[2].eDataType
        Function_Return SortRules
    End_Function
End_Object

Indicating the Sorted Column

When the grid data is sorted around a column, a "sort triangle" symbol is displayed in the column header of that column. When the sort order of the column is reversed, this sort triangle is inverted. To disable drawing a sort triangle, set peDrawSortTriangleStyle to xtpReportDrawSortTriangleNever.

You can also choose to paint the entire sorted column using a shaded background. Set pbShadeSortColumn to true to shade the sorted column using the default shade sort color. To change the color used to shade the sorted column, set piShadeSortColor.

See Also