FutureBasic Logo

<<    Index    >> FutureBasic 5

menu   statement

To create or alter a menu:
menu menuID, itemID, state [, PascalString | CFString | CFArray [, commandID ]] PascalString is OBSOLETE as of 5.7.102
menu menuID, itemID, state [, CFString | CFArray [, commandID ]]

To unhighlight the menu bar: menu

As of FB 5.7.102, a CFString is required and pascal strings are rejected. CFStrings are more flexible and can handle special UTF-8 characters such as superscripts/subscripts. Recommend reviewing the last menu statement section describing menu creation with CFStrings.

Use this statement to do any of the following:
To add a new menu to the menu bar:
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:
To add a new item to an existing menu:
To enable, disable (dim), or checkmark an existing item:
To change the text of an existing item:
To specify a hierarchical submenu to be attached to a menu item:
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:
Meta Characters
The characters in this table have special meanings when they appear in the PascalString parameter when you're adding a new menu item. Note that when you change the text of an existing item, all the characters in PascalString 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 characterEffect
;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.
-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,¬

  titlePascalString = "!"+chr$(childMenuID)+itemPascalString + "/" + chr$(&1B)
  menu parentMenuID,parentMenuItem,,titlePascalString
  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)
   firstCustomHelpItem = fn COUNTMITEMS(hmHandle)+1

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.

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 PascalString parameter.
To remove an individual item, use the GetMHandle function and the DelMenuItem 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.

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

Menu Statement Main Image
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 helpItemPascalString as Str255
  mHndl = fn NEWMENU(255, "X")
  long if mHndl
    InsertMenu( mHndl, -1 )
    AppendMenu( mHndl, ¬
      "ContextualMenu click in window" + str$( wNum ) )
    helpItemPascalString = "My Custom Help"
    err = fn CONTEXTUALMENUSELECT( mHndl, ¬
      #gFBTheEvent.where, _nil, _kCMHelpItemNoHelp, ¬
      @helpItemPascalString, #_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

Creating Menus with CFStrings and CFArrays
Starting in FB 5.7.39, the Menu statements can accept Core Foundation strings or arrays with the added benefit that special characters can be added to menus: Resource Menus Created with FB's Menu Statement
FB's menu statement (as of version 5.7.39+) no longer supports resource menus. FBers can still use Apple's native menu calls for resources but this is not recommended.

New CoreFoundation Menu Statement helpers available in FB 5.7.42:

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