Table of Contents

Compact Mode and the Options Menu

Toolbars have to survive narrow windows. TTMSFNCToolBar handles this automatically: when it no longer has room for every element it compacts and moves the overflow into an options menu, so no command becomes unreachable. This chapter covers compacting, the options (overflow) menu and its events, and the always-visible quick-menu button. It builds on the elements from Buttons and pickers.

Let the toolbar compact

Enable CanCompact and set CompactWidth — the width below which the toolbar collapses. Below that threshold, elements that no longer fit move into the options menu (see below). OnCustomizeCompactToolBar hands you the generated compact toolbar so you can adjust it before it is shown, and OnCompactClick fires when the compact button is activated.

procedure TForm1.EnableCompactMode;
begin
  // Below CompactWidth the toolbar collapses and moves overflowing commands
  // into the options (overflow) menu, so nothing becomes unreachable.
  TMSFNCToolBar1.CanCompact := True;
  TMSFNCToolBar1.CompactWidth := 240;
  TMSFNCToolBar1.OptionsMenu.ShowButton := True;
  TMSFNCToolBar1.OptionsMenu.ShowItemText := True;
  TMSFNCToolBar1.OptionsMenu.ShowItemBitmap := True;

  TMSFNCToolBar1.OnCustomizeCompactToolBar := CustomizeCompact;
  TMSFNCToolBar1.Build;
end;

procedure TForm1.CustomizeCompact(Sender: TObject; ACompactToolBar: TTMSFNCToolBar);
begin
  // Adjust the generated compact toolbar before it is shown to the user.
  ACompactToolBar.Appearance.Fill.Kind := gfkSolid;
  ACompactToolBar.Appearance.Fill.Color := gcWhitesmoke;
end;
Toolbar collapsed into compact mode on a narrow surface Toolbar collapsed into compact mode on a narrow surface

The options (overflow) menu

The options menu is the overflow surface for commands that do not fit. Its OptionsMenu sub-object controls the trigger button and item rendering: ShowButton keeps the overflow button visible, and ShowItemBitmap / ShowItemText decide whether each item shows the command's icon, label, or both. AutoItemBitmapWidth and ItemBitmapWidth size the bitmap column.

Three events shape the menu at runtime:

  • OnOptionsMenuCustomize — add your own items to the popup before it shows.
  • OnOptionsMenuItemCanShow — veto individual commands from the overflow.
  • OnOptionsMenuItemClick — handle a click, optionally suppressing the element's own default action.
procedure TForm1.ConfigureOptionsMenu;
begin
  // Always show the overflow button, with bitmaps and text on each item.
  TMSFNCToolBar1.OptionsMenu.ShowButton := True;
  TMSFNCToolBar1.OptionsMenu.ShowItemBitmap := True;
  TMSFNCToolBar1.OptionsMenu.ShowItemText := True;

  TMSFNCToolBar1.OnOptionsMenuCustomize := OptionsMenuCustomize;
  TMSFNCToolBar1.OnOptionsMenuItemCanShow := OptionsMenuItemCanShow;
  TMSFNCToolBar1.OnOptionsMenuItemClick := OptionsMenuItemClick;
end;

procedure TForm1.OptionsMenuCustomize(Sender: TObject; APopupMenu: TPopupMenu);
begin
  { Add your own items to APopupMenu before the overflow menu is shown. }
end;

procedure TForm1.OptionsMenuItemCanShow(Sender: TObject; AControl: TControl;
  var ACanShowItem: Boolean);
begin
  // Keep a specific command out of the overflow menu.
  ACanShowItem := AControl <> DebugButton;
end;

procedure TForm1.OptionsMenuItemClick(Sender: TObject; AControl: TControl;
  AMenuItem: TMenuItem; var AExecuteDefaultAction: Boolean);
begin
  // AControl is the toolbar element the menu item represents. Set
  // AExecuteDefaultAction := False to suppress the element's own click.
end;

The quick-menu button

Separate from overflow, QuickMenuButton adds an always-visible button at the toolbar's leading edge for a quick-access menu of your own. Set QuickMenuButtonHint for its tooltip and handle OnQuickMenuButtonClick to show your menu.

Combining a quick menu, compacting, and overflow

The example below builds a command-heavy toolbar with a quick-menu button, then enables compacting and a customized options menu so every command stays reachable as the window narrows:

procedure TForm1.BuildResponsiveToolBar;
var
  i: Integer;
  Button: TTMSFNCToolBarButton;
begin
  TMSFNCToolBar1.BeginUpdate;
  try
    // A quick-access menu button stays visible at the toolbar's leading edge.
    TMSFNCToolBar1.QuickMenuButton := True;
    TMSFNCToolBar1.QuickMenuButtonHint := 'Quick actions';
    TMSFNCToolBar1.OnQuickMenuButtonClick := QuickMenuClick;

    // Enough commands that the toolbar overflows on a narrow window.
    for i := 1 to 8 do
    begin
      Button := TMSFNCToolBar1.AddButton(-1, -1, '', '', 'Command ' + IntToStr(i));
      Button.OnClick := CommandClick;
    end;

    // Compacting plus the overflow options menu keep every command reachable.
    TMSFNCToolBar1.CanCompact := True;
    TMSFNCToolBar1.CompactWidth := 260;
    TMSFNCToolBar1.OptionsMenu.ShowButton := True;
    TMSFNCToolBar1.OptionsMenu.ShowItemText := True;
    TMSFNCToolBar1.OnOptionsMenuItemClick := OverflowItemClick;
  finally
    TMSFNCToolBar1.EndUpdate;
  end;
  TMSFNCToolBar1.Build;
end;

procedure TForm1.QuickMenuClick(Sender: TObject);
begin
  { Show your quick-access menu next to the quick-menu button. }
end;

procedure TForm1.CommandClick(Sender: TObject);
begin
  { Run the command represented by Sender (a TTMSFNCToolBarButton). }
end;

procedure TForm1.OverflowItemClick(Sender: TObject; AControl: TControl;
  AMenuItem: TMenuItem; var AExecuteDefaultAction: Boolean);
begin
  { Handle a click on an overflowed command in the options menu. }
end;
Responsive toolbar with a quick-menu button and an overflow options button Responsive toolbar with a quick-menu button and an overflow options button

Common mistakes

  • Expecting overflow without CanCompact. The options menu only receives overflowed commands when compacting is enabled and the toolbar is narrower than CompactWidth.
  • A CompactWidth larger than the toolbar ever gets. If the threshold is wider than the toolbar's actual width, it compacts permanently; size it to the point where content genuinely stops fitting.
  • Rebuilding inside OnCustomizeCompactToolBar. Adjust the supplied compact toolbar's properties; do not tear it down and recreate it — it is generated and owned by the host toolbar.
  • TTMSFNCToolBar — CanCompact, Compact, CompactWidth, OptionsMenu, QuickMenuButton, OnCustomizeCompactToolBar, OnOptionsMenuItemClick

See Also