Runtime Customization Overview

• Mar 18, 2020
• 2 minutes to read

When an application starts, controls within the LayoutControl are arranged using a default layout. End-users, however, are not restricted to this layout, as layouts are fully customizable at runtime. For instance, end-users can temporarily hide specific layout items and their controls, rearrange and resize them, etc. This topic introduces common methods that allow end-users to customize the layout of controls at runtime.

Customization Modes

The LayoutControl supports default and quick customization modes, and you can switch between them by setting the LayoutControl.CustomizationMode property to Quick or Default.

• Default Runtime Customization

  This mode allows end-users to customize layouts using context menus and Customization Form capabilities.

• Quick Runtime Customization

  Layout customization is performed by the touch-friendly Customization Form.

The LayoutControl.AllowCustomization property sets the capability of runtime customization for end-users. By default, this property is set to the static (Shared in VB) AllowCustomizationDefaultValue property value. It is possible to prevent the runtime modification of a specific layout group. To do this, set the group’s LayoutItemContainer.AllowCustomizeChildren property to false.

The LayoutControl.OptionsCustomizationForm property contains settings that specify the customization mode capabilities (visibility of specific buttons, quick mode activation time, etc.).

Saving and Restoring the Layout

Changes in the layout that are made by end-users at runtime are not automatically saved between application runs. After the LayoutControl is destroyed, for instance, when a form is closed, all the end-user’s changes are lost. The solution that allows you to resolve this problem is to save the layout manually when the application closes and restore the saved layout when the application starts. This example demonstrates how to do this.

In this example, the layout will be stored in an XML file, so the LayoutControl.SaveLayoutToXml and LayoutControl.RestoreLayoutFromXml methods will be used. A list of all the methods for saving and loading the layout can be found in the Member Table: Save and Restore Layout topic.

C#

string layoutFileName = "layout.xml";
//...
private void Form1_Load(object sender, EventArgs e) {
   if (System.IO.File.Exists(layoutFileName))
      layoutControl1.RestoreLayoutFromXml(layoutFileName);
}

private void Form1_Closing(object sender, FormClosingEventArgs e) {
   layoutControl1.SaveLayoutToXml(layoutFileName);
}

VB.NET

Dim layoutFileName As String = "layout.xml"
' ...
Private Sub Form1_Load(ByVal sender As Object, ByVal e As System.EventArgs) _
  Handles MyBase.Load
   If System.IO.File.Exists(layoutFileName) Then
      LayoutControl1.RestoreLayoutFromXml(layoutFileName)
   End If
End Sub

Private Sub Form1_Closing(ByVal sender As Object, _
  ByVal e As System.ComponentModel.CancelEventArgs) Handles MyBase.Closing
   LayoutControl1.SaveLayoutToXml(layoutFileName)
End Sub