tk4.2 C API - GetBitmap






NAME

     Tk_GetBitmap,       Tk_DefineBitmap,        Tk_NameOfBitmap,
     Tk_SizeOfBitmap, Tk_FreeBitmap, Tk_GetBitmapFromData - main-
     tain 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  for-
                                           mat.  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 bit-
                                           map was allocated.

     Pixmap          bitmap      (in)      Identifier for a  bit-
                                           map    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  possi-
     ble,  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 con-
                         taining  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.

                         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.

     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  pro-
     cedures 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  argu-
     ment  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 dif-
     ferent file.



KEYWORDS

     bitmap, pixmap