Table of Contents

Docking Toolbars

Applications rarely have just one toolbar. TTMSFNCDockPanel hosts several toolbars in a single docked region — a file bar next to a formatting bar, for example — and arranges them for you. Combined with the drag grip, it gives users a familiar, rearrangeable command area. This chapter covers stacking toolbars on a dock panel and enabling the drag grip. It builds on the toolbars from Buttons and pickers.

Stack toolbars on a dock panel

Drop a TTMSFNCDockPanel, then call AddToolBar for each toolbar it should host — each call returns a fully functional TTMSFNCToolBar you populate as usual. The dock panel arranges the toolbars into a row and sizes itself when AutoSize is on. Wrap the setup in BeginUpdate/EndUpdate so the panel lays out once.

procedure TForm1.BuildDockedToolBars;
var
  fileBar, formatBar: TTMSFNCToolBar;
begin
  TMSFNCDockPanel1.BeginUpdate;
  try
    TMSFNCDockPanel1.AutoSize := True;

    // Each AddToolBar returns a toolbar the dock panel arranges into a row.
    fileBar := TMSFNCDockPanel1.AddToolBar;
    fileBar.AddButton(-1, -1, '', '', 'New');
    fileBar.AddButton(-1, -1, '', '', 'Open');
    fileBar.AddButton(-1, -1, '', '', 'Save');

    formatBar := TMSFNCDockPanel1.AddToolBar;
    formatBar.AddFontNamePicker;
    formatBar.AddFontSizePicker;
    formatBar.AddColorPicker;
  finally
    TMSFNCDockPanel1.EndUpdate;
  end;
end;
Dock panel hosting a file toolbar and a formatting toolbar Dock panel hosting a file toolbar and a formatting toolbar

The drag grip

A toolbar's Appearance.DragGrip draws a grip handle at its leading edge that users can drag. Track the movement with OnDragGripMoving, which reports the horizontal and vertical delta as the toolbar is dragged — use it to reposition a floating toolbar or to persist the user's layout.

procedure TForm1.EnableDragGrip;
begin
  // Draw a drag-grip handle at the toolbar edge and track dragging.
  TMSFNCToolBar1.Appearance.DragGrip := True;
  TMSFNCToolBar1.OnDragGripMoving := ToolBarDragGripMoving;
end;

procedure TForm1.ToolBarDragGripMoving(Sender: TObject; DeltaX, DeltaY: Double);
begin
  // DeltaX/DeltaY report how far the toolbar has moved since the drag started.
  StatusBar1.SimpleText := Format('Moved %.0f, %.0f', [DeltaX, DeltaY]);
end;

Combining docked toolbars with drag grips

The example below builds an editor command area: a dock panel hosting a file toolbar and a formatting toolbar, each with its own drag grip so users can rearrange them.

procedure TForm1.BuildEditorDock;
var
  fileBar, formatBar: TTMSFNCToolBar;
begin
  TMSFNCDockPanel1.BeginUpdate;
  try
    TMSFNCDockPanel1.AutoSize := True;

    fileBar := TMSFNCDockPanel1.AddToolBar;
    fileBar.Appearance.DragGrip := True;
    fileBar.AddButton(-1, -1, '', '', 'New');
    fileBar.AddButton(-1, -1, '', '', 'Open');
    fileBar.AddButton(-1, -1, '', '', 'Save');

    formatBar := TMSFNCDockPanel1.AddToolBar;
    formatBar.Appearance.DragGrip := True;
    formatBar.AddFontNamePicker;
    formatBar.AddFontSizePicker;
    formatBar.AddColorPicker;
  finally
    TMSFNCDockPanel1.EndUpdate;
  end;
end;
Dock panel with two draggable toolbars, each showing a drag grip Dock panel with two draggable toolbars, each showing a drag grip

The popup toolbar

TTMSFNCToolBarPopup is a floating variant of the toolbar: a small popup window of buttons you show on demand near a control — a lightweight actions menu or context toolbar. Instead of adding controls to a docked bar, you fill its Buttons collection, anchor it with PlacementControl (and Placement), handle OnButtonClick, and call Activate to show it. It exposes the underlying toolbar through its read-only ToolBar property if you need finer control.

procedure TForm1.ShowActionsPopup;
var
  btn: TTMSFNCToolBarPopupButton;
begin
  TMSFNCToolBarPopup1.Buttons.Clear;

  btn := TMSFNCToolBarPopup1.Buttons.Add;
  btn.Text := 'Cut';
  btn := TMSFNCToolBarPopup1.Buttons.Add;
  btn.Text := 'Copy';
  btn := TMSFNCToolBarPopup1.Buttons.Add;
  btn.Text := 'Paste';

  // Anchor the popup near a control, then show it.
  TMSFNCToolBarPopup1.PlacementControl := ActionsButton;
  TMSFNCToolBarPopup1.Placement := ppBottom;
  TMSFNCToolBarPopup1.OnButtonClick := PopupButtonClick;
  TMSFNCToolBarPopup1.Activate;
end;

procedure TForm1.PopupButtonClick(Sender: TObject; AButton: TTMSFNCToolBarPopupButton);
begin
  // AButton is the clicked item from the Buttons collection.
  ShowMessage(AButton.Text + ' clicked');
end;

Common mistakes

  • Parenting toolbars directly instead of via AddToolBar. Let the dock panel create its toolbars through AddToolBar so they are docked and arranged; a toolbar merely parented onto the panel is not managed by it.
  • AutoSize off with no explicit size. With AutoSize disabled, give the dock panel a height that fits its toolbars, or they will be clipped.

See Also