TdxCustomLayoutGroup.CreateItem(TdxCustomLayoutItemClass) Method

Creates a new item within a given group and returns the newly created item.

Declaration

function CreateItem(AItemClass: TdxCustomLayoutItemClass = nil): TdxCustomLayoutItem;

Parameters

Name	Type	Description
AItemClass	TdxCustomLayoutItemClass	Optional. The layout item type. This parameter accepts a reference to the corresponding TdxCustomLayoutItem class descendant to select the required item type. If you omit this parameter, the function creates a TdxLayoutItem class instance. Refer to the following section for a complete list of available options: Available Layout Item Types.

Returns

Type	Description
TdxCustomLayoutItem	The created layout item. Cast the returned object to the corresponding TdxCustomLayoutItem class descendant (AItemClass) to access all public API members.

Remarks

Call the CreateItem function to create any supported layout item in the group. The created item is accessible using the Items property.

Available Layout Item Types

Pass the following class-references as the optional AItemClass parameter to create corresponding layout items within the group:

TdxLayoutItem

Default. The standard layout item designed as a container for controls (TControl descendants). The CreateItem function creates this layout item if you omit the optional AItemClass parameter.

TdxLayoutCheckBoxItem

A checkbox designed for complex application UI layouts based on the TdxLayoutControl component.

TdxLayoutEmptySpaceItem

An auxiliary layout item that allows you to adjust the distance between two adjacent layout items.

TdxLayoutImageItem

An image container designed for complex application UI layouts based on the TdxLayoutControl component.

TdxLayoutLabeledItem

An auxiliary layout item you can use to display captions or labels for other layout items.

TdxLayoutRadioButtonItem

A radio button designed for complex application UI layouts based on the TdxLayoutControl component.

TdxLayoutSeparatorItem

A horizontal or vertical static line designed to separate adjacent layout items or groups.

TdxLayoutSplitterItem

A splitter designed to delimit and resize two adjacent layout items without using the Customization Form.

Code Example: 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.

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).

Delphi

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.CaptionOptions.Text := '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;

C++

#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
  }
}