TStyledToolButton - Technical Reference

Overview

TStyledToolButton is the button of the TStyledToolbar. It is a styled graphic button (no window handle, no keyboard focus) that adds the toolbar behaviours of the VCL TToolButton: push, check, drop-down, separator and divider. See the component page for an introduction.

Class Hierarchy

TGraphicControl
  └─ TCustomStyledGraphicButton
      └─ TStyledToolButton

TStyledToolButton derives directly from TCustomStyledGraphicButton (the base of TStyledGraphicButton), so it has all its styling features and rendering (TStyledButtonRender); only the toolbar specific members are described in detail here. For the inherited ones see TStyledGraphicButton-Reference.

Unit

Vcl.StyledToolbar

Description

A button inherits the style of its toolbar (StyleFamily, StyleClass, StyleAppearance, StyleDrawType, StyleRadius, Images, Flat, Cursor) and follows it while it has the same value; assigning a different value overrides the toolbar for that button. Size, hint and events are those of any control.

Toolbar-specific published properties

Property	Type	Default	Description
Style	TToolButtonStyle	tbsButton	tbsButton, tbsCheck, tbsDropDown, tbsSeparator, tbsDivider. tbsTextButton raises an exception
Grouped	Boolean	False	With tbsCheck, the button belongs to a group of adjacent buttons that work as radio buttons
Marked	Boolean	False	Kept for TToolButton compatibility (no visual effect)
MenuItem	TMenuItem	nil	Copies Action, Caption, Down (from Checked), Enabled, Hint, ImageIndex, ImageName, Visible from the menu item
SortOrder	Integer	-1	Position used by TStyledToolbar.SortBySortOrder
AutoSize	Boolean	False	When changed the toolbar recalculates the buttons
Wrap	Boolean	False	The WordWrap of the caption (not a toolbar row wrap)
Index	Integer		Position of the button in the toolbar (read-only, -1 without toolbar)
Width	Integer	toolbar ButtonWidth	Width; not stored when it is the one of the toolbar (separator: 6)
Height	Integer	toolbar ButtonHeight	Height
ImageAlignment	TImageAlignment	iaTop	Position of the image when the toolbar has ShowCaptions and not List (with List it is on the left, without captions centered)
Enabled	Boolean	True	Always False for separators and dividers

Styling (inherited, same name of the toolbar)

Property	Type	Description
StyleFamily, StyleClass, StyleAppearance	string	Family / Class / Appearance; stored only if different from the toolbar
StyleDrawType	TStyledButtonDrawType	Shape (ignored for separators)
StyleRadius	Integer	Corner radius (default: the one of the toolbar)
StyleShadowSize	Integer	Shadow (default: the one of the toolbar)
StyleRoundedCorners	TRoundedCorners	Rounded corners (default: all)
StyleName	string	Per-control VCL Style (Delphi 10.4+)
StyleElements	TStyleElements	Parts that follow the VCL Style
ButtonStyleNormal, ButtonStylePressed, ButtonStyleSelected, ButtonStyleHot, ButtonStyleDisabled	TStyledButtonAttributes	Colours and border of each state
AsVCLComponent	Boolean	Looks like a VCL button of the active VCL Style (not stored)
Transparent	Boolean	Transparent background
Flat	Boolean	Flat button (default: the one of the toolbar)
Cursor	TCursor	Cursor (default: ButtonsCursor of the toolbar)

Caption and images (inherited)

Property	Type	Description
Caption	TCaption	Shown only if the toolbar has ShowCaptions; not stored for separators
CaptionAlignment	TAlignment	Alignment of the caption
WordWrap	Boolean	Wrap of the caption (not stored; use Wrap)
CommandLinkHint	string	Hint text of a command link
Images, DisabledImages	TCustomImageList	Image lists (default: the ones of the toolbar)
ImageIndex, HotImageIndex, PressedImageIndex, SelectedImageIndex, DisabledImageIndex	TImageIndex	Image of each state (default -1)
ImageName, HotImageName, PressedImageName, SelectedImageName, DisabledImageName	TImageName	Image by name (Delphi 10.4+)
ImageMargins	TImageMargins	Margins of the image
Glyph, NumGlyphs	TBitmap, TNumGlyphs	Bitmap glyph (TBitBtn compatibility)
Kind	TBitBtnKind	TBitBtn kind (default bkCustom)

Behaviour (inherited)

Property	Type	Description
Down	Boolean	Pressed state of a tbsCheck button
AllowAllUp	Boolean	In a group, all the buttons can be up
DropDownMenu	TPopupMenu	Menu of a tbsDropDown button (or shown on click for the other styles)
ModalResult	TModalResult	Modal result of the parent form
Action	TBasicAction	Linked action
PopupMenu	TPopupMenu	Context menu
NotificationBadge	TNotificationBadgeAttributes	Badge: see Notification-Badge-guide

Standard properties

Align, Anchors, Constraints, DragCursor, DragKind, DragMode, Font, ParentFont, ParentShowHint, ShowHint, Tag, Visible.

Public members (inherited)

Member	Description
GroupIndex: Integer	Group of the button (set to -1 by Grouped)
AutoClick, AutoClickDelay	Automatic click after a delay: see AutoClick-Delay-guide
Layout, Margin, Spacing	Position of the glyph (TSpeedButton compatibility; not published here)
ActiveStyleName: string	Name of the active VCL Style (read-only)
ButtonState, MouseInControl, Focused, Render, StyleApplied	State and render object (read-only)
procedure SetButtonStyle(const AStyleFamily, AStyleClass, AStyleAppearance)	Sets Family/Class/Appearance in one call (an empty value keeps the current one)
procedure SetButtonStyle(const AStyleFamily; const AModalResult: TModalResult)	Chooses Class and Appearance by ModalResult
procedure AssignStyleTo(ADest)	Copies the style to another button or render
function AssignAttributes(...)	Sets enabled, images, action, OnClick and name in one call
procedure ShowDropDownMenu, DoDropDownMenu	Shows the DropDownMenu
procedure BeginUpdate, EndUpdate	Batch changes without repaint
function GetSplitButtonWidth: Integer	Width of the arrow of a drop-down button
constructor CreateStyled(AOwner; AFamily; AClass; AAppearance)	Creates a styled button
class procedure RegisterDefaultRenderingStyle(...)	Defaults of the buttons (inherited; the toolbar has its own)
procedure Click	Shows the drop-down menu for a button with DropDownMenu, else fires OnClick and the OnToolButtonClick of the toolbar
procedure SetBounds(ALeft, ATop, AWidth, AHeight)	At design time, resizing a button changes ButtonWidth/ButtonHeight of the toolbar

Events

Event	Description
OnClick	The button was clicked
OnDropDownClick	Arrow of a drop-down button clicked (before the menu is shown)
OnMouseDown, OnMouseUp, OnMouseMove, OnMouseEnter, OnMouseLeave, OnMouseActivate	Mouse events
OnContextPopup, OnGesture	Context menu and touch
OnDragDrop, OnDragOver, OnEndDrag, OnStartDrag, OnStartDock, OnEndDock	Drag and docking

Button styles (Style)

Value	Description
tbsButton	Normal push button
tbsCheck	Toggle button (stays down); drawn pressed when Down
tbsDropDown	Split button with DropDownMenu
tbsSeparator	Empty space, always disabled, without image and caption
tbsDivider	As separator, to divide groups

Usage Examples

var
  LButton: TStyledToolButton;
begin
  if Toolbar.NewButton(LButton) then
  begin
    LButton.Caption := 'Save';
    LButton.ImageIndex := 5;
    LButton.Hint := 'Save file';
    LButton.ShowHint := True;
    LButton.OnClick := SaveClick;
  end;

  //Check button of a radio group
  if Toolbar.NewButton(LButton, tbsCheck) then
    LButton.Grouped := True;

  //Own style (overrides the toolbar)
  LButton.SetButtonStyle(BOOTSTRAP_FAMILY, btn_primary, BOOTSTRAP_NORMAL);

  //Badge
  LButton.NotificationBadge.NotificationCount := 5;
end;

Important Notes

• Parent: designed for a TStyledToolbar; NewButton is the preferred way to create it at run-time.
• Size: from ButtonWidth / ButtonHeight of the toolbar; the toolbar resizes the buttons when they change.
• Caption visibility: controlled by ShowCaptions of the toolbar.
• No focus: as every graphic control it cannot receive keyboard focus.

See Also

• TStyledToolButton - Component page
• TStyledToolbar-Reference - Toolbar container
• TStyledGraphicButton-Reference - Base graphic button
• StyledToolbar-Examples