XRCHECKBOX(3X)

NAME
XrCheckBox - an editor for check boxes

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

XrEditor*
XrCheckBox (instance, message, data)
xrEditor * instance;
INT32 message;
INT8 * data;

DESCRIPTION

The checkbox editor is used to create and process a group of related checkboxes within a given window. The number of checkboxes, and how they are displayed, is completely controlled by the application. Each checkbox may also include an optional text label, which will be displayed to the right of the checkbox.

The size of the checkboxes are proportional to the size of the font being used to display the text labels. By allowing an application to specify this font, the size of the checkboxes can be adjusted for individual displays.

This field editor supports two distinct sets of state flags: those associated with the whole instance (which are modified using MSG_GETSTATE and MSG_SETSTATE), and those which are assigned to the individual checkboxes (which are modified using MSG_GETITEMSTATES and MSG_SETITEMSTATES). The state flags which are associated with the instance as a whole have precedence over the individual state flags. For example, if the XrVISIBLE flag is cleared for the instance, then none of the checkboxes will be displayed, regardless of their individual state flag settings. But, if the XrVISIBLE flag is set for the instance, then the field editor will look at the state of the XrVISIBLE flag associated with each checkbox, to determine if the entity should be displayed.

Using the cursor and the mouse, a user can interactively select a checkbox, by moving the cursor over one of the boxes, and 'clicking' the mouse button. This will cause the state of the chosen box to toggle. If the box had previously been active (filled), then it will now become inactive (not filled). Likewise, if the box was previously inactive (not filled), then it will now become active (filled). An application will then be notified of the change, and may handle it accordingly.

The checkbox editor will not restrict the number of boxes which may be active at any given moment, within a given instance. Instead, each checkbox in an instance is treated like an independent entity; its value does not rely on nor affect the value of any other checkbox in the instance.

A checkbox editor instance is composed of 3 components:

- The editor instance's background area.
- The individual checkboxes.
- The checkbox labels.

Of these 'selectable' regions, only select events which occur in one of the individual checkboxes will affect the instance. When one of these is selected, the editor will toggle the state of the checkbox, and then the application program will be notified that the value of one of the checkboxes has changed, along with the index of the checkbox which was modified. If a select event occurs in any of the other components, the application will be notified that a select occurred, but the editor instance was not modified.

When an editor instance is created, the initial value and the label strings for each checkbox will be specified by the application program. For the values, a pointer to an array of 8 bit integer values must be passed in. For the label strings, a pointer to an array of character strings may be passed in. The checkbox editor will not save copies of these pieces of data. Instead, it will save a copy of the pointers only. This will allow an application program to have immediate access to the checkbox values, since the array resides in the application's domain.

The editor allows an application to modify the data values associated with the checkboxes, however, the checkbox labels must not be modified, once the instance has been created. This editor will rely on the fact that when an application modifies any of the checkbox data values, the application will tell the editor to redraw; this allows the editor to remain in sync with the current checkbox data. Modifying the data, without doing a redraw, will cause the editor to behave in an unfriendly fashion.

This editor allows an application program to obtain information about an instance in two ways:

By means of an input event returned when a checkbox
is modified.

By means of the shared data values mentioned above.
This refers to the array of data describing the
value of each checkbox.

When the editor draws the specified checkbox instance, it will attempt to space out the checkboxes, to take full advantage of the specified editorRect. If the rectangle is larger than needed, then the extra space will be divided equally as blank space between the rows and columns. If the rectangle is too small, then the request will fail.

EDITOR MESSAGES

MSG_NEW
    This message will be the means by which an application program can create a checkbox editor instance in a port. It will expect the instance parameter to be set to NULL, and the data parameter to point to a filled out instance of the following structure:

         typedef struct {
              Window       editorWindowId;
              RECTANGLE    editorRect;
              INT8         editorState;
              INT32        editorFGColor;
              INT32        editorBGColor;
              FontInfo   * editorFont;
              INT16        numFields;
              INT16        numCols;
              INT8      ** labels;
              INT8       * values;
              INT8       * stateFlags;
          } xrCheckBoxInfo;

    editorWindowId
    This field indicates the window to which the editor instance is to be attached. Anytime the instance is redrawn, it will be redrawn in this window.

    editorRect
    This describes the location and size of the region into which the checkbox instance is to be located. If the rectangle is larger than is needed to hold the specified instance, then the extra space will be used as padding between the checkboxes. If the rectangle is too small, then the request will fail.

    editorState
    This field contains the initial value of the state flags for this editor instance. It can be composed of any combination of the XrSENSITIVE and XrVISIBLE flags.

    editorFGColor
    This field specifies the foreground color to be used when drawing the editor instance. It will be used to display the checkbox labels, and the checkbox borders. If this is set to -1, the default foreground color (see XrInit(3X) ) will be used.

    editorBGColor
    This field specifies the background color to be used when drawing the editor instance. It will be used to fill the interior of an inactive checkbox. If this is set to -1, the default background color (see XrInit(3X) ) will be used.

    editorFont
    This is a pointer to a structure which describes the font to be used when creating this editor instance. If the pointer has been set to NULL, then the editor will use the default system base font. The font is important not only because it describes how the labels will look, but it will also be used to determine how large the checkboxes should be.

    numFields
    This value indicates the total number of checkboxes which are included in this instance. Once specified, this value cannot be changed.

    numCols
    This value indicates the number of columns into which the checkboxes are to be displayed. Using this value, and numFields, the editor will automatically calculate the number of rows. If this value is greater than numFields, then the create request will fail.

    labels
    This is a pointer to an array of NULL terminated character strings, representing the labels associated with each checkbox. If this pointer is NULL, then none of the checkboxes will have labels. The first entry in the array will correspond to checkbox 0, the second to checkbox 1, etc. If an entry in this array is set to NULL, then the corresponding checkbox will have no label. The editor will not keep a copy of each of these strings; instead, it will only keep a copy of the pointer to the string array. It will rely on the application to NOT modify these strings, once the instance has been created.

    values
    This is a pointer to an array of 8 bit integer values, representing the initial state of each of the checkboxes. If this pointer is NULL, then the create request will fail. The first entry in this array corresponds to the value of checkbox 0, etc. A value of TRUE signifies that the checkbox should be drawn as 'active' (filled), while a value of FALSE signifies that a checkbox should be drawn as 'inactive' (not filled). The editor will not keep a copy of this array. Instead, it will only keep a copy of the pointer to this array. Anytime the value of a checkbox is modified, the editor will update the appropriate location in this array, and then notify the application. The application will then have immediate access to the checkbox values, since the array resides in its data area.

    stateFlags
    This is a pointer to an array of values, each containing the initial state flag settings to be associated with each checkbox in the instance. If this pointer has been set to NULL, then the state flags for each entity will be set to XrSENSITIVE and XrVISIBLE. The first entry in this array corresponds to checkbox 0, etc.

    The editor will then draw the checkbox editor instance in the specified window.

    Upon successful completion, a pointer to the newly created editor structure will be returned to the application This value must be used thereafter, whenever the application wishes to refer to this particular editor instance.

MSG_FREE
    This message is the mechanism by which an editor instance can be destroyed. The only parameter of importance is the instance parameter, which is a pointer to the editor structure, which was returned by the MSG_NEW message; this parameter specifies which instance is to be destroyed.

    When a checkbox instance is destroyed, it will be internally disconnected from the window to which it was attached, it will no longer handle mouse selects, and it will be removed from the window, if the instance is visible.

    After an editor instance has been destroyed, no further messages should be issued in regard to that instance.

MSG_GETSTATE
    This message returns the current state of the XrVISIBLE and XrSENSITIVE flags for the specified checkbox editor instance. The instance parameter specifies which instance to use. The data parameter should be a pointer to an 8 bit integer value, into which the current state flags will be placed.

MSG_SETSTATE
    This message allows an application program to modify the setting of the XrSENSITIVE and XrVISIBLE flags, for a given checkbox editor instance. The data parameter is interpreted as an 8 bit integer value, containing the new state flag values. After saving the new state flags, the editor instance will be redrawn, to reflect the new state. If an instance is not visible, then the rectangle which it occupies will be drawn using the background tile for the window, thus making it invisible. If an instance is visible, but not sensitive, then each checkbox will be drawn and filled with a 50% pattern.

MSG_GETITEMSTATES
    This message allows an application to obtain a copy of the individual state flags associated with each of the checkboxes contained within the specified editor instance. These state flags differ from the state flags obtained using MSG_GETSTATE. The instance parameter must specify the editor instance to be queried, while the data parameter should point to an array of 8 bit integer values. The state flags will be returned by means of this array. The flags associated with checkbox 0 will be returned in the first slot in the array, etc.

MSG_SETITEMSTATES
    This message allows an application to modify the individual state flags associated with each of the checkboxes contained within the specified editor instance. Presently, only the XrVISIBLE and the XrSENSITIVE flags are supported. The instance parameter must specify the editor instance which is to be modified, while the data parameter should point to an array of 8 bit integer values. The new state flags which are to be assigned to each entity within the instance will be obtained from this array. The value in the first slot of the array will be assigned to checkbox 0, etc. After the new state flags have been saved, only those checkboxes whose state flags changed will be redrawn.

MSG_GETITEMCOUNT
    This message allows an application to obtain a count, which indicates the number of individual checkboxes in the specified instance. The editor will assume that the instance parameter specifies the editor instance to be queried, and the data parameter points to a 32 bit integer value; the item count value will be returned by means of this integer.

    This message is useful when used in conjunction with the MSG_GETITEMRECTS message. It allows an application to obtain the number of items in the instance, so that the application can then allocate enough memory to hold the rectangle information returned by MSG_GETITEMRECTS.

MSG_GETITEMRECTS
    This message returns the coordinates for the rectangle which describes each of the individual checkboxes; these rectangles describe only the individual checkboxes - it does not include the labels. The message will expect the instance parameter to indicate the editor instance to be queried, and the data parameter to point to a structure of the following format:

    	RECTANGLE   itemRects[x];

    This array will then be filled with the rectangle information, and returned to the application.

    Before an application can make this call, it needs to know the number of items in the specified instance, so that it can allocate a structure large enough to hold all of the rectangle information. The application should use the MSG_GETITEMCOUNT message to obtain this information; the application can then allocate an array large enough to hold all of the rectangle entries.

    The order of the rectangle items returned in the array directly correlates to the order the items were originally created in. The first element in the array will describe checkbox 0, the second checkbox 1, etc.

    This message is useful to those applications which have a need of knowing where the individual items in a checkbox instance are located. The most common use would be by a forms controller, which would use the information to place an 'active field' indicator by a given item.

MSG_REDRAW
    This editor provides an application with the means for requesting that an instance of checkboxes be redrawn. The current values, labels and font information will be used.

    When this message is issued, the instance parameter must be a pointer to the editor structure associated with the instance to be redrawn. The data parameter must be a 32 bit integer which specifies the type of redraw to perform.

    The checkbox editor supports the following redraw mode:

    - XrREDRAW_ALL

    If any other redraw mode is specified, then the request will fail.

MSG_SIZE
    This message allows an application to obtain the rectangle needed to contain a checkbox editor instance. The checkbox editor expects the instance parameter to be set to NULL, and the data parameter to point to an instance of the following structure:

         typedef struct {
              Window editorWindowId;
              RECTANGLE editorRect;
              INT8 editorState;
              INT32 editorFGColor;
              INT32 editorBGColor;
              FontInfo * editorFont;
              INT16 numFields;
              INT16 numCols;
              INT8 ** labels;
              INT8 * values;
              INT8 * stateFlags;
          } xrCheckBoxInfo;

    The only fields which must be filled out by the application program BEFORE issuing this call, are the numFields, numCols, labels, and editorFont fields; all other fields are ignored.

    Using the supplied information, the editor will determine the size of the rectangle needed to contain this instance. In return, the editorRect field will be filled in with the coordinates for the 0 based rectangle needed to contain this instance; an application program can then offset this rectangle, to position it where ever it likes, within its window.

    If numCols > numFields, then the request will fail.

MSG_MOVE
    This message provides an application with a means for quickly relocating a particular editor instance within a window. The size of the editorRect associated with the instance is not changed. To relocate an editor instance, a new origin point for the instance's editorRect must be specified; the top left corner of the editor rectangle will then be translated such that it now coincides with the new origin. The origin point is interpreted as an absolute position within the window.

    When this message is issued, the instance parameter must point to the editor structure associated with the instance which is to be moved, while the data parameter must point to a POINT structure, containing the new editorRect origin.

    When an editor instance is relocated, the field editor will automatically remove the visual image of the instance from the window, and will then redraw the instance at its new location; this occurs only if the instance is visible.

MSG_RESIZE
    This message provides an application with a means for both changing the size of the editorRect associated with a particular editor instance, and also the location of the new editorRect. All restrictions regarding the editorRect size which applied when the instance was first created using MSG_NEW, still apply. If an invalid editorRect is specified, then the resize request will fail.

    When this message is issued, the instance parameter must point to the editor structure associated with the instance which is to be resized, while the data parameter must point to a RECTANGLE structure containing the new size and origin for the editorRect.

    When an editor instance is resized, the field editor will automatically remove the visual image of the instance from the window, and will then redraw the instance using the new size and location information; this occurs only if the instance is visible.

MSG_EDIT
    Normally, an application will not issue this message; it is usually issued by the Xrlib input routines, when an input event occurs within a checkbox instance.

    When such an event occurs, a MSG_EDIT message will be issued to the editor, with the first parameter, instance, indicating which checkbox instance to process, and the third parameter, data, pointing to an XEvent structure.

    The checkbox editor only handles an event if it maps to an XrSELECT event, as described by XrMapButton(3X) and XrInit(3X); all others are ignored. When a select event occurs within a checkbox instance, the first thing done is to determine if one of the checkboxes was selected.

    If one of the checkboxes was selected, then the value of the selected checkbox will be toggled, and the particular box redrawn. Afterwards, an input event will be added to the front of the application's input queue, informing it that one of the checkboxes was selected. The returned xrEvent structure is set to the following value:

       type       = XrXRAY
       source     = the window id
       inputType  = XrEDITOR
       inputCode  = XrCHECKBOX
       value1     = XrSELECT
       value2     = index of the modified checkbox
       valuePtr   = pointer to instance's editor structure

    The editor will update the value of the selected checkbox in the array shared with the application program. This value is then directly available to the application program.

    If a select occurs within a checkbox instance, but not within the boundary of a checkbox, then the editor will do nothing but push an input event onto the front of the application's input queue. The event will notify the application that the editor was selected, but no action took place. In addition, the cursor position at the time the select event occurred will be returned. The returned xrEvent structure is set to the following value:

       type      = XrXRAY
       source    = the window id
       inputType = XrEDITOR
       inputCode = XrCHECKBOX
       value1    = NULL
       valuePt   = cursor position
       valuePtr  = pointer to instance's editor structure

RETURN VALUE
Upon successful completion of any of the messages, a non-NULL value will be returned. In the case of MSG_NEW, this non-NULL value will be the pointer to the newly created editor instance structure.

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

MSG_NEW
    data is set to NULL [XrINVALIDPTR].

    editorWindowId is an invalid Id [XrINVALIDID].

    numCols > numFields [XrINVALIDPARM].

    values is set to NULL [XrINVALIDPTR].

    An invalid editor rectangle is specified [XrINVALIDRECT].

    A call to 'X' fails { XMakePixmap() } [XrXCALLFAILED].

    Memory cannot be allocated [XrOUTOFMEM].

MSG_REDRAW
    A redraw mode other than XrREDRAW_ALL was specified [XrINVALIDOPTION].

MSG_SIZE
    data is set to NULL [XrINVALIDPTR].

    numCols > numFields [XrINVALIDPARM].

MSG_RESIZE
    An invalid editor rectangle is specified [XrINVALIDRECT].

MSG_GETSTATE, MSG_MOVE, MSG_RESIZE, MSG_GETITEMRECTS,

MSG_GETITEMSTATES, MSG_SETITEMSTATES and MSG_GETITEMCOUNT
    data is set to NULL [XrINVALIDPTR].

All messages, except MSG_NEW and MSG_SIZE
    The instance parameter is set to NULL [INVALIDID].

SEE ALSO
XrInput(3X), XrInit(3X)