Customization Form Styles

Oct 31, 2022
4 minutes to read

The style defines the Customization Form layout and the capabilities available for end users. To specify the required style, use the PivotGridOptionsCustomization.CustomizationFormStyle property.

The Customization Form can be painted in two styles: Simple and Excel 2007.

Simple Style

A simple-style Customization Form displays hidden fields.

End users can hide visible fields by dragging and dropping them onto the Customization Form, and return hidden fields to the pivot report when drop them onto appropriate Header Areas.

When end users move fields to the Customization Form, the field’s visibility is changed, but the field’s area remains unchanged.

Excel 2007 Style

An Excel-style Customization Form contains a separate section where hidden fields are displayed and four more sections that display visible fields located in the Column, Data, Filter, and Row areas.

Similar to a simple-style Customization Form, end users can hide visible fields by dragging and dropping them into the Hidden Fields section and return hidden fields to the pivot report by dropping them onto appropriate Header Areas. When end users move fields to the Hidden Fields section, the field’s visibility is changed, but the field’s area remains unchanged.

A list below displays additional capabilities provided by the Excel-style Customization Form:

Drag field’s header between the Customization Form’s area boxes to move the field to a specific area.
Delay layout updates. First, check the Defer Layout Update check box, then drag fields between the areas and click the Update button to apply changes.
Sort and filter data. You can toggle the sort order of fields by clicking their headers in the Customization Form and invoke filter popup windows using the filter buttons.

You can display hidden fields in a list or hierarchical structure. To learn more, see the User Folders topic.

End users can change the Customization Form layout using a popup menu.

Use the PivotGridOptionsCustomization.CustomizationFormAllowedLayouts property to list all the allowed layouts and prevent end users from selecting particular layouts.

To specify a preferred layout in code, use the PivotGridOptionsCustomization.CustomizationFormLayout property.

If a layout is not specified as allowed, it is hidden from the Customization Form Layout menu, and assigning it to the CustomizationFormLayout property has no effect.

Examples

This example demonstrates how to display the Customization Form near the Pivot Grid.

The form is in SplitContainerControl - a parent container for the Pivot Grid and Customization Form. To specify the SplitContainer’s panel as the Customization Form’s owner, handle the PivotGridControl.ShowingCustomizationForm event and use the e.ParentControl property.

Specify the form’s appearance with the PivotGridOptionsCustomization.CustomizationFormStyle property.

Call the FieldsCustomization method to show the form.

Form1.cs
Form1.vb

using System;
using System.Windows.Forms;

namespace StandaloneCustomForm {
    public partial class Form1 : DevExpress.XtraEditors.XtraForm {
        public Form1() {
            InitializeComponent();
        }
        private void Form1_Load(object sender, EventArgs e) {
            excelDataSource1.FileName = "SalesPerson.xlsx";
            excelDataSource1.Fill();

            // Set the Customization Form style and show the form.
            pivotGridControl1.OptionsCustomization.CustomizationFormStyle = 
                DevExpress.XtraPivotGrid.Customization.CustomizationFormStyle.Excel2007;
            pivotGridControl1.FieldsCustomization();
        }
        private void pivotGridControl1_ShowingCustomizationForm(object sender, 
            DevExpress.XtraPivotGrid.CustomizationFormShowingEventArgs e) {
            // Set the control that owns the Customization Form.
            e.ParentControl = splitContainerControl1.Panel2;

            e.CustomizationForm.Dock = DockStyle.Fill;
        }
    }
}

Imports System
Imports System.Windows.Forms

Namespace StandaloneCustomForm
    Partial Public Class Form1
        Inherits DevExpress.XtraEditors.XtraForm

        Public Sub New()
            InitializeComponent()
        End Sub

        Private Sub Form1_Load(ByVal sender As Object, ByVal e As EventArgs) Handles Me.Load
            excelDataSource1.FileName = "SalesPerson.xlsx"
            excelDataSource1.Fill()

            ' Set the Customization Form style and show the form.
            pivotGridControl1.OptionsCustomization.CustomizationFormStyle = DevExpress.XtraPivotGrid.Customization.CustomizationFormStyle.Excel2007
            pivotGridControl1.FieldsCustomization()
        End Sub

        Private Sub pivotGridControl1_ShowingCustomizationForm(ByVal sender As Object, ByVal e As DevExpress.XtraPivotGrid.CustomizationFormShowingEventArgs) Handles pivotGridControl1.ShowingCustomizationForm
            ' Set the control that owns the Customization Form.
            e.ParentControl = splitContainerControl1.Panel2

            e.CustomizationForm.Dock = DockStyle.Fill
        End Sub
    End Class
End Namespace