TcxButtonEdit Class

An unbound single-line text editor with embedded buttons.

Declaration

TcxButtonEdit = class(
    TcxCustomButtonEdit
)

Remarks

A button editor is a single-line text editor with one or more embedded buttons and support for masked input.

In this topic…

• Button Collection
• UI Automation/Accessibility Support
  • UI Automation Settings
  • Keyboard Navigation Between Embedded Buttons
  • Default Button
• Main API Members
  • Appearance Settings
  • Content-Related APIs
  • Editor Settings and Repository Items
  • General-Purpose API Members
• Code Example: Create Embedded Buttons with Custom Functionality
• Repository Item Class
• Related Compiled Demo

Button Collection

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 associate each button with an action object (a TBasicAction descendant instance) or handle the Properties.OnButtonClick event as demonstrated in the following code example: Create Embedded Buttons with Custom Functionality.

UI Automation/Accessibility Support

The TcxButtonEdit component is mapped to a node in the UI Automation tree when the global UI Automation flag (dxUIAutomationEnabled) is enabled.

UI Automation Settings

Use Automation.Name and Automation.Description properties to specify the editor name and add optional information that are then used to clarify editor purpose for users who rely on third-party assistive tools (such as Microsoft Narrator).

In addition, you can configure UI automation settings at the level of individual buttons using the TdxCustomEditButton.Automation property.

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

Keyboard Navigation Between Embedded Buttons

The button editor does not implement dedicated key combinations for navigation between multiple embedded buttons. Users need to rely on third-party assistive UIA tools to focus embedded buttons using a keyboard.

To focus an embedded button, you need to use the Move to next item command (or a similar counterpart) in a third-party assistive tool (UIA client) while the parent editor has focus.

For example, you need to press Caps Lock + → or Insert + →^[1] while Microsoft Narrator is active.

Default Button

The default editor button is associated with the default action in the editor. Users can press the Ctrl + Enter key combination to activate the button when the editor has focus. You can use the Properties.ClickKey property to change the key combination associated with the default button.

Main API Members

The list below outlines key members of the TcxButtonEdit class.

Appearance Settings

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.

Styles

Provides access to individual styles applied to the editor in different states.

Transparent

Specifies if the editor is transparent in GDI render mode.

Content-Related APIs

Clear

Clears the editor.

CopyToClipboard | CutToClipboard | PasteFromClipboard

Allow you to perform clipboard operations.

EditValue

Specifies the edit value.

OnEditing

Allows you to prevent users from activating the editor.

ResetEditValue

Restores the previous edit value before the pending change is applied.

SelectAll

Selects editor content.

ValidateEdit

Validates the display value.

Editor Settings and Repository Items

ActiveProperties

Provides access to the current editor settings regardless of their source. This property set does not allow you to customize editor settings.

GetPropertiesClass

Returns the actual editor settings type.

Properties

Allows you to customize editor settings directly if the editor does not have an assigned repository item.

RepositoryItem

Specifies a repository item as an external source of editor settings. A repository item has priority over other editor settings.

General-Purpose API Members

AutoSize

Specifies if the editor automatically adjusts its size to fit content.

Enabled

Specifies if the editor is enabled.

CanModify

Indicates if the editor is in read-only mode.

IsEditValidating | IsHiding | IsPosting

Allow you to identify the current operation in the editor.

ShowHint

Specifies if the standalone editor can display hints. To enable hints for an in-place editor in a container control, set its OptionsBehavior.CellHints^[2] property to True.

SupportsSpelling

Indicates if the editor supports the TdxSpellChecker component.

Width | Height

Allow you to explicitly define editor dimensions.

Code Example: Create Embedded 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

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;

C++

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

Repository Item Class

You can create a TcxEditRepositoryButtonItem component in an edit repository to define an unbound button editor, store button editor settings, and share them between multiple button editors.

Related Compiled Demo

To see the TcxButtonEdit component in action, run the Data Editors and Controls demo in the VCL Demo Center installed with compiled DevExpress VCL demos. Click the Button Editor item in the sidebar to run the corresponding demo.

Download: Compiled VCL Demos

Compiled DevExpress demos ship with source code installed in the Public Documents folder (%PUBLIC%) for all users (default). You can find all project and source code files for the Data Editors and Controls demo in the following folder:

Default Installation Path

%PUBLIC%\Documents\DevExpress VCL Demos\MegaDemos\Product Demos\ExpressEditors\

Inheritance

Show 15 items

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl

TcxCustomControl

TcxControl

TcxContainer

TcxCustomEditContainer

TcxCustomEdit

TcxCustomTextEdit

TcxCustomMaskEdit

TcxCustomButtonEdit

TcxButtonEdit

Footnotes

1. Refer to the following topic for detailed information on keyboard configuration for Microsoft Narrator: Narrator Keyboard Commands and Touch Gestures.

2. Set the following behavior properties to True or False to enable or disable in-place editor hints in corresponding container controls:

   • A Data Grid Table View’s OptionsBehavior.CellHints property.
   • A Tree List control’s OptionsBehavior.CellHints property.
   • A Vertical Grid control’s OptionsBehavior.CellHints property.