Tk_AllocBitmapFromObj(3tk)
Tk_AllocBitmapFromObj(3Tk Library ProcedureTk_AllocBitmapFromObj(3)
_________________________________________________________________
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; inter-
nal rep will be modi-
fied to cache pointer
to corresponding Pix-
map.
const char *info (in) Same as objPtr except
description of bitmap
Tk Last change: 8.1 1
Tk_AllocBitmapFromObj(3Tk Library ProcedureTk_AllocBitmapFromObj(3)
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 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.
int *heightPtr (out) Pointer to word to
fill in with bitmap's
height.
Display *display (in) Display for which bit-
map was allocated.
Pixmap bitmap (in) Identifier for a bit-
map 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 bit-
map that matches the description in objPtr and is suitable
for use in tkwin. It re-uses an existing bitmap, if possi-
ble, 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 con-
taining a bitmap description in the
standard X11 or X10 format.
Tk Last change: 8.1 2
Tk_AllocBitmapFromObj(3Tk Library ProcedureTk_AllocBitmapFromObj(3)
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 Macin-
tosh platform:
document A generic document.
stationery Document stationery.
edition The edition symbol.
application Generic application icon.
accessory A desk accessory.
Tk Last change: 8.1 3
Tk_AllocBitmapFromObj(3Tk Library ProcedureTk_AllocBitmapFromObj(3)
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 exclama-
tion 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 effi-
cient than Tk_AllocBitmapFromObj.
Tk_GetBitmapFromObj returns the token for an existing bit-
map, 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 Last change: 8.1 4
Tk_AllocBitmapFromObj(3Tk Library ProcedureTk_AllocBitmapFromObj(3)
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 bit-
map 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 XRead-
BitmapFile 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 Last change: 8.1 5
Tk_AllocBitmapFromObj(3Tk Library ProcedureTk_AllocBitmapFromObj(3)
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_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
Tk Last change: 8.1 6
Man(1) output converted with
man2html