FutureBasic Logo

<<    Index    >> FutureBasic 5

menu   function



Syntax:
selectedMenu = menu(_menuID)
selectedItem = menu(_itemID)


Description:
If you have designated a menu-event handling routine in your program (using the on menu statement), then menu(_menuID) returns the menu number, and menu(_itemID) returns the item number, of the menu item most recently selected by the user. Your menu-event handling routine should check these values each time it's called.
To give the user continual access to the menu bar, your program should execute HandleEvents periodically. HandleEvents checks for recent clicks on the menu bar, and responds by opening the menu and tracking the mouse's movement. Finally, HandleEvents calls your menu-event handling function if the user selects a menu item.

Menu Numbers
With the exception of the Apple Menu, the Help Menu and the Application Menu, the menus on the menu bar are numbered in increasing order from left to right. In most cases, they will be numbered consecutively starting with 1. You use the menu statement to assign menu numbers to the menus your program creates.
The number of the Apple Menu equals the constant _AppleMenu. If your program adds new items to the Apple Menu, the menu function can detect when the user selects those items. Other items in the Apple Menu are handled by the Finder, and your program can't detect when the user selects those. You use the apple menu statement to add items to the Apple Menu.
The number of the Help Menu equals the constant _kHMHelpMenuID. If your program adds new items to the Help Menu, the menu function can detect when the user selects those items. Other items in the Help Menu are handled by the Help Manager, and your program can't detect when the user selects those. To add new items to the Help Menu, you use the Toolbox routines HMGetMenuHandle and AppendMenu (see the menustatement for an example of how to do this).
Your program can't directly detect an item selected in the Application Menu; that's handled by the Finder. However, your program can detect when another application has been brought to the front. See the dialog function for more details.
Your program can also detect when the parent item that pops out a hierarchical menu is selected. This is turned on and off by a constant in the file named UserFloatPrefs which is located in the User Libraries folder. One (undesirable) side effect of enabling this feature is that a menu grayed by setting its title to a disabled state will produce menu events in inactive items. To use the old method (this is the default state) of ignoring hierarchical items, remark out the line in that reads...
_FBEnableMenuChoice = _zTrue
To enable the new feature, remove the remarks and allow the constant to be defined. This declaration is in the file named UserFloatPrefs which is located in the User Libraries folder.
Hierarchical menus have their own menu numbers that are different from their "parent" menu's number. You can use the menu function to detect selection in hierarchical menus that your program creates.
Pop-up menus are considered to be window controls (like buttons), and are therefore not detected by the menu function.

Item Numbers
Menu items are numbered consecutively from top to bottom, starting with 1. Note that a grey dividing line between items has its own item number, even though it can't be selected. It's important to remember this when assigning and interpreting item numbers. Items within hierarchical menus are also numbered consecutively starting with 1.
MENU Function Image

See Also:
menu statement; apple menu; HandleEvents; on menu