TStyledBitBtn - Technical Reference

Overview

TStyledBitBtn is the styled replacement of the VCL TBitBtn: a windowed button (focus, Default, Cancel, ModalResult) with Kind, Glyph, NumGlyphs, Layout, Margin and Spacing. It derives from TCustomStyledButton, as TStyledButton (it is not a descendant of it).

Guide with examples: TStyledBitBtn.

Class Hierarchy

TCustomControl
  └─ TCustomStyledButton
      └─ TStyledBitBtn

Unit

Vcl.StyledButton

Key Features

• Kind (bkOK, bkCancel, bkYes, bkNo, bkAbort, bkRetry, bkIgnore, bkAll, bkClose, bkHelp, bkCustom): caption, ModalResult, Default/Cancel and glyph
• Layout, Margin, Spacing (default 4), Glyph, NumGlyphs as TBitBtn
• Same style, state, badge, AutoClick features of TStyledButton
• Style is the TBitBtn compatibility property (bsAutoDetect), without effect; split button, command link, Flat, DisabledImages, ElevationRequired are available only in code (not published)

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).
Font	TFont		Caption font. The font color is overridden by the style unless the attributes are customized.
WordWrap	Boolean	False	Wraps the caption on more lines.
ParentFont	Boolean	True	Inherits the font of the parent.

Images and glyph

Property	Type	Default	Description
DisabledImageIndex	TImageIndex	-1	Image when the button is disabled. (published from Delphi 10.4)
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.
Kind	TBitBtnKind	bkCustom	Predefined button type: sets Caption, ModalResult, Default/Cancel and draws the default glyph (see TStyledBitBtn).
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.
Spacing	Integer	4	Distance in pixels between image and caption.
PressedImageIndex	TImageIndex	-1	Image when the button is pressed.
SelectedImageIndex	TImageIndex	-1	Image when the button is selected (focused).
PressedImageName	TImageName	''	Name version of PressedImageIndex (Delphi 10.4+).
SelectedImageName	TImageName	''	Name version of SelectedImageIndex (Delphi 10.4+).

Behavior

Property	Type	Default	Description
Action	TBasicAction	nil	Linked action (caption, enabled, image, group, checked).
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).
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).
Style	Vcl.Buttons.TButtonStyle	bsAutoDetect	Compatibility with the TBitBtn property: it has no effect on the rendering (no split button or command link in TStyledBitBtn).
TabOrder	TTabOrder		Position in the tab order.
TabStop	Boolean	True	The button can be reached with the Tab key.
ParentDoubleBuffered	Boolean		Inherits DoubleBuffered from the parent.

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.
Tag	Integer	0	Standard VCL property.
Visible	Boolean	True	Standard VCL property.
ParentBiDiMode	Boolean	True	Standard VCL property.
ParentCustomHint	Boolean	True	Standard VCL property.
ParentShowHint	Boolean	True	Standard VCL property.
PopupMenu	TPopupMenu	nil	Standard VCL property.
ShowHint	Boolean		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.
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.
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.
ElevationRequired	Boolean	False	Shows the Windows UAC shield on the button.
Flat	Boolean	False	Flat appearance (TSpeedButton/TBitBtn compatibility).
StylusHotImageIndex	TImageIndex	-1	Image for stylus/touch hover.
StylusHotImageName	TImageName	''	Name version of StylusHotImageIndex (Delphi 10.4+).
ImageMargins	TImageMargins	Left = 8	Margins around the image (Left/Top/Right/Bottom); default depends on ImageAlignment.
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.

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. 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.
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.
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.
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.
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)
OnKeyUp	Key released while the button has the focus. (public, not published)

Kind

Setting Kind to a value different from bkCustom (not when loading a form that already has a caption):

Kind	Caption	ModalResult	Default	Cancel
bkOK	OK	mrOk	True	False
bkCancel	Cancel	mrCancel	False	True
bkYes	Yes	mrYes	True	False
bkNo	No	mrNo	False	True
bkAbort	Abort	mrAbort	False	False
bkRetry	Retry	mrRetry	False	False
bkIgnore	Ignore	mrIgnore	False	False
bkAll	All	mrAll	False	False
bkClose	Close	mrNone	False	False
bkHelp	Help	mrNone	False	False
bkCustom	(unchanged)	(unchanged)	(unchanged)	(unchanged)

The default glyph of the Kind is drawn when no Glyph is assigned. If you later change ModalResult, Default or Cancel so that they no longer match the Kind, Kind reads back as bkCustom (changing the Caption does not affect it).

RegisterDefaultRenderingStyle

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

The default style is shared with TStyledButton (same base class TCustomStyledButton).

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

• TStyledBitBtn guide
• TStyledBitBtn Demo
• 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