Customization Form
- 6 minutes to read
Overview
The vertical grid provides Customization form that allows users to hide grid rows and create/remove row categories. Click Row Chooser in a row’s context menu to invoke the form.
Options
Form
The VGridCustomizationForm class represents the form. The VGridControlBase.ShowCustomizationForm event fires before the form is shown and allows you to customize it. Use the VGridControlBase.CustomizationForm property to access the form when it is displayed onscreen. When the form is not shown, this property returns null.
The example below shows how to specify the form’s caption, width, border style and icon as in the following figure.
void vGridControl1_ShowCustomizationForm(object sender, EventArgs e) {
VGridControl vGridControl1 = sender as VGridControl;
// Change the form caption.
vGridControl1.CustomizationForm.Text = "Hidden Rows";
// Change the form border style.
vGridControl1.CustomizationForm.FormBorderStyle = FormBorderStyle.FixedSingle;
// Enlarge the form width.
vGridControl1.CustomizationForm.Width += 10;
// Specify the form caption icon.
Icon formIcon = new Icon("C:\\customize1.ico");
vGridControl1.CustomizationForm.Icon = formIcon;
}
Rows
Set the BaseRow.OptionsRow.AllowMoveToCustomizationForm property to false to prohibit users to move the row to Customization form.
Note
The BaseRow.OptionsRow.AllowMove and VGridControl.OptionsBehavior.DragRowHeaders options do not affect the capability to move the row to Customization form.
If you use the BaseRow.Visible or BaseRow.VisibleIndex property to hide a row in code, you can also set the BaseRow.OptionsRow.ShowInCustomizationForm property to false to hide it in Customization form.
Categories
New… and Delete buttons in Categories tab allow users to create and delete row categories in Customization form.
The VGridControl.CustomizationFormCreatingCategory and VGridControl.CustomizationFormDeletingCategory events fire before a category created/deleted. You can handle these events to prevent a category from being created/deleted, customize its caption, etc.
When a user deletes a category, its rows are also deleted. The VGridControl.OptionsBehavior.PreserveChildRows property allows you to preserve the rows, and delete the category only. The preserved rows move to the root level.
How to validate a new category’s caption
When users create a new category, they enter the category’s caption. The example below shows how to check whether a category with the same caption already exists in the grid. If the captions match, the code shows a warning message.
The code enumerates the grid’s categories to compare their captions with the new category’s caption. See Tree Traversal for more information on how to enumerate the grid’s rows.
using DevExpress.XtraVerticalGrid.Events;
public class RowOperationCategoryCaption : RowOperation {
private string newCategoryCaption;
private bool found = false;
public RowOperationCategoryCaption(string newCaption) {
this.newCategoryCaption = newCaption;
}
public bool Found {
get { return found; }
}
public override void Execute(BaseRow row) {
// Check if the processed row is a category.
if (row.XtraRowTypeID != 0) return;
// Compare the row caption with the entered caption.
if (row.Properties.Caption == newCategoryCaption) found = true;
}
public override bool CanContinueIteration(BaseRow row){
return !Found;
}
}
private void vGridControl1_CustomizationFormCreatingCategory(object sender,
CustomizationFormCreatingCategoryEventArgs e) {
RowOperationCategoryCaption operation = new RowOperationCategoryCaption(e.Category.Properties.Caption);
VGridControl vGridControl = sender as VGridControl;
// Perform the operation.
vGridControl.RowsIterator.DoOperation(operation);
// Display a warning message if the match is found.
if (operation.Found) {
string messageText =
"A category row with the same caption already exists.\r\n" +
"Click Yes to modify the new category row caption.\r\n" +
"Click No to create a new category row with the specified caption.\r\n"+
"Do you want to enter new caption?";
DialogResult result = MessageBox.Show(messageText,"Match found",
MessageBoxButtons.YesNo);
// Prohibit to create a new row depending on the user choice.
if (result == DialogResult.Yes) e.CanCreate = false;
}
}
How to Show/Hide the Form in Code
Call the VGridControlBase.RowsCustomization method to show Customization form. The form is shown at the grid’s bottom right. Use the screenLocation parameter to specify where to show the form. The VGridControlBase.ShowCustomizationForm event fires before the form is shown.
To close the form, call the VGridControlBase.DestroyCustomization method. This method sets the VGridControlBase.CustomizationForm property to null. The VGridControlBase.HideCustomizationForm event fires before the form is closed.
The following code shows how to display/hide Customization form depending on whether it is already hidden/displayed.
private void button1_Click(object sender, System.EventArgs e) {
if (vGridControl1.CustomizationForm == null)
vGridControl1.RowsCustomization();
else
vGridControl1.DestroyCustomization();
}
private void vGridControl1_ShowCustomizationForm(object sender, System.EventArgs e) {
button1.Text = "Hide Customization Form";
}
private void vGridControl1_HideCustomizationForm(object sender, System.EventArgs e) {
button1.Text = "Customize...";
}