Class

DesktopMenuItem

Description

An individual menu item in a desktop project. Used by menu bars and contextual menus.

Methods

Name

Parameters

Returns

Shared

AddMenu

Item As DesktopMenuItem

AddMenuAt

Index As Integer, Item As DesktopMenuItem

Child

Name As String

DesktopMenuItem

Clone

DesktopMenuItem

Close

Constructor

Text As String, [Tag As Variant]

Count

Integer

Handle

Ptr

type As DesktopMenuItem.HandleTypes

Ptr

MenuAt

Index As Integer

DesktopMenuItem

PopUp

[x As Integer, y As Integer]

DesktopMenuItem

RemoveMenuAt

Index As Integer

Events

Name

Parameters

Returns

MenuBarSelected

MenuItemSelected

Boolean

Constants

The following class constant is used to add a separator item to a menu. Use this constant to add a separator with the AddMenu or AddMenuAt methods:

Class Constant

Description

TextSeparator

A menu separator.

Enumerations

DesktopMenuItem.HandleTypes

HandleTypes

Specifies the type of Windows OS handle you wish to receive for use with the Handle property.

Enum

Description

WindowsParentHMENU

The HMENU of the DesktopMenuItem if it is a submenu, otherwise it is the parent's HMENU.

WindowsCommandID

The unique menu item identifier for the DesktopMenuItem, used by various Win32 APIs such as GetMenuItemInfo.

Property descriptions

DesktopMenuItem.AutoEnabled

AutoEnabled As Boolean

If set to True, the DesktopMenuItem is enabled by default, as long as the App object or frontmost window has a menu handler for the menuitem.

There is no need to put code in the MenuBarSelected event handler to explicitly enable an autoenabled menu item. AutoEnabled is True by default. When you create dynamic menus by creating a new class based on DesktopMenuItem, AutoEnabled is also True by default. See the example on dynamic menus on the DesktopMenuItem page.

DesktopMenuItem.Enabled

Enabled As Boolean

Indicates whether or not the menu item is enabled.

For MenuItems that belong to an App or Window menu, this property should only be set to True in the MenuBarSelected event handler.

You can set it for MenuItems created for use by contextual menus or for use with the Popup method.

This example is in the MenuBarSelected event handler and it enables a menu.

FilePageSetup.Enabled = True

DesktopMenuItem.HasAltKey

HasAltKey As Boolean

The Alt key on Windows and Linux keyboards. If selected, the Alt key is must be held down while pressing the value of the Key property in order to trigger the event handler for the DesktopMenuItem. This property is for Windows and Linux only.

This property is read-only.

Use Shortcut to change this value at runtime.

DesktopMenuItem.HasCheckMark

HasCheckMark As Boolean

Indicates whether or not the menu item is checked.

DesktopMenuItem.HasMacControlKey

HasMacControlKey As Boolean

The Control key on Mac. This property is Mac-only. If selected, the Control key must be held down while pressing the value of the ShortcutKey property in order to trigger the event handler of the DesktopMenuItem.

This property is read-only.

Use Shortcut to change this value at runtime.

DesktopMenuItem.HasMacOptionKey

HasMacOptionKey As Boolean

The Option key on Mac. This property is Mac-only. If selected, the Option key must be held down while pressing the value of the ShortcutKey property to trigger the event handler of the DesktopMenuItem.

This property is read-only.

Use Shortcut to change this value at runtime.

DesktopMenuItem.HasSecondaryModifierKey

HasSecondaryModifierKey As Boolean

The Shift key on all platforms. If True, the Shift key must be held down while pressing the value of the Key property to trigger the event handler of the DesktopMenuItem.

This property is read-only.

Use Shortcut to change this value at runtime.

DesktopMenuItem.HasStandardModifierKey

HasStandardModifierKey As Boolean

The Control key on Windows and Linux and the Command key on Mac. If this property is selected, the MenuModifier key must be held down while pressing the key specified by the ShortcutKey property to trigger the event handler for the DesktopMenuItem.

This property is read-only.

Use Shortcut to change this value at runtime.

DesktopMenuItem.Icon

Icon As Picture

A picture that is assigned to the DesktopMenuItem.

On macOS and Linux, the picture appears in its original size. Resize the icon externally before adding it to the project. On Windows, the icon is resized so that its size matches the height of the item's Text. In most cases icons that are 16x16 points look best.

Recent versions of Linux (that use recent version of the GNOME desktop manager), default to not showing menu icons. You can change the OS setting to display menu icons using `terminal<http://gnomeshell.wordpress.com/2011/09/11/show-and-hide-the-menu-icons/>`_:

gsettings set org.gnome.desktop.interface menus-have-icons true

The following code is in the Opening event of the main window. The image appears to the left of the menu item's text.

EditFind.Icon = RedApple

DesktopMenuItem.Index

Index As Integer

The number of the selected MenuItem when it is part of an array.

This property is read-only.

DesktopMenuItem.LastRowIndex

LastRowIndex As Integer

The index of the last child menu item owned by this menu.

This property is read-only.

DesktopMenuItem.Name

Name As String

The name of the menu item. Set this property using the Menu Editor.

This example sets the name of a menuitem.

EditMenu.MenuAt(2).Name = "Delete"

DesktopMenuItem.Shortcut

Shortcut As String

The keyboard shortcut for the DesktopMenuItem.

Use this property to set the shortcut in code. You can also specify a shortcut in the Inspector for the MenuItem.

You can use either a printable key or any of the supported non-printable keys (see the table below) as shortcut keys.

If the shortcut key is more than one character and it is being set via code, the modifier key is not implied and must be explicitly defined. For example, the following line sets the Tab key as the shortcut key and uses the Ctrl key as the modifier.

SpecialMyMenuItem.Shortcut = "Ctrl-Tab"

For macOS, use Cmd instead of Ctrl. Or set the HasStandardModifierKey property to True in the IDE and pass the string literal for the desired keyboard shortcut.

The following values are supported for modifier keys:

Name

ALT

CMD

CTRL

CONTROL

OPT

SHIFT

Note

ALT and OPT are treated as the same key.

The following values are supported for non-printable keys:

Name

Backspace

Bksp

Clear

Del

Delete

Down

Down Arrow

DownArrow

Enter

Esc

F1

F2

F3

F4

F5

F6

F7

F8

F9

F10

F11

F12

F13

F14

F15

Help

Left

Left Arrow

LeftArrow

PageDown

PageUp

Return

ReturnLeft

ReturnRight

Right

Right Arrow

RightArrow

Space

Tab

TabLeft

TabRight

Up

Up Arrow

UpArrow

DesktopMenuItem.ShortcutKey

ShortcutKey As String

The shortcut key for the menu item. If this key and the selected modifier keys are held down, the event handler for the menu item will be executed as if the DesktopMenuItem itself were chosen via the mouse pointer.

This property is read-only.

When you use the Inspector for the Menu Editor, you specify the menu item's shortcut key by assigning a key to the Key property and (normally) at least one modifier key. The Menu Editor translates your settings into the value for the Shortcut property.

You can use either a printable key or the following non-printable keys as shortcut keys: F1 - F15, Tab, Enter, Space, Del (Delete), Return, Bksp (Backspace), Esc, Clear, PageUp, PageDown, Left, Right, Up, Down, Help, and Ins (Insert).

To set the shortcut in code, use the Shortcut property. If the shortcut key is more than one character and it is being set via code, the modifier key is not implied and must be explicitly defined. For example, the following line sets the Tab key as the shortcut key and uses the Ctrl key as the modifier.

SpecialMyMenuItem.Shortcut = "Ctrl-Tab"

For macOS, use Cmd instead of Ctrl. Or set the HasStandardModifierKey property to True in the IDE and pass the string literal for the desired keyboard shortcut.

DesktopMenuItem.Tag

Tag As Variant

A “hidden” value associated with the menu item.

The tag is accessible via code when the user chooses the menu item but, unlike the Text property, is not displayed in the menu. It works like the RowTag property of a DesktopPopupMenu control.

This example is in the Opening event of the main window.

EditFind.Tag = "Search"

DesktopMenuItem.Text

Text As String

The value (text) of the menu item.

This example is in the Opening event of the main window.

EditFind.Text = "Find..."

DesktopMenuItem.Visible

Visible As Boolean

Indicates whether or not the menu item is visible. The default is True. If False, the menu item does not appear and no blank space is for it is in the menu.

This property does nothing on Windows so use RemoveMenuAt instead.

This code is in the Opening event of the main window:

EditFind.Visible = False

Method descriptions

DesktopMenuItem.AddMenu

AddMenu(Item As DesktopMenuItem)

Adds the passed DesktopMenuItem to the menu. You can add a Separator by passing the class constant DesktopMenuItem.TextSeparator. Used to build a dynamic menu.

The following code creates a contextual menu in the ConstructContextualMenu event of any DesktopWindow or DesktopUIControl. This event passes in the parameter base as DesktopMenuItem.

base.AddMenu(New DesktopMenuItem("Import"))
base.AddMenu(New DesktopMenuItem("Export"))
base.AddMenu(New DesktopMenuItem(DesktopMenuItem.TextSeparator))

base.AddMenu(New DesktopMenuItem("Cut"))
base.AddMenu(New DesktopMenuItem("Copy"))
base.AddMenu(New DesktopMenuItem("Paste"))
Return True ' display the contextual menu

The following code creates a hierarchical menu that is added to the main menubar. It is in the Opening event of the App or the window. It's easiest to create menus and menuitems using the built-in Menu Editor and enable the DesktopMenuItems using the AutoEnable property. Use code for cases such as dynamic menus and contextual menus.

Var m, mNew As DesktopMenuItem
m = Self.MenuBar
mNew = New DesktopMenuItem

mNew.Text = "View"
mNew.Name = "View"

mNew.AddMenu(New DesktopMenuItem("As Icons"))
mNew.AddMenu(New DesktopMenuItem("As List"))
mNew.AddMenu(New DesktopMenuItem("As Columns"))

mNew.AddMenu(New DesktopMenuItem( "-" ))

Var submenu As New DesktopMenuItem("Sort By")
submenu.AddMenu(New DesktopMenuItem("Name"))
submenu.AddMenu(New DesktopMenuItem("Kind"))
submenu.AddMenu(New DesktopMenuItem("Size"))

mNew.AddMenu(submenu)
m.AddMenu(mNew)

DesktopMenuItem.AddMenuAt

AddMenuAt(Index As Integer, Item As DesktopMenuItem)

Adds Item as a DesktopMenuItem at the position indicated by Index. Index is zero-based.

You can add a Separator by passing the class constant DesktopMenuItem.TextSeparator.

The following example adds a new item in the Edit menu with the text "Paste Special..." just below the Paste item.

Var editPasteSpecial As New DesktopMenuItem
editPasteSpecial.Text = "Paste Special..."
EditMenu.AddMenuAt(5, editPasteSpecial)

DesktopMenuItem.Child

Child(Name As String) As DesktopMenuItem

Looks up menu items by Name and returns a DesktopMenuItem. Returns Nil if a child is not found.

The following example gets the text of the Edit > Cut menuitem.

Var c As DesktopMenuItem
c = EditMenu.Child("EditCut")
MessageBox(c.Text)

DesktopMenuItem.Clone

Clone As DesktopMenuItem

Makes a copy of the DesktopMenuItem and its children if any. Mac does not permit duplicate MenuItems, so you will need to create clones of any MenuItems that are now being used in two or more locations.

Whenever you need to use the same DesktopMenuItem in different places, use the Clone method to create a new copy of the DesktopMenuItem and its children, if any.

Var mi As New DesktopMenuItem("My menu item")
Var myClone As DesktopMenuItem

myClone = mi.Clone ' Creates an independent copy of "mi"

DesktopMenuItem.Close

Close

Removes dynamically created menu items.

This example closes a menu item that was previously created.

EditSelectAll.Close

DesktopMenuItem.Constructor

Constructor(Text As String, [Tag As Variant])

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Creates a new DesktopMenuItem that uses the passed string as its Text property and optionally adds the passed Tag.

This example inserts a new item in the Edit menu with the text "Paste Special..." just below the Paste item.

Var editPasteSpecial As New DesktopMenuItem
editPasteSpecial.Text = "Paste Special..."
EditMenu.AddMenuAt(5, editPasteSpecial)

Using this constructor, you can rewrite the code above more concisely:

Var editPasteSpecial As New DesktopMenuItem("Paste Special...")
EditMenu.AddMenuAt(5, editPasteSpecial)

This example illustrates how you can manipulate the menu bar at run time. By adding this example to the Opening even of a window it will add a new menu to menubar when the window opens.

Var m As DesktopMenuItem
Var mNew As DesktopMenuItem

m = Self.MenuBar
mNew = New DesktopMenuItem

mNew.Text = "MyMenuText"
mNew.Name = "MyMenuName"

Var submenu As New DesktopMenuItem("MySub")

submenu.AddMenu(New DesktopMenuItem("Submenu One"))
submenu.AddMenu(New DesktopMenuItem("Submenu Two"))
submenu.AddMenu(New DesktopMenuItem("Submenu three"))

mNew.AddMenu(submenu)

m.AddMenu(mNew)

DesktopMenuItem.Count

Count As Integer

Returns as an Integer the number of children a menu owns.

For a menu item, it returns the number of submenu items, if any. If there are no submenu items, it returns zero.

DesktopMenuItem.Handle

Handle As Ptr

Provides access to the appropriate underlying Linux or macOS menu implementation.

Handle(type As DesktopMenuItem.HandleTypes) As Ptr

Provides access to the appropriate underlying Windows OS menu implementation.

Note

Passing a type as a parameter to this method on Linux or macOS will result in a PlatformNotSupportedException .

DesktopMenuItem.MenuAt

MenuAt(Index As Integer) As DesktopMenuItem

Item returns as a DesktopMenuItem the item indicated by the index passed.

If the passed index is out of range, an OutOfBoundsException is raised.

The following example gets the DesktopMenuItem corresponding to the Cut item on the Edit menu by position:

Var c As DesktopMenuItem
c = EditMenu.MenuAt(2)
MessageBox(c.Text)

DesktopMenuItem.PopUp

PopUp([x As Integer, y As Integer]) As DesktopMenuItem

Displays the DesktopMenuItem as a contextual menu.

If no parameters are passed, the contextual menu appears at the location of the mouse pointer. If you pass the optional parameters, the contextual menu appears at the passed location. The coordinates are global, not just in the object that handles the MouseDown event.

Popup returns the selected item as a DesktopMenuItem. The selected item's Action event will be fired. If the selected item is handled by a MenuHandler that returns True, then PopUp will return Nil.

The following example displays the Edit menu as a contextual menu. The code is in the MouseDown event handler of a DesktopUIControl. You can get the text of the selected item by accessing the Text property of the returned DesktopMenuItem.

Var popMenu As DesktopMenuItem
popMenu = EditMenu.Clone

Var selectedMenu As DesktopMenuItem
selectedMenu = popMenu.Popup

DesktopMenuItem.RemoveMenuAt

RemoveMenuAt(Index As Integer)

Removes the DesktopMenuItem specified by its position (index).

This example removes the Select All menu item from the Edit menu.

EditMenu.RemoveMenuAt(3)

Event descriptions

DesktopMenuItem.MenuBarSelected

MenuBarSelected

Called when a user selects a menu. You can use this to enable/disable/hide menus based on the context of your app.

DesktopMenuItem.MenuItemSelected

MenuItemSelected As Boolean

Called when a DesktopMenuItem is selected. Return True to prevent the menu event from proceeding any further in the chain of menu handlers.

Refer to the DesktopMenuItem page for an example of how a menu that is created dynamically can use the MenuItemSelected event.

Notes

DesktopMenuItem objects are used to create and access the properties of menu items. You can change the menu item text using the Text property. You can find out if a menu item is checked, or check or uncheck a menu item with the HasCheckmark property. You can also enable or disable a menu item using the Enabled property. The Enabled property should be set only from within an MenuBarSelected event handler. Setting it from anywhere else has no effect.

Three other classes handle specialized menu items. DesktopQuitMenuItem is designed to manage the File > Quit (macOS) and File > Exit (Windows and Linux) menu of a built application; it is enabled by default and automatically calls the Quit method. The DesktopPreferencesMenuItem class is designed to handle the Preferences menu item. In macOS, this menu item is supposed to be located under the application's menu, but on other operating systems, this menu does not exist. A menu item derived from the DesktopPreferencesMenuItem class automatically appears under the application's menu under macOS; on other operating systems is appears where you put it in the Menu Editor. The DesktopApplicationMenuItem class is designed for creating menu items that appear under the application's menu on macOS. Any menu subclassed from DesktopApplicationMenuItem will move to the application's menu for your macOS build but stay where it is for your other builds.

MenuItems can be created on the fly using the New operator or the Clone method.

Contextual menus

Use The ConstructContextualMenu and ContextualMenuAction events of the DesktopUIControl or DesktopWindow to create and manage contextual menus.

Specifying the keyboard shortcut in the menu editor

When you use the Properties pane in the Menu Editor, you specify the menu item's shortcut key by assigning a key to the ShortcutKey property and (normally) at least one modifier key. The Menu Editor translates your settings into the value for the Shortcut property.

You can use either a printable key or the following non-printable keys as shortcut keys: F1 - F15, Tab, Enter, Space, Del (Delete), Return, Bksp (Backspace), Esc, Clear, PageUp, PageDown, Left, Right, Up, Down, Help, and Ins (Insert). If the shortcut key is more than one character and it is being set via code, the modifier key is not implied and must be explicitly defined. For example, the following line sets the Tab key as the shortcut key and uses the Ctrl key as the modifier.

SpecialMyMenuItem.Shortcut = "Ctrl-Tab"

For macOS, use Cmd instead of Ctrl. Or set the HasStandardModifierKey property to True in the IDE and pass the string literal for the desired keyboard shortcut.

Other values you can use are: "Opt", "Alt", "Shift". You can combine keys like this:

MyMenuItem.Shortcut = "Shift-Ctrl-W"

When you are setting a non-printable key in the IDE, you can just enter its name from the list above and check the desired modifier key from the following list.

The ShortcutKey property entry and the entries for the modifier keys are described in the table below.

Name

Description

HasSecondaryModifierKey

The Shift key on all platforms. If selected, the Shift key must be held down while pressing the value of the ShortcutKey property to trigger the event handler of the DesktopMenuItem.

ShortcutKey

The shortcut key for the menu item. If this key and the selected modifier keys set is held down, the event handler for the menu item will be executed as if the menu item itself were chosen via the mouse pointer.

HasMacControlKey

The Control key on Mac. This property is Mac-only. If selected, the Control key must be held down while pressing the value of the ShortcutKey property in order to trigger the event handler of the menuitem.

HasMacOptionKey

The Option key on Mac. This property is Mac-only. If selected, the Option key must be held down while pressing the value of the ShortcutKey property to trigger the event handler of the menu item.

HasStandardModifierKey

The Control key on Windows and Linux and the Command key on Mac. If this property is selected, the HasStandardModifierKey key must be held down while pressing the key specified by the ShortcutKey property to trigger the event handler for the menu item.

HasAltKey

The Alt key on Windows and Linux keyboards. If selected, the Alt key is must be held down while pressing the value of the ShortcutKey property in order to trigger the event handler for the menu item. This property is for Windows and Linux only.

Sample code

The following code changes the text of the EditPaste menu item to "Paste Special…":

EditPaste.Text = "Paste Special..."

The following code adds a new item in the Edit menu with the text "Paste Special..." just below the Paste item.

Var EditPasteSpecial As New DesktopMenuItem
EditPasteSpecial.Text = "Paste Special..."
EditMenu.AddMenuAt(5, EditPasteSpecial)

Using the constructor, you can write:

Var EditPasteSpecial As New DesktopMenuItem("Paste Special...")
EditMenu.AddMenuAt(5, EditPasteSpecial)

The following code adds a Select All menu item to the Edit menu.

Var EditSelectAll As New DesktopMenuItem
EditSelectAll.Text = "Select All..."
EditMenu.AddMenu(EditSelectAll)

The following code gets the DesktopMenuItem corresponding to the Cut item on the Edit menu.

Var c As DesktopMenuItem
c = EditMenu.Child("EditCut")
MessageBox(c.Text)

The following code gets the DesktopMenuItem corresponding to the Cut item on the Edit menu by position:

Var c As DesktopMenuItem
c = EditMenu.MenuAt(2)
MessageBox(c.Text)

The following code removes the fourth dynamically created menu item from a menu item array named WindowItem:

WindowItem(3).Close

The following code assigns a value to the Tag property of a menu item:

SearchFind.Tag = "UserSearch"

The following code displays the Edit menu as a contextual menu. The code is in the MouseDown event handler of a DesktopUIControl. You can get the text of the selected item by accessing the Text property of the returned DesktopMenuItem.

If IsContextualClick Then
  Var m As DesktopMenuItem
  m = EditMenu.Popup
End If

In general you should create and display contextual menus using the ConstructContextualMenu and ContextualMenuSelected event handlers of the DesktopWindow and DesktopUIControl classes. They are fully cross-platform and don't make assumptions about how the user requested a contextual menu.

The following code creates a contextual menu in the ConstructContextualMenu event of any DesktopWindow or DesktopUIControl. This event passes in the parameter base as DesktopMenuItem.

base.AddMenu(New DesktopMenuItem("Import"))
base.AddMenu(New DesktopMenuItem("Export"))
base.AddMenu(New DesktopMenuItem(DesktopMenuItem.TextSeparator))

base.AddMenu(New DesktopMenuItem("Cut"))
base.AddMenu(New DesktopMenuItem("Copy"))
base.AddMenu(New DesktopMenuItem("Paste"))
Return True  ' display the contextual menu

The following code in the ContextualMenuSelected event handles the menu selection. This event passes in the parameter hitItem as DesktopMenuItem. This is the selected menu item.

Select Case hitItem.Text
Case "Import"
  MessageBox("You chose Import")
Case "Export"
  MessageBox("You chose export")
Case "Cut"
  MessageBox("You chose Cut")
Case "Copy"
  MessageBox("You chose Copy")
Case "Paste"
  MessageBox("You chose Paste")
End Select

Return True

In certain cases you cannot specify the menu items that belong in a menu in advance. They may change depending on the context in which the application is used or on the operating system on which the application is running.

A common example of this is the Font menu that is normally included in any application that supports styled text. The programmer has no way of knowing in advance which fonts happen to be installed on the user's computer. The Font menu's menuitems have to be built dynamically when the application is launched.

The recommended technique is to create a subclass of DesktopMenuItem in the Project Window. To create the menuitems, you use the DesktopMenuItem's constructor to instantiate an instance of the class for each menuitem you need. You handle the menuitem in the MenuItemSelected event.

You then write code to populate the menu with the names of the fonts installed on the user's computer. If we assume that fonts won't be added or deleted while the application is running, we can build the font list when the application launches. You can do this in the App.Opening event or the Opening event of a window if the menu should appear only for a particular window. This example uses the App.Opening event.

Before adding the App.Opening event, we will add a DesktopMenuItem subclass to the project. We will name it "AddFont" and set its Super class to DesktopMenuItem. It will use the constructor to add each menuitem. The constructor takes the DesktopMenuItem's text as its parameter. The optional rowtag parameter is not used. Since the constructor is built-in, you do not need to explicitly add a constructor to your code.

The DesktopMenuItem subclass has two events, MenuItemSelected and MenuBarSelected. You do not need to use MenuBarSelected because AutoEnabled is True by default. You do need to add code to the MenuItemSelected event. This is the code that will run when a user selects a menuitem. It serves the same purpose as the Menu Handler that is used for static menuitems.

In this case, we want the menu item to set the selected text in a DesktopTextArea to the font that the user chose. The MenuItemSelected event is:

TextWindow.TextArea1.SelectionFontName = Me.Text
Return True

TextWindow is the name of the window that contains the DesktopTextArea and TextArea1 is the DesktopTextArea. The Text variable holds the font name that was passed to AddFont when the font was created.

Next, we want to add code to the DesktopApplication.Opening event to create the Font menu and populate it with the name of the user's installed fonts. The following code adds the Font menu to the default menubar:

Var m, mNew As DesktopMenuItem
m = Self.MenuBar
mNew = New DesktopMenuItem
mNew.Text = "Fonts"
mNew.Name = "FontsMenu"
m.AddMenu(mNew)

The next block of code populates the Font menu. It uses the built-in System.FontAt function which returns the name of the ith font on the user's computer. The code instantiates an instance of the AddFont subclass for each font:

Var child As DesktopMenuItem
If mNew = Nil Then
  MessageBox("Menu parent is nil!")
  Return
End If

' build the font menu
For i As Integer = 0 To System.LastFontIndex
  child = New AddFont(System.FontAt(i))
  mNew.AddMenu(child)
Next

Compatibility

Desktop projects on all supported operating systems.