From Xojo Documentation
|You are currently browsing the old Xojo documentation site. Please visit the new Xojo documentation site!|
New in 2021r3
An individual menu item in a desktop project. Used by menu bars and contextual menus.
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:
|TextSeparator||A menu separator.|
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 on Mac
The Mac framework does not allow a DesktopMenuItem to be used in different places, e.g. several DesktopMenuBars. Trying to do so will raise a MenuHasParentException. In order to avoid the hassle of creating several times the same DesktopMenuItem, you can use the Clone method to make copies.
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.
Other values you can use are: "Opt", "Alt", "Shift". You can combine keys like this:
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.
|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.|
The following code changes the text of the EditPaste menu item to "Paste Special…":
The following code adds a new item in the Edit menu with the text "Paste Special..." just below the Paste item.
EditPasteSpecial.Text = "Paste Special..."
Using the constructor, you can write:
The following code adds a Select All menu item to the Edit menu.
EditSelectAll.Text = "Select All..."
The following code gets the DesktopMenuItem corresponding to the Cut item on the Edit menu.
The following code gets the DesktopMenuItem corresponding to the Cut item on the Edit menu by position:
The following code removes the fourth dynamically created menu item from a menu item array named WindowItem:
The following code assigns a value to the Tag property of a menu item:
Contextual Menus Code Samples
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.
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.
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.
MessageBox("You chose Import")
MessageBox("You chose export")
MessageBox("You chose Cut")
MessageBox("You chose Copy")
MessageBox("You chose Paste")
Dynamic Menus Code Samples
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.Open 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.
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:
m = Self.MenuBar
mNew = New DesktopMenuItem
mNew.Text = "Fonts"
mNew.Name = "FontsMenu"
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:
If mNew = Nil Then
MessageBox("Menu parent is nil!")
// build the font menu
For i As Integer = 0 To System.LastFontIndex
child = New AddFont(System.FontAt(i))
Note that the Menu Editor and associated Menu Handlers are not needed. The menu selection is handled by the MenuItemSelected event of the subclass of DesktopMenuItem.
|Using the same DesktopMenuItem in different places raises a MenuHasParentException. You should clone the DesktopMenuItems instead.|