Tk_GetBitmap takes as argument a Tk_Uid describing a bitmap. It returns a Pixmap identifier for a bitmap corresponding to the description. It re-uses an existing bitmap, if possible, and creates a new one otherwise. At present, id must have one of the following forms:
Under normal conditions, Tk_GetBitmap returns an identifier for the requested bitmap. If an error occurs in creating the bitmap, such as when id refers to a non-existent file, then None is returned and an error message is left in interp->result.
Tk_DefineBitmap associates a name with in-memory bitmap data so that the name can be used in later calls to Tk_GetBitmap. 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 normally 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 message 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_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, Tk_GetUid("foo"), stip_bits,
stip_width, stip_height);
...
bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("foo"));
This code causes the bitmap file to be read
at compile-time and incorporates 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, Tk_GetUid("@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_GetBitmap maintains a database of all the bitmaps that are currently in use. Whenever possible, it will return an existing bitmap rather than creating a new one. This approach can substantially reduce server overhead, so Tk_GetBitmap should generally be used in preference to Xlib procedures like XReadBitmapFile.
The bitmaps returned by Tk_GetBitmap are shared, so callers should never modify them. If a bitmap must be modified 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 id that was passed to Tk_GetBitmap when the bitmap was created. Bitmap must have been the return value from a previous call to 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_GetBitmap.
When a bitmap returned by Tk_GetBitmap is no longer needed, Tk_FreeBitmap should be called to release it. There should be exactly one call to Tk_FreeBitmap for each call to Tk_GetBitmap. When a bitmap is no longer in use anywhere (i.e. it has been freed as many times as it has been gotten) Tk_FreeBitmap will release it to the X server and delete it from the database.
Copyright © 1990 The Regents of the University of California. Copyright © 1994-1996 Sun Microsystems, Inc. Copyright © 1995, 1996 Roger E. Critchlow Jr.