TStyledButton - Technical Reference

Overview

TStyledButton is a windowed button (TCustomControl) with focus, tab stop, Default/Cancel, accelerators and ModalResult. It is the replacement of the VCL TButton. Rendering is delegated to an internal TStyledButtonRender.

Guide with examples: TStyledButton.

Class Hierarchy

TCustomControl
  └─ TCustomStyledButton
      └─ TStyledButton

Unit

Vcl.StyledButton

Key Features

• Keyboard focus, TabStop, Default, Cancel, & accelerators, ModalResult (closes the parent form)
• Three-tier style: StyleFamily / StyleClass / StyleAppearance, shape (StyleDrawType, StyleRadius, StyleRoundedCorners)
• Five states with their own attributes: Normal, Pressed, Selected, Hot, Disabled
• ImageList, state images (also by name), DisabledImages, Glyph
• Split button (Style = bsSplitButton + DropDownMenu), command link (bsCommandLink + CommandLinkHint), ElevationRequired (UAC shield)
• AutoClick, NotificationBadge, toggle buttons (GroupIndex, AllowAllUp, Down)
• AsVCLComponent / StyleName to follow the VCL Styles; global replacement with the Interposer unit

Published Properties

The properties of the published section are the ones shown in the Object Inspector. Properties marked "(published from Delphi 10.4)" are published only when the D10_4+ condition of the library is defined.

Style (family, class, appearance, shape)

Property	Type	Default	Description
ActiveStyleName	string		Read-only: name of the VCL Style currently applied to the button.
AsVCLComponent	Boolean	False	When True the button is drawn like a standard VCL button (switches to Classic/Windows/Normal and adds seClient to StyleElements). Never stored in the DFM.
StyleElements	TStyleElements		Standard VCL property: with seClient the Classic family follows the active VCL Style. See AsVCLComponent.
StyleName	string	''	VCL Style name (Delphi 10.4+): when set, the button switches to the Classic family and uses the style name as StyleClass, so it follows that VCL Style.
StyleRadius	Integer	6	Corner radius in pixels, used by btRoundRect (DEFAULT_RADIUS).
StyleShadowSize	Integer	-1	Shadow below the face of the button in pixels (at 100% scale), the same in every state: -1 = the shadow of the style family (DEFAULT_SHADOW_SIZE; the Elevated and Fab appearances of Angular-M3 have one), 0 = no shadow, a value greater than zero = that shadow in any family. It is seen only below the button and drawn inside the area of the control, so the face is shorter by the shadow size. Values below -1 raise an exception.
StyleRoundedCorners	TRoundedCorners	all four corners	Set of corners to round: rcTopLeft, rcTopRight, rcBottomRight, rcBottomLeft (ALL_ROUNDED_CORNERS).
StyleDrawType	TStyledButtonDrawType	btRoundRect	Shape: btRoundRect, btRounded, btRect, btEllipse. Stored only when different from the default.
StyleFamily	TStyledButtonFamily (string)	'Classic'	Style family: Classic, Bootstrap, Angular-Light, Angular-Dark, Angular-M3-Light, Angular-M3-Dark, Basic-Colors, SVG-Colors (or a custom registered family). The default can be changed with RegisterDefaultRenderingStyle.
StyleClass	TStyledButtonClass (string)	'Windows'	Predefined style inside the family (e.g. Primary in Bootstrap, Basic in Angular-M3).
StyleAppearance	TStyledButtonAppearance (string)	'Normal'	Visual variant of the family (Normal/Outline, Flat/Raised/Basic/Stroked, Text/Elevated/Outlined/Filled/Tonal...).

State attributes

Property	Type	Default	Description
ButtonStyleNormal	TStyledButtonAttributes	(from style)	Colors, border and shape attributes of the Normal state. Filled from the style; stored only if customized.
ButtonStylePressed	TStyledButtonAttributes	(from style)	Colors, border and shape attributes of the Pressed state. Filled from the style; stored only if customized.
ButtonStyleSelected	TStyledButtonAttributes	(from style)	Colors, border and shape attributes of the Selected state. Filled from the style; stored only if customized.
ButtonStyleHot	TStyledButtonAttributes	(from style)	Colors, border and shape attributes of the Hot state. Filled from the style; stored only if customized.
ButtonStyleDisabled	TStyledButtonAttributes	(from style)	Colors, border and shape attributes of the Disabled state. Filled from the style; stored only if customized.

Caption and appearance

Property	Type	Default	Description
Caption	TCaption	''	Button text (supports the & accelerator in windowed buttons).
CaptionAlignment	TAlignment	taCenter	Horizontal alignment of the caption.
ShowCaption	Boolean	True	Show or hide the caption (useful for icon-only buttons).
CommandLinkHint	string	''	Second line of text of a command link (Style = bsCommandLink).
Font	TFont		Caption font. The font color is overridden by the style unless the attributes are customized.
ParentFont	Boolean	True	Inherits the font of the parent.
WordWrap	Boolean	False	Wraps the caption on more lines.
Flat	Boolean	False	Flat appearance (TSpeedButton/TBitBtn compatibility).

Images and glyph

Property	Type	Default	Description
DisabledImageIndex	TImageIndex	-1	Image when the button is disabled.
DisabledImageName	TImageName	''	Name version of DisabledImageIndex (Delphi 10.4+).
DisabledImages	TCustomImageList	nil	Separate image list used in the disabled state.
HotImageIndex	TImageIndex	-1	Image when the mouse is over the button.
HotImageName	TImageName	''	Name version of HotImageIndex (Delphi 10.4+).
ImageAlignment	TImageAlignment	iaLeft	iaLeft, iaRight, iaTop, iaBottom, iaCenter.
ImageIndex	TImageIndex	-1	Image of the normal state.
ImageName	TImageName	''	Name of the image in a name-aware list (Delphi 10.4+); alternative to ImageIndex.
ImageMargins	TImageMargins	Left = 8	Margins around the image (Left/Top/Right/Bottom); default depends on ImageAlignment.
Images	TCustomImageList	nil	Image list used for the button images.
PressedImageIndex	TImageIndex	-1	Image when the button is pressed.
PressedImageName	TImageName	''	Name version of PressedImageIndex (Delphi 10.4+).
SelectedImageIndex	TImageIndex	-1	Image when the button is selected (focused).
SelectedImageName	TImageName	''	Name version of SelectedImageIndex (Delphi 10.4+).
Spacing	Integer	0	Distance in pixels between image and caption.
StylusHotImageIndex	TImageIndex	-1	Image for stylus/touch hover.
StylusHotImageName	TImageName	''	Name version of StylusHotImageIndex (Delphi 10.4+).
Glyph	TBitmap		Legacy bitmap (TSpeedButton/TBitBtn compatibility). With Kind <> bkCustom the default glyph of the Kind is used.
NumGlyphs	TNumGlyphs	1	Number of images (1-4) in Glyph, side by side: up, disabled, clicked (down), down in a group (exclusive), as in TSpeedButton.
Kind	TBitBtnKind	bkCustom	Predefined button type: sets Caption, ModalResult, Default/Cancel and draws the default glyph (see TStyledBitBtn).

Behavior

Property	Type	Default	Description
Action	TBasicAction	nil	Linked action (caption, enabled, image, group, checked).
AllowAllUp	Boolean	False	With GroupIndex, allows all the buttons of the group to be up.
GroupIndex	Integer	0	Non-zero: the button belongs to a group of mutually exclusive buttons (same parent).
Down	Boolean	False	Pressed state of a grouped (toggle) button.
AutoClick	Boolean	False	When True the button fills itself and fires the click after AutoClickDelay ms (see AutoClick guide). Reset to False after the click.
AutoClickDelay	Integer	5000	Delay in milliseconds before the automatic click (DEFAULT_AUTOCLICK_DELAY).
Cancel	Boolean	False	Cancel button of the form (Esc key).
Cursor	TCursor	crHandPoint	Mouse cursor (DEFAULT_CURSOR).
Default	Boolean	False	Default button of the form (Enter key).
DoubleBuffered	Boolean	True	Double buffered painting (flicker free).
DropDownMenu	TPopupMenu	nil	Popup menu of the split button, shown under the button.
ElevationRequired	Boolean	False	Shows the Windows UAC shield on the button.
Enabled	Boolean	True	Enables/disables the button (Disabled state style).
ModalResult	TModalResult	mrNone	Value assigned to the ModalResult of the parent form on click. It also drives the style of families that map ModalResult to a class (e.g. mrOk = Success in Bootstrap).
ParentDoubleBuffered	Boolean	False	Inherits DoubleBuffered from the parent.
Style	TButtonStyle	bsPushButton	bsPushButton, bsSplitButton (needs DropDownMenu or OnDropDownClick) or bsCommandLink (uses CommandLinkHint).
TabOrder	TTabOrder		Position in the tab order.
TabStop	Boolean	True	The button can be reached with the Tab key.

Notification badge

Property	Type	Default	Description
NotificationBadge	TNotificationBadgeAttributes		Badge (counter or dot) drawn on the button: NotificationCount, CustomText, MaxNotifications, Position, Size, Color, FontColor, FontStyle. See Notification Badge.

Standard VCL properties

Property	Type	Default	Description
Align	TAlign	alNone	Standard VCL property.
Anchors	TAnchors	[akLeft, akTop]	Standard VCL property.
BiDiMode	TBiDiMode		Standard VCL property.
Constraints	TSizeConstraints		Standard VCL property.
DragCursor	TCursor	crDrag	Standard VCL property.
DragKind	TDragKind	dkDrag	Standard VCL property.
DragMode	TDragMode	dmManual	Standard VCL property.
ParentBiDiMode	Boolean	True	Standard VCL property.
ParentShowHint	Boolean	True	Standard VCL property.
PopupMenu	TPopupMenu	nil	Standard VCL property.
ShowHint	Boolean		Standard VCL property.
Visible	Boolean	True	Standard VCL property.
Tag	Integer	0	Standard VCL property.

Public Properties (not published)

Available in code, not shown in the Object Inspector (or published by a sibling component).

Property	Type	Default	Description
ButtonState	TStyledButtonState		Read-only: current visual state (bsmNormal, bsmPressed, bsmSelected, bsmHot, bsmDisabled).
MouseInControl	Boolean		Read-only: True while the mouse is over the button.
StyleApplied	Boolean		True when the attributes of the style have been resolved (lazy resolution).
Render	TStyledButtonRender		The internal renderer that holds all the style logic (advanced use).
RescalingButton	Boolean		True while the button is being rescaled for a DPI change.
Layout	TButtonLayout	blGlyphLeft	Position of the image relative to the caption: blGlyphLeft, blGlyphRight, blGlyphTop, blGlyphBottom.
Margin	Integer	-1	Distance between the border and the image/caption block (-1 = centered).

Public Methods

Method	Description
constructor Create(AOwner: TComponent)	Creates the button with the default style (see RegisterDefaultRenderingStyle).
constructor CreateStyled(AOwner; const AFamily; const AClass; const AAppearance)	Creates the button with the given family, class and appearance.
constructor CreateStyled(AOwner; AFamily; AClass; AAppearance; const ADrawType: TStyledButtonDrawType; const ACursor: TCursor; const AUseCustomDrawType: Boolean)	Creates the button choosing also the shape and the cursor.
class procedure RegisterDefaultRenderingStyle(const ADrawType; const AFamily = DEFAULT_CLASSIC_FAMILY; const AClass = DEFAULT_WINDOWS_CLASS; const AAppearance = DEFAULT_APPEARANCE; const AStyleRadius = DEFAULT_RADIUS; const ACursor = DEFAULT_CURSOR)	Sets the default style used by all the TStyledButton and TStyledBitBtn created afterwards.
procedure SetButtonStyle(const AStyleFamily; const AStyleClass; const AStyleAppearance)	Sets family, class and appearance at once (an empty value keeps the current one); raises an error if the combination does not exist.
procedure SetButtonStyle(const AStyleFamily; const AModalResult: TModalResult)	Sets the family and chooses class and appearance from the ModalResult (as the family defines).
procedure AssignStyleTo(ADestRender: TStyledButtonRender)	Copies the style settings to a render.
procedure AssignStyleTo(ADest: TCustomStyledButton)	Copies the style settings (family, class, appearance, shape, state attributes, badge) to another button.
procedure AssignTo(ADest: TPersistent)	Copies the properties of the button to another button (used by Assign).
function AssignAttributes(const AEnabled; const AImageList; const AImageName; const AImageIndex; const AImageAlignment; const AAction; const AOnClick; const AName): TCustomStyledButton	Sets several attributes in one call and returns the button (for chaining). AImageName exists from Delphi 10.4.
procedure Click	Executes the click: sets the ModalResult of the parent form and fires OnClick (or the drop-down if the mouse is on the arrow of a split button).
procedure ShowDropDownMenu	Shows DropDownMenu under the button.
procedure DoDropDownMenu	Fires OnDropDownClick if assigned, otherwise shows DropDownMenu.
function GetSplitButtonWidth: Integer	Width of the arrow area of a split button.
procedure BeginUpdate / procedure EndUpdate	Suspends / resumes the repaint while changing many properties.
function GetRescalingButton: Boolean / procedure SetRescalingButton	Accessors of RescalingButton.
procedure ReleasePaintBuffer	Releases the shared off-screen bitmap used by the double buffered painting.

Events

Event	Description
OnClick	Button clicked (mouse, keyboard or AutoClick).
OnContextPopup	Context menu requested.
OnDragDrop	Object dropped on the button.
OnDragOver	Object dragged over the button.
OnDropDownClick	Click on the arrow of a split button. When assigned it replaces the automatic display of DropDownMenu (call ShowDropDownMenu yourself if you need it). The Sender is the internal TStyledButtonRender (use Render.OwnerControl or TStyledButtonRender(Sender).OwnerControl to get the button).
OnEndDock	Docking ended.
OnEndDrag	Drag operation ended.
OnEnter	The button received the focus.
OnExit	The button lost the focus.
OnKeyDown	Key pressed while the button has the focus.
OnKeyPress	Character key pressed while the button has the focus.
OnKeyUp	Key released while the button has the focus.
OnMouseActivate	Mouse click is activating the control.
OnMouseDown	Mouse button pressed on the button.
OnMouseEnter	Mouse entered the button.
OnMouseLeave	Mouse left the button.
OnMouseMove	Mouse moved over the button.
OnMouseUp	Mouse button released.
OnStartDock	Docking started.
OnStartDrag	Drag operation started.

RegisterDefaultRenderingStyle

// In the .dpr, after Application.Initialize
TStyledButton.RegisterDefaultRenderingStyle(btRounded, BOOTSTRAP_FAMILY, btn_primary, BOOTSTRAP_NORMAL);

The default style is shared with TStyledBitBtn (same base class TCustomStyledButton), but not with the graphic buttons.

Shadow (StyleShadowSize)

StyleShadowSize is a published property of the component (default -1 = DEFAULT_SHADOW_SIZE, declared in Vcl.ButtonStylesAttributes), like StyleRadius. With -1 the shadow is the one of the style family (the Elevated appearance of Angular-M3 has 2 pixels, 3 on hover, 0 when disabled; Fab has 3, 4 and 0; the other families have none). A value >= 0 replaces it with the same shadow in every state and in any family (0 removes it). The shadow is seen only below the button, inside the area of the control: the face is shorter by the biggest shadow of the five states, the top and the sides are unchanged. It is saved in the form file only if different from -1; values below -1 raise an exception.

The shadow of the family is available in ButtonStyleNormal.ShadowSize, ButtonStyleHot.ShadowSize... (public, not saved property of TStyledButtonAttributes, set by the family: see How to build your custom style). See the section Shadow (StyleShadowSize) of the component page.

See also

• TStyledButton guide
• Styled Buttons: overview and the other button pages: TStyledGraphicButton, TStyledSpeedButton, TStyledBitBtn
• Styled Buttons Examples
• Component Editor, Notification Badge, AutoClick / AutoClickDelay, Angular Material 3 families, How to build your custom style
• Interposer Unit (Vcl.StyledComponentsHooks)