TStyledSpeedButton

TStyledSpeedButton is the styled replacement of the VCL TSpeedButton. Like TSpeedButton it is a graphic control (no window handle, no focus) and it positions the image and the caption with Layout, Margin and Spacing; unlike TSpeedButton it has the full styling of the library: families, classes, appearances, shapes, ImageList images, NotificationBadge, AutoClick.

It is declared in the unit Vcl.StyledButton and derives from TCustomStyledGraphicButton, the same base class of TStyledGraphicButton (it is a sibling, not a descendant). Technical reference: TStyledSpeedButton-Reference.

When to use it

• You are migrating an application that uses TSpeedButton (toolbars made with panels, toggle buttons with GroupIndex) and you want to keep Layout, Margin, Spacing, Glyph and NumGlyphs unchanged.
• You want a button without focus, but with the VCL-compatible layout properties.
• For new code that does not need those properties, TStyledGraphicButton (ImageAlignment and ImageMargins) is equivalent and has more published properties.

Differences from TSpeedButton

	TSpeedButton	TStyledSpeedButton
Rendering	Windows/VCL Styles	GDI+ with the style family, independent of VCL Styles (unless AsVCLComponent/StyleName)
Image	Glyph	Glyph and Images/ImageIndex/ImageName, state images
Default size	23 x 22	23 x 22
Default Transparent	True	True
Default Spacing	4	4
Extras		StyleFamily/StyleClass/StyleAppearance, StyleDrawType, StyleRadius, StyleShadowSize, StyleRoundedCorners, ButtonStyle*, NotificationBadge, AutoClick, Cursor = crHandPoint

Properties that are published by TStyledGraphicButton but not by TStyledSpeedButton (ImageAlignment, ImageMargins, DisabledImages, CaptionAlignment, WordWrap, ModalResult, Style, DropDownMenu, CommandLinkHint, Kind, OnDropDownClick) exist anyway and can be set in code.

By default the image (Glyph or ImageList) is positioned with Layout, Margin and Spacing. If you call AssignAttributes passing an image list, the button switches to the positioning of TStyledGraphicButton (ImageAlignment and ImageMargins).

Design time and Component Editor

Drop it from the Styled Components palette page. Right-click the button and choose Styled Button Editor... to choose family, class, appearance and shape with a preview: see Component Editor. Images, ImageName and the other image names use the image-name editor of the IDE (Delphi 10.4+).

NumGlyphs

Glyph is a bitmap with NumGlyphs (1 to 4) images side by side, in the order of TSpeedButton: up, disabled, clicked (down) and down in a group (exclusive). With NumGlyphs = 1 the same image is used for all the states. For a DPI-aware result prefer an ImageList (Images + ImageIndex).

Examples

1. Replace a TSpeedButton

//Old code
//  SpeedButton1: TSpeedButton;
//New code (same properties: Glyph, NumGlyphs, Layout, Margin, Spacing, GroupIndex, Down...)
  SpeedButton1: TStyledSpeedButton;

With the Interposer unit (Vcl.StyledComponentsHooks) the replacement is automatic, without changing the declarations.

2. Create a button at runtime

var
  LButton: TStyledSpeedButton;
begin
  LButton := TStyledSpeedButton.CreateStyled(Self,
    BOOTSTRAP_FAMILY, btn_secondary, BOOTSTRAP_NORMAL);
  LButton.Parent := ToolPanel;
  LButton.Caption := 'Bold';
  LButton.Layout := blGlyphLeft;
  LButton.Margin := 4;
  LButton.Spacing := 2;
  LButton.Glyph.LoadFromFile('bold.bmp');
end;

3. Image from an ImageList

StyledSpeedButton1.Images := ImageList1;
StyledSpeedButton1.ImageIndex := 5;
StyledSpeedButton1.Layout := blGlyphTop;
StyledSpeedButton1.Spacing := 4;
StyledSpeedButton1.Caption := 'Print';

4. Group of toggle buttons

//Mutually exclusive buttons: same parent and same GroupIndex
SbLeft.GroupIndex := 1;
SbCenter.GroupIndex := 1;
SbRight.GroupIndex := 1;
SbLeft.Down := True;

//Toggle button that can be released
SbBold.GroupIndex := 2;
SbBold.AllowAllUp := True;

5. Multi-state glyph

StyledSpeedButton1.Glyph.LoadFromFile('states.bmp'); //4 images side by side
StyledSpeedButton1.NumGlyphs := 4;                   //up, disabled, down, exclusive

6. Choose a style

//Angular Material 3, tonal button
StyledSpeedButton1.StyleFamily := ANGULAR_M3_LIGHT_FAMILY;
StyledSpeedButton1.StyleClass := btn_Basic;
StyledSpeedButton1.StyleAppearance := TonalAttr;
StyledSpeedButton1.StyleDrawType := btRounded;
StyledSpeedButton1.Transparent := False;

7. Notification badge

StyledSpeedButton1.NotificationBadge.NotificationCount := 12;
StyledSpeedButton1.NotificationBadge.Position := nbpTopRight;

8. Default style

//In the .dpr, after Application.Initialize.
//The default is shared with TStyledGraphicButton.
TStyledSpeedButton.RegisterDefaultRenderingStyle(btRoundRect,
  BOOTSTRAP_FAMILY, btn_light, BOOTSTRAP_NORMAL);

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.

StyledSpeedButton1.StyleFamily := BOOTSTRAP_FAMILY;
StyledSpeedButton1.StyleShadowSize := 3;   // a shadow on a family that has none
StyledSpeedButton1.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, Styled Buttons Examples
• Main Demo

See also

• TStyledSpeedButton-Reference: all the properties, methods and events
• TStyledGraphicButton, TStyledButton, TStyledBitBtn
• Component Editor, Notification Badge, AutoClick / AutoClickDelay
• Interposer Unit (Vcl.StyledComponentsHooks)