Tk_GetCursor(3Tk)Tk_GetCursor(3Tk)NAME
Tk_GetCursor, Tk_GetCursorFromData, Tk_NameOfCursor, Tk_FreeCursor -
maintain database of cursors
SYNOPSIS
#include <tk.h>
Cursor
Tk_GetCursor(interp, tkwin, nameId)
Cursor
Tk_GetCursorFromData(interp, tkwin, source, mask, width, height,
xHot, yHot, fg, bg)
char *
Tk_NameOfCursor(display, cursor)
Tk_FreeCursor(display, cursor)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter to use for error
reporting.
Tk_Window tkwin (in) Token for window in which the
cursor will be used.
Tk_Uid nameId (in) Description of cursor; see below
for possible values.
char *source (in) Data for cursor bitmap, in standard
bitmap format.
char *mask (in) Data for mask bitmap, in standard
bitmap format.
int width (in) Width of source and mask. |
int height (in) Height of source and mask. |
int xHot (in) X-location of cursor hot-spot. |
int yHot (in) Y-location of cursor hot-spot. |
Tk_Uid fg (in) Textual description of foreground
color for cursor.
Tk_Uid bg (in) Textual description of background
color for cursor.
Display *display (in) Display for which cursor was
allocated.
Page 1
Tk_GetCursor(3Tk)Tk_GetCursor(3Tk)
Cursor cursor (in) X identifier for cursor. If passed
toTk_FreeCursor, must have been
returned by some previous call to
Tk_GetCursor or
Tk_GetCursorFromData.
DESCRIPTION
These procedures manage a collection of cursors being used by an
application. The procedures allow cursors to be re-used efficiently,
thereby avoiding server overhead, and also allow cursors to be named with
character strings (actually Tk_Uids).
Tk_GetCursor takes as argument a Tk_Uid describing a cursor, and returns
the X identifier for a cursor corresponding to the description. It re-
uses an existing cursor if possible and creates a new one otherwise.
NameId must be a standard Tcl list with one of the following forms:
name [fgColor [bgColor]]
Name is the name of a cursor in the standard X cursor font, i.e.,
any of the names defined in cursorfont.h, without the XC_. Some
example values are X_cursor, hand2, or left_ptr. Appendix B of
``The X Window System'' by Scheifler & Gettys has illustrations
showing what each of these cursors looks like. If fgColor and
bgColor are both specified, they give the foreground and background
colors to use for the cursor (any of the forms acceptable to
Tk_GetColor may be used). If only fgColor is specified, then there
will be no background color: the background will be transparent.
If no colors are specified, then the cursor will use black for its
foreground color and white for its background color.
@sourceName maskName fgColor bgColor
In this form, sourceName and maskName are the names of files
describing bitmaps for the cursor's source bits and mask. Each file
must be in standard X11 or X10 bitmap format. FgColor and bgColor
indicate the colors to use for the cursor, in any of the forms
acceptable to Tk_GetColor.
@sourceName fgColor
This form is similar to the one above, except that the source is
used as mask also. This means that the cursor's background is
transparent.
Tk_GetCursorFromData allows cursors to be created from in-memory
descriptions of their source and mask bitmaps. Source points to standard
bitmap data for the cursor's source bits, and mask points to standard
bitmap data describing which pixels of source are to be drawn and which
are to be considered transparent. Width and height give the dimensions
of the cursor, xHot and yHot indicate the location of the cursor's hot-
spot (the point that is reported when an event occurs), and fg and bg
describe the cursor's foreground and background colors textually (any of
the forms suitable for Tk_GetColor may be used). Typically, the
Page 2
Tk_GetCursor(3Tk)Tk_GetCursor(3Tk)
arguments to Tk_GetCursorFromData are created by including a cursor file
directly into the source code for a program, as in the following example:
Cursor cursor;
#include "source.cursor"
#include "mask.cursor"
cursor = Tk_GetCursorFromData(interp, tkwin, source_bits,
mask_bits, source_width, source_height, source_x_hot,
source_y_hot, Tk_GetUid("red"), Tk_GetUid("blue"));
Under normal conditions, Tk_GetCursor and Tk_GetCursorFromData will
return an identifier for the requested cursor. If an error occurs in
creating the cursor, such as when nameId refers to a non-existent file,
then None is returned and an error message will be stored in interp-
>result.
Tk_GetCursor and Tk_GetCursorFromData maintain a database of all the
cursors they have created. Whenever possible, a call to Tk_GetCursor or
Tk_GetCursorFromData will return an existing cursor rather than creating
a new one. This approach can substantially reduce server overhead, so
the Tk procedures should generally be used in preference to Xlib
procedures like XCreateFontCursor or XCreatePixmapCursor, which create a
new cursor on each call.
The procedure Tk_NameOfCursor is roughly the inverse of Tk_GetCursor. If
its cursor argument was created by Tk_GetCursor, then the return value is
the nameId argument that was passed to Tk_GetCursor to create the cursor.
If cursor was created by a call to Tk_GetCursorFromData, or by any other
mechanism, then the return value is a hexadecimal string giving the X
identifier for the cursor. Note: the string returned by Tk_NameOfCursor
is only guaranteed to persist until the next call to Tk_NameOfCursor.
When a cursor returned by Tk_GetCursor or Tk_GetCursorFromData is no
longer needed, Tk_FreeCursor should be called to release it. There
should be exactly one call to Tk_FreeCursor for each call to Tk_GetCursor
or Tk_GetCursorFromData. When a cursor is no longer in use anywhere
(i.e. it has been freed as many times as it has been gotten)
Tk_FreeCursor will release it to the X server and remove it from the
database.
BUGS
In determining whether an existing cursor can be used to satisfy a new
request, Tk_GetCursor and Tk_GetCursorFromData consider only the
immediate values of their arguments. For example, when a file name is
passed to Tk_GetCursor, Tk_GetCursor will assume it is safe to re-use an
existing cursor created from the same file name: it will not check to
see whether the file itself has changed, or whether the current directory
has changed, thereby causing the name to refer to a different file.
Similarly, Tk_GetCursorFromData assumes that if the same source pointer
is used in two different calls, then the pointers refer to the same data;
it does not check to see if the actual data values have changed.
Page 3
Tk_GetCursor(3Tk)Tk_GetCursor(3Tk)KEYWORDS
cursor
Page 4
