sm_*mnitem_get

Programming Guide

Gets a menu item's property
int sm_mnitem_get_int(int mem_location, char *script, char *menu, int item_no, int prop);
int sm_n_mnitem_get_int(int mem_location, char *script, char *menu, char *item_name, int prop);

char *sm_mnitem_get_str(int mem_location, char *script, char *menu, int item_no, int prop);

char *sm_n_mnitem_get_str(int mem_location, char *script, char *menu, char *item_name, int prop);
mem_location
The memory location of the item's menu, one of the following constants:
MNL_APPLIC
MNL_SCREEN
MNL_FIELD
script
The name of a memory-resident script that contains the item's menu. The script must already be loaded into memory at mem_location by sm_mnscript_load.
menu
The name of the item's menu, as listed in the Submenu field of the menu bar editor or with the MENU keyword in an ASCII menu file.
item_no, item_name
Specifies the menu item by its number or name:

sm_mnitem_get identifies the item by its numeric offset within the menu, where the first menu item is 0.

sm_n_mnitem_get identifies the item by its name.

prop
The property to get. Supply one of the constants described in Table 5-17.

Returns

· The property's current value, returned either as an integer or as a pointer to a string value. Because this function stores a returned string in a pool of buffers that it shares with other functions, copy or process this data immediately.

NULL Error returned by _get_str variants. Call sm_menu_bar_error to get the error code.

-1 Error returned by _get_int variants. Call sm_menu_bar_error to get the error code.

Description

sm_mnitem_get_int and sm_mnitem_get_str return the current setting of the specified property. Use the _int variant for those properties that have an integer value—for example, MNI_SEP_STYLE; use the _str variant for properties that take string values, such as MNI_NAME and MNI_ACCEL.
Table 5-17 lists the menu item property constants that you can supply as arguments to the prop parameter and the values that these return. Integer and string properties are listed in separate groups.

Table 5-17 Menu item properties

Constant Property values

Integer properties:

MNI_ACCEL

An accelerator keystroke that specifies the keyboard equivalent for selecting this menu item, valid only for action and toggle menu items.

MNI_ACCEL_ACTIVE

A value of PROP_ON or PROP_OFF specifies whether the menu item accelerator is active.

MNI_ACTIVE

A value of PROP_ON or PROP_OFF allows or disallows user access to this menu item. If MNI_ACTIVE is set to PROP_OFF, the menu item is greyed out.

MNI_DISPLAY_ON

Specifies whether to display the menu item on the menu and/or the tool bar. Supply one of these arguments:

DISPLAY_MENU: Menu only (default).
DISPLAY_TOOL: Tool bar only.
DISPLAY_BOTH: Menu and tool bar.
DISPLAY_NEITHER: Neither.

MNI_INDICATOR

A value of PROP_ON or PROP_OFF specifies whether to show the toggle indicator.

MNI_IS_HELP

A value of PROP_ON or PROP_OFF specifies whether to display this item as the rightmost item on the menu bar.

MNI_MNEMONIC

A zero-based offset into the item's label that specifies which character users can type to select this item, provided the menu is displayed. A value of -1 indicates that the item has no mnemonic set.

MNI_ORDER*

The order in which this item appears on the toolbar. The default value is 100. You can enter any value between 0 and 200, inclusive. If all toolbar items are set to the same value, they appear in the same order as they do in the menu.

MNI_SEP_STYLE

The style used by an item separator, specified by one of these constants:

SEP_SINGLE SEP_DOUBLE SEP_NOLINE SEP_SINGLE_DASHED SEP_DOUBLE_DASHED SEP_ETCHEDIN SEP_ETCHEDOUT SEP_ETCHEDIN_DASHED SEP_ETCHEDOUT_DASHED

MNI_SHOW_ACCEL

A value of PROP_ON or PROP_OFF specifies whether a menu item displays the accelerator key next to the item label.

MNI_TM_CLASS

The transaction manager class assigned to this menu item. This property determines how the item behaves in each of the transaction manager modes. Refer to "Using Styles and Classes" in Using the Editors for more information on transaction manager classes.

MNI_TYPE

The menu item's type, specified by one of the following constants:
MI_SEPARATOR MI_SUBMENU MI_ACTION_BTTN MI_TOGGLE_BTTN MT_WINDOWS_OPT MT_WINDOWS_LIST MT_EDIT_CUT MT_EDIT_DELETE MT_EDIT_PASTE MT_EDIT_SELECT MT_EDIT_COPY MT_EDIT_CLEAR

String properties:

MNI_ACT_PIXMAP*

The name of an image file whose contents are shown for an active toolbar item—that is, accessible but not pressed. Refer to Table 25-1 in Using the Editors for valid file types. File paths and extensions are optional; for more information, refer to "Filename Extensions" in Using the Editors.

MNI_ARM_PIXMAP*

The name of an image file whose contents are shown for an armed toolbar item—that is, in its pressed state. If this property is blank, Motif uses the MNI_ACT_PIXMAP property for the item's armed state. Windows uses a modified version of the Active Pixmap property to display a toolbar item's armed state and ignores this property.

MNI_CONTROL

A control string that specifies the action that occurs when this item is selected.

MNI_EXT_HELP_TAG

A help context identifier that specifies the help to invoke from an external help program.

MNI_HOT_PIXMAP*

The name of an image file whose contents are shown when a pointer moves over an active toolbar item. (Windows only)

MNI_INACT_PIXMAP *

The name of an image file whose contents are shown for an inactive or unavailable (grayed) item. If this property is blank, Motif displays an empty toolbar item. Windows uses a grayed version of the Active Pixmap property to display a toolbar item's inactive state if a pixmap is not specified.

MNI_HELP_SCREEN

The name of a Panther screen to invoke as a help screen.

MNI_LABEL

A string expression to display as this item's label.

MNI_MEMO

A string expression for this menu item's Memo Text property.

MNI_NAME

The menu item's name.

MNI_STAT_TEXT

A string expression to display on the screen's status line when this item has focus.

MNI_SUBMENU

Name of the submenu to invoke when this item is selected.

MNI_TOOL_TIP*

The balloon help to display when the cursor remains over the toolbar item.

* Ignored in character-mode.

Constant	Property values
Integer properties:
`MNI_ACCEL`	An accelerator keystroke that specifies the keyboard equivalent for selecting this menu item, valid only for action and toggle menu items.
`MNI_ACCEL_ACTIVE`	A value of `PROP_ON` or `PROP_OFF` specifies whether the menu item accelerator is active.
`MNI_ACTIVE`	A value of `PROP_ON` or `PROP_OFF` allows or disallows user access to this menu item. If `MNI_ACTIVE` is set to `PROP_OFF`, the menu item is greyed out.
`MNI_DISPLAY_ON`	Specifies whether to display the menu item on the menu and/or the tool bar. Supply one of these arguments: `DISPLAY_MENU`: Menu only (default). `DISPLAY_TOOL`: Tool bar only. `DISPLAY_BOTH`: Menu and tool bar. `DISPLAY_NEITHER`: Neither.
`MNI_INDICATOR`	A value of `PROP_ON` or `PROP_OFF` specifies whether to show the toggle indicator.
`MNI_IS_HELP`	A value of `PROP_ON` or `PROP_OFF` specifies whether to display this item as the rightmost item on the menu bar.
`MNI_MNEMONIC`	A zero-based offset into the item's label that specifies which character users can type to select this item, provided the menu is displayed. A value of -1 indicates that the item has no mnemonic set.
`MNI_ORDER*`	The order in which this item appears on the toolbar. The default value is 100. You can enter any value between 0 and 200, inclusive. If all toolbar items are set to the same value, they appear in the same order as they do in the menu.
`MNI_SEP_STYLE`	The style used by an item separator, specified by one of these constants: `SEP_SINGLE SEP_DOUBLE SEP_NOLINE SEP_SINGLE_DASHED SEP_DOUBLE_DASHED SEP_ETCHEDIN SEP_ETCHEDOUT SEP_ETCHEDIN_DASHED SEP_ETCHEDOUT_DASHED`
`MNI_SHOW_ACCEL`	A value of `PROP_ON` or `PROP_OFF` specifies whether a menu item displays the accelerator key next to the item label.
`MNI_TM_CLASS`	The transaction manager class assigned to this menu item. This property determines how the item behaves in each of the transaction manager modes. Refer to "Using Styles and Classes" in Using the Editors for more information on transaction manager classes.
`MNI_TYPE`	The menu item's type, specified by one of the following constants: `MI_SEPARATOR MI_SUBMENU MI_ACTION_BTTN MI_TOGGLE_BTTN MT_WINDOWS_OPT MT_WINDOWS_LIST MT_EDIT_CUT MT_EDIT_DELETE MT_EDIT_PASTE MT_EDIT_SELECT MT_EDIT_COPY MT_EDIT_CLEAR`
String properties:
`MNI_ACT_PIXMAP*`	The name of an image file whose contents are shown for an active toolbar item—that is, accessible but not pressed. Refer to Table 25-1 in Using the Editors for valid file types. File paths and extensions are optional; for more information, refer to "Filename Extensions" in Using the Editors.
`MNI_ARM_PIXMAP*`	The name of an image file whose contents are shown for an armed toolbar item—that is, in its pressed state. If this property is blank, Motif uses the `MNI_ACT_PIXMAP` property for the item's armed state. Windows uses a modified version of the Active Pixmap property to display a toolbar item's armed state and ignores this property.
`MNI_CONTROL`	A control string that specifies the action that occurs when this item is selected.
`MNI_EXT_HELP_TAG`	A help context identifier that specifies the help to invoke from an external help program.
`MNI_HOT_PIXMAP*`	The name of an image file whose contents are shown when a pointer moves over an active toolbar item. (Windows only)
`MNI_INACT_PIXMAP *`	The name of an image file whose contents are shown for an inactive or unavailable (grayed) item. If this property is blank, Motif displays an empty toolbar item. Windows uses a grayed version of the Active Pixmap property to display a toolbar item's inactive state if a pixmap is not specified.
`MNI_HELP_SCREEN`	The name of a Panther screen to invoke as a help screen.
`MNI_LABEL`	A string expression to display as this item's label.
`MNI_MEMO`	A string expression for this menu item's Memo Text property.
`MNI_NAME`	The menu item's name.
`MNI_STAT_TEXT`	A string expression to display on the screen's status line when this item has focus.
`MNI_SUBMENU`	Name of the submenu to invoke when this item is selected.
`MNI_TOOL_TIP*`	The balloon help to display when the cursor remains over the toolbar item.
* Ignored in character-mode.