PivotGridControl.CustomAppearance Event

Allows the appearances of cells to be dynamically customized when the control is displayed on screen and in the print output.

Namespace: DevExpress.XtraPivotGrid

Assembly: DevExpress.XtraPivotGrid.v20.2.dll

NuGet Package: DevExpress.Win.PivotGrid

Declaration

C#

public event PivotCustomAppearanceEventHandler CustomAppearance

VB.NET

Public Event CustomAppearance As PivotCustomAppearanceEventHandler

Event Data

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

Property	Description
Appearance	Gets or sets the appearance settings of the currently processed cell.
Bounds	Gets the cell’s bounds. Inherited from PivotCellEventArgs.
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>.
DataField	Gets the data field which identifies the column where the processed cell resides. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
DisplayText	Gets the display text of the cell currently being processed. Inherited from PivotCellEventArgs.
Focused	Gets whether the processed cell is the focused cell. Inherited from PivotCellEventArgs.
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>.
Selected	Gets whether the processed cell is selected. Inherited from PivotCellEventArgs.
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>.
ThreadSafeArgs	Gets an event parameter that provides thread-safe access to event data.
Value	Gets the processed cell’s value. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.

The event data class exposes the following methods:

Method	Description
CreateDrillDownDataSource()	Returns data records used to calculate a summary value for the cell. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
CreateDrillDownDataSource(List<String>)	Returns data records used to calculate a summary value for the current cell. Allows you to specify the columns to return. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
CreateDrillDownDataSource(Int32, List<String>)	Returns data records used to calculate a summary value for the current cell. Allows you to specify the columns and limit the number of records to return. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
CreateDrillDownDataSource(Int32)	Returns data records used to calculate a summary value for the current cell. Allows you to specify the columns and limit the number of records to return. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
CreateOLAPDrillDownDataSource(List<String>)	Obsolete. In OLAP mode, returns a list of records used to calculate a summary value for the current cell. Allows you to specify the columns to be returned. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
CreateOLAPDrillDownDataSource(Int32, List<String>)	Obsolete. In OLAP mode, returns a list of records used to calculate a summary value for the current cell. Allows you to specify the columns and limit the number of records to be returned. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
CreateServerModeDrillDownDataSource(List<String>)	Obsolete. In server mode, returns a list of records used to calculate a summary value for the current cell. Allows you to specify the columns to be returned. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
CreateServerModeDrillDownDataSource(Int32, List<String>)	Obsolete. In server mode, returns a list of records used to calculate a summary value for the current cell. Allows you to specify the columns and limit the number of records to be returned. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
CreateSummaryDataSource()	Returns a summary data source. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
GetCellValue(TField)	Returns a cell value calculated against the specified data field. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
GetCellValue(PivotGridField)	Returns a cell value calculated for the current column and row field values, against the specified data field. Inherited from PivotCustomDrawCellBaseEventArgs.
GetCellValue(Int32, Int32)	Returns a cell value by the column and row indexes. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
GetCellValue(Object[], Object[], TField)	Returns a cell value calculated for the specified column and row field values, against the specified data field. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
GetCellValue(Object[], Object[], PivotGridField)	Returns a cell value calculated for the specified column and row field values, against the specified data field. Inherited from PivotCustomDrawCellBaseEventArgs.
GetColumnFields()	Returns an array of column fields which correspond to the current cell. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
GetColumnGrandTotal(TField)	Returns a Column Grand Total value calculated for the current row field values, against the specified data field. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
GetColumnGrandTotal(PivotGridField)	Returns a Column Grand Total value calculated for the current row field values, against the specified data field. Inherited from PivotCustomDrawCellBaseEventArgs.
GetColumnGrandTotal(Object[], TField)	Returns a Column Grand Total value calculated for the specified row field values, against the specified data field. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
GetColumnGrandTotal(Object[], PivotGridField)	Returns a Column Grand Total value calculated for the specified row field values, against the specified data field. Inherited from PivotCustomDrawCellBaseEventArgs.
GetFieldValue(TField, Int32)	Returns the specified column or row field’s value for the cell, addressed by its zero-based index in the data area. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
GetFieldValue(TField)	Returns the value of the specified column or row field which identifies the column/row in which the processed cell resides. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
GetFieldValue(PivotGridField, Int32)	Returns a field value that belongs to the specified field and corresponds to a data cell with the specified column or row index. Inherited from PivotCustomDrawCellBaseEventArgs.
GetFieldValue(PivotGridField)	Returns a field value that belongs to the specified field and corresponds to the current data cell. Inherited from PivotCustomDrawCellBaseEventArgs.
GetGrandTotal(TField)	Gets the Grand Total value for the specified field. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
GetGrandTotal(PivotGridField)	Returns the Grand Total value calculated against the specified data field. Inherited from PivotCustomDrawCellBaseEventArgs.
GetNextColumnCellValue(TField)	Returns the value of the cell in the same row but in the next column. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
GetNextColumnCellValue(PivotGridField)	Returns the value of the cell located in the next column of the current row. Inherited from PivotCustomDrawCellBaseEventArgs.
GetNextRowCellValue(TField)	Returns the value of the cell in the next row. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
GetNextRowCellValue(PivotGridField)	Returns the value of the cell located in the next row of the current column. Inherited from PivotCustomDrawCellBaseEventArgs.
GetPrevColumnCellValue(TField)	Returns the value of the cell in the same row but in the previous column. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
GetPrevColumnCellValue(PivotGridField)	Returns the value of the cell located in the previous column of the current row. Inherited from PivotCustomDrawCellBaseEventArgs.
GetPrevRowCellValue(TField)	Returns the value of the cell in the previous row. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
GetPrevRowCellValue(PivotGridField)	Returns the value of the cell located in the previous row of the current column. Inherited from PivotCustomDrawCellBaseEventArgs.
GetRowFields()	Returns an array of the row fields which correspond to the current cell. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
GetRowGrandTotal(TField)	Returns a Row Grand Total value calculated for the current column field values, against the specified data field. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
GetRowGrandTotal(PivotGridField)	Returns a Row Grand Total value calculated for the current column field values, against the specified data field. Inherited from PivotCustomDrawCellBaseEventArgs.
GetRowGrandTotal(Object[], TField)	Returns a Row Grand Total value calculated for the specified column field values, against the specified data field. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
GetRowGrandTotal(Object[], PivotGridField)	Returns a Row Grand Total value calculated for the specified column field values, against the specified data field. Inherited from PivotCustomDrawCellBaseEventArgs.
IsFieldValueExpanded(TField)	Indicates whether the specified field’s value that represents the row or column header of the processed cell is expanded. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
IsFieldValueExpanded(PivotGridField)	Indicates whether a field value that belongs to the specified field and corresponds to the current cell is expanded. Inherited from PivotCustomDrawCellBaseEventArgs.
IsFieldValueRetrievable(TField)	Gets whether the value of the specified column or row field can be retrieved for the current cell by the PivotCellEventArgsBase<TField, TData, TCustomTotal>.GetFieldValue method. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
IsFieldValueRetrievable(PivotGridField)	Gets whether the value of the specified column or row field can be retrieved for the current cell by the PivotCustomDrawCellBaseEventArgs.GetFieldValue method. Inherited from PivotCustomDrawCellBaseEventArgs.
IsOthersFieldValue(TField)	Indicates whether the processed data cell resides within the “Others” row/column when the Top X Value feature is enabled. Inherited from PivotCellEventArgsBase<TField, TData, TCustomTotal>.
IsOthersFieldValue(PivotGridField)	Indicates whether the current data cell resides within the “Others” row/column when the Top X Value feature is enabled. Inherited from PivotCustomDrawCellBaseEventArgs.

Remarks

Unlike custom painting applied by handling the PivotGridControl.CustomDrawCell event, appearances customized via the CustomAppearance event are used when the pivot grid is printed.

The CustomAppearance event fires for each pivot grid cell and allows you to customize the appearance of cells dynamically (depending on their contents, position, values of other cells, etc). Use the event parameter to identify the processed cell.

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.

To customize the appearance settings, use the event parameter’s PivotCustomAppearanceEventArgs.Appearance property.

To access event data while an asynchronous operation is being performed, use a thread-safe event parameter returned by the PivotCustomAppearanceEventArgs.ThreadSafeArgs property. To learn more, see Asynchronous Mode.

Example

The following example shows how to customize the appearance of specific cells via the PivotGridControl.CustomAppearance event.

In this example, custom appearance settings (the yellow background and bold font) are applied to a cell if it meets the following conditions:

• It belongs to an “ExtendedPrice” data field.
• It’s not displayed within total rows or columns.
• It’s value is larger than 1000.

The following image demonstrates code execution:

C#

using DevExpress.XtraPivotGrid;

private void pivotGridControl1_CustomAppearance(object sender, PivotCustomAppearanceEventArgs e) {
    if (e.DataField == fieldExtendedPrice && e.ColumnValueType == PivotGridValueType.Value 
        && e.RowValueType == PivotGridValueType.Value) {
        if (e.Value != null && (decimal)e.Value > 1000) {
            e.Appearance.BackColor = Color.Yellow;
            e.Appearance.FontStyleDelta = FontStyle.Bold;
        }
    }
}

VB.NET

Imports DevExpress.XtraPivotGrid

Private Sub pivotGridControl1_CustomAppearance(ByVal sender As System.Object, _
ByVal e As PivotCustomAppearanceEventArgs) _
Handles pivotGridControl1.CustomAppearance
    If e.DataField Is fieldExtendedPrice And e.ColumnValueType = PivotGridValueType.Value _
        And e.RowValueType = PivotGridValueType.Value Then
        If Not e.Value Is Nothing And Convert.ToDecimal(e.Value) > 1000 Then
            e.Appearance.BackColor = Color.Yellow
            e.Appearance.FontStyleDelta = FontStyle.Bold
        End If
    End If
End Sub