XRINPUT(3X)

NAME
XrInput - the input handling function.

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

XrInput (windowId, message, data)
Window windowId;
INT32 message;
INT8 * data;

DESCRIPTION
XrInput() handles the requests for input by an application from a window or windows and the setting of window and input attributes necessary to handle editors and panel managers.

Most of the messages will use the xrEvent structure which is defined as follows.
typedef struct
{
   UINT32 type;
   INT32 source;
   INT16 inputCode;
   INT8 inputType;
   INT8 value1;
   INT16 value2;
   INT16 value3;
   POINT valuePt;
   INT32 valuePtr;
} xrEvent;

When input occurs from a window, the type field of the structure will be set to one of X's input types or to the define XrXRAY for Xrlib input types. Refer to the X documentation for a complete description of X input. An application can only generate Xrlib input, and thus use editors, panels, and menus, if the window is registered with XrInput. The is accomplished through the MSG_ADDWINDOW message listed below. If the type field of the xrEvent structure is set to XrXRAY, the source field will contain the id of the window in which the input occurred, and the inputType field will be set to one of the defines listed in the table below.

Type | Meaning
XrEDITOR | Input from an editor
XrPANEL | Input from a panel
XrMENU | Input from a menu
XrMESSAGEBOX | Input from a message box
XrFILE | Input from a file descriptor

An application can also gather input from any file descriptor that has been opened. Examples of this would be input from a pty or socket. If this type of input is pending, the source field in the xrEvent structure will be set to the file descriptor and the inputType field will be set to XrFILE. It is then up to the application to get the input from the file descriptor.

The messages which XrInput() provides are broken into several functional groupings.

MSG_ADDWINDOW
    If an application wants to gather Xrlib type input or place editors within a window it has created, Xrlib needs to be told about the window. Issuing this message causes a window to be registered with XrInput(), which then sets up the other routines which need to know about the window. To register a window, windowId should be set to the id of the window to be registered and data needs to point to an xrWindowData structure which is defined as follows:
    typedef struct
    {
       RECTANGLE windowRect;
       Pixmap    foreTile;
       Pixmap    backTile;
    } xrWindowData;

MSG_REMOVEWINDOW
    When an application destroys a window, it should call XrInput() so that the window will be removed from XrInput()'s tables. For this message, windowId should be set to the id of the window to be removed and data is unused and can be set to NULL.

MSG_SETWINDOWDATA
    If an application changes the size or tiles of a window, XrInput() needs to be given the data to modify its tables. For this message, windowId should be set to the id of the window in which the data is to be set and data should be set to point to an xrWindowData structure which contains the needed information.

MSG_GETWINDOWDATA
    This messages returns the data for a window. For this call, windowId should be set to the id of the window in which the data is contained and data is a pointer to an xrWindowData structure. The members of this structure will be set to the data values for the window.

MSG_ADDWINDOWFUNCT
    Xrlib high-level manager functions have the ability to be called automatically upon a particular input or inputs. An example of this is the menu manager displaying a menu upon a menu event input. To accomplish this function, XrInput() maintains a set of information for each registered window. This message is the means by which a particular window gets the capabilities described above. For this message, data is a pointer to the following structure:
    typedef struct
    {
       INT8  processFlag;
       xrPFI (*funct)();
       INT32 instance;
       INT32 message;
       INT32 eventCount;
       xrWindowEvent * eventList;
    } xrWindowFunct;
    The funct field contains a pointer to the function that is to be invoked when a particular event occurs. The function must be of the form:
       (*funct)(instance, message, data)
       INT32 instance;
       int message;
       INT8 * data;
    instance is the instance of the type of element funct is to operate upon. message is the message that is to be sent to the function. data will be a pointer to the event which occurred to invoke this function.

    The rest of the parameters contained within the xrWindowFunct structure are defined as follows. processFlag is a boolean which is set to TRUE or FALSE by the application or manager adding the xrWindowFunct structure. It is used to turn on and off the processing of the event list and the automatic calling of the function attached to the window. eventCount contains a count of that number of events. eventList contains a pointer to an array of window event structures which are defined as follows:
    typedef struct
    {
       UINT32 inputType;
       INT16  inputCode;
    } xrWindowEvent;
    The type field of this structure can be set to any combination of X event types. The input code field is used for button or key events to further distingush the function. Each window can have as many xrWindowFunct structures attached to it as is needed. When input occurs on the window the event lists contained within the xrWindowFunct structures that are attached to the window will be searched to see if a match can be found. If the event matches one of the events listed for the window the function for the event is invoked. If no match is found, the event is returned as normal input.

MSG_REMOVEWINDOWFUNCT
    This message removes an xrWindowFunct structure that was previously added to the window windowId. data is a pointer to the function that matches the function supplied in the xrWindowFunct structure contained within the window.

MSG_SETPROCESSFLAG
    A manager of a window may, at times, want to turn on and off the event list checking and function calling provided through MSG_ADDWINDOWFUNCT. This message sets the processFlag field of the xrWindowFunct structure to TRUE which turns on the processing function for the window identified by the parameter windowId. data is a pointer to the function whose processFlag is to be set.

MSG_CLEARPROCESSFLAG
    This message is used to turn off a processing function for a window. Issuing this message causes processFlag to be set to FALSE which turns off the processing function for the window identified by the parameter windowId. data is a pointer to the function whose processFlag is to be cleared.

The following set of messages provide for the different forms of gathering input from Xrlib.

Xrlib supports both blocked and non-blocked input. Blocked input will cause the input routine to wait for input to occur on one of the windows or the file descriptors before returning. Blocked input will also return before input occurs is the application has supplied a timeout value. Non-blocked input will return immediately with either input or an indicator that no input has occurred.

Two modes of input are available within Xrlib. They are regular reads and hot reads. The difference between the two types of read involve the activation of the event list processing of the events attached to the window. For hot reads, when input occurs, the set of events attached to the window is scanned. If an event is found which matches the input, the cooresponding function is called. This is the means by which all of the editors and the menu system is invoked.

MSG_BLKREAD
    This message copies an input event into the XEvent structure pointed at by data if there is input pending. If there is no input, the call will wait until input occurs and return the input.

MSG_NONBLKREAD
    This message copies an input event into the XEvent structure pointed at by data if there is input pending. If there is no input, data is left unchanged and FALSE is returned.

MSG_BLKHOTREAD
    This message copies an input event into the XEvent structure pointed at by data if there is input pending. If there is no input, the call will wait until input occurs and return the input. If the input is select or menu input, the editors or menuing system will be invoked if appropriate.

MSG_NONBLKHOTREAD
    This message copies an input event into the XEvent structure pointed at by data if there is input pending. If there is no input, data is left unchanged and FALSE is returned. If the input is select or menu input, the editors or menuing system will be invoked if appropriate.

Xrlib provides a set of message for manipulating the input queue. The following list contains this set of messages.

MSG_PUSHEVENT
    This message places an event structure pointed to by data onto the front of the input queue. The next read will return this event.

MSG_PEEKEVENT
    This messages fills out the event structure pointed to by data from the event on the front of the input queue. The input queue is left unaffected by this call. If the input queue is empty, this call will fail.

MSG_CLEAR
    This message clears the input queue of all pending input. data is unused for this call and can be set to NULL.

The following list contains the set of messages to setup and change which sources XrInput() is to gather input.

MSG_ADDINPUT
    This message adds a file descriptor for which XrInput() is to gather input. data is a pointer to an xrFDInput structure which is defined as follows.
    typedef struct
    {
       INT32 fd;
       INT8  type;
    } xrFDInput;
    The fd field contains the file descriptor for the source of the input in which XrInput() is to gather input. The type field tells XrInput() which forms of input should be gathered from the file descriptor. It can be set to any combination of the defines XrREAD, XrWRITE, or XrEXCEPTION. These defines should be "Or'ed" together to define the value of this field.

MSG_REMOVEINPUT
    This message removes a previously added file descriptor from the input set. data must be set to point to an xrFDInput structure discussed in MSG_ADDINPUT. The structure should contain the file descriptor and the conditions which are to be removed.

MSG_SETTIMEOUT
    This message sets a timeout value, in seconds, for XrInput() to wait for input to occur from the file descriptors it is selecting upon. data is a pointer to the following structure.
    struct timeval
    {
       unsigned long tv_sec;
       long          tv_usec;
    };
    The tv_sec field defines the number of seconds to wait before a timeout is to occur. The tv_usec field defines the number of micro seconds to wait before a timeout is to occur. This structure is defined in <time.h>.

    The timeout value will affect how blocked reads work. Normally, the blocked read will wait indefinitely for input. If an application sets a timeout value, the blocked read will wait only the number of seconds + the number of micro seconds given by the value. The value of the timeout will have no effect on non-blocked reads.

MSG_GETTIMEOUT
    This message returns the current timeout value. data is a pointer a timeval structure which will be filled out to the current values.

RETURNED VALUE
For all of XrInput()'s messages, TRUE is returned if the function succeeds and FALSE is returned if it fails.

ERROR CONDITIONS
If XrInput() fails, the xrErrno global will be set to one of the following values.

xrErrno will be set to XrINVALIDID for all messages if the passed in window id is invalid.

xrErrno will be set to XrINVALIDMSG for any messages besides the messages listed above.

xrErrno will be set to XrINVALIDPARM whenever the data parameter contains invalid information.

xrErrno will be set to XrOUTOFMEM if MSG_ADDWINDOW cannot allocate the needed space for a window.

For reading messages, a return value of FALSE indicates that their was no input or a timeout occurred before input. There is no failure condition.