Class

DesktopMenuBar

Description

Used to handle the application's and windows' menu bar.

Properties

Name

Type

Read-Only

Shared

LastRowIndex

Integer

✓

Name

String

Tag

Variant

Text

String

Events

Name

Parameters

Returns

MenuBarSelected

MenuItemSelected

Boolean

Property descriptions

DesktopMenuBar.LastRowIndex

LastRowIndex As Integer

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

This property is read-only.

DesktopMenuBar.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"

DesktopMenuBar.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"

DesktopMenuBar.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..."

Method descriptions

DesktopMenuBar.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.Value = "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)

DesktopMenuBar.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)

DesktopMenuBar.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.Value)

DesktopMenuBar.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"

DesktopMenuBar.Close

Close

Removes dynamically created menu items.

This example closes a menu item that was previously created.

EditSelectAll.Close

DesktopMenuBar.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 event 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)

DesktopMenuBar.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.

DesktopMenuBar.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 .

DesktopMenuBar.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.Value)

DesktopMenuBar.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

DesktopMenuBar.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

DesktopMenuBar.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.

DesktopMenuBar.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

When you create a new desktop project, a default MenuBar (called MainMenuBar) is added to your project.

You can refer to a MenuBar globally by its name because an "implicit instance" is automatically created for you to use. If you use the global name, then you will get the same MenuBar instance everywhere you use it. If you modify the MenuBar in code, the modification will appear everywhere the MenuBar is used.

If you would rather have separate instances of the MenuBar, you should assign it in code manually in the DesktopWindow.Opening event:

Self.DesktopMenuBar = New MainMenuBar

On macOS, if a window does not have a MenuBar specified, then the window uses the MenuBar specified on DesktopApplication.MenuBar.

On Windows and Linux, if a window does not have a MenuBar specified, then the window will display without a MenuBar even if one is specified in DesktopApplication.MenuBar.

Compatibility

Desktop projects on all supported operating systems.

See also

DesktopMenuItem parent class; DesktopApplication.MenuBar and DesktopWindow.MenuBar properties.