Tk_GetBitmap(3Tk)Tk_GetBitmap(3Tk)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
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.
Page 1
Tk_GetBitmap(3Tk)Tk_GetBitmap(3Tk)
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 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:
@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.
gray25 25% gray: a pattern where 25% of the bits
are on, consisting of all the bit
positions that can be reached by a chess
knight starting at (0,0).
hourglass An hourglass symbol.
info A large letter ``i''.
questhead The silhouette of a human head, with a
question mark in it.
question A large question-mark.
warning A large exclamation point.
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
Page 2
Tk_GetBitmap(3Tk)Tk_GetBitmap(3Tk)
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
Page 3
Tk_GetBitmap(3Tk)Tk_GetBitmap(3Tk)
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 directory has changed, thereby
causing the name to refer to a different file.
KEYWORDS
bitmap, pixmap
Page 4
