About Us Documentation

Contact Site Map




Tk_GetBitmap(3)       Tk Library Procedures                   8.0



Tk_GetBitmap, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmap, Tk_GetBitmapFromData - main- tain database of single-plane pixmaps


#include <tk.h> Pixmap Tk_GetBitmap(interp, tkwin, id) int Tk_DefineBitmap(interp, nameId, source, width, height) Tk_Uid Tk_NameOfBitmap(display, bitmap) Tk_SizeOfBitmap(display, bitmap, widthPtr, heightPtr) Tk_FreeBitmap(display, bitmap)


Tcl_Interp *interp (in) Interpreter to use for error reporting. Tk_Window tkwin (in) Token for window in which the bitmap will be used. Tk_Uid id (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 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. Tk 1 Tk_GetBitmap(3) Tk Library Procedures 8.0 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_GetBitmap. _________________________________________________________________


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 possi- ble, 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 con- taining 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. Tk 2 Tk_GetBitmap(3) Tk Library Procedures 8.0 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. 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 ballon words. Tk 3 Tk_GetBitmap(3) Tk Library Procedures 8.0 caution A triangle with an exclama- tion point. 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 are currently in use. 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. Tk 4 Tk_GetBitmap(3) Tk Library Procedures 8.0 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 pro- cedures 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 argu- ment 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. 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 dif- ferent file.


bitmap, pixmap Tk 5 Prepared by Ready-to-Run Software, Inc.


Email addresses listed on this site may  NOT be used for unsolicited commercial email.

Ready-to-Run Software, Inc Privacy Statement

Portions (c)Copyright, 1996-2005 by Ready-to-Run Software, Inc
(All rights reserved.)
212 Cedar Cove
Lansing, NY 14882
Phone: 607 533 UNIX (8649)
Fax: 607 533 4002

To return to the Ready-to-Run Software WinPak Table of contents please presshere