How to Create Layout Items and Groups

• Oct 20, 2023
• 4 minutes to read

This topic describes how to create layout items and groups at design time, runtime and in code. Select one of the following links to jump to the desired section of this topic.

At Design Time

Via Layout Control’s Runtime UI

In Code

At Design Time

To create layout items and groups, use the Customization Form. To invoke this form, double-click the control or click Designer… within the layout control‘s context menu.

Click the “Add Group” button to create a layout group within the Available Items pane.

Click the “Add Item” button to create a standard layout item.

To create an auxiliary layout item, click the “Add Auxiliary Item” button and select the item’s type within the button’s dropdown list.

After creation, every layout element represents an “available” element. The term “available” means that the element was created, but has not been placed within the layout control. “Available” layout elements are displayed within the Available Items pane.

When importing a form layout, layout elements are created automatically. To import a form’s layout into the layout control, click Import… within the control’s context menu.

Via Layout Control’s Runtime UI

End-users can use the Customization Form to create only groups and certain auxiliary items – standard layout items and image items cannot be added by end-users.

In Code

The table below lists layout elements and methods that allow you to create them:

Created Element	Method
Layout Group Tabbed Layout Group	A layout control’s CreateGroup function A layout container’s CreateGroup function A layout group’s CreateGroup function
Layout Item	A layout control’s CreateItemForControl function A layout container’s CreateItemForControl function A layout group’s CreateItemForControl function
Layout Item Empty Space Item Image Item Label Item Separator Item Splitter Item	A layout control’s CreateItem function A layout container’s CreateItem function A layout group’s CreateItem function
Any Layout Element	A layout container’s CloneItem function

Use the layout control’s AvailableItems collection to access all the newly created items.

The following code sample demonstrates how to:

• Create a layout group within the root group.

• Create layout items for editor controls located on a form.

• Create auxiliary items.

• Add the created items to the group.

Delphi

uses
  ..., dxLayoutControl;
var
  ALayoutGroup: TdxLayoutGroup;
  ALayoutItem: TdxLayoutItem;
begin
  dxLayoutControl1.BeginUpdate;  // Postpones updates
  try
    // Creates a child group within the root group
    ALayoutGroup := TdxLayoutGroup(dxLayoutControl1.CreateGroup(nil, dxLayoutControl1.Items));
    ALayoutGroup.CaptionOptions.Text := 'Group'; // Specifies the group caption
    // Creates a layout item for cxTextEdit1
    dxLayoutControl1.CreateItemForControl(cxTextEdit1, ALayoutGroup);
    // Creates an empty space item and sets its height
    TdxLayoutEmptySpaceItem(ALayoutGroup.CreateItem(TdxLayoutEmptySpaceItem)).Height := 20;
    ALayoutGroup.CreateItemForControl(cxTextEdit2); // Creates a layout item for cxTextEdit2
    ALayoutGroup.CreateItem(TdxLayoutSeparatorItem);  // Creates a separator item within the group
    ALayoutItem := TdxLayoutItem(dxLayoutControl1.CreateItem);  // Creates a layout item
    ALayoutItem.Control := cxTextEdit3;
    ALayoutItem.Parent := ALayoutGroup;  // Adds the item to the group created earlier
  finally
    dxLayoutControl1.EndUpdate;  // Resumes updates, even if an exception occurs
  end;
end;

C++

#include "dxLayoutControl.hpp"
// ...
  TdxLayoutGroup *ALayoutGroup;
  TdxLayoutItem *ALayoutItem;
  // ...
  dxLayoutControl1->BeginUpdate();  // Postpones updates
  try
  {
    // Creates a child group within the root group
    ALayoutGroup = dynamic_cast<TdxLayoutGroup*>(dxLayoutControl1->CreateGroup(nullptr, dxLayoutControl1->Items));
    ALayoutGroup->CaptionOptions->Text = "Group"; // Specifies the group caption
    dxLayoutControl1->CreateItemForControl(cxTextEdit1, ALayoutGroup); // Creates a layout item for cxTextEdit1
    // Creates an empty space item and sets its height
    dynamic_cast<TdxLayoutEmptySpaceItem*>(ALayoutGroup->CreateItem(TdxLayoutEmptySpaceItem))->Height = 20;
    ALayoutGroup->CreateItemForControl(cxTextEdit2);  // Creates a layout item for cxTextEdit2
    ALayoutGroup->CreateItem(TdxLayoutSeparatorItem); // Creates a separator item within the group
    ALayoutItem = dynamic_cast<TdxLayoutItem*>(dxLayoutControl1->CreateItem()); // Creates a layout item
    ALayoutItem->Control = cxTextEdit3;
    ALayoutItem->Parent = ALayoutGroup;  // Adds the item to the group created earlier
  }
  __finally
    dxLayoutControl1->EndUpdate();  // Resumes updates, even if an exception occurs