Programming Guide

Makes a menu available for display

void int sm_menu_install(int scope, int mem_location, char *script, char *menu);

scope

Specifies the menu's scope within the application with one of these constants:

MNS_APPLIC

Associates menu with the application and displays it. An application menu displays with all screens unless you install another menu at screen scope (MNS_SCREEN). Under Motif, the application menu can display on the base window along with the active screen's menu if you set the baseWindow and formMenus resources to true. You can install an application menu only from a script that is loaded into application (MNL_APPLIC) memory.

MNS_SCREEN

Associates menu with the current screen and displays it. The menu displays when its screen is invoked or reexposed. You can install a screen menu from a script that is loaded into application (MNL_APPLIC) or screen (MNL_SCREEN) memory.

MNS_SCRN_POPUP

Associates menu with the current screen and makes it available for display as a popup that the user invokes when the cursor is outside a field or in field that has no menu associated with it. You can install a screen popup menu from a script that is loaded into application (MNL_APPLIC) or screen (MNL_SCREEN) memory.

MNS_FIELD

Associates a menu with the current field, and makes it available for display as a popup that the user invokes while in that field. You can install a field menu from a script in any memory location.

mem_location

Specifies the memory location in which script is loaded. A script's memory location determines the scope at which you can install its menus—for example, you can install a screen menu only from a script that is loaded into screen (MNL_SCREEN) or application (MNL_APPLIC) memory. You load a menu script into memory with sm_mnscript_load with one of the arguments in the following table. The table shows which scope arguments are valid for each memory location:

Memory location	Valid scopes
MNL_APPLIC	All
MNL_SCREEN	MNS_SCREEN, MNS_SCRN_POPUP, MNS_FIELD
MNL_FIELD	MNS_FIELD
MNL_ANY	Panther searches for the menu's script in all memory locations that are valid for the menu's scope, starting with the "lowest" location. For example, if you want to install a screen-level menu, (MNS_SCREEN), Panther first looks in screen memory, (MNL_SCREEN), then in application memory (MNL_APPLIC).

Refer to sm_mnscript_load for more information about these arguments.

script

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

menu

Specifies a menu definition in script to install. If you supply an empty string, Panther installs the first menu definition in script. Make sure that menu names among all scripts loaded at the same memory location are unique; otherwise, results can be unpredictable.

If you supply NULL, Panther uses the first menu in script. A NULL value requires you to supply a non-NULL value for script.

• 0 MNERR_OK: Success.

• -1 MNERR_SCRIPT: Script not found, or script or menu name not supplied.

• -3 MNERR_NOT_SUPPORTED: Invalid scope or menus not supported.

• -4 MNERR_MENU: Menu name not found.

• -7 MNERR_MALLOC: Memory allocation error.

• -10 MNERR_LOCATION: Invalid memory location for specified scope.

sm_menu_install finds a menu in the specified script and memory location and reads its definition. If the menu contains external references, Panther resolves these; it then makes the menu available for display.

Except for Motif versions, Panther applications can display only one menu bar at a time. For example, if an application contains multiple screens and each screen has its own menu, Panther displays only the menu bar of the active screen. Under Motif, an application menu and screen menu can display simultaneously.

The scope at which you install a menu determines when Panther displays it; its memory location determines whether you can have identical instances of the same menu.

Menus display according to their scope assignment as follows:

• An application menu displays at all times unless a screen menu is installed. Note that under Motif, an application menu bar can display along with a screen menu.

• A screen menu displays when its screen is invoked or reexposed. This menu also displays with successive screens that lack their own menus: with sibling and child windows; and, if invoked as a form, with other forms invoked later.

• A screen popup menu displays when invoked from an area of the screen that has no field, or when the cursor is in a field that has no menu of its own associated with it.

• A field menu displays as a popup that the user invokes while on that field.

You can install a menu at any scope that is the same or higher than the scope of its caller. For example, the application's startup routines in jmain.c can only install a menu at application scope, while a screen's entry procedure can install a menu at all scopes except field (MNS_FIELD); a field's entry procedure can install menus at all scopes, including field.

Panther installs a screen menu with the current screen, a field menu with the current field. If another menu is already installed at the specified scope, Panther removes the previous menu. If the same menu is already installed from the same memory location, Panther does not try to reinstall it.

Because a script can be loaded only once into a given memory location, all menus installed from that location are identical. Panther provides only one memory location at the application level (MNL_APPLIC). So, all scripts in application memory are unique, and all instances of a menu installed from application memory are the same: changes in one are immediately propagated to all others.

You can install the same menu from application memory for different screens and fields; if you do, all instances of this menu are always the same. If you install the same menu from screen memory for different fields on that screen; all popup menus of those fields are identical.

For example, the following JPL procedure in an application's startup screen loads a menu script into application memory; it then installs the menu scr_mn for the startup screen from application memory:

if sm_mnscript_load(MNL_APPLIC, "mnscript_myprog") == MNERR_OK

   call sm_menu_install \
        (MNS_SCREEN, MNL_APPLIC,"mnscript_myprog", "scr_mn")
else
{
   msg emsg "No menu found for application. Goodbye"
   call jm_exit
}
return 

Subsequently, other screens in this application can install their own instances of this menu with the following call:

call sm_menu_install \
     (MNS_SCREEN, MNL_APPLIC, "mnscript_myprog", "scr_mn")

All screens that display the scr_mn menu display the same menu. Thus, if one screen makes a menu option inactive, that option is inactive when other screens display that menu.

Conversely, you can install multiple copies of the same menu for screens and widgets, where each copy is unique. Because screens and widgets can load menu scripts into their private memory locations, each location can maintain its own copy of a menu; changes to one have no effect on the others.

To install unique copies of the same menu for several screens, repeat these steps for each screen:

1. Load the menu script into screen memory—call sm_mnscript_load with an argument of MNL_SCREEN.
2. Install the menu from screen memory—call sm_menu_install with arguments of MNS_SCREEN and MNL_SCREEN.

Similarly, you can make sure that several widgets on a screen have unique copies of the same popup menu. Repeat these steps for each field:

1. Load the menu script into field memory for the widget—call sm_mnscript_load with an argument of MNL_FIELD.
2. Install the menu from the widget's memory—call sm_menu_install with arguments of MNS_FIELD and MNL_FIELD.

A menu definition can specify submenus whose contents are defined outside the current script—that is, the submenu's External property is set to Yes. For maximum flexibility, the external flag contains no information about this menu's script name. Consequently, when you install a menu, Panther resolves external references by searching first among scripts in the same memory location, then among scripts in the next highest memory location, and so on.

For example, given a menu installed from screen memory, Panther tries to resolve each of its external references first by searching among other scripts in screen memory; if no match is found in screen memory, Panther continues the search among the scripts loaded into application memory. If no menu is found in any memory location, Panther displays an empty submenu.

You can explicitly remove any instance of a menu by calling sm_menu_remove. Otherwise, the menu remains installed until its screen or widget is removed from memory—for example, when a screen with its own menu is removed from the form or window stack. Panther automatically removes all menus and frees their memory when the application exits.

---

---