Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

CentOS 7.0 - man page for tk_definebitmap (centos section 3)

Tk_AllocBitmapFromObj(3)	      Tk Library Procedures		 Tk_AllocBitmapFromObj(3)

_________________________________________________________________________________________________

NAME
       Tk_AllocBitmapFromObj,	Tk_GetBitmap,  Tk_GetBitmapFromObj,  Tk_DefineBitmap,  Tk_NameOf-
       Bitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, Tk_FreeBitmap - maintain database  of  sin-
       gle-plane pixmaps

SYNOPSIS
       #include <tk.h>

       Pixmap
       Tk_AllocBitmapFromObj(interp, tkwin, objPtr)

       Pixmap
       Tk_GetBitmap(interp, tkwin, info)

       Pixmap
       Tk_GetBitmapFromObj(tkwin, objPtr)

       int
       Tk_DefineBitmap(interp, name, source, width, height)

       const char *
       Tk_NameOfBitmap(display, bitmap)

       Tk_SizeOfBitmap(display, bitmap, widthPtr, heightPtr)

       Tk_FreeBitmapFromObj(tkwin, objPtr)

       Tk_FreeBitmap(display, bitmap)

ARGUMENTS
       Tcl_Interp *interp (in)		     Interpreter to use for error reporting; if NULL then
					     no error message is left after errors.

       Tk_Window tkwin (in)		     Token for window in which the bitmap will be used.

       Tcl_Obj *objPtr (in/out) 	     String value describes desired bitmap; internal  rep
					     will  be  modified to cache pointer to corresponding
					     Pixmap.

       const char *info (in)		     Same as  objPtr  except  description  of  bitmap  is
					     passed  as  a  string  and  resulting  Pixmap is not
					     cached.

       const char *name (in)		     Name for new bitmap to be defined.

       const char *source (in)		     Data for bitmap, in standard bitmap format.  Must be
					     stored  in  static  memory  whose	value  will never
					     change.

       int width (in)			     Width of bitmap.

       int height (in)			     Height of bitmap.

       int *widthPtr (out)		     Pointer to word to fill in with bitmap's width.

       int *heightPtr (out)		     Pointer to word to fill in with bitmap's height.

       Display *display (in)		     Display for which bitmap was allocated.

       Pixmap bitmap (in)		     Identifier    for	  a    bitmap	 allocated     by
					     Tk_AllocBitmapFromObj or Tk_GetBitmap.
_________________________________________________________________

DESCRIPTION
       These  procedures  manage  a  collection  of  bitmaps (one-plane pixmaps) being used by an
       application.  The procedures allow bitmaps to be  re-used  efficiently,	thereby  avoiding
       server overhead, and also allow bitmaps to be named with character strings.

       Tk_AllocBitmapFromObj  returns  a Pixmap identifier for a bitmap that matches the descrip-
       tion in objPtr and is suitable for use in tkwin.  It re-uses an existing bitmap, if possi-
       ble,  and  creates  a  new  one	otherwise.  ObjPtr's value must have one of the following
       forms:

       @fileName	   FileName must be the name of a file containing a bitmap description in
			   the standard X11 or X10 format.

       name		   Name  must  be  the name of a bitmap defined previously with a call to
			   Tk_DefineBitmap.  The following names are pre-defined by Tk:

			   error       The international "don't" symbol:  a circle with a  diago-
				       nal line across it.

			   gray75      75%  gray:  a checkerboard pattern where three out of four
				       bits are on.

			   gray50      50% gray: a checkerboard pattern where every other bit  is
				       on.

			   gray25      25%  gray:  a  checkerboard pattern where one out of every
				       four bits is on.

			   gray12      12.5% gray: a pattern where one-eighth of the bits are on,
				       consisting of every fourth pixel in every other row.

			   hourglass   An hourglass symbol.

			   info        A large letter "i".

			   questhead   The  silhouette	of  a human head, with a question mark in
				       it.

			   question    A large question-mark.

			   warning     A large exclamation point.

			   In addition, the following pre-defined names are available only on the
			   Macintosh platform:

			   document    A generic document.

			   stationery  Document stationery.

			   edition     The edition symbol.

			   application Generic application icon.

			   accessory   A desk accessory.

			   folder      Generic folder icon.

			   pfolder     A locked folder.

			   trash       A trash can.

			   floppy      A floppy disk.

			   ramdisk     A floppy disk with chip.

			   cdrom       A cd disk icon.

			   preferences A folder with prefs symbol.

			   querydoc    A database document icon.

			   stop        A stop sign.

			   note        A face with balloon words.

			   caution     A triangle with an exclamation point.

       Under  normal  conditions,  Tk_AllocBitmapFromObj  returns an identifier for the requested
       bitmap.	If an error occurs in creating the bitmap, such as when objPtr refers to  a  non-
       existent  file,	then  None is returned and an error message is left in interp's result if
       interp is not NULL. Tk_AllocBitmapFromObj caches information about  the	return	value  in
       objPtr,	which  speeds  up  future  calls  to procedures such as Tk_AllocBitmapFromObj and
       Tk_GetBitmapFromObj.

       Tk_GetBitmap is identical to Tk_AllocBitmapFromObj except that the description of the bit-
       map  is	specified  with  a  string instead of an object.  This prevents Tk_GetBitmap from
       caching the return value, so Tk_GetBitmap is less efficient than Tk_AllocBitmapFromObj.

       Tk_GetBitmapFromObj returns the token  for  an  existing  bitmap,  given  the  window  and
       description  used  to create the bitmap.  Tk_GetBitmapFromObj does not actually create the
       bitmap;	the  bitmap  must  already  have  been	created   with	 a   previous	call   to
       Tk_AllocBitmapFromObj or Tk_GetBitmap.  The return value is cached in objPtr, which speeds
       up future calls to Tk_GetBitmapFromObj with the same objPtr and tkwin.

       Tk_DefineBitmap associates a name with in-memory bitmap data so that the name can be  used
       in later calls to Tk_AllocBitmapFromObj or Tk_GetBitmap.  The nameId argument gives a name
       for the bitmap;	it must not previously have been used in a call to Tk_DefineBitmap.   The
       arguments source, width, and height describe the bitmap.  Tk_DefineBitmap normally returns
       TCL_OK; if an error occurs (e.g. a bitmap named nameId  has  already  been  defined)  then
       TCL_ERROR   is	returned   and	an  error  message  is	left  in  interp->result.   Note:
       Tk_DefineBitmap expects the memory pointed to by source	to  be	static:   Tk_DefineBitmap
       does not make a private copy of this memory, but uses the bytes pointed to by source later
       in calls to Tk_AllocBitmapFromObj or Tk_GetBitmap.

       Typically Tk_DefineBitmap is used by #include-ing a bitmap file directly into a C  program
       and then referencing the variables defined by the file.	For example, suppose there exists
       a file stip.bitmap, which was created by the bitmap program and contains  a  stipple  pat-
       tern.  The following code uses Tk_DefineBitmap to define a new bitmap named foo:
	      Pixmap bitmap;
	      #include "stip.bitmap"
	      Tk_DefineBitmap(interp, "foo", stip_bits,
		  stip_width, stip_height);
	      ...
	      bitmap = Tk_GetBitmap(interp, tkwin, "foo");
       This  code  causes  the bitmap file to be read at compile-time and incorporates the bitmap
       information into the program's executable image.  The same bitmap file could  be  read  at
       run-time using Tk_GetBitmap:
	      Pixmap bitmap;
	      bitmap = Tk_GetBitmap(interp, tkwin, "@stip.bitmap");
       The  second  form is a bit more flexible (the file could be modified after the program has
       been compiled, or a different string could be provided to read a different file),  but  it
       is a little slower and requires the bitmap file to exist separately from the program.

       Tk  maintains a database of all the bitmaps that are currently in use.  Whenever possible,
       it will return an existing bitmap rather than creating a new one.  When	a  bitmap  is  no
       longer  used,  Tk  will	release it automatically.  This approach can substantially reduce
       server overhead, so Tk_AllocBitmapFromObj and Tk_GetBitmap should  generally  be  used  in
       preference to Xlib procedures like XReadBitmapFile.

       The  bitmaps  returned  by  Tk_AllocBitmapFromObj  and Tk_GetBitmap are shared, so callers
       should never modify them.  If a bitmap must be modified dynamically,  then  it  should  be
       created by calling Xlib procedures such as XReadBitmapFile or XCreatePixmap directly.

       The  procedure  Tk_NameOfBitmap is roughly the inverse of Tk_GetBitmap.	Given an X Pixmap
       argument, it returns the textual description that was passed to Tk_GetBitmap when the bit-
       map  was  created.   Bitmap  must  have	been  the  return  value  from a previous call to
       Tk_AllocBitmapFromObj or Tk_GetBitmap.

       Tk_SizeOfBitmap returns the dimensions of its bitmap argument in the words pointed  to  by
       the widthPtr and heightPtr arguments.  As with Tk_NameOfBitmap, bitmap must have been cre-
       ated by Tk_AllocBitmapFromObj or Tk_GetBitmap.

       When a bitmap is no longer needed, Tk_FreeBitmapFromObj or Tk_FreeBitmap should be  called
       to  release it.	For Tk_FreeBitmapFromObj the bitmap to release is specified with the same
       information used to create it; for Tk_FreeBitmap the bitmap to release is  specified  with
       its   Pixmap  token.   There  should  be  exactly  one  call  to  Tk_FreeBitmapFromObj  or
       Tk_FreeBitmap for each call to Tk_AllocBitmapFromObj or Tk_GetBitmap.

BUGS
       In determining whether  an  existing  bitmap  can  be  used  to	satisfy  a  new  request,
       Tk_AllocBitmapFromObj  and  Tk_GetBitmap  consider  only the immediate value of the string
       description.  For example, when a file name is passed to Tk_GetBitmap,  Tk_GetBitmap  will
       assume  it  is safe to re-use an existing bitmap 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.

KEYWORDS
       bitmap, pixmap

Tk					       8.1			 Tk_AllocBitmapFromObj(3)


All times are GMT -4. The time now is 04:28 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password