Customization Form
- 4 minutes to read
The Customization Form provides the ability to temporarily hide specific grid rows, and make them visible again at runtime. It is a separate form listing the headers of all hidden rows whose VGridOptionsRow.ShowInCustomizationForm option is enabled. The BaseRow.Visible and BaseRow.VisibleIndex properties of these rows are set to false and -1, respectively. Row headers are displayed in the Customization Form one under another. They have the same height as when they are within the row header panel.
Hiding and Restoring Rows
End-users have the opportunity to hide rows in the vertical grid controls (VGridControl and PropertyGridControl) when the Customization Form appears. If a row’s VGridOptionsRow.AllowMoveToCustomizationForm option is turned on, users can drag the row header from the header panel to the Customization Form to hide the row. Dragging the header back to the row header panel makes the row visible again.
If the Customization Form is visible onscreen, dragging and moving row headers is allowed regardless of the VGridOptionsRow.AllowMove and VGridOptionsBehavior.DragRowHeaders option settings.
Rows can also be moved to/from the Customization Form programmatically. For this purpose, you should change the BaseRow.Visible property of the required row. Setting this property to false hides the row and moves it to the Customization Form (if the row’s VGridOptionsRow.ShowInCustomizationForm option is set to true). Thereafter, to display the row, set its BaseRow.Visible property to true. Hiding and restoring rows via code can be performed regardless of the VGridOptionsRow.AllowMoveToCustomizationForm option setting and the Customization Form’s visibility.
Note
When the VGridOptionsRow.ShowInCustomizationForm option of a row is not active, dragging the row header away from the header panel or setting its BaseRow.Visible property to false will hide the row, but the row will not be placed in the Customization Form. In this case, you can only restore this row programmatically.
Customization Form Tabs
The Customization Form contains two tabs: Rows and Categories.
The Categories tab contains hidden rows of the CategoryRow type. Other types of hidden rows are contained in the Rows tab. If a category is dragged to the Customization Form, its header will be placed in the Categories tab while the Rows tab will contain the headers of its child rows, provided that they are not category rows. Child category rows will be displayed in the Categories tab.
The New… and Delete buttons allow the creation and deletion of category rows directly in the Customization Form.
Note that there are two corresponding events (VGridControlBase.CustomizationFormCreatingCategory and VGridControlBase.CustomizationFormDeletingCategory) that occur when creating/deleting categories by clicking these buttons. Keep in mind that if you delete a category row by clicking the Delete button in the Customization Form, all of its child rows (if any) will be deleted as well if the VGridOptionsBehavior.PreserveChildRows option is disabled. Otherwise (if the VGridOptionsBehavior.PreserveChildRows option is active), child rows are moved to the VGridControlBase.Rows collection representing top-level grid rows, but they remain hidden in the Customization Form.
Showing, Accessing and Hiding the Customization Form
The Customization Form can be invoked and hidden with the help of the VGridControlBase.RowsCustomization and VGridControlBase.DestroyCustomization methods, respectively. The VGridControlBase.ShowCustomizationForm or VGridControlBase.HideCustomizationForm event is generated each time you display or hide the Customization Form. Please refer to the Using the Customization Form topic for more information on how to use these methods and events.
After being created, the Customization Form can be accessed from the grid control’s VGridControlBase.CustomizationForm property. This property is represented by an instance of the VGridCustomizationForm object. Since this object is a descendant of the Form class, it can be adjusted like a regular form. In addition, it introduces three properties: VGridCustomizationForm.PressedRow, VGridCustomizationForm.RowItemWidth and VGridCustomizationForm.CategoryItemWidth. The first one can be used to obtain the row selected in the Customization Form when a dragging operation starts. The other two properties specify the width of the row headers displayed in the Rows and Categories tabs, respectively.