TStyledGraphicButton - Technical Reference

Overview

TStyledGraphicButton is a "pure" graphic button (TGraphicControl): no window handle, no focus, no tab stop. Rendering is delegated to an internal TStyledButtonRender, shared by all the styled buttons.

Guide with examples: TStyledGraphicButton.

Class Hierarchy

TGraphicControl
  └─ TCustomStyledGraphicButton
      └─ TStyledGraphicButton

Unit

Vcl.StyledButton

Key Features

• No window handle: lightweight, usable in TControlList, toolbars, floating buttons
• 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), Glyph; Action support
• Toggle buttons (GroupIndex, AllowAllUp, Down), split button, command link, AutoClick, NotificationBadge
• AsVCLComponent / StyleName to follow the VCL Styles

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.
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.
StyleElements	TStyleElements		Standard VCL property: with seClient the Classic family follows the active VCL Style. See AsVCLComponent.
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
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	False	Transparent background (graphic buttons only).
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).
Flat	Boolean	False	Flat appearance (TSpeedButton/TBitBtn compatibility).
WordWrap	Boolean	False	Wraps the caption on more lines.

Images and glyph

Property	Type	Default	Description
ImageAlignment	TImageAlignment	iaLeft	iaLeft, iaRight, iaTop, iaBottom, iaCenter.
DisabledImageIndex	TImageIndex	-1	Image when the button is disabled.
DisabledImages	TCustomImageList	nil	Separate image list used in the disabled state.
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.
HotImageIndex	TImageIndex	-1	Image when the mouse is over the button.
Images	TCustomImageList	nil	Image list used for the button images.
ImageIndex	TImageIndex	-1	Image of the normal state.
Kind	TBitBtnKind	bkCustom	Predefined button type: sets Caption, ModalResult, Default/Cancel and draws the default glyph (see TStyledBitBtn).
PressedImageIndex	TImageIndex	-1	Image when the button is pressed.
SelectedImageIndex	TImageIndex	-1	Image when the button is selected (focused).
DisabledImageName	TImageName	''	Name version of DisabledImageIndex (Delphi 10.4+).
HotImageName	TImageName	''	Name version of HotImageIndex (Delphi 10.4+).
ImageName	TImageName	''	Name of the image in a name-aware list (Delphi 10.4+); alternative to ImageIndex.
PressedImageName	TImageName	''	Name version of PressedImageIndex (Delphi 10.4+).
SelectedImageName	TImageName	''	Name version of SelectedImageIndex (Delphi 10.4+).
ImageMargins	TImageMargins	Left = 8	Margins around the image (Left/Top/Right/Bottom); default depends on ImageAlignment.

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).
DropDownMenu	TPopupMenu	nil	Popup menu of the split button, shown under the button.
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).

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.
Constraints	TSizeConstraints		Standard VCL property.
DragCursor	TCursor	crDrag	Standard VCL property.
DragKind	TDragKind	dkDrag	Standard VCL property.
DragMode	TDragMode	dmManual	Standard VCL property.
PopUpMenu	TPopupMenu	nil	Standard VCL property.
ParentShowHint	Boolean	True	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
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.
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).
Spacing	Integer	0	Distance in pixels between image and caption.

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.
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
OnContextPopup	Context menu requested.
OnDragDrop	Object dropped on the button.
OnDragOver	Object dragged over the button.
OnEndDock	Docking ended.
OnEndDrag	Drag operation ended.
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.
OnGesture	Touch gesture received.
OnStartDock	Docking started.
OnStartDrag	Drag operation started.
OnClick	Button clicked (mouse, keyboard or AutoClick).
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).

RegisterDefaultRenderingStyle

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

The default style is shared with TStyledSpeedButton (same base class TCustomStyledGraphicButton), but not with TStyledButton and TStyledBitBtn.

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

• TStyledGraphicButton 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
• TStyledToolButton