A newer version of this page is available. Switch to the current version.

PivotGridControl.CustomFieldValueCells Event

Allows you to customize field value cells.

Namespace: DevExpress.XtraPivotGrid

Assembly: DevExpress.XtraPivotGrid.v19.1.dll


public event PivotCustomFieldValueCellsEventHandler CustomFieldValueCells
Public Event CustomFieldValueCells As PivotCustomFieldValueCellsEventHandler

Event Data

The CustomFieldValueCells event's data class is PivotCustomFieldValueCellsEventArgs. The following properties provide information specific to this event:

Property Description
ColumnCount Gets the number of columns in the pivot grid. Inherited from PivotCustomFieldValueCellsEventArgsBase.
IsUpdateRequired Gets whether the area where the field value cells reside needs to be redrawn after the event is handled. Inherited from PivotCustomFieldValueCellsEventArgsBase.
RowCount Gets the number of rows in the pivot grid. Inherited from PivotCustomFieldValueCellsEventArgsBase.

The event data class exposes the following methods:

Method Description
FindAllCells(Boolean, Predicate<Object[]>) Returns all cells whose values match the specified condition.
FindCell(Boolean, Predicate<Object[]>) Returns the header of the column/row whose summary values match the specified condition.
GetCell(Boolean, Int32) Returns the field value cell by its index.
GetCellCount(Boolean) Returns the number of field value cells in the specified area. Inherited from PivotCustomFieldValueCellsEventArgsBase.
GetCellValue(Int32, Int32) Gets the value of a data cell by its column and row indexes. Inherited from PivotCustomFieldValueCellsEventArgsBase.
GetGrandTotalLocation(Boolean) Returns the location of Grand Total columns or rows. Inherited from PivotCustomFieldValueCellsEventArgsBase.
GetLevelCount(Boolean) Returns the number of column or row levels. Inherited from PivotCustomFieldValueCellsEventArgsBase.
Remove(FieldValueCellBase) Removes the specified field value cell. Inherited from PivotCustomFieldValueCellsEventArgsBase.
SetGrandTotalLocation(Boolean, GrandTotalLocation) Sets the location of Grand Total columns or rows to the specified value. Inherited from PivotCustomFieldValueCellsEventArgsBase.
Split(Boolean, Predicate<T2>, FieldValueSplitData[]) Splits all field value cells that match the specified condition.
Split(Boolean, Predicate<T2>, Boolean, FieldValueSplitData[]) Splits all field value cells that match the specified condition, or only the first matching cell.
Split(Boolean, Predicate<T2>, Boolean, IList<FieldValueSplitData>) Splits all field value cells that match the specified condition, or only the first matching cell.
Split(Boolean, Predicate<T2>, IList<FieldValueSplitData>) Splits all field value cells that match the specified condition.


The CustomFieldValueCells event occurs when the layout of the Pivot Grid Control is changed, allowing you to customize column and row headers: field value cells, data field, total and grand total headers.


Use the event parameter's PivotCustomFieldValueCellsEventArgsBase<T1, T2>.GetCell method, to obtain data related to an individual cell, by its index. This method returns a FieldValueCell object, which provides the data. Use the PivotCustomFieldValueCellsEventArgsBase.GetCellCount method to obtain the total number of field value cells. Column/row headers can also be identified by their column/row. Use the PivotCustomFieldValueCellsEventArgsBase<T1, T2>.FindCell method to obtain the header whose column/row matches a specific condition.

The CustomFieldValueCells event allows you to specify the location of grand total headers using the PivotCustomFieldValueCellsEventArgsBase.SetGrandTotalLocation method. To obtain the current location of grand total headers, use the PivotCustomFieldValueCellsEventArgsBase.GetGrandTotalLocation method.

When handling the CustomFieldValueCells event, you can also remove individual cells with their nested columns and rows via the PivotCustomFieldValueCellsEventArgsBase.Remove method.

The PivotCustomFieldValueCellsEventArgsBase<T1, T2>.Split method allows you to split field value cells that have more than one nested cell. This method splits cells that match the specified condition (or, optionally, only the first matching cell) in a custom manner defined by the FieldValueSplitData objects.


Custom values provided via the PivotGridControl.CustomCellValue, PivotGridControl.CustomSummary and PivotGridControl.CustomCellDisplayText events are not available when handling the CustomFieldValueCells event, because it is raised prior to these events.


The following example demonstrates how to split field value cells.In this example, the Grand Total column header is split into two cells: Price and Count. To do this, the CustomFieldValueCells event is handled, and the event parameter's Split method is used. Cells that should be split are identified by a predicate that returns true for those cells. The quantity, size and captions of newly created cells are specified by an array of cell definitions (the FieldValueSplitData objects).

using System.Data;
using DevExpress.XtraPivotGrid;

namespace XtraPivotGrid_SplittingCells {
    public static class PivotHelper {
        public const string Employee = "Employee";
        public const string Widget = "Widget";
        public const string Month = "Month";
        public const string RetailPrice = "Retail Price";
        public const string WholesalePrice = "Wholesale Price";
        public const string Quantity = "Quantity";
        public const string Remains = "Remains";

        public const string EmployeeA = "Employee A";
        public const string EmployeeB = "Employee B";
        public const string WidgetA = "Widget A";
        public const string WidgetB = "Widget B";
        public const string WidgetC = "Widget C";

        public static void FillPivot(PivotGridControl pivot) {
            pivot.Fields.Add(Employee, PivotArea.RowArea);
            pivot.Fields.Add(Widget, PivotArea.RowArea);
            pivot.Fields.Add(Month, PivotArea.ColumnArea).AreaIndex = 0;
            pivot.Fields.Add(RetailPrice, PivotArea.DataArea);
            pivot.Fields.Add(WholesalePrice, PivotArea.DataArea);
            pivot.Fields.Add(Quantity, PivotArea.DataArea);
            foreach (PivotGridField field in pivot.Fields) {
                field.AllowedAreas = GetAllowedArea(field.Area);
            pivot.OptionsView.RowTotalsLocation = PivotRowTotalsLocation.Far;
            pivot.OptionsView.ColumnTotalsLocation = PivotTotalsLocation.Far;
            pivot.OptionsDataField.Area = PivotDataArea.ColumnArea;
            pivot.OptionsDataField.AreaIndex = 1;
        static PivotGridAllowedAreas GetAllowedArea(PivotArea area) {
            switch (area) {
                case PivotArea.ColumnArea:
                    return PivotGridAllowedAreas.ColumnArea;
                case PivotArea.RowArea:
                    return PivotGridAllowedAreas.RowArea;
                case PivotArea.DataArea:
                    return PivotGridAllowedAreas.DataArea;
                case PivotArea.FilterArea:
                    return PivotGridAllowedAreas.FilterArea;
                    return PivotGridAllowedAreas.All;
        public static DataTable GetDataTable() {
            DataTable table = new DataTable();
            table.Columns.Add(Employee, typeof(string));
            table.Columns.Add(Widget, typeof(string));
            table.Columns.Add(Month, typeof(int));
            table.Columns.Add(RetailPrice, typeof(double));
            table.Columns.Add(WholesalePrice, typeof(double));
            table.Columns.Add(Quantity, typeof(int));
            table.Columns.Add(Remains, typeof(int));
            table.Rows.Add(EmployeeA, WidgetA, 6, 45.6, 40, 3);
            table.Rows.Add(EmployeeA, WidgetA, 7, 38.9, 30, 6);
            table.Rows.Add(EmployeeA, WidgetB, 6, 24.7, 20, 7);
            table.Rows.Add(EmployeeA, WidgetB, 7, 8.3, 7.5, 5);
            table.Rows.Add(EmployeeA, WidgetC, 6, 10.0, 9, 4);
            table.Rows.Add(EmployeeA, WidgetC, 7, 20.0, 18.5, 5);
            table.Rows.Add(EmployeeB, WidgetA, 6, 77.8, 70, 2);
            table.Rows.Add(EmployeeB, WidgetA, 7, 32.5, 30, 1);
            table.Rows.Add(EmployeeB, WidgetB, 6, 12, 11, 10);
            table.Rows.Add(EmployeeB, WidgetB, 7, 6.7, 5.5, 4);
            table.Rows.Add(EmployeeB, WidgetC, 6, 30.0, 28.7, 6);
            table.Rows.Add(EmployeeB, WidgetC, 7, 40.0, 38.3, 7);
            return table;

See Also