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 char *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 or X10  for-

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