TcxEditButton Class

A button displayed within an editor.

Declaration

delphi

TcxEditButton = class(
    TcxCustomEditButton
)

Remarks

An editor button is a button within the editor client area. Editor buttons implement built-in or custom editor functionality. Editors maintain a collection of buttons accessible through the Properties.Buttons property.

An editor button can have a border and/or an opaque background depending on the parent editor’s look & feel settings.

To execute custom code in response to a click on an editor button, you can associate the button with an action object (a TBasicAction descendant instance) or handle the parent editor’s Properties.OnButtonClick event.

Main API Members

The list below outlines key members of the TcxEditButton class. These members allow you to configure editor buttons.

Appearance Settings

Caption | ContentAlignmentSpecify the caption and its position within the button.Glyph | ImageIndexSpecify a custom editor button glyph.Kind | ModeAllow you to switch between available button content types and usage scenarios.LeftAlignmentAligns the button to the left or right border of the parent editor.StretchableAllows you to stretch the button together with the parent editor.TransparentEnables transparency for the editor button background.WidthAllows you to explicitly specify the width of the editor button.

User Interaction Options

ActionAllows you to associate the editor button with an action object. A click on the button executes the associated action.Automation

Provides access to UI Automation and accessibility-related settings.

Tip

Use Automation.Name, Automation.Description, and other API members to specify information visible to third-party assistive tools as UIA node properties.

DefaultAllows you to set the editor button as default (the Enter keystroke executes the action associated with the default button). An editor can have only one default button at a time.HintSpecifies a hint for the editor button.HotTrackModeAllows you to switch between available hot-track modes for the editor button. This property has no effect if the Transparent property is set to True.

General-Purpose API Members

AssignCopies compatible settings between editor buttons.EnabledSpecifies if the editor button is enabled. If a user clicks the button when it is enabled, the parent editor raises the Properties.OnButtonClick event.VisibleHides or displays the editor button.

Code Example: Create Editor Buttons with Custom Functionality

The code example below demonstrates OnButtonClick and OnCreate event handlers.

The application form’s OnCreate event handler creates two additional embedded buttons in a TcxButtonEdit control and configures the appearance and behavior of all embedded buttons. The OnButtonClick event handler associates all created buttons with the editor’s functionality.

Note

This example uses a TcxImageList component with three SVG icons as a source of glyphs for the created buttons.

Delphi
C++

delphi

procedure TMyForm.cxButtonEdit1PropertiesButtonClick(Sender: TObject;
  AButtonIndex: Integer);
var
  AEditor: TcxButtonEdit;
begin
  AEditor := Sender as TcxButtonEdit;
  if AButtonIndex = 0 then // The first button clears the editor
    AEditor.Clear
  else if AButtonIndex = 1 then // The second button selects content
    AEditor.SelectAll
  else if AButtonIndex = 2 then // The third button hides or reveals content
  begin
    if AEditor.Properties.EchoMode = eemNormal then
      AEditor.Properties.EchoMode := eemPassword
    else
      AEditor.Properties.EchoMode := eemNormal;
  end;
end;

procedure TMyForm.FormCreate(Sender: TObject);
var
  AProperties: TcxButtonEditProperties;
  I: Integer;
begin
  cxButtonEdit1.ShowHint := True; // Enables hints for the editor
  AProperties := cxButtonEdit1.Properties;
  AProperties.BeginUpdate; // Initiates the following batch change
  try
    AProperties.Images := cxImageList1; // Assigns the source of button glyphs
    // Create two additional buttons
    AProperties.Buttons.Add;
    AProperties.Buttons.Add;
    // Specify common button settings
    for I := 0 to AProperties.Buttons.Count - 1 do
    begin
      AProperties.Buttons.Items[I].Kind := bkGlyph; // Changes the button content type to "glyph"
      AProperties.Buttons.Items[I].ImageIndex := I; // Specifies image indexes in the source list
      AProperties.Buttons.Items[I].HotTrackMode := TcxEditButtonHotTrackMode.Editor;
    end;
    // Specify unique button settings
    AProperties.Buttons.Items[0].Hint := 'Clear';
    AProperties.Buttons.Items[1].Hint := 'Select All';
    AProperties.Buttons.Items[2].Hint := 'Hide/Reveal';
    AProperties.Buttons.Items[2].LeftAlignment := True;
    AProperties.Buttons.Items[2].Transparent := True;
  finally
    AProperties.EndUpdate; // Calls EndUpdate regardless of the batch operation's success
  end;
end;

cpp

void __fastcall TMyForm::cxButtonEdit1PropertiesButtonClick(TObject *Sender,
   int AButtonIndex)
{
  TcxButtonEdit *AEditor = dynamic_cast<TcxButtonEdit*>(Sender);
  // ...
  if(AButtonIndex == 0) // The first button clears the editor
    AEditor->Clear();
  else if(AButtonIndex == 1) // The second button selects content
    AEditor->SelectAll();
  else if(AButtonIndex == 2) // The third button hides or reveals content
  {
    if(AEditor->Properties->EchoMode == eemNormal)
      AEditor->Properties->EchoMode = eemPassword;
    else
      AEditor->Properties->EchoMode = eemNormal;
  }
}

void __fastcall TMyForm::FormCreate(TObject *Sender)
{
  TcxButtonEditProperties *AProperties = cxButtonEdit1->Properties;
  cxButtonEdit1->ShowHint = true; // Enables hints for the editor
  AProperties->BeginUpdate(); // Initiates the following batch change
  try
  {
    AProperties->Images = cxImageList1; // Assigns the source of button glyphs
    // Create two additional buttons
    AProperties->Buttons->Add();
    AProperties->Buttons->Add();
    // Specify common button settings
    for(int i = 0; i < AProperties->Buttons->Count; i++)
    {
      AProperties->Buttons->Items[i]->Kind = bkGlyph; // Changes the button content type to "glyph"
      AProperties->Buttons->Items[i]->ImageIndex = i; // Specifies image indexes in the source list
      AProperties->Buttons->Items[i]->HotTrackMode = TcxEditButtonHotTrackMode::Editor;
    }
    // Specify unique button settings
    AProperties->Buttons->Items[0]->Hint = "Clear";
    AProperties->Buttons->Items[1]->Hint = "Select All";
    AProperties->Buttons->Items[2]->Hint = "Hide/Reveal";
    AProperties->Buttons->Items[2]->LeftAlignment = true;
    AProperties->Buttons->Items[2]->Transparent = true;
  }
  __finally
  {
    AProperties->EndUpdate(); // Calls EndUpdate regardless of the batch operation's success
  }
}

Direct TcxEditButton Class Reference

The TcxEditButtons.Items property references a TcxEditButton object.

Inheritance

TObject TPersistent TCollectionItem TcxCustomEditButton TcxEditButton