Description of TStyledButtonGroup

TStyledButtonGroup shows a list of buttons with flow or full-size layout, like a classic TButtonGroup, with the styled rendering of the library.

You can define StyleFamily/StyleClass/StyleAppearance for every button at component level or change the Style on a single "Button" Item.

TStyledButtonGroup inherits from TButtonGroup, so you can continue to use it as the VCL component as showed in the Demo:

• Unit: Vcl.StyledButtonGroup
• Palette: Styled Components
• Inheritance: TButtonGroup > TStyledButtonGroup; the items are TStyledGrpButtonItem (collection TStyledGrpButtonItems)
• All properties, methods and events: TStyledButtonGroup Reference
• Live demo: TStyledButtonGroup Demo

When to use it

Use it for side menus, tool palettes, option selectors or any vertical/horizontal list of buttons where every button can have a different color (for example a Primary, a Success and a Danger button) and an optional notification badge, keeping the TButtonGroup programming model (Items, ItemIndex, ButtonOptions, OnButtonClicked).

Differences from TButtonGroup

• You can define a custom style for every button in the "Group": each TStyledGrpButtonItem has its own StyleFamily, StyleClass, StyleAppearance, StyleDrawType, StyleRadius and StyleRoundedCorners.
• You can specify Flat buttons.
• The Buttons caption can be aligned also at center or right (CaptionAlignment).
• The Buttons icons can be aligned left, top, bottom, right, center (ImageAlignment).
• Additional Spacing and ImageMargins to control the exact position of the icon and of the caption.
• You can use a Notification Badge on every Button, supplied by the OnGetNotificationBadgeInfo event.
• The buttons use a hand cursor (ButtonsCursor) while the group keeps its own Cursor.
• All the styles of the library (Classic, Bootstrap, Angular, Angular Material 3, colors) work in light and dark mode.

Design-time

Drop a TStyledButtonGroup from the Styled Components palette. Set StyleFamily, StyleClass and StyleAppearance of the group in the Object Inspector (the lists show the registered values), then add the buttons with the Items collection editor.

Right click on the component to open the Component Editor (verb Styled ButtonGroup Editor...): it lets you choose family, class, appearance and shape of the group (see Component Editor). The other verbs of the standard TButtonGroup editor are still available.

Every item of the collection shows its own StyleFamily, StyleClass, StyleAppearance, StyleDrawType, StyleRadius, StyleShadowSize, StyleRoundedCorners in the Object Inspector.

How an item overrides the group style

A new item copies the style of the group when it is created. The style properties of the item are saved in the .dfm only if they differ from those of the group. When an item has a family, class or appearance different from the group it is drawn with its own attributes (resolved once and cached), otherwise it shares the attributes of the group (ButtonStyleNormal, ButtonStyleHot...). The shape (StyleDrawType, StyleRadius, StyleRoundedCorners) and the shadow (StyleShadowSize: -1 = the one of the style family, 0 = none, greater than zero = that shadow, seen below the item and inside its area) are also taken from the item.

Examples

Basic group created at runtime

uses
  Vcl.StyledButtonGroup, Vcl.BootstrapButtonStyles;

var
  Group: TStyledButtonGroup;
  Item: TStyledGrpButtonItem;
begin
  Group := TStyledButtonGroup.CreateStyled(Self,
    BOOTSTRAP_FAMILY, btn_secondary, 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;

Per-item style

// SetButtonStyle sets family, class and appearance together (an empty value keeps the group value)
// (Items[] returns the VCL type TGrpButtonItem: cast it to reach the style properties)
TStyledGrpButtonItem(Group.Items[0]).SetButtonStyle(
  BOOTSTRAP_FAMILY, btn_primary, BOOTSTRAP_NORMAL);
// or property by property
TStyledGrpButtonItem(Group.Items[1]).StyleClass := btn_success;
TStyledGrpButtonItem(Group.Items[2]).StyleClass := btn_danger;
TStyledGrpButtonItem(Group.Items[2]).StyleDrawType := btRounded;

Items.Add already returns a TStyledGrpButtonItem.

SetButtonStyle raises EStyledButtonGroupError if the combination is not registered.

Image above the caption, centered caption

Group.CaptionAlignment := taCenter;
Group.ImageAlignment := iaTop;
Group.ButtonOptions := [gboShowCaptions, gboGroupStyle];
Group.ButtonWidth := 90;
Group.ButtonHeight := 80;

Flat group with Angular Material 3 style

uses
  Vcl.AngularButtonStyles;

Group.SetButtonGroupStyle(ANGULAR_M3_LIGHT_FAMILY, btn_Basic, TextAttr);
Group.Flat := True;

See Angular Material 3 families. SetButtonGroupStyle raises an exception if the combination is not available.

Notification badge

The badge of an item is provided by an event, called when each item is drawn:

procedure TForm1.GroupGetNotificationBadgeInfo(const AButtonItemIndex: Integer;
  var ABadgeContent: string; var ASize: TNotificationBadgeSize;
  var APosition: TNotificationBadgePosition; var AColor, AFontColor: TColor;
  var AFontStyle: TFontStyles);
begin
  if AButtonItemIndex = 0 then
    ABadgeContent := IntToStr(FUnreadMessages);   // empty content = no badge
end;

Assign it to OnGetNotificationBadgeInfo, then call Group.Invalidate when the count changes. See the Notification Badge guide.

Default style for all the groups

TStyledButtonGroup.RegisterDefaultRenderingStyle(btRounded,
  BOOTSTRAP_FAMILY, btn_primary, BOOTSTRAP_OUTLINE);

Replacing TButtonGroup globally

The unit Vcl.StyledComponentsHooks declares TButtonGroup = class(TStyledButtonGroup): with it in the uses clause the TButtonGroup of the forms become styled groups, without changing the code. The items of such a group are TStyledGrpButtonItem as well. See Interposer Unit.

See also

• TStyledButtonGroup Reference
• TStyledButtonGroup Demo
• TStyledCategoryButtons
• Notification Badge
• Component Editor
• Interposer Unit