XRRASTEREDIT(3X)

NAME
XrRasterEdit - an editor that creates and controls a raster editor.

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

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

DESCRIPTION

The raster editor is used to create and process an instance of a raster editor within a given window. It will allow an application program to specify a raster image from as small as 16x16 pixels; the specified raster image need not be square.

The number of bits making up each pixel (referred to as the 'depth' of the pixel) is definable by the application, but can assume only one of the following values:

- 1 bit/pixel    [XrBIT1]
- 1 byte/pixel   [XrBYTE1]
- 2 bytes/pixel  [XrBYTE2]
- 3 bytes/pixel  [XrBYTE3]
- 4 bytes/pixel  [XrBYTE4]

When a raster editor instance is created, the application can specify how much of the raster image is to be displayed at any given time; this is referred to as the 'view region'. The view region can be from as small as 16 x 16, up to the size of the raster image. Each pixel within this view region will be expanded and displayed as a 'pixelSize'x'pixelSize' bit area, thus allowing a user to easily select and modify a pixel within the region. Each pixel will be surrounded by a one bit wide border.

The 'pixelSize' value is specified at the time the instance is created. It allows an application to size the raster editor instance, so that it will be usable in any sized display. Any value greater than or equal to 4 may be specified as the pixel expansion factor.

Using the cursor and the mouse, a user will be able to select a pixel to be changed in one of several ways:

By 'clicking' the mouse, the pixel over which the cursor is located will be changed to whatever color the application has specified. By pressing the mouse button, and then dragging the cursor, any pixels over which the cursor passes will be changed to whatever color the application has specified; releasing the mouse button will cause the action to stop, as will the receipt of any other X event.

If the raster image is larger than the view region, in either direction, then the editor will display and manage either/both a vertical and/or a horizontal scrollbar. The horizontal scrollbar will be located beneath the raster edit display, while the vertical scrollbar will be located to the right of the raster edit display. The raster editor will take sole responsibility for processing the scrollbars; however, anytime the raster image is scrolled, an event will be returned to an application program, informing it of the new view origin.

These scrollbars provide the means by which a user can scroll through the complete raster area. There are currently 4 ways in which a scroll operation may be requested:

- The 'UP' (LEFT) arrow is selected.
- The 'DOWN' (RIGHT) arrow is selected.
- A position within the scroll area is selected.
- The slide box is interactively moved.

Depending upon which of the above methods is used, a different amount of scrolling may take place:

    When either of the scroll arrows is selected, the view region will pan 1 pixel in the requested direction.

    When a select occurs within the scroll area, the requested portion of the raster image will then be displayed.

    When the slide box is selected, the raster image will not be updated, until the user has finished moving the slide box. When slide box movement has completed, the editor will redraw the instance, and display the requested portion of the raster area.

For each of the above events, the raster editor will return an input event, informing the application that the raster image has been scrolled, along with the new view origin.

EDITOR MESSAGES

MSG_NEW
    This message will be the means by which an application program can create a raster editor instance in 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       pixelColor;
              INT32       pixelSize;
              SIZE        viewRegion;
              xrPixmap    rasterData;
          } xrRasterEditInfo;

    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 into which the raster editor is to be located. This must include space for the view region, and scrollbars, if needed. When the instance is laid out, the view region will be positioned starting at the upper left of the editorRect, the horizontal scrollbar will be positioned at the lower left, and the vertical scrollbar will be positioned at the upper right of the editorRect.

    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. The foreground color is used to draw the border around each pixel in the raster image, and by the scrollbars. 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. The background color is used only by the scrollbars. If this is set to -1, the default background color (see XrInit(3X) ) will be used.

    pixelColor
    This field specifies the color to which a pixel should be set, when it is 'selected' by the user.

    pixelSize
    This describes the height and width into which each displayed pixel is to be expanded. This must be a value greater than or equal to 4. Any other value will cause the create request to fail.

    viewRegion
    This describes the height and width of the view region for the instance. The dimensions for these values may be in the range from 16 up to the corresponding dimension of the raster image. If a view region is specified which is larger than the raster image, then the request will fail.

    rasterData
    This field contains all of the information describing the raster image which is to be edited. This includes the size of the raster (height and width), the depth of each pixel within the raster, and a pointer to the actual raster data. The size can assume any value greater than or equal to 16. The depth can assume a value of 1 bit, or 1, 2, 3 or 4 bytes.

    The editor will then draw the raster editor instance in the specified window. The initial location of the view region is the upper right corner of the raster area.

    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 raster editor 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 raster editor instance indicated by the instance parameter. 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. If any scrollbars are being used by this instance, then their state will be identical to that of the raster editor instance.

MSG_SETSTATE
    This message allows an application program to modify the setting of the XrSENSITIVE and XrVISIBLE flags, for a given raster editor instance, along with any scrollbars which may be in use by this instance. The instance parameter specifies which editor instance is to be affected. 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. The scrollbar editor will also be invoked, if necessary, to cause the scrollbars associated with this instance to be redrawn using the new state information. 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_SETCOLOR
    This message allows an application to specify the color to which a pixel should be set, when it is 'selected' by the user. The data parameter will be interpreted as a 32 bit integer value, containing the color information. The instance parameter specifies the editor instance to be affected.

MSG_REDRAW
    Since the buffer containing the data describing the raster area resides in the application's domain, a means is provided to allow the application to change the data, and then tell the editor about it; the editor will then update the visible portion of the instance, to match the new data.

    Using the MSG_REDRAW message, an application can force the editor to redraw a raster editor instance. The editor will use the data in the array pointed to by the rasterData, structure, as the new raster information. The complete editor instance will be redrawn.

    When this message is invoked, the instance parameter must point to the editor structure for the instance to be redrawn, and the data parameter must be a 32 bit integer which specifies the type of redraw which is to occur.

    The raster editor supports only a single 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 raster editor instance. Depending upon the description supplied by the application program, this rectangle may hold only a raster editor instance, or it may also include up to 2 scrollbars. The 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       pixelColor;
              INT32       pixelSize;
              SIZE        viewRegion;
              xrPixmap    rasterData;
          } xrRasterEditInfo;

    The only fields which must be filled out by the application program BEFORE issuing this call, are the height and width fields in the rasterData structure and the pixelSize and viewRegion fields; all other fields are ignored.

    Using the supplied raster image height, width sizes, the view region height and width sizes, and the pixel size values, the editor will determine the size of the rectangle needed to contain this instance. If either the height or width of the raster image is greater than the corresponding view region dimension, then this rectangle will also take into account the scrollbars. 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.

    Specifying a raster height or width or a view region height or width less than 16 will cause this request to fail.

MSG_POSITION
    This message provides an application with the means for positioning the view region within the raster image. The instance parameter must point to the editor structure associated with the instance to be modified, while the data parameter must point to a POINT structure, containing the new origin of the view region; the top left corner of the view region will be positioned at the specified (x,y) position within the raster image.

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 raster editor instance.

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

    The 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 the raster editor, the first thing done is to determine which of the following regions was selected:

    - The raster editor region.
    - The vertical scrollbar.
    - The horizontal scrollbar.
    - The background area.

    Depending upon the region selected, a different action is taken:

    Vertical scrollbar
    The view box will be scrolled vertically within the raster area. Upon completion of the scroll operation, the following event will be pushed onto the front of the application's input queue:

        type      = XrXRAY
        source    = the window Id
        inputType = XrEDITOR
        inputCode = XrRASTEREDIT
        value1    = XrSCROLLBAR
        valuePt   = new view origin
        valuePtr  = pointer to instance's editor structure

    Horizontal scrollbar
    The view box will be scrolled horizontally within the raster area. Upon completion of the scroll operation, the following event will be pushed onto the front of the application's input queue:

        type      = XrXRAY
        source    = the window Id
        inputType = XrEDITOR
        inputCode = XrRASTEREDIT
        value1    = XrSCROLLBAR
        valuePt   = new view origin
        valuePtr  = pointer to instance's editor structure

    Raster edit region
    The selected pixel(s) will be modified, and an input event will be added to the front of the application's input queue, informing it that the raster area has been modified. The returned xrEvent structure is set to the following value:

        type      = XrXRAY
        source    = the window Id
        inputType = XrEDITOR
        inputCode = XrRASTEREDIT
        value1    = XrSELECT
        valuePtr  = pointer to instance's editor structure

    If the raster was modified by the user dragging the cursor, and the draw operation was terminated by the receipt of an X event other than a select up event, then the X event which caused the drag operation to terminate will also be pushed on the front of the input queue, BEFORE the xrEvent discussed above is pushed. If the terminating event was a select up event, then the field editor will swallow it.

    Since the actual raster data resides in the application's domain, it can have immediate access to the data.

    Background region
    This implies that the select occurred within the editorRect, but not within any of the previously mentioned components. The following input event will be returned; it includes the cursor position at the time the select event occurred:

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

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

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

    editorRect is an invalid size [XrINVALIDRECT].

    A dimension of the raster image size or the view region size is less than 16 [XrINVALIDPARM].

    A dimension of the view region is greater than the corresponding dimension of the raster image [XrINVALIDPARM].

    The raster depth is not 1 bit, or 1, 2, 3 or 4 bytes [XrINVALIDDEPTH].

    pixelSize is an invalid value [XrPARMOUTOFRANGE].

    The pointer to the raster data has been set to NULL [XrINVALIDPTR].

    Memory cannot be allocated [XrOUTOFMEM].

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

MSG_SIZE
    data is set to NULL [XrINVALIDPTR].

    A dimension of the raster image size or the view region size is less than 16 [XrINVALIDPARM].

    A dimension of the view region is greater than the corresponding dimension of the raster image [XrINVALIDPARM].

    pixelSize is an invalid value [XrPARMOUTOFRANGE].

MSG_RESIZE
    data is set to NULL [XrINVALIDPTR].

    editorRect is an invalid size [XrINVALIDRECT].

MSG_POSITION
    An invalid view region origin is specified [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)