Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Tk_AllocCursorFromObj(3)     Tk	Library	Procedures    Tk_AllocCursorFromObj(3)

______________________________________________________________________________

NAME
       Tk_AllocCursorFromObj, Tk_GetCursor, Tk_GetCursorFromObj, Tk_GetCursor-
       FromData, Tk_NameOfCursor, Tk_FreeCursorFromObj,	Tk_FreeCursor -	 main-
       tain database of	cursors

SYNOPSIS
       #include	<tk.h>

       Tk_Cursor
       Tk_AllocCursorFromObj(interp, tkwin, objPtr)

       Tk_Cursor
       Tk_GetCursor(interp, tkwin, name)

       Tk_Cursor
       Tk_GetCursorFromObj(tkwin, objPtr)

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

ARGUMENTS
       Tcl_Interp *interp (in)		     Interpreter  to use for error re-
					     porting.

       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	corresponding  Tk_Cur-
					     sor.

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

       const char *source (in)		     Data for cursor cursor, in	 stan-
					     dard cursor format.

       const char *mask	(in)		     Data for mask cursor, in standard
					     cursor 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  al-
					     located.

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

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

       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 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.  Ap-
	      pendix B of "The X Window	System"	by Scheifler & Gettys has  il-
	      lustrations  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 supports all of the  X  cursors  and
	      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	resource.  The	appli-
	      cation 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 de-
	      scribing	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	Macin-
	      tosh or Windows computers.

       @sourceName
	      This form	only works on Windows, and will	load a Windows	system
	      cursor (.ani or .cur) from the file specified in sourceName.

       Tk_GetCursor  is	identical to Tk_AllocCursorFromObj except that the de-
       scription of the	cursor is specified with a string instead  of  an  ob-
       ject.   This  prevents  Tk_GetCursor  from caching the return value, so
       Tk_GetCursor is less efficient than Tk_AllocCursorFromObj.

       Tk_GetCursorFromObj returns the token for an existing cursor, 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 de-
       scriptions 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 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 ar-
       guments to Tk_GetCursorFromData are created by including	a cursor  file
       directly	 into the source code for a program, as	in the following exam-
       ple:
	      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 message 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	overhead, so the Tk procedures
       should generally	be used	in preference to Xlib procedures like XCreate-
       FontCursor  or  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  re-
       turned  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_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_GetCursor-
       FromData.

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

Tk				      8.1	      Tk_AllocCursorFromObj(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | BUGS | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tk_AllocCursorFromObj.tk85&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help