Tk Library Procedures
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.
-
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.
-
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''.
-
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 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.
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
Last change: 4.1
[ tcl8.0a1 | tk8.0a1 | X-ref ]
Copyright © 1989-1994 The Regents of the University of California.
Copyright © 1994-1996 Sun Microsystems, Inc.