XRSCROLLBAR(3X)

NAME
XrScrollBar - an editor that creates and controls a scroll bar.

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

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

DESCRIPTION

The scrollbar editor is used to create and process an instance of a scrollbar within a given window. Both vertical and horizontal scrollbars are supported by the editor. Scrollbars can be manipulated by selecting one of the direction arrows, interactively moving the slide box, or by selecting a location within the scroll region.

The components making up a scrollbar instance are configurable, and can be modified at any time after the instance has been created. These components include the following:

- Scroll arrows
- A variable sized slide box
- The upper and lower limits of the scroll region (or slide area)

The scrollbar editor provides an application with two modes of interactive slide operations:

Normal and Transparent

In Transparent mode, when the user wants to interactively move the slide box, only an outline of the slide box is moved; the real slide box is not moved.

In Normal mode, when the user wants to interactively move the slide box, the slide box itself is moved.

The editor also allows the application program to specify a handler routine, which will be automatically invoked during an interactive slide operation, each time the slide box position is changed by the specified number of scroll region units. This allows an application to update its window contents as the slide box is moved.

The scroll region units are defined by the application; this allows an application to supply the minimum and maximum value for the scroll region. For a horizontal scrollbar, the minimum value is the left edge of the region, and the maximum value is the right edge of the region; for a vertical scrollbar, the minimum value is the upper edge of the region, and the maximum value is the lower edge of the region. Anytime the slide box position is referenced, it will be specified in terms of these maximum and minimum values. All integer values in this range are referred to as scroll region units.

Both the height and the width of a scrollbar are definable by an application program. There are no real upper limits imposed upon a scrollbar instance, but there are lower limits. The limits relate to the ratio between the height and width of a scrollbar. For a vertical scrollbar, the minimum height of a scrollbar is calculated using the width of the scrollbar rectangle; for a horizontal scrollbar, the minimum width of a scrollbar is calculated using the height of the scrollbar rectangle. If the specified editorRect is not large enough to contain the requested scrollbar instance, then the create request will fail. If MSG_SIZE is used to obtain the minimum rectangle, then a create request should never fail for the above mentioned reasons.

EDITOR MESSAGES

MSG_NEW
    This message will be the means by which an application program can create a scrollbar 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;
              INT8           orientation;
              xrSBParameters configuration;
          } xrScrollBarInfo;

    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 scrollbar instance. The rectangle must be at least large enough to hold a minimally sized scrollbar; if it is not, then the create request will fail. To prevent this from happening, an application should use the MSG_SIZE message to obtain the minimal rectangle, and it can then stretch and offset the rectangle, to obtain the desired size scrollbar.

    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, XrVISIBLE and XrTRANSPARENT flags.

    editorFGColor
    This field specifies the foreground color to be used when drawing the editor instance. This is used for all borders, and for filling the slide box. 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 is used for the interior of the scrollbar region. If this is set to -1, the default background color (see XrInit(3X) ) will be used.

    orientation
    This describes the orientation of the scrollbar instance, and can assume one of the following values: XrHORIZONTAL or XrVERTICAL.

    configuration
    This field specifies all of the configuration parameters needed to initially display the scrollbar instance. This field is an instance of the following structure:

    typedef struct {
            INT8   components;
            INT16  min;
            INT16  max;
            INT16  slidePosition;
            INT16  slideSize;
            INT32  (*handler)();
            INT16  granularity;
    } xrSBParameters;

    The components field specifies the component parts which are to be initially displayed as part of the scrollbar instance. It is constructed by OR'ing together a combination of the XrSLIDEBOX and XrSCROLLARROWS flags.

    The min and max values describe the units which are to be assigned to the top (left) and bottom (right) of the scroll region.

    The slidePosition value specifies the initial position of the slide box within the scroll region. The position is expressed in scroll region units, and must be in the range min - max; if an invalid position is specified, then the create request will fail. If the XrSLIDEBOX flag is not set in the components field, then this field is ignored.

    The slideSize value specifies the initial size of the slide box. It is expressed in scroll region units, and must be in the range 0 to (min - max); if an invalid size is specified, then the create request will fail. If the XrSLIDEBOX flag is not set in the components field, then this field is ignored.

    The handler field allows an application to specify its own handler routine, which will be automatically invoked by the scrollbar editor during interactive slide operations. If the handler field is set to NULL, then the scrollbar editor will disable this feature.

    When the handler routine is invoked, it will be called in the following fashion:

         INT32
         handler (windowId, editorInstance, slidePosition)
             Window     windowId;
             xrEditor * editorInstance;
             INT16      slidePosition;

    The granularity value represents a value in the range 0 to (min - max), where min and max are the limits of the scroll region.

    The editor will then draw the scrollbar 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 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, which was returned by the MSG_NEW message; this parameter specifies which instance is to be destroyed.

    When a scrollbar 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, XrSENSITIVE and XrTRANSPARENT flags for the specified scrollbar instance. The instance parameter specifies which instance to inquire about. 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, XrVISIBLE and XrTRANSPARENT flags, for a given scrollbar 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, if either the XrSENSITIVE or XrVISIBLE flags changed. 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 only the outline of the scrollbar,the slide box, and the scroll arrows will be drawn. The XrTRANSPARENT flag controls the behavior of the slide box during interactive slide box move operations.

MSG_REDRAW
    This editor provides an application with the means for requesting that a particular scrollbar instance be redrawn.

    When this message is issued, the instance parameter must point 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 scrollbar editor supports the following redraw mode:

    - XrREDRAW_ALL

    When the XrREDRAW_ALL option is specified, the complete scrollbar instance will be redrawn; similar to when the instance was first displayed.

    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 minimally sized scrollbar of a specified width (if vertical) or height (if horizontal). Once an application program has obtained this information, it can stretch and offset the rectangle, thus customizing it to it's own needs. It 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;
              INT8           orientation;
              xrSBParameters configuration;
          } xrScrollBarInfo;

    One field which must be filled out by the application program BEFORE issuing this call, is the orientation field; it must be set to either XrVERTICAL or XrHORIZONTAL.

    If a vertical scrollbar was specified, then the width of the desired scrollbar must be specified. This is done by setting the following value in the structure:

    editorRect.width

    If a horizontal scrollbar was specified, then the height of the desired scrollbar must be specified. This is done by setting the following value in the structure:

    editorRect.height

    If this value is less than 11, then the request will fail; a scrollbar cannot be smaller than 11 pixels.

    In return, the editorRect field will be filled in with the coordinates for the 0 based rectangle needed to contain an instance of the smallest sized scrollbar with the specified orientation and height or width.

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_GETPARAMETERS
    This message provides an application with the means for obtaining the current configuration parameters associated with a particular scrollbar instance, or the means for initializing a parameter structure with the default configuration values. If an application wishes to obtain the current configuration parameters for an existing scrollbar instance, then it should set the instance parameter such that it specifies the instance to be queried; if an application wishes to only initialize a parameter structure with the default values, then it should set the instance parameter to NULL. The data parameter must to point to an instance of the following structure:

    typedef struct {
            INT8   components;
            INT16  min;
            INT16  max;
            INT16  slidePosition;
            INT16  slideSize;
            INT32  (*handler)();
            INT16  granularity;
    } xrSBParameters;

    Each field in this structure will be filled in with the current configuration information for the specified instance, or the default value.

    The default value associated with each field is shown below:

    components = XrSCROLLARROWS | XrSLIDEBOX
    min = 0
    max = 100
    slidePosition = 0
    slideSize = 10
    handler = NULL
    granularity = 10

MSG_SETPARAMETERS
    This message provides an application with the means for modifying the configuration parameters associated with a particular scrollbar instance. It will expect the instance parameter to specify the instance to be queried, and the data parameter to point to an instance of the following structure:

    typedef struct {
            INT8   components;
            INT16  min;
            INT16  max;
            INT16  slidePosition;
            INT16  slideSize;
            INT32  (*handler)();
            INT16  granularity;
    } xrSBParameters;

    If the XrSLIDEBOX flag in the components field is not set, then the values in the slidePosition, slideSize, handler and granularity fields will be ignored.

    After the values have been saved, the affected components within the instance will be redrawn; the whole instance is not redrawn.

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 scrollbar instance.

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

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

    - A scroll arrow.
    - The slide box.
    - The scroll region.

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

    A scroll arrow box
    If the scroll arrows are displayed as part of the instance, then an input event will be added to the front of the application's input queue, informing it that the particular scroll arrow was selected. The slide box position is not modified. The returned xrEvent structure is set to the following values:
    	type      = XrXRAY
    	source    = the window Id
     	inputType = XrEDITOR
            inputCode = XrSCROLLBAR
            value1    = (see values listed below)
            value2    = current slide box position
            valuePtr  = pointer to instance's editor structure

    The value1 field will return an indication of which scrollbar arrow was selected. It will be set to one of the following values:

            XrSCROLL_LEFT
            XrSCROLL_RIGHT
            XrSCROLL_UP
            XrSCROLL_DOWN

    If an application then wants the slide box position modified, it should calculate the new slide box position, and then use the MSG_SETPARAMETERS message to reposition the slide box.

    If the scroll arrows are not visible, then a NULL event will be returned to the application. The returned xrEvent structure will be set to the following values:
    	type      = XrXRAY
    	source    = the window Id
     	inputType = XrEDITOR
            inputCode = XrSCROLLBAR
            value1    = NULL
            value2    = current slide box position
            valuePt   = cursor position
            valuePtr  = pointer to instance's editor structure

    An application could easily implement smooth, continuous scrolling, by polling for a select up event after it has received one of the above scroll arrow events. When the select up event is received, the application would know to stop the continuous scrolling.

    Slide box
    When the slide box is selected, the scrollbar editor will keep control, until any X event is received; normally, it is a select up event which terminates the slide operation.

    If the scrollbar is currently configured to operate in Normal mode, then as the user moves the cursor, the slide box will follow. If the slide operation terminates because a select up event is received, then the xrEvent event described below will be pushed onto the front of the application's input queue. If the slide operation terminates because any other X event is received, then the X event will be re-pushed onto the front of the input queue, and then the xrEvent event described below will be pushed. The xrEvent event, will be set to contain the following information:
    	type      = XrXRAY
    	source    = the window Id
    	inputType = XrEDITOR
            inputCode = XrSCROLLBAR
            value1    = XrSCROLL_SLIDE
            value2    = new slide box position
            valuePtr  = pointer to instance's editor structure

    If the scrollbar is currently configured to operate in Transparent mode, then as the user moves the cursor, an outline of the slidebox will follow. If the slide operation terminates because a select up event is received, then the xrEvent event described below will be pushed onto the front of the application's input queue. If the slide operation terminates because any other X event is received, then the X event will be re-pushed onto the front of the input queue, and then the xrEvent event described below will be pushed. The position of the slide box will not be changed. The position of the slide box outline will be returned; it is up to the application to then instruct the scrollbar editor to move the slide box to that position, if desired. The xrEvent structure will contain the following information:
    	type      = XrXRAY
    	source    = the window Id
    	inputType = XrEDITOR
            inputCode = XrSCROLLBAR
            value1    = XrTSCROLL_SLIDE
            value2    = current slide box position
            value3    = slide box outline position
            valuePtr  = pointer to instance's editor structure

    For both of the above modes, as the slide box is moved, each time its position changes by the specified granularity, the specified interactive slide handler routine will be invoked.

    Scroll region
    When a select occurs within the scroll region portion of a scrollbar, the editor will return an input event to the application, informing it that a select occurred within the instance's scroll region. The editor will not automatically reposition the slide box. It is up to the application, once it has received notification, to update the slide box position. Returned as part of the input event, is the location of the cursor at the time of the select, expressed as in scroll region units.

    The xrEvent structure will contain the following information:
    	type      = XrXRAY
    	source    = the window Id
    	inputType = XrEDITOR
            inputCode = XrSCROLLBAR
            value1    = XrSCROLL_LESS or XrSCROLL_MORE
            value2    = current slide box position
            value3    = cursor location (in slide region units)
            valuePtr  = pointer to instance's editor structure

    NOTE: if the slide box component is not currently being displayed, then the value1 field will always be set to XrSCROLL_MORE.

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 scrollbar 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 not large enough to contain the scrollbar [XrINVALIDRECT].

    The width for a vertical scrollbar is less than 11 [XrINVALIDPARM].

    The height for a horizontal scrollbar is less than 11 [XrINVALIDPARM].

    orientation is set to an unknown value [XrINVALIDOPTION].

    granularity is outside the scrollbar unit range [XrPARMOUTOFRANGE].

    max <= min [XrINVALIDPARM].

    slidePosition is outside the scrollbar unit range [XrPARMOUTOFRANGE].

    slideSize is outside the scrollbar unit range [XrPARMOUTOFRANGE].

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

    Memory cannot be allocated [XrOUTOFMEM].

MSG_RESIZE
    data is set to NULL [XrINVALIDPTR].

    editorRect is not large enough to contain the scrollbar [XrINVALIDRECT].

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

MSG_SIZE
    data is set to NULL [XrINVALIDPTR].

    The width for a vertical scrollbar is less than 11 [XrINVALIDPARM].

    The height for a horizontal scrollbar is less than 11 [XrINVALIDPARM].

    orientation is set set to an unknown value [XrINVALIDOPTION].

MSG_SETPARAMETERS
    data is set to NULL [XrINVALIDPTR].

    max <= min [XrINVALIDPARM].

    slidePosition is outside the scrollbar unit range [XrPARMOUTOFRANGE].

    slideSize is outside the scrollbar unit range [XrPARMOUTOFRANGE].

    granularity is outside the scrollbar unit range [XrPARMOUTOFRANGE].

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

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

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