TStyledGraphicButton - Technical Reference

Overview

TStyledGraphicButton is a pure graphic button control that provides styled rendering without focus or tab-stop capabilities. It's ideal for use in visual lists, toolbars, and scenarios where a lightweight button control is needed.

Class Hierarchy

TGraphicControl
  └─ TCustomStyledGraphicButton
      └─ TStyledGraphicButton

Unit

Vcl.StyledButton

Description

TStyledGraphicButton is a non-windowed control (derived from TGraphicControl) that renders buttons with custom styles. Unlike windowed controls, it cannot receive keyboard focus, making it perfect for toolbars, lists, and decorative UI elements where focus management isn't required.

All rendering is handled by an internal TStyledButtonRender instance, which provides consistent styling across all styled components in the library.

Key Features

• 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
• Image support: ImageList with state-specific images (Normal, Hot, Pressed, Selected, Disabled)
• Notification badge: Optional badge overlay with custom text and colors
• VCL Styles integration: Can switch between styled and VCL rendering
• GDI+ rendering: Smooth antialiased rendering independent of VCL Styles

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 ([rcTopLeft, rcTopRight, rcBottomLeft, rcBottomRight])

Appearance Properties

Property	Type	Description
Caption	TCaption	Button text
CaptionAlignment	TAlignment	Caption alignment (taLeftJustify, taCenter, taRightJustify)
ShowCaption	Boolean	Show/hide caption (default: True)
WordWrap	Boolean	Enable text word-wrapping
Flat	Boolean	Flat button appearance
Transparent	Boolean	Transparent background (for graphic buttons only)

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/down
DisabledImageIndex	TImageIndex	Image when button is disabled
DisabledImages	TCustomImageList	Separate ImageList for disabled state

State Properties

Property	Type	Description
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
ModalResult	TModalResult	Modal result value for forms

Custom Attributes

Property	Type	Description
ButtonStyleNormal	TStyledButtonAttributes	Custom attributes for normal state
ButtonStyleHot	TStyledButtonAttributes	Custom attributes for hot/hover state
ButtonStylePressed	TStyledButtonAttributes	Custom attributes for pressed state
ButtonStyleSelected	TStyledButtonAttributes	Custom attributes for selected state
ButtonStyleDisabled	TStyledButtonAttributes	Custom attributes for disabled state

Notification Badge

Property	Type	Description
NotificationBadge	TNotificationBadgeAttributes	Badge configuration (text, color, shape, visibility)

Compatibility

Property	Type	Description
AsVCLComponent	Boolean	Switch to VCL-style rendering (uses VCL Styles if active)
Glyph	TBitmap	Legacy bitmap glyph (for TSpeedButton compatibility)
NumGlyphs	TNumGlyphs	Number of glyphs in bitmap (1-4)

Main Methods

RegisterDefaultRenderingStyle (Class Method)

Sets the default rendering style for all TStyledGraphicButton instances created afterwards.

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;
  const ACursor: TCursor = DEFAULT_CURSOR); virtual;

Example:

// Set all buttons to Bootstrap Primary with rounded corners
TStyledGraphicButton.RegisterDefaultRenderingStyle(
  btRounded,
  BOOTSTRAP_FAMILY,
  btn_primary,
  BOOTSTRAP_NORMAL
);

Events

Event	Description
OnClick	Triggered when button is clicked
OnMouseEnter	Mouse enters button area
OnMouseLeave	Mouse leaves button area
OnMouseDown	Mouse button pressed
OnMouseUp	Mouse button released
OnMouseMove	Mouse moves over button

Usage Examples

Basic Button

var
  Btn: TStyledGraphicButton;
begin
  Btn := TStyledGraphicButton.CreateStyled(Self,
    BOOTSTRAP_FAMILY,
    btn_primary,
    BOOTSTRAP_NORMAL);
  Btn.Parent := Self;
  Btn.Caption := 'Click Me';
  Btn.StyleDrawType := btRounded;
  Btn.OnClick := ButtonClick;
end;

Button with Image

Btn := TStyledGraphicButton.CreateStyled(Self,
  BOOTSTRAP_FAMILY,
  btn_success,
  BOOTSTRAP_NORMAL);
Btn.Parent := Self;
Btn.Caption := 'Save';
Btn.Images := ImageList1;
Btn.ImageIndex := 0;
Btn.ImageAlignment := iaLeft;

Toggle Button

Btn := TStyledGraphicButton.CreateStyled(Self,
  BOOTSTRAP_FAMILY,
  btn_secondary,
  BOOTSTRAP_NORMAL);
Btn.Parent := Self;
Btn.Caption := 'Bold';
Btn.AllowAllUp := True;
Btn.GroupIndex := 1;  // 0 = no grouping
Btn.Down := False;     // Initial state

Button with Notification Badge

Btn := TStyledGraphicButton.CreateStyled(Self,
  BOOTSTRAP_FAMILY,
  btn_primary,
  BOOTSTRAP_NORMAL);
Btn.Parent := Self;
Btn.Caption := 'Messages';
Btn.NotificationBadge.Visible := True;
Btn.NotificationBadge.BadgeText := '5';
Btn.NotificationBadge.BadgeColor := clRed;

Custom Styled Button

Btn := TStyledGraphicButton.CreateStyled(Self,
  BOOTSTRAP_FAMILY,
  btn_secondary,
  BOOTSTRAP_NORMAL);
Btn.Parent := Self;
Btn.Caption := 'Custom';
Btn.ButtonStyleNormal.ButtonColor := $00FF8800;  // Orange
Btn.ButtonStyleNormal.BorderColor := clBlack;
Btn.ButtonStyleNormal.FontColor := clWhite;
Btn.ButtonStyleHot.ButtonColor := $00CC6600;     // Darker on hover

State-Specific Images

Btn := TStyledGraphicButton.Create(Self);
Btn.Images := ImageList1;
Btn.ImageIndex := 0;           // Normal state
Btn.HotImageIndex := 1;        // Hover state
Btn.PressedImageIndex := 2;    // Pressed state
Btn.DisabledImageIndex := 3;   // Disabled state

Important Notes

• No Focus: TStyledGraphicButton cannot receive keyboard focus (no TabStop)
• Lightweight: Uses less resources than windowed controls
• Use in Lists: Perfect for TControlList, virtual lists, and custom-drawn lists
• GDI+ Required: Requires Windows XP SP2+ for antialiased rendering
• DPI Aware: Automatically scales with DPI changes

See Also

• TStyledButton - Windowed button with focus support
• TStyledSpeedButton - TSpeedButton-compatible styled button
• TStyledToolButton - Toolbar button component