TcxEditButton Class
A button displayed within an editor.
#Declaration
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 | ContentAlignment
- Specify the caption and its position within the button.
- Glyph | ImageIndex
- Specify a custom editor button glyph.
- Kind | Mode
- Allow you to switch between available button content types and usage scenarios.
- LeftAlignment
- Aligns the button to the left or right border of the parent editor.
- Stretchable
- Allows you to stretch the button together with the parent editor.
- Transparent
- Enables transparency for the editor button background.
- Width
- Allows you to explicitly specify the width of the editor button.
#Behavior Settings
- Action
- Allows you to associate the editor button with an action object. A click on the button executes the associated action.
- Default
- Allows 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.
- Hint
- Specifies a hint for the editor button.
- HotTrackMode
- Allows 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
- Assign
- Copies compatible settings between editor buttons.
- Automation
- Provides access to the button’s UI Automation and accessibility settings.
- Enabled
- Specifies if the editor button is enabled. If a user clicks the button when it is enabled, the parent editor raises the Properties.OnButtonClick event.
- Visible
- Hides 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 Tcx
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;
#Direct TcxEditButton Class Reference
The TcxEditButtons.Items property references a TcxEditButton
object.