diff options
Diffstat (limited to 'doc/GetBitmap.3')
-rw-r--r-- | doc/GetBitmap.3 | 52 |
1 files changed, 17 insertions, 35 deletions
diff --git a/doc/GetBitmap.3 b/doc/GetBitmap.3 index 69e319e..a9bd2c2 100644 --- a/doc/GetBitmap.3 +++ b/doc/GetBitmap.3 @@ -14,7 +14,6 @@ Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_Na .nf \fB#include <tk.h>\fR .sp -.VS 8.1 Pixmap \fBTk_AllocBitmapFromObj(\fIinterp, tkwin, objPtr\fB)\fR .sp @@ -23,19 +22,16 @@ Pixmap .sp Pixmap \fBTk_GetBitmapFromObj(\fItkwin, objPtr\fB)\fR -.VE .sp int \fBTk_DefineBitmap(\fIinterp, name, source, width, height\fB)\fR .sp -CONST char * +const char * \fBTk_NameOfBitmap(\fIdisplay, bitmap\fB)\fR .sp \fBTk_SizeOfBitmap(\fIdisplay, bitmap, widthPtr, heightPtr\fB)\fR .sp -.VS 8.1 \fBTk_FreeBitmapFromObj(\fItkwin, objPtr\fB)\fR -.VE .sp \fBTk_FreeBitmap(\fIdisplay, bitmap\fB)\fR .SH ARGUMENTS @@ -45,17 +41,15 @@ Interpreter to use for error reporting; if NULL then no error message is left after errors. .AP Tk_Window tkwin in Token for window in which the bitmap will be used. -.VS 8.1 br .AP Tcl_Obj *objPtr in/out String value describes desired bitmap; internal rep will be modified to cache pointer to corresponding Pixmap. -.AP "CONST char" *info in +.AP "const char" *info in Same as \fIobjPtr\fR except description of bitmap is passed as a string and -resulting Pixmap isn't cached. -.VE -.AP "CONST char" *name in +resulting Pixmap is not cached. +.AP "const char" *name in Name for new bitmap to be defined. -.AP "CONST char" *source in +.AP "const char" *source in Data for bitmap, in standard bitmap format. Must be stored in static memory whose value will never change. .AP "int" width in @@ -80,13 +74,11 @@ 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. .PP -.VS 8.1 \fBTk_AllocBitmapFromObj\fR returns a Pixmap identifier for a bitmap that matches the description in \fIobjPtr\fR and is suitable for use in \fItkwin\fR. It re-uses an existing bitmap, if possible, and creates a new one otherwise. \fIObjPtr\fR's value must have one of the following forms: -.VE .TP 20 \fB@\fIfileName\fR \fIFileName\fR must be the name of a file containing a bitmap @@ -99,21 +91,18 @@ by Tk: .RS .TP 12 \fBerror\fR -The international "don't" symbol: a circle with a diagonal line -across it. -.VS "" br +The international +.QW don't +symbol: a circle with a diagonal line across it. .TP 12 \fBgray75\fR 75% gray: a checkerboard pattern where three out of four bits are on. -.VE .TP 12 \fBgray50\fR 50% gray: a checkerboard pattern where every other bit is on. -.VS "" br .TP 12 \fBgray25\fR 25% gray: a checkerboard pattern where one out of every four bits is on. -.VE .TP 12 \fBgray12\fR 12.5% gray: a pattern where one-eighth of the bits are on, consisting of @@ -123,7 +112,8 @@ every fourth pixel in every other row. An hourglass symbol. .TP 12 \fBinfo\fR -A large letter ``i''. +A large letter +.QW i . .TP 12 \fBquesthead\fR The silhouette of a human head, with a question mark in it. @@ -180,18 +170,17 @@ A database document icon. A stop sign. .TP 12 \fBnote\fR -A face with ballon words. +A face with balloon words. .TP 12 \fBcaution\fR A triangle with an exclamation point. .RE .LP -.VS 8.1 Under normal conditions, \fBTk_AllocBitmapFromObj\fR returns an identifier for the requested bitmap. If an error occurs in creating the bitmap, such as when \fIobjPtr\fR refers to a non-existent file, then \fBNone\fR is returned and an error -message is left in \fIinterp\fR's result if \fIinterp\fR isn't +message is left in \fIinterp\fR's result if \fIinterp\fR is not NULL. \fBTk_AllocBitmapFromObj\fR caches information about the return value in \fIobjPtr\fR, which speeds up future calls to procedures such as \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmapFromObj\fR. @@ -204,13 +193,12 @@ return value, so \fBTk_GetBitmap\fR is less efficient than .PP \fBTk_GetBitmapFromObj\fR returns the token for an existing bitmap, given the window and description used to create the bitmap. -\fBTk_GetBitmapFromObj\fR doesn't actually create the bitmap; the bitmap +\fBTk_GetBitmapFromObj\fR does not actually create the bitmap; the bitmap must already have been created with a previous call to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR. The return value is cached in \fIobjPtr\fR, which speeds up future calls to \fBTk_GetBitmapFromObj\fR with the same \fIobjPtr\fR and \fItkwin\fR. -.VE .PP \fBTk_DefineBitmap\fR associates a name with in-memory bitmap data so that the name can be used in later @@ -219,12 +207,12 @@ argument gives a name for the bitmap; it must not previously have been used in a call to \fBTk_DefineBitmap\fR. The arguments \fIsource\fR, \fIwidth\fR, and \fIheight\fR describe the bitmap. -\fBTk_DefineBitmap\fR normally returns TCL_OK; if an error occurs +\fBTk_DefineBitmap\fR normally returns \fBTCL_OK\fR; if an error occurs (e.g. a bitmap named \fInameId\fR has already been defined) then -TCL_ERROR is returned and an error message is left in +\fBTCL_ERROR\fR 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 make +\fIsource\fR to be static: \fBTk_DefineBitmap\fR does not make a private copy of this memory, but uses the bytes pointed to by \fIsource\fR later in calls to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR. @@ -237,26 +225,22 @@ which was created by the \fBbitmap\fR program and contains a stipple pattern. The following code uses \fBTk_DefineBitmap\fR to define a new bitmap named \fBfoo\fR: -.VS .CS Pixmap bitmap; #include "stip.bitmap" Tk_DefineBitmap(interp, "foo", stip_bits, - stip_width, stip_height); + stip_width, stip_height); \&... bitmap = Tk_GetBitmap(interp, tkwin, "foo"); .CE -.VE 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 \fBTk_GetBitmap\fR: -.VS .CS Pixmap bitmap; bitmap = Tk_GetBitmap(interp, tkwin, "@stip.bitmap"); .CE -.VE 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 @@ -289,7 +273,6 @@ argument in the words pointed to by the \fIwidthPtr\fR and \fIbitmap\fR must have been created by \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR. .PP -.VS 8.1 When a bitmap is no longer needed, \fBTk_FreeBitmapFromObj\fR or \fBTk_FreeBitmap\fR should be called to release it. For \fBTk_FreeBitmapFromObj\fR the bitmap to release is specified @@ -299,7 +282,6 @@ with its Pixmap token. There should be exactly one call to \fBTk_FreeBitmapFromObj\fR or \fBTk_FreeBitmap\fR for each call to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR. -.VE .SH BUGS In determining whether an existing bitmap can be used to satisfy |