TStyledBitBtn

TStyledBitBtn is the styled replacement of the VCL TBitBtn. Like TBitBtn it is a windowed button (keyboard focus, Default, Cancel, ModalResult) with the Kind property (OK, Cancel, Yes, No...), the Glyph/NumGlyphs bitmap and the Layout, Margin and Spacing properties that position the image and the caption; unlike TBitBtn it has the full styling of the library.

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

When to use it

• You are migrating an application that uses TBitBtn, especially with Kind and Glyph, and you want to keep the same properties.
• You want the "OK / Cancel / Yes / No..." buttons of a dialog with the caption, the ModalResult and the icon set by one property.
• For new code that does not need those properties, TStyledButton with Images is equivalent and exposes more published properties.

Differences from TBitBtn

	TBitBtn	TStyledBitBtn
Rendering	Windows/VCL Styles	GDI+ with the style family, independent of VCL Styles (unless AsVCLComponent/StyleName)
Kind glyph	Bitmap of the VCL resources	Default glyph of the library, drawn according to the state
Style of the button	none	StyleFamily/StyleClass/StyleAppearance (the ModalResult of the Kind can choose them), StyleDrawType, StyleRadius, StyleShadowSize, StyleRoundedCorners, ButtonStyle*
Image	Glyph	Glyph and Images/ImageIndex/ImageName, state images
Style	bsAutoDetect, bsWin31, bsNew	The property exists with the TBitBtn type (default bsAutoDetect) but has no effect
Extras		NotificationBadge, AutoClick/AutoClickDelay, Cursor = crHandPoint
Default Spacing	4	4

Split button, command link, Flat, DisabledImages, ImageAlignment, ImageMargins, ElevationRequired are inherited from the base class and available in code, but they are not published by TStyledBitBtn.

Kind

Setting Kind (different from bkCustom) sets Caption, ModalResult, Default and Cancel, and shows the default glyph of the Kind when no Glyph is assigned:

Kind	Caption	ModalResult	Default	Cancel
bkOK	OK	mrOk	True	False
bkCancel	Cancel	mrCancel	False	True
bkYes	Yes	mrYes	True	False
bkNo	No	mrNo	False	True
bkAbort	Abort	mrAbort	False	False
bkRetry	Retry	mrRetry	False	False
bkIgnore	Ignore	mrIgnore	False	False
bkAll	All	mrAll	False	False
bkClose	Close	mrNone	False	False
bkHelp	Help	mrNone	False	False
bkCustom	(unchanged)	(unchanged)	(unchanged)	(unchanged)

The captions are the localized strings of the library. If you change ModalResult, Default or Cancel so that they no longer match the Kind, reading Kind returns bkCustom (changing the Caption does not affect it).

The style follows the ModalResult

When ModalResult is not mrNone the style family chooses the class and the appearance, so with Kind the buttons are colored by their meaning. In the Bootstrap family: bkOK is Success, bkYes is Primary, bkNo is Secondary, bkCancel and bkAbort are Danger, bkRetry is Warning, bkIgnore is Secondary, bkAll is Primary Outline. bkClose and bkHelp have ModalResult = mrNone and use the default class of the family. Other families map the ModalResult in their own way: see Angular Material 3 families and How to build your custom style.

Design time and Component Editor

Drop it from the Styled Components palette page, set Kind in the Object Inspector (the caption and the glyph change at once) and right-click the button to choose Styled Button Editor...: family, class, appearance and shape with a preview. See Component Editor.

Examples

1. Replace a TBitBtn

//Old code
//  BitBtn1: TBitBtn;
//New code (same properties: Kind, Glyph, NumGlyphs, Layout, Margin, Spacing, ModalResult...)
  BitBtn1: TStyledBitBtn;

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

2. OK and Cancel buttons

var
  LOK, LCancel: TStyledBitBtn;
begin
  LOK := TStyledBitBtn.CreateStyled(Self,
    BOOTSTRAP_FAMILY, btn_success, BOOTSTRAP_NORMAL);
  LOK.Parent := Self;
  LOK.Kind := bkOK;           //Caption, ModalResult, Default and glyph

  LCancel := TStyledBitBtn.CreateStyled(Self,
    BOOTSTRAP_FAMILY, btn_secondary, BOOTSTRAP_NORMAL);
  LCancel.Parent := Self;
  LCancel.Kind := bkCancel;   //Cancel = True, ModalResult = mrCancel
end;

3. Custom button with a Glyph

Btn.Kind := bkCustom;
Btn.Caption := 'Save';
Btn.Glyph.LoadFromFile('save.bmp');
Btn.NumGlyphs := 1;
Btn.Layout := blGlyphLeft;
Btn.Margin := 4;
Btn.Spacing := 4;

4. Image from an ImageList

Btn.Caption := 'Print';
Btn.Images := ImageList1;
Btn.ImageIndex := 5;
Btn.Layout := blGlyphRight; //Layout, Margin and Spacing position the image

5. Override the values given by Kind

Btn.Kind := bkOK;
Btn.Caption := 'Confirm';   //custom caption: the Kind does not change
Btn.ModalResult := mrYes;   //no longer matches bkOK: Kind now reads bkCustom

6. The same buttons in many families

procedure TForm1.ApplyFamily(const AFamily: TStyledButtonFamily);
begin
  //Class and appearance are chosen by the family from the ModalResult of the Kind
  StyledBitBtn1.SetButtonStyle(AFamily, StyledBitBtn1.ModalResult);
  StyledBitBtn2.SetButtonStyle(AFamily, StyledBitBtn2.ModalResult);
end;

//ApplyFamily(BOOTSTRAP_FAMILY);
//ApplyFamily(ANGULAR_M3_LIGHT_FAMILY);

7. Notification badge

StyledBitBtn1.NotificationBadge.NotificationCount := 4;

8. Default style

//In the .dpr, after Application.Initialize.
//The default is shared with TStyledButton.
TStyledBitBtn.RegisterDefaultRenderingStyle(btRounded);

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.

StyledBitBtn1.StyleFamily := BOOTSTRAP_FAMILY;
StyledBitBtn1.StyleShadowSize := 3;   // a shadow on a family that has none
StyledBitBtn1.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).

Demo

The TStyledBitBtn Demo shows all the TBitBtnKind values side by side with the standard TBitBtn, in the Classic, Bootstrap, Angular-Light, Angular-Dark, Basic-Colors and SVG-Colors families.

See also

• TStyledBitBtn-Reference: all the properties, methods and events
• TStyledButton, TStyledGraphicButton, TStyledSpeedButton
• Styled Buttons Examples
• Component Editor, Interposer Unit (Vcl.StyledComponentsHooks)