Tk_FreeCursor man page on BSDOS

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



Tk_GetCursor(3)	      Tk Library Procedures	  Tk_GetCursor(3)

_________________________________________________________________

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  cur-
					     sor;   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

Tk			       4.1				1

Tk_GetCursor(3)	      Tk Library Procedures	  Tk_GetCursor(3)

					     for cursor.

       Tk_Uid	       bg	   (in)	     Textual  description
					     of	 background color
					     for cursor.

       Display	       *display	   (in)	     Display  for   which
					     cursor   was   allo-
					     cated.

       Tk_Cursor       cursor	   (in)	     Opaque Tk identifier
					     for    cursor.    If
					     passed toTk_FreeCur-
					     sor,  must have been
					     returned	by   some
					     previous	call   to
					     Tk_GetCursor      or
					     Tk_GetCursorFrom-
					     Data.
_________________________________________________________________

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  cur-
       sor, and returns an opaque Tk identifier for a cursor cor-
       responding 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 follow-
       ing forms:

       name [fgColor [bgColor]]
	      Name is the name of a cursor in the standard X cur-
	      sor font, i.e., any of the names defined in cursor-
	      font.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 illus-
	      trations 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 spec-
	      ified, 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

Tk			       4.1				2

Tk_GetCursor(3)	      Tk Library Procedures	  Tk_GetCursor(3)

	      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 con-
	      flicts color cursors will always be loaded in pref-
	      erence 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 com-
	      puters.

       @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 Win-
	      dows computers.

       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 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).  Typi-
       cally,  the  arguments 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_GetCursor-
       FromData will return an identifier for the requested  cur-
       sor.   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			       4.1				3

Tk_GetCursor(3)	      Tk Library Procedures	  Tk_GetCursor(3)

       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    XCre-
       atePixmapCursor, 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  hex-
       adecimal	 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_NameOfCur-
       sor.  Also, this call is not portable except  for  cursors
       returned by Tk_GetCursor.

       When  a	cursor	returned by Tk_GetCursor or Tk_GetCursor-
       FromData 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_GetCur-
       sorFromData.   When  a cursor is no longer in use anywhere
       (i.e. it has been freed as many times as it has been  got-
       ten)  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_GetCursorFrom-
       Data consider only the immediate	 values	 of  their  argu-
       ments.	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			       4.1				4

[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server BSDOS

List of man pages available for BSDOS

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]
Tweet
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