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 SEE ALSO Xlib(3x), X(1), X(8c) AUTHOR Copyright 1985, 1986, Massachusetts Institute of Technology. See _X(_1) for a complete copyright notice. Tony Della Fera (MIT Project Athena, DEC) BUGS 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 _X protocol. Printed 1/10/87 29 January 1986 16