head	1.18;
access;
symbols
	core-8-5-9:1.14
	core-8-5-8:1.14
	macosx-cocoa-merge:1.18
	macosx-cocoa-premerge:1.18
	macosx-carbon-freeze:1.18
	core-8-5-7:1.14
	core-8-5-6:1.14
	core-8-6-b1:1.16
	core-8-6-a3:1.15
	core-8-5-5:1.14
	core-8-6-a2:1.15
	core-8-5-4:1.14
	core-8-5-3:1.14
	core-8-6-a1:1.14
	core-8-4-19:1.5.2.1
	core-8-5-branch:1.14.0.2
	core-8-5-2:1.14
	core-8-4-18:1.5.2.1
	core-8-5-1:1.14
	core-8-4-17:1.5.2.1
	core-8-5-0:1.14
	core-8-5-b3:1.13
	core-8-5-b2:1.12
	core-8-4-16:1.5.2.1
	core-8-5-b1:1.10
	core-stablilizer-merge:1.10
	core-stabilizer-branch:1.10.0.2
	core-stabilizer-merge:1.14
	core-8-4-15:1.5.2.1
	core-8-5-a6:1.10
	core-8-5-a5:1.9
	core-8-4-14:1.5.2.1
	core-8-5-a4:1.9
	core-8-4-13:1.5.2.1
	core-8-4-12:1.5.2.1
	core-8-4-11:1.5.2.1
	core-8-5-a3:1.8
	core-8-4-10:1.5
	core-8-4-9-branch:1.5.0.6
	core-8-5-a2:1.7
	core-8-4-9:1.5
	core-8-4-8:1.5
	core-8-4-7:1.5
	core-8-5-a1:1.5
	core-8-4-6:1.5
	core-8-4-5:1.5
	mistachkin-dev-branch:1.5.0.4
	core-8-4-4:1.5
	core-8-4-3:1.5
	core-8-4-branch:1.5.0.2
	core-8-4-2:1.5
	core-8-4-1:1.5
	core-8-3-5:1.3
	core-8-4-0:1.5
	macosx-8-4-merge-2002-08-31-trunk:1.5
	macosx-8-4-premerge-2002-08-31-branch:1.3.18.1
	macosx-8-4-premerge-2002-08-31-trunk:1.5
	macosx-8-4-merge-2002-08-30-branch:1.3.18.1
	macosx-8-4-merge-2002-08-30-trunk:1.5
	macosx-8-4-merge-2002-08-20-branch:1.3.18.1
	macosx-8-4-merge-2002-08-20-trunk:1.5
	core-8-4-b2:1.5
	core-8-4-b1:1.3
	macosx-premerge-6-9-02:1.3
	core-8-4-a4:1.3
	core-8-3-4:1.3
	macosx-8-4-branch:1.3.0.18
	macosx-8-4-branchpoint:1.3
	core-8-4-a3:1.3
	core-8-3-3:1.3
	dgp-privates-into-namespace:1.3.0.16
	tclpro-1-5-0:1.3
	core-8-4-win-speedup:1.3.0.14
	core-8-4-a2:1.3
	tclpro-1-4-1:1.3
	tclpro-1-4-0:1.3
	core-8-3-2:1.3
	ajuba-ajuba2-2-1-base:1.3
	ajuba-ajuba2-2-0:1.3
	core-8-4-a1:1.3
	core-8-3-1-branch:1.3.0.12
	core-8-3-1:1.3
	scriptics-sc-2-0-b5:1.3
	scriptics-sc-2-0-fixed:1.3
	scriptics-sc-2-0-b2:1.3
	scriptics-sc-2-0-b1:1.3
	core-8-3-0:1.3
	core-8-3-b2:1.3
	core-8-3-b1:1.3
	scriptics-sc-1-1:1.3
	scriptics-sc-1-1-b1:1.3
	core-8-2-3:1.3
	scriptics-sc-1-1-branch:1.3.0.10
	scriptics-sc-1-1-base:1.3
	scriptics-sc-1-0:1.3
	scriptics-sc-1-0-branch:1.3.0.8
	scriptics-sc-1-0-base:1.3
	core-8-2-2:1.3
	core-8-2-1:1.3
	scriptics-bc-1-0-b1:1.3
	core-8-2-1-branch:1.3.0.6
	scriptics-tclpro-1-3-0:1.3
	core-8-2-0:1.3
	core-8-2-b3-branch:1.3.0.4
	core-8-2-b3-base:1.3
	scriptics-tclpro-1-3-b4:1.3
	core-8-2-b2:1.3
	scriptics-tclpro-1-3-b3:1.3
	core-8-2-b1:1.3
	scriptics-tclpro-1-3-b2:1.3
	merge-to-mainline-5/21/99:1.3
	scriptics-tclpro-1-3-b2-branch:1.3.0.2
	core-8-1-1:1.3
	scriptics-tclpro-1-3-b1:1.3
	core-8-1-1-base:1.3
	core-8-1-0:1.3
	merge-to-mainline-4-29-99:1.3
	merge-to-mainline-4-23-99:1.3
	core-8-1-branch-old:1.1.0.4
	core-8-0-6-branch:1.2.0.6
	core-8-0-6-base:1.2
	core-8-0-5:1.2
	core-8-1-b3:1.1.4.4
	core-8-1-b2:1.1.4.2
	dev-8-1-stubs-branch:1.1.4.2.0.2
	dev-stubs-branch:1.2.0.4
	scriptics-tclpro-1-2:1.2
	scriptics-tclpro-1-2-b2:1.2
	core-8-1-merge-2/10/99:1.2
	core-8-0-5-branch:1.2.0.2
	core-8-0-5-base:1.2
	scriptics-tclpro-1-2-b1:1.2
	scriptics-tclpro-1-2-a1:1.2
	core-8-1-b1:1.1.4.2
	core-8-0-4:1.2
	core-8-1-a2:1.1.4.1
	core-8-0-2:1.1
	core-8-0-3:1.2;
locks; strict;
comment	@# @;


1.18
date	2009.05.04.09.12.33;	author dkf;	state Exp;
branches;
next	1.17;

1.17
date	2009.02.27.23.23.36;	author nijtmans;	state Exp;
branches;
next	1.16;

1.16
date	2008.11.05.22.58.30;	author nijtmans;	state Exp;
branches;
next	1.15;

1.15
date	2008.06.30.22.57.01;	author dkf;	state Exp;
branches;
next	1.14;

1.14
date	2007.12.13.15.23.43;	author dgp;	state Exp;
branches;
next	1.13;

1.13
date	2007.10.29.16.04.12;	author dkf;	state Exp;
branches;
next	1.12;

1.12
date	2007.10.26.20.13.22;	author dgp;	state Exp;
branches;
next	1.11;

1.11
date	2007.10.24.14.32.56;	author dkf;	state Exp;
branches;
next	1.10;

1.10
date	2007.01.05.00.00.48;	author nijtmans;	state Exp;
branches
	1.10.2.1;
next	1.9;

1.9
date	2005.06.21.22.58.53;	author dkf;	state Exp;
branches;
next	1.8;

1.8
date	2005.04.06.21.11.53;	author dkf;	state Exp;
branches;
next	1.7;

1.7
date	2004.09.19.16.05.36;	author dkf;	state Exp;
branches;
next	1.6;

1.6
date	2004.08.22.15.43.20;	author dkf;	state Exp;
branches;
next	1.5;

1.5
date	2002.08.08.01.43.10;	author hobbs;	state Exp;
branches
	1.5.2.1;
next	1.4;

1.4
date	2002.08.05.04.30.38;	author dgp;	state Exp;
branches;
next	1.3;

1.3
date	99.04.16.01.51.08;	author stanton;	state Exp;
branches
	1.3.18.1;
next	1.2;

1.2
date	98.09.14.18.22.48;	author stanton;	state Exp;
branches;
next	1.1;

1.1
date	98.04.01.09.40.03;	author rjohnson;	state Exp;
branches
	1.1.4.1;
next	;

1.1.4.1
date	98.09.29.00.25.08;	author stanton;	state Exp;
branches;
next	1.1.4.2;

1.1.4.2
date	98.09.30.02.15.53;	author stanton;	state Exp;
branches;
next	1.1.4.3;

1.1.4.3
date	99.03.30.04.11.56;	author stanton;	state Exp;
branches;
next	1.1.4.4;

1.1.4.4
date	99.04.07.00.36.10;	author stanton;	state Exp;
branches;
next	;

1.3.18.1
date	2002.08.20.20.27.00;	author das;	state Exp;
branches;
next	;

1.5.2.1
date	2005.06.21.23.01.36;	author dkf;	state Exp;
branches;
next	;

1.10.2.1
date	2007.11.01.16.37.12;	author dgp;	state Exp;
branches;
next	;


desc
@@


1.18
log
@Purge mention of interp->result. [Bug 2431507]
@
text
@'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" 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.17 2009/02/27 23:23:36 nijtmans Exp $
'\" 
.so man.macros
.TH Tk_AllocBitmapFromObj 3 8.1 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, Tk_FreeBitmap \- maintain database of single-plane pixmaps
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Pixmap
\fBTk_AllocBitmapFromObj(\fIinterp, tkwin, objPtr\fB)\fR
.sp
Pixmap
\fBTk_GetBitmap(\fIinterp, tkwin, info\fB)\fR
.sp
Pixmap
\fBTk_GetBitmapFromObj(\fItkwin, objPtr\fB)\fR
.sp
int
\fBTk_DefineBitmap(\fIinterp, name, source, width, height\fB)\fR
.sp
const char *
\fBTk_NameOfBitmap(\fIdisplay, bitmap\fB)\fR
.sp
\fBTk_SizeOfBitmap(\fIdisplay, bitmap, widthPtr, heightPtr\fB)\fR
.sp
\fBTk_FreeBitmapFromObj(\fItkwin, objPtr\fB)\fR
.sp
\fBTk_FreeBitmap(\fIdisplay, bitmap\fB)\fR
.SH ARGUMENTS
.AS "unsigned long" *pixelPtr
.AP Tcl_Interp *interp in
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 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 is not cached.
.AP "const char" *name in
Name for new bitmap to be defined.
.AP "const void" *source in
Data for bitmap, in standard bitmap format.
Must be stored in static memory whose value will never change.
.AP "int" width in
Width of bitmap.
.AP "int" height in
Height of bitmap.
.AP "int" *widthPtr out
Pointer to word to fill in with \fIbitmap\fR's width.
.AP "int" *heightPtr out
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_AllocBitmapFromObj\fR or
\fBTk_GetBitmap\fR.
.BE
.SH DESCRIPTION
.PP
These procedures manage a collection of bitmaps (one-plane pixmaps)
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_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:
.TP 20
\fB@@\fIfileName\fR
\fIFileName\fR must be the name of a file containing a bitmap
description in the standard X11 format.
.TP 20
\fIname\fR
\fIName\fR must be the name of a bitmap defined previously with
a call to \fBTk_DefineBitmap\fR.  The following names are pre-defined
by Tk:
.RS
.TP 12
\fBerror\fR
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.
.TP 12
\fBgray50\fR
50% gray: a checkerboard pattern where every other bit is on.
.TP 12
\fBgray25\fR
25% gray: a checkerboard pattern where one out of every four bits is on.
.TP 12
\fBgray12\fR
12.5% gray: a pattern where one-eighth of the bits are on, consisting of
every fourth pixel in every other row.
.TP 12
\fBhourglass\fR
An hourglass symbol.
.TP 12
\fBinfo\fR
A large letter
.QW i .
.TP 12
\fBquesthead\fR
The silhouette of a human head, with a question mark in it.
.TP 12
\fBquestion\fR
A large question-mark.
.TP 12
\fBwarning\fR
A large exclamation point.
.PP
In addition, the following pre-defined names are available only on the
\fBMacintosh\fR platform:
.TP 12
\fBdocument\fR
A generic document.
.TP 12
\fBstationery\fR
Document stationery.
.TP 12
\fBedition\fR
The \fIedition\fR symbol.
.TP 12
\fBapplication\fR
Generic application icon.
.TP 12
\fBaccessory\fR
A desk accessory.
.TP 12
\fBfolder\fR
Generic folder icon.
.TP 12
\fBpfolder\fR
A locked folder.
.TP 12
\fBtrash\fR
A trash can.
.TP 12
\fBfloppy\fR
A floppy disk.
.TP 12
\fBramdisk\fR
A floppy disk with chip.
.TP 12
\fBcdrom\fR
A cd disk icon.
.TP 12
\fBpreferences\fR
A folder with prefs symbol.
.TP 12
\fBquerydoc\fR
A database document icon.
.TP 12
\fBstop\fR
A stop sign.
.TP 12
\fBnote\fR
A face with balloon words.
.TP 12
\fBcaution\fR
A triangle with an exclamation point.
.RE
.LP
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 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.
.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 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.
.PP
\fBTk_DefineBitmap\fR associates a name with
in-memory bitmap data so that the name can be used in later
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
describe the bitmap.
\fBTk_DefineBitmap\fR normally returns \fBTCL_OK\fR; if an error occurs
(e.g. a bitmap named \fInameId\fR has already been defined) then
\fBTCL_ERROR\fR is returned and an error message is left in
interpreter \fIinterp\fR's result.
Note:  \fBTk_DefineBitmap\fR expects the memory pointed to by
\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.
.PP
Typically \fBTk_DefineBitmap\fR is used by \fB#include\fR-ing a
bitmap file directly into a C program and then referencing
the variables defined by the file.
For example, suppose there exists a file \fBstip.bitmap\fR,
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:
.CS
Pixmap bitmap;
#include "stip.bitmap"
Tk_DefineBitmap(interp, "foo", stip_bits,
    stip_width, stip_height);
\&...
bitmap = Tk_GetBitmap(interp, tkwin, "foo");
.CE
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:
.CS
Pixmap bitmap;
bitmap = Tk_GetBitmap(interp, tkwin, "@@stip.bitmap");
.CE
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
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_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR should generally
be used in preference to Xlib procedures like \fBXReadBitmapFile\fR.
.PP
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
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 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_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_AllocBitmapFromObj\fR or
\fBTk_GetBitmap\fR.
.PP
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.
.SH BUGS
.PP
In determining whether an existing bitmap can be used to satisfy
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
see whether the file itself has changed, or whether the current
directory has changed, thereby causing the name to refer to
a different file.
.SH KEYWORDS
bitmap, pixmap
@


1.17
log
@[Feature Request 2636558] Tk_DefineBitmap
and Tk_GetBitmapFromData signature problem
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: GetBitmap.3,v 1.16 2008/11/05 22:58:30 nijtmans Exp $
d214 1
a214 1
\fIinterp->result\fR.
@


1.16
log
@fix [Bug 1866774 ] Remove X10 references from docs
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: GetBitmap.3,v 1.15 2008/06/30 22:57:01 dkf Exp $
d54 1
a54 1
.AP "const char" *source in
@


1.15
log
@Minor doc updates (removing out of date changebars, improving typedef formatting,
 etc.)
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: GetBitmap.3,v 1.14 2007/12/13 15:23:43 dgp Exp $
d86 1
a86 1
description in the standard X11 or X10 format.
@


1.14
log
@merge stable branch onto HEAD
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: GetBitmap.3,v 1.10.2.1 2007/11/01 16:37:12 dgp Exp $
a70 1

a285 1

d287 1
a296 1

@


1.13
log
@Lots more GOOBE stuff. Now works with 'make html'!
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: GetBitmap.3,v 1.12 2007/10/26 20:13:22 dgp Exp $
@


1.12
log
@        * doc/*.1:              Revert doc changes that broke
        * doc/*.3:              `make html` so we can get the release
        * doc/*.n:              out the door.
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: GetBitmap.3,v 1.10 2007/01/05 00:00:48 nijtmans Exp $
d51 1
a51 1
resulting Pixmap isn't cached.
d96 3
a98 2
The international "don't" symbol:  a circle with a diagonal line
across it.
d117 2
a118 1
A large letter ``i''.
d185 1
a185 1
message is left in \fIinterp\fR's result if \fIinterp\fR isn't
d198 1
a198 1
\fBTk_GetBitmapFromObj\fR doesn't actually create the bitmap; the bitmap
d217 1
a217 1
\fIsource\fR to be static:  \fBTk_DefineBitmap\fR doesn't make
@


1.11
log
@Lots of improvements to look and feel of manual pages
@
text
@d116 1
a116 2
A large letter
.QW i .
@


1.10
log
@various "const" additions, in line with TIP #27
fix bug #1627732
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: GetBitmap.3,v 1.9 2005/06/21 22:58:53 dkf Exp $
d116 2
a117 1
A large letter ``i''.
@


1.10.2.1
log
@merge updates from HEAD
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: GetBitmap.3,v 1.10 2007/01/05 00:00:48 nijtmans Exp $
d51 1
a51 1
resulting Pixmap is not cached.
d96 2
a97 3
The international
.QW don't
symbol:  a circle with a diagonal line across it.
d116 1
a116 2
A large letter
.QW i .
d183 1
a183 1
message is left in \fIinterp\fR's result if \fIinterp\fR is not
d196 1
a196 1
\fBTk_GetBitmapFromObj\fR does not actually create the bitmap; the bitmap
d215 1
a215 1
\fIsource\fR to be static:  \fBTk_DefineBitmap\fR does not make
@


1.9
log
@Fix silly error in SYNOPSIS of Tk_AllocBitmapFromObj doc [1224983]
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: GetBitmap.3,v 1.8 2005/04/06 21:11:53 dkf Exp $
d31 1
a31 1
CONST char *
d49 1
a49 1
.AP "CONST char" *info in
d52 1
a52 1
.AP "CONST char" *name in
d54 1
a54 1
.AP "CONST char" *source in
@


1.8
log
@Purge old and inaccurate .VS/.VE macros.
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: GetBitmap.3,v 1.7 2004/09/19 16:05:36 dkf Exp $
d20 1
a20 1
\fBTk_GetBitmapFromObj(\fIinterp, tkwin, objPtr\fB)\fR
@


1.7
log
@Standardize style of section refs & public symbols. Remove displayed tabs
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: GetBitmap.3,v 1.6 2004/08/22 15:43:20 dkf Exp $
a18 1
.VS 8.1
a26 1
.VE
a35 1
.VS 8.1
a36 1
.VE
a45 1
.VS 8.1 br
a51 1
.VE
a78 1
.VS 8.1
a83 1
.VE
a97 1
.VS "" br
a100 1
.VE
a103 1
.VS "" br
a106 1
.VE
a178 1
.VS 8.1
a201 1
.VE
a227 1
.VS
a235 1
.VE
a239 1
.VS
a243 1
.VE
a275 1
.VS 8.1
a284 1
.VE
@


1.6
log
@More doc fixes from Mikhail Kolesnitchenko. [Patch 1013520]
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: GetBitmap.3,v 1.5 2002/08/08 01:43:10 hobbs Exp $
d224 1
a224 1
\fBTk_DefineBitmap\fR normally returns TCL_OK;  if an error occurs
d226 1
a226 1
TCL_ERROR is returned and an error message is left in
d247 1
a247 1
	stip_width, stip_height);
@


1.5
log
@	* doc/GetBitmap.3: removed doc refs to deprecated
	Tk_GetBitmapFromData. [Bug #590379]
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: GetBitmap.3,v 1.4 2002/08/05 04:30:38 dgp Exp $
d185 1
a185 1
A face with ballon words.
@


1.5.2.1
log
@Fix silly error in SYNOPSIS of Tk_AllocBitmapFromObj [Bug 1224983]
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: GetBitmap.3,v 1.5 2002/08/08 01:43:10 hobbs Exp $
d21 1
a21 1
\fBTk_AllocBitmapFromObj(\fIinterp, tkwin, objPtr\fB)\fR
@


1.4
log
@Applied companion patch for Tcl Patch 585105,
updating Tk to use Tcl 8.4's fully CONST-ified
interface, and fully CONSTifying Tk at the
same time.

This patch includes purging Tk of its last
direct access to interp->result.  [Bug 589853]

The substantial changes include copying
event sequence strings into Tcl_DStrings
in tkBind.c, and copying [text] indices into
Tcl_DStrings because parsing them involved
overwriting them.  If this causes performance
trouble, that can be resolved by further
converting them to Tcl_Obj's.

The #defines USE_NON_CONST and USE_COMPAT_CONST
have the same effect for Tk as they do for Tcl.
(They actually change tcl.h)
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: GetBitmap.3,v 1.3 1999/04/16 01:51:08 stanton Exp $
d14 1
a14 1
Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, Tk_FreeBitmap, Tk_GetBitmapFromData \- maintain database of single-plane pixmaps
@


1.3
log
@* Merged 8.1 branch into the main trunk
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id$
d33 1
a33 1
char *
d60 1
a60 1
.AP char *source in
@


1.3.18.1
log
@merged with trunk at tag macosx-8-4-merge-2002-08-20-trunk
@
text
@d14 1
a14 1
Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, Tk_FreeBitmap \- maintain database of single-plane pixmaps
d33 1
a33 1
CONST char *
d60 1
a60 1
.AP "CONST char" *source in
@


1.2
log
@Replaced SCCS strings, fixed binary files
@
text
@d3 1
a3 1
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
d11 1
a11 1
.TH Tk_GetBitmap 3 8.0 Tk "Tk Library Procedures"
d14 1
a14 1
Tk_GetBitmap, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmap, Tk_GetBitmapFromData \- maintain database of single-plane pixmaps
d19 1
d21 8
a28 1
\fBTk_GetBitmap(\fIinterp, tkwin, id\fB)\fR
d31 1
a31 1
\fBTk_DefineBitmap(\fIinterp, nameId, source, width, height\fB)\fR
d33 1
a33 1
Tk_Uid
d38 4
d46 2
a47 1
Interpreter to use for error reporting.
d50 9
a58 3
.AP Tk_Uid id in
Description of bitmap;  see below for possible values.
.AP Tk_Uid nameId in
d74 2
a75 1
Identifier for a bitmap allocated by \fBTk_GetBitmap\fR.
d85 7
a91 5
\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:
d191 2
a192 1
Under normal conditions, \fBTk_GetBitmap\fR
d194 1
a194 1
occurs in creating the bitmap, such as when \fIid\fR refers
d196 20
a215 1
message is left in \fIinterp->result\fR.
d219 1
a219 1
calls to \fBTk_GetBitmap\fR.  The \fInameId\fR
d231 2
a232 1
by \fIsource\fR later in calls to \fBTk_GetBitmap\fR.
d242 1
d246 1
a246 1
Tk_DefineBitmap(interp, Tk_GetUid("foo"), stip_bits,
d249 1
a249 1
bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("foo"));
d251 1
d256 1
d259 1
a259 1
bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("@@stip.bitmap"));
d261 1
d267 1
a267 2
\fBTk_GetBitmap\fR maintains a
database of all the bitmaps that are currently in use.
d270 1
d272 2
a273 2
\fBTk_GetBitmap\fR should generally be used in preference to Xlib
procedures like \fBXReadBitmapFile\fR.
d275 1
a275 1
The bitmaps returned by \fBTk_GetBitmap\fR
d283 1
a283 1
Given an X Pixmap argument, it returns the \fIid\fR that was
d286 1
a286 1
call to \fBTk_GetBitmap\fR.
d291 2
a292 1
\fIbitmap\fR must have been created by \fBTk_GetBitmap\fR.
d294 11
a304 7
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.
d308 2
a309 2
a new request, \fBTk_GetBitmap\fR
considers only the immediate value of its \fIid\fR argument.  For
@


1.1
log
@Initial revision
@
text
@d8 1
a8 1
'\" SCCS: @@(#) GetBitmap.3 1.27 97/08/22 18:52:11
@


1.1.4.1
log
@initial tk8.1a2 version
@
text
@d3 1
a3 1
'\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
d8 1
a8 1
'\" SCCS: @@(#) GetBitmap.3 1.28 98/01/14 13:58:57
d11 1
a11 1
.TH Tk_AllocBitmapFromObj 3 8.1 Tk "Tk Library Procedures"
d14 1
a14 1
Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, Tk_FreeBitmap, Tk_GetBitmapFromData \- maintain database of single-plane pixmaps
a18 1
.VS 8.1
d20 1
a20 8
\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
a29 4
.VS 8.1
\fBTk_FreeBitmapFromObj(\fItkwin, objPtr\fB)\fR
.VE
.sp
d34 1
a34 2
Interpreter to use for error reporting; if NULL then no error message
is left after errors.
d37 3
a39 9
.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 char *info in
Same as \fIobjPtr\fR except description of bitmap is passed as a string and
resulting Pixmap isn't cached.
.VE
.AP char *name in
d55 1
a55 2
Identifier for a bitmap allocated by \fBTk_AllocBitmapFromObj\fR or
\fBTk_GetBitmap\fR.
d65 5
a69 7
.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
d169 1
a169 2
.VS 8.1
Under normal conditions, \fBTk_AllocBitmapFromObj\fR
d171 1
a171 1
occurs in creating the bitmap, such as when \fIobjPtr\fR refers
d173 1
a173 20
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
d177 1
a177 1
calls to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR.  The \fInameId\fR
d189 1
a189 2
by \fIsource\fR later in calls to \fBTk_AllocBitmapFromObj\fR or
\fBTk_GetBitmap\fR.
d220 2
a221 1
Tk maintains a database of all the bitmaps that are currently in use.
a223 1
When a bitmap is no longer used, Tk will release it automatically.
d225 2
a226 2
\fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR should generally
be used in preference to Xlib procedures like \fBXReadBitmapFile\fR.
d228 1
a228 1
The bitmaps returned by \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR
d236 1
a236 1
Given an X Pixmap argument, it returns the textual description that was
d239 1
a239 1
call to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR.
d244 1
a244 2
\fIbitmap\fR must have been created by \fBTk_AllocBitmapFromObj\fR or
\fBTk_GetBitmap\fR.
d246 7
a252 11
.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
d256 2
a257 2
a new request, \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR
consider only the immediate value of the string description.  For
@


1.1.4.2
log
@Merged 8.0.3 changes into 8.1
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: GetBitmap.3,v 1.2 1998/09/14 18:22:48 stanton Exp $
@


1.1.4.3
log
@* doc/GetBitmap.3:
* generic/tkBitmap.c (BitmapInit): Eliminated use of Tk_Uid's in
bitmaps.  Added a few CONST declarations.
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id$
d31 1
a31 1
\fBTk_DefineBitmap(\fIinterp, name, source, width, height\fB)\fR
d33 1
a33 1
char *
d54 1
a54 1
.AP CONST char *info in
d58 1
a58 1
.AP CONST char *name in
a241 1
.VS
d245 1
a245 1
Tk_DefineBitmap(interp, "foo", stip_bits,
d248 1
a248 1
bitmap = Tk_GetBitmap(interp, tkwin, "foo");
a249 1
.VE
a253 1
.VS
d256 1
a256 1
bitmap = Tk_GetBitmap(interp, tkwin, "@@stip.bitmap");
a257 1
.VE
@


1.1.4.4
log
@Minor fix to dist scripts
man page lint
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: GetBitmap.3,v 1.1.4.3 1999/03/30 04:11:56 stanton Exp $
d54 1
a54 1
.AP "CONST char" *info in
d58 1
a58 1
.AP "CONST char" *name in
@


