Table of Contents

Format toolbar

TTMSFNCRichEditorFormatToolBar provides the character- and paragraph-formatting commands of a word processor: font name and size pickers, bold/italic/underline/strikeout, left/center/right alignment, text and background colour pickers, bullets and numbering, indent and unindent, and image and hyperlink insertion. Bind it to an editor with RichEditor (see Connecting toolbars); this chapter covers choosing which commands appear, responding when a command is applied, and customising individual buttons.

Rich editor format toolbar showing font, style, alignment, colour, and list buttons Rich editor format toolbar showing font, style, alignment, colour, and list buttons

Choosing which buttons are visible

Options is a set of TTMSFNCRichEditorFormatToolBarOption. It defaults to AllFormatOptions (every button). Assign a smaller set to show only the commands your application supports; the remaining buttons reflow to close the gaps, and separators adjust automatically.

procedure TForm1.ConfigureFormatButtons;
begin
  // Options is a set of TTMSFNCRichEditorFormatToolBarOption. It defaults to
  // AllFormatOptions (every button). Assign a smaller set to show only those.
  TMSFNCRichEditorFormatToolBar1.Options :=
    [ftoFontName, ftoFontSize,
     ftoBold, ftoItalic, ftoUnderline,
     ftoAlignLeft, ftoAlignCenter, ftoAlignRight,
     ftoTextColor, ftoBackgroundColor,
     ftoBullets, ftoNumbering];

  // Add or remove individual buttons instead of reassigning the whole set.
  TMSFNCRichEditorFormatToolBar1.Options :=
    TMSFNCRichEditorFormatToolBar1.Options + [ftoHyperlink, ftoImage] - [ftoStrikeout];
end;

The available option values map one-to-one to the toolbar buttons:

Option Button
ftoFontName, ftoFontSize Font name and size pickers
ftoBold, ftoItalic, ftoUnderline, ftoStrikeout Character style buttons
ftoAlignLeft, ftoAlignCenter, ftoAlignRight Paragraph alignment
ftoTextColor, ftoBackgroundColor Text and highlight colour pickers
ftoBullets, ftoNumbering Bulleted and numbered lists
ftoUnindent, ftoIndent Decrease and increase indent
ftoImage, ftoHyperlink Insert image and insert hyperlink

Responding to applied commands

The format toolbar exposes an event for each command, in two flavours:

  • Value events carry the value the user chose: OnApplyFontName (AFontName: string), OnApplyFontSize (AFontSize: Integer), OnApplyTextColor and OnApplyBackgroundColor (AColor: TTMSFNCGraphicsColor), and OnApplyBullets (AIndex: Integer).
  • Plain TNotifyEvent signals report that a command ran without a value: OnApplyBold, OnApplyItalic, OnApplyUnderline, OnApplyStrikeout, OnAlignLeft, OnAlignCenter, OnAlignRight, OnApplyNumbering, OnApplyIndent, OnApplyUnindent, OnInsertHyperlink, and OnInsertBitmap.

Every apply event fires after the toolbar has already applied the change to the bound editor, so a handler is the place to update a status bar, mark the document dirty, or log the action — not to veto it.

procedure TForm1.FormCreate(Sender: TObject);
begin
  TMSFNCRichEditorFormatToolBar1.RichEditor := TMSFNCRichEditor1;

  // Value events carry the value the user picked. They fire AFTER the change
  // has already been applied to the bound editor.
  TMSFNCRichEditorFormatToolBar1.OnApplyFontName  := DoFontNameApplied;
  TMSFNCRichEditorFormatToolBar1.OnApplyFontSize  := DoFontSizeApplied;
  TMSFNCRichEditorFormatToolBar1.OnApplyTextColor := DoTextColorApplied;

  // Plain TNotifyEvent commands only signal that the action ran.
  TMSFNCRichEditorFormatToolBar1.OnApplyBold := DoBoldApplied;
end;

procedure TForm1.DoFontNameApplied(Sender: TObject; AFontName: string);
begin
  StatusBar1.Panels[0].Text := 'Font: ' + AFontName;
end;

procedure TForm1.DoFontSizeApplied(Sender: TObject; AFontSize: Integer);
begin
  StatusBar1.Panels[1].Text := Format('Size: %d', [AFontSize]);
end;

procedure TForm1.DoTextColorApplied(Sender: TObject; AColor: TTMSFNCGraphicsColor);
begin
  // AColor is the color that was just applied to the selection. Mirror it onto
  // a preview shape so the user sees the active text color at a glance.
  ColorPreview.Fill.Color := AColor;
end;

procedure TForm1.DoBoldApplied(Sender: TObject);
begin
  StatusBar1.Panels[3].Text := 'Bold toggled';
end;

Reaching individual buttons and pickers

Sometimes you need to touch one control rather than the whole Options set — disable a command conditionally, relabel a button, or read the picker's current value. Every button and picker has an accessor function: BoldButton, ItalicButton, UnderlineButton, StrikeoutButton, NumberingButton, AlignLeftButton/AlignCenterButton/AlignRightButton, IndentButton/UnindentButton, ImageButton, HyperlinkButton, and the FontNamePicker, FontSizePicker, TextColorPicker, BackgroundColorPicker, and BulletsPicker.

procedure TForm1.CustomizeIndividualButtons;
begin
  // Each button and picker is reachable through an accessor function, so you
  // can fine-tune a single control without rebuilding the toolbar.

  // Disable a command button while leaving it visible.
  TMSFNCRichEditorFormatToolBar1.BoldButton.Enabled := False;

  // Change the caption/tooltip text of the hyperlink button.
  TMSFNCRichEditorFormatToolBar1.HyperlinkButton.Text := 'Link';

  // Read the font name currently shown in the font-name picker.
  ShowMessage('Current font: ' +
    TMSFNCRichEditorFormatToolBar1.FontNamePicker.SelectedFontName);
end;
Tip

Hiding a command with Options removes its button entirely, while disabling a button through its accessor keeps it visible but greyed out. Use Options for commands your app never supports and the accessor for commands that are only sometimes available.

Combining restricted buttons with event handling

A typical setup restricts the toolbar to the commands you support, wires the apply events that keep the rest of your UI in sync, and touches an individual button — all three features of this chapter in one routine:

procedure TForm1.SetupFormatToolBar;
begin
  TMSFNCRichEditorFormatToolBar1.RichEditor := TMSFNCRichEditor1;

  // Restrict the toolbar to a compact command set.
  TMSFNCRichEditorFormatToolBar1.Options :=
    [ftoFontName, ftoFontSize, ftoBold, ftoItalic, ftoUnderline,
     ftoAlignLeft, ftoAlignCenter, ftoAlignRight, ftoTextColor];

  // Mirror the applied font name into a status bar panel.
  TMSFNCRichEditorFormatToolBar1.OnApplyFontName := DoFontNameApplied;

  // Start with strikeout unavailable until a document is loaded.
  TMSFNCRichEditorFormatToolBar1.BoldButton.Enabled := True;
end;

procedure TForm1.DoFontNameApplied(Sender: TObject; AFontName: string);
begin
  StatusBar1.Panels[0].Text := 'Font: ' + AFontName;
end;

Pitfalls

  • Apply events do not fire for programmatic editor changes. They report toolbar commands. Changing the editor's content in code does not raise OnApplyBold and friends.
  • ftoTextColor is the font colour; ftoBackgroundColor is the highlight. There is no FontColor option — use ftoTextColor for the text colour picker.

See also