vcl-cxbuttonedit-5f53e3a9.md
The base class for single-line text editors with embedded buttons.
TcxCustomButtonEdit = class(
TcxCustomMaskEdit
)
A button editor is a single-line text editor with one or more embedded buttons and support for masked input.
A button editor maintains a collection of embedded buttons accessible through the Properties.Buttons property.
To associate editor buttons with specific functionality in your application, you can link each button to an action object (a TBasicAction descendant instance) or handle the Properties.OnButtonClick event as demonstrated in the code example below.
The list below outlines key members of the TcxCustomButtonEdit class. These members allow you to configure button editors.
Style | StyleDisabled | StyleFocused | StyleHot | StyleReadOnly
Allow you to define individual appearance settings for different editor states.
Tip
To apply the same style settings to multiple editors, use a TcxEditStyleController component. If you need to apply the same style settings to all editors in your application, you can use a TcxDefaultEditStyleController component.
StylesProvides access to individual styles applied to the editor in different states.TransparentSpecifies if the editor is transparent in GDI render mode.
ClearClears the editor.CopyToClipboard | CutToClipboard | PasteFromClipboardAllow you to perform clipboard operations.EditValueSpecifies the edit value.OnEditingAllows you to prevent users from activating the editor.ResetEditValueRestores the previous edit value before the pending change is applied.SelectAllSelects editor content.ValidateEditValidates the display value.
DataBindingAllows you to bind the editor to data.CanPostEditValueIdentifies if the data-aware editor can post its edit value to the bound data storage. Only data-aware editors publish this property.OnPostEditValueExecutes custom code when the editor posts its value to the bound data storage.PostEditValuePosts the edit value to the bound data storage.
ActivePropertiesProvides access to the current editor settings regardless of their source. This property set does not allow you to customize editor settings.GetPropertiesClassReturns the actual editor settings type.PropertiesAllows you to customize editor settings directly if the editor does not have an assigned repository item.RepositoryItemSpecifies a repository item as an external source of editor settings. A repository item has priority over other editor settings.
AutoSizeSpecifies if the editor automatically adjusts its size to fit content.EnabledSpecifies if the editor is enabled.CanModifyIdentifies if the editor is in read-only mode.IsEditValidating | IsHiding | IsPostingAllow you to identify the current operation in the editor.ShowHintSpecifies if the standalone editor can display hints. To enable hints for an in-place editor in a container control, set its OptionsBehavior.CellHints[1] property to True.SupportsSpellingIdentifies if the editor supports the TdxSpellChecker component.Width | HeightAllow you to explicitly define editor dimensions.
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.
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;
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
}
}
Do not use the TcxCustomButtonEdit class directly. Use the following descendants instead:
TcxButtonEditAn unbound single-line text editor with embedded buttons.TcxDBButtonEditA data-aware single-line text editor with embedded buttons.
Show 14 items
TObject TPersistent TComponent TControl TWinControl TCustomControl TcxCustomControl TcxControl TcxContainer TcxCustomEditContainer TcxCustomEdit TcxCustomTextEdit TcxCustomMaskEdit TcxCustomButtonEdit
Footnotes
True or False to enable or disable in-place editor hints in corresponding container controls:See Also