NAME
Tk_GetPixmap, Tk_GetPixmapClipMask, Tk_DefinePixmap, Tk_NameOfPixmap, Tk_PixmapOfName, Tk_SizeOfPixmap, Tk_DepthOfPixmap, Tk_FreePixmap, Tk_GetPixmapFromData, Tk_CacheStatusOfPixmap, Tk_SetCacheStatusOfPixmap, Tk_DefaultCacheStatus, Tk_SetDefaultCacheStatus - maintain database of color pixmaps

SYNOPSIS
#include <tk.h>

Pixmap
Tk_GetPixmap(interp, tkwin, id)

Pixmap
Tk_GetPixmapClipMask(display, pixmap)

int
Tk_DefinePixmap(interp, nameId, tkwin, pixmap, clipMask, source, width, height, depth, format)

Tk_Uid
Tk_NameOfPixmap(display, pixmap)

Pixmap
Tk_PixmapOfName(id, tkwin)

void
Tk_SizeOfPixmap(display, pixmap, widthPtr, heightPtr)

int
Tk_DepthOfPixmap(display, pixmap)

void
Tk_FreePixmap(display, pixmap)

Pixmap
Tk_GetPixmapFromData(interp, tkwin, name, source, width, height, depth, format)

int
Tk_SavePixmap(interp, tkwin, fileName, pixmap, clipMask, width, height, format)

int
Tk_UndefinePixmap(interp, name, tkwin)

int
Tk_CacheStatusOfPixmap(display, pixmap)

int
Tk_SetCacheStatusOfPixmap(display, pixmap, status)

int
Tk_DefaultCacheStatus()

int
Tk_SetDefaultCacheStatus(status)

ARGUMENTS
Interpreter to use for error reporting. Display that contains the pixmap. Token for window in which the pixmap will be used. Description of pixmap; see below for possible values. Name for new pixmap to be defined. Data for pixmap, in standard bitmap format, or Xpm 3 format. Must be stored in static memory the value of which will never change. Width of pixmap. Height of pixmap. Depth of pixmap. The clipmask that should be used for drawing the pixmap. The filename used to save the pixmap. The format that should be used. Possible values are bitmap and xpm3. Pointer to word to fill in with pixmap's width. Pointer to word to fill in with pixmap's height. Identifier for a pixmap allocated by Tk_GetPixmap. The cache status for a pixmap, or the global cache status.

DESCRIPTION

These procedures manage a collection of pixmaps being used by an application. The procedures allow pixmaps to be re-used efficiently, thereby avoiding server overhead, and they also allow pixmaps to be named with character strings.

Tk_GetPixmap takes a Tk_Uid describing a pixmap as argument. It returns a Pixmap identifier for a pixmap corresponding to the description. It re-uses an existing pixmap, 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, or a file containing a pixmap description in the Xpm3 format.

name
    Name must be the name of a pixmap defined previously with a call to Tk_DefinePixmap. 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).

    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.

    bomb.xpm
        An ignited bomb.

    exclaim.xpm
        An exclamation point in a dot.

    exit.xpm
        An exit sign.

    hourglass.xpm
        An hourglass symbol.

    info.xpm
        A large letter ``i''' in a dot.

    no_entry.xpm
        A no entry sign.

    preserver.xpm
        A life preserver.

    question.xpm
        A question mark in a dot.

    stop.xpm
        A stop sign.

    tick.xpm
        A tick symbol in a dot.

Under normal conditions, Tk_GetPixmap returns an identifier for the requested pixmap. If an error occurs in creating the pixmap, such as when id refers to a non-existent file, then None is returned and an error message is left in interp->result.

Tk_GetPixmapClipMask takes a Pixmap identifier as argument. It returns a Pixmap identifier for the clipmask associated to the given pixmap.

Tk_DefinePixmap associates a name with in-memory pixmap data so that the name can be used in later calls to Tk_GetPixmap. It is also possible to specify an externally created pixmap and clipMask. The nameId argument gives a name to the pixmap; it must not have been used previously in a call to Tk_DefinePixmap. The arguments source, width, height and depth describe the pixmap. The argument format specifies the format of the data. If no format is specified, the format is derived from the passed data. Tk_DefinePixmap normally returns TCL_OK; if an error occurs (e.g. a pixmap named nameId has already been defined), then TCL_ERROR is returned and an error message is left in interp->result. Note: Tk_DefinePixmap expects the memory pointed at by source to be static: Tk_DefinePixmap doesn't make a private copy of this memory, but uses the bytes pointed at by source later in calls to Tk_GetPixmap.

Typically, Tk_DefinePixmap is used by #include-ing a pixmap 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, or an Xpm3 pixmap. The following code uses Tk_DefinePixmap to define a new bitmap named foo:
    Pixmap bitmap;
    #include "stip.bitmap"
    Tk_DefinePixmap(interp, Tk_GetUid("foo"), stip_bits,
    	stip_width, stip_height, "bitmap");
    ...
    bitmap = Tk_GetPixmap(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_GetPixmap:
    Pixmap bitmap;
    bitmap = Tk_GetPixmap(interp, tkwin, Tk_GetUid("@stip.bitmap"));
The second form is a bit more flexible (the file can be modified after the program has been compiled, or a different string can 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_GetPixmap maintains a database of all the pixmaps that have been created. Whenever possible, it will return an existing pixmap rather than creating a new one. This approach can substantially reduce server overhead, so Tk_GetPixmap should generally be used in preference to Xlib procedures like XReadBitmapFile or XGetBitmapFromData, which create a new bitmap on each call.

The pixmaps returned by Tk_GetPixmap are shared, so callers should never modify them. If a pixmap must be modified dynamically, then it should be created by calling Xlib procedures such as XReadBitmapFile or XCreatePixmap directly.

The procedure Tk_NameOfPixmap is roughly the inverse of Tk_GetPixmap. Provided with an X pixmap argument, it returns the id that was passed to Tk_GetPixmap when the pixmap was created.

The procedure Tk_PixmapOfName is exactly the inverse of Tk_NameOfPixmap. Provided with a name, it returns the pixmap id which is associated with that name.

Tk_SizeOfPixmap returns the dimensions of its pixmap argument in the words pointed at by the widthPtr and heightPtr arguments.

Tk_DepthOfPixmap returns the depth of its pixmap argument.

When a pixmap returned by Tk_GetPixmap is no longer needed, Tk_FreePixmap should be called to release it. There should be exactly one call to Tk_FreePixmap for each call to Tk_GetPixmap. When a pixmap is no longer in use anywhere (i.e. it has been freed as many times as it has been gotten), Tk_FreePixmap will release it to the X server and delete it from the database.

The procedure Tk_GetPixmapFromData is a historical relic from a time before Tk_DefinePixmap existed; its use is discouraged nowadays, and it may be deleted soon. Tk_GetPixmapFromData serves as a combination of Tk_DefinePixmap and Tk_GetPixmap: given an in-memory description for a pixmap similar to what would be passed to Tk_DefinePixmap (source, width, height and depth), it returns a pixmap corresponding to the description that is suitable for use in window tkwin. At present it does this by calling Tk_DefinePixmap 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, height and depth. The parameter name allows you to specify a name directly. Then it calls Tk_GetPixmap. Tk_GetPixmapFromData keeps a database of names and data, so that if the same source, width, height and depth are used again later, Tk_GetPixmapFromData will re-use the original name.

Tk_SavePixmap saves the given pixmap and clipMask to the specified file fileName in the format selected with the format parameter.

Tk_UndefinePixmap undefines the given pixmap. This means that any association of name with a bitmap or pixmap is removed. This can be used to undefine names defined by Tk_DefinePixmap.

Tk_CacheStatusPixmap returns the cache status for pixmap. The returned value is 0 or 1.

Tk_SetCacheStatusPixmap sets the cache status pixmap to status. There is no return value. A pixmap that is cached is not destroyed when it is no longer needed. Instead, it remains in the Tk hash table for later use.

Tk_DefaultCacheStatus returns the default cache status. The returned value is 0 or 1.

Tk_SetDefaultCacheStatus returns the default cache status to status. Pixmaps that are loaded get this cache status by default.

BUGS
In determining whether an existing pixmap can be used to satisfy a new request, Tk_GetPixmap considers only the immediate value of its id argument. For example, when a file name is passed to Tk_GetPixmap, Tk_GetPixmap will assume it is safe to re-use an existing pixmap 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