'\"'\" Copyright (c) 1990 The Regents of the University of California.'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.'\"'\" See the file "license.terms" for information on usage and redistribution'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.'\" '\" SCCS: @(#) GetBitmap.3 1.27 97/08/22 18:52:11'\" .so man.macros.TH Tk_GetBitmap 3 8.0 Tk "Tk Library Procedures".BS.SH NAMETk_GetBitmap, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmap, Tk_GetBitmapFromData \- maintain database of single-plane pixmaps.SH SYNOPSIS.nf\fB#include <tk.h>\fR.spPixmap\fBTk_GetBitmap(\fIinterp, tkwin, id\fB)\fR.spint\fBTk_DefineBitmap(\fIinterp, nameId, source, width, height\fB)\fR.spTk_Uid\fBTk_NameOfBitmap(\fIdisplay, bitmap\fB)\fR.sp\fBTk_SizeOfBitmap(\fIdisplay, bitmap, widthPtr, heightPtr\fB)\fR.sp\fBTk_FreeBitmap(\fIdisplay, bitmap\fB)\fR.SH ARGUMENTS.AS "unsigned long" *pixelPtr.AP Tcl_Interp *interp inInterpreter to use for error reporting..AP Tk_Window tkwin inToken for window in which the bitmap will be used..AP Tk_Uid id inDescription of bitmap;  see below for possible values..AP Tk_Uid nameId inName for new bitmap to be defined..AP char *source inData for bitmap, in standard bitmap format.Must be stored in static memory whose value will never change..AP "int" width inWidth of bitmap..AP "int" height inHeight of bitmap..AP "int" *widthPtr outPointer to word to fill in with \fIbitmap\fR's width..AP "int" *heightPtr outPointer to word to fill in with \fIbitmap\fR's height..AP Display *display inDisplay for which \fIbitmap\fR was allocated..AP Pixmap bitmap inIdentifier for a bitmap allocated by \fBTk_GetBitmap\fR..BE.SH DESCRIPTION.PPThese procedures manage a collection of bitmaps (one-plane pixmaps)being used by an application.  The procedures allow bitmaps to bere-used efficiently, thereby avoiding server overhead, and alsoallow bitmaps to be named with character strings..PP\fBTk_GetBitmap\fR takes as argument a Tk_Uid describing a bitmap.It returns a Pixmap identifier for a bitmap corresponding to thedescription.  It re-uses an existing bitmap, if possible, andcreates a new one otherwise.  At present, \fIid\fR must haveone of the following forms:.TP 20\fB@\fIfileName\fR\fIFileName\fR must be the name of a file containing a bitmapdescription in the standard X11 or X10 format..TP 20\fIname\fR\fIName\fR must be the name of a bitmap defined previously witha call to \fBTk_DefineBitmap\fR.  The following names are pre-definedby Tk:.RS.TP 12\fBerror\fRThe international "don't" symbol:  a circle with a diagonal lineacross it..VS "" br.TP 12\fBgray75\fR75% gray: a checkerboard pattern where three out of four bits are on..VE.TP 12\fBgray50\fR50% gray: a checkerboard pattern where every other bit is on..VS "" br.TP 12\fBgray25\fR25% gray: a checkerboard pattern where one out of every four bits is on..VE.TP 12\fBgray12\fR12.5% gray: a pattern where one-eighth of the bits are on, consisting ofevery fourth pixel in every other row..TP 12\fBhourglass\fRAn hourglass symbol..TP 12\fBinfo\fRA large letter ``i''..TP 12\fBquesthead\fRThe silhouette of a human head, with a question mark in it..TP 12\fBquestion\fRA large question-mark..TP 12\fBwarning\fRA large exclamation point..PPIn addition, the following pre-defined names are available only on the\fBMacintosh\fR platform:.TP 12\fBdocument\fRA generic document..TP 12\fBstationery\fRDocument stationery..TP 12\fBedition\fRThe \fIedition\fR symbol..TP 12\fBapplication\fRGeneric application icon..TP 12\fBaccessory\fRA desk accessory..TP 12\fBfolder\fRGeneric folder icon..TP 12\fBpfolder\fRA locked folder..TP 12\fBtrash\fRA trash can..TP 12\fBfloppy\fRA floppy disk..TP 12\fBramdisk\fRA floppy disk with chip..TP 12\fBcdrom\fRA cd disk icon..TP 12\fBpreferences\fRA folder with prefs symbol..TP 12\fBquerydoc\fRA database document icon..TP 12\fBstop\fRA stop sign..TP 12\fBnote\fRA face with ballon words..TP 12\fBcaution\fRA triangle with an exclamation point..RE.LPUnder normal conditions, \fBTk_GetBitmap\fRreturns an identifier for the requested bitmap.  If an erroroccurs in creating the bitmap, such as when \fIid\fR refersto a non-existent file, then \fBNone\fR is returned and an errormessage is left in \fIinterp->result\fR..PP\fBTk_DefineBitmap\fR associates a name within-memory bitmap data so that the name can be used in latercalls to \fBTk_GetBitmap\fR.  The \fInameId\fRargument gives a name for the bitmap;  it must not previouslyhave been used in a call to \fBTk_DefineBitmap\fR.The arguments \fIsource\fR, \fIwidth\fR, and \fIheight\fRdescribe the bitmap.\fBTk_DefineBitmap\fR normally returns TCL_OK;  if an error occurs(e.g. a bitmap named \fInameId\fR has already been defined) thenTCL_ERROR is returned and an error message is left in\fIinterp->result\fR.Note:  \fBTk_DefineBitmap\fR expects the memory pointed to by\fIsource\fR to be static:  \fBTk_DefineBitmap\fR doesn't makea private copy of this memory, but uses the bytes pointed toby \fIsource\fR later in calls to \fBTk_GetBitmap\fR..PPTypically \fBTk_DefineBitmap\fR is used by \fB#include\fR-ing abitmap file directly into a C program and then referencingthe variables defined by the file.For example, suppose there exists a file \fBstip.bitmap\fR,which was created by the \fBbitmap\fR program and containsa stipple pattern.The following code uses \fBTk_DefineBitmap\fR to define anew bitmap named \fBfoo\fR:.CSPixmap bitmap;#include "stip.bitmap"Tk_DefineBitmap(interp, Tk_GetUid("foo"), stip_bits,	stip_width, stip_height);\&...bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("foo"));.CEThis code causes the bitmap file to be readat compile-time and incorporates the bitmap information intothe program's executable image.  The same bitmap file could beread at run-time using \fBTk_GetBitmap\fR:.CSPixmap bitmap;bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("@stip.bitmap"));.CEThe second form is a bit more flexible (the file could be modifiedafter the program has been compiled, or a different string could beprovided to read a different file), but it is a little slower andrequires the bitmap file to exist separately from the program..PP\fBTk_GetBitmap\fR maintains adatabase of all the bitmaps that are currently in use.Whenever possible, it will return an existing bitmap ratherthan creating a new one.This approach can substantially reduce server overhead, so\fBTk_GetBitmap\fR should generally be used in preference to Xlibprocedures like \fBXReadBitmapFile\fR..PPThe bitmaps returned by \fBTk_GetBitmap\fRare shared, so callers should never modify them.If a bitmap must be modified dynamically, then it should becreated by calling Xlib procedures such as \fBXReadBitmapFile\fRor \fBXCreatePixmap\fR directly..PPThe procedure \fBTk_NameOfBitmap\fR is roughly the inverse of\fBTk_GetBitmap\fR.Given an X Pixmap argument, it returns the \fIid\fR that waspassed to \fBTk_GetBitmap\fR when the bitmap was created.\fIBitmap\fR must have been the return value from a previouscall to \fBTk_GetBitmap\fR..PP\fBTk_SizeOfBitmap\fR returns the dimensions of its \fIbitmap\fRargument in the words pointed to by the \fIwidthPtr\fR and\fIheightPtr\fR arguments.  As with \fBTk_NameOfBitmap\fR,\fIbitmap\fR must have been created by \fBTk_GetBitmap\fR..PPWhen a bitmap returned by \fBTk_GetBitmap\fRis no longer needed, \fBTk_FreeBitmap\fR should be called to release it.There should be exactly one call to \fBTk_FreeBitmap\fR foreach call to \fBTk_GetBitmap\fR.When a bitmap is no longer in use anywhere (i.e. it has been freed asmany times as it has been gotten) \fBTk_FreeBitmap\fR will releaseit to the X server and delete it from the database..SH BUGSIn determining whether an existing bitmap can be used to satisfya new request, \fBTk_GetBitmap\fRconsiders only the immediate value of its \fIid\fR argument.  Forexample, when a file name is passed to \fBTk_GetBitmap\fR,\fBTk_GetBitmap\fR will assume it is safe to re-use an existingbitmap created from the same file name:  it will not check tosee whether the file itself has changed, or whether the currentdirectory has changed, thereby causing the name to refer toa different file..SH KEYWORDSbitmap, pixmap