Futurebasic/Language/Reference/menu statement

= MENU statement =

Syntax
To create or alter a menu:

To unhighlight the menu bar:

Revised
February, 2002 (Release 6)

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  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  parameter to zero.

Set the  parameter either to   or , depending on whether you want the menu to be initially enabled or dimmed (you can change this state later).

Set the  parameter to the text that you want to appear as the new menu's title.



This creates a new empty menu (see below to learn how to add items to the menu). The value you choose for  will determine the new menu's position on the menu bar; menus are automatically positioned from left to right in increasing order of their  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  parameter to the ID number of an existing menu.

Set the  parameter to zero.

Set the state parameter to  or.

Do not specify the  parameter (if you do, all the menu's items will go away!)



To add a new item to an existing menu:

 Set the  parameter to the ID number of an existing menu.

Set the  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  parameter.

Set the  parameter to ,   or  , depending on what you want the item's initial state to be (you can change this state later).

Set the  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  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  and   parameters to an existing item in an existing menu.

Set the  parameter to ,   or. Note that setting state to   or to   will remove any existing checkmark on the item.



To change the text of an existing item:

 Set the  and   parameters to an existing item in an existing menu.

Set the  parameter to the desired text. Note that when you change the text of an existing item, all the characters in  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  parameter to the ID number of an existing menu; this is the "parent" menu which will contain the submenu.

Set the  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  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  parameter to a string which ends with these two characters:.



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. See the examples below.

To unhighlight the menu bar:

 Execute the  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 parameter when you're adding a new menu item. Note that when you change the text of an existing item, all the characters in  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.

IMAGE WAS HERE

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  to some number in the range 32 through 235 which is not being used by any existing menu.

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

Items in the Apple Menu You should use the  statement to add items to the top of the Apple Menu. After adding these items, you can use the  statement (with the   parameter set to  ) 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  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):

After adding items to the Help Menu, you can use the  statement (with the  parameter set to   ) to alter the items.

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

Removing Menus Call the  procedure to remove a menu created by the   statement:

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  statement, specifying zero in the   parameter, and specifying a menu title in the   parameter.

To remove an individual item, use the  function and the   procedure:

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  function defined above.

<Strong>IMAGE WAS HERE

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  message of. will be the window number of the window. At this point you may need to react by showing a menu under the cursor.

IMAGE WAS HERE

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