GetBitmap man page on DigitalUNIX

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

Tk_GetBitmap(3)		     Tk Library Procedures	       Tk_GetBitmap(3)

______________________________________________________________________________

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

SYNOPSIS
       #include <tk.h>

       Pixmap
       Tk_GetBitmap(interp, tkwin, id)

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

       Tk_Uid
       Tk_NameOfBitmap(display, bitmap)

       Tk_SizeOfBitmap(display, bitmap, widthPtr, heightPtr)

       Tk_FreeBitmap(display, bitmap)

ARGUMENTS
       Tcl_Interp      *interp	   (in)	     Interpreter   to  use  for	 error
					     reporting.

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

       Pixmap	       bitmap	   (in)	     Identifier for a bitmap allocated
					     by 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 bit‐
       maps 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  descrip‐
       tion.   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 for‐
			   mat.

       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 ballon words.

			   caution     A triangle with an 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	 argu‐
       ment  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 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 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, 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 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
       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  cre‐
       ated  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.0		       Tk_GetBitmap(3)
[top]

List of man pages available for DigitalUNIX

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