vcl-dxlayoutcontrol.md
A Layout control.
TdxLayoutControl = class(
TdxCustomLayoutControl
)
The Layout control is designed to arrange controls on a form without overlapping or misalignment.
The list below outlines key members of the TdxLayoutControl class. These members allow you to manage nested groups and items, as well as configure core UI layout appearance and behavior settings.
SmartPasteInserts the specified string or current clipboard content into all configured layout items using the AI-powered Smart Paste functionality.
DefaultUseGlobalSkinEnables 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 TdxCustomLayoutLookAndFeel descendant 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 synchronization with global skin and palette is disabled.
OptionsImageAllows you to specify source image lists for layout items in enabled and disabled states.UseGlobalSkinSpecifies if the Layout control uses global skin and palette instead of individual look & feel settings defined using the LayoutLookAndFeel property.
AbsoluteItemCountReturns the total number of all items and groups in the layout control (the number of items accessible through the AbsoluteItems property).AbsoluteItemsProvides 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 | CreateItemCreate new groups and items.CreateItemForControl.Creates a new layout item for an individual control. The created item contains and positions the target control.FindItemReturns a nested layout item by its name, handle, or target control.ItemsProvides access to the root layout group.
Provides access to UI Automation and accessibility-related settings.[1]
Tip
Use Automation.Name, Automation.Description, and other API members to specify information visible to third-party assistive tools as UIA node properties.
OnHyperlinkClickAllows you to respond to a click on a layout item caption or prevent hyperlink activation.OnHyperlinkMouseEnter | OnHyperlinkMouseLeaveAllow you to track mouse pointer movements between hyperlinks in layout item captions.OnShowHyperlinkHintAllows you to customize hyperlink hints.OptionsItemProvides access to layout item behavior settings.RedrawOnResize
Specifies if the layout control redraws content during resize operations.
Tip
You can set the RedrawOnResize property to False to increase resize operation performance if your application design is based on a resizable layout that includes graphics-rich controls.
CustomizationSpecifies if the layout control is in customization mode.CustomizeAvailableItemsViewKindSwitches the Available Items pane on the Customization Form between list and tree display modes.CustomizeFormProvides access to the Customization Form.CustomizeFormBoundsAllows you to adjust Customization Form dimensions.CustomizeFormClassAllows you to replace the predefined Customization Form with a custom implementation.CustomizeFormTabbedViewSwitches the Customization Form between tabbed and side-by-side pane display modes.MenuItemsSpecifies options available in runtime layout customization menus. In addition, you can handle the OnGetCustomizationMenuItems event.OnCustomizationAllows you to execute custom code in response to Customization property value changes.OnGetCustomizationMenuItemsAllows you to hide or display individual customization menu items based on custom criteria. This event complements the MenuItems property.UndoRedoManagerAllows you to undo or reapply layout customization operations.
AlignmentConstraintCountReturns the number of alignment constraint rules created in the layout control (the number of items accessible through the AlignmentConstraints property).AlignmentConstraintsProvides indexed access to all [alignment constraint] rules in the layout control.ContentBounds | OccupiedClientHeight | OccupiedClientWidthReturn client area and content dimensions.CreateAlignmentConstraintCreates an alignment constraint rule. Use the AlignmentConstraint property of any layout group or item to associate it with the created alignment constraint rule.LayoutDirectionAllows you to arrange groups and items horizontally or vertically.LeftPos | TopPosReturn horizontal and vertical content scroll positions (if the layout control displays corresponding scroll bars).
CanRestoreChecks if external storage is specified in the OptionsStoring property set and contains a saved layout control state.LoadFromIniFile | LoadFromRegistry | LoadFromStreamLoad a saved state of the layout control and its content from a specified source.OptionsStoringProvides access to layout state storage-related settings.RestoreRestores the layout control state from a source specified in the OptionsStoring property set.SaveToIniFile | SaveToRegistry | SaveToStreamSave the current state of the layout control and its content to the target storage.StoreSaves the current state of the layout control and its content to the external storage specified in the OptionsStoring property set.
AssignCopies settings between Layout controls.BeginUpdate | EndUpdate | CancelUpdateAllow you to avoid excessive redraw operations during batch data and appearance changes.
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.
Tip
This code example demonstrates a general layout group management technique useful when you need to maintain multiple groups within the same Layout control.
If your form layout design includes only one group, you can create layout items directly within the root group (TdxCustomLayoutControl.Items).
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
}
}
The following code example demonstrates a procedure that deletes all nested groups and items within the target layout group:
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
}
}
Show 11 items
TObject TPersistent TComponent TControl TWinControl TCustomControl TcxCustomControl TcxControl TcxScrollingControl TdxCustomLayoutControl TdxLayoutControl
Footnotes
See Also