getbitmap(3Tk)

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