DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

Tk_AllocBitmapFromObj(3)




______________________________________________________________________________


NAME

       Tk_AllocBitmapFromObj,        Tk_GetBitmap,        Tk_GetBitmapFromObj,
       Tk_DefineBitmap,  Tk_NameOfBitmap,  Tk_SizeOfBitmap,  Tk_FreeBitmapFro-
       mObj, Tk_FreeBitmap - maintain database of single-plane pixmaps


SYNOPSIS

       #include <tk.h>

       Pixmap                                                                  |
       Tk_GetBitmapFromObj(interp, tkwin, objPtr)                              |

       Pixmap                                                                  |
       Tk_GetBitmap(interp, tkwin, info)                                       |

       Pixmap                                                                  |
       Tk_GetBitmapFromObj(tkwin, objPtr)                                      |

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


ARGUMENTS

       Tcl_Interp      *interp     (in)      Interpreter   to  use  for  error
                                             reporting; 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   isn't |
                                             cached.

       CONST char      *name       (in)      Name  for  new   bitmap   to   be
                                             defined.

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

       Pixmap          bitmap      (in)      Identifier for a bitmap allocated
                                             by    Tk_AllocBitmapFromObj    or
                                             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_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-
                           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_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 |
       returned  and  an  error  message  is left in interp's result if interp |
       isn't NULL. Tk_AllocBitmapFromObj caches information about  the  return |
       value  in  objPtr,  which  speeds up future calls to procedures such as |
       Tk_AllocBitmapFromObj and Tk_GetBitmapFromObj.                          |

       Tk_GetBitmap is identical  to  Tk_AllocBitmapFromObj  except  that  the |
       description  of  the  bitmap  is  specified with a string instead of an |
       object.  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 |
       doesn't  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 doesn't 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
       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, "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
       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  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
       automatically.  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_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_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_AllocBitmapFromObj or Tk_GetBitmap.


BUGS

       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.


KEYWORDS

       bitmap, pixmap

Tk                                    8.1             Tk_AllocBitmapFromObj(3)

Man(1) output converted with man2html