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.

     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
     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.

KEYWORDS
     cursor