tk4.2 C API - GetCursor






NAME

     Tk_GetCursor,     Tk_GetCursorFromData,     Tk_NameOfCursor,
     Tk_FreeCursor - maintain database of cursors


SYNOPSIS

     #include <tk.h>

     Tk_Cursor
     Tk_GetCursor(interp, tkwin, nameId)

     Tk_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  bit-
                                           map,  in standard bit-
                                           map 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 cur-
                                           sor was allocated.

     Tk_Cursor       cursor      (in)      Opaque  Tk  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 an opaque Tk identifier for a cursor correspond-
     ing 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 Sys-
          tem'' 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.

          The Macintosh version of Tk also supports all of the  X
          cursors.   Tk  on  the  Mac will also accept any of the
          standard Mac cursors including ibeam, crosshair, watch,
          plus,  and  arrow.  In addition, Tk will load Macintosh
          cursor resources of the types  crsr  (color)  and  CURS
          (black  and  white) by the name of the of the resource.
          The application and  all  its  open  dynamic  library's
          resource  files  will be searched for the named cursor.
          If there are conflicts color  cursors  will  always  be
          loaded in preference to black and white cursors.

     @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.  This form of the command will not work
          on Macintosh or Windows computers.

     @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.  This form  of  the
          command  will  not work on Macintosh or Windows comput-
          ers.

     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  loca-
     tion  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 argu-
     ments  to  Tk_GetCursorFromData  are  created by including a
     cursor file directly into the source code for a program,  as
     in the following example:
          Tk_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  cur-
     sor, 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.  Also,  this
     call   is  not  portable  except  for  cursors  returned  by
     Tk_GetCursor.

     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 dif-
     ferent calls, then the pointers refer to the same data;   it
     does  not  check  to  see  if  the  actual  data values have
     changed.



KEYWORDS

     cursor