*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> standard/getcursor (3)              


Tk_GetCursor(3Tk)					     Tk_GetCursor(3Tk)

NAME    [Toc]    [Back]

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

SYNOPSIS    [Toc]    [Back]

     #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)

ARGUMENTS    [Toc]    [Back]

     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 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
Tk_GetCursor(3Tk)					     Tk_GetCursor(3Tk)

     Cursor	     cursor	 (in)	   X identifier	for cursor.  If	passed
					   toTk_FreeCursor, must have been
					   returned by some previous call to
					   Tk_GetCursor	or

DESCRIPTION    [Toc]    [Back]

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

     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	hotspot
 (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

									Page 2

Tk_GetCursor(3Tk)					     Tk_GetCursor(3Tk)

     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-

     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

BUGS    [Toc]    [Back]

     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.

									Page 3

Tk_GetCursor(3Tk)					     Tk_GetCursor(3Tk)

KEYWORDS    [Toc]    [Back]


									Page 4

getcursor(3G)							 getcursor(3G)

NAME    [Toc]    [Back]

     getcursor - returns the cursor characteristics

C SPECIFICATION    [Toc]    [Back]

     void getcursor(index, color, wtm, b)
     short *index;
     Colorindex	*color,	*wtm;
     Boolean *b;

PARAMETERS    [Toc]    [Back]

     index   expects a pointer to the location into which the system writes
	     the index of the current cursor.  The cursor index	is an index
	     into a table of cursor bitmaps.

     color   is	an obsolete parameter.	It is retained for compatibility with
	     previous releases.

     wtm     is	an obsolete parameter.	It is retained for compatibility with
	     previous releases.

     b	     expects a pointer to the location into which the system returns a
	     boolean indicating	if the cursor in visible in the	current

DESCRIPTION    [Toc]    [Back]

     getcursor returns the index of the	current	cursor and a boolean value
     indicating	if the cursor is visible in the	current	window.	 (The cursor
     will not be visible if cursoff has	been called.)

SEE ALSO    [Toc]    [Back]

     curson, defcursor,	setcursor

NOTE    [Toc]    [Back]

     This routine is available only in immediate mode.

									PPPPaaaaggggeeee 1111
[ Back ]
 Similar pages
Name OS Title
getcolor IRIX maintain database of colors
getfontstr IRIX maintain database of fonts
getcolor IRIX maintain database of colors
getgc IRIX maintain database of read-only graphics contexts
getbitmap IRIX maintain database of single-plane pixmaps
VkCursorList IRIX Support lists of cursors that can be used for animation
make FreeBSD maintain program dependencies
make OpenBSD maintain program dependencies
bgicons IRIX maintain icons on the desktop background
maintgeom IRIX maintain geometry of one window relative to another
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service