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

FreeBSD Manual Pages


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


       Tk_AllocBitmapFromObj,	 Tk_GetBitmap,	 Tk_GetBitmapFromObj,	Tk_De-
       fineBitmap,  Tk_NameOfBitmap,  Tk_SizeOfBitmap,	 Tk_FreeBitmapFromObj,
       Tk_FreeBitmap - maintain	database of single-plane pixmaps

       #include	<tk.h>

       Tk_AllocBitmapFromObj(interp, tkwin, objPtr)

       Tk_GetBitmap(interp, tkwin, info)

       Tk_GetBitmapFromObj(tkwin, objPtr)

       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)

       Tcl_Interp *interp (in)		     Interpreter  to use for error re-
					     porting; 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 mod-
					     ified to cache pointer to	corre-
					     sponding Pixmap.

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

       const char *name	(in)		     Name for new  bitmap  to  be  de-

       const void *source (in)		     Data for bitmap, in standard bit-
					     map 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  al-

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

       These procedures	manage a collection of bitmaps (one-plane pixmaps) be-
       ing 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 description in objPtr and is	suitable for use in tkwin.  It
       re-uses an existing bitmap, if possible,	and creates a new  one	other-
       wise.  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 format.

       name		   Name	must be	the name of a  bitmap  defined	previ-
			   ously  with a call to Tk_DefineBitmap.  The follow-
			   ing names are pre-defined by	Tk:

			   error       The international  "don't"  symbol:   a
				       circle with a diagonal 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  re-
       turned 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_Al-
       locBitmapFromObj	and Tk_GetBitmapFromObj.

       Tk_GetBitmap is identical to Tk_AllocBitmapFromObj except that the  de-
       scription  of  the  bitmap is specified with a string instead of	an ob-
       ject.  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_Get-
       Bitmap.	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  nor-
       mally  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  mes-
       sage  is	 left  in interpreter interp's 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  di-
       rectly  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 pattern.  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	incor-
       porates	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  af-
       ter  the	program	has been compiled, or a	different string could be pro-
       vided 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	creat-
       ing a new one.  When a bitmap is	no longer used,	Tk will	release	it au-
       tomatically.  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 modi-
       fied 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 bitmap	was created.  Bitmap must have
       been the	return value from a previous call to Tk_AllocBitmapFromObj  or

       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 created 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_Al-
       locBitmapFromObj	or Tk_GetBitmap.

       In determining whether an existing bitmap can be	used to	satisfy	a  new
       request,	Tk_AllocBitmapFromObj and Tk_GetBitmap consider	only the imme-
       diate 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 cur-
       rent directory has changed, thereby causing the name to refer to	a dif-
       ferent file.

       bitmap, pixmap

Tk				      8.1	      Tk_AllocBitmapFromObj(3)


Want to link to this manual page? Use this URL:

home | help