NAME
Tk_GetBitmap, Tk_DefineBitmap, Tk_NameOfBitmap,
Tk_SizeOfBitmap, Tk_FreeBitmap, Tk_GetBitmapFromData -
maintain database of single-plane pixmaps
SYNOPSIS
#include <tk.h>
Pixmap
Tk_GetBitmap(interp, tkwin, id))
int
Tk_DefineBitmap(interp, nameId, source, width, height))
Tk_Uid
Tk_NameOfBitmap(display, bitmap))
Tk_SizeOfBitmap(display, bitmap, widthPtr, heightPtr))
Tk_FreeBitmap(display, bitmap))
ARGUMENTS
Tcl_Interp *interp (in) Interpreter to use
for error reporting.
Tk_Window tkwin (in) Token for window in
which the bitmap
will be used.
Tk_Uid id (in) Description of
bitmap; see below
for possible values.
Tk_Uid nameId (in) Name for new bitmap
to be defined.
char *source (in) Data for bitmap, in
standard bitmap for-
mat. 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.
bitmap's height.
Display *display (in) Display for which
bitmap was allo-
cated.
Pixmap bitmap (in) Identifier for a
bitmap allocated by
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 bitmaps to be named with
character strings.
Tk_GetBitmap takes as argument a Tk_Uid describing a
bitmap. It returns a Pixmap identifier for a bitmap cor-
responding 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:
@fileName FileName must be the name of a file
containing a bitmap description in the
standard X11 or X10 format.
name Name must be the name of a bitmap
defined previously with a call to
Tk_DefineBitmap. The following names
are pre-defined by Tk:
error The international "don't"
symbol: a circle with a
diagonal line across it.
gray50 50% gray: a checkerboard
pattern where every other
bit is on.
gray12 12.5% gray: a pattern
where one-eighth of the
bits are on, consisting of
every fourth pixel in
every other row.
hourglass An hourglass symbol.
info A large letter ``i''.
in it.
question A large question-mark.
warning A large exclamation point.
Under normal conditions, Tk_GetBitmap returns an identi-
fier for the requested bitmap. If an error occurs in cre-
ating 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 pri-
vate 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 pro-
gram'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 differ-
ent 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
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 argu-
ment 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.
BUGS
In determining whether an existing bitmap can be used to
satisfy a new request, Tk_GetBitmap considers only the
immediate value of its id argument. For example, when a
file name is passed to Tk_GetBitmap, Tk_GetBitmap will
assume it is safe to re-use an existing bitmap created
from the same file name: it will not check to see whether
the file itself has changed, or whether the current direc-
tory has changed, thereby causing the name to refer to a
different file.
KEYWORDS
bitmap, pixmap