GetCursor man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

Tk_GetCursor(3)		     Tk Library Procedures	       Tk_GetCursor(3)


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

       #include <tk.h>

       Tk_GetCursor(interp, tkwin, nameId)

       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)	     Interpreter  to  use  for	 error

       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 stan‐
					     dard 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

       Tk_Cursor       cursor	   (in)	     Opaque Tk identifier for  cursor.
					     If	 passed	 toTk_FreeCursor, must
					     have been returned by some previ‐
					     ous   call	  to  Tk_GetCursor  or

       These procedures manage a collection of cursors being used by an appli‐
       cation.	 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	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 illustra‐
	      tions 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 back‐
	      ground 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	 addi‐
	      tion,  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 Macin‐
	      tosh or Windows computers.

       Tk_GetCursorFromData  allows  cursors  to  be  created  from  in-memory
       descriptions  of their source and mask bitmaps.	Source points to stan‐
       dard bitmap data for the cursor's source bits, and mask points to stan‐
       dard  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 includ‐
       ing 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 cursor, such as when nameId refers to a non-existent file,
       then  None  is  returned	 and  an  error	 message  will	be  stored  in

       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 cre‐
       ating 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  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_GetCur‐
       sor or Tk_GetCursorFromData.  When a cursor is no longer	 in  use  any‐
       where  (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

       In  determining whether an existing cursor can be used to satisfy a new
       request, Tk_GetCursor and Tk_GetCursorFromData consider only the	 imme‐
       diate  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


Tk				      4.1		       Tk_GetCursor(3)

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net