TStyledToolbar - Technical Reference

Overview

TStyledToolbar is a styled toolbar control that contains TStyledToolButton components. It provides full customization of the button styles and precise control over the button dimensions. See the component page for an introduction and StyledToolbar-Examples for code samples.

Class Hierarchy

TWinControl
  └─ TCustomPanel
      └─ TCustomFlowPanel
          └─ TStyledToolbar

Unit

Vcl.StyledToolbar

Description

TStyledToolbar extends TCustomFlowPanel to create a toolbar container for TStyledToolButton components. Unlike the standard VCL TToolBar, the dimension of the buttons is controlled by ButtonWidth and ButtonHeight instead of being the one of the largest caption.

All the buttons share the style of the toolbar (Family, Class, Appearance, shape, radius, cursor, images, flat) until a single button gets its own value. The published properties that the VCL TToolBar has for the graphic look (GradientDrawingOptions, GradientDirection, DrawingStyle, GradientStartColor, GradientEndColor) exist only for backward compatibility and are ignored.

Key Features

• Flow layout: the buttons flow in rows, with wrapping (Wrapable)
• Fixed button size: ButtonWidth and ButtonHeight for all the buttons
• AutoSize with wrapping: the toolbar grows with the number of rows
• Uniform styling: one style for all the buttons, with per-button override
• Separators and dividers, check buttons, drop-down buttons
• ShowCaptions and List: captions with image on top or on the left
• BeginUpdate / EndUpdate: batch changes with a single resize
• Style families: Classic, Bootstrap, Angular-Light, Angular-Dark, Angular-M3-Light, Angular-M3-Dark, Basic-Colors, SVG-Colors and custom
• Component Editor at design time (Component-Editor)

Published properties

Toolbar layout

Property	Type	Default	Description
ButtonWidth	Integer	23	Width of every button (the width of the arrow is added to the drop-down buttons)
ButtonHeight	Integer	22	Height of every button
ShowCaptions	Boolean	False	Show the captions of the buttons
List	Boolean	False	With ShowCaptions, the image is on the left of the caption instead of on top
Wrapable	Boolean	True	Buttons wrap on the next row when the toolbar is too narrow (the AutoWrap of the flow panel)
AutoSize	Boolean	False	With Wrapable the toolbar grows to contain all the rows (height for alTop/alBottom, width for alLeft/alRight, limited to the parent); without Wrapable it is the AutoSize of the flow panel
Indent	Integer	0	Left margin of the toolbar: a value other than 0 sets AlignWithMargins := True and Margins.Left
Flat	Boolean	True	Flat value passed to all the buttons
Transparent	Boolean	-	Transparent background (not stored in the .dfm)
EdgeBorders	TEdgeBorders	[]	Edges where the bevel is drawn (ebLeft, ebTop, ebRight, ebBottom)
EdgeInner	TEdgeStyle	esNone	Style of the inner edge (esNone, esRaised, esLowered)
EdgeOuter	TEdgeStyle	esNone	Style of the outer edge
ButtonsCursor	TCursor	crHandPoint	Cursor of all the buttons

Images

Property	Type	Default	Description
Images	TCustomImageList	nil	ImageList shared by all the buttons
DisabledImages	TCustomImageList	nil	Images of the disabled buttons

Style (applied to all the buttons)

Property	Type	Default	Description
StyleFamily	TStyledButtonFamily	Classic	Style family
StyleClass	TStyledButtonClass	Windows	Predefined class within the family
StyleAppearance	TStyledButtonAppearance	Normal	Visual variant
StyleDrawType	TStyledButtonDrawType	btRoundRect	Shape: btRoundRect, btRounded, btRect, btEllipse
StyleRadius	Integer	6	Corner radius (a value <= 0 raises an exception)
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
StyleElements	TStyleElements		Which parts follow the VCL Style (Classic family only)

The defaults of the style properties are the ones registered with RegisterDefaultRenderingStyle. A button is changed together with the toolbar only if it has the same value of the toolbar.

Compatibility (no effect on the look)

Property	Type	Default	Description
Customizable	Boolean	False	Kept for TToolBar compatibility
HideClippedButtons	Boolean	False	Kept for TToolBar compatibility
GradientDrawingOptions	TTBGradientDrawingOptions	[gdoHotTrack, gdoGradient]	Ignored
GradientDirection	TGradientDirection	gdVertical	Ignored
DrawingStyle	TTBDrawingStyle	dsNormal	Ignored
GradientStartColor	TColor	clWindow	Ignored
GradientEndColor	TColor		Ignored

Published from the ancestors

Align (default alTop), Anchors, BorderWidth, Caption, Color, Constraints, Ctl3D, DoubleBuffered, DockSite, DragCursor, DragKind, DragMode, Enabled, Font, Height, ParentBackground, ParentBiDiMode, ParentColor (default True), ParentDoubleBuffered, ParentFont, ParentShowHint, PopupMenu, ShowHint, TabOrder, TabStop, Touch, Visible.

Public properties

Property	Type	Description
ButtonCount	Integer	Number of buttons in the toolbar (read-only)
Buttons[Index]	TStyledToolButton	The Index-th button, counting only the TStyledToolButton controls (read-only; nil if Index is out of range)
AutoWrap	Boolean	True when the buttons wrap (read-only; it is Wrapable)
AsVCLComponent	Boolean	Classic family with seClient in StyleElements: buttons drawn as the VCL buttons of the active VCL Style. Setting True selects Classic/Windows/Normal. Not stored
StyleApplied	Boolean	True when the style attributes have been resolved

Methods

Creation

constructor Create(AOwner: TComponent); override;
constructor CreateStyled(AOwner: TComponent;
  const AFamily: TStyledButtonFamily;
  const AClass: TStyledButtonClass;
  const AAppearance: TStyledButtonAppearance); virtual;

Create uses the default style (see RegisterDefaultRenderingStyle); CreateStyled the given Family/Class/Appearance.

Buttons

Method	Description
function NewButton(out ANewToolButton: TStyledToolButton; const AStyle: TToolButtonStyle = tbsButton): Boolean	Creates a button (owner: the owner of the toolbar), sets the toolbar style and size and adds it at the end. If OnCustomizeNewButton returns a button it is used instead. Returns True if the button exists
procedure ClearButtons	Frees all the controls of the toolbar
procedure SortBySortOrder	Reorders the buttons by their SortOrder
procedure BeginUpdate / procedure EndUpdate	Defers the resize of the buttons until the last EndUpdate

Style

Method	Description
procedure SetToolbarStyle(const AStyleFamily; const AStyleClass; const AStyleAppearance)	Sets Family, Class and Appearance; raises EStyledButtonError if the combination is not available
class procedure RegisterDefaultRenderingStyle(const ADrawType: TStyledButtonDrawType; const AFamily = DEFAULT_CLASSIC_FAMILY; const AClass = DEFAULT_WINDOWS_CLASS; const AAppearance = DEFAULT_APPEARANCE; const AStyleRadius: Integer = DEFAULT_RADIUS)	Default style of the toolbars created afterwards (call it after Application.Initialize)
procedure Assign(Source: TPersistent)	Copies the toolbar settings (size, captions, images, style...) from another TStyledToolbar

Other

Method	Description
procedure Click	Fires OnClick
procedure SetBounds(ALeft, ATop, AWidth, AHeight: Integer)	Sets the bounds of the toolbar
procedure ScaleForPPI(NewPPI: Integer)	Scales the toolbar and the button size for a new monitor DPI (Delphi 10.1+)

Protected, for descendants: GetStyledToolButtonClass (virtual, returns the class of the buttons created by NewButton), TrackMenu, ClickButton, CancelMenu (dynamic).

Events

Event	Type	Description
OnToolButtonClick	TNotifyEvent	A button was clicked (Sender is the button, called after the OnClick of the button)
OnCustomizeNewButton	TSTBNewButtonEvent	In NewButton: Sender, AIndex (position of the new button), var AButton (assign your own button)
OnCustomizeAdded	TSTBButtonEvent	A button was inserted in the toolbar (Sender, AButton)
OnClick, OnDblClick, OnContextPopup, OnEnter, OnExit, OnResize, OnCanResize, OnGesture		Standard events
OnMouseActivate, OnMouseDown, OnMouseUp, OnMouseMove, OnMouseEnter, OnMouseLeave		Mouse events
OnAlignInsertBefore, OnAlignPosition		Alignment of the controls
OnDockDrop, OnDockOver, OnGetSiteInfo, OnUnDock, OnStartDock, OnEndDock, OnDragDrop, OnDragOver, OnEndDrag, OnStartDrag		Docking and drag and drop

Related types and constants

Name	Description
TStyledToolButtonClass	class of TStyledToolButton
TButtonProc, TControlProc	Anonymous method types used to iterate buttons and controls
DEFAULT_TOOLBUTTON_SEP_WIDTH	Default width of separators (6)
DEFAULT_SORT_ORDER	Default SortOrder of a button (-1)
EStyledToolbarError	Exception class of the unit

Usage Examples

var
  LToolbar: TStyledToolbar;
  LButton: TStyledToolButton;
begin
  LToolbar := TStyledToolbar.CreateStyled(Self,
    BOOTSTRAP_FAMILY, btn_secondary, BOOTSTRAP_NORMAL);
  LToolbar.Parent := Self;
  LToolbar.Images := ImageList1;
  LToolbar.ShowCaptions := True;
  LToolbar.ButtonWidth := 80;
  LToolbar.ButtonHeight := 36;

  if LToolbar.NewButton(LButton) then
  begin
    LButton.Caption := 'New';
    LButton.ImageIndex := 0;
  end;
  //a button with its own style
  if LToolbar.NewButton(LButton) then
  begin
    LButton.Caption := 'Save';
    LButton.SetButtonStyle(BOOTSTRAP_FAMILY, btn_primary, BOOTSTRAP_NORMAL);
  end;
end;

Important Notes

• Fixed size: the size of a button does not change with the width of the caption.
• Flow layout: based on TFlowPanel, not on the common control TToolBar.
• ShowCaptions is a toolbar setting: a button cannot override it.
• Images: set Images on the toolbar; a button can use another list.
• Design time: moving a button over another one changes the order; resizing a button changes ButtonWidth / ButtonHeight of the toolbar. At run-time the layout does not change the order.

See Also

• TStyledToolbar - Component page
• StyledToolbar-Examples - Examples
• TStyledToolButton-Reference - Individual toolbar button
• StyledToolbarDemo - Demo
• Component-Editor