PivotGridControl.CustomFieldSort Event
Provides the ability to sort data using custom rules.
Namespace: DevExpress.Xpf.PivotGrid
Assembly: DevExpress.Xpf.PivotGrid.v18.2.dll
Declaration
Event Data
The CustomFieldSort event's data class is PivotCustomFieldSortEventArgs. The following properties provide information specific to this event:
| Property | Description |
|---|---|
| Field | Gets the field whose values are being compared. |
| Handled | Gets or sets whether a comparison operation is being handled and therefore no default processing is required. |
| ListSourceRowIndex1 | Gets the index in the data source of the first of the two rows being compared. |
| ListSourceRowIndex2 | Gets the index in the data source of the second of the two rows being compared. |
| Result | Gets or sets the result of a custom comparison. |
| SortLocation | Gets a target UI element to whose values sorting is applied. |
| SortOrder | Gets the sort order applied to the field. |
| ThreadSafeField | Gets the field whose values are being compared. Provides read-only access to field settings. |
| Value1 | Gets the first value being compared. |
| Value2 | Gets the second value being compared. |
The event data class exposes the following methods:
| Method | Description |
|---|---|
| GetListSourceColumnValue(Int32, String) | Gets a value from the specified row and column. |
Remarks
Handle the CustomFieldSort event to provide a custom sorting algorithm for a specific field. Note that the PivotGridField.SortMode property of this field should be set to FieldSortMode.Custom to apply custom sorting. Otherwise, the CustomFieldSort event will not be raised.
The CustomFieldSort event fires for pairs of rows in the underlying data source, before data is grouped according to the layout of column and row fields. The PivotCustomFieldSortEventArgs.ListSourceRowIndex1 and PivotCustomFieldSortEventArgs.ListSourceRowIndex2 parameters identify the indexes of the rows. The field being processed is specified by the PivotCustomFieldSortEventArgs.Field parameter. The field’s values in these rows are specified by the PivotCustomFieldSortEventArgs.Value1 and PivotCustomFieldSortEventArgs.Value2 parameters.
Important
Use the PivotCustomFieldSortEventArgs.ThreadSafeField property instead of PivotCustomFieldSortEventArgs.Field to access fields in the CustomFieldSort event handler when Asynchronous Mode is enabled.
In the event handler, you should compare these two values and assign the result to the PivotCustomFieldSortEventArgs.Result property as follows:
- set Result to -1 if the first row should be positioned above the second row when data is sorted in ascending order. When data is sorted in descending order the first row will be positioned below the second row.
- set Result to 1 if the first row should be positioned below the second row when data is sorted in ascending order. When data is sorted in descending order the first row will be positioned above the second row.
- set Result to 0 to indicate that the rows are equal. In this case, the compared rows will be grouped into one field value.
If your comparison logic requires additional data from the underlying data source, use the PivotCustomFieldSortEventArgs.GetListSourceColumnValue method. This method allows you to obtain values from the data source by a column name and row index.
The PivotCustomFieldSortEventArgs.Handled parameter should be set to true if the current comparison operation was handled. You can leave this parameter set to false to invoke the default comparison mechanism after your event handler has finished. In the latter instance, the result of a custom comparison operation is ignored.
The CustomFieldSort event also fires to sort unique filter values in the Filter Drop-Down. Each filter value may correspond to multiple rows in the underlying data source. So, the event’s ListSourceRowIndex1 and ListSourceRowIndex2 parameters cannot be used to identify underlying rows. They are set to -1 when comparing filter values in the Filter Drop-Down.
Note
Custom sorting is not supported in OLAP or server mode. To sort data in OLAP and server mode using custom algorithms, handle the PivotGridControl.CustomServerModeSort event.