XRMENU(3X)

NAME
XrMenu - the Xrlib Menu Manager.

SYNOPSIS
#include <X/Xlib.h>
#include <Xr/Xrlib.h>

xrMenu *
XrMenu (menuInstance, message, data)
xrMenu * menuInstance;
INT32 message;
INT8 * data;

DESCRIPTION
XrMenu is the Xrlib menu manager. This man page gives a brief summary of the menu manager structures, messages, and item language. For a more complete description, refer to the ``Dialogs'' chapter in the programmer's manual.

STRUCTURES
The following structures are used to communicate with the menu manager. The menu structures shown below are described in the programmer's manual.
   typedef struct
   {
      INT8            * menuTitle;
      INT8           ** menuItems;
      INT32             numItems;
      xrPanelContext  * menuContext;
      INT16             menuId;
      INT32             menuStyle;
   } xrMenuInfo;
   typedef struct _xrMenuIndex
   {
      struct _xrMenu    * menuInstance;
      INT32               itemIndex;
      INT32               itemData;
   } xrMenuIndex;

MESSAGES
The following messages allow the programmer to communicate with the Xrlib menu manager.

MSG_NEW
    MSG_NEW creates a menu structure. The menuInstance parameter should be set to NULL, as it is not used. The data parameter is a pointer to a menuInfo structure.

MSG_FREE
    MSG_FREE destroys a menu, its associated menu editor, and frees all resources allocated by the menu manager. menuInstance is a pointer to the menu to be freed. data should be set to NULL. Care should be taken not to refer to a menu after it has been freed.

MSG_EDIT
    MSG_EDIT posts the currently active menu for a given window. This command will be made transparently to the application by the input model most of the time, but may be called by you if necesssary.

MSG_ACTIVATEMENU
    MSG_ACTIVATEMENU makes the given menu the current menu for the given window. A menu may be current for several windows at the same time. When the input model gets a post menu input from the user, it will post the current menu for the window the input came from. data is a window id.

MSG_DEACTIVATEMENU
    MSG_DEACTIVATEMENU makes the given menu inactive for the given window. data is a window id.

MSG_ADDSUBMENU
    MSG_ADDSUBMENU allows you to add one menu to another as a sub-menu. The sub-menu is created in the same way as the parent menu, this message simply allows you to link menus into a tree structure. menuInstance is a pointer to the sub-menu. data points to an xrMenuIndex structure that specifies the location in the menu tree. Set the menuInstance pointer to the parent menu instance pointer. Set the itemIndex portion of the structure to the item in question, and the itemData member to NULL.

MSG_REMOVESUBMENU
    MSG_REMOVESUBMENU removes a link between two menus. Neither of the menus are destroyed, there is simply not a path between them any longer. menuInstance is a pointer to the sub-menu. data points to an xrMenuIndex structure that specifies the location in the menu tree. Set the menuInstance pointer to the parent menu instance pointer. Set the itemIndex portion of the structure to the item in question, and the itemData member to NULL.

MSG_ACTIVATEITEM
    MSG_ACTIVATEITEM allows you to make an item in a menu selctable. Unselectable items are shown greyed and are not selectable by the user. data is an integer index to the item to be made active. menuInstance is the menu instance in question.

MSG_DEACTIVATEITEM
    MSG_DEACTIVATEITEM allows you to make an item in a menu unselectable. Unselectable items are shown greyed and are not selectable by the user. data is an integer index to the item to be made active. menuInstance is the menu instance in question.

MSG_SETITEMFUNCTION
    MSG_SETITEMFUNCTION sets a function to be executed when an item is selected by the user. data points to an xrMenuIndex structure. The menuInstance member of this structure points to the menu in question. The itemIndex member determines which item is associated with the function, and the itemData member contains the pointer to the function.

MSG_SETITEMEVENT
    MSG_SETITEMEVENT sets an event to be returned when a menu item is selected by the user. data points to an xrMenuIndex structure. The menuInstance member of this structure points to the menu in question. The itemIndex member determines which item is associated with the event, and the itemData member contains the pointer to the event created by the programmer.

ITEM LANGUAGE
The XRMENU item language allows the programmer to send special commands on a per-item basis to the Xrlib menu manager. These commands are described in the following table.

Command | Action
\DA | Item is disabled
\KEc | Item has keyboard equivalent c
\- | Single line (unselectable)
\= | double line (unselectable)

RETURN VALUE
Unless otherwise specified, XrMenu() returns menuInstance if it is successful and NULL on failure.

ERROR CONDITIONS
Messages to XrMenu will fail, set the xrErrno global and return a NULL value, under the following conditions:

MSG_NEW

    data is set to NULL [XrINVALIDPTR].

    A call to 'X' failed [XrXCALLFAILED].

    Memory cannot be allocated [XrOUTOFMEM].

MSG_FREE

    A call to 'X' failed [XrXCALLFAILED].

MSG_EDIT

    data is set to NULL [XrINVALIDPTR].

    A call to 'X' failed [XrXCALLFAILED].

MSG_ACTIVATEMENU

    data is set to NULL [XrINVALIDPTR].

    A call to 'X' failed [XrXCALLFAILED].

MSG_DEACTIVATEMENU

    data is set to NULL [XrINVALIDPTR].

    A call to 'X' failed [XrXCALLFAILED].

MSG_ADDSUBMENU

    data is set to NULL [XrINVALIDPTR].

    A call to 'X' failed [XrXCALLFAILED].

    Memory cannot be allocated [XrOUTOFMEM].

MSG_REMOVESUBMENU

    data is set to NULL [XrINVALIDPTR].

    A call to 'X' failed [XrXCALLFAILED].

MSG_ACTIVATEITEM

    data is set to NULL [XrINVALIDPTR].

    A call to 'X' failed [XrXCALLFAILED].

MSG_DEACTIVATEITEM

    data is set to NULL [XrINVALIDPTR].

    A call to 'X' failed [XrXCALLFAILED].

MSG_SETITEMFUNCTION

    data is set to NULL [XrINVALIDPTR].

    A call to 'X' failed [XrXCALLFAILED].

MSG_SETITEMEVENT

    data is set to NULL [XrINVALIDPTR].

    A call to 'X' failed [XrXCALLFAILED].