_________________________________________________________________
NAME
Tk_GetPixmap, Tk_GetPixmapClipMask, Tk_DefinePixmap, Tk_NameOfPixmap, Tk_PixmapOfName, Tk_SizeOfPixmap, Tk_DepthOfPixmap, Tk_FreePixmap, Tk_GetPixmapFromData,
Pixmap
Tk_GetPixmap(interp, tkwin, id)
Pixmap
Tk_GetPixmapClipMask(display, pixmap)
int
Tk_DefinePixmap(interp, nameId, tkwin, pixmap, clipMask, source, width, height, depth, format)
Tk_Uid
Tk_NameOfPixmap(display, pixmap)
Pixmap
Tk_PixmapOfName(id, tkwin)
void
Tk_SizeOfPixmap(display, pixmap, widthPtr, heightPtr)
int
Tk_DepthOfPixmap(display, pixmap)
void
Tk_FreePixmap(display, pixmap)
Pixmap
Tk_GetPixmapFromData(interp, tkwin, name, source, width, height, depth, format)
int
Tk_SavePixmap(interp, tkwin, fileName, pixmap, clipMask, width, height, format)
int
Tk_UndefinePixmap(interp, name, tkwin)
int
Tk_CacheStatusOfPixmap(display, pixmap)
int
Tk_SetCacheStatusOfPixmap(display, pixmap, status)
int
Tk_DefaultCacheStatus() int
Tk_SetDefaultCacheStatus(status)
unsigned int height (in) Height of pixmap.
unsigned int depth (in) Depth of pixmap.
unsigned int *heightPtr (out) Pointer to word to fill in with pixmap's height.
Tk_GetPixmap takes a Tk_Uid describing a pixmap as argument. It returns a Pixmap identifier for a pixmap corresponding to the description. It re-uses an existing pixmap, if possible, and creates a new one otherwise. At present, id must have one of the following forms:
questhead
The silhouette of a human head, with a question mark in it.
question
A large question-mark.
warning
A large exclamation point.
bomb.xpm
An ignited bomb.
exclaim.xpm
An exclamation point in a dot.
exit.xpm
An exit sign.
hourglass.xpm
An hourglass symbol.
info.xpm
A large letter ``i''' in a dot.
no_entry.xpm
A no entry sign.
preserver.xpm
A life preserver.
question.xpm
A question mark in a dot.
stop.xpm
A stop sign.
tick.xpm
A tick symbol in a dot.
Under normal conditions, Tk_GetPixmap returns an identifier for the requested pixmap. If an error occurs in creating the pixmap, such as when id refers to a non-existent file, then None is returned and an error message is left in interp->result.
Tk_GetPixmapClipMask takes a Pixmap identifier as argument. It returns a Pixmap identifier for the clipmask associated to the given pixmap.
Tk_DefinePixmap associates a name with in-memory pixmap data so that the name can be used in later calls to Tk_GetPixmap. It is also possible to specify an externally created pixmap and clipMask. The nameId argument gives a name to the pixmap; it must not have been used previously in a call to Tk_DefinePixmap. The arguments source, width, height and depth describe the pixmap. The argument format specifies the format of the data. If no format is specified, the format is derived from the passed data. Tk_DefinePixmap normally returns TCL_OK; if an error occurs (e.g. a pixmap named nameId has already been defined), then TCL_ERROR is returned and an error message is left in interp->result. Note: Tk_DefinePixmap expects the memory pointed at by source to be static: Tk_DefinePixmap doesn't make a private copy of this memory, but uses the bytes pointed at by source later in calls to Tk_GetPixmap.
Typically, Tk_DefinePixmap is used by #include-ing a pixmap 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, or an Xpm3 pixmap. The following code uses Tk_DefinePixmap to define a new bitmap named foo:
Pixmap bitmap;
#include "stip.bitmap"
Tk_DefinePixmap(interp, Tk_GetUid("foo"), stip_bits, stip_width, stip_height, "bitmap"); ...
bitmap = Tk_GetPixmap(interp, tkwin, Tk_GetUid("foo")); This code causes the bitmap file to be read at compiletime and incorporates the bitmap information into the program's executable image. The same bitmap file could be read at run-time using Tk_GetPixmap:
Pixmap bitmap;
bitmap = Tk_GetPixmap(interp, tkwin, Tk_GetUid("@stip.bitmap")); The second form is a bit more flexible (the file can be modified after the program has been compiled, or a different string can 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_GetPixmap maintains a database of all the pixmaps that have been created. Whenever possible, it will return an existing pixmap rather than creating a new one. This approach can substantially reduce server overhead, so Tk_GetPixmap should generally be used in preference to Xlib procedures like XReadBitmapFile or XGetBitmapFromData, which create a new bitmap on each call.
The pixmaps returned by Tk_GetPixmap are shared, so callers should never modify them. If a pixmap must be modified dynamically, then it should be created by calling Xlib procedures such as XReadBitmapFile or XCreatePixmap directly.
The procedure Tk_NameOfPixmap is roughly the inverse of Tk_GetPixmap. Provided with an X pixmap argument, it returns the id that was passed to Tk_GetPixmap when the pixmap was created.
The procedure Tk_PixmapOfName is exactly the inverse of Tk_NameOfPixmap. Provided with a name, it returns the pixmap id which is associated with that name.
Tk_SizeOfPixmap returns the dimensions of its pixmap argument in the words pointed at by the widthPtr and heightPtr arguments.
Tk_DepthOfPixmap returns the depth of its pixmap argument.
When a pixmap returned by Tk_GetPixmap is no longer needed, Tk_FreePixmap should be called to release it. There should be exactly one call to Tk_FreePixmap for each call to Tk_GetPixmap. When a pixmap is no longer in use anywhere (i.e. it has been freed as many times as it has been gotten), Tk_FreePixmap will release it to the X server and delete it from the database.
The procedure Tk_GetPixmapFromData is a historical relic from a time before Tk_DefinePixmap existed; its use is discouraged nowadays, and it may be deleted soon. Tk_GetPixmapFromData serves as a combination of Tk_DefinePixmap and Tk_GetPixmap: given an in-memory description for a pixmap similar to what would be passed to Tk_DefinePixmap (source, width, height and depth), it returns a pixmap corresponding to the description that is suitable for use in window tkwin. At present it does this by calling Tk_DefinePixmap to define a name of the form ``_tknum'' where num is an integer that starts at 1 and increments for each new combination of source, width, height and depth. The parameter name allows you to specify a name directly. Then it calls Tk_GetPixmap. Tk_GetPixmapFromData keeps a database of names and data, so that if the same source, width, height and depth are used again later, Tk_GetPixmapFromData will re-use the original name.
Tk_SavePixmap saves the given pixmap and clipMask to the specified file fileName in the format selected with the format parameter.
Tk_UndefinePixmap undefines the given pixmap. This means that any association of name with a bitmap or pixmap is removed. This can be used to undefine names defined by Tk_DefinePixmap.
Tk_CacheStatusPixmap returns the cache status for pixmap. The returned value is 0 or 1.
Tk_SetCacheStatusPixmap sets the cache status pixmap to status. There is no return value. A pixmap that is cached is not destroyed when it is no longer needed. Instead, it remains in the Tk hash table for later use.
Tk_DefaultCacheStatus returns the default cache status. The returned value is 0 or 1.
Tk_SetDefaultCacheStatus returns the default cache status to status. Pixmaps that are loaded get this cache status by default.
BUGS
In determining whether an existing pixmap can be used to satisfy a new request, Tk_GetPixmap considers only the immediate value of its id argument. For example, when a file name is passed to Tk_GetPixmap, Tk_GetPixmap will assume it is safe to re-use an existing pixmap 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 different file.
KEYWORDS
bitmap, pixmap