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)