vcl-cxbuttons.md
An advanced button component with support for multiple usage scenarios.
TcxButton = class(
TcxCustomButton
)
TcxButton is an advanced DevExpress counterpart for the standard TButton component shipped with the VCL library.
The TcxButton component can display both a caption and a glyph as well as execute an associated command on a click (in Standard and Command Link modes):
Alternatively, the button can display an associated drop-down menu (in any of the three supported drop-down modes):
In addition, you can use the SpeedButtonOptions.GroupIndex property to define a button as part of a TcxButton group (similar to the standard TSpeedButton component shipped with the VCL library):
The list below outlines key members of the TcxCustomButton class. These members allow you to configure button appearance and behavior.
CaptionSpecifies a caption for the button.DescriptionSpecifies a description for the button (in Command Link and Office Drop Down modes only).LookAndFeelProvides access to look & feel settings (at the component level).OnCustomDrawAllows you to override or complement built-in draw routines for the button.OptionsImageProvides access to all button glyph-related settings (the button can display a glyph only if the PaintStyle property is set to bpsDefault or bpsGlyph).PopupAlignmentSpecifies menu alignment (if the Kind property is set to cxbkDropDown, cxbkDropDownButton, or cxbkOfficeDropDown).
KindSpecifies the selected button type (according to the target purpose).PaintStyleSpecifies the active content display mode.SpeedButtonOptionsProvides access to speed button options. You can use the SpeedButtonOptions.GroupIndex property to use the button as a standard TSpeedButton component (that is, as part of a button group).
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.
DropDownMenuAllows you to associate the button with a drop-down menu component. The button can display a drop-down menu only if the Kind property is set to cxbkDropDown, cxbkDropDownButton, or cxbkOfficeDropDown.OnClickAllows you to respond to a click on the button. You can set the RepeatClick property to True to raise the OnClick event repeatedly while the button is pressed.OnDropDownMenuPopupExAllows you to customize the associated drop-down menu before it is displayed.RepeatClickSpecifies if the button generates OnClick events repeatedly at regular intervals while pressed.
The following code example creates five buttons with different-sized SVG glyphs using a single image list as a glyph source:
uses
cxButtons, // Declares the TcxButton class and related types
cxGraphics; // Declares the TcxImageList class and related types
// ...
procedure TMyForm.FormCreate(Sender: TObject);
var
AButton: TcxButton;
ALargeGlyphSettings: TcxButtonImageOptions;
begin
AButton := TcxButton.Create(Self); // Creates the large "Apply" button
AButton.Parent := Self; // Associates the created button with the form
AButton.Caption := 'Apply';
AButton.Font.Size := 20;
// Position the button
AButton.Top := 40;
AButton.Left := 40;
AButton.Height := 60;
AButton.Width := 140;
// Assign a glyph and configure related settings
ALargeGlyphSettings := AButton.OptionsImage;
ALargeGlyphSettings.Images := cxImageList1;
ALargeGlyphSettings.ImageIndex := 0;
ALargeGlyphSettings.SVGOptions.UseRegularAsLarge := True;
ALargeGlyphSettings.SVGOptions.LargeSize.Width := 48;
ALargeGlyphSettings.SVGOptions.LargeSize.Height := 48;
AButton := TcxButton.Create(Self); // Creates the large "Cancel" button
AButton.Parent := Self; // Associates the created button with the form
// Position the button
AButton.Top := 40;
AButton.Left := 200;
AButton.Height := 60;
AButton.Width := 60;
AButton.PaintStyle := bpsGlyph;
// Assign a glyph and configure related settings
AButton.OptionsImage.Assign(ALargeGlyphSettings); // Copies common settings from the "Apply" button
AButton.OptionsImage.ImageIndex := 1; // Assigns a different glyph from the source image list
AButton := TcxButton.Create(Self); // Creates the small "Refresh" button
AButton.Parent := Self; // Associates the created button with the form
AButton.Caption := 'Refresh';
AButton.Left := 40; // Positions the button
AButton.OptionsImage.Images := cxImageList1;
AButton.OptionsImage.ImageIndex := 2;
AButton := TcxButton.Create(Self); // Creates the small "Add" button
AButton.Parent := Self; // Associates the created button with the form
AButton.Caption := 'Add';
AButton.Left := 115; // Positions the button
AButton.OptionsImage.Images := cxImageList1;
AButton.OptionsImage.ImageIndex := 3;
AButton := TcxButton.Create(Self); // Creates the small "Remove" button
AButton.Parent := Self; // Associates the created button with the form
AButton.Caption := 'Remove';
AButton.Left := 190; // Positions the button
AButton.OptionsImage.Images := cxImageList1;
AButton.OptionsImage.ImageIndex := 4;
end;
#include "cxButtons.hpp" // Declares the TcxButton class and related types
#include "cxGraphics.hpp" // Declares the TcxImageList class and related types
// Add the following linker directives to the corresponding CPP source file:
#pragma link "cxButtons" // Required to use cxButtons.hpp declarations
#pragma link "cxGraphics" // Required to use cxGraphics.hpp declarations
// ...
void __fastcall TMyForm::FormCreate(TObject *Sender)
{
TcxButton *AButton;
TcxButtonImageOptions *ALargeGlyphSettings;
AButton = new TcxButton(this); // Creates the large "Apply" button
AButton->Parent = this; // Associates the created button with the form
AButton->Caption = "Apply";
AButton->Font->Size = 20;
// Resize and position the button
AButton->Top = 40;
AButton->Left = 40;
AButton->Height = 60;
AButton->Width = 140;
// Assign a glyph and configure related settings
ALargeGlyphSettings = AButton->OptionsImage;
ALargeGlyphSettings->Images = cxImageList1;
ALargeGlyphSettings->ImageIndex = 0;
ALargeGlyphSettings->SVGOptions->UseRegularAsLarge = true;
ALargeGlyphSettings->SVGOptions->LargeSize->Width = 48;
ALargeGlyphSettings->SVGOptions->LargeSize->Height = 48;
AButton = new TcxButton(this); // Creates the large "Cancel" button
AButton->Parent = this; // Associates the created button with the form
// Resize and position the button
AButton->Top = 40;
AButton->Left = 200;
AButton->Height = 60;
AButton->Width = 60;
AButton->PaintStyle = bpsGlyph;
// Assign a glyph and configure related settings
AButton->OptionsImage->Assign(ALargeGlyphSettings); // Copies common settings from the "Apply" button
AButton->OptionsImage->ImageIndex = 1; // Assigns a different glyph within the source image list
AButton = new TcxButton(this); // Creates the small "Refresh" button
AButton->Parent = this; // Associates the created button with the form
AButton->Caption = "Refresh";
AButton->Left = 40; // Positions the button
AButton->OptionsImage->Images = cxImageList1;
AButton->OptionsImage->ImageIndex = 2;
AButton = new TcxButton(this); // Creates the small "Add" button
AButton->Parent = this; // Associates the created button with the form
AButton->Caption = "Add";
AButton->Left = 115; // Positions the button
AButton->OptionsImage->Images = cxImageList1;
AButton->OptionsImage->ImageIndex = 3;
AButton = new TcxButton(this); // Creates the small "Remove" button
AButton->Parent = this; // Associates the created button with the form
AButton->Caption = "Remove";
AButton->Left = 190; // Positions the button
AButton->OptionsImage->Images = cxImageList1;
AButton->OptionsImage->ImageIndex = 4;
}
TObject TPersistent TComponent TControl TWinControl TButtonControl TCustomButton TcxCustomButton TcxButton
See Also