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(bitmap) Tk_SizeOfBitmap(bitmap, widthPtr, heightPtr)

Tk_FreeBitmap(bitmap) Pixmap Tk_GetBitmapFromData(interp, tkwin, source, width, height)

ARGUMENTS

Tcl_Interp∗interp(in) Interpreter to use for error reporting. 

Tk_Windowtkwin(in) Token for window in which the bitmap will be used. 

Tk_Uidid(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. 

unsigned intwidth(in) Width of bitmap. 

unsigned intheight(in) Height of bitmap. 

unsigned int∗widthPtr(out) Pointer to word to fill in with bitmap’s width. 

unsigned int∗heightPtr(out) Pointer to word to fill in with bitmap’s height. 

Pixmapbitmap(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:

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).

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 have been created.  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 or XGetBitmapFromData, which create a new bitmap on each call. 

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. 

The procedure Tk_GetBitmapFromData is a historical relic from a time before Tk_DefineBitmap existed;  its use is discouraged nowadays and it may be deleted soon.  Tk_GetBitmapFromData serves as a combination of Tk_DefineBitmap and Tk_GetBitmap:  given an in-memory description for a bitmap similar to what would be passed to Tk_DefineBitmap (source, width, and height), it returns a bitmap corresponding to that description that is suitable for use in window tkwin.  At present it does this by calling Tk_DefineBitmap to define a name of the form “_tknum” where num is an integer that starts at 1 and increments for each new combination of source, width, and height.  Then it calls Tk_GetBitmap.  Tk_GetBitmapFromData keeps a database of names and data, so that if the same source, width, and height are used again later, Tk_GetBitmapFromData will re-use the original name. 

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

Sprite version 1.0  —