How to: Create custom customization form

• Oct 29, 2020
• 3 minutes to read

You can create a custom Customization Form and use it instead of the standard Customization Form. The custom form can display any elements supported by the default form, and can also provide additional layout customization functionality. This tutorial shows how to create this form.

Basic steps to create a custom Customization Form are as follows:

• Create a form by deriving it from the DevExpress.XtraLayout.Customization.UserCustomizationForm class.
• Add any standard control elements supported by the default Customization Form. At design time, you can add it via the form’s context menu.
• Add custom controls and implement the required functionality.
• Register the new Customization Form via the LayoutControl.RegisterUserCustomizationForm method.

Design-time Sample

This tutorial shows how to implement a simple Customization Form providing a Restore All button, that allows an end-user to make all hidden items visible.

1. Create a new form.

   

2. Switch to the code designer, and change the form’s ancestor to the UserCustomizationForm class.

   C#

   // Original code:
   public partial class Form2 : Form {
   //... 
   
   // New code:
   public partial class Form2 : DevExpress.XtraLayout.Customization.UserCustomizationForm {
   

   VB.NET

   // Original code:
   Partial Class Form2
       Inherits System.Windows.Forms.Form
   // ...
   
   // New code:
   Partial Class Form2
       Inherits DevExpress.XtraLayout.Customization.UserCustomizationForm
   

3. Rebuild the project by selecting the Build->Rebuild Solution menu command.

4. Switch to the designer. Set the form’s caption as required. In this sample, it’s set to “New Customization Form”. Now the form looks like:

   

5. Right-click the form to open the context menu, allowing you to add the standard control elements, supported by the default Customization Form:

   

   You can add any of these elements using this menu, and then arrange the elements as required. In this example, only the Hidden Item List and Button Panel are added:

   

6. Add a SimpleButton control at the bottom of the form. Give it the Restore All caption:

   

7. Write a Click event handler for the Restore All button as follows:

   C#

   private void btnRestoreAll_Click(object sender, EventArgs e) {
       // Restores all the hidden layout items and groups from the Customization Form.
       while (this.OwnerControl.HiddenItems.Count > 0)
           this.OwnerControl.HiddenItems[0].RestoreFromCustomization();
   }
   

   VB.NET

   Private Sub btnRestoreAll_Click(sender As Object, e As EventArgs)
       ' Restores all the hidden layout items and groups from the Customization Form.
       While Me.OwnerControl.HiddenItems.Count > 0
          Me.OwnerControl.HiddenItems(0).RestoreFromCustomization()
       End While
   End Sub
   

8. In the main form’s Layout Control, register the new Customization Form via the LayoutControl.RegisterUserCustomizationForm method:

   C#

   private void Form1_Load(object sender, EventArgs e) {
       layoutControl1.RegisterUserCustomizationForm(typeof(Form2));
   }
   

   VB.NET

   Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
       LayoutControl1.RegisterUserCustomizationForm(GetType(Form2))
   End Sub
   

When running the main form, the new Customization Form can now be opened by right-clicking the Layout Control, and selecting the Customize Layout menu command.

The result is shown in the image below: