TStyledButtonGroup - Technical Reference

Overview

TStyledButtonGroup extends TButtonGroup with styled button rendering, per-item styles, caption/image alignment and notification badges. This page lists the members added by the library to TStyledButtonGroup, TStyledGrpButtonItem and TStyledGrpButtonItems; the members inherited from the VCL are summarized briefly. For the usage see TStyledButtonGroup.

Class Hierarchy

TButtonGroup            (Vcl.ButtonGroup)
  └─ TStyledButtonGroup

TGrpButtonItem          (Vcl.ButtonGroup, a TCollectionItem)
  └─ TStyledGrpButtonItem

TGrpButtonItems
  └─ TStyledGrpButtonItems

Unit

Vcl.StyledButtonGroup

Description

TStyledButtonGroup maintains the compatibility with TButtonGroup (Items, ItemIndex, ButtonOptions, ButtonWidth, ButtonHeight, Images, the VCL events) and draws every button with the Styled Components renderer. The group has a style (StyleFamily/StyleClass/StyleAppearance, shape and radius) shared by its buttons; each item can override it. The class is registered for Win32 and Win64 and has the Component Editor Styled ButtonGroup Editor... (see Component Editor).

Key Features

• Full TButtonGroup compatibility
• Group style and per-item style
• Caption alignment (left, center, right) and image alignment (left, right, top, bottom, center), with Spacing and ImageMargins
• Flat appearance
• Notification badges through an event
• Follows the VCL Style with the Classic family (AsVCLComponent)

Published properties (Object Inspector)

Items and layout

Property	Type	Default	Description
Items	TStyledGrpButtonItems	empty	Collection of the buttons (TStyledGrpButtonItem); Items.Add returns a TStyledGrpButtonItem, Items[Index] returns the VCL type TGrpButtonItem
CaptionAlignment	TAlignment	taLeftJustify	Alignment of the caption: taLeftJustify, taCenter, taRightJustify (used when gboShowCaptions is in ButtonOptions)
ImageAlignment	TImageAlignment	iaLeft	Position of the image: iaLeft, iaRight, iaTop, iaBottom, iaCenter
ImageMargins	TImageMargins	Left=2	Margins around the image; stored only when changed
Spacing	Integer	4	Distance between the image and the caption
Flat	Boolean	False	Flat buttons: the face of the Normal and Disabled button is not drawn
ButtonsCursor	TCursor	crHandPoint	Cursor when the mouse is over a button
Cursor	TCursor	crDefault	Cursor of the group outside the buttons

Style

Property	Type	Default	Description
StyleFamily	TStyledButtonFamily	Classic	Style family of the buttons
StyleClass	TStyledButtonClass	Windows	Style class of the buttons
StyleAppearance	TStyledButtonAppearance	Normal	Appearance of the buttons
StyleDrawType	TStyledButtonDrawType	btRoundRect	Shape (btRect, btRoundRect, btRounded, btEllipse)
StyleRadius	Integer	6	Corner radius; must be greater than zero
StyleShadowSize	Integer	-1	Shadow of the buttons in pixels, the same in every state (-1 = the one of the style family, 0 = none); values below -1 raise an exception
StyleRoundedCorners	TRoundedCorners	all four	Which corners are rounded
ButtonStyleNormal, ButtonStylePressed, ButtonStyleSelected, ButtonStyleHot, ButtonStyleDisabled	TStyledButtonAttributes	from the style	Colors, border and font of each state, shared by the items that have the style of the group

Setting StyleFamily to a family that is not registered raises EStyledAttributesException (while streaming a form it falls back to Classic).

Events

Event	Type	Description
OnGetNotificationBadgeInfo	TGetButtonGroupBadgeInfo	Supplies the badge of an item: (const AButtonItemIndex: Integer; var ABadgeContent: string; var ASize: TNotificationBadgeSize; var APosition: TNotificationBadgePosition; var AColor, AFontColor: TColor; var AFontStyle: TFontStyles). The badge is drawn if ABadgeContent is not empty (defaults: nbsNormal, nbpTopRight, bold)

Inherited from TButtonGroup (summary)

ButtonOptions (gboAllowReorder, gboFullSize, gboGroupStyle, gboShowCaptions), ButtonWidth, ButtonHeight, ItemIndex, Images, Align, Anchors, Color, Font, Enabled, Visible, StyleElements, TabOrder, TabStop, PopupMenu, ShowHint, bevel/border properties, and the events OnButtonClicked, OnBeforeDrawButton, OnDrawButton, OnAfterDrawButton, OnDrawIcon, OnHotButton, OnReorderButton, OnClick, OnEnter, OnExit... See the Embarcadero documentation of Vcl.ButtonGroup.TButtonGroup.

Public members

Member	Description
property AsVCLComponent: Boolean	True when the group follows the VCL Style (Classic family, seClient in StyleElements, class equal to the active style); setting it to True resets the style to Classic/Windows/Normal. Not stored
property StyleApplied: Boolean	True when the style has been resolved
constructor CreateStyled(AOwner; const AFamily; const AClass; const AAppearance)	Creates the group with a given style (Create uses the defaults registered with RegisterDefaultRenderingStyle)
class procedure RegisterDefaultRenderingStyle(const ADrawType; const AFamily = DEFAULT_CLASSIC_FAMILY; const AClass = DEFAULT_WINDOWS_CLASS; const AAppearance = DEFAULT_APPEARANCE; const AStyleRadius = DEFAULT_RADIUS; const AButtonsCursor = DEFAULT_CURSOR)	Default style, shape, radius and buttons cursor of the groups created afterwards
procedure SetButtonGroupStyle(const AStyleFamily; const AStyleClass; const AStyleAppearance)	Sets family, class and appearance together; raises EStyledButtonGroupError if the combination is not available
function StyledButtonState(const AIndex: Integer; const AState: TButtonDrawState): TStyledButtonState	Converts the draw state of the VCL into the styled state (Disabled, Hot, Pressed, Selected, Normal)
procedure Assign(Source: TPersistent)	Copies also the style of another TStyledButtonGroup
procedure SetBounds(...)	Override of TControl.SetBounds

TStyledGrpButtonItem

Item of the group (Items), a TGrpButtonItem: Caption, ImageIndex, Hint, Action, OnClick are inherited from the VCL. A new item gets the style, shape and radius of the group.

Published

Property	Type	Default	Description
ButtonGroup	TStyledButtonGroup	read-only	The group the item belongs to
StyleFamily	TStyledButtonFamily	of the group	Family of the item; stored only if the item has a family, class or appearance different from the group
StyleClass	TStyledButtonClass	of the group	Class of the item
StyleAppearance	TStyledButtonAppearance	of the group	Appearance of the item
StyleDrawType	TStyledButtonDrawType	of the group	Shape of the item; stored only if different
StyleRadius	Integer	of the group	Corner radius of the item; stored only if different
StyleShadowSize	Integer	of the group	Shadow of the item (-1 = the one of the style family); stored only if different
StyleRoundedCorners	TRoundedCorners	of the group	Rounded corners of the item; stored only if different

The item has no NotificationBadge property: the badges of the group are supplied by the OnGetNotificationBadgeInfo event of the group.

Public

Method	Description
procedure SetButtonStyle(const AStyleFamily; const AStyleClass; const AStyleAppearance)	Sets family, class and appearance of the item. An empty value keeps the current one or, if the item has none, uses that of the group; raises EStyledButtonGroupError if the combination is not available

TStyledGrpButtonItems

Collection of the items: function Add: TStyledGrpButtonItem and property ButtonGroup: TStyledButtonGroup (the owner). Class references: TStyledButtonGroupClass, TStyledGrpButtonItemClass, TStyledGrpButtonItemsClass.

Types

Name	Description
TGetButtonGroupBadgeInfo	Type of OnGetNotificationBadgeInfo (see above)
TGrpButtonProc	reference to procedure (Button: TStyledGrpButtonItem), used to iterate the items
EStyledButtonGroupError	Exception class

Usage Examples

Basic ButtonGroup

var
  Group: TStyledButtonGroup;
  Item: TStyledGrpButtonItem;
begin
  Group := TStyledButtonGroup.CreateStyled(Self,
    BOOTSTRAP_FAMILY, btn_primary, BOOTSTRAP_NORMAL);
  Group.Parent := Self;
  Group.Align := alLeft;
  Group.Images := ImageList1;
  Group.ButtonOptions := [gboFullSize, gboShowCaptions];

  Item := Group.Items.Add;
  Item.Caption := 'Home';
  Item.ImageIndex := 0;
end;

Image above the caption

Group.SetButtonGroupStyle(ANGULAR_LIGHT_FAMILY, btn_PrimaryIndigo, RaisedAttr);
Group.ImageAlignment := iaTop;
Group.CaptionAlignment := taCenter;
Group.ButtonOptions := [gboShowCaptions, gboGroupStyle];
Group.ButtonHeight := 80;

Per-item styling

TStyledGrpButtonItem(Group.Items[0]).StyleClass := btn_primary;   // blue
TStyledGrpButtonItem(Group.Items[1]).StyleClass := btn_success;   // green
TStyledGrpButtonItem(Group.Items[2]).StyleClass := btn_danger;    // red

Flat group

Group.Flat := True;
Group.CaptionAlignment := taLeftJustify;
Group.ImageAlignment := iaLeft;

Replacing TButtonGroup with the Interposer unit

Vcl.StyledComponentsHooks declares TButtonGroup = class(TStyledButtonGroup); the group creates TStyledGrpButtonItem items. See Interposer Unit.

See Also

• TStyledButtonGroup - Usage and examples
• TStyledButtonGroup Demo
• TStyledCategoryButtons Reference - Categorized button group
• TStyledToolbar Reference - Toolbar with styled buttons
• Notification Badge