TStyledSpeedButton - Technical Reference

Overview

TStyledSpeedButton is the styled replacement of the VCL TSpeedButton: a graphic button (no focus) with Layout, Margin and Spacing to position the glyph/image and the caption. It derives from TCustomStyledGraphicButton, as TStyledGraphicButton (it is not a descendant of it).

Guide with examples: TStyledSpeedButton.

Class Hierarchy

TGraphicControl
  └─ TCustomStyledGraphicButton
      └─ TStyledSpeedButton

Unit

Vcl.StyledButton

Key Features

• Layout, Margin, Spacing, Glyph, NumGlyphs as TSpeedButton
• Defaults like TSpeedButton: size 23x22, empty caption, Transparent = True, Spacing = 4
• Same style, state, badge, AutoClick and group features of TStyledGraphicButton
• Fewer published properties than TStyledGraphicButton (no ImageAlignment, ImageMargins, DisabledImages, ModalResult, Style, WordWrap...): they remain available in code

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
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).
ShowCaption	Boolean	True	Show or hide the caption (useful for icon-only buttons).
Flat	Boolean	False	Flat appearance (TSpeedButton/TBitBtn compatibility).
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.
Transparent	Boolean	True	Transparent background (default True, as TSpeedButton).

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+).
HotImageIndex	TImageIndex	-1	Image when the mouse is over the button. (published from Delphi 10.4)
HotImageName	TImageName	''	Name version of HotImageIndex (Delphi 10.4+).
ImageIndex	TImageIndex	-1	Image of the normal state. (published from Delphi 10.4)
ImageName	TImageName	''	Name of the image in a name-aware list (Delphi 10.4+); alternative to ImageIndex.
Images	TCustomImageList	nil	Image list used for the button images. (published from Delphi 10.4)
Glyph	TBitmap		Legacy bitmap (TSpeedButton/TBitBtn compatibility). With Kind <> bkCustom the default glyph of the Kind is used.
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).
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.
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	4	Distance in pixels between image and caption.

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.
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).
Cursor	TCursor	crHandPoint	Mouse cursor (DEFAULT_CURSOR).
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.
Enabled	Boolean	True	Enables/disables the button (Disabled state style).

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.
ParentShowHint	Boolean	True	Standard VCL property.
ParentBiDiMode	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
ActiveStyleName	string		Read-only: name of the VCL Style currently applied to the button.
Focused	Boolean		Read-only: True if the button has the keyboard focus (always False for graphic buttons).
ButtonState	TStyledButtonState		Read-only: current visual state (bsmNormal, bsmPressed, bsmSelected, bsmHot, bsmDisabled).
MouseInControl	Boolean		Read-only: True while the mouse is over the button.
Render	TStyledButtonRender		The internal renderer that holds all the style logic (advanced use).
StyleApplied	Boolean		True when the attributes of the style have been resolved (lazy resolution).
RescalingButton	Boolean		True while the button is being rescaled for a DPI change.
CaptionAlignment	TAlignment	taCenter	Horizontal alignment of the caption.
CommandLinkHint	string	''	Second line of text of a command link (Style = bsCommandLink).
ImageAlignment	TImageAlignment	iaLeft	iaLeft, iaRight, iaTop, iaBottom, iaCenter.
DisabledImages	TCustomImageList	nil	Separate image list used in the disabled state.
DropDownMenu	TPopupMenu	nil	Popup menu of the split button, shown under the button.
Kind	TBitBtnKind	bkCustom	Predefined button type: sets Caption, ModalResult, Default/Cancel and draws the default glyph (see TStyledBitBtn).
ImageMargins	TImageMargins	Left = 8	Margins around the image (Left/Top/Right/Bottom); default depends on ImageAlignment.
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).
Style	TButtonStyle	bsPushButton	bsPushButton, bsSplitButton (needs DropDownMenu or OnDropDownClick) or bsCommandLink (uses CommandLinkHint).
WordWrap	Boolean	False	Wraps the caption on more lines.

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 TStyledGraphicButton and TStyledSpeedButton 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: TCustomStyledGraphicButton)	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): TCustomStyledGraphicButton	Sets several attributes in one call and returns the button (for chaining). AImageName exists from Delphi 10.4. In a TStyledSpeedButton/TStyledBitBtn, passing an image list switches the positioning from Layout/Margin/Spacing to ImageAlignment/ImageMargins.
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.

Events

Event	Description
OnClick	Button clicked (mouse, keyboard or AutoClick).
OnDblClick	Button double clicked.
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.
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). (public, not published)

RegisterDefaultRenderingStyle

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

The default style is shared with TStyledGraphicButton (same base class TCustomStyledGraphicButton).

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

• TStyledSpeedButton 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