Tk_AllocCursorFromObj man page on UnixWare

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

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)

       char *
       Tk_NameOfCursor(display, cursor)

       Tk_FreeCursorFromObj(tkwin, objPtr)				       │

       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.

       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	 isn't │
					     cached.

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

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

       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 isn't 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
	      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 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 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  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.

       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 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 │
       doesn't	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 stan‐
       dard cursor data for the cursor's source bits, and mask points to stan‐
       dard  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 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_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
       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_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)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server UnixWare

List of man pages available for UnixWare

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