Programming Guide

sm_*mnitem_change

Sets a menu item's property 

int sm_mnitem_change(int mem_location, char *script, char *menu, int item_no, int prop, int intval, char *strval);
int sm_n_mnitem_change(int mem_location, char *script, char *menu, char *item_name, int prop, int intval, char *strval);

mem_location
The memory location of the item's menu, one of the following constants: 
MNL_ANY
MNL_APPLIC
MNL_SCREEN
MNL_FIELD

If you supply MNL_ANY, Panther looks for the menu in all memory locations. If the menu is installed in more than one location, the function call fails and returns MN_ERR_LOCATION.

script
The name of a memory-resident script that contains the menu to change. The script must already be loaded into memory at mem_location by sm_mnscript_load. If you supply NULL, Panther searches in the most recently loaded script in mem_location for the specified menu.

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. If you supply NULL, Panther uses the first menu in script.

item_no, item_name
Specifies the menu item to change by its number or name:

prop
The property to change, one of the constants listed in Table 5-14.

intval
The integer value to set for prop. If the property takes a string value, supply 0.

strval
The string value to set for prop. If the property takes an integer value, supply NULL.

Returns

Description

sm_mnitem_change sets the property of a menu item. Menu item properties are derived from a memory-resident script. Because sm_mnitem_change changes the specified script, all instances of items from this script get the property change.

Menu Item Property Constants

Table 5-14 lists menu item property constants and the values you can set these to. Integer and string properties are listed in separate groups.

Table 5-14 Menu item properties that can be changed at runtime

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.

You cannot set this property for main menu items. Accelerator keys for edit-type items such as Edit Cut or Edit Paste are set by the GUI platform—for example, in Windows, through the Panther initialization file; on Motif, in the Panther file. To change edit item accelerators, modify the appropriate GUI file.

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 specifies no mnemonic for this item.

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.

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, and for information about path and extension options.

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. This function does not check for duplicate names.

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_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_TOOL_TIP*

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

* Ignored in character-mode.

Calling from JPL

sm_mnitem_change and sm_n_mnitem_change have too many parameters to allow installation by sm_install; consequently, they are not directly accessible to JPL modules. (Refer to "Installing Prototyped Functions" in Application Development Guide for function installation requirements.) A number of wrapper functions that call sm_mnitem_change and sm_n_mnitem_change are declared and installed in funclist.c. You can call these functions from JPL to modify menu items.

Table 5-15 lists the provided wrapper functions and their parameter declarations. Each wrapper function is narrowly defined to look for a menu in a discrete memory location—application, screen, or field—or to look in all memory locations (the change_i_any and change_s_any variants). Also, the change_i variants set only integer properties; the change_s variants set only string properties. All parameters are identical in type and purpose to those declared for sm_mnitem_change and sm_n_mnitem_change.

Table 5-15 Wrapper functions for changing menu item properties from JPL

Function names Parameter declarations

To modify integer properties, call:

sm_n_mnitem_change_i_any*
sm_n_mnitem_change_i_app
sm_n_mnitem_change_i_screen
sm_n_mnitem_change_i_field

(char *script, char *menu, char *item_name,
int prop, int intval)

sm_mnitem_change_i_any*
sm_mnitem_change_i_app
sm_mnitem_change_i_screen
sm_mnitem_change_i_field

(char *script, char *menu, int item_no,
int prop, int intval)

To modify string properties, call:

sm_n_mnitem_change_s_any*
sm_n_mnitem_change_s_app
sm_n_mnitem_change_s_screen
sm_n_mnitem_change_s_field

(char *script, char *menu, char *item_name,
int prop, char *strval)

sm_mnitem_change_s_any*
sm_mnitem_change_s_app
sm_mnitem_change_s_screen
sm_mnitem_change_s_field

(char *script, char *menu, int item_no
int prop, char *strval)

* Panther looks for the menu in all memory locations. If the menu is installed in more than one location, the function call fails and returns MN_ERR_LOCATION.