Class RadPivotGrid

RadPivotGrid is a control which provides functionality similar to the functionality of PivotTables in MS Excel. It aggregates large chunks of data and displays them in a human readable way.

Inheritance
System.Object
RadControl
RadPivotGrid
Inherited Members
Namespace: Telerik.WinControls.UI
Assembly: Telerik.WinControls.PivotGrid.dll

Syntax

[TelerikToolboxCategory("Data Controls")]
public class RadPivotGrid : RadControl, INotifyPropertyChanged, ISupportInitializeNotification, ISupportInitialize, IComponentTreeHandler, ILayoutHandler, IPCHost, IAnalyticsProvider, IPrintable, IChartDataProvider

Constructors

RadPivotGrid()

Initializes a new instance of the RadPivotGrid class with default settings. Creates an empty pivot grid control that can be configured to display aggregated data from various data sources.

Declaration
public RadPivotGrid()

Properties

AggregateDescriptions

A collection of PropertyAggregateDescription which describes how the values in the cells are calculated (aggregated).

Declaration
public AggregateDescriptionsCollection AggregateDescriptions { get; }
Property Value
AggregateDescriptionsCollection

AggregatesLevel

Gets or sets the depth of the Aggregates groups among the other groups when more than one aggregate is used.

Declaration
public int AggregatesLevel { get; set; }
Property Value
System.Int32

AggregatesPosition

Gets or sets the axis of the Aggregates groups when more than one aggregate is used.

Declaration
public PivotAxis AggregatesPosition { get; set; }
Property Value
PivotAxis

AllowContextMenu

Gets or sets a value indicating whether the built-in context menu is enabled.

Declaration
public bool AllowContextMenu { get; set; }
Property Value
System.Boolean

AllowDefaultScreenTips

Gets or sets a value indicating whether the built-in screen tips are enabled.

Declaration
public bool AllowDefaultScreenTips { get; set; }
Property Value
System.Boolean

AllowFieldsDragDrop

Gets or sets a value indicating whether fields can be dragged and dropped between different areas of the pivot grid. When enabled, users can reorganize the pivot layout by moving fields between row, column, value and filter areas.

Declaration
public bool AllowFieldsDragDrop { get; set; }
Property Value
System.Boolean

AllowGroupFiltering

Gets or sets a value indicating whether Group Filtering is enabled.

Declaration
public bool AllowGroupFiltering { get; set; }
Property Value
System.Boolean

AllowHorizontalResize

Gets or sets a value indicating whether the user is able to resize columns.

Declaration
public bool AllowHorizontalResize { get; set; }
Property Value
System.Boolean

AllowSelection

Gets or sets a value indicating whether the user is able to select cells.

Declaration
public bool AllowSelection { get; set; }
Property Value
System.Boolean

AllowSorting

Gets or sets a value indicating whether the user is able to sort the group labels.

Declaration
public bool AllowSorting { get; set; }
Property Value
System.Boolean

AllowVerticalResize

Gets or sets a value indicating whether the user is able to resize rows.

Declaration
public bool AllowVerticalResize { get; set; }
Property Value
System.Boolean

AutoExpandColumnHeaders

Gets or sets a value indicating whether the created column groups should be initially expanded.

Declaration
public bool AutoExpandColumnHeaders { get; set; }
Property Value
System.Boolean

AutoExpandRowHeaders

Gets or sets a value indicating whether the newly created row groups should be initially expanded.

Declaration
public bool AutoExpandRowHeaders { get; set; }
Property Value
System.Boolean

AutoSize

Gets or sets whether the edit control is auto-sized

Declaration
public override bool AutoSize { get; set; }
Property Value
System.Boolean

Overrides

BackColor

RadPivotGrid consists of multiple visual elements and separate settings are provided to customize their appearance. Current BackColor property might be ignored.

Declaration
public override Color BackColor { get; set; }
Property Value
System.Drawing.Color

Overrides

ChartDataProvider

Gets or sets the chart data provider.

Declaration
public PivotGridChartDataProvider ChartDataProvider { get; set; }
Property Value
PivotGridChartDataProvider

The chart data provider.

ColumnGrandTotalsPosition

Gets or sets the position of the GrandTotal column in the Columns axis.

Declaration
public TotalsPos ColumnGrandTotalsPosition { get; set; }
Property Value
TotalsPos

ColumnGroupDescriptions

A collection of PropertyGroupDescriptionBase which is used for generating column groups.

Declaration
public ColumnGroupDescriptionCollection ColumnGroupDescriptions { get; }
Property Value
ColumnGroupDescriptionCollection

ColumnGroupsExpandBehavior

Gets or sets the behavior that will set the expand or collapse state for column IGroups.

Declaration
public IItemExpandBehavior<ExpandBehaviorParameters> ColumnGroupsExpandBehavior { get; set; }
Property Value
IItemExpandBehavior<ExpandBehaviorParameters>

ColumnHeaderHeight

Gets or sets the height of the column headers area.

Declaration
public int ColumnHeaderHeight { get; set; }
Property Value
System.Int32

ColumnHeadersLayout

Gets or sets the layout type of the column headers.

Declaration
public PivotLayout ColumnHeadersLayout { get; set; }
Property Value
PivotLayout

ColumnsSubTotalsPosition

Gets or sets the position of the SubTotal columns in the Columns axis.

Declaration
public TotalsPos ColumnsSubTotalsPosition { get; set; }
Property Value
TotalsPos

ColumnWidth

Gets or sets the default column width for all columns.

Declaration
public int ColumnWidth { get; set; }
Property Value
System.Int32

DataMember

Gets or sets the name of the list or table in the data source for which RadPivotGrid is displaying aggregated data.

Declaration
public string DataMember { get; set; }
Property Value
System.String

DataProvider

Gets or sets the IDataProvider that populates the pivot grid with data.

Declaration
public IDataProvider DataProvider { get; set; }
Property Value
IDataProvider

DataSource

Gets or sets the data source for which RadPivotGrid is displaying aggregated data.

Declaration
public object DataSource { get; set; }
Property Value
System.Object

DefaultSize

Gets the default size of the control.

Declaration
protected override Size DefaultSize { get; }
Property Value
System.Drawing.Size

The default System.Drawing.Size of the control.

DialogsFactory

Gets or sets the dialogs factory.

Declaration
public PivotGridDialogsFactory DialogsFactory { get; set; }
Property Value
PivotGridDialogsFactory

The dialogs factory.

EmptyValueString

Gets or sets the string that will appears on cells that do not have a value.

Declaration
public string EmptyValueString { get; set; }
Property Value
System.String

ErrorString

Gets or sets the string that will appears on cells for which an error has occured during calculation.

Declaration
public string ErrorString { get; set; }
Property Value
System.String

FilterAreaHeight

Gets or sets the height of the report filters area.

Declaration
public int FilterAreaHeight { get; set; }
Property Value
System.Int32

FilterDescriptions

A collection of PropertyFilterDescription which defines the fields that are available in the Report Filters area.

Declaration
public FilterDescriptionsCollection FilterDescriptions { get; }
Property Value
FilterDescriptionsCollection

ForeColor

RadPivotGrid consists of multiple visual elements and separate settings are provided to customize their appearance. Current ForeColor property might be ignored.

Declaration
public override Color ForeColor { get; set; }
Property Value
System.Drawing.Color

Overrides

LayoutState

Gets or sets an object which holds the state of the resized and the collapsed rows and columns. Setting the object will apply the state and will update the layout.

Declaration
public PivotLayoutState LayoutState { get; set; }
Property Value
PivotLayoutState

PivotGridElement

Gets the pivot grid element.

Declaration
public RadPivotGridElement PivotGridElement { get; }
Property Value
RadPivotGridElement

The pivot grid element.

PrintStyle

Gets or sets the PivotGridPrintStyle that is responsible for printing the pivot grid.

Declaration
public PivotGridPrintStyle PrintStyle { get; set; }
Property Value
PivotGridPrintStyle

RowGrandTotalsPosition

Gets or sets the position of the GrandTotal row in the Rows axis.

Declaration
public TotalsPos RowGrandTotalsPosition { get; set; }
Property Value
TotalsPos

RowGroupDescriptions

A collection of PropertyGroupDescriptionBase which is used for generating row groups.

Declaration
public RowGroupDescriptionCollection RowGroupDescriptions { get; }
Property Value
RowGroupDescriptionCollection

RowGroupsExpandBehavior

Gets or sets the behavior that will set the expand or collapse state for row IGroups.

Declaration
public IItemExpandBehavior<ExpandBehaviorParameters> RowGroupsExpandBehavior { get; set; }
Property Value
IItemExpandBehavior<ExpandBehaviorParameters>

RowHeadersLayout

Gets or sets the layout type of the row headers.

Declaration
public PivotLayout RowHeadersLayout { get; set; }
Property Value
PivotLayout

RowHeight

Gets or sets the default row height for all rows.

Declaration
public int RowHeight { get; set; }
Property Value
System.Int32

RowsSubTotalsPosition

Gets or sets the position of the SubTotal rows in the Rows axis.

Declaration
public TotalsPos RowsSubTotalsPosition { get; set; }
Property Value
TotalsPos

ShowFilterArea

Gets or sets a value indicating whether the Report Filters area should be displayed.

Declaration
public bool ShowFilterArea { get; set; }
Property Value
System.Boolean

Text

This property is not relevant for this class.

Declaration
public override string Text { get; set; }
Property Value
System.String

Overrides

XmlSerializationInfo

Gets or sets the serialization information for RadPivotGrid used by SaveLayout and LoadLayout methods to persist and restore grid settings. By default or when set to null, the ComponentXmlSerializationInfo provided by GetDefaultXmlSerializationInfo() will be used.

Declaration
public ComponentXmlSerializationInfo XmlSerializationInfo { get; set; }
Property Value
ComponentXmlSerializationInfo

Methods

BeginInit()

Signals the start of the control's initialization and suspends layout and data updates. Used during control creation and when loading the control state from a serialized form.

Declaration
public override void BeginInit()
Overrides

BeginUpdate()

Puts RadPivotGrid in update mode and suspends visual refreshing. Use this method before making multiple property changes to improve performance by preventing multiple layout updates. Must be paired with a subsequent call to EndUpdate() when finished making changes.

Declaration
public void BeginUpdate()

CreateChildItems(RadElement)

Creates the child elements for the RadPivotGrid control. Initializes the pivotGridElement and adds it to the parent's collection.

Declaration
protected override void CreateChildItems(RadElement parent)
Parameters
RadElement parent

The parent element that will contain the created child elements.
Overrides

CreatePivotGridElement()

Creates the RadPivotGridElement which is the main visual element of the pivot grid control. Override this method to create a custom pivot grid element when inheriting from RadPivotGrid.

Declaration
protected virtual RadPivotGridElement CreatePivotGridElement()
Returns
RadPivotGridElement

A new instance of RadPivotGridElement that will be used to render the pivot grid.

CreateXmlSerializer(ComponentXmlSerializationInfo)

Creates the XML serializer used for saving and loading the pivot grid's layout. Override this method to provide custom serialization behavior when extending this control.

Declaration
protected virtual ComponentXmlSerializer CreateXmlSerializer(ComponentXmlSerializationInfo info)
Parameters
ComponentXmlSerializationInfo info

The serialization information that defines which properties to serialize.
Returns
ComponentXmlSerializer

A ComponentXmlSerializer instance that will handle the actual serialization.

EndInit()

Signals the end of the control's initialization and resumes layout and data updates. The control will be refreshed to reflect all changes made during initialization.

Declaration
public override void EndInit()
Overrides

EndUpdate()

Ends the update mode and refreshes the pivot grid's visual representation. Call this method after BeginUpdate() once you've finished making property changes to apply all pending updates at once.

Declaration
public void EndUpdate()

GetDefaultXmlSerializationInfo()

Gets the default serialization information for RadPivotGrid used by SaveLayout and LoadLayout methods to persist and restore grid settings to/from XML. This includes configuration of rows, columns, aggregates, filters, and appearance settings.

Declaration
protected virtual ComponentXmlSerializationInfo GetDefaultXmlSerializationInfo()
Returns
ComponentXmlSerializationInfo

A ComponentXmlSerializationInfo instance configured with the default settings for RadPivotGrid serialization.

IsInputKey(Keys)

Determines whether the specified key is a regular input key or a special key that requires preprocessing.

Declaration
protected override bool IsInputKey(Keys keyData)
Parameters
System.Windows.Forms.Keys keyData

One of the System.Windows.Forms.Keys values.
Returns
System.Boolean

true if the specified key is a regular input key; otherwise, false.
Overrides

LoadLayout(Stream)

Loads the RadPivotGrid's layout configuration from an XML stream. Restores group configurations, column widths, row heights, and other display settings from the provided stream.

Declaration
public virtual void LoadLayout(Stream stream)
Parameters
System.IO.Stream stream

The stream containing the saved layout information.

LoadLayout(String)

Loads the RadPivotGrid's layout configuration from an XML file. Restores group configurations, column widths, row heights, and other display settings from the specified file.

Declaration
public virtual void LoadLayout(string fileName)
Parameters
System.String fileName

The path to the file containing the saved layout information.

LoadLayout(XmlReader)

Loads the RadPivotGrid's layout configuration from an XML reader. Restores group configurations, column widths, row heights, and other display settings from the provided XML reader.

Declaration
public virtual void LoadLayout(XmlReader xmlReader)
Parameters
System.Xml.XmlReader xmlReader

The XmlReader containing the saved layout information.

OnKeyDown(KeyEventArgs)

Raises the System.Windows.Forms.Control.KeyDown event.

Declaration
protected override void OnKeyDown(KeyEventArgs e)
Parameters
System.Windows.Forms.KeyEventArgs e

A System.Windows.Forms.KeyEventArgs that contains the event data.
Overrides

OnLostFocus(EventArgs)

Raises the System.Windows.Forms.Control.LostFocus event.

Declaration
protected override void OnLostFocus(EventArgs e)
Parameters
System.EventArgs e

An System.EventArgs that contains the event data.
Overrides

OnMouseDown(MouseEventArgs)

Raises the System.Windows.Forms.Control.MouseDown event.

Declaration
protected override void OnMouseDown(MouseEventArgs e)
Parameters
System.Windows.Forms.MouseEventArgs e

A System.Windows.Forms.MouseEventArgs that contains the event data.
Overrides

OnMouseMove(MouseEventArgs)

Raises the System.Windows.Forms.Control.MouseMove event.

Declaration
protected override void OnMouseMove(MouseEventArgs e)
Parameters
System.Windows.Forms.MouseEventArgs e

A System.Windows.Forms.MouseEventArgs that contains the event data.
Overrides

OnMouseUp(MouseEventArgs)

Raises the MouseUp event.

Declaration
protected override void OnMouseUp(MouseEventArgs e)
Parameters
System.Windows.Forms.MouseEventArgs e

The System.Windows.Forms.MouseEventArgs instance containing the event data.
Overrides

OnMouseWheel(MouseEventArgs)

Raises the System.Windows.Forms.Control.MouseWheel event.

Declaration
protected override void OnMouseWheel(MouseEventArgs e)
Parameters
System.Windows.Forms.MouseEventArgs e

A System.Windows.Forms.MouseEventArgs that contains the event data.
Overrides

OnScreenTipNeeded(Object, ScreenTipNeededEventArgs)

Called when the screen tip is needed.

Declaration
protected override void OnScreenTipNeeded(object sender, ScreenTipNeededEventArgs e)
Parameters
System.Object sender

The sender.
ScreenTipNeededEventArgs e

The ScreenTipNeededEventArgs instance containing the event data.
Overrides

Print()

Directly prints the RadPivotGrid to the default printer without showing any printer settings dialog. This is a convenience method that uses the current default printer with default settings.

Declaration
public virtual void Print()

Print(Boolean)

Prints the RadPivotGrid with an option to display the printer settings dialog first.

Declaration
public virtual void Print(bool showPrinterSettings)
Parameters
System.Boolean showPrinterSettings

When true, displays the printer settings dialog before printing; when false, prints directly using default settings.

Print(Boolean, RadPrintDocument)

Prints the RadPivotGrid using a specified print document and with an option to display the printer settings dialog.

Declaration
public virtual void Print(bool showPrinterSettings, RadPrintDocument document)
Parameters
System.Boolean showPrinterSettings

When true, displays the printer settings dialog before printing; when false, prints directly using default settings.
RadPrintDocument document

An instance of RadPrintDocument used to control the print process and settings.

PrintPreview()

Opens a print preview dialog that allows viewing and adjusting how the pivot grid will appear when printed. This method creates a new RadPrintDocument with default settings.

Declaration
public virtual void PrintPreview()

PrintPreview(RadPrintDocument)

Opens a print preview dialog that allows viewing and adjusting how the pivot grid will appear when printed. This overload uses a specified RadPrintDocument for more control over the printing process.

Declaration
public virtual void PrintPreview(RadPrintDocument document)
Parameters
RadPrintDocument document

An instance of RadPrintDocument used to control the print process and settings.

ReloadData()

Recalculates all the aggregated data and refreshes the visual representation of the pivot grid. Use this method when the underlying data source has changed and you need to update the pivot grid.

Declaration
public void ReloadData()

SaveLayout(Stream)

Saves the RadPivotGrid's current layout configuration to a stream in XML format. This includes group configurations, column widths, row heights, and other display settings. The stream remains open after the operation completes.

Declaration
public virtual void SaveLayout(Stream stream)
Parameters
System.IO.Stream stream

The stream where the layout information will be written.

SaveLayout(String)

Saves the RadPivotGrid's current layout configuration to a file in XML format. This includes group configurations, column widths, row heights, and other display settings.

Declaration
public virtual void SaveLayout(string fileName)
Parameters
System.String fileName

The path to the file where the layout information will be saved.

SaveLayout(XmlWriter)

Saves the RadPivotGrid's current layout configuration to XML format. This includes properties like group configurations, column widths, row heights, and other display settings.

Declaration
public virtual void SaveLayout(XmlWriter xmlWriter)
Parameters
System.Xml.XmlWriter xmlWriter

The XmlWriter used to write the serialized layout data.

ShowFieldList()

Shows the Field Chooser dialog which allows users to select and organize fields in the pivot grid. Users can drag fields to different areas (row fields, column fields, data fields, or filter fields) to reorganize the pivot grid.

Declaration
public void ShowFieldList()

Events

AggregateDescriptorElementCreating

Fires when an aggregate descriptor element is being created. Allows for replacing it with a custom element.

Declaration
public event AggregateDescriptorElementCreatingEventHandler AggregateDescriptorElementCreating
Event Type
AggregateDescriptorElementCreatingEventHandler

AggregatesPositionElementCreating

Fires when the aggregate position element is being created. Allows for replacing it with a custom element.

Declaration
public event AggregatesPositionElementCreatingEventHandler AggregatesPositionElementCreating
Event Type
AggregatesPositionElementCreatingEventHandler

CellCreating

Fires when a cell element is being created. Allows for replacing the default elements with custom ones.

Declaration
public event PivotCellCreatingEventHandler CellCreating
Event Type
PivotCellCreatingEventHandler

CellFormatting

Fires when a cell element is updated. Allows for customizing the appearance of the cells.

Declaration
public event PivotCellEventHandler CellFormatting
Event Type
PivotCellEventHandler

DataProviderChanged

Fires when the DataProvider property has changed.

Declaration
public event DataProviderChangedEventHandler DataProviderChanged
Event Type
DataProviderChangedEventHandler

FilterDescriptorElementCreating

Fires when a filter descriptor element is being created. Allows for replacing it with a custom element.

Declaration
public event FilterDescriptorElementCreatingEventHandler FilterDescriptorElementCreating
Event Type
FilterDescriptorElementCreatingEventHandler

GroupDescriptorElementCreating

Fires when a group descriptor element is being created. Allows for replacing it with a custom element.

Declaration
public event GroupDescriptorElementCreatingEventHandler GroupDescriptorElementCreating
Event Type
GroupDescriptorElementCreatingEventHandler

GroupElementCreating

Fires when a group element is being created. Allows for replacing the default group elements.

Declaration
public event PivotGroupElementCreatingEventHandler GroupElementCreating
Event Type
PivotGroupElementCreatingEventHandler

GroupElementFormatting

Fires when a group element is updated. Allows for customizing its appearance.

Declaration
public event PivotGroupElementEventHandler GroupElementFormatting
Event Type
PivotGroupElementEventHandler

GroupExpandedChanged

Fires when a group is expanded or collapsed.

Declaration
public event PivotGroupEventHandler GroupExpandedChanged
Event Type
PivotGroupEventHandler

PrintElementFormatting

Fires when a print element is being prepared for painting.

Declaration
public event PrintElementEventHandler PrintElementFormatting
Event Type
PrintElementEventHandler

PrintElementPaint

Fires when the print element has been painted. Allows for adding custom painting.

Declaration
public event PrintElementPaintEventHandler PrintElementPaint
Event Type
PrintElementPaintEventHandler

RowCreating

Fires when a row element is being created. Allows for replacing the default elements with custom ones.

Declaration
public event PivotRowCreatingEventHandler RowCreating
Event Type
PivotRowCreatingEventHandler

RowFormatting

Fires when a row element is updated.

Declaration
public event PivotRowEventHandler RowFormatting
Event Type
PivotRowEventHandler

SelectionChanged

Fires when the selection in RadPivotGrid has changed.

Declaration
public event EventHandler SelectionChanged
Event Type
System.EventHandler

UpdateCompleted

Fires when the data provider has finished building the data and the UI was updated.

Declaration
public event EventHandler UpdateCompleted
Event Type
System.EventHandler

Explicit Interface Implementations

IChartDataProvider.SetChartView(ChartView)

Sets the chart view to display data from this pivot grid.

Declaration
void IChartDataProvider.SetChartView(ChartView chartView)
Parameters
ChartView chartView

The chart view to associate with this pivot grid data.
Implements

IChartDataProvider.UpdateChartData()

Updates the chart data based on the current state of the pivot grid. Refreshes the associated chart view with the latest data from the pivot grid.

Declaration
void IChartDataProvider.UpdateChartData()
Implements

IPrintable.BeginPrint(RadPrintDocument, PrintEventArgs)

Declaration
int IPrintable.BeginPrint(RadPrintDocument sender, PrintEventArgs args)
Parameters
RadPrintDocument sender

System.Drawing.Printing.PrintEventArgs args

Returns
System.Int32

Implements

IPrintable.EndPrint(RadPrintDocument, PrintEventArgs)

Declaration
bool IPrintable.EndPrint(RadPrintDocument sender, PrintEventArgs args)
Parameters
RadPrintDocument sender

System.Drawing.Printing.PrintEventArgs args

Returns
System.Boolean

Implements

IPrintable.GetSettingsDialog(RadPrintDocument)

Declaration
Form IPrintable.GetSettingsDialog(RadPrintDocument document)
Parameters
RadPrintDocument document

Returns
System.Windows.Forms.Form

Implements

IPrintable.PrintPage(Int32, RadPrintDocument, PrintPageEventArgs)

Declaration
bool IPrintable.PrintPage(int pageNumber, RadPrintDocument sender, PrintPageEventArgs args)
Parameters
System.Int32 pageNumber

RadPrintDocument sender

System.Drawing.Printing.PrintPageEventArgs args

Returns
System.Boolean

Implements

Extension Methods