summaryrefslogtreecommitdiffstats
path: root/doc/GetBitmap.3
diff options
context:
space:
mode:
Diffstat (limited to 'doc/GetBitmap.3')
-rw-r--r--doc/GetBitmap.352
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