PivotGridControl.CustomCellDisplayText Event

Enables custom display text to be provided for the cells displayed within the Data Area.

Namespace: DevExpress.XtraPivotGrid

Assembly: DevExpress.XtraPivotGrid.v20.1.dll

Declaration

public event PivotCellDisplayTextEventHandler CustomCellDisplayText
Public Event CustomCellDisplayText As PivotCellDisplayTextEventHandler

Event Data

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

Property Description
ColumnCustomTotal Gets the column custom total which displays the current cell. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
ColumnField Gets the innermost column field which corresponds to the processed cell. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
ColumnFieldIndex For internal use. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
ColumnIndex Gets the visual index of the column that contains the processed cell. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
ColumnValueType Gets the type of column which contains the processed cell. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
Data For internal use. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
DataField Gets the data field which identifies the column where the processed cell resides. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
DisplayText Gets or sets the display text for the cell currently being processed.
Item For internal use. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
RowCustomTotal Gets the row custom total which contains the current cell. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
RowField Gets the innermost row field which corresponds to the processed cell. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
RowFieldIndex For internal use. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
RowIndex Gets the index of the row that contains the processed cell. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
RowValueType Gets the type of row which contains the processed cell. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
SummaryType Gets the summary type of the currently processed value. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
SummaryValue Gets the summary value currently being processed. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
Value Gets the processed cell's value. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.

Remarks

The CustomCellDisplayText event provides the ability to customize the display text within data cells (the cells which are displayed within the Data Area). A data cell displays a summary value which is calculated against a specific Data Field. This field is identified by the event's DataField parameter. The current value and its formatted text representation is specified by the event's Value and DisplayText parameters.

It's possible to specify the settings used to format data cells via the PivotGridFieldBase.CellFormat, PivotGridFieldBase.TotalCellFormat and PivotGridFieldBase.GrandTotalCellFormat properties of data fields. So handle the CustomCellDisplayText event if these format properties do not suit your needs.

Use the PivotGridControl.FieldValueDisplayText event or PivotGridFieldBase.ValueFormat property to customize display text used to represent field values.

Cell values can also be replaced with custom ones by handling the PivotGridControl.CustomCellValue event which is raised before the CustomCellDisplayText event.

IMPORTANT

Do not change cell values, modify the control's layout, or change the control's object model in the events used for custom control painting. Actions that update the layout can cause the control to malfunction.

Examples

The following example shows how to provide custom text for the PivotGridControl's cells by handling the PivotGridControl.CustomCellDisplayText event.

In this example, if a row total value is less than 2000, PivotGridControl displays the 'Low' value instead. If the value exceeds 6000, 'High' is displayed; otherwise, 'Middle'.

win-pivot-customcelldisplaytext-event

using System;
using System.Windows.Forms;
using DevExpress.XtraPivotGrid;

namespace WinFormsPivotCustomCellDisplayText
{
    public partial class Form1 : Form
    {
        public Form1()
        {
            InitializeComponent();
            salesPersonTableAdapter1.Fill(nwindDataSet1.SalesPerson);
            fieldCountry1.FilterValues.FilterType = PivotFilterType.Included;
            fieldCountry1.FilterValues.Add("UK");
        }

        private void pivotGridControl1_CustomCellDisplayText(object sender, 
                     DevExpress.XtraPivotGrid.PivotCellDisplayTextEventArgs e)
        {
            // In this example, if a row total value is less than 2000, 'Low' is displayed instead. 
            // If the value exceeds 6000, 'High' is displayed; otherwise, 'Middle'.
            if (e.RowValueType == PivotGridValueType.Total ||
                e.ColumnValueType != PivotGridValueType.Total) return;
            if (Convert.ToSingle(e.Value) < 2000)
                e.DisplayText = "Low";
            else if (Convert.ToSingle(e.Value) > 6000)
                e.DisplayText = "High";
            else
                e.DisplayText = "Middle";
        }
    }
}
See Also