Table of Contents

Text, Images, and Commands

TTMSFNCButton is a command button with FNC bitmap and HTML text support. Use it when a plain framework button is not enough for the visual language of the form.

Configure Text and Click Handling

Set Text and handle OnClick as with a regular button. The control also exposes FNC text layout and word-wrapping options.

procedure TForm1.ConfigureButton;
begin
  TMSFNCButton1.Text := 'Refresh';
  TMSFNCButton1.OnClick := TMSFNCButton1Click;
end;

procedure TForm1.TMSFNCButton1Click(Sender: TObject);
begin
  ShowMessage('Refresh requested.');
end;

Add Bitmap Content

Assign a BitmapContainer and BitmapName when the image is shared with other controls. Set ShowImage to display it and use image/text alignment properties to tune layout.

procedure TForm1.ConfigureImageButton;
begin
  TMSFNCButton1.BitmapContainer := TMSFNCBitmapContainer1;
  TMSFNCButton1.BitmapName := 'refresh';
  TMSFNCButton1.ShowImage := True;
  TMSFNCButton1.BitmapSize := 20;
  TMSFNCButton1.Text := '<b>Refresh</b>';
end;

Bitmaps at high-DPI scale

A bitmap is the one part of a button that cannot be scaled up for free. Fonts, paddings and the BitmapSize box are all expressed in logical units and follow the form as its DPI changes, but a 20x20 PNG has 20x20 pixels and nothing more — on a 150% or 200% display it is stretched and turns soft. This is what the high-DPI support added in 1.0.1.0 addresses: the button draws its image through an internal TTMSFNCImage whose Bitmaps property is a TTMSFNCScaledBitmaps collection, and every entry in that collection carries its own Scale. At paint time the renderer picks the entry matching the current display scale, falling back to the largest entry available.

Register one variant per scale you want to support and keep BitmapSize at the design value.

procedure TForm1.ConfigureHighDPIButton;
begin
  TMSFNCButton1.Text      := 'Save';
  TMSFNCButton1.ShowImage := True;

  { BitmapSize frames the glyph in logical units - leave it at the design-time
    value; the extra pixels come from the scaled variants below. }
  TMSFNCButton1.BitmapSize := 20;

  { The button draws through an internal TTMSFNCImage whose Bitmaps property is
    a TTMSFNCScaledBitmaps collection: one entry per display scale. The renderer
    asks the collection for the entry matching the monitor's scale and falls
    back to the largest entry when there is no exact match. }
  TMSFNCButton1.Image.Bitmaps.Clear;
  TMSFNCButton1.Image.Bitmaps.AddBitmapFromFile('save.png', 1.0);
  TMSFNCButton1.Image.Bitmaps.AddBitmapFromFile('save@1.5x.png', 1.5);
  TMSFNCButton1.Image.Bitmaps.AddBitmapFromFile('save@2x.png', 2.0);

  { When the artwork lives in a shared container, assign the container on the
    button (it cascades to the image renderer) and register a container item
    name per scale. Each entry resolves its own name, so give the variants
    distinct names instead of reusing one. }
  TMSFNCButton2.BitmapContainer := TMSFNCBitmapContainer1;
  TMSFNCButton2.ShowImage       := True;
  TMSFNCButton2.BitmapSize      := 20;
  TMSFNCButton2.Image.Bitmaps.Clear;
  TMSFNCButton2.Image.Bitmaps.AddBitmapName('print-1x', 1.0);
  TMSFNCButton2.Image.Bitmaps.AddBitmapName('print-2x', 2.0);
end;
Important

Assign the scaled variants instead of, or after, Bitmap and BitmapName — not before. A non-empty Bitmap always wins over the collection, and assigning BitmapName replaces the collection with a single unscaled entry, silently discarding variants added earlier.

Combining rich text, bitmap content, and click handling

HTML-capable text and bitmap content work together when one command needs both an icon and a formatted label: the bitmap area docks to one side, the text area takes the remainder, and the caption is rendered by the button's own HTML text renderer so a bold verb and a dimmed shortcut hint fit on a single control.

procedure TForm1.ConfigureSaveButton;
begin
  { Bitmap side: resolve the glyph from a shared container. }
  TMSFNCButton1.BitmapContainer := TMSFNCBitmapContainer1;
  TMSFNCButton1.BitmapName      := 'save';
  TMSFNCButton1.ShowImage       := True;
  TMSFNCButton1.BitmapSize      := 20;

  { Text side: HTML markup is rendered by the button's own text renderer, so a
    bold verb plus a dimmed shortcut hint needs no second control. }
  TMSFNCButton1.ShowText     := True;
  TMSFNCButton1.Text         := '<b>Save</b>  <font color="#888888">Ctrl+S</font>';
  TMSFNCButton1.WordWrapping := False;

  { Layout: the bitmap area is docked left, the text area fills what remains. }
  TMSFNCButton1.ImageAlign := TAlignLayout.Left;
  TMSFNCButton1.TextAlign  := TAlignLayout.Client;

  { Dialog roles. Default fires the button on Return, Cancel on Escape, so a
    two-button dialog needs one of each. Both properties are FMX-only - VCL and
    WEB projects get the equivalent behaviour from the framework button. }
  TMSFNCButton1.Default := True;
  TMSFNCButton1.OnClick := TMSFNCButton1Click;

  TMSFNCButton2.Text    := 'Cancel';
  TMSFNCButton2.Cancel  := True;
  TMSFNCButton2.OnClick := TMSFNCButton2Click;
end;

procedure TForm1.TMSFNCButton1Click(Sender: TObject);
begin
  SaveDocument;
end;

procedure TForm1.TMSFNCButton2Click(Sender: TObject);
begin
  Close;
end;

ImageAlign and TextAlign are typed to the framework's own alignment type, so the FMX values above (TAlignLayout.Left, TAlignLayout.Client) become alLeft and alClient in VCL and WEB projects.

The example also assigns the dialog roles. Default fires the button when the user presses Return and Cancel fires it on Escape, so a two-button dialog sets one of each; both properties exist on the FMX button (added in 1.0.0.8, which brought it in line with the framework button) and are not published in VCL or WEB, where the framework supplies the same behaviour.

See also