4D Doc Center : APPEND MENU ITEM

4D v13.4

APPEND MENU ITEM


APPEND MENU ITEM ( menu ; itemText {; subMenu {; process {; *}}} )

Parameter	Type	Description
menu	Longint, MenuRef	Menu number or Menu reference
itemText	Text	Text for the new menu items
subMenu	MenuRef	Reference of submenu associated with item
process	Longint	Process reference number
*	Operator	If passed: consider metacharacters as standard characters

Description

The APPEND MENU ITEM command appends new menu items to the menu whose number or reference is passed in menu.

If you omit the process parameter, APPEND MENU ITEM applies to the menu bar for the current process. Otherwise, APPEND MENU ITEM applies to the menu bar for the process whose reference number is passed in process.

Note: If you pass a MenuRef in menu, the process parameter serves no purporse and will be ignored.

If you do not pass the * parameter, APPEND MENU ITEM allows you to append one or several menu items in one call.

You define the items to be appended with the parameter itemText as follows:

Separate each item from the next one with a semi-colon (;). For example,
"ItemText1;ItemText2;ItemText3".
To disable an item: Place an opening parenthesis (() in the item text.
To specify a separation line: Pass "-" or "(-" as item text.
To specify a font style for a line: In the item text, place a less than sign (<) followed by one of these characters:
<B Bold
<I Italic
<U Underline

To add a check mark to an item: In the item text, place an exclamation mark (!) followed by the character you want as a check mark. On Macintosh, the character is displayed; on Windows, a check mark is displayed no matter what character you passed.
To add an icon to an item: In the item text, place a circumflex accent (^) followed by a character whose code plus 208 is the resource ID of a Mac OS-based icon resource.
To add a shortcut to an item: In the item text, place a slash (/) followed by the shortcut character for the item.

Note: Use menus that have a reasonable number of items. For example, if you want to display more than 50 items, consider using a scrollable area in a form instead of a menu.

If you pass the * parameter, the "special" characters (; ( !...) included in the item text will be considered as standard characters and not as metacharacters. This means that you can create menu items like "Copy (special)..." or "Find/Replace...". Note that when the * parameter is passed, you cannot create several items in a single call since the ";" character is considered as a standard character.

Note: The GET MENU ITEMS and Get menu item commands will or will not return any metacharacters in the text of a menu item depending on how it was created: if it was created with the * option, metacharacters will be returned as standard characters.

The optional subMenu parameter can be used to indicate a menu as the added item and thus position a hierarchical submenu. You must pass a menu reference (MenuRef type string) specifying a menu created, for example, using the Create menu command. If the command adds more than one menu item, the submenu is associated with the first item.

Important: The new items do not have any associated methods or actions. These must be associated with the items using the SET MENU ITEM PROPERTY or SET MENU ITEM METHOD commands, or the items can also be managed from within a form method using the Menu selected command.

Example

This example appends the names of the available fonts to the Font menu, which in this example is the sixth menu of the current menu bar:

  ` In the On Startup database method

  ` The font list is loaded and menu item text is built

 FONT LIST(◊asAvailableFont)

 ◊atFontMenuItems:=""

 For($vlFont;1;Size of array(◊asAvailableFont))

    ◊atFontMenuItems:=◊atFontMenuItems+";"+◊asAvailableFont{$vlFont}

 End for

Then, in any form or project method, you can write:

APPEND MENU ITEM(6;◊atFontMenuItems)