Table of Contents

Tabs

Tabs are stored in the Tabs collection. Add tabs when the user needs to switch between views, filter contexts, documents, or work areas without leaving the current screen.

TabSet with tabs, a badge, a progress tab and close buttons TabSet with tabs, a badge, a progress tab and close buttons

Creating tabs

Use AddTab or Tabs.Add to create tabs from code. Wrap larger changes in BeginUpdate and EndUpdate so the control redraws once after the batch is complete.

procedure TForm1.CreateDocumentTabs;
var
  Tab: TTMSFNCTabSetTab;
begin
  TMSFNCTabSet1.BeginUpdate;
  try
    TMSFNCTabSet1.Tabs.Clear;

    Tab := TMSFNCTabSet1.AddTab('Overview');
    Tab.Hint := 'Project overview';

    Tab := TMSFNCTabSet1.AddTab('Reports');
    Tab.BitmapVisible := True;
    Tab.BitmapSize := 18;
    Tab.Bitmaps.Add.Bitmap.LoadFromFile('reports.png');

    Tab := TMSFNCTabSet1.AddTab('Archive');
    Tab.Enabled := False;
  finally
    TMSFNCTabSet1.EndUpdate;
  end;
end;

Tab properties

Property Description
Text Tab label
TextVisible Shows or hides the label
TextAlign Text alignment when UseDefaultAppearance is False
Trimming Trims text that is too long for the tab
WordWrapping Wraps text inside the tab
Enabled Enables or disables the tab
TabVisible Shows the tab in the visible tab strip
Width Tab width when TabSize.Mode uses a fixed-width mode
Hint Tooltip text when hints are enabled on the control
UseDefaultAppearance Uses TabAppearance when True; uses tab-level colors and shape when False

Per-tab appearance

Set UseDefaultAppearance to False when a tab needs its own visual state. The tab then uses its Color, ActiveColor, HoverColor, DownColor, DisabledColor, TextColor, ActiveTextColor, HoverTextColor, DownTextColor, DisabledTextColor, and Shape properties.

Use default appearance for most tabs and override only the tabs that communicate status or priority. This keeps the control easier to scan.

Bitmap icons

Attach bitmap icons to a tab with the Bitmaps collection and enable BitmapVisible. Bitmaps is deliberately a collection rather than a single bitmap: it is a TTMSFNCScaledBitmaps, and every entry carries its own Scale. When the tab paints its icon it asks the collection for the entry matching the monitor's display scale and falls back to the largest entry when there is no exact match. A single 18x18 PNG that looks right at 100% therefore turns soft on a 150% or 200% display, while a 27x27 and 36x36 sibling stay sharp — this is what the high-DPI support added in 1.0.1.0 resolves against.

Keep BitmapSize at the logical (design) size; it frames the icon, while the collection supplies the pixels. Disabled tabs draw from a separate DisabledBitmaps collection, so a greyed icon needs its own scaled variants.

procedure TForm1.BuildScaledTabIcons;
var
  Tab: TTMSFNCTabSetTab;
begin
  TMSFNCTabSet1.BeginUpdate;
  try
    Tab := TMSFNCTabSet1.AddTab('Reports');
    Tab.BitmapVisible := True;

    { BitmapSize frames the icon in logical units - keep it at the design-time
      value. The pixels come from the collection below. }
    Tab.BitmapSize := 18;

    { Bitmaps is a TTMSFNCScaledBitmaps collection: one entry per display scale.
      The tab asks the collection for the entry matching the monitor's scale and
      falls back to the largest entry when there is no exact match, so shipping
      1.0 / 1.5 / 2.0 covers 100%, 150% and 200% displays. }
    Tab.Bitmaps.Clear;
    Tab.Bitmaps.AddBitmapFromFile('reports.png', 1.0);
    Tab.Bitmaps.AddBitmapFromFile('reports@1.5x.png', 1.5);
    Tab.Bitmaps.AddBitmapFromFile('reports@2x.png', 2.0);

    { DisabledBitmaps is a separate collection with the same shape, so a greyed
      icon needs its own set of scaled variants. }
    Tab.DisabledBitmaps.Clear;
    Tab.DisabledBitmaps.AddBitmapFromFile('reports-disabled.png', 1.0);
    Tab.DisabledBitmaps.AddBitmapFromFile('reports-disabled@2x.png', 2.0);

    { When the icons live in the tab set's shared BitmapContainer, register the
      container item name per scale instead of loading a file. Each entry
      resolves its own name, so give the variants distinct names. }
    TMSFNCTabSet1.BitmapContainer := TMSFNCBitmapContainer1;
    Tab := TMSFNCTabSet1.AddTab('Archive');
    Tab.BitmapVisible := True;
    Tab.Bitmaps.Clear;
    Tab.Bitmaps.AddBitmapName('archive-1x', 1.0);
    Tab.Bitmaps.AddBitmapName('archive-2x', 2.0);
  finally
    TMSFNCTabSet1.EndUpdate;
  end;

  if TTMSFNCUtils.IsHighDPIScale(Self) then
    StatusLabel.Text := Format('Tab icons resolved at %.2fx',
      [TTMSFNCUtils.GetDPIScale(Self)]);
end;

An entry may name a bitmap in the tab set's BitmapContainer instead of holding one (AddBitmapName). Each entry resolves its own name, so give the variants distinct container names rather than reusing one name across scales.

Badges

Badges are compact status indicators. They work well for unread counts, validation warnings, or pending actions.

procedure TForm1.ConfigureStatusTabs;
var
  DownloadsTab: TTMSFNCTabSetTab;
  MessagesTab: TTMSFNCTabSetTab;
begin
  TMSFNCTabSet1.BeginUpdate;
  try
    TMSFNCTabSet1.Options.CloseMode := tcmTab;
    TMSFNCTabSet1.Options.CloseAction := ttcaHide;
    TMSFNCTabSet1.Options.TabListButton := True;

    DownloadsTab := TMSFNCTabSet1.AddTab('Downloads');
    DownloadsTab.BitmapVisible := True;
    DownloadsTab.BitmapSize := 18;
    DownloadsTab.Bitmaps.Add.Bitmap.LoadFromFile('download.png');
    DownloadsTab.ProgressKind := tpkRectangular;
    DownloadsTab.ProgressMode := tpmNormal;
    DownloadsTab.ProgressMax := 100;
    DownloadsTab.Progress := 72;
    DownloadsTab.CloseButton := True;

    MessagesTab := TMSFNCTabSet1.AddTab('Messages');
    MessagesTab.Badge := '12';
    MessagesTab.BadgeColor := gcOrange;
    MessagesTab.BadgeTextColor := gcWhite;
    MessagesTab.CloseButton := True;
  finally
    TMSFNCTabSet1.EndUpdate;
  end;
end;

Progress indicators

Tabs support rectangular and circular progress indicators.

Property Description
ProgressKind tpkNone, tpkCircular, or tpkRectangular
ProgressMode tpmNormal or tpmMarquee
Progress Current progress value
ProgressMax Maximum progress value
ProgressColor Tab-level progress color when UseDefaultAppearance is False

Close buttons

Close buttons can appear on individual tabs when Options.CloseMode is tcmTab.

Property Description
CloseButton Shows or hides the close button on a tab
Options.CloseMode Uses tcmTab for per-tab close buttons or tcmMenu for a menu button
Options.CloseAction Uses ttcaFree to destroy a tab or ttcaHide to move it to the hidden-tab list

When Options.CloseAction is ttcaHide, enable Options.TabListButton so users can restore hidden tabs.

Combining tab creation, badges, and progress indicators

Create tabs with bitmap icons, attach badge counts, show a circular progress indicator, and enable per-tab close buttons:

procedure TForm1.FormCreate(Sender: TObject);
var
  tab: TTMSFNCTabSetTab;
begin
  // The bitmap container is assigned on the control, not on a tab.
  TMSFNCTabSet1.BitmapContainer := TMSFNCBitmapContainer1;

  TMSFNCTabSet1.BeginUpdate;
  try
    TMSFNCTabSet1.Tabs.Clear;

    // Inbox with an icon and an unread badge.
    tab := TMSFNCTabSet1.AddTab('Inbox');
    tab.Bitmaps.AddBitmapName('inbox');
    tab.BitmapVisible := True;
    tab.Badge := '12';
    tab.CloseButton := True;

    // Downloads with a circular progress indicator.
    tab := TMSFNCTabSet1.AddTab('Downloads');
    tab.Bitmaps.AddBitmapName('download');
    tab.BitmapVisible := True;
    tab.ProgressKind := tpkCircular;
    tab.ProgressMode := tpmNormal;
    tab.Progress := 45;
    tab.ProgressMax := 100;
    tab.CloseButton := True;

    // Shared close behaviour: hide on close, with a tab-list button to restore.
    TMSFNCTabSet1.Options.CloseMode := tcmTab;
    TMSFNCTabSet1.Options.CloseAction := ttcaHide;
    TMSFNCTabSet1.Options.TabListButton := True;
  finally
    TMSFNCTabSet1.EndUpdate;
  end;
end;

See also