TStyledButton - Technical Reference

Overview

TStyledButton is a windowed button control (TWinControl) that provides styled rendering with full keyboard focus support. It's a direct replacement for the standard VCL TButton with enhanced styling capabilities.

Class Hierarchy

TWinControl
  └─ TCustomStyledButton
      └─ TStyledButton

Unit

Vcl.StyledButton

Description

TStyledButton is a windowed control that provides all the functionality of TStyledGraphicButton plus focus management, tab-stop support, and keyboard interaction. It's designed as a drop-in replacement for TButton while offering extensive styling options not available in standard VCL buttons.

Like TStyledGraphicButton, rendering is handled by an internal TStyledButtonRender instance for consistency across the component library.

Key Features

• Full focus support: TabStop, keyboard navigation, accelerator keys
• Five button states: Normal, Pressed, Selected, Hot (hover), Disabled
• Multiple style families: Classic, Bootstrap, Angular-Light, Angular-Dark, Basic-Color, SVG-Color
• Custom shapes: Rectangle, RoundedRect, Rounded (full-round), Ellipse
• Button modes: Normal, Default, Cancel, Split Button, Command Link
• Image support: ImageList with state-specific images
• Notification badge: Optional badge overlay
• Auto-click: Automatic click after delay (for countdown dialogs)
• 100% TButton compatible: Drop-in replacement with enhanced features

Main Properties

Styling Properties

Property	Type	Description
StyleFamily	TStyledButtonFamily	Style family (Classic, Bootstrap, Angular-Light, Angular-Dark, Basic-Color, SVG-Color)
StyleClass	TStyledButtonClass	Predefined style class within the family
StyleAppearance	TStyledButtonAppearance	Visual variant (Normal, Outline, Flat, Raised, etc.)
StyleDrawType	TStyledButtonDrawType	Button shape (btRect, btRoundRect, btRounded, btEllipse)
StyleRadius	Integer	Corner radius for btRoundRect (default: 6)
StyleRoundedCorners	TRoundedCorners	Which corners to round

Button Behavior

Property	Type	Description
Default	Boolean	Default button (activated by Enter key)
Cancel	Boolean	Cancel button (activated by Escape key)
ModalResult	TModalResult	Modal result for forms (mrOk, mrCancel, etc.)
Style	TButtonStyle	Button style (bsButton, bsSplitButton, bsCommandLink)
Down	Boolean	Button pressed state (for toggle buttons)
GroupIndex	Integer	Button group for radio-button behavior
AllowAllUp	Boolean	Allow all buttons in group to be unpressed

Focus and Keyboard

Property	Type	Description
TabStop	Boolean	Can receive focus via Tab key (default: True)
TabOrder	Integer	Order in tab sequence
ElevationRequired	Boolean	Show administrator shield icon

Appearance Properties

Property	Type	Description
Caption	TCaption	Button text
CaptionAlignment	TAlignment	Caption alignment (taLeftJustify, taCenter, taRightJustify)
ShowCaption	Boolean	Show/hide caption (default: True)
CommandLinkHint	String	Hint text for command link style
WordWrap	Boolean	Enable text word-wrapping
Flat	Boolean	Flat button appearance

Image Properties

Property	Type	Description
Images	TCustomImageList	ImageList for button images
ImageIndex	TImageIndex	Default image index
ImageName	TImageName	Image name (Delphi 10.4+)
ImageAlignment	TImageAlignment	Image position (iaLeft, iaRight, iaTop, iaBottom, iaCenter)
ImageMargins	TImageMargins	Margins around the image
HotImageIndex	TImageIndex	Image when mouse hovers
PressedImageIndex	TImageIndex	Image when button is pressed
SelectedImageIndex	TImageIndex	Image when button is selected
DisabledImageIndex	TImageIndex	Image when button is disabled
StylusHotImageIndex	TImageIndex	Image for stylus/touch hover

Split Button

Property	Type	Description
DropDownMenu	TPopupMenu	Popup menu for split button

Auto-Click Feature

Property	Type	Description
AutoClick	Boolean	Enable automatic click after delay
AutoClickDelay	Integer	Delay in milliseconds before auto-click (default: 5000)

Notification Badge

Property	Type	Description
NotificationBadge	TNotificationBadgeAttributes	Badge configuration

Compatibility

Property	Type	Description
AsVCLComponent	Boolean	Switch to VCL-style rendering
Kind	TBitBtnKind	Button kind (bkOK, bkCancel, bkYes, bkNo, etc.) for TBitBtn compatibility

Main Methods

RegisterDefaultRenderingStyle (Class Method)

Sets the default rendering style for all TStyledButton instances.

class procedure RegisterDefaultRenderingStyle(
  const ADrawType: TStyledButtonDrawType;
  const AFamily: TStyledButtonFamily = DEFAULT_CLASSIC_FAMILY;
  const AClass: TStyledButtonClass = DEFAULT_WINDOWS_CLASS;
  const AAppearance: TStyledButtonAppearance = DEFAULT_APPEARANCE;
  const AStyleRadius: Integer = DEFAULT_RADIUS); virtual;

Click

Programmatically clicks the button.

procedure Click; override;

Events

Event	Description
OnClick	Triggered when button is clicked
OnEnter	Button receives focus
OnExit	Button loses focus
OnKeyDown	Key pressed while button has focus
OnKeyUp	Key released while button has focus
OnKeyPress	Character key pressed
OnMouseEnter	Mouse enters button area
OnMouseLeave	Mouse leaves button area
OnDropDownClick	Split button dropdown clicked (before menu shown)

Usage Examples

Basic Button (TButton Replacement)

var
  Btn: TStyledButton;
begin
  Btn := TStyledButton.CreateStyled(Self,
    BOOTSTRAP_FAMILY,
    btn_primary,
    BOOTSTRAP_NORMAL);
  Btn.Parent := Self;
  Btn.Caption := 'OK';
  Btn.ModalResult := mrOk;
  Btn.Default := True;  // Activated by Enter key
  Btn.OnClick := OKButtonClick;
end;

Split Button with Menu

Btn := TStyledButton.CreateStyled(Self,
  BOOTSTRAP_FAMILY,
  btn_success,
  BOOTSTRAP_NORMAL);
Btn.Parent := Self;
Btn.Caption := 'Save';
Btn.Style := bsSplitButton;
Btn.DropDownMenu := SaveOptionsMenu;
Btn.OnClick := SaveClick;  // Main button click

Command Link Button

Btn := TStyledButton.CreateStyled(Self,
  BOOTSTRAP_FAMILY,
  btn_primary,
  BOOTSTRAP_NORMAL);
Btn.Parent := Self;
Btn.Caption := 'Continue';
Btn.CommandLinkHint := 'Proceed to the next step';
Btn.Style := bsCommandLink;
Btn.ImageIndex := 0;
Btn.ImageAlignment := iaLeft;

Button with Auto-Click

Btn := TStyledButton.CreateStyled(Self,
  BOOTSTRAP_FAMILY,
  btn_primary,
  BOOTSTRAP_NORMAL);
Btn.Parent := Self;
Btn.Caption := 'Close (5)';
Btn.ModalResult := mrOk;
Btn.AutoClick := True;
Btn.AutoClickDelay := 5000;  // 5 seconds
// Update caption in timer to show countdown

Default Button Styling by ModalResult

// Buttons automatically style based on ModalResult
BtnOK := TStyledButton.Create(Self);
BtnOK.ModalResult := mrOk;  // Will use Success/Primary colors

BtnCancel := TStyledButton.Create(Self);
BtnCancel.ModalResult := mrCancel;  // Will use Warning colors

BtnNo := TStyledButton.Create(Self);
BtnNo.ModalResult := mrNo;  // Will use Danger colors

Toggle Button

BtnBold := TStyledButton.CreateStyled(Self,
  BOOTSTRAP_FAMILY,
  btn_secondary,
  BOOTSTRAP_NORMAL);
BtnBold.Caption := 'B';
BtnBold.GroupIndex := 1;
BtnBold.AllowAllUp := True;
BtnBold.Down := False;
// Check Down property to determine state

Elevation Required (UAC Shield)

Btn := TStyledButton.CreateStyled(Self,
  BOOTSTRAP_FAMILY,
  btn_primary,
  BOOTSTRAP_NORMAL);
Btn.Caption := 'Settings';
Btn.ElevationRequired := True;  // Shows Windows UAC shield icon

Setting Default Styles Globally

// In project DPR file, after Application.Initialize
uses
  Vcl.StyledButton, Vcl.ButtonStylesAttributes;

begin
  Application.Initialize;

  // All TStyledButton instances will use these defaults
  TStyledButton.RegisterDefaultRenderingStyle(
    btRounded,
    BOOTSTRAP_FAMILY,
    btn_primary,
    BOOTSTRAP_NORMAL
  );

  Application.CreateForm(TMainForm, MainForm);
  Application.Run;
end.

Replacing Standard TButton

Method 1: Direct Replacement

// Old code:
// var
//   Button1: TButton;

// New code:
var
  Button1: TStyledButton;

// All TButton properties and events are compatible!

Method 2: Using Interposer Unit

Add to project:

uses
  Vcl.StyledComponentsHooks;  // Automatically replaces TButton with TStyledButton

Important Notes

• Focus Support: Unlike TStyledGraphicButton, this control can receive focus
• Keyboard Accelerators: Supports Alt+Key accelerators (underlined characters in caption)
• Default/Cancel: Can be designated as form's default or cancel button
• ModalResult: Automatically closes parent dialog with specified result
• TabStop: Participates in tab order navigation
• DPI Aware: Automatically scales with DPI changes
• Thread-Safe: Can be safely created and manipulated from UI thread only

See Also

• TStyledGraphicButton - Lightweight graphic button
• TStyledBitBtn - TBitBtn-compatible styled button
• TStyledSpeedButton - TSpeedButton-compatible styled button