Tk_AllocBitmapFromObj(3tk) Tk Library Procedures Tk_AllocBitmapFromObj(3tk)
______________________________________________________________________________
NAME
Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_De-
fineBitmap, 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 re-
porting; 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 mod-
ified to cache pointer to corre-
sponding 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 de-
fined.
const void *source (in) Data for bitmap, in standard bit-
map 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 al-
located.
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) be-
ing 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 other-
wise. 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 format.
name Name must be the name of a bitmap defined previ-
ously with a call to Tk_DefineBitmap. The follow-
ing 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 re-
turned 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_Al-
locBitmapFromObj and Tk_GetBitmapFromObj.
Tk_GetBitmap is identical to Tk_AllocBitmapFromObj except that the de-
scription of the bitmap is specified with a string instead of an ob-
ject. 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_Get-
Bitmap. 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 nor-
mally 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 mes-
sage is left in interpreter interp's 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 di-
rectly 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 incor-
porates 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 af-
ter the program has been compiled, or a different string could be pro-
vided 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 creat-
ing a new one. When a bitmap is no longer used, Tk will release it au-
tomatically. 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 modi-
fied 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_Al-
locBitmapFromObj 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 imme-
diate 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 cur-
rent directory has changed, thereby causing the name to refer to a dif-
ferent file.
KEYWORDS
bitmap, pixmap
Tk 8.1 Tk_AllocBitmapFromObj(3tk)
Generated by dwww version 1.14 on Fri Jan 24 06:03:54 CET 2025.