Customization Form

• Apr 02, 2024
• 8 minutes to read

The Customization Form allows you to create or delete a layout element (group or item), arrange it within the layout control and change its visibility using drag-and-drop operations.

At design time, you can open the Customization Form in the following ways:

• Select Designer… in the control’s context menu;

• Double-click the layout control or its elements.

In code, you can switch the form’s visibility using the layout control’s Customization property.

The Customization Form is comprised of the following panes:

• Layout Tree View – provides the layout control’s hierarchical structure. This pane is used to rearrange the control’s layout.

• Available Items – contains invisible layout elements. This pane is used to change the visibility of the control’s elements, or create new elements. If the form’s panes are displayed side-by-side, separated by a vertical splitter (the layout control’s CustomizeFormTabbedView property is set to False), you can switch the visibility of elements by dragging them between panes.

To modify the layout structure in the Customization Form, you can drag layout elements within a tree in both panes. While dragging a layout element over a layout group’s caption, you have the choice of making this element the group’s child, or its sibling in the tree hierarchy. The Customization Form displays the following drag images (indicators) to assist you during drag-and-drop operations. The drag images suggest the resulting drop position for a layout element being dragged, relative to a layout element under the mouse pointer, as shown in the following table.

Indicator	Context	Sample	Meaning
	Dragging over the top part of a layout element’s caption.		A layout element being dragged will be positioned before a layout element located under the mouse pointer, as its sibling (at the same nesting level).
	Dragging over the bottom part of a layout element’s caption.		A layout element being dragged will be positioned after a layout element located under the mouse pointer, as its sibling (at the same nesting level).
	Dragging over the central part of a layout group’s caption.		A layout element being dragged will be nested as the last child of a layout group located under the mouse pointer.

Multiple layout elements can be selected simultaneously in the Customization Form by clicking them while holding down the Shift and/or Ctrl key. So, while element and menu item descriptions in the tables below refer to a single selected element, the same descriptions apply to all the selected elements.

The Layout Tree View pane’s elements include:

Element	Description
	Expands the tree.
	Collapses the tree.
	Deletes a selected layout element. At runtime, only layout elements that were created at runtime can be deleted.
	Aligns selected layout elements to a certain container side. This button is only available at design-time.

The Available Items pane’s elements include:

Element	Description
	Expands the tree.
	Collapses the tree.
	Creates a new layout group.
	Creates a new layout item. This element is available at design time only.
	Creates a new auxiliary item. Note that the “Add Image Item” item is available only at design time.
	Deletes a selected layout element. At runtime, only layout elements that were created at runtime can be deleted.
	Toggles the layout elements structure representation between a tree and a flat list.

Common elements:

Element	Description
	Changes the arrangement of panes within the Customization Form.
	Closes the Customization Form.

Design-time elements:

Element	Description
	Enables the root group highlight.
	Changes the visibility of the layout control and layout element selectors.

Runtime elements:

Element	Description
	Undoes the last operation performed on a layout element. This action corresponds to the Undo method of the layout control’s Undo/Redo Manager.
	Redoes the last undo operation performed on a layout element. This action corresponds to the Redo method of the layout control’s Undo/Redo Manager.
	Saves the current layout.
	Restores the layout previously saved using the Store Layout button.
	Switches the Customization Form between “Display Item Names” and “Display Item Captions” modes.

Customization Form Context Menu

The context menu commands include:

The Layout Tree View pane’s context menu.

Menu Item	Description
Undo	Undoes the last operation performed on a layout element. This action corresponds to the Undo method of the layout control’s Undo/Redo Manager. This menu item is available at runtime only.
Redo	Redoes the last undo operation performed on a layout element. This action corresponds to the Redo method of the layout control’s Undo/Redo Manager. This menu item is available at runtime only.
Expand All	Expands the tree.
Collapse All	Collapses the tree.
Delete	Deletes a selected layout element. At runtime, only layout elements that were created at runtime can be deleted.
Align by	Aligns selected elements to a certain container side. Particularly, it creates an alignment constraint for the chosen container side and assigns this constraint to the selected layout items. This menu item is only available at design time, and it is enabled when multiple layout elements are selected.
Horizontal Alignment	Horizontally aligns a selected layout element within a parent container. For a complete list of available horizontal alignment styles, refer to the TdxCustomLayoutItem.AlignHorz description. This action corresponds to the layout item’s AlignHorz property.
Vertical Alignment	Vertically aligns a selected layout element within the parent container. This action corresponds to the layout item’s AlignVert property. For a complete list of available vertical alignments, refer to the TdxCustomLayoutItem.AlignVert description.
Layout Direction	Arranges the group’s contents into different layouts within the group. This action corresponds to the group’s LayoutDirection property. For a complete list of available arrangements, refer to the TdxLayoutDirection description.
Border	Changes the group border’s visibility. This action corresponds to the group’s ShowBorder property.
Expand Button	Changes the group expand button’s visibility. This action corresponds to the group’s ButtonOptions.ShowExpandButton property.
Group	Creates a new parent for a selected layout element, and places the selected element into the parent.
Ungroup	Moves a selected group’s contents to the group’s parent and then deletes this group.
Caption	Changes the element caption’s visibility. This action corresponds to the layout element’s CaptionOptions.Visible property.
Caption Position	Changes the element caption’s position within the element. This action corresponds to the layout element’s CaptionOptions.Layout property.
Caption Horizontal Alignment	Changes the horizontal text alignment within the caption position. This action corresponds to the layout element’s CaptionOptions.AlignHorz property.
Caption Vertical Alignment	Changes the vertical text alignment within the caption position. This action corresponds to the layout element’s CaptionOptions.AlignVert property.
Rename	Renames a selected layout element. Alternatively, press the F2 key. This menu item is disabled if the layout control’s OptionsItem.AllowRename property is set to False.
Collapsible	Allows or forbids an end user to collapse a layout element associated with a splitter item. This menu item is enabled only for a selected splitter item. This action corresponds to the splitter item’s AllowCloseOnClick property.

You can control the runtime visibility of items within the Layout Tree View pane’s context menu via a layout control’s MenuItems property.

The Available Items pane’s context menu.

Menu Item	Description
Undo	Undoes the last operation performed on a layout element. This action corresponds to the Undo method of the layout control’s Undo/Redo Manager. This menu item is available at runtime only.
Redo	Redoes the last undo operation performed on a layout element. This action corresponds to the Redo method of the layout control’s Undo/Redo Manager. This menu item is available at runtime only.
Expand All	Expands the tree.
Collapse All	Collapses the tree.
Add Group	Creates a new layout group. Alternatively, use the Alt+G key combination.
Add Image Item	Creates a new image item. This menu item is available at design time only.
Add Item	Creates a new standard layout item. Alternatively, use the Alt+I key combination. This menu item is available at design time only.
Add Empty Space Item	Creates a new empty space item.
Add Label Item	Creates a new label item.
Add Separator Item	Creates a new separator.
Add Splitter Item	Creates a new splitter.
Delete	Deletes a selected layout element.
Rename	Renames a selected layout element. Alternatively, press the F2 key.

The table below lists the main properties that relate to the Customization Form.

Window Instance	The layout control’s CustomizeForm property.
Visibility	The layout control’s Customization property. The layout control’s OnCustomization event fires after the form’s visibility has been changed.
Bounds	The layout control’s CustomizeFormBounds property.
Contents	The layout control’s CustomizeFormTabbedView property.
HitTest Information	Based on the Customization Form point, the layout control’s GetHitTest function returns the following HitTest objects: For the Available Items pane, a TdxLayoutCustomizeFormAvailableItemsHitTest object; For the Layout Tree View pane, a TdxLayoutCustomizeFormTreeViewItemsHitTest object; For all other form points, a TdxLayoutCustomizeFormHitTest object.