TStyledToolButton - Technical Reference

Overview

TStyledToolButton is a button component designed for use within TStyledToolbar. It combines the styling capabilities of TStyledGraphicButton with toolbar-specific features.

Class Hierarchy

TGraphicControl
  └─ TCustomStyledGraphicButton
      └─ TStyledGraphicButton
          └─ TStyledToolButton

Unit

Vcl.StyledToolbar

Description

TStyledToolButton is a specialized styled button for toolbars. It inherits from TStyledGraphicButton and adds toolbar-specific properties like IsSeparator, IsDivider, and Style (push button, check, group, dropdown).

Buttons automatically inherit styling from their parent TStyledToolbar, but can override individual properties for custom appearance.

Key Features

• Toolbar integration: Designed to work within TStyledToolbar
• Multiple button styles: Push, Check, Group, Dropdown
• Separators and dividers: Visual grouping of buttons
• Style inheritance: Inherits parent toolbar styles by default
• Per-button override: Can customize individual button appearance
• Notification badge: Badge support for all toolbar buttons
• All TStyledGraphicButton features: Full styling capabilities

Main Properties

Toolbar-Specific

Property	Type	Description
Style	TToolButtonStyle	Button behavior (tbsButton, tbsCheck, tbsDropDown, tbsSeparator, tbsDivider)
IsSeparator	Boolean	Button acts as a separator (thin vertical line)
IsDivider	Boolean	Button acts as a divider (wider vertical bar)
SortOrder	Integer	Display order in toolbar

Button Behavior (inherited)

Property	Type	Description
Down	Boolean	Button pressed state (for tbsCheck style)
GroupIndex	Integer	Button group for radio-button behavior
AllowAllUp	Boolean	Allow all buttons in group to be unpressed

Appearance (inherited)

Property	Type	Description
Caption	TCaption	Button caption
ImageIndex	TImageIndex	Image index in parent toolbar's ImageList
Images	TCustomImageList	Custom ImageList (overrides toolbar's)
Enabled	Boolean	Enable/disable button
Visible	Boolean	Show/hide button

Styling (can override toolbar defaults)

Property	Type	Description
StyleFamily	TStyledButtonFamily	Style family (inherits from toolbar if not set)
StyleClass	TStyledButtonClass	Style class (inherits from toolbar if not set)
StyleAppearance	TStyledButtonAppearance	Appearance (inherits from toolbar if not set)
StyleDrawType	TStyledButtonDrawType	Button shape
StyleRadius	Integer	Corner radius

Badge

Property	Type	Description
NotificationBadge	TNotificationBadgeAttributes	Badge overlay configuration

Button Styles (Style Property)

Value	Description
tbsButton	Normal push button
tbsCheck	Toggle/check button (stays down when clicked)
tbsDropDown	Button with dropdown menu
tbsSeparator	Thin vertical separator line
tbsDivider	Wider vertical divider bar

Usage Examples

Basic Toolbar Button

var
  Btn: TStyledToolButton;
begin
  Btn := TStyledToolButton.Create(Toolbar);
  Btn.Parent := Toolbar;
  Btn.Caption := 'Save';
  Btn.ImageIndex := 5;
  Btn.Hint := 'Save file';
  Btn.ShowHint := True;
  Btn.OnClick := SaveClick;
end;

Check Button (Toggle)

BtnBold := TStyledToolButton.Create(Toolbar);
BtnBold.Parent := Toolbar;
BtnBold.Caption := 'B';
BtnBold.Style := tbsCheck;  // Toggle button
BtnBold.OnClick := BoldClick;

// Check if button is down
if BtnBold.Down then
  ApplyBold;

Button Group (Radio Buttons)

// Left align button
BtnLeft := TStyledToolButton.Create(Toolbar);
BtnLeft.Parent := Toolbar;
BtnLeft.Caption := 'L';
BtnLeft.Style := tbsCheck;
BtnLeft.GroupIndex := 1;
BtnLeft.Down := True;

// Center align button
BtnCenter := TStyledToolButton.Create(Toolbar);
BtnCenter.Parent := Toolbar;
BtnCenter.Caption := 'C';
BtnCenter.Style := tbsCheck;
BtnCenter.GroupIndex := 1;  // Same group

// Right align button
BtnRight := TStyledToolButton.Create(Toolbar);
BtnRight.Parent := Toolbar;
BtnRight.Caption := 'R';
BtnRight.Style := tbsCheck;
BtnRight.GroupIndex := 1;  // Same group
// Only one button in group can be Down

Separator and Divider

// Button
Btn1 := TStyledToolButton.Create(Toolbar);
Btn1.Parent := Toolbar;
Btn1.Caption := 'Cut';

// Thin separator
Sep := TStyledToolButton.Create(Toolbar);
Sep.Parent := Toolbar;
Sep.Style := tbsSeparator;
Sep.Width := 8;

// Button
Btn2 := TStyledToolButton.Create(Toolbar);
Btn2.Parent := Toolbar;
Btn2.Caption := 'Copy';

// Wider divider
Div := TStyledToolButton.Create(Toolbar);
Div.Parent := Toolbar;
Div.Style := tbsDivider;
Div.Width := 12;

// Button
Btn3 := TStyledToolButton.Create(Toolbar);
Btn3.Parent := Toolbar;
Btn3.Caption := 'Paste';

Dropdown Button

Btn := TStyledToolButton.Create(Toolbar);
Btn.Parent := Toolbar;
Btn.Caption := 'File';
Btn.Style := tbsDropDown;
Btn.DropDownMenu := FilePopupMenu;
// Click shows dropdown menu

Button with Custom Style (Override Toolbar)

// Toolbar uses Bootstrap Secondary
Toolbar := TStyledToolbar.CreateStyled(Self,
  BOOTSTRAP_FAMILY,
  btn_secondary,
  BOOTSTRAP_NORMAL);

// Normal button (uses toolbar style)
BtnNormal := TStyledToolButton.Create(Toolbar);
BtnNormal.Parent := Toolbar;
BtnNormal.Caption := 'Normal';

// Important button (overrides with Primary style)
BtnImportant := TStyledToolButton.Create(Toolbar);
BtnImportant.Parent := Toolbar;
BtnImportant.Caption := 'Save';
BtnImportant.StyleClass := btn_primary;  // Override!
BtnImportant.StyleAppearance := BOOTSTRAP_NORMAL;

Button with Notification Badge

BtnMessages := TStyledToolButton.Create(Toolbar);
BtnMessages.Parent := Toolbar;
BtnMessages.Caption := 'Messages';
BtnMessages.ImageIndex := 10;
BtnMessages.NotificationBadge.Visible := True;
BtnMessages.NotificationBadge.BadgeText := '5';
BtnMessages.NotificationBadge.BadgeColor := clRed;
BtnMessages.NotificationBadge.BadgeTextColor := clWhite;

SortOrder for Custom Positioning

// Create buttons in any order
Btn3 := TStyledToolButton.Create(Toolbar);
Btn3.SortOrder := 300;
Btn3.Caption := 'Third';

Btn1 := TStyledToolButton.Create(Toolbar);
Btn1.SortOrder := 100;
Btn1.Caption := 'First';

Btn2 := TStyledToolButton.Create(Toolbar);
Btn2.SortOrder := 200;
Btn2.Caption := 'Second';

// They will display in SortOrder: First, Second, Third

Important Notes

• Parent Must Be TStyledToolbar: Designed for use in TStyledToolbar
• Size From Toolbar: Width and Height come from toolbar's ButtonWidth/ButtonHeight
• Caption Visibility: Controlled by toolbar's ShowCaptions property
• Style Inheritance: Inherits toolbar's style unless explicitly overridden
• No Focus: Like TStyledGraphicButton, cannot receive keyboard focus

See Also

• TStyledToolbar - Toolbar container
• TStyledGraphicButton - Base graphic button