PivotGridControl.FieldValueImageIndex Event

Enables images to be shown within column and row headers.

Namespace: DevExpress.XtraPivotGrid

Assembly: DevExpress.XtraPivotGrid.v24.1.dll

NuGet Package: DevExpress.Win.PivotGrid

Declaration

C#

public event PivotFieldImageIndexEventHandler FieldValueImageIndex

VB.NET

Public Event FieldValueImageIndex As PivotFieldImageIndexEventHandler

Event Data

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

Property	Description
CustomTotal	Gets the custom total that corresponds to the currently processed column/row header.
Data	This member supports the .NET Framework infrastructure and is not intended to be used directly from your code. Inherited from PivotFieldValueEventArgs.
DataField	Gets the data field that identifies the processed value.
Field	Gets the field being processed.
FieldIndex	Gets the field position among the visible fields within the header area.
ImageIndex	Gets or sets the index of the image to display within the currently processed column/row header.
IsCollapsed	Gets whether the processed field value is collapsed.
IsColumn	Gets whether the field is displayed within the Column Header Area.
IsOthersValue	Gets whether the current header corresponds to the “Others” row/column.
Item	For internal use. Inherited from PivotFieldValueEventArgsBase<T>.
MaxIndex	Gets the maximum row index (for row fields) or column index (for column fields) that corresponds to the field value currently being processed.
MinIndex	Gets the minimum row index (for row fields) or column index (for column fields) that corresponds to the field value currently being processed.
ThreadSafeArgs	Gets an event parameter that provides thread-safe access to event data.
Value	Gets the column field or row field value that corresponds to the currently processed column/row header.
ValueType	Gets the type of the currently processed column/row header.

The event data class exposes the following methods:

Method	Description
ChangeExpandedState()	Changes the expanded state of the current field value.
CreateDrillDownDataSource()	Returns data records associated with the processed field value.
CreateDrillDownDataSource(List<String>)	Returns data records used to calculate a summary value for the current cell. Allows you to specify the columns to return.
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.
CreateDrillDownDataSource(Int32)	Returns data records used to calculate a summary value for the current cell. Allows you to limit the number of records to return.
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.
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.
GetCellValue(Int32, Int32)	Returns a value displayed in a cell with the specified column and row indexes.
GetFieldValue(T, Int32)	Returns the specified column or row field value for the cell, addressed by its zero-based index in the Data Area. Inherited from PivotFieldValueEventArgsBase<T>.
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.
GetHigherLevelFields()	Returns the parent field(s) for the field value being currently processed.
GetHigherLevelFieldValue(T)	Returns the value of a specific parent field corresponding to the field value currently being processed. Inherited from PivotFieldValueEventArgsBase<T>.
GetHigherLevelFieldValue(PivotGridField)	Returns the value of a specific parent field corresponding to the field value currently being processed.

Remarks

The FieldValueImageIndex event lets you assign images for individual field values, total headers and grand total headers. An image can be assigned to a header via the PivotFieldImageIndexEventArgs.ImageIndex parameter which represents the index of the image in the PivotGridControl.ValueImages list.

The type of the currently processed header is determined by the ValueType parameter. If the FieldValueImageIndex event is raised for a field value or total header the Field parameter identifies the corresponding column field or row field. If the FieldValueImageIndex event is raised for a grand total header the Field property will return null.

Note

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

Example

The following sample code handles the PivotGridControl.FieldValueImageIndex event to display images within the “Category Name” field values.

The image below shows the result.

C#

using DevExpress.XtraPivotGrid;

static string[] CategoryNames = new string[] {"Beverages", "Condiments", "Confections", 
  "Dairy Products", "Grains/Cereals", "Meat/Poultry", "Produce", "Seafood"};
public static int GetCategoryIndexByName(object name) {
    if(name != null)
        for(int i = 0; i < CategoryNames.Length; i++)
            if(CategoryNames[i] == name.ToString()) return i;
        return -1;
}

// ...
private void pivotGridControl1_FieldValueImageIndex(object sender, 
  PivotFieldImageIndexEventArgs e) {
    if(e.Field == fieldCategoryName && e.ValueType == PivotGridValueType.Value) 
        e.ImageIndex = GetCategoryIndexByName(e.Value);
    if (e.ValueType == PivotGridValueType.GrandTotal && e.IsColumn == false)
        e.ImageIndex = 8;
}

VB.NET

Imports DevExpress.XtraPivotGrid

Private Shared CategoryNames As String() = New String() {"Beverages", "Condiments", _
  "Confections", "Dairy Products", "Grains/Cereals", "Meat/Poultry", "Produce", "Seafood"}
Public Shared Function GetCategoryIndexByName(ByVal name As Object) As Integer
   If Not name Is Nothing Then
         Dim i As Integer = 0
         While i < CategoryNames.Length
            If CategoryNames(i) = name.ToString() Then
               Return i
            End If
            i += 1
         End While
   End If
   Return -1
End Function
' ...
Private Sub pivotGridControl1_FieldValueImageIndex(ByVal sender As Object, ByVal e As PivotFieldImageIndexEventArgs)
    If e.Field = fieldCategoryName1 AndAlso e.ValueType = PivotGridValueType.Value Then
        e.ImageIndex = GetCategoryIndexByName(e.Value)
    End If
    If e.ValueType = PivotGridValueType.GrandTotal AndAlso e.IsColumn = False Then
        e.ImageIndex = 8
    End If
End Sub