` | | | ## Property descriptions

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

forsearch

MenuBar.Handle **Handle** As `Integer` Provides access to the appropriate underlying platform menu implementation. This property is read-only. If the requested handle type doesn't make sense for the platform the application is running on, a PlatformNotSupportedException is raised. **MenuItem.HandleType** enumeration: - CocoaNSMenuItem: Returns the underlying NSMenuItem. If there is a submenu, the NSMenu can be got through NSMenuItem's submenu method. - WindowsParentHMENU: Returns the HMENU of the MenuItem if it is a submenu, otherwise it returns the parent's HMENU - WindowsCommandID: Returns the unique menu item identifier for the MenuItem, used by various Win32 APIs such as GetMenuItemInfo

forsearch

MenuBar.LastRowIndex **LastRowIndex** As `Integer` The index of the last child menu item owned by this menu. This property is read-only.

forsearch

MenuBar.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. ``` xojo EditMenu.Item(2).Name = "Delete" ```

forsearch

MenuBar.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 `PopupMenu` control. This example is in the Open event of the main window. ``` xojo EditFind.Tag = "Search" ``` ## Method descriptions

forsearch

MenuBar.AddMenu **AddMenu**(Item As `MenuItem`) Adds the passed MenuItem to the menu. You can add a Separator by passing the class constant MenuItem.TextSeparator. Used to build a dynamic menu. The following code creates a contextual menu in the ConstructContextualMenu event of any `Window` or `RectControl`. This event passes in the parameter base as MenuItem. ``` xojo base.AddMenu(New MenuItem("Import")) base.AddMenu(New MenuItem("Export")) base.AddMenu(New MenuItem(MenuItem.TextSeparator)) base.AddMenu(New MenuItem("Cut")) base.AddMenu(New MenuItem("Copy")) base.AddMenu(New MenuItem("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 Open event of the App or the window. It's easiest to create menus and menuitems using the built-in Menu Editor and enable the MenuItems using the AutoEnable property. Use code for cases such as dynamic menus and contextual menus. ``` xojo Var m, mNew As MenuItem m = Self.MenuBar mNew = New MenuItem mNew.Value = "View" mNew.Name = "View" mNew.AddMenu(New MenuItem("As Icons")) mNew.AddMenu(New MenuItem("As List")) mNew.AddMenu(New MenuItem("As Columns")) mNew.AddMenu(New MenuItem( "-" )) Var submenu As New MenuItem("Sort By") submenu.AddMenu(New MenuItem("Name")) submenu.AddMenu(New MenuItem("Kind")) submenu.AddMenu(New MenuItem("Size")) mNew.AddMenu(submenu) m.AddMenu(mNew) ```

forsearch

MenuBar.AddMenuAt **AddMenuAt**(Index As `Integer`, Item As `MenuItem`) Adds *Item* as a MenuItem at the position indicated by *Index*. Index is zero-based. You can add a Separator by passing the class constant MenuItem.TextSeparator. The following example adds a new item in the Edit menu with the text "Paste Special..." just below the Paste item. ``` xojo Var editPasteSpecial As New MenuItem editPasteSpecial.Text = "Paste Special..." EditMenu.AddMenuAt(5, editPasteSpecial) ```

forsearch

MenuBar.Child **Child**(Name As `String`) As `MenuItem` Looks up menu items by Name and returns a MenuItem. Returns `Nil` if a child is not found. The following example gets the text of the Edit \> Cut menuitem. ``` xojo Var c As MenuItem c = EditMenu.Child("EditCut") MessageBox(c.Value) ```

forsearch

MenuBar.Clone **Clone** As `MenuItem` Makes a copy of the `MenuItem` 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 `MenuItem` in different places, use the Clone method to create a new copy of the `MenuItem` and its children, if any. ``` xojo Var mi As New MenuItem("My menu item") Var myClone As MenuItem myClone = mi.Clone ' Creates an independent copy of "mi" ```

forsearch

MenuBar.Close **Close** Removes dynamically created menu items. This example closes a menu item that was previously created. ``` xojo EditSelectAll.Close ```

forsearch

MenuBar.Constructor **Constructor**(Text as `String`, \[Tag as `Variant` = `Nil`\])

Note

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

Creates a new MenuItem 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. ``` xojo Var editPasteSpecial As New MenuItem editPasteSpecial.Text = "Paste Special..." EditMenu.AddMenuAt(5, editPasteSpecial) ``` Using this constructor, you can rewrite the code above more concisely: ``` xojo Var editPasteSpecial As New MenuItem("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 open even of a window it will add a new menu to MenuBar when the window opens. ``` xojo Var m As MenuItem Var mNew As MenuItem m = Self.MenuBar mNew = New MenuItem mNew.Text = "MyMenuText" mNew.Name = "MyMenuName" Var submenu As New MenuItem("MySub") submenu.AddMenu(New MenuItem("Submenu One")) submenu.AddMenu(New MenuItem("Submenu Two")) submenu.AddMenu(New MenuItem("Submenu three")) mNew.AddMenu(submenu) m.AddMenu(mNew) ```

forsearch

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

forsearch

MenuBar.MenuAt **MenuAt**(Index As `Integer`) As `MenuItem` Item returns as a MenuItem the item indicated by its index (zero-based). If the passed index is out of range, an `OutOfBoundsException` is raised. The following example gets the MenuItem corresponding to the Cut item on the Edit menu by position: ``` xojo Var c As MenuItem c = EditMenu.MenuAt(2) MessageBox(c.Value) ```

forsearch

MenuBar.Popup **Popup**(\[x As `Integer`, y As `Integer`\]) As `MenuItem` Displays the MenuItem 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 **MenuItem**. 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 `RectControl`. You can get the text of the selected item by accessing the Text property of the returned MenuItem. ``` xojo Var popMenu As MenuItem popMenu = EditMenu.Clone Var selectedMenu As MenuItem selectedMenu = popMenu.Popup ```

forsearch

MenuBar.Remove **Remove**(Child As `MenuItem`) Removes the MenuItem specified by the *name*. This code removes the Select All menu item from the Edit menu. ``` xojo EditMenu.Remove(3) ```

forsearch

MenuBar.RemoveMenuAt **RemoveMenuAt**(Index As `Integer`) Removes the MenuItem specified by its position (index). This example removes the Select All menu item from the Edit menu. ``` xojo EditMenu.RemoveMenuAt(3) ``` ## Event descriptions

forsearch

MenuBar.Action **Action** As `Boolean` Called when a MenuItem is selected. Return `True` to prevent the menu event from proceeding any further in the chain of menu handlers. Refer to the `MenuItem` page for an example of how a menu that is created dynamically can use the Action event.

forsearch

MenuBar.EnableMenu **EnableMenu** Called when a user selects a menu. You can use this to enable/disable/hide menus based on the context of your app. ## 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 `Window.Open` event: ``` xojo Self.MenuBar = New MainMenuBar ``` On macOS, if a window does not have a `MenuBar` specified, then the window uses the MenuBar specified on `Application.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 `Application.MenuBar`. ## Compatibility All project types on all supported operating systems. ## See also `MenuItem` parent class; `MenuItem`; `Application.MenuBar` and `Window.MenuBar` properties.