TdxCustomLayoutControl Class

The base class for the Layout control.

Declaration

TdxCustomLayoutControl = class(
    TcxScrollingControl,
    IdxLayoutComponent,
    IdxSkinSupport,
    IdxCustomizeControlsHelper,
    IcxEditorFieldLink2,
    IdxLayoutContainerObject,
    IdxLayoutContainerOwner,
    IdxAcrylicHostControlListener,
    IdxUIALayoutControl
)

Remarks

The Layout control is designed to arrange controls on a form without overlapping or misalignment.

VCL Layout Control: An Application Example

Main API Members

The list below outlines key members of the TdxCustomLayoutControl class. These members allow you to manage nested groups and items, as well as configure core UI layout appearance and behavior settings.

Appearance Settings

DefaultUseGlobalSkin

Enables or disables synchronization with global skin and palette for all Layout controls in the application. The UseGlobalSkin property allows you to override this setting at the level of an individual Layout control.

LayoutLookAndFeel

Allows you to associate the Layout control with a component (a TdxLayoutSkinLookAndFeel instance) designed to store general look & feel and layout item group-specific settings (such as offsets and paddings).

You can use this property to define individual look & feel settings for the Layout control when synchronizing with the global skin. If a vector skin is selected, it always uses the color palette defined at the global level.

OptionsImage

Allows you to specify source image lists for layout items in enabled and disabled states.

UseGlobalSkin

Specifies if the Layout control uses global skin and palette instead of individual look & feel settings defined using the LayoutLookAndFeel property.

Layout Item and Group Management

AbsoluteItemCount: Returns the total number of all items and groups in the layout control (the number of items accessible through the AbsoluteItems property).
AbsoluteItems: Provides indexed access to all items and groups in the layout control.
Clear: Removes all nested layout items, groups, and associated controls.

Tip
If you need to clear an individual layout group, refer to the following code example: Clear a Layout Group.
CreateGroup | CreateItem: Create new groups and items
CreateItemForControl.: Creates a new layout item for an individual control. The created item contains and positions the target control.
FindItem: Returns a nested layout item by its name, handle, or target control.
Items: Provides access to the root layout group.

User Interaction APIs

OnHyperlinkClick: Allows you to respond to a click on a layout item caption or prevent hyperlink activation.
OnHyperlinkMouseEnter | OnHyperlinkMouseLeave: Allow you to track mouse pointer movements between hyperlinks in layout item captions.
OnShowHyperlinkHint: Allows you to customize hyperlink hints.
OptionsItem: Provides access to layout item behavior settings.
RedrawOnResize: Specifies if the layout control redraws its content during resize operations.

End-User Layout Customization

Customization: Specifies if the layout control is in customization mode.
CustomizeAvailableItemsViewKind: Switches the Available Items pane on the Customization Form between list and tree display modes.
CustomizeForm: Provides access to the Customization Form.
CustomizeFormBounds: Allows you to adjust Customization Form dimensions.
CustomizeFormClass: Allows you to replace the predefined Customization Form with a custom implementation.
CustomizeFormTabbedView: Switches the Customization Form between tabbed and side-by-side pane display modes.
MenuItems: Specifies options available in runtime layout customization menus. In addition, you can handle the OnGetCustomizationMenuItems event.
OnCustomization: Allows you to execute custom code in response to Customization property value changes.
OnGetCustomizationMenuItems: Allows you to hide or display individual customization menu items based on custom criteria. The MenuItems property specifies initially available menu items.
UndoRedoManager: Allows you to undo or reapply layout customization operations.

Content Position and Arrangement

AlignmentConstraintCount: Returns the number of alignment constraint rules created in the layout control (the number of items accessible through the AlignmentConstraints property).
AlignmentConstraints: Provides indexed access to all [alignment constraint] rules in the layout control.
ContentBounds | OccupiedClientHeight | OccupiedClientWidth: Return client area and content dimensions.
CreateAlignmentConstraint: Creates an alignment constraint rule. Use the AlignmentConstraint property of any layout group or item to associate it with the created alignment constraint rule.
LayoutDirection: Allows you to arrange groups and items horizontally or vertically.
LeftPos | TopPos: Return horizontal and vertical content scroll positions (if the layout control displays corresponding scroll bars).

Layout State Management

CanRestore: Checks if external storage is specified in the OptionsStoring property set and contains a saved layout control state.
LoadFromIniFile | LoadFromRegistry | LoadFromStream: Load a saved state of the layout control and its content from a specified source.
OptionsStoring: Provides access to layout state storage-related settings.
Restore: Restores the layout control state from a source specified in the OptionsStoring property set.
SaveToIniFile | SaveToRegistry | SaveToStream: Save the current state of the layout control and its content to the target storage.
Store: Saves the current state of the layout control and its content to the external storage specified in the OptionsStoring property set.

General-Purpose API Members

Assign: Copies settings between Layout controls.
BeginUpdate | EndUpdate | CancelUpdate: Allow you to avoid excessive redraw operations during batch data and appearance changes.

Code Examples

Create Layout Groups and Items

The code example in this section creates a parent TdxLayoutControl and nested layout group populated with four editors separated with auxiliary splitter and empty space layout items. Both the parent form and its nested layout control automatically adjust their dimensions according to group content.

Delphi
C++

uses
  dxLayoutControl,  // Declares the TdxLayoutControl class
  dxLayoutContainer, // Declares TdxLayoutGroup and TdxLayoutItem classes
  cxCalendar,  // Declares the TcxDateEdit class
  cxCurrencyEdit, // Declares the TcxCurrencyEdit class
  cxSpinEdit;  // Declares the TcxSpinEdit class
  System.DateUtils; // Declares the Today function
// ...

procedure TMyForm.FormCreate(Sender: TObject);
var
  ALayoutGroup: TdxLayoutGroup;
  ALayoutItem: TdxLayoutItem;
  ACalendar: TcxDateEdit;
  ACurrencyEdit: TcxCurrencyEdit;
  ASpinEdit: TcxSpinEdit;
  AIconPath: string;
  ALayoutControl: TdxLayoutControl;
begin
  AIconPath := 'C:\Program Files (x86)\DevExpress\VCL\ExpressLibrary\Sources\' +
    'Icon Library\SVG Images\Icon Builder\';
  Self.AutoSize := True;  // Enables automatic form size adjustment
  // Create a layout control for the current form
  ALayoutControl := TdxLayoutControl.Create(Self);
  ALayoutControl.Parent := Self;
  ALayoutControl.BeginUpdate;  // Initiates the following batch change
  try
    ALayoutControl.AutoSize := True;  // Enables automatic layout control size adjustment
    // Create a parent layout group for all UI elements
    ALayoutGroup := ALayoutControl.Items.CreateGroup(TdxLayoutGroup) as TdxLayoutGroup;
    ALayoutGroup.Caption := 'Order';
    // Create and configure a date editor and its container layout item
    ACalendar := TcxDateEdit.Create(Self);
    ACalendar.Properties.Kind := ckDate;
    ACalendar.EditValue := Today;
    ALayoutItem := ALayoutGroup.CreateItemForControl(ACalendar);
    ALayoutItem.CaptionOptions.Text := 'Purchase Date: ';
    ALayoutItem.CaptionOptions.Glyph.LoadFromFile(AIconPath + 'Actions_Calendar.svg');
    ALayoutItem.CaptionOptions.Glyph.SourceWidth := 16;
    ALayoutItem.CaptionOptions.Glyph.SourceHeight := 16;
    // Create and configure a currency editor and its container layout item
    ACurrencyEdit := TcxCurrencyEdit.Create(Self);
    ACurrencyEdit.Value := 0;
    ALayoutItem := ALayoutGroup.CreateItemForControl(ACurrencyEdit);
    ALayoutItem.CaptionOptions.Text := 'Price: ';
    ALayoutItem.CaptionOptions.Glyph.LoadFromFile(AIconPath + 'Business_Money.svg');
    ALayoutItem.CaptionOptions.Glyph.SourceWidth := 16;
    ALayoutItem.CaptionOptions.Glyph.SourceHeight := 16;
    // Create and configure a spin editor and its container layout item
    ASpinEdit := TcxSpinEdit.Create(Self);
    ALayoutItem := ALayoutGroup.CreateItemForControl(ASpinEdit);
    ALayoutItem.CaptionOptions.Text := 'Quantity: ';
    ALayoutItem.CaptionOptions.Glyph.LoadFromFile(AIconPath + 'Shopping_ShoppingCart.svg');
    ALayoutItem.CaptionOptions.Glyph.SourceWidth := 16;
    ALayoutItem.CaptionOptions.Glyph.SourceHeight := 16;
    ALayoutGroup.CreateItem(TdxLayoutSeparatorItem); // Creates a separator layout item
    // Create an empty space item and specify its height
    (ALayoutGroup.CreateItem(TdxLayoutEmptySpaceItem) as TdxLayoutEmptySpaceItem).Height := 20;
    // Create and configure a currency editor and its container layout item below the empty space
    ACurrencyEdit := TcxCurrencyEdit.Create(Self);
    ACurrencyEdit.Properties.ReadOnly := True;
    ACurrencyEdit.Value := 0;
    ALayoutItem := ALayoutGroup.CreateItemForControl(ACurrencyEdit);
    ALayoutItem.CaptionOptions.Text := 'Payment Amount: ';
  finally
    ALayoutControl.EndUpdate;  // Calls EndUpdate regardless of the batch operation's success
  end;
end;

#include "dxLayoutControl.hpp"  // Declares the TdxLayoutControl class
#include "dxLayoutContainer.hpp" // Declares TdxLayoutGroup and TdxLayoutItem classes
#include "cxCalendar.hpp"  // Declares the TcxDateEdit class
#include "cxCurrencyEdit.hpp" // Declares the TcxCurrencyEdit class
#include "cxSpinEdit.hpp"  // Declares the TcxSpinEdit class
#include "System.DateUtils.hpp" // Declares the Today function

// Add the following linker directives to the corresponding CPP source file:
#pragma link "dxLayoutControl"  // Required to use dxLayoutControl.hpp declarations
#pragma link "dxLayoutContainer"  // Required to use dxLayoutContainer.hpp declarations
#pragma link "cxCalendar"  // Required to use cxCalendar.hpp declarations
#pragma link "cxCurrencyEdit" // Required to use cxCurrencyEdit declarations
#pragma link "cxSpinEdit"  // Required to use cxSpinEdit declarations
// ...

void __fastcall TMyForm::FormCreate(TObject *Sender)
{
  TdxLayoutGroup *ALayoutGroup;
  TdxCustomLayoutGroup *AGroup;
  TdxLayoutItem *ALayoutItem;
  TdxCustomLayoutItem *ALayoutSpaceItem;
  TcxDateEdit *ACalendar;
  TcxCurrencyEdit *ACurrencyEdit;
  TcxSpinEdit *ASpinEdit;
  UnicodeString AIconPath;
  TdxLayoutControl *ALayoutControl;
  // ...

  AIconPath = "C:\\Program Files (x86)\\DevExpress\\VCL\\ExpressLibrary\\Sources\\"
    "Icon Library\\SVG Images\\Icon Builder\\";
  this->AutoSize = true;
  ALayoutControl = new TdxLayoutControl(this);
  ALayoutControl->Parent = this;
  ALayoutControl->BeginUpdate();  // Initiates the following batch change
  try
  {
    ALayoutControl->AutoSize = true;  // Enables automatic layout control size adjustment
    // Create a parent layout group for all UI elements
    AGroup = ALayoutControl->Items->CreateGroup(__classid(TdxLayoutGroup));
    ALayoutGroup = dynamic_cast<TdxLayoutGroup*>(AGroup);
    ALayoutGroup->CaptionOptions->Text = "Order";
    // Create and configure a date editor and its container layout item
    ACalendar = new TcxDateEdit(this);
    ACalendar->Properties->Kind = ckDate;
    ACalendar->EditValue = Today();
    ALayoutItem = ALayoutGroup->CreateItemForControl(ACalendar);
    ALayoutItem->CaptionOptions->Text = "Purchase Date: ";
    ALayoutItem->CaptionOptions->Glyph->LoadFromFile(AIconPath + "Actions_Calendar.svg");
    ALayoutItem->CaptionOptions->Glyph->SourceWidth = 16;
    ALayoutItem->CaptionOptions->Glyph->SourceHeight = 16;
    // Create and configure a currency editor and its container layout item
    ACurrencyEdit = new TcxCurrencyEdit(this);
    ACurrencyEdit->Value = 0;
    ALayoutItem = ALayoutGroup->CreateItemForControl(ACurrencyEdit);
    ALayoutItem->CaptionOptions->Text = "Price: ";
    ALayoutItem->CaptionOptions->Glyph->LoadFromFile(AIconPath + "Business_Money.svg");
    ALayoutItem->CaptionOptions->Glyph->SourceWidth = 16;
    ALayoutItem->CaptionOptions->Glyph->SourceHeight = 16;
    // Create and configure a spin editor and its container layout item
    ASpinEdit = new TcxSpinEdit(this);
    ALayoutItem = ALayoutGroup->CreateItemForControl(ASpinEdit);
    ALayoutItem->CaptionOptions->Text = "Quantity: ";
    ALayoutItem->CaptionOptions->Glyph->LoadFromFile(AIconPath + "Shopping_ShoppingCart.svg");
    ALayoutItem->CaptionOptions->Glyph->SourceWidth = 16;
    ALayoutItem->CaptionOptions->Glyph->SourceHeight = 16;
    ALayoutGroup->CreateItem(__classid(TdxLayoutSeparatorItem));  // Creates a separator layout item
    // Create an empty space layout item and specify its height
    ALayoutSpaceItem = ALayoutGroup->CreateItem(__classid(TdxLayoutEmptySpaceItem));
    dynamic_cast<TdxLayoutEmptySpaceItem*>(ALayoutSpaceItem)->Height = 20;
    // Create and configure a currency editor and its container layout item below the empty space
    ACurrencyEdit = new TcxCurrencyEdit(this);
    ACurrencyEdit->Properties->ReadOnly = true;
    ACurrencyEdit->Value = 0;
    ALayoutItem = ALayoutGroup->CreateItemForControl(ACurrencyEdit);
    ALayoutItem->CaptionOptions->Text = "Payment Amount: ";
  }
  __finally
  {
    ALayoutControl->EndUpdate();  // Calls EndUpdate regardless of the batch operation's success
  }
}

VCL Layout Control: A Group with Items

Clear a Layout Group

The following code example demonstrates a procedure that deletes all nested groups and items within the target layout group:

Delphi
C++

uses
  dxLayoutControl,  // Declares the TdxLayoutControl class
  dxLayoutContainer; // Declares TdxLayoutGroup and TdxLayoutItem classes
// ...

procedure TMyForm.ClearGroup(ALayoutControl: TdxLayoutControl; ALayoutGroup: TdxLayoutGroup);
var
  AItem: TdxCustomLayoutItem;
  I: Integer;
begin
  if (ALayoutControl = nil) or (ALayoutGroup = nil) then Exit;
  if not ALayoutControl.Container.IsUpdateLocked then  // Checks the control state (for recursive calls)
    ALayoutControl.BeginUpdate;  // Initiates the following batch change
  try
    for I := ALayoutGroup.Count - 1 downto 0 do  // Iterates through all nested groups and items
    begin
      AItem := ALayoutGroup.Items[I];
      if (AItem is TdxLayoutItem) and ((AItem as TdxLayoutItem).Control <> nil) then
        (AItem as TdxLayoutItem).Control.Free  // Deletes the current non-group item
      else
        if AItem is TdxLayoutGroup then  // If the current item is a nested group
          ClearGroup(ALayoutControl, (AItem as TdxLayoutGroup));  // Calls ClearGroup recursively
    end;
    // Delete auxiliary layout items
    for I := ALayoutGroup.Count - 1 downto 0 do // Iterates through remaining auxiliary layout items
      ALayoutGroup.Items[I].Free;
  finally
    if ALayoutControl.Container.IsUpdateLocked then  // Checks the control state (for recursive calls)
      ALayoutControl.EndUpdate;  // Calls EndUpdate regardless of the batch operation's success
  end;
end;

#include "dxLayoutControl.hpp"  // Declares the TdxLayoutControl class
#include "dxLayoutContainer.hpp" // Declares TdxLayoutGroup and TdxLayoutItem classes

// Add the following linker directives to the corresponding CPP source file:
#pragma link "dxLayoutControl"  // Required to use dxLayoutControl.hpp declarations
#pragma link "dxLayoutContainer" // Required to use dxLayoutContainer.hpp declarations
// ...

void __fastcall TMyForm::ClearGroup(TdxLayoutControl *ALayoutControl, TdxLayoutGroup *ALayoutGroup)
{
  TdxCustomLayoutItem *AItem;
  if((ALayoutControl == nullptr) || (ALayoutGroup == nullptr)) { return; }
  if(!ALayoutControl->Container->IsUpdateLocked())  // Checks the control state (for recursive calls)
    ALayoutControl->BeginUpdate();  // Initiates the following batch change
  try
  {
    for(int i = ALayoutGroup->Count - 1; i >= 0; i--)  // Iterates through all nested groups and items
    {
      AItem = ALayoutGroup->Items[i];
      if((AItem->InheritsFrom(__classid(TdxLayoutItem))) &&
         (dynamic_cast<TdxLayoutItem*>(AItem)->Control != nullptr))
        delete dynamic_cast<TdxLayoutItem*>(AItem)->Control;  // Deletes the current non-group item
      else if(AItem->InheritsFrom(__classid(TdxLayoutGroup)))  // If the current item is a nested group
        ClearGroup(ALayoutControl, dynamic_cast<TdxLayoutGroup*>(AItem));  // Calls ClearGroup recursively
    }
    // Delete auxiliary layout items
    for(int i = ALayoutGroup->Count - 1; i >= 0; i--)  // Iterates through remaining auxiliary layout items
      delete ALayoutGroup->Items[i];
  }
  __finally
  {
    if(ALayoutControl->Container->IsUpdateLocked())  // Checks the control state (for recursive calls)
      ALayoutControl->EndUpdate();  // Calls EndUpdate regardless of the batch operation's success
  }
}