*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> Tk/getbitmap (3)              


Tk_GetBitmap(3Tk)					     Tk_GetBitmap(3Tk)

NAME    [Toc]    [Back]

     Tk_GetBitmap, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap,
     Tk_FreeBitmap, Tk_GetBitmapFromData - maintain database of	single-plane

SYNOPSIS    [Toc]    [Back]

     #include <tk.h>

     Tk_GetBitmap(interp, tkwin, id)

     Tk_DefineBitmap(interp, nameId, source, width, height)

     Tk_NameOfBitmap(display, bitmap)

     Tk_SizeOfBitmap(display, bitmap, widthPtr,	heightPtr)

     Tk_FreeBitmap(display, bitmap)

ARGUMENTS    [Toc]    [Back]

     Tcl_Interp	     *interp	 (in)	   Interpreter to use for error

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

     Tk_Uid	     id		 (in)	   Description of bitmap;  see below
					   for possible	values.

     Tk_Uid	     *nameId	 (in)	   Name	for new	bitmap to be defined.

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

     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

									Page 1

Tk_GetBitmap(3Tk)					     Tk_GetBitmap(3Tk)

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

DESCRIPTION    [Toc]    [Back]

     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_GetBitmap takes	as argument a Tk_Uid describing	a bitmap.  It returns
     a Pixmap identifier for a bitmap corresponding to the description.	 It
     re-uses an	existing bitmap, if possible, and creates a new	one otherwise.
     At	present, id 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 diagonal line across	it.

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

			 gray25	     25% gray: a pattern where 25% of the bits
				     are on, consisting	of all the bit
				     positions that can	be reached by a	chess
				     knight starting at	(0,0).

			 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.

     Under normal conditions, Tk_GetBitmap returns an identifier for the
     requested bitmap.	If an error occurs in creating the bitmap, such	as
     when id refers to a non-existent file, then None is returned and an error
     message is	left in	interp->result.

     Tk_DefineBitmap associates	a name with in-memory bitmap data so that the
     name can be used in later calls to	Tk_GetBitmap.  The nameId argument
     gives a name for the bitmap;  it must not previously have been used in a

									Page 2

Tk_GetBitmap(3Tk)					     Tk_GetBitmap(3Tk)

     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 doesn't make a private copy of this memory, but
     uses the bytes pointed to by source later in calls	to 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 pattern.  The	following code
     uses Tk_DefineBitmap to define a new bitmap named foo:
	  Pixmap bitmap;
	  #include "stip.bitmap"
	  Tk_DefineBitmap(interp, Tk_GetUid("foo"), stip_bits,
			  stip_width, stip_height);
	  bitmap = Tk_GetBitmap(interp,	tkwin, Tk_GetUid("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, Tk_GetUid("@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_GetBitmap 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.  This approach	can substantially reduce server
     overhead, so Tk_GetBitmap should generally	be used	in preference to Xlib
     procedures	like XReadBitmapFile.

     The bitmaps returned by 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	id that	was passed to
     Tk_GetBitmap when the bitmap was created.	Bitmap must have been the
     return value from a previous call to 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 created by Tk_GetBitmap.

     When a bitmap returned by Tk_GetBitmap is no longer needed, Tk_FreeBitmap
     should be called to release it.  There should be exactly one call to
     Tk_FreeBitmap for each call to Tk_GetBitmap.  When	a bitmap is no longer

									Page 3

Tk_GetBitmap(3Tk)					     Tk_GetBitmap(3Tk)

     in	use anywhere (i.e. it has been freed as	many times as it has been
     gotten) Tk_FreeBitmap will	release	it to the X server and delete it from
     the database.

BUGS    [Toc]    [Back]

     In	determining whether an existing	bitmap can be used to satisfy a	new
     request, Tk_GetBitmap considers only the immediate	value of its id
     argument.	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    [Toc]    [Back]

     bitmap, pixmap

									PPPPaaaaggggeeee 4444
[ Back ]
 Similar pages
Name OS Title
getfontstr IRIX maintain database of fonts
getcolor IRIX maintain database of colors
getcursor IRIX maintain database of cursors
getcolor IRIX maintain database of colors
getcursor IRIX maintain database of cursors
getgc IRIX maintain database of read-only graphics contexts
getpixmap IRIX allocate and free pixmaps
editmap FreeBSD query and edit single records in database maps for sendmail
glClipPlane Tru64 specify a plane against which all geometry is clipped
clipplane IRIX specify a plane against which all geometry is clipped
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service