Tk_AllocCursorFromObj(3Tk Library ProcedureTk_AllocCursorFromObj(3)



     Tk_AllocCursorFromObj,  Tk_GetCursor,   Tk_GetCursorFromObj,
     Tk_GetCursorFromData, Tk_NameOfCursor, Tk_FreeCursorFromObj,
     Tk_FreeCursor - maintain database of cursors


     #include <tk.h>

     Tk_AllocCursorFromObj(interp, tkwin, objPtr)

     Tk_GetCursor(interp, tkwin, name)

     Tk_GetCursorFromObj(tkwin, objPtr)

     Tk_GetCursorFromData(interp, tkwin, source, mask, width, height, xHot, yHot, fg, bg)

     const char *
     Tk_NameOfCursor(display, cursor)

     Tk_FreeCursorFromObj(tkwin, objPtr)

     Tk_FreeCursor(display, cursor)


     Tcl_Interp *interp (in)               Interpreter to use for
                                           error reporting.

     Tk_Window tkwin (in)                  Token  for  window  in
                                           which  the cursor will
                                           be used.

     Tcl_Obj *objPtr (in/out)              Description of cursor;
                                           see below for possible
                                           values.  Internal  rep
                                           will  be  modified  to
                                           cache    pointer    to

     char *name (in)                       Same as objPtr  except
                                           description  of cursor
                                           is passed as a  string
                                           and          resulting
                                           Tk_Cursor    is    not

Tk                      Last change: 8.1                        1

Tk_AllocCursorFromObj(3Tk Library ProcedureTk_AllocCursorFromObj(3)

     const char *source (in)               Data for  cursor  cur-
                                           sor,  in standard cur-
                                           sor format.

     const char *mask (in)                 Data for mask  cursor,
                                           in   standard   cursor

     int width (in)                        Width  of  source  and

     int height (in)                       Height of  source  and

     int xHot (in)                         X-location  of  cursor

     int yHot (in)                         Y-location  of  cursor

     Tk_Uid fg (in)                        Textual description of
                                           foreground  color  for

     Tk_Uid bg (in)                        Textual description of
                                           background  color  for

     Display *display (in)                 Display for which cur-
                                           sor was allocated.

     Tk_Cursor cursor (in)                 Opaque  Tk  identifier
                                           for cursor.  If passed
                                           to Tk_FreeCursor, must
                                           have  been returned by
                                           some previous call  to
                                           Tk_GetCursor        or


     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.

     Tk_AllocCursorFromObj takes as argument an object describing
     a  cursor,  and returns an opaque Tk identifier for a cursor
     corresponding to the description.  It  re-uses  an  existing
     cursor   if  possible  and  creates  a  new  one  otherwise.
     Tk_AllocCursorFromObj caches information  about  the  return

Tk                      Last change: 8.1                        2

Tk_AllocCursorFromObj(3Tk Library ProcedureTk_AllocCursorFromObj(3)

     value  in objPtr, which speeds up future calls to procedures
     such as Tk_AllocCursorFromObj and Tk_GetCursorFromObj. If an
     error  occurs  in  creating  the cursor, such as when objPtr
     refers to a non-existent file, then None is returned and  an
     error message will be stored in interp's result if interp is
     not NULL.  ObjPtr must contain 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
          cursor,   i.e.,   any   of   the   names   defined   in
          cursorcursor.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  tran-
          sparent.   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 supports all of the X  cur-
          sors  and will also accept any of the standard Mac cur-
          sors  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 resource.  The application
          and all its open dynamic library's resource files  will
          be  searched  for  the named cursor.  If there are con-
          flicts color cursors will always be loaded  in  prefer-
          ence to black and white cursors.

     @sourceName maskName fgColor bgColor
          In this form, sourceName and maskName are the names  of
          files  describing  cursors for the cursor's source bits
          and mask.  Each file must be in  standard  X11  or  X10
          cursor 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-


Tk                      Last change: 8.1                        3

Tk_AllocCursorFromObj(3Tk Library ProcedureTk_AllocCursorFromObj(3)

          This form only works on Windows, and will load  a  Win-
          dows  system cursor (.ani or .cur) from the file speci-
          fied in sourceName.

     Tk_GetCursor is identical  to  Tk_AllocCursorFromObj  except
     that  the  description  of  the  cursor  is specified with a
     string instead of an  object.   This  prevents  Tk_GetCursor
     from caching the return value, so Tk_GetCursor is less effi-
     cient than Tk_AllocCursorFromObj.

     Tk_GetCursorFromObj returns the token for an  existing  cur-
     sor,  given  the  window  and description used to create the
     cursor.  Tk_GetCursorFromObj does not  actually  create  the
     cursor;  the  cursor  must  already have been created with a
     previous call to Tk_AllocCursorFromObj or Tk_GetCursor.  The
     return  value  is  cached  in objPtr, which speeds up future
     calls to Tk_GetCursorFromObj with the same objPtr and tkwin.

     Tk_GetCursorFromData allows cursors to be created  from  in-
     memory  descriptions  of  their  source  and  mask  cursors.
     Source points to  standard  cursor  data  for  the  cursor's
     source  bits,  and  mask  points  to  standard  cursor  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_GetCursorFromData will return  an
     identifier  for the requested cursor.  If an error occurs in
     creating the cursor then None is returned and an error  mes-
     sage will be stored in interp's result.

     Tk_AllocCursorFromObj,           Tk_GetCursor,           and
     Tk_GetCursorFromData  maintain a database of all the cursors
     they  have  created.    Whenever   possible,   a   call   to
     Tk_AllocCursorFromObj, Tk_GetCursor, or Tk_GetCursorFromData
     will return an existing cursor rather than  creating  a  new
     one.   This  approach  can substantially reduce server over-
     head, so the Tk  procedures  should  generally  be  used  in
     preference  to  Xlib  procedures  like  XCreateFontCursor or

Tk                      Last change: 8.1                        4

Tk_AllocCursorFromObj(3Tk Library ProcedureTk_AllocCursorFromObj(3)

     XCreatePixmapCursor, which create a new cursor on each call.
     The  Tk  procedures  are  also more portable than the lower-
     level X procedures.

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

     When   a   cursor   returned    by    Tk_AllocCursorFromObj,
     Tk_GetCursor,  or  Tk_GetCursorFromData is no longer needed,
     Tk_FreeCursorFromObj or Tk_FreeCursor should  be  called  to
     release  it.  For Tk_FreeCursorFromObj the cursor to release
     is specified with the same information used  to  create  it;
     for  Tk_FreeCursor  the  cursor to release is specified with
     its Tk_Cursor token.  There should be exactly  one  call  to
     Tk_FreeCursor   for   each  call  to  Tk_AllocCursorFromObj,
     Tk_GetCursor, or Tk_GetCursorFromData.


     In determining whether an existing cursor  can  be  used  to
     satisfy  a new request, Tk_AllocCursorFromObj, 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 caus-
     ing 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.



Tk                      Last change: 8.1                        5

Man(1) output converted with man2html