TTMSFNCPopupMenu
TTMSFNCPopupMenu is a cross-platform popup menu component that provides a modern, customizable context menu solution for Windows and macOS applications.
It supports rich styling, multiple menu item types, sub-menus, embedded controls, and advanced appearance customization.
Integrated in TMS FNC Core, it ensures a consistent user experience across platforms and TMS Products.
How to Use TTMSFNCPopupMenu
The popup menu can be attached to any control or displayed programmatically. It supports a hierarchical structure with different item types, including checkable items and embedded UI controls.
- Create and display context menus with hierarchical structure.
- Support for various menu item types including standard items, separators, checkable items, and toolbar containers.
- Embed simple custom controls within menu items for enhanced functionality.
- Customize appearance with extensive styling options for professional-looking menus.
Important distinction between TTMSFNCMenuItem and TTMSFNCMenuItemControl
TTMSFNCMenuItem is used to define the structure and content of the menu within the Items collection. It holds the configuration such as text, icons, event handlers, and sub-items.
TTMSFNCMenuItemControl is the visual control that is dynamically created when the popup menu is shown. It represents the rendered menu item based on the properties of its associated TTMSFNCMenuItem.
In most popup menu events, you will be working with TTMSFNCMenuItemControl as the sender or parameter. However, you can always access the underlying TTMSFNCMenuItem via its MenuItem property if you need to reference the original configuration.
1. Basic Menu Creation and Display
The TTMSFNCPopupMenu can be used as a context menu for any control or displayed programmatically at specific screen coordinates.
uses
..., FMX.TMSFNCPopupMenu;
procedure TForm1.CreateBasicMenu;
var
MenuItem: TTMSFNCMenuItem;
begin
// Create menu items
MenuItem := TMSFNCPopupMenu1.AddMenuItem('Copy');
MenuItem.OnClick := CopyClick;
MenuItem := TMSFNCPopupMenu1.AddMenuItem('Paste');
MenuItem.OnClick := PasteClick;
// Add a separator
TMSFNCPopupMenu1.AddMenuSeparatorItem;
// Add a submenu
MenuItem := TMSFNCPopupMenu1.AddMenuItem('Options');
MenuItem.AddMenuItem('Option 1');
MenuItem.AddMenuItem('Option 2');
// Assign popup menu to a control
MyControl.PopupMenu := TMSFNCPopupMenu1;
end;
// Or display programmatically
procedure TForm1.ShowContextMenu(X, Y: Single);
begin
TMSFNCPopupMenu1.Popup(X, Y);
end;
2. Working with Checkable Items and Groups
Create radio groups and checkbox items for user selections.
uses
..., FMX.TMSFNCPopupMenu;
procedure TForm1.CreateCheckableItems;
var
MenuItem: TTMSFNCMenuItem;
begin
// Create radio group items
MenuItem := TMSFNCPopupMenu1.AddMenuItem('Small', mitCheck);
MenuItem.GroupName := 'Size';
MenuItem.Checked := True;
MenuItem := TMSFNCPopupMenu1.AddMenuItem('Medium', mitCheck);
MenuItem.GroupName := 'Size';
MenuItem := TMSFNCPopupMenu1.AddMenuItem('Large', mitCheck);
MenuItem.GroupName := 'Size';
// Add separator
TMSFNCPopupMenu1.AddMenuSeparatorItem;
// Create standalone checkbox
MenuItem := TMSFNCPopupMenu1.AddMenuItem('Enable Notifications', mitCheck);
MenuItem.Checked := True;
TMSFNCPopupMenu1.AddMenuItem('Show Size').OnClick := GetSelectedSize;
end;
procedure TForm4.GetSelectedSize(Sender: TObject);
var
MenuItem: TTMSFNCMenuItem;
begin
// Get the checked item from a group
MenuItem := TMSFNCPopupMenu1.GetCheckedMenuItemByGroupName('Size');
if Assigned(MenuItem) then
ShowMessage('Selected size: ' + MenuItem.Text);
end;
3. Embedding Controls in Menu Items
Add custom controls like edit boxes, buttons, or other components directly into menu items.
uses
..., FMX.TMSFNCPopupMenu, FMX.TMSFNCCustomControl, FMX.Edit;
procedure TForm1.AddEmbeddedControls;
var
MenuItem: TTMSFNCMenuItem;
SearchEdit: TEdit;
VolumeSlider: TTrackBar;
begin
// Add search box
MenuItem := TMSFNCPopupMenu1.AddMenuItem('', mitDefault);
MenuItem.Selectable := False;
SearchEdit := TEdit.Create(Self);
SearchEdit.Width := 150;
SearchEdit.Height := 22;
SearchEdit.TextPrompt := 'Search...';
MenuItem.Control := SearchEdit;
MenuItem.ControlAlignment := caClient;
TMSFNCPopupMenu1.AddMenuSeparatorItem;
// Add volume slider
MenuItem := TMSFNCPopupMenu1.AddMenuItem('Volume:', mitDefault);
MenuItem.Selectable := False;
VolumeSlider := TTrackBar.Create(Self);
VolumeSlider.Width := 100;
VolumeSlider.Min := 0;
VolumeSlider.Max := 100;
VolumeSlider.Value := 75;
MenuItem.Control := VolumeSlider;
MenuItem.ControlAlignment := caRight;
end;
4. Creating Toolbar Menus
Use toolbar items to create compact button groups within the menu.
uses
..., FMX.TMSFNCPopupMenu;
procedure TForm1.CreateToolbarMenu;
var
ToolbarItem: TTMSFNCMenuItem;
ButtonItem: TTMSFNCMenuItem;
begin
// Create formatting toolbar
ToolbarItem := TMSFNCPopupMenu1.AddMenuItem('', mitToolBar);
// Add toolbar buttons
ButtonItem := ToolbarItem.AddMenuItem('Bold', mitDefault);
ButtonItem.BitmapName := 'Bold';
ButtonItem.Hint := 'Bold (Ctrl+B)';
ButtonItem.ShowHint := True;
ButtonItem := ToolbarItem.AddMenuItem('Italic', mitDefault);
ButtonItem.BitmapName := 'Italic';
ButtonItem.Hint := 'Italic (Ctrl+I)';
ButtonItem.ShowHint := True;
ButtonItem := ToolbarItem.AddMenuItem('Underline', mitDefault);
ButtonItem.BitmapName := 'Underline';
ButtonItem.Hint := 'Underline (Ctrl+U)';
ButtonItem.ShowHint := True;
TMSFNCPopupMenu1.AddMenuSeparatorItem;
// Create alignment toolbar
ToolbarItem := TMSFNCPopupMenu1.AddMenuItem('', mitToolBar);
ButtonItem := ToolbarItem.AddMenuItem('Left', mitCheck);
ButtonItem.GroupName := 'Align';
ButtonItem.Checked := True;
ButtonItem := ToolbarItem.AddMenuItem('Center', mitCheck);
ButtonItem.GroupName := 'Align';
ButtonItem := ToolbarItem.AddMenuItem('Right', mitCheck);
ButtonItem.GroupName := 'Align';
end;
Properties
| Property | Function |
|---|---|
Appearance |
Controls the visual appearance of the popup menu including colors, fonts, and spacing |
BitmapContainer |
Links to a TTMSFNCBitmapContainer for centralized bitmap management |
Items |
Collection of menu items that make up the menu structure |
OnPopup |
Event fired before the popup menu is displayed |
OnClose |
Event fired when the popup menu is closed |
Methods
| Method | Function |
|---|---|
Popup(X, Y: Single) |
Displays the popup menu at the specified screen coordinates |
AddMenuItem(AText: string; AType: TTMSFNCMenuItemType = mitDefault): TTMSFNCMenuItem |
Adds a new menu item with specified text and type |
AddMenuSeparatorItem: TTMSFNCMenuItem |
Adds a separator item to the menu |
GetMenuItemByText(AText: string): TTMSFNCMenuItem |
Finds a menu item by its text property |
GetCheckedMenuItemByGroupName(AGroupName: string): TTMSFNCMenuItem |
Returns the checked item from a specified group |
SelectMenuItemControl(AMenuItemControl: TTMSFNCMenuItemControl) |
Programmatically selects a menu item control |
Events
| Event | Function |
|---|---|
OnPopup |
Fired before the popup menu is displayed |
OnClose |
Fired when the popup menu is closed |
OnMenuItemClick |
Default click handler for menu items without individual OnClick |
OnMenuItemAdd |
Allows control over menu item addition, can be used to filter items |
OnMenuItemControlAdded |
Fired after a menu item control is added to the menu |
OnMenuItemSelectable |
Allows customization of item selectability at runtime |
OnItemCheck |
Fired when a checkable item is checked/unchecked |
OnGetFocusedSubControl |
Allows customization of focused sub-control detection |
OnGetItemControlClass |
Allows customization of menu item control class for dynamic creation |
OnItemMouseDown |
Fired on mouse down over a menu item |
OnItemMouseUp |
Fired on mouse up over a menu item |
OnItemControlMouseDown |
Fired on mouse down over an embedded control |
OnItemControlMouseUp |
Fired on mouse up over an embedded control |
OnItemKeyDown |
Fired on key down when menu item has focus |
OnItemControlKeyDown |
Fired on key down when embedded control has focus |
OnBeforeDrawMenuItem |
Allows customization before drawing a menu item |
OnAfterDrawMenuItem |
Allows customization after drawing a menu item |
OnBeforeDrawMenuItemImage |
Allows customization before drawing item image |
OnAfterDrawMenuItemImage |
Allows customization after drawing item image |
OnBeforeDrawMenuItemText |
Allows customization before drawing item text |
OnAfterDrawMenuItemText |
Allows customization after drawing item text |
OnBeforeDrawMenuItemNote |
Allows customization before drawing item note |
OnAfterDrawMenuItemNote |
Allows customization after drawing item note |
OnGetNumberOfPopupMenuItems |
Allows dynamic determination of menu item count |
OnGetNumberOfSubMenuItems |
Allows dynamic determination of sub-menu item count |
TTMSFNCPopupMenuAppearance
The appearance property controls the overall visual styling of the popup menu.
| Property | Function |
|---|---|
Fill |
Background fill settings for the menu |
Stroke |
Border stroke settings for the menu |
MenuRounding |
Corner radius for rounded menu appearance. Default: 8 |
MenuMargins |
Internal margins around menu content |
DefaultItemAppearance |
Default appearance settings for menu items |
MinimumAutoSizeItemHeight |
Minimum height for auto-sized items. Default: 23 |
MinimumAutoSizeToolBarItemHeight |
Minimum height for toolbar items. Default: 50 |
MenuOffSetPoint |
Offset point for menu positioning relative to placement |
CheckedIcon |
Icon displayed for checked menu items |
SubMenuIcon |
Icon displayed for items with sub-menus |
PopupMenuPlacement |
Placement strategy for the popup menu. Default: ppAbsolute |
TTMSFNCMenuItem
Represents an individual item within the popup menu. Items can be standard menu items, separators, checkable items, or containers for other controls.
MenuItem Properties
| Property | Function |
|---|---|
Text |
Display text for the menu item |
Note |
Additional text displayed on the right side of the item |
ItemType |
Type of menu item (mitDefault, mitSeparator, mitCheck, mitToolBar, mitDropDownButton) |
Enabled |
Enables or disables the menu item. Default: True |
Checked |
Check state for checkable items. Default: False |
Selectable |
Determines if the item can be selected. Default: True |
GroupName |
Group name for radio-style items |
Bitmap |
Icon bitmap for the menu item |
BitmapName |
Name reference for bitmap from BitmapContainer |
Items |
Sub-items collection for hierarchical menus |
Appearance |
Item-specific appearance settings |
ShortCut |
Keyboard shortcut for the item |
Control |
Embedded control within the menu item |
ControlAlignment |
Alignment of the embedded control. Default: caNone |
ControlPosition |
Position of the embedded control. Default: cpCenterLeft |
Action |
Associated action for the menu item |
Hint |
Hint text for the menu item |
ShowHint |
Determines if hint should be displayed. Default: False |
DisplayTag |
Custom integer tag for display purposes |
OnClick |
Click event handler for the menu item |
TTMSFNCMenuItemAppearance
Controls the visual appearance of individual menu items, allowing customization of colors, fonts, and spacing.
| Property | Function |
|---|---|
Fill |
Background fill for normal state |
SelectedFill |
Background fill for selected/hovered state |
DisabledFill |
Background fill for disabled state |
Font |
Font settings for menu item text |
SelectedFontColor |
Font color for selected state. Default: gcNull |
DisabledFontColor |
Font color for disabled state. Default: gcGray |
NoteFont |
Font settings for note text |
SelectedNoteFontColor |
Note font color for selected state. (gcNull will default to the SelectedFont.) Default: gcNull |
DisabledNoteFontColor |
Note font color for disabled state. (gcNull will default to the SelectedFont.) Default: gcNull |
Separator |
Appearance of separator lines |
ItemRounding |
Corner radius for item background. Default: 2 |
ItemHeight |
Fixed height for items (-1 for auto). Default: -1 |
AccessoryWidth |
Width reserved for accessory icons. Default: 12 |
BitmapSize |
Size of item bitmaps (-1 for auto). Default: -1 |
BitmapMargins |
Margins around bitmaps |
ItemMargins |
Margins around items |
LeftTextIndent |
Left indentation for text. Default: 24 |
TextHorizontalSpacing |
Horizontal spacing between text elements. Default: 2 |
TTMSFNCMenuItemControl
A TTMSFNCMenuItemControl is the actual control instance that is created and displayed when a TTMSFNCMenuItem is rendered in the popup. It contains the visual and behavioral representation of the item and is used in most popup-related events.
Note
TTMSFNCMenuItem defines the logical item, while TTMSFNCMenuItemControl is the runtime control. In most events, you interact with TTMSFNCMenuItemControl, which gives access to the original MenuItem property.
Properties
| Property | Function |
|---|---|
Appearance |
Appearance settings for the menu item control. |
Index |
Index of the item within its parent. |
Text, Note |
Text and note string displayed. |
MenuItem |
Reference to the original TTMSFNCMenuItem. |
Checked |
Whether the item is checked. |
AccessoryBitmap, Bitmap, BitmapName |
Visual icons. |
Control, ControlAlignment, ControlPosition |
Embedded control and layout options. |
ItemType |
Type of item (mitDefault, mitCheck, etc.). |
BitmapContainer |
Reference to the bitmap container. |
GroupName |
Grouping for radio-style behavior. |
HasSubItems |
Whether the item has sub-items. |
Selectable |
If the item is selectable. |
ShortCut |
Shortcut key combination. |
Selected |
Indicates if the control is currently selected. |
Action |
Associated TBasicAction. |
ParentMenuControl |
Access the parent menu control. |
PopupMenu |
Reference to the owning popup menu. |
View |
Interface for menu layout and navigation. |
Methods
| Method | Function |
|---|---|
Create(...), Destroy |
Constructor/destructor. |
Assign(Source) |
Copies properties from another object. |
Initialize |
Prepares the control before display. |
Popup |
Displays the item as a popup. |
SetSelected |
Marks the item as selected. |
GetParentMenuControl |
Retrieves the parent menu control. |
GetFirstMenuItem(...), GetNextMenuItem(...), GetPreviousMenuItem(...), GetLastMenuItem(...) |
Navigation helpers. |
Events
These are typically triggered through TTMSFNCPopupMenu:
| Event | Function |
|---|---|
OnClick |
Triggered when the control is clicked. Has priority on MenuItemClicked event. |
Advanced Examples
Custom Appearance Configuration
uses
..., FMX.TMSFNCPopupMenu, FMX.TMSFNCGraphicsTypes;
procedure TForm1.ConfigureModernDarkTheme;
var
mp: TTMSFNCPopupMenuAppearance;
dip: TTMSFNCMenuItemAppearance;
begin
mp := TMSFNCPopupMenu1.Appearance;
// Dark menu background
mp.Fill.Color := $FF1E1E1E;
mp.Stroke.Color := $FF3A3A3A;
mp.MenuRounding := 12;
// Configure margins
mp.MenuMargins.Left := 6;
mp.MenuMargins.Top := 6;
mp.MenuMargins.Right := 6;
mp.MenuMargins.Bottom := 6;
// Configure default item appearance
dip := mp.DefaultItemAppearance;
// Normal state
dip.Fill.Color := gcNull;
dip.Font.Color := $FFE4E4E4;
dip.Font.Size := 11;
// Selected state
dip.SelectedFill.Color := $FF0E639C;
dip.SelectedFontColor := gcWhite;
// Disabled state
dip.DisabledFontColor := $FF666666;
// Item styling
dip.ItemRounding := 6;
dip.ItemHeight := 32;
dip.AccessoryWidth := 20;
dip.LeftTextIndent := 36;
end;
Dynamic Menu Creation
uses
..., FMX.TMSFNCPopupMenu;
procedure TForm1.FormCreate(Sender: TObject);
begin
// If not assigned in Design-Time
TMSFNCPopupMenu1.OnMenuItemClick := DoMenuItemClick;
TMSFNCPopupMenu1.OnGetNumberOfPopupMenuItems := DoGetNumberOfPopupMenuItems;
TMSFNCPopupMenu1.OnMenuItemControlAdded := DoMenuItemControlAdded;
MyDataList := TDictionary<string, string>.Create;
MyDataList.Add('readme.md','15:41');
MyDataList.Add('sales.docx','13:04');
MyDataList.Add('quote.pdf','12:57');
MyDataList.Add('image.png','8:25');
end;
procedure TForm1.DoMenuItemClick(Sender: TObject; AMenuItemControl: TTMSFNCMenuItemControl);
begin
ShowMessage(AMenuItemControl.Text + ' ' + AMenuItemControl.Note);
end;
procedure TForm1.DoGetNumberOfPopupMenuItems(Sender: TObject;
var ADisplayItemCount: Integer);
begin
// Dynamic item count based on data
ADisplayItemCount := MyDataList.Count + 2; // +2 for header and separator
end;
procedure TForm1.DoMenuItemControlAdded(Sender: TObject;
AMenuItemControl: TTMSFNCMenuItemControl);
begin
case AMenuItemControl.Index of
0: begin
AMenuItemControl.Text := 'Recent Files';
AMenuItemControl.Selectable := False;
AMenuItemControl.Appearance.LeftTextIndent := 2;
AMenuItemControl.Appearance.Font.Style := [TFontStyle.fsBold];
end;
1: begin
AMenuItemControl.ItemType := mitSeparator;
end;
else
begin
// Configure from data
if AMenuItemControl.Index - 2 < MyDataList.Count then
begin
AMenuItemControl.Text := MyDataList.ToArray[AMenuItemControl.Index - 2].Key;
AMenuItemControl.Note := MyDataList.ToArray[AMenuItemControl.Index - 2].Value;
end;
end;
end;
end;
Working with Actions
uses
..., FMX.TMSFNCPopupMenu, System.Actions, FMX.ActnList;
procedure TForm1.SetupActionsMenu;
var
MenuItem: TTMSFNCMenuItem;
begin
// File menu items linked to actions
MenuItem := TMSFNCPopupMenu1.AddMenuItem('File Operations', mitDefault);
MenuItem.AddMenuItem(ActionNew);
MenuItem.AddMenuItem(ActionOpen);
MenuItem.AddMenuItem(ActionSave);
MenuItem.AddMenuSeparatorItem;
MenuItem.AddMenuItem(ActionExit);
end;