PivotGridControl.CustomFieldSort Event
Allows you to provide a custom sorting algorithm for the field values.
Namespace: DevExpress.XtraPivotGrid
Assembly: DevExpress.XtraPivotGrid.v19.1.dll
Declaration
Event Data
The CustomFieldSort event's data class is PivotGridCustomFieldSortEventArgs. The following properties provide information specific to this event:
Property | Description |
---|---|
Data | For internal use. Inherited from PivotGridCustomFieldSortEventArgsBase<T>. |
Field | Gets the field whose values are being compared. Inherited from PivotGridCustomFieldSortEventArgsBase<T>. |
Handled | Gets or sets whether a comparison operation is being handled, so no default processing is required. Inherited from PivotGridCustomFieldSortEventArgsBase<T>. |
ListSourceRowIndex1 | Gets the index in the data source for the first of the two rows being compared. Inherited from PivotGridCustomFieldSortEventArgsBase<T>. |
ListSourceRowIndex2 | Gets the index in the data source for the second of the two rows being compared. Inherited from PivotGridCustomFieldSortEventArgsBase<T>. |
Result | Gets or sets the result of a custom comparison. Inherited from PivotGridCustomFieldSortEventArgsBase<T>. |
SortLocation | Gets a target UI element to whose values sorting is applied. Inherited from PivotGridCustomFieldSortEventArgsBase<T>. |
SortOrder | Gets the sort order applied to the field. Inherited from PivotGridCustomFieldSortEventArgsBase<T>. |
Value1 | Gets the first value being compared. Inherited from PivotGridCustomFieldSortEventArgsBase<T>. |
Value2 | Gets the second value being compared. Inherited from PivotGridCustomFieldSortEventArgsBase<T>. |
The event data class exposes the following methods:
Method | Description |
---|---|
GetListSourceColumnValue(Int32, String) | Gets a value from the specified row and column. Inherited from PivotGridCustomFieldSortEventArgsBase<T>. |
GetSortResult() | For internal use. Inherited from PivotGridCustomFieldSortEventArgsBase<T>. |
SetArgs(ICustomSortRowsEventArgs) | Initializes the PivotGridCustomFieldSortEventArgsBase<T> instance with values obtained from the specified object. For internal use. Inherited from PivotGridCustomFieldSortEventArgsBase<T>. |
Remarks
The CustomFieldSort event occurs for the field whose PivotGridFieldBase.SortMode property is set to the PivotSortMode.Custom value. Handle the CustomFieldSort event to provide a custom sorting algorithm for the field values.
Important
In OLAP or server mode, handle the PivotGridControl.CustomServerModeSort event instead.
How to Sort Field Values in Pivot Grid
The CustomFieldSort event fires for pairs of field values before they are grouped according to the layout of column and row fields. To establish a new sort order, perform the following actions:
- Get values to compare from the e.Value1 and e.Value2 properties.
Compare these values and assign the result to the e.Result property as follows:
- -1 if the first value should be placed before the second value when values are sorted in ascending order. When values are sorted in descending order, the first value is after the second value.
- 1 if the first value should be placed after the second value when values are sorted in ascending order. When values are sorted in descending order, the first value is placed before the second value.
- 0 to indicate that the values are equal. The rows are grouped into one field value.
Note
Values are sorted before grouping. If the values are equal (the e.Result is set to 0), they are in the same group.
To get additional field values from the data source, call the e.GetListSourceColumnValue method with the following parameters:
- Set row index parameter to the e.ListSourceRowIndex1 or e.ListSourceRowIndex2 value
- Set the column name parameter to the field name. The current field name is available with the e.Field.FieldName property.
Set the e.Handled property to true to finalize the comparison and use the e.Result value. Otherwise, the default comparison is in effect and e.Result is ignored.
Note
The CustomFieldSort event occurs in different situations in PivotDataProcessingEngine.Legacy and PivotDataProcessingEngine.LegacyOptimized modes because of the different workflow - the legacy engine aggregates data after sorting performed at the data source level, while the optimized engine sorts the aggregated data. The legacy engine raises the CustomFieldSort event more often to compare different rows of data. The optimized engine raises the event to compare the resulting data groups.
However, you can still use the e.ListSourceRowIndex1 and e.ListSourceRowIndex2 properties and the e.GetListSourceColumnValue method. They return the data from the first data row included in the processed group.
How to Sort Filter Values in Filter Drop-Down
Handle the CustomFieldSort event to sort unique filter values in the Filter Drop-Down. To determine whether the data comes from the filter, check the e.SortLocation property - its value is PivotSortLocation.Filter or PivotSortLocation.GroupFilter.
Important
A field value in a filter relates to multiple rows in the underlying data source. The ListSourceRowIndex1 and ListSourceRowIndex2 properties are always -1 when the event fires for the field located in the Filter Drop-Down.
Example
This example demonstrates how to sort a field (Sales Person) by the hidden data field values (Last Name) in the pivot’s column header (the field’s SortLocation is Pivot ). If a field is located in a filter popup, a custom comparison method is used to to sort the field values.
Note
The complete sample project CustomFieldSort - How to Use a Hidden Field to Sort the Visible Field is available in the DevExpress Examples repository.
using DevExpress.XtraEditors;
using DevExpress.XtraPivotGrid;
using System;
using System.Collections;
namespace CustomFieldSortExample
{
public partial class Form1 : XtraForm
{
public Form1()
{
InitializeComponent();
pivotGridControl1.CustomFieldSort += new PivotGridCustomFieldSortEventHandler(pivotGridControl1_CustomFieldSort);
}
private void Form1_Load(object sender, EventArgs e)
{
excelDataSource1.FileName = "SalesPerson.xlsx";
excelDataSource1.Fill();
pivotGridControl1.BestFit();
}
private void checkEdit1_CheckedChanged(object sender, EventArgs e)
{
fieldSalesPerson1.SortMode = ((CheckEdit)sender).Checked ? PivotSortMode.Custom : PivotSortMode.Default;
}
void pivotGridControl1_CustomFieldSort(object sender, PivotGridCustomFieldSortEventArgs e)
{
if (e.Field.FieldName == "Sales Person")
{
if (e.SortLocation == PivotSortLocation.Pivot)
{
object orderValue1 = e.GetListSourceColumnValue(e.ListSourceRowIndex1, "Last Name"),
orderValue2 = e.GetListSourceColumnValue(e.ListSourceRowIndex2, "Last Name");
e.Result = Comparer.Default.Compare(orderValue1, orderValue2);
}
else
{
e.Result = Comparer.Default.Compare(e.Value1.ToString().Split(' ')[1], e.Value2.ToString().Split(' ')[1]);
}
e.Handled = true;
}
}
}
}
Related GitHub Examples
The following code snippets (auto-collected from DevExpress Examples) contain references to the CustomFieldSort event.
Note
The algorithm used to collect these code examples remains a work in progress. Accordingly, the links and snippets below may produce inaccurate results. If you encounter an issue with code examples below, please use the feedback form on this page to report the issue.