TTMSFNCNavigationPanel

The TTMSFNCNavigationPanel displays a set of TTMSFNCPanel instances based on a panel collection. The navigation panel can display items, buttons and has a separate compact mode.

Properties

Property name	Description
ActivePanelIndex	Property to get or set the active panel.
BitmapContainer	Property to assign a TTMSFNCBitmapContainer instance in order to retrieve bitmaps via a name.
ButtonsAppearance	A set of properties to configure the buttons appearance at the bottom of the navigation panel.
CompactMode	Switches between normal and compact mode. In compact mode the CompactModeSize is applied to the width.
CompactModeSize	The width of the navigation panel in compact mode.
ItemsAppearance	A set of properties to configure the items appearance.
MaxButtonCount	The maximum number of buttons shown in the buttons area. If the number of buttons exceed this number the buttons are automatically added to the context menu, shown with the options button
MaxItemCount	The maximum number of items shown in the items area. If the number of items exceed this number the items are automatically added to the context menu, shown with the options button.
Mode	The mode of the navigation panel. The default mode is mixed, to show items and buttons. The other modes are configured to only display items, or only display buttons.
Panels[Index]	The panel items collection.
ShowCompactModeButton	Shows or hides the compact mode button in the header of the panel.
ShowFooter	Shows or hides the footer of each panel inside the navigation panel.
ShowHeader	Shows or hides the header of each panel inside the navigation panel.
Splitter	The splitter of the navigation panel to show more or less items.

Methods

Method name	Description
AddPanel	Adds a new panel.
InsertPanel	Inserts a new panel at a specific index.
MovePanel	Moves an existing panel to a specific index.
RemovePanel	Removes an existing panel.
SelectNextPanel	Selects the next panel starting from the active panel index.
SelectPanel	Selects a specific panel.
SelectPreviousPanel	Selects the previous panel starting from the active panel index.
SplitItems	Converts / splits a number of items in buttons.

Events

Event name	Description
OnAfterDrawButton	Event called after a button is drawn.
OnAfterDrawCompactItem	Event called after a compact item is drawn.
OnAfterDrawItem	Event called after an item is drawn.
OnAfterDrawItemBadge	Event called after a badge is drawn.
OnAfterDrawOptionsButton	Event called after the options button is drawn.
OnAfterDrawSplitter	Event called after a splitter is drawn.
OnBeforeDrawButton	Event called before a button is drawn.
OnBeforeDrawCompactItem	Event called before a compact item is drawn.
OnBeforeDrawItem	Event called before an item is drawn.
OnBeforeDrawItemBadge	Event called before a badge is drawn.
OnBeforeDrawOptionsButton	Event called before the options button is drawn.
OnBeforeDrawSplitter	Event called before a splitter is drawn.
OnCompactItemClick	Event called when an item in compact mode is clicked.
OnCustomizeContextMenu	Event called to further customize the context menu shown from the options menu button.
OnItemAnchorClick	Event called when an anchor is clicked at a specific item.
OnItemClick	Event called when an item is clicked.
OnSplitterMove	Event called when the splitter is moved.

Adding new panels

By default the NavigationPanel is initialized with three panels. Adding new panels can be done by using the panels collection directly or by using the helper methods as demonstrated below.

TMSFNCNavigationPanel1.Panels.Clear;
TMSFNCNavigationPanel1.AddPanel('New Panel');

Removing panels

To remove an existing panel, you can use the panels collection directly or use the RemovePanel helper method as demonstrated below.

TMSFNCNavigationPanel1.RemovePanel(0);

Before

After

Moving panels

To move a panel to a different location, changing the index of the panel collection item is sufficient, or you can also use the MovePanel method as demonstrated below. You might notice here that the ActivePanelIndex is set to the new index. The MovePanel function automatically changes the ActivePanelIndex.

TMSFNCNavigationPanel1.MovePanel(0, 1);

Before

After

Modes

The navigation panel supports three modes.

• npmItems Setting the mode property to npmItems will show the items in the panel collection above the buttons area. Using the splitter to hide items will not show them as buttons but instead will add them as menu items in the options menu.

• npmButtons Setting the mode property to npmButtons will show the items in the panel collection as buttons inside the buttons area. There is no splitter as there will also be no items above the buttons area. The buttons are shown from right left and are automatically added as menu items to the options menu when they would exceed the available size.

• npmMixed (default) Setting the mode property to npmMixed will show the items in the panel collection above the buttons area and inside the buttons area, depending on the Kind property. When the kind property is set to pikItem, the panel item is added as an item above the buttons area. When the kind property is set to pikButton, the panel item is added as a button inside the buttons area. When the splitter is moved, the items are added as buttons when moving down, and buttons are converted to items when moving up. When the available size is exceeded or the maximum number of items / buttons is exceeded, then the panel items are added as entries in the options menu.

Compact Mode

The navigation panel has a separate compact mode that can be activated programmatically via the CompactMode property or visually via the compact mode button inside the panel. By default the header of the panel contains a compact button (optionally shown with ShowCompactModeButton) as shown in the screenshot below, and when clicking it, the panel width is reduced to the CompactModeSize property.

Normal mode	Compact mode

In the compact mode, the items are reduced to bitmap only, and the content of the panel disappears. The content area is then filled with a separate button and contains vertical text that is set with the CompactText property of a panel item. The button also has a separate compact appearance under the ItemsAppearance property. When clicking this button the OnCompactItemClick event is triggered.

Options Menu

As already explained in the modes chapter, when some items are set unvisible, or are hidden during a splitter or resize operation they are transferred to the options menu. The options menu is shown after clicking on the three-dotted button at the buttons area. This button can optionally be shown using the ButtonsAppearance.ShowOptionsButton (True by default). Clicking on this button shows a context menu with the hidden items, the ability to show more or less items above the buttons area and the list of items to add or remove from the visible items / buttons lists.

In the sample below, the MaxButtonCount property is set to 1, which means that when dragging the splitter down, only one item will be converted as a button item, and the rest of the items will be added to the options menu. As they are three items, and one item remains in the items area, there is one additional item available in the options menu. Clicking that item will show the corresponding panel and trigger the OnItemClick event.

Appearance

The appearance of the navigation panel can be customized in three areas: the items area, the buttons area and the panel area. The items area is customized with the ItemsAppearance property where each state (normal, disabled, hover, down and active) of the item can be customized. The same applies to the buttons area, where the ButtonsAppearance property is responsible for the appearance of each button and its state. The buttons have the same states as the items. The panel header, footer and content area is styled by the panel itself. The panel can be accessed at designtime / runtime and has separate property to control the appearance. Below is a sample that customizes the appearance of the navigation panel.

var
 I: Integer;
begin
 Fill.Color := gcWhite;
 Fill.Kind := TBrushKind.Solid;
 TMSFNCNavigationPanel1.ButtonsAppearance.BackgroundFill.Color := gcSteelblue;
 TMSFNCNavigationPanel1.ButtonsAppearance.OptionsMenuButtonBulletColor := gcWhite;
 TMSFNCNavigationPanel1.ButtonsAppearance.BackgroundStroke.Color := gcDarkblue;
 TMSFNCNavigationPanel1.ButtonsAppearance.Stroke.Color := gcDarkblue;
 TMSFNCNavigationPanel1.ButtonsAppearance.ActiveFill.Color := gcDarkblue;
 TMSFNCNavigationPanel1.ButtonsAppearance.ActiveStroke.Color := gcDarkblue;
 TMSFNCNavigationPanel1.ButtonsAppearance.HoverStroke.Color := gcDarkblue;
 TMSFNCNavigationPanel1.ButtonsAppearance.DownStroke.Color := gcDarkblue;
 TMSFNCNavigationPanel1.ItemsAppearance.Stroke.Color := gcDarkblue;
 TMSFNCNavigationPanel1.ItemsAppearance.ActiveFill.Color := gcDarkblue;
 TMSFNCNavigationPanel1.ItemsAppearance.ActiveStroke.Color := gcDarkblue;
 TMSFNCNavigationPanel1.ItemsAppearance.HoverStroke.Color := gcDarkblue;
TMSFNCNavigationPanel1.ItemsAppearance.DownStroke.Color := gcDarkblue;
 TMSFNCNavigationPanel1.Splitter.Fill.Color := gcDarkblue;
 TMSFNCNavigationPanel1.Splitter.Stroke.Color := gcDarkblue;
 TMSFNCNavigationPanel1.Splitter.BulletColor := gcWhite;
 TMSFNCNavigationPanel1.Stroke.Color := gcDarkBlue;

 for I := 0 to TMSFNCNavigationPanel1.Panels.Count - 1 do
 begin
 TMSFNCNavigationPanel1.Panels[I].Container.Header.Fill.Color := gcSteelBlue;
 TMSFNCNavigationPanel1.Panels[I].Container.Header.Font.Color := gcWhite;
 TMSFNCNavigationPanel1.Panels[I].Container.Header.Stroke.Color := gcDarkblue;
 TMSFNCNavigationPanel1.Panels[I].Container.Fill.Color := gcLightsteelblue;
 TMSFNCNavigationPanel1.Panels[I].Container.Stroke.Color := gcDarkblue;
 end;

Badges

Each panel item can display a badge, at the right side of the item. The badge can be any text you like, including HTML formatted text. Badges are separately styled with the Badge* properties under ItemsAppearance. Below is a sample that displays a simple numeric badge as well as a completely styled HTML formatted text with images badge.

TMSFNCNavigationPanel1.Panels[0].Badge := '5';

TMSFNCNavigationPanel1.ItemsAppearance.BadgeFill.Color := gcYellowgreen;
TMSFNCNavigationPanel1.ItemsAppearance.BadgeFont.Color := gcBlack;
TMSFNCNavigationPanel1.ItemsAppearance.BadgeStroke.Color := gcBlack;
TMSFNCNavigationPanel1.BitmapContainer := TMSFNCBitmapContainer1;
TMSFNCNavigationPanel1.Panels[0].Badge := '<p> <img
src="'+TMSFNCBitmapContainer1.RandomBitmapName+'"/> calendar</p>';