.TH XMENU 3X "29 January 1986" "X Version 10"
XMenu - X Deck of cards Menu System
.B XMenu *XMenuCreate(parent, xdef_env)
.B int XMenuAddPane(menu, label, active)
.B int XMenuAddSelection(menu, pane, data, label, active)
.B int XMenuInsertPane(menu, pane, label, active)
.B int XMenuInsertSelection(menu, pane,selection, data, label, active)
.B int XMenuFindPane(menu, label)
.B int XMenuFindSelection(menu, pane, label)
.B int XMenuChangePane(menu, pane, label)
.B int XMenuChangeSelection(menu, pane,selection, data,d_sw, label,l_sw)
.B int XMenuSetPane(menu, pane, active)
.B int XMenuSetSelection(menu, pane, selection, active)
.B int XMenuDeletePane(menu, pane)
.B int XMenuDeleteSelection(menu, pane, selection)
.B int XMenuRecompute(menu)
.B XMenuEventHandler(handler)
.B int XMenuLocate(menu, pane,selection, x,y, ulx,uly, width,height)
.B XMenuSetFreeze(menu, freeze)
.B int XMenuActivate(menu, pane,selection, x,y, event_mask, data)
.B int *pane, *selection;
Window System Utility Package that implements a `deck of cards'
is intended for use in conjunction with
the \fIC Language X Window System Interface Library.\fP
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 patterned inactive background and no selections on the
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
When the mouse cursor enters an active selection in a pane that has been
activated then that selection 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
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 selection mouse event is received by
one of several results will occur, depending upon the state of the menu system
at 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 application 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
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', `Forward', `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.
system is maintained (menus, panes and selections) via routines in
library. The library contains the following routines:
In order for a process to create a menu, it is necessary for that process
to have opened a connection to an
display server and have a window in hand that will be designated as the
parent window of the menu being created (remember that
is designed such that child windows of a parent window are clipped to the
borders of the parent). Typically the
) is used for this purpose. When the connection is open and a parent
window chosen, the application calls
passing it the parent window and a null-terminated string.
The string designates the default environment name that will be used
by XMenu to read the users
variables. Typically the application 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
setable parameters are set via the
mechanism. If any parameters do not have
values then they default to preset
parameters are listed below along with their preset internal values.
If the create operation is successful
object. If it fails NULL will be returned.
Once a menu has been created the application may then begin
adding panes and subsequently selections. Panes are added by calling
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.
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 inactive 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 XM_FAILURE 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!
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
adds additional selections to a pane in call order. That is, selections will
appear in the pane with the first selection added being at the top of the pane
and the last selection added being at the bottom of the pane.
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
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
application state changes. If the add operation is successful then the
index number of the selection just added will be returned. If it fails
XM_FAILURE 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
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
but in situations where panes are simply being added to a menu one after
another then the use of the simpler and more efficient
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
inactive 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 XM_FAILURE will be returned.
This routine allows the application to insert selections 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 selection with an index number from 0 through 4
inclusive. It is possible to use
but in situations where selections are simply being added to a pane one after
another then the use of the simpler and more efficient
takes the following 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 selection;
a null-terminated string that will be the label for the new selection; A
(char *) data value that will be returned by
whenever the new selection is selected by a user; and an int that designates
whether or not the selection will be considered active for selection. It is
sometimes useful 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 XM_FAILURE
This routine allows the application to find the index number of a pane whose
label matches a given NULL terminated string.
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 XM_FAILURE
This routine allows the application to find the index number of a selection
whose label matches a given NULL terminated string.
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
If the find operation is successful then the index number of the first
selection whose label matched the given string will be returned. If is fails
XM_FAILURE will be returned.
This routine allows the application to change a pane's label on the fly. This
is useful for situations where a state change in the application must be
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 pane label. If the
change operation is successful the index number of the pane just changed will
be returned. If it fails XM_FAILURE will be returned.
may be called any time after the pane being changed has been added / inserted
This routine allows the application to change a selection's data and label on
the fly. This is useful for situations where a state change in the application
must be reflected in the menu.
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
selection; an int that indicates whether or not to actually 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 successful the index number of
the selection just changed will be returned. If it fails XM_FAILURE will be
may be called anytime after the pane selection being changed has been added to
the specified pane and menu.
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
addition this allows the application to activate and utilize dummy panes that
were added at menu creation time as place holders for future selections.
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 XM_FAILURE will be returned.
may be called anytime after the pane being set has been added / inserted into
allows the application to make an 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
purpose. In addition this allows the application to activate and utilize
selections that were added at menu creation time with a future purpose in mind.
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 successful the index number of the selection just set will
be returned. If it fails XM_FAILURE will be returned.
may be called anytime after the pane selection being set has been added to the
This routine allows the application to delete panes when they will no longer
takes the following arguments: the menu containing the pane to be deleted;
and the index number of that pane in the specified menu.
This routine allows the application to delete selections when they will no
takes the following arguments: the menu containing the pane which contains the
selection 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
After the initial menu configuration has been constructed (in fact, anytime
that the menu configuration, a pane label or selection label is altered), the
menu dependencies need to be recomputed.
will do this automatically if needed when
is called. In the interest of efficiency it is suggested that the application
This need only be done if
have been called since the last call to
is called before the first pane has been added to the menu a error will result
indicating 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
In this way all operations will batched and all dependencies will be up to date
call occurs. If the recompute operation is successful XM_SUCCESS will be
be returned. If it fails XM_FAILURE will be returned.
event queue with the application, it is possible that
events selected by the application will arrive and be queued while a menu is
posted. Before a menu is posted, it is up to the application to decide what
will happen to events that do occur while the menu is posted.
allows the application to specify an asynchronous event handling routine.
takes only one argument which is a pointer to a routine which returns int.
This routine will be called by
if it encounters an event that it does not recognize. The format of the
handler should be as follows:
If no action is taken by the application (i.e., no event handler is specified)
will discard any events that they do not recognize.
This routine provides an application will all the necessary data to properly
locate and position a menu with respect to the parent window.
takes the following arguments: the menu that is being located; the index number
of the current pane; the index number of the 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 locate operation is successful XM_SUCCESS
will be be returned. If it fails XM_FAILURE will be returned.
This routine allows the application to forcibly override the
setting of the `freeze' parameter. If freeze mode is turned on the
bits under where the menu will appear are saved by
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
takes two arguments: The menu to be set and an int that indicates whether or
not to place the menu in freeze mode.
.I XMenuActivate maps a given menu to the display and activates the menu for
is called it is suggested that the application synchronize the X connection and
and process all events in the
internal event queue. This guarantees that a minimum of asynchronous
call-backs to the applications event handler routine (or discards if no
application event handler is specified).
guarantees that no unprocessed events of its own will be left in the
event queue upon its return.
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 positioned
within the menu's parent window such that the specified X and Y location
(relative to the parent window) is in the center of the specified current
selection in the current pane. The mouse button event mask provided by the
application should be suitable for an
operation. It provides the application with a way to indicate which mouse
events will be used to identify a selection request. Every time
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 routine:
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 XM_SUCCESS 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 XM_IA_SELECT will
3) If there is no selection current at the time a
selection request is made then the data pointer will
be left untouched and XM_NO_SELECT will be returned.
4) If at any time an error occurs the data pointer is
left untouched and XM_FAILURE is returned.
When the application is no longer intending to use a menu
frees all resources (both
resources and system resources) that are being held by the menu.
takes only one argument, the menu to be destroyed. WARNING! Using a menu after
it has been destroyed is to invite disaster!
will return a null-terminated string that describes the current error state of
library. The string returned is static in the
library and should not be modified or freed. The error state is set every time
routine returns a status condition.
Determines whether or not to grab the
server while a menu is posted.
The default value is off.
Determines the menu display style.
One of: left_hand, right_hand, center.
The default value is right_hand.
Determines the menu selection high light mode.
If box mode is chosen then the SelectionBorderWidth and SelectionBorderColor
parameters effect the box line width and color respectively.
If invert mode is chose then the SelectionForeground and MenuBackground
colors are used for the inversion.
The default value is invert.
Determines the color of the mouse cursor while it is within
The default value is black.
Determines the menu background color.
The default value is white.
Determines which of the five possible bitmap patterns will be used to tile
One of: dimple1, dimple3, gray1, gray3, cross_weave.
The default value is gray3.
Determines the display style of all menu panes.
One of: flush_left, flush_right, center.
The default value is center.
Determines the font used for the label (heading text) of each pane.
The default value is 8x13.
Determines the pane foreground color.
This is the color used for the label (heading text) in each pane.
The default value is black.
Determines the color of all menu pane borders.
The default value is black.
Determines the width (in pixels) of all menu pane borders.
Any integer greater than or equal to 0 may be used.
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
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.
Determines the display style of all menu selections.
One of: flush_left, flush_right, center.
The default value is flush_left.
Determines the font used for the text in each selection.
Any valid X font may be used.
The default value is 6x10.
Determines the selection foreground color.
This is the color used for the text in each selection.
The default value is black.
Determines the color of all menu selection borders.
The default value is black.
Determines the width (in pixels) of all menu selection borders.
Any integer greater than or equal to 0 may be used.
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.
routines may be set by the application to change how asynchronous error
Synchronous error reporting is primarily accomplished by examining the return
values of routines and using the
routine. Although its use is discouraged, synchronous error reporting may also
be accomplished by having the application directly examine the value of the
routine returns a status condition. The following sequence of symbols is
and may be used to index the null-terminated description strings in the global
.ta \w'XME_CREATE_WINDOW 'u + .5i
XME_CODE_COUNT Total number of entries in \fI_XMErrorList\fP (17).
XME_NO_ERROR -> ``No error''
XME_NOT_INIT -> ``Menu not initialized''
XME_ARG_BOUNDS -> ``Argument out of bounds''
XME_P_NOT_FOUND -> ``Pane not found''
XME_S_NOT_FOUND -> ``Selection not found''
XME_STYLE_PARAM -> ``Invalid menu style parameter''
XME_GRAB_MOUSE -> ``Unable to grab mouse''
XME_INTERP_LOC -> ``Unable to interpret locator''
XME_CALLOC -> ``Unable to calloc memory''
XME_CREATE_ASSOC -> ``Unable to create XAssocTable''
XME_STORE_BITMAP -> ``Unable to store bitmap''
XME_MAKE_TILES -> ``Unable to make tile pixmaps''
XME_MAKE_PIXMAP -> ``Unable to make pixmap''
XME_CREATE_CURSOR -> ``Unable to create cursor''
XME_OPEN_FONT -> ``Unable to open font''
XME_CREATE_WINDOW -> ``Unable to create windows''
XME_CREATE_TRANSP -> ``Unable to create transparencies''
/usr/include/X/XMenu.h, /usr/lib/libXMenu.a, /usr/include/X/Xlib.h,
Copyright 1985, 1986, Massachusetts Institute of Technology.
See \fIX(1)\fP for a complete copyright notice.
Tony Della Fera (MIT Project Athena, DEC)
There is a problem that necessitates an additional round trip time
when panes are activated and deactivated. In order for this to be fixed
efficiently, a change needs to be made to the