XRSTATICRASTER(3X)

NAME
XrStaticRaster - an editor which displays a static raster image

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

xrEditor *
XrStaticRaster (instance, message, data);
xrEditor * instance;
INT32      message;
INT8     * data;

DESCRIPTION

The static raster editor provides an application with the means for placing uneditable raster images anywhere within the bounds of a window.

The application must specify a rectangular region, into which the raster image will be drawn. If the raster image will not fit exactly within the rectangle, then the create request will fail.

The actual raster data is not supplied to the editor. Instead, the application must pass in the pixmap Id associated with the raster image. The pixmap Id is obtained by registering the raster data with the appropriate server, using the XStorePixmapZ() routine. Refer to the `Xlib' documentation for a further discussion on this subject. It is up to the application to guarantee that it does not pass in an invalid pixmap Id.

Once a static raster image has been displayed, the only attributes which may be modified are the XrVISIBLE and XrSENSITIVE state flags. The actual raster data cannot be modified.

EDITOR MESSAGES

MSG_NEW
    This message will be the means by which an application program can create a static raster image within a window. 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;
              INT32        rasterHeight;
              INT32        rasterWidth;
              Pixmap       rasterId;
          } xrStaticRasterInfo;

    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 static raster image is to be displayed. If the raster image will not fit exactly within this rectangle, then the create request will fail.

    editorState
    This field contains the initial value of the state flags for this editor instance. If 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. This value is unused by this field editor. 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. This value is unused by this field editor. If this is set to -1, the default background color (see XrInit(3X) ) will be used.

    rasterHeight
    This specifies the height of the raster image, in pixels.

    rasterWidth
    This specifies the width of the raster image, in pixels.

    rasterId
    This contains the pixmap Id associated with the static raster data. The pixmap Id is obtained by registering the raster data with appropriate server.

    The editor will then draw the static raster image 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 there after, 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 returned by MSG_NEW; this parameter specifies which instance is to be destroyed.

    When a static raster 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 static raster instance indicated by the instance parameter. 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 the static raster instance indicated by the instance parameter. The data parameter is interpreted as an 8 bit integer value, containing the new state flag value. 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.

MSG_REDRAW
    This message will provide an application with the means for requesting that a static raster image be redrawn.

    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 static raster 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 height and width of the rectangle needed to contain a given static raster image.

    The static raster 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;
              INT32        rasterHeight;
              INT32        rasterWidth;
              Pixmap       rasterId;
          } xrStaticRasterInfo;

    The fields which must be filled out by the application program BEFORE issuing this call, are the rasterHeight and rasterWidth fields.

    In return, the editorRect field will be filled in with the coordinates for the 0 based rectangle needed to contain the instance; an application program can then offset this rectangle, to position it where ever it likes, within it's window.

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_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 static raster instance.

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

    The static raster 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 static raster image, the editor will do nothing but add an input event to the front of the application's input queue, informing it that a static raster image was selected. The returned xrEvent structure is set to the following value:

       type      = XrXRAY
       source    = the window Id
       inputType = XrEDITOR
       inputCode = XrSTATICRASTER
       value1    = XrSELECT
       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.

If a message request fails, then a NULL value is returned.

ERROR CONDITIONS
Messages to the static raster 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].

    rasterId is an invalid Id [XrINVALIDID].

    editorRect is an invalid size [XrINVALIDRECT].

    rasterHeight or rasterWidth is less than or equal to zero [XrINVALIDPARM].

    Memory cannot be allocated [XrOUTOFMEM].

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

MSG_SIZE
    data is set to NULL [XrINVALIDPTR].

    rasterHeight or rasterWidth is less than or equal to zero [XrINVALIDPARM].

MSG_GETSTATE and MSG_MOVE
    data is set to NULL [XrINVALIDPTR].

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

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