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)
Tcl_Interp *interp
(in) Tk_Window tkwin
(in) Tk_Uid nameId
(in) char *source
(in) char *mask
(in) int width
(in) int height
(in) int xHot
(in) int yHot
(in) Tk_Uid fg
(in) Tk_Uid bg
(in) Display *display
(in) Cursor cursor
(in) 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:
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
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.