Skip to main content
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.

Stack multiple toolbars on a dock panelPascalC++
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;

void __fastcall TForm1::BuildDockedToolBars()
{
  TTMSFNCToolBar *fileBar, *formatBar;
  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();
  }
}
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.

Show a drag grip and track draggingPascalC++
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;

void __fastcall TForm1::EnableDragGrip()
{
  // Draw a drag-grip handle at the toolbar edge and track dragging.
  TMSFNCToolBar1->Appearance->DragGrip = true;
  TMSFNCToolBar1->OnDragGripMoving = ToolBarDragGripMoving;
}

void __fastcall TForm1::ToolBarDragGripMoving(TObject *Sender, double DeltaX, double DeltaY)
{
  // DeltaX/DeltaY report how far the toolbar has moved since the drag started.
  StatusLabel->Text = Format("Moved %.0f, %.0f", ARRAYOFCONST(((Extended)DeltaX, (Extended)DeltaY)));
}

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.

Dock two draggable toolbars with a branded panelPascalC++
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;

void __fastcall TForm1::BuildEditorDock()
{
  TTMSFNCToolBar *fileBar, *formatBar;
  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();
  }
}
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.

Show a floating popup toolbar of buttonsPascalC++
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;

void __fastcall TForm1::ShowActionsPopup()
{
  TMSFNCToolBarPopup1->Buttons->Clear();

  Fmx::Tmsfnctoolbarpopup::TTMSFNCToolBarPopupButton *btn = static_cast<Fmx::Tmsfnctoolbarpopup::TTMSFNCToolBarPopupButton *>(TMSFNCToolBarPopup1->Buttons->Add());
  btn->Text = "Cut";
  btn = static_cast<Fmx::Tmsfnctoolbarpopup::TTMSFNCToolBarPopupButton *>(TMSFNCToolBarPopup1->Buttons->Add());
  btn->Text = "Copy";
  btn = static_cast<Fmx::Tmsfnctoolbarpopup::TTMSFNCToolBarPopupButton *>(TMSFNCToolBarPopup1->Buttons->Add());
  btn->Text = "Paste";

  // Anchor the popup near a control, then show it.
  TMSFNCToolBarPopup1->PlacementControl = ActionsButton;
  TMSFNCToolBarPopup1->Placement = ppBottom;
  TMSFNCToolBarPopup1->OnButtonClick = PopupButtonClick;
  auto popup = TMSFNCToolBarPopup1;
  popup->Activate();
}

void __fastcall TForm1::PopupButtonClick(TObject *Sender, Fmx::Tmsfnctoolbarpopup::TTMSFNCToolBarPopupButton *AButton)
{
  // AButton is the clicked item from the Buttons collection.
  ShowMessage(AButton->Text + " clicked");
}

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