PivotTable Field List
- 5 minutes to read
The PivotTable Field List pane allows end-users to organize the structure of a pivot table and populate it with data. The Field List is divided into two sections: the Fields Section at the top of the pane lists the available data source fields and can be used to add fields to a pivot table, and the Areas Section at the bottom contains four areas corresponding to the PivotTable regions and is used to rearrange fields within the PivotTable report.
The Field List is invoked automatically when an end-user inserts a new pivot table or clicks any cell in the existing PivotTable report. If the Field List doesn’t appear, an end-user can do one of the following to display the pane.
On the PivotTable Tools | Analyze tab, in the Show group, click the Field List button.
Tip
For an example on how to create a ribbon UI and add the PivotTable Tools ribbon page to the SpreadsheetControl, refer to the Getting Started topic.
Right click any cell in the pivot table and select the Show Field List item in the context menu.
Add, Move or Remove Fields
To add a field to the pivot table, an end-user should drag the field from the Fields Section of the Field List pane and drop it to required area of the Areas Section.
- To add a field to the report filter area of a pivot table, an end-user should move the field to the Filters area of the Field List.
- To add a field to the row axis area of a pivot table, an end-user should move the field to the Rows area of the Field List
- To add a field to the column axis area of a pivot table, an end-user should move the field to the Columns area of the Field List.
- To add a field to the data area of a pivot table, an end-user should move the field to the Values area of the Field List
End-users can add multiple fields to each area, reorder fields within one area, or move a field to another area in the Field List.
To remove a field from the report, an end-user should drag this field outside the Field List pane.
Each time end-users add, rearrange or remove fields using the Pivot Table Field List, the pivot table is updated automatically to reflect its new state. If a pivot table an end-user is working with is rather complex and is based on a large data set, this update operation may take some time to complete. To improve performance, end-users can disable automatic updating of the pivot table by selecting the Defer Layout Update check box at the bottom of the Field List pane. In this case, the pivot table will not be updated unless an end-user clicks the Update button at the bottom-right corner of the Field List. To switch back to automatic updating of the PivotTable layout, an end-user should clear the Defer Layout Update check box.
To programmatically create a pivot table, add it to the worksheet’s collection of pivot tables (accessible from the Worksheet.PivotTables property) by using the PivotTableCollection.Add method. For details on how to build and adjust a pivot table in code, refer to the Pivot Table API topic and Pivot Tables section of examples.
PivotTable Field List Options
The SpreadsheetControl provides you with the capability to specify the size and initial position of the PivotTable Field List at run time. The Field List settings are defined by the SpreadsheetPivotTableFieldListOptions object, which can be accessed using the SpreadsheetControl.Options.PivotTableFieldList notation.
To specify the starting position of the Field List pane, use the SpreadsheetPivotTableFieldListOptions.StartPosition property. By default, the pane appears in the center of the SpreadsheetControl. To specify the pane’s position manually, set the SpreadsheetPivotTableFieldListOptions.StartPosition property to the SpreadsheetPivotTableFieldListStartPosition.ManualScreen or SpreadsheetPivotTableFieldListStartPosition.ManualSpreadsheetControl value, and then use the SpreadsheetPivotTableFieldListOptions.StartLocation property to define the coordinates of the upper-left corner of the PivotTable Field List relative to the upper-left corner of the screen or SpreadsheetControl, respectively.
To specify the size of the PivotTable Field List pane, use the SpreadsheetPivotTableFieldListOptions.StartSize property.
The example below demonstrates how to use properties of the SpreadsheetPivotTableFieldListOptions object to specify the starting position and size of the Field List pane.
// Specify the custom position and size of the PivotTable Field List pane.
SpreadsheetPivotTableFieldListOptions pivotTableFieldListOptions = spreadsheetControl.Options.PivotTableFieldList;
pivotTableFieldListOptions.StartPosition = SpreadsheetPivotTableFieldListStartPosition.ManualSpreadsheetControl;
pivotTableFieldListOptions.StartLocation = new Point(756, 0);
pivotTableFieldListOptions.StartSize = new Size(314, 614);
Hide or Disable the Field List
The SpreadsheetControl allows you to specify whether the Field List should be shown for pivot tables in a particular workbook. To do this, use the DocumentSettings.ShowPivotTableFieldList property of the DocumentSettings object containing workbook options and accessible from the IWorkbook.DocumentSettings property. If the DocumentSettings.ShowPivotTableFieldList property is set to false, the Field List is not displayed when an end-user clicks anywhere in the existing pivot table and can be invoked only by using the corresponding commands in the Spreadsheet UI.
To prevent the Field List from being displayed for a specific pivot table, use the PivotBehaviorOptions.EnableFieldList property of the object accessible from the PivotTable.Behavior property. If the PivotBehaviorOptions.EnableFieldList property is false, the Field List button on a ribbon and the Show Field List item in the context menu are shown disabled, so that an end-user cannot invoke the Field List pane to change the layout of the existing pivot table.