NAME¶
Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap,
Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, Tk_FreeBitmap -
maintain database of single-plane pixmaps
SYNOPSIS¶
#include <tk.h>
Pixmap
Tk_AllocBitmapFromObj(interp, tkwin, objPtr)
Pixmap
Tk_GetBitmap(interp, tkwin, info)
Pixmap
Tk_GetBitmapFromObj(tkwin, objPtr)
int
Tk_DefineBitmap(interp, name, source, width, height)
const char *
Tk_NameOfBitmap(display, bitmap)
Tk_SizeOfBitmap(display, bitmap, widthPtr, heightPtr)
Tk_FreeBitmapFromObj(tkwin, objPtr)
Tk_FreeBitmap(display, bitmap)
ARGUMENTS¶
- Tcl_Interp *interp (in)
- Interpreter to use for error reporting; if NULL then no
error message is left after errors.
- Tk_Window tkwin (in)
- Token for window in which the bitmap will be used.
- Tcl_Obj *objPtr (in/out)
- String value describes desired bitmap; internal rep will be
modified to cache pointer to corresponding Pixmap.
- const char *info (in)
- Same as objPtr except description of bitmap is
passed as a string and resulting Pixmap is not cached.
- const char *name (in)
- Name for new bitmap to be defined.
- const 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_AllocBitmapFromObj or 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_AllocBitmapFromObj returns a Pixmap identifier for a bitmap that
matches the description in
objPtr and is suitable for use in
tkwin. It re-uses an existing bitmap, if possible, and creates a new
one otherwise.
ObjPtr's value 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.
- gray75
- 75% gray: a checkerboard pattern where three out of four
bits are on.
- gray50
- 50% gray: a checkerboard pattern where every other bit is
on.
- gray25
- 25% gray: a checkerboard pattern where one out of every
four bits 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.
In addition, the following pre-defined names are available only on the
Macintosh platform:
- document
- A generic document.
- stationery
- Document stationery.
- edition
- The edition symbol.
- application
- Generic application icon.
- accessory
- A desk accessory.
- folder
- Generic folder icon.
- pfolder
- A locked folder.
- trash
- A trash can.
- floppy
- A floppy disk.
- ramdisk
- A floppy disk with chip.
- cdrom
- A cd disk icon.
- preferences
- A folder with prefs symbol.
- querydoc
- A database document icon.
- stop
- A stop sign.
- note
- A face with balloon words.
- caution
- A triangle with an exclamation point.
Under normal conditions,
Tk_AllocBitmapFromObj returns an identifier for
the requested bitmap. If an error occurs in creating the bitmap, such as when
objPtr refers to a non-existent file, then
None is returned and
an error message is left in
interp's result if
interp is not
NULL.
Tk_AllocBitmapFromObj caches information about the return value
in
objPtr, which speeds up future calls to procedures such as
Tk_AllocBitmapFromObj and
Tk_GetBitmapFromObj.
Tk_GetBitmap is identical to
Tk_AllocBitmapFromObj except that the
description of the bitmap is specified with a string instead of an object.
This prevents
Tk_GetBitmap from caching the return value, so
Tk_GetBitmap is less efficient than
Tk_AllocBitmapFromObj.
Tk_GetBitmapFromObj returns the token for an existing bitmap, given the
window and description used to create the bitmap.
Tk_GetBitmapFromObj
does not actually create the bitmap; the bitmap must already have been created
with a previous call to
Tk_AllocBitmapFromObj or
Tk_GetBitmap.
The return value is cached in
objPtr, which speeds up future calls to
Tk_GetBitmapFromObj with the same
objPtr and
tkwin.
Tk_DefineBitmap associates a name with in-memory bitmap data so that the
name can be used in later calls to
Tk_AllocBitmapFromObj or
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 does not make
a private copy of this memory, but uses the bytes pointed to by
source
later in calls to
Tk_AllocBitmapFromObj or
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, "foo", stip_bits,
stip_width, stip_height);
...
bitmap = Tk_GetBitmap(interp, tkwin, "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, "@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 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.
When a bitmap is no longer used, Tk will release it automatically. This
approach can substantially reduce server overhead, so
Tk_AllocBitmapFromObj and
Tk_GetBitmap should generally be used
in preference to Xlib procedures like
XReadBitmapFile.
The bitmaps returned by
Tk_AllocBitmapFromObj and
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 textual
description that was passed to
Tk_GetBitmap when the bitmap was
created.
Bitmap must have been the return value from a previous call to
Tk_AllocBitmapFromObj or
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_AllocBitmapFromObj or
Tk_GetBitmap.
When a bitmap is no longer needed,
Tk_FreeBitmapFromObj or
Tk_FreeBitmap should be called to release it. For
Tk_FreeBitmapFromObj the bitmap to release is specified with the same
information used to create it; for
Tk_FreeBitmap the bitmap to release
is specified with its Pixmap token. There should be exactly one call to
Tk_FreeBitmapFromObj or
Tk_FreeBitmap for each call to
Tk_AllocBitmapFromObj or
Tk_GetBitmap.
BUGS¶
In determining whether an existing bitmap can be used to satisfy a new request,
Tk_AllocBitmapFromObj and
Tk_GetBitmap consider only the
immediate value of the string description. 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