XREDITOR(3X)

NAME
Editor - Facilities providing some field editor manipulations

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

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

DESCRIPTION
XrEditor() provides a group of functions used to manipulate the list of editors attached to a window. The messages to the function can be used by both the Xrlib editors and the application. However, there are restrictions on the use of some of the messages. These restrictions will be noted along with the message descriptions.

The messages use the xrEditor structure for passing the editor information. The editor structure is defined as follows.
typedef struct _xrEditor
{
   struct _xrEditor * (*editorFunct)();
   Window editorWindowId;
   RECTANGLE editorRect;
   INT8 editorState;
   INT8 * editorData;
   struct _xrEditor * nextEditor;
} xrEditor;

The following set of messages should only be issued by field editors.

MSG_ADD
    This message allows a field editor to attach a particular editor instance to the active editor group within a specific window. Once an editor instance has been attached to a window, it is then able to receive input. The windowId parameter specifies the window to which the instance is to be attached. The data parameter points to the xrEditor structure associated with the editor instance. The XrEditor() function maintains a linked list of editor instances attached to each window and the new editor instance will be linked to the end of this list.

MSG_REMOVE
    This message allows a field editor to remove a particular editor instance from the list of editors attached to a window. Once an editor instance becomes unattached from a window, it is no longer able to receive any user input. Therefore, an editor instance should only be unattached when it is no longer needed. The windowId parameter specifies the window to which the instance is currently attached. The data parameter points to the xrEditor structure associated with the editor instance.

The following set of messages can be issued by an application.

MSG_PROCESSEVENT
    This message will take a passed-in XrEvent structure, and see if the event occurred within any of the field editor instances associated with the specified window. If the event did not occur within a rectangle of an editor group whose state is visible and sensitive, the message will fail. Also, if the event did not occur within one of the window's field editors, then the message will fail. A value of FALSE will be returned for both cases. If, however, the event did occur within one of the window's field editor instances, and the editor group in which the editor resides is visible and sensitive, then the handler routine for that editor instance will be called, and given the opportunity to process the event. Upon completion of the processing, the return value generated by the field editor will be returned.

    At invocation time, the windowId parameter must specify the window in which the input event occurred and the data parameter must point to the xrEvent structure containing the input information.

MSG_REDRAW
    This message allows an application to request that all field editor instances which lie within a specified rectangular portion of a window be completely redrawn. This is especially useful when a portion of a window which was hidden by another window is uncovered.

    To use this facility, the windowId parameter must be set to specify the window to be partially redrawn. The data parameter must point to a RECTANGLE structure which defines the rectangular region to be redrawn.

MSG_REDRAWALL
    This message provides an application with the means of easily redrawing all of the editors attached to a window. For this message, windowId should contain the window in which the editors are to be redrawn. data is unused and should be set to NULL.

MSG_SETSTATE
    This function allows an application to quickly modify the state flags associated with every field editor instance attached to a particular window. The state flags for each instance will be set to the same value. The state flags are defined in XrFieldEditors(3X) man page. To use this function, the application must set the windowId parameter to specify the window whose field editors are to be modified, and the data parameter must be set to the state value to be used for the set of editors.

RETURN VALUE
windowId is returned if the call to XrEditor() succeeds. FALSE is returned otherwise.

ERROR CONDITIONS
If XrEditor() returns FALSE, the xrErrno global will be set to one of the following values.

xrErrno will be set to XrINVALIDID for all of the messages if the window identified by the windowId parameter has not been registered with XrInput().

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 XrINVALIDEVENT if MSG_PROCESSEVENT fails because the event does not fall within one of the editors attached to the window or the event does not fall within a visible and sensitive editor group.

SEE ALSO
XrInput(3X), XrEditorGroup(3X), xrErrno(3X)