TStyledSpeedButton - Technical Reference

Overview

TStyledSpeedButton is a styled button component designed for backward compatibility with TSpeedButton. It extends TStyledGraphicButton with Layout, Margin, and Spacing properties for legacy glyph positioning.

Class Hierarchy

TGraphicControl
  └─ TCustomStyledGraphicButton
      └─ TStyledGraphicButton
          └─ TStyledSpeedButton

Unit

Vcl.StyledButton

Description

TStyledSpeedButton provides full compatibility with the standard VCL TSpeedButton while adding modern styling capabilities. It includes Layout, Margin, and Spacing properties that control how the glyph and caption are positioned, matching the behavior of classic TSpeedButton.

This component is recommended when migrating existing code that uses TSpeedButton's glyph positioning properties.

Key Features

• TSpeedButton compatibility: Layout, Margin, Spacing properties
• Glyph support: Bitmap glyph with NumGlyphs for multi-state images
• All TStyledGraphicButton features: Styling, ImageList, states, etc.
• Group behavior: GroupIndex, AllowAllUp, Down properties
• Lightweight: Non-windowed control (no focus)

Additional Properties (vs TStyledGraphicButton)

Glyph Layout Properties

Property	Type	Description
Layout	TButtonLayout	Position of glyph relative to caption (blGlyphLeft, blGlyphRight, blGlyphTop, blGlyphBottom)
Margin	Integer	Margin between button edge and glyph+caption (default: -1 = auto)
Spacing	Integer	Space between glyph and caption (default: 0)
Glyph	TBitmap	Bitmap glyph (legacy, not DPI-aware)
NumGlyphs	TNumGlyphs	Number of images in glyph bitmap (1-4) for different states

NumGlyphs Behavior

The NumGlyphs property determines how many states are stored in the glyph bitmap:

• 1: Single image used for all states
• 2: Two images: Normal and Disabled
• 3: Three images: Normal, Disabled, and Down (pressed)
• 4: Four images: Normal, Disabled, Down (pressed), and Hot (mouse over)

Images are arranged horizontally in the bitmap.

Usage Examples

Basic SpeedButton Replacement

var
  Btn: TStyledSpeedButton;
begin
  Btn := TStyledSpeedButton.CreateStyled(Self,
    BOOTSTRAP_FAMILY,
    btn_secondary,
    BOOTSTRAP_NORMAL);
  Btn.Parent := Self;
  Btn.Caption := 'Bold';
  Btn.Glyph.LoadFromFile('bold.bmp');
  Btn.Layout := blGlyphLeft;
  Btn.Margin := 4;
  Btn.Spacing := 2;
end;

Using ImageList (Recommended)

// Modern approach using ImageList instead of Glyph
Btn := TStyledSpeedButton.CreateStyled(Self,
  BOOTSTRAP_FAMILY,
  btn_primary,
  BOOTSTRAP_NORMAL);
Btn.Parent := Self;
Btn.Caption := 'Save';
Btn.Images := ImageList1;
Btn.ImageIndex := 0;
Btn.ImageAlignment := iaLeft;  // Instead of Layout
// Spacing still works with ImageList
Btn.Spacing := 4;

Toggle Button Group

// Create mutually exclusive button group
BtnLeft := TStyledSpeedButton.CreateStyled(Self,
  BOOTSTRAP_FAMILY, btn_secondary, BOOTSTRAP_NORMAL);
BtnLeft.Caption := 'Left';
BtnLeft.GroupIndex := 1;
BtnLeft.Down := True;

BtnCenter := TStyledSpeedButton.CreateStyled(Self,
  BOOTSTRAP_FAMILY, btn_secondary, BOOTSTRAP_NORMAL);
BtnCenter.Caption := 'Center';
BtnCenter.GroupIndex := 1;

BtnRight := TStyledSpeedButton.CreateStyled(Self,
  BOOTSTRAP_FAMILY, btn_secondary, BOOTSTRAP_NORMAL);
BtnRight.Caption := 'Right';
BtnRight.GroupIndex := 1;
// Only one button in group can be Down at a time

Multi-State Glyph

Btn := TStyledSpeedButton.CreateStyled(Self,
  BOOTSTRAP_FAMILY, btn_secondary, BOOTSTRAP_NORMAL);
Btn.Glyph.LoadFromFile('button_states.bmp');  // 4 images horizontally
Btn.NumGlyphs := 4;  // Normal, Disabled, Down, Hot
Btn.Caption := 'Toggle';

Migration from TSpeedButton

// Old code:
// var
//   SpeedButton1: TSpeedButton;

// New code:
var
  SpeedButton1: TStyledSpeedButton;

// All TSpeedButton properties are compatible!
// Plus you get modern styling options:
SpeedButton1.StyleFamily := BOOTSTRAP_FAMILY;
SpeedButton1.StyleClass := btn_primary;
SpeedButton1.StyleDrawType := btRounded;

Important Notes

• Glyph vs ImageList: Prefer ImageList for DPI-aware scaling
• No Focus: Like TSpeedButton, this control cannot receive keyboard focus
• GroupIndex: Use non-zero values for grouped/radio button behavior
• Legacy Support: Maintain compatibility while gaining modern styling

See Also

• TStyledGraphicButton - Base graphic button
• TStyledBitBtn - TBitBtn-compatible styled button
• TStyledButton - Windowed button with focus support