gsmcat

Purpose

     Sets the cursor attributes.

C Syntax

     int gsmcat_ (foreground, background, width, height, pattern, mask, 0x, 0y, logop)

     int *foreground, *background, *width, *height, *pattern, *mask, *0x, *0y, *logop)

FORTRAN Syntax

     INTEGER function gsmcat_ (foreground, background, width, height, pattern, mask, 0x, 0y, logop)

     INTEGER foreground, background, width, height, pattern, mask, 0x, 0y, logop)

Pascal Syntax

     FUNCTION gsmcat_ (

     VAR foreground, background, width, height: INTEGER;
     VAR pattern: ARRAY [1..k| of INTEGER;
     VAR mask: ARRAY [1..k| of INTEGER;
     VAR 0x, 0y, logop: INTEGER
     ): INTEGER [PUBLIC|;

Description

     The gsmcat subroutine defines  the multi-color cursor for
     the GSL.  The gscmap subroutine must initialize the color
     map before gsmcat can be called.

     Only  one cursor,  either the  multi-color cursor  or the
     single-color cursor, can be active  in the GSL at any one
     time.  The gsmcat subroutine  forces all subsequent calls
     to the  gsmcur and gsecur  subroutines to operate  on the
     multi-color version  of the  cursor.  To change  from the
     single-color cursor to the  multi-color cursor, erase the
     cursor with gsecur, then call the gsmcat subroutine.

     The  multi-color cursor  is a  two-color, clipped  cursor
     with logical operations.  Its size  is limited to 32 bits
     in  width and  32 bits  in height.   Although the  cursor
     origin cannot  be moved outside the  frame buffer bounda-
     ries, any  portion beyond  the origin that  falls outside
     the frame buffer is clipped.  In addition, a mask is pro-
     vided that  can be  used to allow  portions of  the frame
     buffer to show through the cursor.   Any bits set to 0 in
     the mask  indicate that the  matching bits in  the cursor
     pattern do not affect the underlying frame buffer.

     Parameters

     foreground        Defines a color entry in the color map.
                       This color  is used for  the foreground
                       color  (bits set  to 1)  in the  multi-
                       color  cursor raster.   A  value of  -1
                       indicates no change to this attribute.

     background        Defines a color entry in the color map.
                       This color  is used for  the background
                       color  (bits set  to 0)  in the  multi-
                       color  cursor raster.   A  value of  -1
                       indicates no change to this attribute.

     width, height     Define, in pixels, the width and height
                       of the bit pattern  and mask to be used
                       as the  cursor.  The maximum  value for
                       width and  height of  the cursor  is 32
                       bits.   If width  or height  equals -1,
                       then  the pattern  and the  mask remain
                       unchanged.

     pattern           Defines  the  raster  image used  as  a
                       cursor.  It must be specified in 32-bit
                       integers,  and  there  must  be  height
                       number of rows.  The  GSL will only use
                       width number of bits in each integer.

     mask              Defines the mask pattern of the cursor.
                       Each bit in the mask corresponds with a
                       bit in the  multi-color cursor pattern.
                       If a bit is set (has a value of 1), the
                       matching bit in  the pattern is applied
                       to the underlying dispaly raster.  If a
                       bit is not set (has  a value of 0), the
                       matching bit  in the pattern  is masked
                       and  does  not  affect  the  underlying
                       display raster.   The size of  the mask
                       must  match  the  size of  the  pattern
                       exactly.

     0x, 0y            Indicate the origin of the cursor rela-
                       tive  to  the   lower  leftmost  corner
                       (0, 0)  of  the  cursor  pattern.   The
                       origin must be placed within the cursor
                       pattern:   0x < width and  0y < height.
                       The origin  of the cursor is  placed at
                       the position indicated, when the appli-
                       cation  moves  the   cursor  using  the
                       gsmcur  subroutine.   If x  equals  -1,
                       then the origin remains unchanged.

     logop             Defines   the   logical  operation   to
                       perform  between   the  cursor  pattern
                       being  drawn and  the  contents of  the
                       frame  buffer.   The following  logical
                       operations are supported:

                       3    Replace
                       6    Exclusive-or

     You cannot change the  cursor attributes while the cursor
     is visible.

     There is no default cursor defined, so all cursor parame-
     ters must be set before the cursor is displayed.

     For Pascal, the application must declare the array passed
     as  being  fixed  length   and  declare  the  routine  as
     accepting arrays  of that length.   The k in  the routine
     declaration must be a constant.

Return Value

     GS_SUCC   Successful.
     GS_COLI   Invalid color index.
     GS_CURS   Cursor size invalid.
     GS_CURO   Cursor origin invalid.
     GS_CURV   Cursor visible.
     GS_LONS   Invalid logical operation.

Related Information

     In this book:  "gscatt,"  "gsecur," and "gsmcur."