TdxCustomLayoutControl.BeginUpdate Method

Postpones all control redraw operations that reflect content and appearance setting changes until an EndUpdate or CancelUpdate procedure call.

Declaration

procedure BeginUpdate;

Remarks

Every time you change a layout item/group or appearance setting, the Layout control redraws content to reflect the change. Enclose multiple content and appearance changes between BeginUpdate and EndUpdate procedure calls to avoid UI flickering due to excessive redraw operations and improve performance.

BeginUpdate/EndUpdate and Batch Changes

A BeginUpdate procedure call disables notifications and postpones applying all changes until an EndUpdate call. A subsequent EndUpdate call does the following:

• Re-enables change notifications and corresponding redraw operations
• Applies all changes made after a BeginUpdate call
• Sends corresponding notifications in a batch
• Redraws the Layout control

Note

Ensure that every BeginUpdate procedure call is followed by an EndUpdate or CancelUpdate call, even if an exception occurs. Otherwise, all layout items, groups, and embedded controls remain frozen and unresponsive.

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.

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

Clear a Layout Group

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

Delphi

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;

C++

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