XRPANEL(3X)

NAME
XrPanel - The Xrlib Panel Manager.

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

xrPanel *
XrPanel (panelInstance, message, data)
xrPanel * panelInstance;
INT32 message;
INT8 * data;

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

STRUCTURES
The following structures are used to communicate with the panel manager.

The xrPanelInfo Structure
    This structure is used to create a panel in conjunction with MSG_NEW.
    typedef struct {
            POINT             panelOrigin;
            SIZE              panelSize;
            Window            relativeTo;
            Window            childOf;
            xrPanelContext  * panelContext;
            xrPanelField    * fieldList;
            INT32             numFields;
            INT32             panelId;
    } xrPanelInfo;
    typedef struct {
            xrEditor     * (* editorFunct) ();
            INT8         * editorData;
            xrEditor     * editorInstance;
    }xrPanelField;

The panel context tructure
    This structure contains the information used by the panel manager to deal with a particular panel.
    typedef struct {
            Pixmap          winBackground;
            Pixmap          winForeground;
            INT16           borderWidth;
            INT32           foregroundColor;
            INT32           backgroundColor;
            FontInfo      * fontInfo;
            Cursor          cursor;
            INT32           showFlag;
            xrEditor     *  currentEditor;
            INT32           timer;
            INT32           (* initFunct)();
    }xrPanelContext;
    A description of each member of these structures is given in the ``Dialogs'' chapter of the programmer's manual.

MESSAGES
The following messages allow the programmer to give the panel manager directives.

MSG_NEW
    MSG_NEW creates the panel structure discussed earlier. The panelInstance parameter may be set to NULL, as it is not used. The data parameter should be set to a structure of type xrPanelInfo. MSG_NEW returns a pointer to a panel, failure is indicated by a return value of NULL.

MSG_FREE
    MSG_FREE destroys a panel and frees the associated memory. data may be set to NULL for this command.

MSG_SIZE
    MSG_SIZE returns the size of a panel given a panelInfo structure. data should point to a panelInfo structure. The size is returned in the panelSize member of the panelInfo structure.

MSG_EDIT
    MSG_EDIT causes the panel manager to begin looking for input to a particular panel. MSG_EDIT should be sent to the panel manager when an application expects input from a panel. data should point to an xrEvent structure.

MSG_CURRENTEDITOR
    MSG_CURRENTEDITOR instructs the panel manager to invoke a specific editor when MSG_EDIT is received. This allows a panel to have an active field (such as a TextEdit field) without a input from the user. data points to an xrEditor instance.

MSG_MOVE
    MSG_MOVE allows a panel to be moved about the display. data is a pointer to a point structure.

MSG_RESIZE
    MSG_RESIZE allows a panel to be resized by the application. data is a pointer to a rectangle structure. The panel will be moved to an absolute point on the display and its window will change to the given size.

MSG_HIDE
    MSG_HIDE hides a panel. data is not used and may be set to NULL.

MSG_SHOW
    MSG_SHOW shows a panel. data is not used and may be set to NULL. A panel will be shown automatically upon creation if the showFlag field of the panelInfo structure is set to TRUE.

MSG_REDRAW
    MSG_REDRAW causes the editors of a panel to be redrawn. data is not used and may be set to NULL.

MSG_GETPANELCONTEXT
    MSG_GETPANELCONTEXT fills out an xrPanelContext structure with the panel defaults. data should point to an xrPanelContext structure.

MSG_NEWSUBPANEL
    MSG_NEWSUBPANEL creates a sub-panel. panelInstance should be the pointer to the parent panel, and data is a xrPanelInfo structure.

MSG_FREESUBPANEL
    MSG_FREESUBPANEL destroys a sub-panel and its associated memory.

MSG_SHOWSUBPANEL
    MSG_SHOWSUBPANEL causes the editors of a sub-panel to be added to its main panel. data should point to an xrEditorGroup structure indicating which sub-panel is to be activated.

MSG_HIDESUBPANEL
    MSG_HIDESUBPANEL removes the editors from its associated main panel. data should point to an xrEditorGroup structure indicating which sub-panel is to be deactivated.

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

ERROR CONDITIONS
Messages to the panel manager 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_SIZE

    data is set to NULL [XrINVALIDPTR].

    A call to 'X' failed [XrXCALLFAILED].

MSG_FREE

    panelInstance is set to NULL [XrINVALIDPTR].

    A call to 'X' failed [XrXCALLFAILED].

MSG_EDIT

    data is set to NULL [XrINVALIDPTR].

    Panel is not showing [XrINVALIDEVENT]

    A call to 'X' failed [XrXCALLFAILED].

MSG_CURRENTEDITOR

    data is set to NULL [XrINVALIDPTR].

MSG_MOVE

    data is set to NULL [XrINVALIDPTR].

    A call to 'X' failed [XrXCALLFAILED].

MSG_RESIZE

    data is set to NULL [XrINVALIDPTR].

    A call to 'X' failed [XrXCALLFAILED].

MSG_HIDE

    A call to 'X' failed [XrXCALLFAILED].

MSG_SHOW

    A call to 'X' failed [XrXCALLFAILED].

MSG_REDRAW

    A call to 'X' failed [XrXCALLFAILED].

MSG_GETPANELCONTEXT

    data is set to NULL [XrINVALIDPTR].

    A call to 'X' failed [XrXCALLFAILED].

MSG_NEWSUBPANEL

    data is set to NULL [XrINVALIDPTR].

    A call to 'X' failed [XrXCALLFAILED].

    Memory cannot be allocated [XrOUTOFMEM]

MSG_FREESUBPANEL

    data is set to NULL [XrINVALIDPTR].

    A call to 'X' failed [XrXCALLFAILED].

MSG_SHOWSUBPANEL

    data is set to NULL [XrINVALIDPTR].

    A call to 'X' failed [XrXCALLFAILED].

MSG_HIDESUBPANEL

    data is set to NULL [XrINVALIDPTR].

    A call to 'X' failed [XrXCALLFAILED].