TStyledGraphicButton

TStyledGraphicButton is a "pure" graphic button with styles. It derives from TGraphicControl: it has no window handle, no keyboard focus and no tab stop, so it is very light and can be used where a windowed control cannot, for example in a TControlList (Delphi 11+), in a custom list, on a toolbar-like panel or as a floating/icon button.

It is declared in the unit Vcl.StyledButton. Technical reference: TStyledGraphicButton-Reference.

When to use it

Use TStyledGraphicButton when...	Use another component when...
you do not need the keyboard focus (toolbars, icon buttons, lists, many buttons on a form)	the button must be reached with the Tab key, be Default/Cancel or have an & accelerator: use TStyledButton
the button is inside a TControlList or a virtual list	you are migrating a TSpeedButton and want its Layout/Margin/Spacing: use TStyledSpeedButton
you need many buttons with a small footprint	you are migrating a TBitBtn with Kind: use TStyledBitBtn

Differences from the VCL buttons

• The VCL has no graphic button with an ImageList, a modern style and Down/GroupIndex all together: TSpeedButton is the closest one, but it uses a Glyph and the Windows look.
• The appearance does not depend on the VCL Styles: the button looks the same with or without a VCL Style (unless AsVCLComponent/StyleName is used, see below).
• Rendering is made with GDI+ (antialiased shapes), by an internal TStyledButtonRender shared by all the styled buttons.
• Besides the Glyph, it supports Images/ImageIndex/ImageName, state images (HotImageIndex, PressedImageIndex, SelectedImageIndex, DisabledImageIndex, DisabledImages), NotificationBadge and AutoClick.
• Default size 75 x 25, cursor crHandPoint, shape btRoundRect with StyleRadius 6.

The style: family, class, appearance

With three properties you choose the look of the button:

• StyleFamily: Classic, Bootstrap, Angular-Light, Angular-Dark, Angular-M3-Light, Angular-M3-Dark, Basic-Colors, SVG-Colors (and your custom families)
• StyleClass: predefined colors inside the family (e.g. Primary, Success, Danger in Bootstrap)
• StyleAppearance: the variant (e.g. Normal/Outline in Bootstrap; Flat/Raised/Basic/Stroked in Angular; Text/Elevated/Outlined/Filled/Tonal in the Angular Material 3 families)

The shape is controlled by StyleDrawType (btRoundRect, btRounded, btRect, btEllipse), StyleRadius and StyleRoundedCorners; StyleShadowSize adds a shadow below the button (see Shadow). The five states (Normal, Pressed, Selected, Hot, Disabled) are exposed by ButtonStyleNormal, ButtonStylePressed, ButtonStyleSelected, ButtonStyleHot, ButtonStyleDisabled: they are filled by the style and you can customize any color.

To follow a VCL Style set AsVCLComponent := True, or (Delphi 10.4+) assign a VCL style name to StyleName. See StyledButtonVCLStylesDemo.

Design time and Component Editor

Drop the component from the Styled Components palette page (the IDE adds the needed units to the uses clause). Right-click it and choose Styled Button Editor... (the same verb is at the bottom of the Object Inspector) to select family, class, appearance and shape with a click, seeing a preview of the result: see Component Editor.

In the Object Inspector the properties of the style appear as StyleFamily, StyleClass, StyleAppearance, StyleDrawType, StyleRadius, StyleShadowSize, StyleRoundedCorners. Only the values different from the defaults are stored in the DFM.

Examples

1. A button created at runtime

uses
  Vcl.StyledButton, Vcl.BootstrapButtonStyles;

var
  LButton: TStyledGraphicButton;
begin
  LButton := TStyledGraphicButton.CreateStyled(Self,
    BOOTSTRAP_FAMILY, btn_primary, BOOTSTRAP_NORMAL);
  LButton.Parent := Self;
  LButton.SetBounds(16, 16, 120, 32);
  LButton.Caption := 'Click me';
  LButton.StyleDrawType := btRounded;
  LButton.OnClick := ButtonClick;
end;

2. Change the style at once

//An empty value keeps the current one
StyledGraphicButton1.SetButtonStyle(BOOTSTRAP_FAMILY, btn_danger, BOOTSTRAP_OUTLINE);

//Angular Material 3, "Filled" button
StyledGraphicButton2.SetButtonStyle(ANGULAR_M3_LIGHT_FAMILY, btn_Basic, FilledAttr);

3. Icon button with an ImageList

StyledGraphicButton1.Images := ImageList1;
StyledGraphicButton1.ImageIndex := 3;
//Delphi 10.4+: you can use the name instead of the index
//StyledGraphicButton1.ImageName := 'save';
StyledGraphicButton1.HotImageIndex := 4;
StyledGraphicButton1.DisabledImages := DisabledImageList;
StyledGraphicButton1.ImageAlignment := iaLeft;
StyledGraphicButton1.Caption := 'Save';

4. Toggle buttons (group)

//Buttons with the same GroupIndex and the same parent are mutually exclusive
BtnLeft.GroupIndex := 1;
BtnCenter.GroupIndex := 1;
BtnRight.GroupIndex := 1;
BtnLeft.Down := True;

//Single toggle button
BtnBold.GroupIndex := 2;
BtnBold.AllowAllUp := True;

5. Notification badge and AutoClick

StyledGraphicButton1.NotificationBadge.NotificationCount := 5;  //shows "5"
StyledGraphicButton1.NotificationBadge.Color := clRed;

StyledGraphicButton2.AutoClickDelay := 3000;
StyledGraphicButton2.AutoClick := True; //OnClick after 3 seconds

See Notification Badge and AutoClick / AutoClickDelay.

6. Customize the colors of the states

StyledGraphicButton1.ButtonStyleNormal.ButtonColor := clTeal;
StyledGraphicButton1.ButtonStyleNormal.FontColor := clWhite;
StyledGraphicButton1.ButtonStyleHot.ButtonColor := clAqua;

7. Split button

StyledGraphicButton1.Style := bsSplitButton;
StyledGraphicButton1.DropDownMenu := PopupMenu1; //shown by the arrow

8. Default style for the application

//In the .dpr, after Application.Initialize.
//It is shared by TStyledGraphicButton and TStyledSpeedButton.
TStyledGraphicButton.RegisterDefaultRenderingStyle(
  btRounded, BOOTSTRAP_FAMILY, btn_primary, BOOTSTRAP_NORMAL);

To replace all the standard buttons of an existing application see the Interposer Unit (Vcl.StyledComponentsHooks).

Shadow (StyleShadowSize)

StyleShadowSize is a property of the component, like StyleRadius, StyleDrawType and StyleRoundedCorners: it gives the button a soft shadow below its face, as the Elevated button of Angular Material has.

• -1 (default): the shadow of the style family. Only the Elevated (2 pixels, 3 on hover) and Fab (3 and 4 pixels) appearances of the Angular-M3 families have one: the other families have none.
• 0: no shadow, even if the family has one.
• greater than zero: that shadow, in pixels at 100% scale (it follows the DPI), the same in every state and in any family.

The shadow is seen only below the button and it is drawn inside the area of the control: the face is shorter by the size of the shadow, the top and the sides are unchanged. Give the button a few pixels more height than you want for the face. The value is saved in the form file only when it is different from -1.

StyledGraphicButton1.StyleFamily := BOOTSTRAP_FAMILY;
StyledGraphicButton1.StyleShadowSize := 3;   // a shadow on a family that has none
StyledGraphicButton1.StyleShadowSize := 0;   // no shadow on an Angular-M3 Elevated button

The shadow that the style family provides is also available, read only, in ButtonStyleNormal.ShadowSize, ButtonStyleHot.ShadowSize... (a public property of TStyledButtonAttributes, not saved: it is the default that StyleShadowSize = -1 uses).

Demos

• Family, Class & Appearance Demo and Styled Buttons Examples
• Styled Buttons with VCL Styles Demo
• AutoClick Demo, Rounded Corners Demo
• The Control List page of StyledComponentsDemo (Delphi 11+, see Main Demo) shows TStyledGraphicButton inside a TControlList:

See also

• TStyledGraphicButton-Reference: all the properties, methods and events
• TStyledButton, TStyledSpeedButton, TStyledBitBtn
• Component Editor, Angular Material 3 families, How to build your custom style
• TStyledToolButton: the button of the styled toolbar