GSMCAT(3g,L)                AIX Technical Reference                GSMCAT(3g,L)



-------------------------------------------------------------------------------
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 multicolor cursor for the GSL.  The gscmap
subroutine must initialize the color map before gsmcat can be called.

Only one cursor, either the multicolor 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
multicolor version of the cursor.  To change from the single-color cursor to
the multicolor cursor, erase the cursor with gsecur, then call the gsmcat
subroutine.

The multicolor 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 boundaries, any portion
beyond the origin that falls outside the frame buffer is clipped.  In addition,
a mask is provided 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



Processed November 7, 1990       GSMCAT(3g,L)                                 1

GSMCAT(3g,L)                AIX Technical Reference                GSMCAT(3g,L)



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 multicolor
                  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 multicolor
                  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 multicolor cursor pattern.  If
                  a bit is set (has a value of 1), the matching bit in the
                  pattern is applied to the underlying display 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 relative 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 application 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 on the PS/2:

                  1    AND
                  3    REPLACE
                  6    Exclusive-or
                  7    OR

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



Processed November 7, 1990       GSMCAT(3g,L)                                 2

GSMCAT(3g,L)                AIX Technical Reference                GSMCAT(3g,L)



There is no default cursor defined, so all cursor parameters 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."




































Processed November 7, 1990       GSMCAT(3g,L)                                 3