Classes 7
Contents
Menus
About this chapter
This chapter describes the Mops classes and words that allow you to build your application's menus.
| Inside Macintosh: | Event Manager |
|---|---|
| Menu Manager | |
| Mops: | Events |
| Menu | zMenu |
| MenuMod.txt | zMenuMod.txt |
Using Menus
Mops menus integrate the Toolbox concept of a menu within an object that stores Mops words to be executed when the user makes a particular choice. The Mops event object, fEvent, takes care of actually pulling down the menus by tracking the mouse and calling the menu manager whenever there is a click in the menu bar. FEvent also handles key-equivalents for you automatically if you declare the key equivalents in your item text. If the user makes a choice, a message is sent to the Mops menuBar object telling it to find the menu affected and execute the cell indexed by the item number chosen. Menus are a subclass of X-Array, which provides the ability to execute one of a list of xts by index.
There are two steps to defining the menus for your application. You must first create an object of class Menu for each menu in the application, and allocate as many indexed cells to each menu object as there are items to be selected. For example:
7 menu FileMen \ creates a menu object that can have up to 7 items
However, if you have many menu items with similar behavior, such as in a font menu, you only need to provide one indexed cell for that behavior, provided it is the last. This is because if a menu item is selected whose number is beyond the last indexed cell of the menu object, no error occurs, but the last indexed cell is executed. This feature is useful for the Apple menu as well. Note that even divider lines in your menu count as items, and you have to leave space for them, and allocate them an xt, in your menu (you can just use NULL).
Then, in ResEdit, you create menu resources for your menus. This is quite easy to do. You will need to assign a resource ID for your menus in ResEdit—it is quite satisfactory to give the Apple menu ID 1, the Edit menu ID 2 and so on. Then, when you initialize each menu object in Mops with the init: method, you will pass the corresponding resource ID, along with an xt list giving the word to be executed corresponding to each menu item. Finally, at run time you send getnew: to each menu object to cause the menu to appear.
Menu items which call hierarchical menus need to have a special character appended to the name of the menu item. See IM-IV for more info.
After your menus are set up, various methods are available to change their characteristics. getitem: and setitem: fetch and store the item string for a given item. Note that while the Menu Manager numbers items from 1 to N instead of starting from 0, in Mops we follow our normal convention of starting from 0. This means that the xt for the word to be executed when item N is selected (using our numbering) will be item number N in the xt list. The Toolbox automatically highlights (turns black) any menu title for which an item is chosen, and the normal: method can be used to unhighlight any menu. Class Menu automatically does a normal: after a handler returns, but some never return if they do a BECOME or an ABORT. Class Menu's enableItem: and disableItem: methods are useful during activate events, when you should ensure that only those menu items are enabled that are appropriate for the current window and the current state. If you want to enable or disable an entire menu, use enable: and disable:. To enable or disable the entire menu bar, use MBar's enable: and disable: methods. Finally, check: and unCheck: (in Menu) control the display of a checkmark next to an item.
Mops defines a single instance of class MBar, called menuBar. Because forward references to this object were necessary, menuBar is vectored through a Value. As a result, any messages that you send to the menuBar object will be late-bound. You should rarely need to communicate with MenuBar directly, because most of the methods important to an application are in class Menu.
Classes
Menu
Class menu creates objects that associate Mops words with each of the items in a Macintosh menu. The Mops word associated with an item is executed when that item is chosen by the user.
| Superclass | X-Array | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| Source file | Menu, MenuMod.txt, zMenu, zMenuMod.txt | |||||||||
| Status | Core | |||||||||
| Instance variables | ||||||||||
| ||||||||||
| Indexed data | 4-byte cells (must be xts of valid Mops words) | |||||||||
| System objects | None |
| Inherits: | X-Array, Array, Indexed-Obj, Object |
|---|
| initialization | ||
|---|---|---|
| putResID: | ( resID -- ) | Sets the resource ID for this menu |
| init: | ( xt1 ... xtN N resID -- ) | Sets the xt list and resource ID for this menu. This may be done at compile time. |
| runtime control | ||
| SetNib: | ( addr len -- ) | PowerMops Only. Initializes Nib resource package name by add len string. Input Nib package name without .nib extension. This requires runtime initialization. |
| new: | ( addr len -- ) | Calls the toolbox to create a new menu using this object's data as the menu record. Not resource based. The title is passed in |
| getNew: | ( -- ) | Calls the toolbox to create a new resource-based menu. We recommend that you use init: and getNew: as the normal means of creating a menu |
| CreateFormNib: | ( addr len -- ) | PowerMops Only. Calls the toolbox to create a new Nib resource-based menu. The instance name is passed in. The name will become the default menu title. |
| insert: | ( -- ) | Inserts this menu into the menu bar |
| addRes: | ( type -- ) | Adds all resources of a type to this menu. Use this to append fonts or Apple menu items to a menu |
| release: | ( -- ) | Releases the menu's heap storage. |
| operations on the whole menu | ||
| normal: | ( -- ) | Removes the highlighting from all titles across the menu bar (regardless of which menu is the subject of this selector). |
| SetTitle: | ( addr len -- ) | PowerMops Only. Change menu title by addr len string at runtime. |
| operations on individual items | ||
| getItem: | ( item# -- addr len ) | Returns the text string for an item |
| putItem: | ( item# addr len -- ) | Replaces the text string for the item by the passed-in text. The ‘meta-characters’ described in IM don't apply |
| insertItem: | ( item# addr len -- ) | Inserts a new item after the item given by item#. The ‘meta-characters’ described in IM apply—for example, if the text begins with a hyphen, the item will be a dividing line across the width of the menu |
| deleteItem: | ( item# -- ) | Deletes the given item |
| addItem: | ( addr len -- ) | Adds a new item to the end of this menu, with the passed-in text. The text may be blank but should not be the null string. The ‘meta-characters’ described in IM apply |
| add: | ( addr len -- ) | An alias for addItem: |
| enableItem: | ( item# -- ) | Makes an item eligible for selection by the user (black) |
| disableItem: | ( item# -- ) | Makes an item ineligible for selection by the user (gray) |
| openDesk: | ( item# -- ) | 68k Mops only. Runs the desk accessory/Apple menu item named by the specified item |
| exec: | ( item# -- ) | Executes the handler for this item. Menu handlers will have item# on the stack when they execute, and they should leave it there. This way, they can ignore it if they want to, which will be the most common situation. If the item# is too great for this menu, we actually execute the last item rather than give an error. This allows us to save memory when a menu may have dozens of identical items. But of course we don't alter the item# on the stack |
| check: | ( item# -- ) | Shows a check mark by the item |
| unCheck: | ( item# -- ) | Removes a check mark from an item. |
| SeparateLine: | ( item# -- ) | PowerMops only. Change the item into a separate line. |
| SetCommandKey: | ( item# char -- ) | PowerMops only. Set a command key shortcut by char to the item. |
| accessing | ||
| ID: | ( -- resID ) | Returns the resource ID of this menu |
| handle: | ( -- hndl ) | Returns the menu handle. |
Error messages -- “You must send me a new: message first”
An operation was attempted before the menu was created with the Toolbox.
AppleMenu
Subclass AppleMenu facilitates standard Apple Menu support, by filling the menu with all the DAs/Apple Menu items at getNew: time.
| Superclass | Menu | ||||
|---|---|---|---|---|---|
| Source file | MenuMod.txt zMenuMod.txt | ||||
| Status | Core | ||||
| Instance variables | none | ||||
| Indexed data | 4-byte cells (must be xts of valid Mops words) | ||||
| System objects | |||||
|
| Inherits: | Menu, X-Array, Array, Indexed-Obj, Object |
|---|
| accessing | ||
|---|---|---|
| getNew: | ( item# -- ) | Same as getNew: in Menu, but also adds all the DAs/ Apple Menu items via addRes: self |
Error messages - “You must send me a new: message first”
An operation was attempted before the menu was created with the Toolbox.
EditMenu
Subclass EditMenu facilitates standard DA support. The exec: method first calls SystemEdit so any active DA gets a go at it.
| Superclass | Menu |
|---|---|
| Source file | MenuMod.txt |
| Status | Core |
| Instance variables | none |
| Indexed data | 4-byte cells (must be xts of valid Mops words) |
| System objects | None |
| Inherits: | Menu, X-Array, Array, Indexed-Obj, Object |
|---|
| accessing | ||
|---|---|---|
| exec: | ( -- ) | Same as exec: on Menu, but includes a SystemEdit call |
Error messages - “You must send me a new: message first”
An operation was attempted before the menu was created with the Toolbox.
PopupMenu
Class PopupMenu provides support for popUp menus in dialogs. (If you need one somewhere else, you will have to define a subclass with different init: and normal: methods.) The sequence for setting up a popup menu is first to initialize the menu and dialog objects via init: methods—this may be done at compile time. At run time, send getnew: to the dialog and menu, then send a link: to the menu, passing the address of the dialog object. See the example code at the end of the file PopupMenu. The handling of popup menus is notoriously tricky, but we handle most of the mundane details for you. From System 7 onwards there is a system control (CDEF) that you can put into your dialogs with ResEdit in much the same way as you add buttons and checkboxes. See IM ToolBox Essentials - Controls for details.
At present, 68k Mops only.
| Superclass | Menu | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Source file | PopupMenuMod.txt, PopupMenu | |||||||||||||||||||||||||||
| Status | Optional | |||||||||||||||||||||||||||
| Instance variables | ||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||
| Indexed data | 4-byte cells (must be xts of valid Mops words) | |||||||||||||||||||||||||||
| System objects | None |
| Inherits: | Menu, X-Array, Array, Indexed-Obj, Object |
|---|
| accessing | ||
|---|---|---|
| getText: | ( -- addr len ) | Returns the text to be displayed in the pop-up box |
| putText: | ( addr len -- ) | Sets the text to be displayed in the pop-up box. Doesn't attempt to actually display it, since the dialog may not be initialized |
| item#: | ( -- item# ) | Returns the number of the menu item displayed in the pop-up box |
| putItem#: | ( item# -- ) | Sets the number of the menu item to be displayed in the pop-up box |
| putTitle#: | ( title# -- ) | Sets the dialog item number of the pop-up title (note—not the pop-up box!) |
| put^dlg: | ( ^dlg -- ) | Stores the passed-in pointer to the owning dialog object |
| f-link: | ( -- ptr ) | Returns the address of the next popUpMenu object belonging to the same dialog. Returns nilP if none |
| set-f-link: | ( ptr -- ) | Sets the link to the next popUpMenu object belonging to the same dialog. This link (a pointer to a popUpMenu object) is passed in |
| box#: | ( -- n ) | Returns the dialog item number of the pop-up box. |
| runtime control | ||
| init: | ( xt-list resID box# title# -- ) | Initializes the menu |
| getNew: | ( -- ) | As for getNew: on Menu |
| link: | ( ^dlg -- ) | Call this at runtime, after you have sent getnew: to both the dialog and the menu. This method handles all the housekeeping for asso-ciating the menu with the dialog. For example, it installs a userItem handler for the pop-up box (PUBoxProc in file PopupMenu). This word is called from the dialog whenever the pop-up box needs to be redrawn. (Don't confuse this with the action handler for the pop-up box, which handles a click on the box, and which you have to specify when you send init: to the dialog.) |
| operations | ||
| normal: | ( -- ) | Unhilites the pop-up title |
| drawText: | ( -- ) | Draws the text in the pop-up box |
| drawBox: | ( -- ) | Draws the pop-up box, with the required drop shadow and down-pointing arrow symbol. This method will be called automatically when the dialog box is updated, via our userItem handler PUBoxProc. (The pop-up box is a userItem in the dialog, and at link: time we automatically install PUBoxProc as the userItem handler.) |
| hit: | ( -- ) | Handles a click on the pop-up box. Your action handler for the pop-up box (which is an item in the dialog) should include sending hit: to the menu. As well as handling details such as the hiliting of the pop-up box, hit: sends exec: super, to execute your handler for the selected menu item. When your handler gets called, the previously selected item# (whose text was in the pop-up box before) will still be in the item# ivar, while the new one will be on the stack. This will be useful if you need to know if the item# is being changed or not. |
Error messages - “You must send me a new: message first”
An operation was attempted before the menu was created with the Toolbox.
Mbar
MBar is used to create a single system object, MenuBar. It maintains the list of menu objects and their IDs, and is chiefly useful at startup to build and draw the menu bar via messages sent by the menu text loader.
| Superclass | Object | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| Source file | Menu zMenu | |||||||||
| Status | Core | |||||||||
| Instance variables | ||||||||||
| ||||||||||
| Indexed data | None | |||||||||
| System objects | ||||||||||
|
| Inherits: | Object |
|---|
| accessing | ||
|---|---|---|
| clear: | ( -- ) | Clears all menus out of the menu bar |
| add: | ( men0 … menN #menus -- ) | Specifies the menu objects to be added to the menu bar |
| new: | ( -- ) | Calls the toolbox to insert each menu from add: into the menu bar and draws the menu bar |
| init: | ( men0 … menN #menus -- ) | Combines the actions of clear:, add: and new: |
| draw: | ( -- ) | Draws the menu bar. (Primarily used by new:) |
| enable: | ( -- ) | Enables all menus in menu bar |
| disable: | ( -- ) | Disables all menus in menu bar |
| exec: | ( item# menuID -- ) | Executes the handler for the given item in the given menu |
| click: | ( -- ) | Handles a click in the menu bar, calling the toolbox to track menu selection until the mouse button is released. Then executes the handler for the selected item (if any) |
| key: | ( chr -- ) | Executes the handler of an item selected by a command key combination, if any |
Error messages - None
| Views and Controls | Classes | Graphics |
| Documentation |
