TdxCustomLayoutGroup.CaptionOptions Property

Specifies the group caption and related settings.

Declaration

property CaptionOptions: TdxLayoutGroupCaptionOptions read; write;

Property Value

Type	Description
TdxLayoutGroupCaptionOptions	Stores the layout group caption and related settings.

Remarks

Use the CaptionOptions.Text property to specify a caption for the layout group. Layout item and group captions support multiple formatting options and can include accelerator characters.

Available Options

Use the CaptionOptions.FormattedText to configure the appearance and behavior of formatted text ranges defined in the layout group caption. To display a glyph within the layout group caption, use the CaptionOptions.Glyph or CaptionOptions.ImageIndex property.

Refer to the TdxLayoutGroupCaptionOptions class description for detailed information on all available options.

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