summaryrefslogtreecommitdiffstats
path: root/doc/GetBitmap.3
diff options
context:
space:
mode:
authorstanton <stanton>1999-04-16 01:51:06 (GMT)
committerstanton <stanton>1999-04-16 01:51:06 (GMT)
commit03656f44f81469f459031fa3a4a7b09c8bc77712 (patch)
tree31378e81bd58f8c726fc552d6b30cbf3ca07497b /doc/GetBitmap.3
parent404fc236f34304df53b7e44bc7971d786b87d453 (diff)
downloadtk-03656f44f81469f459031fa3a4a7b09c8bc77712.zip
tk-03656f44f81469f459031fa3a4a7b09c8bc77712.tar.gz
tk-03656f44f81469f459031fa3a4a7b09c8bc77712.tar.bz2
* Merged 8.1 branch into the main trunk
Diffstat (limited to 'doc/GetBitmap.3')
-rw-r--r--doc/GetBitmap.3136
1 files changed, 94 insertions, 42 deletions
diff --git a/doc/GetBitmap.3 b/doc/GetBitmap.3
index 4321cce..28b5cb1 100644
--- a/doc/GetBitmap.3
+++ b/doc/GetBitmap.3
@@ -1,42 +1,61 @@
'\"
'\" Copyright (c) 1990 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: GetBitmap.3,v 1.2 1998/09/14 18:22:48 stanton Exp $
+'\" RCS: @(#) $Id: GetBitmap.3,v 1.3 1999/04/16 01:51:08 stanton Exp $
'\"
.so man.macros
-.TH Tk_GetBitmap 3 8.0 Tk "Tk Library Procedures"
+.TH Tk_AllocBitmapFromObj 3 8.1 Tk "Tk Library Procedures"
.BS
.SH NAME
-Tk_GetBitmap, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmap, Tk_GetBitmapFromData \- maintain database of single-plane pixmaps
+Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, Tk_FreeBitmap, Tk_GetBitmapFromData \- maintain database of single-plane pixmaps
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
+.VS 8.1
Pixmap
-\fBTk_GetBitmap(\fIinterp, tkwin, id\fB)\fR
+\fBTk_GetBitmapFromObj(\fIinterp, tkwin, objPtr\fB)\fR
+.sp
+Pixmap
+\fBTk_GetBitmap(\fIinterp, tkwin, info\fB)\fR
+.sp
+Pixmap
+\fBTk_GetBitmapFromObj(\fItkwin, objPtr\fB)\fR
+.VE
.sp
int
-\fBTk_DefineBitmap(\fIinterp, nameId, source, width, height\fB)\fR
+\fBTk_DefineBitmap(\fIinterp, name, source, width, height\fB)\fR
.sp
-Tk_Uid
+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
.AS "unsigned long" *pixelPtr
.AP Tcl_Interp *interp in
-Interpreter to use for error reporting.
+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.
-.AP Tk_Uid id in
-Description of bitmap; see below for possible values.
-.AP Tk_Uid nameId in
+.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
+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
Name for new bitmap to be defined.
.AP char *source in
Data for bitmap, in standard bitmap format.
@@ -52,7 +71,8 @@ Pointer to word to fill in with \fIbitmap\fR's height.
.AP Display *display in
Display for which \fIbitmap\fR was allocated.
.AP Pixmap bitmap in
-Identifier for a bitmap allocated by \fBTk_GetBitmap\fR.
+Identifier for a bitmap allocated by \fBTk_AllocBitmapFromObj\fR or
+\fBTk_GetBitmap\fR.
.BE
.SH DESCRIPTION
@@ -62,11 +82,13 @@ 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
-\fBTk_GetBitmap\fR 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 possible, and
-creates a new one otherwise. At present, \fIid\fR must have
-one of the following forms:
+.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
@@ -166,15 +188,35 @@ A face with ballon words.
A triangle with an exclamation point.
.RE
.LP
-Under normal conditions, \fBTk_GetBitmap\fR
+.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 \fIid\fR refers
+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->result\fR.
+message is left in \fIinterp\fR's result if \fIinterp\fR isn't
+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.
+.PP
+\fBTk_GetBitmap\fR is identical to \fBTk_AllocBitmapFromObj\fR except
+that the description of the bitmap is specified with a string instead
+of an object. This prevents \fBTk_GetBitmap\fR from caching the
+return value, so \fBTk_GetBitmap\fR is less efficient than
+\fBTk_AllocBitmapFromObj\fR.
+.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
+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
-calls to \fBTk_GetBitmap\fR. The \fInameId\fR
+calls to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR. The \fInameId\fR
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
@@ -186,7 +228,8 @@ TCL_ERROR is returned and an error message is left in
Note: \fBTk_DefineBitmap\fR expects the memory pointed to by
\fIsource\fR to be static: \fBTk_DefineBitmap\fR doesn't make
a private copy of this memory, but uses the bytes pointed to
-by \fIsource\fR later in calls to \fBTk_GetBitmap\fR.
+by \fIsource\fR later in calls to \fBTk_AllocBitmapFromObj\fR or
+\fBTk_GetBitmap\fR.
.PP
Typically \fBTk_DefineBitmap\fR is used by \fB#include\fR-ing a
bitmap file directly into a C program and then referencing
@@ -196,36 +239,40 @@ 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, Tk_GetUid("foo"), stip_bits,
+Tk_DefineBitmap(interp, "foo", stip_bits,
stip_width, stip_height);
\&...
-bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("foo"));
+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, Tk_GetUid("@stip.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
requires the bitmap file to exist separately from the program.
.PP
-\fBTk_GetBitmap\fR maintains a
-database of all the bitmaps that are currently in use.
+Tk 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.
+When a bitmap is no longer used, Tk will release it automatically.
This approach can substantially reduce server overhead, so
-\fBTk_GetBitmap\fR should generally be used in preference to Xlib
-procedures like \fBXReadBitmapFile\fR.
+\fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR should generally
+be used in preference to Xlib procedures like \fBXReadBitmapFile\fR.
.PP
-The bitmaps returned by \fBTk_GetBitmap\fR
+The bitmaps returned by \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR
are shared, so callers should never modify them.
If a bitmap must be modified dynamically, then it should be
created by calling Xlib procedures such as \fBXReadBitmapFile\fR
@@ -233,28 +280,33 @@ or \fBXCreatePixmap\fR directly.
.PP
The procedure \fBTk_NameOfBitmap\fR is roughly the inverse of
\fBTk_GetBitmap\fR.
-Given an X Pixmap argument, it returns the \fIid\fR that was
+Given an X Pixmap argument, it returns the textual description that was
passed to \fBTk_GetBitmap\fR when the bitmap was created.
\fIBitmap\fR must have been the return value from a previous
-call to \fBTk_GetBitmap\fR.
+call to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR.
.PP
\fBTk_SizeOfBitmap\fR returns the dimensions of its \fIbitmap\fR
argument 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.
+\fIbitmap\fR must have been created by \fBTk_AllocBitmapFromObj\fR or
+\fBTk_GetBitmap\fR.
.PP
-When a bitmap returned by \fBTk_GetBitmap\fR
-is no longer needed, \fBTk_FreeBitmap\fR should be called to release it.
-There should be exactly one call to \fBTk_FreeBitmap\fR for
-each call to \fBTk_GetBitmap\fR.
-When a bitmap is no longer in use anywhere (i.e. it has been freed as
-many times as it has been gotten) \fBTk_FreeBitmap\fR will release
-it to the X server and delete it from the database.
+.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
+with the same information used to create it; for
+\fBTk_FreeBitmap\fR the bitmap to release is specified
+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
-a new request, \fBTk_GetBitmap\fR
-considers only the immediate value of its \fIid\fR argument. For
+a new request, \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR
+consider only the immediate value of the string description. For
example, when a file name is passed to \fBTk_GetBitmap\fR,
\fBTk_GetBitmap\fR will assume it is safe to re-use an existing
bitmap created from the same file name: it will not check to