Seth Woolley's Man Viewer

Tk_GetBitmap(3) - Tk_AllocBitmapFromObj, Tk_DefineBitmap, Tk_FreeBitmap, Tk_FreeBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_NameOfBitmap, Tk_SizeOfBitmap - maintain database of single-plane pixmaps - man 3 Tk_GetBitmap

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

Tk_AllocBitmapFromObj(3)     Tk Library Procedures    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(1,5,n))                                       |

       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(1,8))      Interpreter   to  use  for  error(8,n)
                                             reporting; if(3,n) NULL then no  error(8,n)
                                             message is left after errors.

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

       Tcl_Obj         *objPtr     (in(1,8)/out)                                    ||
                                             String  value  describes  desired |
                                             bitmap; internal rep will be mod- |
                                             ified  to cache pointer to corre- |
                                             sponding Pixmap.                  |

       CONST                                                                   |
       char      *info(1,5,n)       (in(1,8))                                        |     |
                                             Same as objPtr except description |
                                             of bitmap is passed as  a  string(3,n) |
                                             and    resulting   Pixmap   isn't |
                                             cached.

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

       CONST char      *source     (in(1,8))      Data for bitmap, in(1,8) standard bit-
                                             map format.  Must  be  stored  in(1,8)
                                             static  memory  whose  value will
                                             never change.

       int             width       (in(1,8))      Width of bitmap.

       int             height      (in(1,8))      Height of bitmap.

       int             *widthPtr   (out)     Pointer to word to fill  in(1,8)  with
                                             bitmap's width.

       int             *heightPtr  (out)     Pointer  to  word to fill in(1,8) with
                                             bitmap's height.

       Display         *display    (in(1,8))      Display  for  which  bitmap   was
                                             allocated.

       Pixmap          bitmap      (in(1,8))      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(5,8) with character strings.

       Tk_AllocBitmapFromObj returns a Pixmap identifier  for  a  bitmap  that |
       matches the description in(1,8) objPtr and is suitable for use in(1,8) tkwin.  It |
       re-uses an existing bitmap, if(3,n) 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(1,n) containing a
                           bitmap description in(1,8) 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(8,n)       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(1,8) every other row.

                           hourglass   An hourglass symbol.

                           info(1,5,n)        A large letter ``i''.

                           questhead   The silhouette of a human head, with  a
                                       question mark in(1,8) 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(8,n) occurs in(1,8) creating the bitmap, |
       such as when objPtr  refers  to  a  non-existent  file(1,n),  then  None  is |
       returned  and  an  error(8,n)  message  is left in(1,8) interp's result if(3,n) interp |
       isn't NULL. Tk_AllocBitmapFromObj caches information about  the  return |
       value  in(1,8)  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(3,n) instead of an |
       object.  This prevents Tk_GetBitmap from caching the return  value,  so |
       Tk_GetBitmap is less(1,3) 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(1,8) 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(1,8) 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(1,8) a call to Tk_DefineBitmap.  The arguments
       source, width, and height describe the  bitmap.   Tk_DefineBitmap  nor-
       mally  returns  TCL_OK;  if(3,n) an error(8,n) occurs (e.g. a bitmap named(5,8) nameId
       has already been defined) then TCL_ERROR is returned and an error(8,n)  mes-
       sage  is  left  in(1,8)  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(1,8) calls to Tk_AllocBitmapFromObj or Tk_GetBitmap.

       Typically  Tk_DefineBitmap  is  used  by  #include-ing  a  bitmap  file(1,n)
       directly into a C program and then referencing the variables defined by
       the file.  For example, suppose there exists a file(1,n) 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(5,8) 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(1,n) to be read(2,n,1 builtins) at compile-time and  incor-
       porates  the  bitmap  information  into the program's executable image.
       The same bitmap file(1,n) could be read(2,n,1 builtins) 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(1,n)  could  be  modified
       after  the  program  has  been compiled, or a different string(3,n) could be
       provided to read(2,n,1 builtins) a different file(1,n)), but  it  is  a  little  slower  and
       requires the bitmap file(1,n) to exist separately from the program.

       Tk  maintains  a database of all the bitmaps that are currently in(1,8) 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(1,8)
       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(1,8) 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(3,n) description.  For example, when a  file(1,n)  name
       is  passed  to Tk_GetBitmap, Tk_GetBitmap will assume it is safe to re-
       use an existing bitmap created from the same file(1,n) name:   it  will  not
       check  to  see whether the file(1,n) 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)

References for this manual (incoming links)