'\"!  tbl | mmdoc
.if n .pH arch.cursor @(#)cursor	40.1
.ig
imaged dc 8/30/89
docformat -c -s4 -dqm4 fn
..
.\" turn off automatic hyphenation -- JHevelin (08-09-89)
.am RT
.nh
..
.ds S) Shapes
.BK "Shapes Internal Architecture"
.CH "The CURSOR Object" "9"
.H 1 "The CURSOR Object" 
.H 2 "Introduction"
.nh
A cursor is a raster-like object whose image is
automatically managed by \*(S).
When the origin is updated,
the image is moved to the new position and
removed from the original location.
If the cursor obscures one or more
of the screen rasters,
the raster is restored when the cursor is moved.
.P
The cursor object can take advantage of hardware cursor support
and displays that provide it.
It can also be accelerated by allowing it to use overlay planes,
if they exist.
.H 2 "Cursor Attributes"
The external cursor attributes are documented in the
\f2Shapes Reference Manual\f1.
This section discusses the internal attributes that are
used in the implementation of the generic cursor object.
All cursor attributes are defined in include/sh_CURSOR.ah.
.PC
RASTER       CURS_RASTER;
COLOR        CURS_COLOR;
COLOR        CURS_BACK_COLOR;
COORD_2D     CURS_ORG;
COORD_2D     CURS_HOT_SPOT;
RASTER       CURS_IMAGE_RASTER;
RASTER       CURS_MASK_RASTER;
unsigned int CURS_NEEDS_CUES : 1;
unsigned int curs_is_valid : 1;
unsigned int curs_backing_is_valid : 1;
unsigned int curs_method : 2;
unsigned int curs_mono_color : 1;
unsigned int curs_mono_back_color : 1;
RASTER       curs_backing_raster;
SHAPE        curs_clip_shape;
COLOR        curs_color_rgb;
COLOR        curs_back_color_rgb;
COORD_2D     curs_prev_org;
COORD_2D     curs_dim;
.SF
.H 2 curs_is_valid
.P
A cursor becomes invalid whenever the mask raster,
image raster, or display raster are updated.
This flag is checked in Display_Cursor.
.H 2 curs_backing_is_valid
.P
This flag indicates that the backing raster needs to be reallocated.
Reallocation is necessary whenever the
size of the image or mask raster changes. 
.H 2 curs_method
.P
Indicates how the cursor is to be implemented.
.TB "Cursor Options"
.TS
box;
cBI cBI
l | l.
Option	Description
=
CURS_GENERIC	Render cursor into the same framebuffer
	the window system is using.
_
CURS_OVERLAY	Render into the overlay plane; the window system
	is assumed to not be using the overlay plane but
	the normal planes of the framebuffer.
_
CURS_HARDWARE	Cursor is handled by hardware.
.TE
.H 2 "curs_mono_color, curs_mono_back_color"
.P
The values of these are derived from either CURS_COLOR or
CURS_BACK_COLOR, whichever was set more recently,
such that they are always opposites.
.H 2 curs_backing_raster
.P
A raster representing what was in the display raster prior
to the cursor being rendering.
Once the cursor is moved, the backing raster is copied
back in to repair the damage the cursor caused.
Its use is only necessary for generic and overlay cursors.
.H 2 curs_clip_shape
.P
This shape represents the intersection between the raster
clip shapes and the cursor's mask raster's clip shape.
It is updated with every cursor display.
.H 2 "curs_color_rgb, curs_back_color_rgb"
.P
These variables store the values of the cursor's
foreground and background colors.
They are guaranteed to be different from each other.
When the user sets a new color,
\*(S) looks at the color map
to determine its RGB values and places that RGB value
in these variables.
.H 2 curs_prev_org
.P
Describes the position to which the
curs_back_raster should be restored when CURS_ORG
is updated.
.H 2 curs_dim
.P
Dimension of the cursor in x and y, representing the
maximum in each dimension of the mask and image
raster dimensions.
.H 2 "Cursor Operators"
The calling conventions of the external cursor operators
are documented in the
\f2Shapes Reference Manual\f1.
This section discusses the implementation of these operators,
assuming the reader is familiar with their behavior.
All cursor operators are defined in include/sh_CURSOR.h.
.P
.H 2 Install_Cursor
.P
This is called if the background raster needs to
be re-allocated,
a new CURS_RASTER has been selected,
or image or mask rasters change.
.P
It determines the most appropriate rendering method
(see curs_method) for the cursor, given its current attributes.
If a backing raster is needed,
one is created and initialized.
.H 2 Remove_Cursor
.P
This is called whenever the cursor is pulled down,
such as when the CURS_RASTER is set to a new raster,
prior to moving the cursor to a new location,
or when a new image or mask raster is set.
.P
Remove_Cursor removes the cursor from the current location
and restores the backing raster, if appropriate. 
.H 2 Display_Raster
.P
Display_Raster is called whenever the cursor origin is moved.
It does the following:
.BL
.LI
Removes the current cursor.
.LI
Saves to the backing raster a rectangle
the size of curs_dims with the left corner at CURS_ORG.
.LI
Renders the cursor into the new position.
.LE
.P
