TStyledCategoryButtons - Technical Reference

Overview

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

Class Hierarchy

TCategoryButtons        (Vcl.CategoryButtons)
  └─ TStyledCategoryButtons

TButtonItem             (Vcl.CategoryButtons, a TCollectionItem)
  └─ TStyledButtonItem

TButtonCategory
  └─ TStyledButtonCategory

TButtonCategories
  └─ TStyledButtonCategories

Unit

Vcl.StyledCategoryButtons

Description

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

Key Features

• Full TCategoryButtons compatibility
• Collapsible categories containing styled buttons
• Component 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)

Categories and layout

Property	Type	Default	Description
Categories	TStyledButtonCategories	empty	Collection of the categories (TStyledButtonCategory); Categories.Add and Categories[Index] return a TStyledButtonCategory; the buttons of a category are in its Items (TButtonItem, cast to TStyledButtonItem)
CaptionAlignment	TAlignment	taLeftJustify	Alignment of the caption: taLeftJustify, taCenter, taRightJustify (used when boShowCaptions 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 component 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 component

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	TGetCategoryButtonsBadgeInfo	Supplies the badge of a button: (const ACategoryIndex, 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 TCategoryButtons (summary)

ButtonOptions (boAllowReorder, boAllowCopyingButtons, boFullSize, boGradientFill, boShowCaptions, boBoldCaptions, boUsePlusMinus, boCaptionOnlyBorder), ButtonWidth, ButtonHeight, ButtonFlow, Images, HeaderFont, SelectedItem, Align, Anchors, Color, Font, Enabled, Visible, StyleElements, TabOrder, TabStop, PopupMenu, ShowHint, and the events OnButtonClicked, OnCategoryCollapase (spelled so in the VCL), OnSelectedItemChange, OnBeforeDrawButton, OnDrawButton, OnAfterDrawButton, OnDrawIcon, OnHotButton, OnReorderButton, OnClick, OnEnter, OnExit... See the Embarcadero documentation of Vcl.CategoryButtons.TCategoryButtons.

Public members

Member	Description
property AsVCLComponent: Boolean	True when the component 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 component 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 components created afterwards
procedure SetCategoryButtonsStyle(const AStyleFamily; const AStyleClass; const AStyleAppearance)	Sets family, class and appearance together; raises EStyledCategoryButtonsError if the combination is not available
function StyledButtonState(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 TStyledCategoryButtons
procedure SetBounds(...)	Override of TControl.SetBounds

TStyledButtonItem

Button of a category (Category.Items), a TButtonItem: Caption, ImageIndex, Hint, Action, OnClick are inherited from the VCL. A new item gets the style, shape and radius of the component; Assign copies the style properties too.

Published

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

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

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 component; raises EStyledCategoryButtonsError if the combination is not available
procedure Assign(Source: TPersistent)	Copies the caption, image and the style of another item

TStyledButtonCategory and TStyledButtonCategories

TStyledButtonCategory is a TButtonCategory (Caption, Collapsed, Color, GradientColor, TextColor, Items) without additional members: it exists so that the collection creates styled categories. TStyledButtonCategories is the collection: function Add: TStyledButtonCategory, Items[Index]: TStyledButtonCategory (default property) and property CategoryButtons: TStyledCategoryButtons (the owner).

Types

Name	Description
TGetCategoryButtonsBadgeInfo	Type of OnGetNotificationBadgeInfo (see above)
TButtonProc	reference to procedure (Button: TStyledButtonItem), used to iterate the items
TStyledCategoryButtonsClass, TStyledButtonItemClass, TStyledButtonCategoryClass, TStyledButtonCategoriesClass	Class references
EStyledCategoryButtonsError	Exception class

Usage Examples

Categories and styled items

var
  CatButtons: TStyledCategoryButtons;
  Cat: TStyledButtonCategory;
  Item: TStyledButtonItem;
begin
  CatButtons := TStyledCategoryButtons.CreateStyled(Self,
    BOOTSTRAP_FAMILY, btn_primary, BOOTSTRAP_NORMAL);
  CatButtons.Parent := Self;
  CatButtons.Align := alLeft;
  CatButtons.Images := ImageList1;

  Cat := CatButtons.Categories.Add;
  Cat.Caption := 'File';
  Item := Cat.Items.Add as TStyledButtonItem;
  Item.Caption := 'New';
  Item.ImageIndex := 0;
  Item.SetButtonStyle(BOOTSTRAP_FAMILY, btn_success, BOOTSTRAP_NORMAL);

  Cat := CatButtons.Categories.Add;
  Cat.Caption := 'Tools';
  Cat.Collapsed := True;   // starts collapsed
end;

Image position and flat buttons

CatButtons.ImageAlignment := iaTop;
CatButtons.CaptionAlignment := taCenter;
CatButtons.Flat := True;

Replacing TCategoryButtons with the Interposer unit

Vcl.StyledComponentsHooks declares TCategoryButtons = class(TStyledCategoryButtons) and TButtonCategory = class(TStyledButtonCategory); the component creates TStyledButtonItem buttons. See Interposer Unit.

See Also

• TStyledCategoryButtons - Usage and examples
• TStyledCategoryButtons Demo
• TStyledButtonGroup Reference - Button group without categories
• TStyledToolbar Reference - Toolbar with styled buttons
• Notification Badge