PivotGridControl.CustomFieldSort Event

Provides the capability to sort data using custom rules.

Namespace: DevExpress.XtraPivotGrid

Assembly: DevExpress.XtraPivotGrid.v18.1.dll

Declaration

C#

public event PivotGridCustomFieldSortEventHandler CustomFieldSort

VB.NET

Public Event CustomFieldSort As PivotGridCustomFieldSortEventHandler

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.
Field	Gets the field whose values are being compared.
Handled	Gets or sets whether a comparison operation is being handled, so no default processing is required.
ListSourceRowIndex1	Gets the index in the data source for the first of the two rows being compared.
ListSourceRowIndex2	Gets the index in the data source for 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.
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.
GetSortResult()	For internal use.
SetArgs(Int32, Int32, Object, Object, PivotSortOrder)	For internal use.

Remarks

Handle the CustomFieldSort event to provide a custom sorting algorithm for a specific field. Note that the PivotGridFieldBase.SortMode property of this field should be set to PivotSortMode.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 PivotGridCustomFieldSortEventArgsBase<T>.ListSourceRowIndex1 and PivotGridCustomFieldSortEventArgsBase<T>.ListSourceRowIndex2 parameters identify the indexes of the rows. The field being processed is specified by the PivotGridCustomFieldSortEventArgsBase<T>.Field parameter. The field values in these rows are specified by the PivotGridCustomFieldSortEventArgsBase<T>.Value1 and PivotGridCustomFieldSortEventArgsBase<T>.Value2 parameters.

In the event handler, compare these two values and assign the result to the PivotGridCustomFieldSortEventArgsBase<T>.Result property as follows:

• Set the 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 the 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 the Result to 0 to indicate that the rows are equal. In this case, the compared rows will be grouped into one field value.

Note

Note that the sorting is applied before grouping. So, if the rows are equal (the Result is set to 0) the corresponding field values will be grouped into a single category.

If your comparison logic requires additional data from the underlying data source, use the PivotGridCustomFieldSortEventArgsBase<T>.GetListSourceColumnValue method. This method allows you to obtain values from the data source by a column name and row index.

The PivotGridCustomFieldSortEventArgsBase<T>.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 the 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.

Example

This example demonstrates how to implement a custom sorting algorithm by handling the PivotGridControl.CustomFieldSort event.

The image shows the result:

C#

using DevExpress.XtraPivotGrid;

// fieldResult
this.fieldResult.SortMode = DevExpress.XtraPivotGrid.PivotSortMode.Custom;

private void pivotGridControl1_CustomFieldSort(object sender, 
  PivotGridCustomFieldSortEventArgs e) {
    if (e.Field.FieldName == "Result") {
        if (e.Value1 == null || e.Value2 == null) return;
        e.Handled = true;
        string s1 = e.Value1.ToString().Replace("Result ", String.Empty);
        string s2 = e.Value2.ToString().Replace("Result ", String.Empty);
        if (Convert.ToInt32(s1) > Convert.ToInt32(s2))
            e.Result = 1;
        else
            if (Convert.ToInt32(s1) == Convert.ToInt32(s2))
                e.Result = Comparer<Int32>.Default.Compare(Convert.ToInt32(s1), 
                  Convert.ToInt32(s2));
            else
                e.Result = -1;
    }
}

VB.NET

Imports DevExpress.XtraPivotGrid

' fieldResult
Me.fieldResult.SortMode = DevExpress.XtraPivotGrid.PivotSortMode.Custom

Private Sub pivotGridControl1_CustomFieldSort(ByVal sender As Object, _
  ByVal e As PivotGridCustomFieldSortEventArgs) Handles pivotGridControl1.CustomFieldSort
    If e.Field.FieldName = "Result" Then
        If e.Value1 Is Nothing OrElse e.Value2 Is Nothing Then
            Return
        End If
        e.Handled = True
        Dim s1 As String = e.Value1.ToString().Replace("Result ", String.Empty)
        Dim s2 As String = e.Value2.ToString().Replace("Result ", String.Empty)
        If Convert.ToInt32(s1) > Convert.ToInt32(s2) Then
            e.Result = 1
        Else
            If Convert.ToInt32(s1) = Convert.ToInt32(s2) Then
                e.Result = Comparer(Of Int32).Default.Compare(Convert.ToInt32(s1), _
                  Convert.ToInt32(s2))
            Else
                e.Result = -1
            End If
        End If
    End If
End Sub

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.

C#

how-to-reorder-pivotgrid-rows-and-columns-by-drag-and-drop-e4545/CS/ReorderHelper.cs#L61

targetPivot = pivot;
targetPivot.CustomFieldSort += targetPivot_CustomFieldSort;
targetPivot.MouseMove += targetPivot_MouseMove;

customfieldsort-how-to-sort-field-values-by-invisible-data-column-values-e331/CS/CustomFieldSortExample/Form1.cs#L11

    InitializeComponent();
    pivotGridControl1.CustomFieldSort += new PivotGridCustomFieldSortEventHandler(pivotGridControl1_CustomFieldSort);
}

VB.NET

how-to-reorder-pivotgrid-rows-and-columns-by-drag-and-drop-e4545/VB/ReorderHelper.vb#L83

targetPivot_Renamed = pivot
AddHandler targetPivot_Renamed.CustomFieldSort, AddressOf targetPivot_CustomFieldSort
AddHandler targetPivot_Renamed.MouseMove, AddressOf targetPivot_MouseMove

customfieldsort-how-to-sort-field-values-by-invisible-data-column-values-e331/VB/CustomFieldSortExample/Form1.vb#L12

    InitializeComponent()
    AddHandler pivotGridControl1.CustomFieldSort, AddressOf pivotGridControl1_CustomFieldSort
End Sub

using-customfilterpopupitems-event-to-apply-custom-sort-order-to-filter-popup-items-e3247/VB/WindowsApplication1/Form1.vb#L59

Private Sub pivotGridControl1_CustomFieldSort(ByVal sender As Object, ByVal e As PivotGridCustomFieldSortEventArgs) Handles pivotGridControl1.CustomFieldSort
    If (Not rowField.Equals(e.Field)) Then

how-to-implement-sorting-for-a-custom-cell-value-e2149/VB/ImplementSortingforaCustomCellValue/Form1.vb#L61

Private Sub pivotGridControl1_CustomFieldSort(ByVal sender As Object, ByVal e As PivotGridCustomFieldSortEventArgs) Handles pivotGridControl1.CustomFieldSort
    If Me.pivotData Is Nothing OrElse sortInfo Is Nothing Then