menu statement

	<< Index >>	FutureBasic 5
menu		statement

Syntax:
To create or alter a menu:
menu menuID, itemID, state [, string$ [, commandID ]]
To unhighlight the menu bar: menu

Description:
Use this statement to do any of the following:

Add a new menu to the menu bar.
Enable or disable a menu.
Add a new item to an existing menu.
Enable or disable a menu item.
Add or remove a checkmark from a menu item.
Change the text of a menu item.
Specify a hierarchical submenu to be attached to a menu item
Unhighlight the menu bar.

To add a new menu to the menu bar:

Set the menuID parameter to a number which is not already in use by an existing menu. Use a number in the range 1 through 31.
Set the itemID parameter to zero.
Set the state parameter either to _enable or _disable, depending on whether you want the menu to be initially enabled or dimmed (you can change this state later).
Set the string$ parameter to the text that you want to appear as the new menu's title.
Set the commandID parameter to the desired commandID for the menu item.

This creates a new empty menu (see below to learn how to add items to the menu). The value you choose for menuID will determine the new menu's position on the menu bar; menus are automatically positioned from left to right in increasing order of their menuID numbers. Almost always, you'll want to assign your menus consecutive numbers starting with 1.
To enable or disable (dim) an existing menu:

Set the menuID parameter to the ID number of an existing menu.
Set the itemID parameter to zero.
Set the state parameter to _enable or _disable.
Do not specify the string$ parameter (if you do, all the menu's items will go away!)

To add a new item to an existing menu:

Set the menuID parameter to the ID number of an existing menu.
Set the itemID parameter to a positive number which is not being used by any other item in the menu. This number determines the item's position in the menu; items are numbered consecutively from top to bottom starting with 1. If you "skip" an item, then either a blank space or a grey dividing line will appear in that position, depending on what version of System software you're using. Note that a grey dividing line between items has its own item ID number. You can create a grey dividing line by using the meta character "-" in the string$ parameter.
Set the state parameter to _enable, _disable or _checked, depending on what you want the item's initial state to be (you can change this state later).
Set the string$ parameter to the text that you want to appear in the item. Note that when you're adding a new item, certain special characters in string$ won't appear in the item text but have other special meanings. Consult the "Meta Characters" table below.

To enable, disable (dim), or checkmark an existing item:

Set the menuID and itemID parameters to an existing item in an existing menu.
Set the state parameter to _enable, _disable or _checked. Note that setting state to _enable or to _disable will remove any existing checkmark on the item.

To change the text of an existing item:

Set the menuID and itemID parameters to an existing item in an existing menu.
Set the string$ parameter to the desired text. Note that when you change the text of an existing item, all the characters in string$ will appear in the item text, and none will be interpreted as "meta characters."

To specify a hierarchical submenu to be attached to a menu item:

Set the menuID parameter to the ID number of an existing menu; this is the "parent" menu which will contain the submenu.
Set the itemID parameter to a positive number which is not being used by any other item in the menu. This is the "parent" item to which the submenu will be attached.
Set the state parameter to the ID number of the submenu. This should be a number in the range 32 through 235 which is not being used by any other menu.
Set the string$ parameter to a string which ends with these two characters: "/" + chr$(&1B).

Note: The above procedure will attach the submenu to the parent menu item, but it doesn't install the submenu. To install the submenu, you also need to call the Toolbox procedure InsertMenu. See the examples below.
To unhighlight the menu bar:

Execute the menu statement without any parameters. The menu bar is automatically highlighted every time the user selects a menu item, and it remains highlighted until your program unhighlights it. By unhighlighting the menu bar, your program lets the user know that the action associated with that menu item has completed.

Meta Characters
The characters in this table have special meanings when they appear in the string$ parameter when you're adding a new menu item. Note that when you change the text of an existing item, all the characters in string$ will appear in the item text, and none will be interpreted as meta characters. The exception to this rule is a string that starts with a minus sign. The minus sign is a flag used by most menu definitions do draw a divider line. If your item needs to contain a minus sign, you may still display the item properly if you put a space before the character.

Meta character	Effect
;	When it appears by itself, ";" creates a grey dividing line. When it appears as a delimiter in a list (e.g., "item1;item2"), each of the items in the list becomes a separate menu item. You can use this fact to add several new menu items with just a single Menu statement.
(	When it appears in an item that follows a semicolon, "(" initially disables (dims) the item.
/	The character following "/" becomes a command-key equivalent for the menu item. Or, if the character following "/" is Chr$(&1B), it indicates that this menu item has a submenu.
!	When "!" appears in an item that follows a semicolon, the character following "!" is displayed as a "mark" on the left side of the menu item.
^	The number (1 through 9) following "^" is added to 256 to get an icon resource number. The corresponding icon is displayed on the left side of the menu item.
-	Creates a grey dividing line. Any other characters in the item string are ignored.
<	The letter following "<" is interpreted as a text attribute to be applied to the menu item. Use one of the following letters: B=Bold O=Outlined U=Underlined I=Italic S=Shadowed

Creating Hierarchical Menus
You can use the following function to add a new menu item and attach a new hierarchical menu to it. You should set childMenuID to some number in the range 32 through 235 which is not being used by any existing menu.

local fn MakeHierMenu(parentMenuID,parentMenuItem,¬

    itemString$,childMenuID)

  title$ = "!"+chr$(childMenuID)+itemString$ + "/" + chr$(&1B)

  menu parentMenuID,parentMenuItem,,title$

  call InsertMenu(fn NEWMENU(childMenuID,""), -1)

end fn
After you have called fn MakeHierMenu, you can use the menu statement to add new items to the hierarchical menu (set the menuID parameter to the value of childMenuID).

Items in the Apple Menu
You should use the apple menu statement to add items to the top of the Apple Menu. After adding these items, you can use the menu statement (with the menuID parameter set to _appleMenu) to alter the items (for example to enable or dim them).

Items in the Help Menu
You can add items to the bottom of the Help Menu by getting a handle for the Help Menu and then calling the AppendMenu procedure. You also need to find out the item number of your first Help item for use by your menu event handler (any existing items are handled by the Help Manager):

dim as int OSErr, @ firstCustomHelpItem

dim as Handle @ hmHandle

#if carbonlib

   OSErr = fn HMGETHELPMENU(hmHandle, firstCustomHelpItem)

#else

   OSErr = fn HMGETHELPMENUHANDLE(hmHandle)

   firstCustomHelpItem = fn COUNTMITEMS(hmHandle)+1

#endif

call AppendMenu(hmHandle, "My Help")
After adding items to the Help Menu, you can use the menu statement (with the menuID parameter set to _kHMHelpMenuID ) to alter the items.

Note:
Do not use the menu statement to add new items to the Help Menu; use AppendMenu instead.

Removing Menus
Call the DeleteMenu procedure to remove a menu created by the menu statement:
call DeleteMenu(menuID)
This may cause other menus in the menu bar to slide to the left to fill the gap; however, they still retain their original menu ID numbers.

Removing Menu Items
To remove all the items from a menu you created, use the menu statement, specifying zero in the itemID parameter, and specifying a menu title in the string$ parameter.
To remove an individual item, use the GetMHandle function and the DelMenuItem procedure:
call DELMENUITEM(fn GETMHANDLE(menuID), itemID)
Note that this will renumber any items below the deleted item, as they move up to fill in the gap. Menu item numbers are always numbered consecutively starting with 1.

Example:
The following lines create a complete menu which also contains a hierarchical menu. This example makes use of the MakeHierMenu function defined above.

menu 3,0,_enable,"Game"

menu 3,1,_enable,"See High Scores/H"

menu 3,2,_enable,"Reset High Scores/R"

menu 3,3,_disable,"-"

fn MakeHierMenu(3,4,"Scenarios",100)

'Items in hierarchical menu:

menu 100,1,_checked,"Level 1"

menu 100,2,_enable,"Level 2"

menu 100,3,_enable,"Level 3"

'It takes two menu statements to include a

'special character like "!" in the text:

menu 3,5,_enable,"dummy"   'This adds the item

menu 3,5,_enable,"Play Now!"   'This alters the item

Contextual Menus
At about the time that the Appearance Manager came on to the scene, programmers began to use contextual menus. A contextual menu appears when the user clicks at a specific area in a window while holding down the control key. When this type of action takes place, you will receive (Appearance Manager Runtime only) a dialog(0) message of _cntxtMenuClick. dialog(_cntxtMenuClick) will be the window number of the window. At this point you may need to react by showing a menu under the cursor.
Menu Statement Contextual Image

The following function builds and displays a menu and might be called in reaction to a contextual menu click.

local fn DoContextMenu( wNum as long )

  dim @ selectionType as long

  dim @ menuID as short

  dim @ menuItem as short

  dim mHndl as Handle

  dim err as OSStatus

  dim helpItemString as Str255

  mHndl = fn NEWMENU(255, "X")

  long if mHndl

    InsertMenu( mHndl, -1 )

    AppendMenu( mHndl, ¬

      "ContextualMenu click in window" + str$( wNum ) )

    helpItemString = "My Custom Help"

    err = fn CONTEXTUALMENUSELECT( mHndl, ¬

      #gFBTheEvent.where, _nil, _kCMHelpItemNoHelp, ¬

      @helpItemString, #_nil, @selectionType, ¬

      @menuID, @menuItem )

    /*

    In this function, we don't actually do anything with the

    selectionType, menuID, or menuItem returned, but we

    could react to it right here

    */

    DisposeMenu( mHndl )

  end if

end fn

See Also:
menu function; on menu fn; apple menu