4.3BSD-UWisc/man/cat3/XMenu.3x

XMENU(3X) UNIX Programmer's Manual XMENU(3X)

NAME
XMenu - X Deck of cards Menu System

SYNOPSIS
#include <X/XMenu.h>

XMenu *XMenuCreate(parent, xdef_env)
Window parent;
char *xdef_env;

int XMenuAddPane(menu, label, active)
XMenu *menu;
char *label;
int active;

int XMenuAddSelection(menu, pane, data, label, active)
XMenu *menu;
int pane;
char *data;
char *label;
int active;

int XMenuInsertPane(menu, pane, label, active)
XMenu *menu;
int pane;
char *label;
int active;

int XMenuInsertSelection(menu, pane,selection, data, label, active)
XMenu *menu;
int pane, selection;
caddr_d data;
char *label;
int active;

int XMenuFindPane(menu, label)
XMenu *menu;
char *label;

int XMenuFindSelection(menu, pane, label)
XMenu *menu;
int pane;
char *label;

int XMenuChangePane(menu, pane, label)
XMenu *menu;
int pane;
char *label;

int XMenuChangeSelection(menu, pane,selection, data,d_sw, label,l_sw)
XMenu *menu;
int pane, selection;

Printed 1/10/87 29 January 1986 1

XMENU(3X) UNIX Programmer's Manual XMENU(3X)

char *data;
int d_sw;
char *label;
int l_sw;

int XMenuSetPane(menu, pane, active)
XMenu *menu;
int pane;
int active;

int XMenuSetSelection(menu, pane, selection, active)
XMenu *menu;
int pane, selection;
int active;

int XMenuDeletePane(menu, pane)
XMenu *menu;
int pane;

int XMenuDeleteSelection(menu, pane, selection)
XMenu *menu;
int pane, selection;

int XMenuRecompute(menu)
XMenu *menu;

int XMenuLocate(menu, pane,selection, x,y, ulx,uly, width,height)
XMenu *menu;
int pane, selection;
int x, y;
int *ulx, *uly;
int *width, *height;

XMenuSetAEQ(menu, aeq)
XMenu *menu;
int aeq;

XMenuSetEvHandler(menu, handler)
XMenu *menu;
int (*handler)();

XMenuSetFreeze(menu, freeze)
XMenu *menu;
int freeze;

int XMenuActivate(menu, pane,selection, x,y, event_mask, data)
XMenu *menu;
int *pane, *selection;
int x, y;
int event_mask;
char **data;

Printed 1/10/87 29 January 1986 2

XMENU(3X) UNIX Programmer's Manual XMENU(3X)

XMenuDestroy(menu)
XMenu *menu;

char *XMenuError()

DESCRIPTION
_X_M_e_n_u is an _X Window System Utility Package that implements
a `deck of cards' menu system. _X_M_e_n_u is intended for use in
conjunction with _X_l_i_b, the _C _L_a_n_g_u_a_g_e _X _W_i_n_d_o_w _S_y_s_t_e_m _I_n_t_e_r_-
_f_a_c_e _L_i_b_r_a_r_y.

In a `deck of cards' menu system a menu is composed of
several cards or panes. The panes are stacked as if they
were a deck of playing cards that were fanned out. Each of
these panes has one or more selections. A user interacts
with a `deck of cards' menu by sliding the mouse cursor
across the panes of the menu. As the mouse cursor enters
each pane it will rise to the top of the deck and become
`current'. If the current pane is an active pane it will be
`activated', or made available for selection. To indicate
this its background will then change from the patterned
inactive background to a solid color and the selections on
that pane will be activated. If the current pane is not an
active pane (a setable state) then it will not be activated.
To indicate this its background will continue to be the pat-
terned inactive background and no selections on the pane
will be activated. The pane previously containing the mouse
will lower (preserving its stacking order). If it was
activated it will then become deactivated, its background
changing back to the inactive pattern. Because of this
action it is not possible to have more than one current pane
at any one time. When the mouse cursor enters an active
selection in a pane that has been activated then that selec-
tion will become activated and be high lighted. If the
selection is not active or the pane has not been activated
then the selection will not be activated and will not be
high lighted. Selection high lighting is accomplished in
one of two ways depending upon the state of the user's _X_d_e_-
_f_a_u_l_t_s variables. If `box' mode high lighting is in effect,
the menu selection will be activated by placing a high light
box around the selection as the mouse cursor enters the
selection's active region and removing it (deactivating the
selection) as the cursor leaves. If `invert' mode high
lighting is in effect, the menu selection will be activated
by inverting the background and foreground colors within the
selection's active region as the mouse cursor enters it and
reinverting them as the cursor leaves.

The application specifies a mouse event that will signify
that the user has made a selection. Any time that the selec-
tion mouse event is received by _X_M_e_n_u one of several results
will occur, depending upon the state of the menu system at

Printed 1/10/87 29 January 1986 3

XMENU(3X) UNIX Programmer's Manual XMENU(3X)

the time of the event. If the selection event occurs while
the mouse cursor is in an activated selection the data that
has been stored with that selection will be returned to the
application program. The data stored is in the form of a
generic pointer to memory (char *). This allows the appli-
cation programmer to completely define the interpretation of
the selection data by recasting the data pointer as is
desired.

An application constructs a menu by first creating the _X_M_e_n_u
object. Once the _X_M_e_n_u object has been created then panes
and selections are added in order as is needed. Typically
panes contain related selections that are `described' by the
pane's label. For example, you might create a pane labeled
`Mail' that has selections labeled `Read', `Send', `For-
ward', `Refile' and `Delete'. There is no real need for the
panes in a menu to be related to each other but typically
they are related by default by the fact that they are all
being utilized the application that created the menu.

The _X_M_e_n_u system is maintained (menus, panes and selections)
via routines in the _X_M_e_n_u library. The library contains the
following routines:

XMenuCreate
In order for a process to create a menu, it is
necessary for that process to have opened a connec-
tion to an _X display server and have a window in
hand that will be designated as the parent window of
the menu being created (remember that _X is designed
such that child windows of a parent window are
clipped to the borders of the parent). Typically
the _X root window ( _R_o_o_t_W_i_n_d_o_w ) is used for this
purpose. When the connection is open and a parent
window chosen, the application calls _X_M_e_n_u_C_r_e_a_t_e
passing it the parent window and a null-terminated
string. The string designates the default environ-
ment name that will be used by XMenu to read the
users _X_d_e_f_a_u_l_t_s variables. Typically the applica-
tion name is used for this purpose (a good software
engineering practice is to use element zero of the
applications argument vector, argv[0], as the
default environment since this is the name by which
the application was called from the shell). All
_u_s_e_r setable parameters are set via the _X_d_e_f_a_u_l_t_s
mechanism. If any parameters do not have _X_d_e_f_a_u_l_t_s
values then they default to preset _X_M_e_n_u internal
values. The _X_d_e_f_a_u_l_t_s parameters are listed below
along with their preset internal values. If the
create operation is successful _X_M_e_n_u_C_r_e_a_t_e will
return an _X_M_e_n_u object. If it fails NULL will be
returned.

Printed 1/10/87 29 January 1986 4

XMENU(3X) UNIX Programmer's Manual XMENU(3X)

XMenuAddPane
Once a menu has been created the application may
then begin adding panes and subsequently selections.
Panes are added by calling _X_M_e_n_u_A_d_d_P_a_n_e.
_X_M_e_n_u_A_d_d_P_a_n_e adds additional panes to a menu in call
order. That is, panes will appear in the menu with
the first pane added being at the front of the pane
stack and the last pane added being at the back of
the pane stack. _X_M_e_n_u_A_d_d_P_a_n_e takes the following
arguments: The menu to which the pane is being
added; A null-terminated string that will be the
label for the new pane; and an flag that designates
whether or not the pane is to be considered active
for selection. It is sometimes useful to add inac-
tive panes to indicate a currently unavailable but
planned set of selections. If the add operation is
successful the index number of the pane just added
will be returned. If it fails _X_M__F_A_I_L_U_R_E will be
returned. Further panes may be added at a later
time but remember that when this routine is used to
add panes they are always added to the back of the
pane stack!

XMenuAddSelection
Once a pane has been added to a menu is it possible
to begin adding selections to that pane. Selections
are added to panes in much the same way as panes are
added to menus. Selections are added by calling
_X_M_e_n_u_A_d_d_S_e_l_e_c_t_i_o_n. _X_M_e_n_u_A_d_d_S_e_l_e_c_t_i_o_n adds additional
selections to a pane in call order. That is, selec-
tions will appear in the pane with the first selec-
tion added being at the top of the pane and the last
selection added being at the bottom of the pane.
_X_M_e_n_u_A_d_d_S_e_l_e_c_t_i_o_n takes the following arguments: The
menu containing the pane to which the selection is
being added; The index number of the pane to which
the selection is being added; A null-terminated
string that will be the label for the new selection;
A (char *) data value that will be returned by
_X_M_e_n_u_A_c_t_i_v_a_t_e whenever the new selection is selected
by the menu's user; and a flag that designates
whether or not the selection will be considered
active. It is sometimes useful to add inactive
selections which may become active as the applica-
tion state changes. If the add operation is suc-
cessful then the index number of the selection just
added will be returned. If it fails _X_M__F_A_I_L_U_R_E will
be returned. Further selections may be added at a
later time but remember when this routine is used to
add selections they are always added to the bottom
of a pane!

Printed 1/10/87 29 January 1986 5

XMENU(3X) UNIX Programmer's Manual XMENU(3X)

XMenuInsertPane
This routine allows the application to insert menu
panes into a menu in random order. If the index
number of the pane being inserted matches the index
number of a pane that already exists, then the
existing pane is displaced backward (its index
number and the index numbers of all following planes
increased by one) in the menu and the new pane
inserted in its place. Panes may be inserted into
any menu provided that the index number of the pane
being inserted is no more than one greater than the
index number of the last pane in the menu. For
example, if a menu contains 4 panes with index
numbers 0 through 3 then it is possible to insert a
new pane with an index number from 0 through 4
inclusive. It is possible to use _X_M_e_n_u_I_n_s_e_r_t_P_a_n_e in
place of _X_M_e_n_u_A_d_d_P_a_n_e but in situations where panes
are simply being added to a menu one after another
then the use of the simpler and more efficient
_X_M_e_n_u_A_d_d_P_a_n_e routine is encouraged. _X_M_e_n_u_I_n_s_e_r_t_P_a_n_e
takes the following arguments: The menu into which
the pane is being inserted; the index number of the
new pane; a null-terminated string that will be the
label for the new pane; and an int that designates
whether or not the pane will to be considered active
for selection. It is sometimes useful to add inac-
tive panes to indicate a currently unavailable but
planned set of selections. If the insert operation
is successful the index number of the pane just
inserted will be returned. If it fails _X_M__F_A_I_L_U_R_E
will be returned.

XMenuInsertSelection
This routine allows the application to insert selec-
tions into a menu pane in random order. If the
index number of the selection being inserted matches
the index number of a selection that already exists
in the specified pane, then the existing selection
is displaced downward (its index number and the
index numbers of all following selections increased
by one) in the pane and the new selection inserted
in its place. Selections may be inserted into any
pane provided that the index number of the selection
being inserted is no more than one greater than the
index number of the last selection in the pane. For
example, if a pane contains 4 selections numbered 0
through 3 then it is possible to insert a new selec-
tion with an index number from 0 through 4
inclusive. It is possible to use _X_M_e_n_u_I_n_s_e_r_t_S_e_l_e_c_-
_t_i_o_n in place of _X_M_e_n_u_A_d_d_S_e_l_e_c_t_i_o_n but in situations
where selections are simply being added to a pane
one after another then the use of the simpler and

Printed 1/10/87 29 January 1986 6

XMENU(3X) UNIX Programmer's Manual XMENU(3X)

more efficient _X_M_e_n_u_A_d_d_S_e_l_e_c_t_i_o_n routine is
encouraged. _X_M_e_n_u_I_n_s_e_r_t_S_e_l_e_c_t_i_o_n takes the follow-
ing arguments: the menu containing the pane into
which the selection is being inserted; the index
number of the pane to which the selection is being
inserted; the desired index number of the new selec-
tion; a null-terminated string that will be the
label for the new selection; A (char *) data value
that will be returned by _X_M_e_n_u_A_c_t_i_v_a_t_e whenever the
new selection is selected by a user; and an int that
designates whether or not the selection will be con-
sidered active for selection. It is sometimes use-
ful to insert inactive selections which may become
active as the application state changes. If the
insert operation is successful the index number of
the selection just inserted will be returned. If it
fails _X_M__F_A_I_L_U_R_E will be returned.

XMenuFindPane
This routine allows the application to find the
index number of a pane whose label matches a given
NULL terminated string. _X_M_e_n_u_F_i_n_d_P_a_n_e takes the
following arguments: the menu containing the pane
whose index number is being searched for; and a null
terminated string to be searched for. If the find
operation is successful then the index number of the
first pane whose label matches the given string will
be returned. If it fails _X_M__F_A_I_L_U_R_E will be
returned.

XMenuFindSelection
This routine allows the application to find the
index number of a selection whose label matches a
given NULL terminated string. _X_M_e_n_u_F_i_n_d_S_e_l_e_c_t_i_o_n
takes the following arguments: the menu containing
the pane which contains the selection being searched
for; the index number of the pane which contains the
selection being searched for; and a null terminated
string to be searched for. If the find operation is
successful then the index number of the first selec-
tion whose label matched the given string will be
returned. If is fails _X_M__F_A_I_L_U_R_E will be returned.

XMenuChangePane
This routine allows the application to change a
pane's label on the fly. This is useful for situa-
tions where a state change in the application must
be reflected in the menu. _X_M_e_n_u_C_h_a_n_g_e_P_a_n_e takes the
following arguments: the menu containing the pane
whose label is being changed; the index number of
that pane in the specified menu; and a null-
terminated string that will be the used as the new

Printed 1/10/87 29 January 1986 7

XMENU(3X) UNIX Programmer's Manual XMENU(3X)

pane label. If the change operation is successful
the index number of the pane just changed will be
returned. If it fails _X_M__F_A_I_L_U_R_E will be returned.
_X_M_e_n_u_C_h_a_n_g_e_P_a_n_e may be called any time after the
pane being changed has been added / inserted into
the specified menu.

XMenuChangeSelection
This routine allows the application to change a
selection's data and label on the fly. This is use-
ful for situations where a state change in the
application must be reflected in the menu. _X_M_e_n_u_-
_C_h_a_n_g_e_S_e_l_e_c_t_i_o_n takes the following arguments: the
menu containing the pane that contains the selection
to be changed; the index number of that pane in the
menu; the index number of the selection to be
changed; a (char *) new data value for the selec-
tion; an int that indicates whether or not to actu-
ally store the new data value (in case only the
label is being changed); Aanull-terminated string
that will be the used as the new selection label;
and an int that indicates whether or not to actually
store the new label (incase only the data value is
being changed). If the change operation is success-
ful the index number of the selection just changed
will be returned. If it fails _X_M__F_A_I_L_U_R_E will be
returned. _X_M_e_n_u_C_h_a_n_g_e_S_e_l_e_c_t_i_o_n may be called any-
time after the pane selection being changed has been
added to the specified pane and menu.

XMenuSetPane
_X_M_e_n_u_S_e_t_P_a_n_e allows the application to make an
active pane inactive or an inactive pane active.
This provides the application with the ability to
restrict the usage of certain panes to times when
they may or may not have a valid purpose. In addi-
tion this allows the application to activate and
utilize dummy panes that were added at menu creation
time as place holders for future selections.
_X_M_e_n_u_S_e_t_P_a_n_e takes the following arguments: the menu
containing the pane to be activated or deactivated;
the index number of that pane in the specified menu;
and an int that designates whether or not the pane
is to be considered active for selection. If the
set operation is successful the index number of the
pane just set will be returned. If it fails
_X_M__F_A_I_L_U_R_E will be returned. _X_M_e_n_u_S_e_t_P_a_n_e may be
called anytime after the pane being set has been
added / inserted into the specified menu.

XMenuSetSelection
_X_M_e_n_u_S_e_t_S_e_l_e_c_t_i_o_n allows the application to make an

Printed 1/10/87 29 January 1986 8

XMENU(3X) UNIX Programmer's Manual XMENU(3X)

active selection inactive or an inactive selection
active. This provides the application with the
ability to restrict the usage of certain selections
to times when they may or may not have a valid pur-
pose. In addition this allows the application to
activate and utilize selections that were added at
menu creation time with a future purpose in mind.
_X_M_e_n_u_S_e_t_S_e_l_e_c_t_i_o_n takes the following arguments: the
menu containing the pane that contains the selection
to be activated or deactivated; the index number of
that pane in the menu; the index number of the
selection to be activated / deactivated; and an int
that designates whether or not to make the specified
selection active. If the set operation is success-
ful the index number of the selection just set will
be returned. If it fails _X_M__F_A_I_L_U_R_E will be
returned. _X_M_e_n_u_S_e_t_S_e_l_e_c_t_i_o_n may be called anytime
after the pane selection being set has been added to
the specified pane and menu.

XMenuDeletePane
This routine allows the application to delete panes
when they will no longer be needed. _X_M_e_n_u_D_e_l_e_t_e_P_a_n_e
takes the following arguments: the menu containing
the pane to be deleted; and the index number of that
pane in the specified menu.

XMenuDeleteSelection
This routine allows the application to delete selec-
tions when they will no longer be needed. _X_M_e_n_u_-
_D_e_l_e_t_e_S_e_l_e_c_t_i_o_n takes the following arguments: the
menu containing the pane which contains the selec-
tion to be deleted; the index number of the pane
containing the selection to be deleted; and the
index number of the selection to be deleted in that
pane.

XMenuRecompute
After the initial menu configuration has been con-
structed (in fact, anytime that the menu configura-
tion, a pane label or selection label is altered),
the menu dependencies need to be recomputed. _X_M_e_n_u
will do this automatically if needed when _X_M_e_n_u_L_o_-
_c_a_t_e or _X_M_e_n_u_A_c_t_i_v_a_t_e is called. In the interest of
efficiency it is suggested that the application call
_X_M_e_n_u_R_e_c_o_m_p_u_t_e prior to any calls to _X_M_e_n_u_L_o_c_a_t_e or
_X_M_e_n_u_A_c_t_i_v_a_t_e. This need only be done if
_X_M_e_n_u_A_d_d_P_a_n_e, _X_M_e_n_u_A_d_d_S_e_l_e_c_t_i_o_n, _X_M_e_n_u_I_n_s_e_r_t_P_a_n_e,
_X_M_e_n_u_I_n_s_e_r_t_S_e_l_e_c_t_i_o_n, _X_M_e_n_u_C_h_a_n_g_e_P_a_n_e, _X_M_e_n_u_-
_C_h_a_n_g_e_S_e_l_e_c_t_i_o_n, _X_M_e_n_u_D_e_l_e_t_e_P_a_n_e, or _X_M_e_n_u_-
_D_e_l_e_t_e_S_e_l_e_c_t_i_o_n have been called since the last call
to _X_M_e_n_u_R_e_c_o_m_p_u_t_e or _X_M_e_n_u_A_c_t_i_v_a_t_e. If

Printed 1/10/87 29 January 1986 9

XMENU(3X) UNIX Programmer's Manual XMENU(3X)

_X_M_e_n_u_R_e_c_o_m_p_u_t_e is called before the first pane has
been added to the menu a error will result indicat-
ing that the menu has not been initialized. The
most efficient state is achieved if a sequence of
panes and selections are added or modified in order
and then a single call is immediately made to
_X_M_e_n_u_R_e_c_o_m_p_u_t_e. In this way all operations will
batched and all dependencies will be up to date by
the time the next _X_M_e_n_u_A_c_t_i_v_a_t_e call occurs. If the
recompute operation is successful _X_M__S_U_C_C_E_S_S will be
be returned. If it fails _X_M__F_A_I_L_U_R_E will be
returned.

XMenuLocate
This routine provides an application will all the
necessary data to properly locate and position a
menu with respect to the parent window. _X_M_e_n_u_L_o_c_a_t_e
takes the following arguments: the menu that is
being located; the index number of the desired
current pane; the index number of the desired
current selection; the X and Y coordinates of where
the application would like the center of the current
selection (in the current pane) to be; and four
return value pointers to int that will be filled in
by the routine. The four return value pointers are
set to the following values (respectively): the
upper left X and Y coordinates of the entire menu
(relative to the parent window); and the overall
width and height of the entire menu. If the
specified current selection is not a valid selection
index within the specified current pane (i.e., a
negative value or a value greater than the index of
the last selection in that pane) the return values
will be computed with the specified X and Y location
in the center of the flag of the specified current
pane. If the locate operation is successful
_X_M__S_U_C_C_E_S_S will be be returned. If it fails
_X_M__F_A_I_L_U_R_E will be returned.

XMenuSetAEQ
This routine allows the application to enable _A_s_y_n_c_h_r_o_-
_n_o_u_s _E_v_e_n_t _Q_u_e_u_e_i_n_g mode. _X_M_e_n_u_S_e_t_A_E_Q takes two argu-
ments: The menu to be set and an int that indicates
whether or not to place the menu in _A_s_y_n_c_h_r_o_n_o_u_s _E_v_e_n_t
_Q_u_e_u_e_i_n_g (_A_E_Q) mode. When in this mode foreign events
are queue for the duration of menu activation. For a
complete discussion of asynchronous event handling and
the other _A_s_y_n_c_h_r_o_n_o_u_s _E_v_e_n_t modes please see the
description of _X_M_e_n_u_A_c_t_i_v_a_t_e below.

XMenuSetEvHandler
_X_M_e_n_u_S_e_t_E_v_H_a_n_d_l_e_r allows the application to enable

Printed 1/10/87 29 January 1986 10

XMENU(3X) UNIX Programmer's Manual XMENU(3X)

_A_s_y_n_c_h_r_o_n_o_u_s _E_v_e_n_t _H_a_n_d_o_f_f (_A_E_H) mode.
_X_M_e_n_u_S_e_t_E_v_H_a_n_d_l_e_r takes two arguments: The menu to
be set and a pointer to a routine which returns int.
When in this mode foreign events are handed off to
the specified routine as they are received (provied
_A_E_Q mode is not enabled). Specifing a NULL event
handling routine will effectively disable _A_s_y_n_c_h_r_o_-
_n_o_u_s _E_v_e_n_t _H_a_n_d_o_f_f mode. For a complete discussion
of asynchronous event handling and the various _A_s_y_n_-
_c_h_r_o_n_o_u_s _E_v_e_n_t modes please see the description of
_X_M_e_n_u_A_c_t_i_v_a_t_e below. The format of the handler
should be as follows:
int handler(event)
XEvent *event;

XMenuSetFreeze
This routine allows the application to forcibly
override the _X_d_e_f_a_u_l_t_s setting of the `freeze'
parameter. If freeze mode is turned on the bits
under where the menu will appear are saved by _X_M_e_n_u
then the _X server is frozen and remains frozed while
the menu is activated. Immediately after the menu
is deactivated the bits under the menu are restored
to their original state and the server is unfrozen.
This routine is necessary for certain applications
that must guarantee that the screen contents are not
damaged by _X_M_e_n_u. _X_M_e_n_u_S_e_t_F_r_e_e_z_e takes two argu-
ments: The menu to be set and an int that indicates
whether or not to place the menu in freeze mode.

XMenuActivate
_X_M_e_n_u_A_c_t_i_v_a_t_e maps a given menu to the display and
activates the menu for user selection. Since _X
processes events in an asynchronous manner it is
suggested that the application synchronize the X
connection and and process all events in the _X_l_i_b
internal event queue before _X_M_e_n_u_A_c_t_i_v_a_t_e is called.
It is likely that _X_M_e_n_u_A_c_t_i_v_a_t_e will encounter
events not associated with _X_M_e_n_u (foreign events)
while it is executing. These events are handled by
_X_M_e_n_u in one of three ways:

1) _A_s_y_n_c_h_r_o_n_o_u_s _E_v_e_n_t _D_i_s_c_a_r_d (_A_E_D) mode.
This is the default mode and requires no action on the
part of the application. To reenable this mode the
asynchronous event handler should be set to NULL and
_A_E_Q mode should be disabled.
2) _A_s_y_n_c_h_r_o_n_o_u_s _E_v_e_n_t _Q_u_e_u_e_i_n_g (_A_E_Q) mode.
This mode is set by _X_M_e_n_u_S_e_t_A_E_Q). In this mode
all foreign events will be queued up until
_X_M_e_n_u_A_c_t_i_v_a_t_e terminates, at which time they will
be returned to the _X event queue. As long as

Printed 1/10/87 29 January 1986 11

XMENU(3X) UNIX Programmer's Manual XMENU(3X)

_A_E_Q mode is enabled any specified asynchronous event
handler (i.e., _A_E_H mode) is temporarily disabled.
Disableing _A_E_Q mode will return _X_M_e_n_u to its
previous method of asynchronous event handling.
3) _A_s_y_n_c_h_r_o_n_o_u_s _E_v_e_n_t _H_a_n_d_o_f_f (_A_E_H) mode.
In this mode the application has identified an
asynchronous event handler (via _X_M_e_n_u_S_e_t_E_V_H_a_n_d_l_e_r)
which will accept foreign events. Enableling _A_E_Q
mode temporarily disables any specified asynchronous
event handler. Setting the asynchronous event handler
to NULL will enable _A_E_D mode (provided _A_E_Q mode
is not enabled).

_X_M_e_n_u_A_c_t_i_v_a_t_e takes the following arguments: the menu that
is to be posted; the desired current pane and selection; the
X and Y menu position; the mouse button event mask; and a
pointer to a pointer to char (char **). The menu is posi-
tioned within the menu's parent window such that the speci-
fied X and Y location (relative to the parent window) is in
the center of the specified current selection in the current
pane. If the specified current selection is not a valid
selection index within the specified current pane (i.e., a
negative value or a value greater than the index of the last
selection in that pane) the menu will be mapped with the
specified X and Y location in the center of the flag of the
specified current pane. The mouse button event mask pro-
vided by the application should be suitable for an _X_G_r_a_b_-
_M_o_u_s_e operation. It provides the application with a way to
indicate which mouse events will be used to identify a
selection request. Every time _X_M_e_n_u_A_c_t_i_v_a_t_e returns, the
pane and selection indices are left at their last known
values (i.e., the last current pane and selection indices).
The following are the defined return states for this rou-
tine:

1) If the selection that is current at the time a
selection request is made is active then the data
pointer will be set to the data associated with that
particular selection and _X_M__S_U_C_C_E_S_S is returned.
2) If the selection that is current at the time a
selection request is made is not active then the data
pointer will be left untouched and _X_M__I_A__S_E_L_E_C_T will
be returned.
3) If there is no selection current at the time a
selection request is made then the data pointer will
be left untouched and _X_M__N_O__S_E_L_E_C_T will be returned.
4) If at any time an error occurs the data pointer is
left untouched and _X_M__F_A_I_L_U_R_E is returned.

XMenuDestroy
When the application is no longer intending to use a
menu _X_M_e_n_u_D_e_s_t_r_o_y should be called. _X_M_e_n_u_D_e_s_t_r_o_y

Printed 1/10/87 29 January 1986 12

XMENU(3X) UNIX Programmer's Manual XMENU(3X)

frees all resources (both _X resources and system
resources) that are being held by the menu. _X_M_e_n_u_-
_D_e_s_t_r_o_y takes only one argument, the menu to be des-
troyed. WARNING! Using a menu after it has been
destroyed is to invite disaster!

XMenuError
When called _X_M_e_n_u_E_r_r_o_r will return a null-terminated
string that describes the current error state of the
_X_M_e_n_u library. The string returned is static in the
_X_M_e_n_u library and should not be modified or freed.
The error state is set every time an _X_M_e_n_u routine
returns a status condition. _X_M_e_n_u_E_r_r_o_r takes no
arguments.

X DEFAULTS
MenuFreeze
Determines whether or not to grab the _X server while
a menu is posted. One of: _o_n, _o_f_f. The default
value is _o_f_f.

MenuReverseVideo
Determines whether clock should be in normal mode
(white on black) or reverse video mode (black on
white). On color displays this value is ignored.
One of: _o_n, _o_f_f. The default value is _o_f_f.

MenuStyle
Determines the menu display style. One of:
_l_e_f_t__h_a_n_d, _r_i_g_h_t__h_a_n_d, _c_e_n_t_e_r. The default value is
_r_i_g_h_t__h_a_n_d.

MenuMode
Determines the menu selection high light mode. One
of: _b_o_x, _i_n_v_e_r_t. If _b_o_x mode is chosen then the
_S_e_l_e_c_t_i_o_n_B_o_r_d_e_r_W_i_d_t_h and _S_e_l_e_c_t_i_o_n_B_o_r_d_e_r_C_o_l_o_r param-
eters effect the box line width and color respec-
tively. If _i_n_v_e_r_t mode is chose then the _S_e_l_e_c_t_i_o_n_-
_F_o_r_e_g_r_o_u_n_d and _M_e_n_u_B_a_c_k_g_r_o_u_n_d colors are used for
the inversion. The default value is _i_n_v_e_r_t.

MenuMouse
Determines the color of the mouse cursor while it is
within the menu. On black and white displays this
value is ignored. Any valid _X color may be used.
The default value is _B_l_a_c_k.

MenuBackground
Determines the menu background color. On black and
white displays this value is ignored. Any valid _X
color may be used. The default value is _W_h_i_t_e.

Printed 1/10/87 29 January 1986 13

XMENU(3X) UNIX Programmer's Manual XMENU(3X)

MenuInactivePattern
Determines which of the five possible bitmap pat-
terns will be used to tile inactive panes. One of:
_d_i_m_p_l_e_1, _d_i_m_p_l_e_3, _g_r_a_y_1, _g_r_a_y_3, _c_r_o_s_s__w_e_a_v_e. The
default value is _g_r_a_y_3.

PaneStyle
Determines the display style of all menu panes. One
of: _f_l_u_s_h__l_e_f_t, _f_l_u_s_h__r_i_g_h_t, _c_e_n_t_e_r. The default
value is _c_e_n_t_e_r.

PaneFont
Determines the font used for the label (heading
text) of each pane. Any valid _X font may be used.
The default value is _8_x_1_3.

PaneForeground
Determines the pane foreground color. This is the
color used for the label (heading text) in each
pane. On black and white displays this value is
ignored. Any valid _X color may be used. The
default value is _B_l_a_c_k.

PaneBorder
Determines the color of all menu pane borders. On
black and white displays this value is ignored. Any
valid _X color may be used. The default value is
_B_l_a_c_k.

PaneBorderWidth
Determines the width (in pixels) of all menu pane
borders. Any integer greater than or equal to 0 may
be used. The default value is 2.

PaneSpread
Determines the horizontal spread of menu panes. Any
double greater than or equal to 0.0 may be used. A
value of 1.0 specifies a one to one ratio between
horizontal spread and vertical spread. A value less
than 1.0 will compress the menu panes inward and a
value greater than 1.0 will expand them outward.
The default value is 1.0.

SelectionStyle
Determines the display style of all menu selections.
One of: _f_l_u_s_h__l_e_f_t, _f_l_u_s_h__r_i_g_h_t, _c_e_n_t_e_r. The default
value is _f_l_u_s_h__l_e_f_t.

SelectionFont
Determines the font used for the text in each selec-
tion. Any valid _X font may be used. The default
value is _6_x_1_0.

Printed 1/10/87 29 January 1986 14

XMENU(3X) UNIX Programmer's Manual XMENU(3X)

SelectionForeground
Determines the selection foreground color. This is
the color used for the text in each selection. On
black and white displays this value is ignored. Any
valid _X color may be used. On black and white
displays this value is ignored. The default value
is _b_l_a_c_k.

SelectionBorder
Determines the color of all menu selection borders.
On black and white displays this value is ignored.
Any valid _X color may be used. The default value is
_b_l_a_c_k.

SelectionBorderWidth
Determines the width (in pixels) of all menu selec-
tion borders. Any integer greater than or equal to
0 may be used. The default value is 1.

SelectionSpread
Determines the inter-selection spread. Any double
greater than or equal to 0.0 may be used. A value
of 1.0 specifies that 1.0 times the height of the
current selection font will be used for padding The
default value is 0.25.

DIAGNOSTICS
Since _X_M_e_n_u uses the _X_l_i_b library, the _X_I_O_E_r_r_o_r and _X_E_r_r_o_r
_X_l_i_b routines may be set by the application to change how
asynchronous error reporting occurs.

Synchronous error reporting is primarily accomplished by
examining the return values of routines and using the
_X_M_e_n_u_E_r_r_o_r routine. Although its use is discouraged, syn-
chronous error reporting may also be accomplished by having
the application directly examine the value of the __X_M_E_r_r_o_r_-
_C_o_d_e global variable. __X_M_E_r_r_o_r_C_o_d_e is set every time an
_X_M_e_n_u routine returns a status condition. The following
sequence of symbols is provided in _X_M_e_n_u._h and may be used
to index the null-terminated description strings in the glo-
bal error string array __X_M_E_r_r_o_r_L_i_s_t.

_X_M_E__C_O_D_E__C_O_U_N_T Total number of entries in __X_M_E_r_r_o_r_L_i_s_t (17).

_X_M_E__N_O__E_R_R_O_R -> ``No error''
_X_M_E__N_O_T__I_N_I_T -> ``Menu not initialized''
_X_M_E__A_R_G__B_O_U_N_D_S -> ``Argument out of bounds''
_X_M_E__P__N_O_T__F_O_U_N_D -> ``Pane not found''
_X_M_E__S__N_O_T__F_O_U_N_D -> ``Selection not found''
_X_M_E__S_T_Y_L_E__P_A_R_A_M -> ``Invalid menu style parameter''
_X_M_E__G_R_A_B__M_O_U_S_E -> ``Unable to grab mouse''
_X_M_E__I_N_T_E_R_P__L_O_C -> ``Unable to interpret locator''

Printed 1/10/87 29 January 1986 15

XMENU(3X) UNIX Programmer's Manual XMENU(3X)

_X_M_E__C_A_L_L_O_C -> ``Unable to calloc memory''
_X_M_E__C_R_E_A_T_E__A_S_S_O_C -> ``Unable to create XAssocTable''
_X_M_E__S_T_O_R_E__B_I_T_M_A_P -> ``Unable to store bitmap''
_X_M_E__M_A_K_E__T_I_L_E_S -> ``Unable to make tile pixmaps''
_X_M_E__M_A_K_E__P_I_X_M_A_P -> ``Unable to make pixmap''
_X_M_E__C_R_E_A_T_E__C_U_R_S_O_R -> ``Unable to create cursor''
_X_M_E__O_P_E_N__F_O_N_T -> ``Unable to open font''
_X_M_E__C_R_E_A_T_E__W_I_N_D_O_W -> ``Unable to create windows''
_X_M_E__C_R_E_A_T_E__T_R_A_N_S_P -> ``Unable to create transparencies''

FILES
/usr/include/X/XMenu.h, /usr/lib/libXMenu.a,
/usr/include/X/Xlib.h, /usr/lib/libX.a