NAME
TkAllocBitmapFromObj, TkGetBitmap, TkGetBitmapFromObj,TkDefineBitmap, TkNameOfBitmap, TkSizeOfBitmap, TkFreeBitmapFro-
mObj, TkFreeBitmap - maintain database of single-plane pixmaps
SYNOPSIS
##iinncclluuddee <
Pixmap | TTkkGGeettBBiittmmaappFFrroommOObbjj((interp, tkwin, objPtr)) | Pixmap | TTkkGGeettBBiittmmaapp((interp, tkwin, info)) | Pixmap | TTkkGGeettBBiittmmaappFFrroommOObbjj((tkwin, objPtr)) | int TTkkDDeeffiinneeBBiittmmaapp((interp, name, source, width, height)) CONST char * TTkkNNaammeeOOffBBiittmmaapp((display, bitmap)) TTkkSSiizzeeOOffBBiittmmaapp((display, bitmap, widthPtr, heightPtr)) TTkkFFrreeeeBBiittmmaappFFrroommOObbjj((tkwin, objPtr)) | TTkkFFrreeeeBBiittmmaapp((display, bitmap)) AARRGGUUMMEENNTTSS TclInterp *interp (in) Interpreter to use for error reporting; if NULL then no error message is left after errors. TkWindow tkwin (in) Token for window in which the bitmap will be used. TclObj *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 TTkkAAllllooccBBiittmmaappFFrroommOObbjj or TTkkGGeettBBiittmmaapp.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. TTkkAAllllooccBBiittmmaappFFrroommOObbjj 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 abitmap 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 TTkkDDeeffiinneeBBiittmmaapp. The follow-
ing names are pre-defined by Tk:
eerrrroorr The international "don't" symbol: a circle with a diagonal line across it. ggrraayy7755 ||75% gray: a checkerboard pattern where |
three out of four bits are on.ggrraayy5500 50% gray: a checkerboard pattern where
every other bit is on. ggrraayy2255 ||25% gray: a checkerboard pattern where |
one out of every four bits is on.ggrraayy1122 12.5% gray: a pattern where one-eighth
of the bits are on, consisting of every fourth pixel in every other row. hhoouurrggllaassss An hourglass symbol. iinnffoo A large letter ``i''. qquueesstthheeaadd The silhouette of a human head, with a question mark in it.qquueessttiioonn A large question-mark.
wwaarrnniinngg A large exclamation point.In addition, the following pre-defined names are
available only on the MMaacciinnttoosshh platform: ddooccuummeenntt A generic document. ssttaattiioonneerryy Document stationery. eeddiittiioonn The edition symbol. aapppplliiccaattiioonn Generic application icon. aacccceessssoorryy A desk accessory. ffoollddeerr Generic folder icon. ppffoollddeerr A locked folder. ttrraasshh A trash can. ffllooppppyy A floppy disk. rraammddiisskk A floppy disk with chip. ccddrroomm A cd disk icon. pprreeffeerreenncceess A folder with prefs symbol. qquueerryyddoocc A database document icon. ssttoopp A stop sign. nnoottee A face with ballon words. ccaauuttiioonn A triangle with an exclamation point. Under normal conditions, TTkkAAllllooccBBiittmmaappFFrroommOObbjj 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 NNoonnee is |
returned and an error message is left in interp's result if interp | isn't NULL. TTkkAAllllooccBBiittmmaappFFrroommOObbjj caches information about the return | value in objPtr, which speeds up future calls to procedures such as | TTkkAAllllooccBBiittmmaappFFrroommOObbjj and TTkkGGeettBBiittmmaappFFrroommOObbjj. | TTkkGGeettBBiittmmaapp is identical to TTkkAAllllooccBBiittmmaappFFrroommOObbjj except that the | description of the bitmap is specified with a string instead of an | object. This prevents TTkkGGeettBBiittmmaapp from caching the return value, so | TTkkGGeettBBiittmmaapp is less efficient than TTkkAAllllooccBBiittmmaappFFrroommOObbjj. | TTkkGGeettBBiittmmaappFFrroommOObbjj returns the token for an existing bitmap, given the | window and description used to create the bitmap. TTkkGGeettBBiittmmaappFFrroommOObbjj | doesn't actually create the bitmap; the bitmap must already have been | created with a previous call to TTkkAAllllooccBBiittmmaappFFrroommOObbjj or TTkkGGeettBBiittmmaapp. | The return value is cached in objPtr, which speeds up future calls to | TTkkGGeettBBiittmmaappFFrroommOObbjj with the same objPtr and tkwin.TTkkDDeeffiinneeBBiittmmaapp associates a name with in-memory bitmap data so that
the name can be used in later calls to TTkkAAllllooccBBiittmmaappFFrroommOObbjj or TTkkGGeett-
BBiittmmaapp. The nameId argument gives a name for the bitmap; it must not previously have been used in a call to TTkkDDeeffiinneeBBiittmmaapp. The argumentssource, width, and height describe the bitmap. TTkkDDeeffiinneeBBiittmmaapp nor-
mally returns TCLOK; if an error occurs (e.g. a bitmap named nameIdhas already been defined) then TCLERROR is returned and an error mes-
sage is left in interp->result. Note: TTkkDDeeffiinneeBBiittmmaapp expects the
memory pointed to by source to be static: TTkkDDeeffiinneeBBiittmmaapp doesn't make a private copy of this memory, but uses the bytes pointed to by source later in calls to TTkkAAllllooccBBiittmmaappFFrroommOObbjj or TTkkGGeettBBiittmmaapp.Typically TTkkDDeeffiinneeBBiittmmaapp is used by ##iinncclluuddee-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 ssttiipp..bbiittmmaapp, which was created by the bbiittmmaapp program and contains a stipple pattern. The following code uses TTkkDDeeffiinneeBBiittmmaapp to define a new bitmap named ffoooo: | Pixmap bitmap; |#include "stip.bitmap" |
TkDefineBitmap(interp, "foo", stipbits, | stipwidth, stipheight); | ... | bitmap = TkGetBitmap(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 TTkkGGeettBBiittmmaapp: |
Pixmap bitmap; | bitmap = TkGetBitmap(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 TTkkAAllllooccBBiittmmaappFFrroommOObbjj and TTkkGGeettBBiittmmaapp should generally be used in preference to Xlib procedures like XXRReeaaddBBiittmmaappFFiillee. The bitmaps returned by TTkkAAllllooccBBiittmmaappFFrroommOObbjj and TTkkGGeettBBiittmmaapp areshared, 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 XXRReeaaddBBiittmmaappFFiillee or XXCCrreeaatteePPiixxmmaapp directly. The procedure TTkkNNaammeeOOffBBiittmmaapp is roughly the inverse of TTkkGGeettBBiittmmaapp. Given an X Pixmap argument, it returns the textual description that was passed to TTkkGGeettBBiittmmaapp when the bitmap was created. Bitmap must have been the return value from a previous call to TTkkAAllllooccBBiittmmaappFFrroommOObbjj or TTkkGGeettBBiittmmaapp. TTkkSSiizzeeOOffBBiittmmaapp returns the dimensions of its bitmap argument in the words pointed to by the widthPtr and heightPtr arguments. As with TTkkNNaammeeOOffBBiittmmaapp, bitmap must have been created by TTkkAAllllooccBBiittmmaappFFrroommOObbjj or TTkkGGeettBBiittmmaapp. When a bitmap is no longer needed, TTkkFFrreeeeBBiittmmaappFFrroommOObbjj or | TTkkFFrreeeeBBiittmmaapp should be called to release it. For TTkkFFrreeeeBBiittmmaappFFrroommOObbjj | the bitmap to release is specified with the same information used to | create it; for TTkkFFrreeeeBBiittmmaapp the bitmap to release is specified with | its Pixmap token. There should be exactly one call to | TTkkFFrreeeeBBiittmmaappFFrroommOObbjj or TTkkFFrreeeeBBiittmmaapp for each call to | TTkkAAllllooccBBiittmmaappFFrroommOObbjj or TTkkGGeettBBiittmmaapp.BUGS
In determining whether an existing bitmap can be used to satisfy a newrequest, TTkkAAllllooccBBiittmmaappFFrroommOObbjj and TTkkGGeettBBiittmmaapp consider only the imme-
diate value of the string description. For example, when a file nameis passed to TTkkGGeettBBiittmmaapp, TTkkGGeettBBiittmmaapp will assume it is safe to re-
use an existing bitmap created from the same file name: it will notcheck 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. KKEEYYWWOORRDDSS bitmap, pixmap Tk 8.1 TkAllocBitmapFromObj(3)