.if n .pH ref.cursor @(#)cursor	40.1

.ig
imagen 8/31/89
docformat -c -s4 -dqm4 -p1 cursor
..
.SO mstr.hdr
.ds Lb Shapes
.\" turn off automatic hyphenation -- JHevelin (08-09-89)
.am RT
.nh
..
.\" BEGIN SHAPES------------------------------------------------
.if !"\*(Lb"Paint" \{\
.br
.BK "Shapes Reference Manual"
.CH "Cursor Object" "5"
.H 1 "Cursor Object"
.H 2 "Introduction"
.P
.nh
A cursor is a raster-like object whose image is
automatically managed by Shapes.
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 overlap planes,
if they exist.
.IX "cursor object"
.H 4 "NAME"
.P
Create_Cursor \- Creates a cursor object.
.IX "Create_Cursor"
.tm .CE U 3 "Create_Cursor" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Create_Cursor\f2(cursor, ras)\f1
.br
CURSOR cursor;
.br
RASTER ras;
.H 4 "DESCRIPTION"
.P
Creates a cursor and associates it with a raster.
Many cursors may exist at one time,
but only one cursor may be active on a screen raster.
The cursor image is automatically managed by Shapes.
When the origin is moved,
it is displayed at the new position and removed
from the old position.
The obscured portion of the screen is updated
when the cursor is moved.
.P
Immediately after creating the cursor,
you should set the following attributes in the
order set out here:

.br
CURS_IMAGE_RASTER
.br
CURS_MASK_RASTER
.br
CURS_RASTER
.P
It is also advised that you set the values of
CURS_COLOR and CUR_BACK_COLOR at this time,
although you may accept the defaults.
.P	
You should also query the value of CURS_NEED_CUES
at this time in order to determine whether or not
you need to set the cursor's raster attribute,
RAS_CURSOR_OVERLAP.
See CURS_NEED_CUES.
.P
The cursor created will be as high performance as possible,
given its size.
The cursor will use hardware support where possible,
and the cursor will exist in the overlay plane if
doing so increases performance.
.P
\f2cursor\f1
Specifies the cursor to be created.
.P
\f2ras\f1
Specifies the raster to which the cursor is assigned.
.H 4 "RETURNED VALUE"
.P
CURSOR
.H 4 "SEE ALSO"
.P
Destroy_Cursor
.br
RAS_CURSOR_OVERLAP
.br
CURSON_NEEDS_CUES
.H 4 "NAME"
.P
Destroy_Cursor \- Destroys a cursor and frees its resources.
.IX "Destroy_Cursor"
.tm .CE U 3 "Destroy_Cursor" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Destroy_Cursor\f2(cursor)\f1
.br
CURSOR cursor;
.H 4 "DESCRIPTION"
.P
Destroys the cursor object and frees its
resources if no other objects refer to the cursor.
.P
\f2cursor\f1
Specifies the cursor to be destroyed.
.H 4 "RETURNED VALUE"
.P
[None]
.H 4 "SEE ALSO"
.H 4 "NAME"
.P
Get_Cursor \- returns the setting of the specified cursor attribute.
.IX "Get_Cursor"
.tm .CE U 3 "Get_Cursor" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Get_Cursor\f2(cursor, attr)\f1
.br
CURSOR cursor;
.br
CURS_attr attr;
.H 4 "DESCRIPTION"
.P
Returns the setting of the specified attribute.
.P
\f2cursor\f1
Specifies the cursor for which the attribute
setting is to be returned.
.P
\f2attr\f1
Specifies the attribute for which the setting is
to be returned.
.H 4 "RETURNED VALUE"
.P
[None]
.H 4 "SEE ALSO"
.P
Set_Cursor
.H 4 "NAME"
.P
Set_Cursor \- Sets a cursor attribute.
.IX "Set_Cursor"
.tm .CE U 3 "Set_Cursor" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Set_Cursor\f2(cursor, attr, setting)\f1
.br
CURSOR cursor;
.br
CURS_attr attr;
.br
<attribute type> setting;
.H 4 "DESCRIPTION"
.P
Sets the specified attribute.
.P
If you want to change either the
CURS_IMAGE_RASTER or the CURS_MASK_RASTER after
you have set up the cursor object,
you should first disable the cursor by setting
the CURS_RASTER to NULL.
.P
\f2cursor\f1
Specifies the cursor for which the attribute is
to be set.
.P
\f2attr\f1
Specifies the attribute to be set.
.P
\f2setting\f1
Specifies the setting for the attribute.
.H 4 "RETURNED VALUE"
.P
[None]
.H 4 "SEE ALSO"
.P
Get_Cursor
.IX "Cursor Attributes"
.H 2 "Cursor Attributes"
.H 4 "NAME"
.P
CURS_BACK_COLOR
.IX "CURS_BACK_COLOR"
.tm .CE U 3 "CURS_BACK_COLOR" \n(PN
.H 4 "DESCRIPTION"
.P
Specifies the background color.
You may specify this color as either of type
COL_INDEX or COL_RGB.
This color is rendered for cursor image values of 0.
.P
If you specify an index color,
the color map associated with the cursor's
raster is used to determine the mapping from index to RGB.
The mapping is checked again at cursor render time:\ \&
the color rendered may be that which was
mapped when you set the background color.
.P
If you specify an RGB color,
it is used directly,
if the hardware permits.
.P
The only guarantee made for cursor color
behavior is that CURS_BACK_COLOR is always
different from CURS_COLOR.
.H 4 "RETURNED VALUE"
.P
COLOR *
.H 4 "SEE ALSO"
.P
CURS_COLOR
.IX "Cursor Attributes"
.H 4 "NAME"
.P
CURS_COLOR
.IX "CURS_COLOR"
.tm .CE U 3 "CURS_COLOR" \n(PN
.H 4 "DESCRIPTION"
.P
Specifies the foreground color.
You may specify this color as either of type
COL_INDEX or COL_RGB.
This color is rendered for cursor image values of 1
(one).
.P
If you specify an index color,
the color map associated with the cursor's
raster is used to determine the mapping from index to RGB.
The mapping is checked again at cursor render time:\ \&
the color rendered may be that which was
mapped when you set the foreground color.
.P
If you specify an RGB color,
it is used directly,
if the hardware permits.
.P
In the worst case for both RGB and indexed color,
CURS_COLOR is always different from CURS_BACK_COLOR.
This is the only guarantee made for cursor color behavior.
.H 4 "RETURNED VALUE"
.P
COLOR *
.H 4 "SEE ALSO"
.P
CURS_BACK_COLOR
.IX "Cursor Attributes"
.H 4 "NAME"
.P
CURS_IMAGE_RASTER
.IX "CURS_IMAGE_RASTER"
.tm .CE U 3 "CURS_IMAGE_RASTER" \n(PN
.H 4 "DESCRIPTION"
.P
The one-bit raster containing the image of the cursor.
Setting this attribute may cause updating of the
CURS_NEEDS_CUES attribute,
as rasters of certain sizes and shapes cannot be
handled in hardware.
.P
Set this attribute immediately after creating the cursor.
Once the attribute is set,
Shapes may alter the contents of the raster.
You may reclaim this raster for your own use by
setting this attribute to NULL again.
.P
This raster must be of the same dimensions as the
CURS_MASK_RASTER raster.
If you keep the dimensions of the raster less
than or equal to 32 by 32,
the performance can be improved with hardware assistance.
.H 4 "RETURNED VALUE"
.P
RASTER
.H 4 "SEE ALSO"
.P
Create_Cursor
.br
Create_Raster
.br
RAS_DEPTH
.br
Write_Raster
.IX "Cursor Attributes"
.H 4 "NAME"
.P
CURS_HOT_SPOT
.IX "CURS_HOT_SPOT"
.tm .CE U 3 "CURS_HOT_SPOT" \n(PN
.H 4 "DESCRIPTION"
.P
The offset of the cursor hot spot relative to the cursor origin.
The hot spot is the point that is displayed at the mouse location
when the cursor is tracked.
It gives a hint as to which area of the cursor is important.
.P
Some accelerators have a hardware cursor of limited size.
When a small hardware cursor is employed,
only the area around the cursor hot spot is visible.
Other parts of the cursor may not be displayed.
.H 4 "RETURNED VALUE"
.P
POINT_B2D *
.H 4 "SEE ALSO"
.P
CURS_ORG
.IX "Cursor Attributes"
.H 4 "NAME"
.P
CURS_MASK_RASTER
.IX "CURS_MASK_RASTER"
.tm .CE U 3 "CURS_MASK_RASTER" \n(PN
.H 4 "DESCRIPTION"
.P
The one-bit raster containing the clip mask of the cursor.
Setting this attribute may cause updating of the
CURS_NEEDS_CUES attribute,
as rasters of certain sizes and shapes cannot be
handled in hardware.
.P
Where the cursor mask contains 1 bits,
the cursor is rendered;
where it contains 0 bits,
the cursor image is ignored.
The cursor image is logically ANDed with the
cursor mask before being used.
.P
Set this attribute immediately after creating the cursor.
Once the attribute is set,
the contents of the raster are set.
You may reclaim this raster for your own use by
setting this attribute to NULL again.
.P
This raster must have the same dimensions as the
CURS_IMAGE_RASTER raster.
If you keep the dimensions of the raster less
than or equal to 32 by 32,
the performance can be improved with hardware assistance.
.H 4 "RETURNED VALUE"
.P
RASTER
.H 4 "SEE ALSO"
.P
Create_Cursor
.br
Create_Raster
.br
RAS_DEPTH
.br
Write_Raster
.IX "Cursor Attributes"
.H 4 "NAME"
.P
CURS_NEEDS_CUES
.IX "CURS_NEEDS_CUES"
.tm .CE U 3 "CURS_NEEDS_CUES" \n(PN
.H 4 "DESCRIPTION"
.P
Query this attribute to determine whether to
notify a screen raster when it is overlapped by a cursor.
Zero indicates the need for no notification.
This attribute cannot be set by the application.
.P
The setting is influenced by the CURS_MASK_RASTER
and CURS_IMAGE_RASTER size.
Typically if your device has hardware cursor support,
grids less than or equal to 32\|\(mu\|32 will not need
raster cues.
.P
The attribute is not valid until the cursor is
associated with a screen raster.
Changing the dimensions of CURS_MASK_RASTER or
CURS_IMAGE_RASTER requires that you query
CURS_NEED_CUES AGAIN.
.P
The following example is a test for whether the
cursor needs cues.
.SS
cursor = Create_Cursor();
Set_Cursor(cursor, CURS_IMAGE_RASTER, cursor1_image);
Set_Cursor(cursor, CURS_MASK_RASTER, cursor1_mask);

screen = Get_Cursor(cursor, CURS_RASTER_SCREEN);

Set_Cursor(cursor, CURS_RASTER, ras);

screen = Get_Cursor(cursor, CURS_RASTER_SCREEN);

Set_Raster(ras, RAS_CURSOR_OVERLAP,
    Get_Cursor(cursor, CURS_NEEDS_CUES));
.ft1
.SE
.H 4 "RETURNED VALUE"
.P
Integer
.H 4 "SEE ALSO"
.P
RAS_CURSOR_OVERLAP
.IX "Cursor Attributes"
.H 4 "NAME"
.P
CURS_ORG
.IX "CURS_ORG"
.tm .CE U 3 "CURS_ORG" \n(PN
.H 4 "DESCRIPTION"
.P
Specifies the origin of the cursor in the screen raster.
The cursor is rendered at this location.
.P
The origin indicates where CURS_IMAGE_RASTER is
displayed on the screen,
using CURS_MASK_RASTER as an enable plane.
The origin may be negative.
Before display, the cursor is clipped by the
CURS_RASTER raster clip shape.
.P
When the cursor is removed for rendering operations,
it is not redisplayed until the next cursor
position update occurs.
This may be an update to the same position.
.H 4 "RETURNED VALUE"
.P
POINT_B2D *
.H 4 "SEE ALSO"
.IX "Cursor Attributes"
.H 4 "NAME"
.P
CURS_RASTER
.IX "CURS_RASTER"
.tm .CE U 3 "CURS_RASTER" \n(PN
.H 4 "DESCRIPTION"
.P
Setting this attribute associates a cursor with a
particular screen raster.
A NULL setting removes the cursor from the screen
raster.
.P
Setting this attribute also updates the
CURS_NEEDS_CUES attribute and determines the
active cursor.
.P
On some devices,
multiple cursor rendering methods are supported,
and the method used can be controlled by the
application using this attribute.
For example,
in the case of a CG4 framebuffer,
if the root device of CURS_RASTER is
.PC "/dev/fb or /dev/cgfourX"
(where X is the UNIX minor device number),
the overlay and overlay enable planes are used
for cursor support.
If the root device of CURS_RASTER is
.PC "/dev/cgfourX_clr,"
the cursor is supported using the color planes.
The overlay plane is used alone whenever the root
device of CURS_RASTER is
.PC "/dev/cgfourX_ovl"
or
.PC "/dev/bwtwoX."
.H 4 "RETURNED VALUE"
.P
COLOR *
.H 4 "SEE ALSO"
.br \}
.\"  ENDIF SHAPES------------------------------------------------
