GuiAddMenu()

Adds a menu heading/item to a window's menu, or changes the menu for a window.


Synopsis

error = GuiAddMenu(Specification, Option, Additional)


Args

The Specification and Additional args depend upon Option as described below.

Option is one of the following.

Options Meaning
MENU Changes the menu for the window. Specification is the name of the MENU resource definition to set as the window's menu. If supplying the name directly, quote it.
HEADING Adds a new heading to the menu. A heading has items attached to it. Specification is the MENU definition line for the heading to be added. Additional is the position at which the heading is to be added. See Notes for details.
ITEM Adds a new item to some menu heading. A item can be selected by the user, unless you're adding a separator line. Specification is the MENU definition line for the item to be added. Additional is the position at which the item is to be added. See Notes for details.
POPUP Creates and lets the user operate a popup menu. Specification is the name of the MENU resource definition to set as the popup menu. If supplying the name directly, quote it. Additional is the X and Y positions where to present the popup menu on the screen. (If omitted, then GuiAddMenu uses the current position of the mouse pointer). GuiAddMenu does not return until the user has dismissed the popup menu. Note that one of your menu event callbacks may be called if the user selects an item in the popup menu.

If Option is omitted, then it defaults to 'POPUP'.


Returns

If successful, an empty string is returned. Otherwise, an error message.


Notes

Every heading and item (in a menu) has a unique position. Positions are referenced by where a heading/item appears in the menu. The position of an item includes the position of the heading that it falls under. The position of a sub-item includes the positions of both the item and heading that the sub-item falls under.

For example, assume that you have 2 Menu Headings labeled "File" and "Edit". "File" has 2 items labeled "Open" and "Save". The first item ("Open") has 2 subitems labeled "All" and "Excerpt". Here's how the menu would look displayed:

"File" is heading 1 and "Edit" is heading 2. So, the position of the "File" heading is simply '1', and the position of the "Edit" heading is '2'. "Open" is at position 1 under "File", so its effective position is '1 1'. (A space separates an item's position from its heading's position). "Save" is at position 2 under "File", so its effective position is '1 2'.

"Open" has two subitems. So, the position of "All" is '1 1 1', and the position of "Excerpt" is '1 1 2'.

Note: A separator line also counts in enumerating the positions. For example, if there was a separator line between "Open" and "Save", then it would have a position of '1 2'. And "Save" would therefore have a position of '1 3'.


When adding a heading, you must specify its caption (text) as the Specification arg. For example, to add a heading (with the caption "My heading", and the "h" underlined for a mnuemonic) at position 3:

GuiAddMenu('My &heading', 'HEADING', 3)
You can then add another heading (with the caption "My item 1") at the first position beneath this new heading.
GuiAddMenu('My item 1', 'HEADING', 3 1)
When adding an item, you must specify its caption (text) in the Specification arg. But you can also supply other information, such as any accelerator, and options such as "MARK", "ID", "DISABLE", etc. The caption, accelerator, and options are each separated by a comma. The format for Specification is:
caption, variable, accelerator, options
For example, here we add a sub-item (with the caption "My sub 1") at the first position beneath the "My item 1" heading added above. We omit the accelerator, and specify an option of MARK and DISABLE.
GuiAddMenu('My sub 1, , , MARK | DISABLE', 'ITEM', 3 1 1)
Here we add a second sub-item (with the caption "My sub 2") at the second position beneath the "My item 1" heading added above. We specify an accelerator of CTRL C, and omit any options.
GuiAddMenu('My sub 2, , CTRL "C"', 'ITEM', 3 1 2)
Here we add a second item (with the caption "My Item 2") at the second position beneath "My heading". We do not specify any accelerator, nor options.
GuiAddMenu('My Item 2', 'ITEM', 3 2)