2 '\" Copyright (c) 1990 The Regents of the University of California.
3 '\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
5 '\" See the file "license.terms" for information on usage and redistribution
6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
11 .TH Tk_AllocBitmapFromObj 3 8.1 Tk "Tk Library Procedures"
14 Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, Tk_FreeBitmap \- maintain database of single-plane pixmaps
21 \fBTk_GetBitmapFromObj(\fIinterp, tkwin, objPtr\fB)\fR
24 \fBTk_GetBitmap(\fIinterp, tkwin, info\fB)\fR
27 \fBTk_GetBitmapFromObj(\fItkwin, objPtr\fB)\fR
31 \fBTk_DefineBitmap(\fIinterp, name, source, width, height\fB)\fR
34 \fBTk_NameOfBitmap(\fIdisplay, bitmap\fB)\fR
36 \fBTk_SizeOfBitmap(\fIdisplay, bitmap, widthPtr, heightPtr\fB)\fR
39 \fBTk_FreeBitmapFromObj(\fItkwin, objPtr\fB)\fR
42 \fBTk_FreeBitmap(\fIdisplay, bitmap\fB)\fR
44 .AS "unsigned long" *pixelPtr
45 .AP Tcl_Interp *interp in
46 Interpreter to use for error reporting; if NULL then no error message
48 .AP Tk_Window tkwin in
49 Token for window in which the bitmap will be used.
51 .AP Tcl_Obj *objPtr in/out
52 String value describes desired bitmap; internal rep will be
53 modified to cache pointer to corresponding Pixmap.
54 .AP "CONST char" *info in
55 Same as \fIobjPtr\fR except description of bitmap is passed as a string and
56 resulting Pixmap isn't cached.
58 .AP "CONST char" *name in
59 Name for new bitmap to be defined.
60 .AP "CONST char" *source in
61 Data for bitmap, in standard bitmap format.
62 Must be stored in static memory whose value will never change.
67 .AP "int" *widthPtr out
68 Pointer to word to fill in with \fIbitmap\fR's width.
69 .AP "int" *heightPtr out
70 Pointer to word to fill in with \fIbitmap\fR's height.
71 .AP Display *display in
72 Display for which \fIbitmap\fR was allocated.
74 Identifier for a bitmap allocated by \fBTk_AllocBitmapFromObj\fR or
80 These procedures manage a collection of bitmaps (one-plane pixmaps)
81 being used by an application. The procedures allow bitmaps to be
82 re-used efficiently, thereby avoiding server overhead, and also
83 allow bitmaps to be named with character strings.
86 \fBTk_AllocBitmapFromObj\fR returns a Pixmap identifier for a bitmap
87 that matches the description in \fIobjPtr\fR and is suitable for use
88 in \fItkwin\fR. It re-uses an existing bitmap, if possible, and
89 creates a new one otherwise. \fIObjPtr\fR's value must have one
90 of the following forms:
94 \fIFileName\fR must be the name of a file containing a bitmap
95 description in the standard X11 or X10 format.
98 \fIName\fR must be the name of a bitmap defined previously with
99 a call to \fBTk_DefineBitmap\fR. The following names are pre-defined
104 The international "don't" symbol: a circle with a diagonal line
109 75% gray: a checkerboard pattern where three out of four bits are on.
113 50% gray: a checkerboard pattern where every other bit is on.
117 25% gray: a checkerboard pattern where one out of every four bits is on.
121 12.5% gray: a pattern where one-eighth of the bits are on, consisting of
122 every fourth pixel in every other row.
128 A large letter ``i''.
131 The silhouette of a human head, with a question mark in it.
134 A large question-mark.
137 A large exclamation point.
139 In addition, the following pre-defined names are available only on the
140 \fBMacintosh\fR platform:
149 The \fIedition\fR symbol.
152 Generic application icon.
170 A floppy disk with chip.
176 A folder with prefs symbol.
179 A database document icon.
185 A face with ballon words.
188 A triangle with an exclamation point.
192 Under normal conditions, \fBTk_AllocBitmapFromObj\fR
193 returns an identifier for the requested bitmap. If an error
194 occurs in creating the bitmap, such as when \fIobjPtr\fR refers
195 to a non-existent file, then \fBNone\fR is returned and an error
196 message is left in \fIinterp\fR's result if \fIinterp\fR isn't
197 NULL. \fBTk_AllocBitmapFromObj\fR caches information about the return
198 value in \fIobjPtr\fR, which speeds up future calls to procedures
199 such as \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmapFromObj\fR.
201 \fBTk_GetBitmap\fR is identical to \fBTk_AllocBitmapFromObj\fR except
202 that the description of the bitmap is specified with a string instead
203 of an object. This prevents \fBTk_GetBitmap\fR from caching the
204 return value, so \fBTk_GetBitmap\fR is less efficient than
205 \fBTk_AllocBitmapFromObj\fR.
207 \fBTk_GetBitmapFromObj\fR returns the token for an existing bitmap, given
208 the window and description used to create the bitmap.
209 \fBTk_GetBitmapFromObj\fR doesn't actually create the bitmap; the bitmap
210 must already have been created with a previous call to
211 \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR. The return
212 value is cached in \fIobjPtr\fR, which speeds up
213 future calls to \fBTk_GetBitmapFromObj\fR with the same \fIobjPtr\fR
217 \fBTk_DefineBitmap\fR associates a name with
218 in-memory bitmap data so that the name can be used in later
219 calls to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR. The \fInameId\fR
220 argument gives a name for the bitmap; it must not previously
221 have been used in a call to \fBTk_DefineBitmap\fR.
222 The arguments \fIsource\fR, \fIwidth\fR, and \fIheight\fR
224 \fBTk_DefineBitmap\fR normally returns TCL_OK; if an error occurs
225 (e.g. a bitmap named \fInameId\fR has already been defined) then
226 TCL_ERROR is returned and an error message is left in
227 \fIinterp->result\fR.
228 Note: \fBTk_DefineBitmap\fR expects the memory pointed to by
229 \fIsource\fR to be static: \fBTk_DefineBitmap\fR doesn't make
230 a private copy of this memory, but uses the bytes pointed to
231 by \fIsource\fR later in calls to \fBTk_AllocBitmapFromObj\fR or
234 Typically \fBTk_DefineBitmap\fR is used by \fB#include\fR-ing a
235 bitmap file directly into a C program and then referencing
236 the variables defined by the file.
237 For example, suppose there exists a file \fBstip.bitmap\fR,
238 which was created by the \fBbitmap\fR program and contains
240 The following code uses \fBTk_DefineBitmap\fR to define a
241 new bitmap named \fBfoo\fR:
245 #include "stip.bitmap"
246 Tk_DefineBitmap(interp, "foo", stip_bits,
247 stip_width, stip_height);
249 bitmap = Tk_GetBitmap(interp, tkwin, "foo");
252 This code causes the bitmap file to be read
253 at compile-time and incorporates the bitmap information into
254 the program's executable image. The same bitmap file could be
255 read at run-time using \fBTk_GetBitmap\fR:
259 bitmap = Tk_GetBitmap(interp, tkwin, "@stip.bitmap");
262 The second form is a bit more flexible (the file could be modified
263 after the program has been compiled, or a different string could be
264 provided to read a different file), but it is a little slower and
265 requires the bitmap file to exist separately from the program.
267 Tk maintains a database of all the bitmaps that are currently in use.
268 Whenever possible, it will return an existing bitmap rather
269 than creating a new one.
270 When a bitmap is no longer used, Tk will release it automatically.
271 This approach can substantially reduce server overhead, so
272 \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR should generally
273 be used in preference to Xlib procedures like \fBXReadBitmapFile\fR.
275 The bitmaps returned by \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR
276 are shared, so callers should never modify them.
277 If a bitmap must be modified dynamically, then it should be
278 created by calling Xlib procedures such as \fBXReadBitmapFile\fR
279 or \fBXCreatePixmap\fR directly.
281 The procedure \fBTk_NameOfBitmap\fR is roughly the inverse of
283 Given an X Pixmap argument, it returns the textual description that was
284 passed to \fBTk_GetBitmap\fR when the bitmap was created.
285 \fIBitmap\fR must have been the return value from a previous
286 call to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR.
288 \fBTk_SizeOfBitmap\fR returns the dimensions of its \fIbitmap\fR
289 argument in the words pointed to by the \fIwidthPtr\fR and
290 \fIheightPtr\fR arguments. As with \fBTk_NameOfBitmap\fR,
291 \fIbitmap\fR must have been created by \fBTk_AllocBitmapFromObj\fR or
295 When a bitmap is no longer needed, \fBTk_FreeBitmapFromObj\fR or
296 \fBTk_FreeBitmap\fR should be called to release it.
297 For \fBTk_FreeBitmapFromObj\fR the bitmap to release is specified
298 with the same information used to create it; for
299 \fBTk_FreeBitmap\fR the bitmap to release is specified
300 with its Pixmap token.
301 There should be exactly one call to \fBTk_FreeBitmapFromObj\fR
302 or \fBTk_FreeBitmap\fR for each call to \fBTk_AllocBitmapFromObj\fR or
307 In determining whether an existing bitmap can be used to satisfy
308 a new request, \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR
309 consider only the immediate value of the string description. For
310 example, when a file name is passed to \fBTk_GetBitmap\fR,
311 \fBTk_GetBitmap\fR will assume it is safe to re-use an existing
312 bitmap created from the same file name: it will not check to
313 see whether the file itself has changed, or whether the current
314 directory has changed, thereby causing the name to refer to