From Xojo Documentation
|You are currently browsing the old Xojo documentation site. Please visit the new Xojo documentation site!|
An individual menu item.
|Action||Boolean||Fires when a MenuItem is selected.
Return True to prevent the menu event from proceeding any further in the chain of menu handlers.
|EnableMenu||Fires when a user pulls down a menu.|
|AlternateMenuModifier||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 MenuItem.|
|Boolean||If set to True, the MenuItem 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 EnableMenuItems event handler to explicitly enable an autoenabled menu item. AutoEnable is True by default. When you create dynamic menus by creating a new class based on MenuItem, AutoEnable is also True by default. See the example on dynamic menus in the Examples section.
|Checked||Boolean||Indicates whether or not the menu item is checked.|
|Enabled||Boolean||Indicates whether or not the menu item is enabled. This property can be set only from an EnableMenuItems event handler.
You can enable a menu item either by assigning the Enabled property a value of True or by calling the Enable method.
|Icon||Picture||A picture that is assigned to the MenuItem.
On Macintosh 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.
|Integer||The number of the selected MenuItem when it is part of an array.|
|Key||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 menu item itself were chosen via the mouse pointer.|
|KeyboardShortCut||String||The keyboard shortcut for the MenuItem.
In the Menu Editor, you assign the KeyboardShortCut property using the Key, MenuModifier, AlternateMenuModifier, MacControlKey, MacOptionKey, and PCAltKey properties rather than dealing directly with this property. See the section on the keyboard shortcut in the Notes section.
|MacControlKey||Boolean||The Control key on Macintosh. This property is Macintosh-only. If selected, the Control key must be held down while pressing the value of the Key property in order to trigger the event handler of the menuitem.|
|MacOptionKey||Boolean||The Option key on Macintosh. This property is Macintosh-only. If selected, the Option key must be held down while pressing the value of the Key property to trigger the event handler of the menu item.|
|MenuModifier||Boolean||The Control key on Windows and Linux and the Command key on Macintosh. If this property is selected, the MenuModifier key must be held down while pressing the key specified by the Key property to trigger the event handler for the menu item.|
|Name||String||The name of the menu item.|
|PCAltKey||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 menu item. This property is for Windows and Linux only.|
|Tag||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.
|Text||String||The text of the menu item.|
|Visible||Boolean||Indicates whether or not the menu item is visible. This property is not supported on Windows.|
|Item as MenuItem||Appends the passed MenuItem to the menu. You can append a Separator by passing the class constant MenuItem.TextSeparator. Used to build a dynamic menu,|
|Name as String||MenuItem||Looks up menu items by Name and returns a MenuItem.|
|Child||Text as String||MenuItem||Looks up menu items by Text and returns a MenuItem.|
|Close||Removes dynamically created menu items.|
|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.
|Enable||Sets the Enabled property of the menu item to True. Call Enable only within an EnableMenuItems event handler.|
|Index as Integer,
Item as MenuItem
|Inserts Item as a MenuItem at the position indicated by Index. Index is zero-based.
You can insert a Separator by passing the class constant MenuItem.TextSeparator.
|Index as Integer||MenuItem||Item returns as a MenuItem the item indicated by its index (zero-based).
If the passed index is out of range, REALbasic throws an OutOfBoundsException.
|[x as Integer,
y as Integer]
|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.
|Index as Integer||Removes the MenuItem specified by its position (index).|
|Child as MenuItem||Removes the MenuItem specified by reference.|
|MenuItem||Name as String [,Tag as String]||Sets the Text property and optionally the Tag property of the new MenuItem.|
The Examples section shows how to use the MenuItem constructor to add a "Paste Special..." item to the built-in Edit menu.
The following class constant is used to add a separator item to a menu. Use this constant to add a separator with the Append or Insert methods
|TextSeparator||A menu separator.|
MenuItem 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 Checked property. You can also enable or disable a menu item using the Enabled property. The Enabled property should be set only from within an EnableMenuitems event handler. Setting it from anywhere else has no effect.
Three other classes handle specialized menu items. QuitMenuItem is designed to manage the File . Quit (File . Exit on Windows and Linux) menu of a built application; it is enabled by default and automatically calls the Quit method. The PrefsMenuItem class is designed to handle the Preferences menu item. In Mac OS X, 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 PrefsMenuItem class automatically appears under the application's menu under Mac OS X; on other operating systems is appears where you put it in the Menu Editor. The AppleMenuItem class is designed for creating menu items that appear under the application's menu on Mac OS X. Any menu subclassed from AppleMenuItem will move to the application's menu for your Mac OS X build but stay where it is for your other builds.
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 Key property and (normally) at least one modifier key. The Menu Editor translates your settings into the value for the KeyboardShortcut 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 sent 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.
For Macintosh, use "Cmd" instead of "Ctrl." Or set the MenuModifier property to True in code and pass the string literal for the desired keyboard shortcut.
When you are setting a non-printable key in the IDE, you can just enter its name from the list above and select the desired modifier key from the following list.
The Key property entry and the entries for the modifier keys are described in the table below.
|The Shift key on all platforms. If selected, the Shift key must be held down while pressing the value of the Key property to trigger the event handler of the MenuItem.|
|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.|
|The Control key on Macintosh. This property is Macintosh-only. If selected, the Control key must be held down while pressing the value of the Key property in order to trigger the event handler of the menuitem.|
|The Option key on Macintosh. This property is Macintosh-only. If selected, the Option key must be held down while pressing the value of the Key property to trigger the event handler of the menu item.|
|The Control key on Windows and Linux and the Command key on Macintosh. If this property is selected, the MenuModifier key must be held down while pressing the key specified by the Key property to trigger the event handler for the menu item.|
|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 menu item. This property is for Windows and Linux only.|
The following example changes the text of the EditPaste menu item to "Paste Special…":
The following example inserts a new item in the Edit menu with the text "Paste Special..." just below the Paste item.
Using the constructor, you can write:
The following example adds a Select All menu item to the Edit menu.
The following example gets the MenuItem corresponding to the Cut item on the Edit menu.
Dim c as MenuItem
The following example gets the MenuItem corresponding to the Cut item on the Edit menu by position:
Dim c as MenuItem
The following example removes the fourth dynamically created menu item from a menu item array named WindowItem:
The following example assigns a value to the Tag property of a menu item:
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.
Dim m as MenuItem
In general you should create and display contextual menus using the ConstructContextualMenu and ContextualMenuAction event handlers of the Window and RectControl classes. They are fully cross-platform and don't make assumptions about how the user requested a contextual menu.
The following code in the ContextualMenuAction event handles the menu selection. This event passes in the parameter hitItem as MenuItem. This is the selected menu item.
Select Case hititem.text
MsgBox "You chose Import"
MsgBox "You chose export"
MsgBox "You chose Cut"
MsgBox "You chose Copy"
MsgBox "You chose Paste"
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 recommeded technique is to create a subclass of MenuItem in the Project Window. To create the menuitems, you use the MenuItem's constructor to instantiate an instance of the class for each menuitem you need. You handle the menuitem in the Action 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.Open event or the Open 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.Open event, we will add the MenuItem subclass to the project We will name it "AddFont" and set its Super Class to MenuItem. It will use the constructor to add each menuitem. The constructor takes the MenuItem'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 MenuItem subclass has two events, Action and EnableMenu. You do not need to use EnableMenu because AutoEnable is True by default. You do need to add code to the Action 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 TextArea to the font that the user chose. The Action event is simply
Next, we want to add code to the App.Open 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:
Dim m,mNew as MenuItem
The next block of code populates the Font menu. It uses the built-in Font 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:
Dim child as MenuItem
MsgBox "parent is nil!"
//build the font menu
Note that the Menu Editor and associated Menu Handlers are not needed. The menu selection is handled by the Action event of the subclass of MenuItem.