head	1.11;
access;
symbols
	core-8-5-9:1.9
	core-8-5-8:1.9
	macosx-cocoa-merge:1.11
	macosx-cocoa-premerge:1.11
	macosx-carbon-freeze:1.11
	core-8-5-7:1.9
	core-8-5-6:1.9
	core-8-6-b1:1.10
	core-8-6-a3:1.10
	core-8-5-5:1.9
	core-8-6-a2:1.10
	core-8-5-4:1.9
	core-8-5-3:1.9
	core-8-6-a1:1.9
	core-8-4-19:1.5
	core-8-5-branch:1.9.0.2
	core-8-5-2:1.9
	core-8-4-18:1.5
	core-8-5-1:1.9
	core-8-4-17:1.5
	core-8-5-0:1.9
	core-8-5-b3:1.8
	core-8-5-b2:1.7
	core-8-4-16:1.5
	core-8-5-b1:1.7
	core-stablilizer-merge:1.7
	core-stabilizer-branch:1.7.0.2
	core-stabilizer-merge:1.9
	core-8-4-15:1.5
	core-8-5-a6:1.7
	core-8-5-a5:1.6
	core-8-4-14:1.5
	core-8-5-a4:1.6
	core-8-4-13:1.5
	core-8-4-12:1.5
	core-8-4-11:1.5
	core-8-5-a3:1.6
	core-8-4-10:1.5
	core-8-4-9-branch:1.5.0.6
	core-8-5-a2:1.6
	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.4
	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.4.18.1
	macosx-8-4-premerge-2002-08-31-trunk:1.5
	macosx-8-4-merge-2002-08-30-branch:1.4.18.1
	macosx-8-4-merge-2002-08-30-trunk:1.5
	macosx-8-4-merge-2002-08-20-branch:1.4.18.1
	macosx-8-4-merge-2002-08-20-trunk:1.5
	core-8-4-b2:1.5
	core-8-4-b1:1.4
	macosx-premerge-6-9-02:1.4
	core-8-4-a4:1.4
	core-8-3-4:1.4
	macosx-8-4-branch:1.4.0.18
	macosx-8-4-branchpoint:1.4
	core-8-4-a3:1.4
	core-8-3-3:1.4
	dgp-privates-into-namespace:1.4.0.16
	tclpro-1-5-0:1.4
	core-8-4-win-speedup:1.4.0.14
	core-8-4-a2:1.4
	tclpro-1-4-1:1.4
	tclpro-1-4-0:1.4
	core-8-3-2:1.4
	ajuba-ajuba2-2-1-base:1.4
	ajuba-ajuba2-2-0:1.4
	core-8-4-a1:1.4
	core-8-3-1-branch:1.4.0.12
	core-8-3-1:1.4
	scriptics-sc-2-0-b5:1.4
	scriptics-sc-2-0-fixed:1.4
	scriptics-sc-2-0-b2:1.4
	scriptics-sc-2-0-b1:1.4
	core-8-3-0:1.4
	core-8-3-b2:1.4
	core-8-3-b1:1.4
	scriptics-sc-1-1:1.4
	scriptics-sc-1-1-b1:1.4
	core-8-2-3:1.4
	scriptics-sc-1-1-branch:1.4.0.10
	scriptics-sc-1-1-base:1.4
	scriptics-sc-1-0:1.4
	scriptics-sc-1-0-branch:1.4.0.8
	scriptics-sc-1-0-base:1.4
	core-8-2-2:1.4
	core-8-2-1:1.4
	scriptics-bc-1-0-b1:1.4
	core-8-2-1-branch:1.4.0.6
	scriptics-tclpro-1-3-0:1.4
	core-8-2-0:1.4
	core-8-2-b3-branch:1.4.0.2
	core-8-2-b3-base:1.4
	scriptics-tclpro-1-3-b4:1.4
	core-8-2-b2:1.4
	scriptics-tclpro-1-3-b3:1.4
	core-8-2-b1:1.4
	scriptics-tclpro-1-3-b2:1.4
	merge-to-mainline-5/21/99:1.4
	scriptics-tclpro-1-3-b2-branch:1.4.0.4
	core-8-1-1:1.4
	scriptics-tclpro-1-3-b1:1.4
	core-8-1-1-base:1.4
	core-8-1-0:1.4
	merge-to-mainline-4-29-99:1.4
	merge-to-mainline-4-23-99:1.4
	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.1
	core-8-1-b2:1.1.4.1
	dev-8-1-stubs-branch:1.1.4.1.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.1
	core-8-0-4:1.2
	core-8-1-a2:1.1
	core-8-0-2:1.1
	core-8-0-3:1.2;
locks; strict;
comment	@# @;


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

1.10
date	2008.06.30.22.57.01;	author dkf;	state Exp;
branches;
next	1.9;

1.9
date	2007.12.13.15.23.43;	author dgp;	state Exp;
branches;
next	1.8;

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

1.7
date	2007.01.05.00.00.48;	author nijtmans;	state Exp;
branches
	1.7.2.1;
next	1.6;

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

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

1.4
date	99.04.21.21.53.22;	author rjohnson;	state Exp;
branches
	1.4.18.1;
next	1.3;

1.3
date	99.04.16.18.26.12;	author surles;	state Exp;
branches;
next	1.2;

1.2
date	98.09.14.18.22.49;	author stanton;	state Exp;
branches
	1.2.8.1;
next	1.1;

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

1.1.4.1
date	98.09.30.02.15.55;	author stanton;	state Exp;
branches;
next	;

1.2.8.1
date	99.04.21.02.32.56;	author rjohnson;	state Exp;
branches;
next	;

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

1.7.2.1
date	2007.11.01.16.37.13;	author dgp;	state Exp;
branches;
next	;


desc
@@


1.11
log
@Purge mention of interp->result. [Bug 2431507]
@
text
@'\"
'\" Copyright (c) 1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 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: GetImage.3,v 1.10 2008/06/30 22:57:01 dkf Exp $
'\" 
.so man.macros
.TH Tk_GetImage 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_GetImage, Tk_RedrawImage, Tk_SizeOfImage, Tk_FreeImage \- use an image in a widget
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_Image
\fBTk_GetImage\fR(\fIinterp, tkwin, name, changeProc, clientData\fR)
.sp
\fBTk_RedrawImage\fR(\fIimage, imageX, imageY, width, height, drawable, drawableX, drawableY\fR)
.sp
\fBTk_SizeOfImage\fR(\fIimage, widthPtr, heightPtr\fR)
.sp
\fBTk_FreeImage\fR(\fIimage\fR)
.SH ARGUMENTS
.AS Tk_ImageChangedProc *changeProc
.AP Tcl_Interp *interp in
Place to leave error message.
.AP Tk_Window tkwin in
Window in which image will be used.
.AP "const char" *name in
Name of image.
.AP Tk_ImageChangedProc *changeProc in
Procedure for Tk to invoke whenever image content or size changes.
.AP ClientData clientData in
One-word value for Tk to pass to \fIchangeProc\fR.
.AP Tk_Image image in
Token for image instance;  must have been returned by a previous
call to \fBTk_GetImage\fR.
.AP int imageX in
X-coordinate of upper-left corner of region of image to redisplay
(measured in pixels from the image's upper-left corner).
.AP int imageY in
Y-coordinate of upper-left corner of region of image to redisplay
(measured in pixels from the image's upper-left corner).
.AP "int" width (in)
Width of region of image to redisplay.
.AP "int" height (in)
Height of region of image to redisplay.
.AP Drawable drawable in
Where to display image.  Must either be window specified to
\fBTk_GetImage\fR or a pixmap compatible with that window.
.AP int drawableX in
Where to display image in \fIdrawable\fR: this is the x-coordinate
in \fIdrawable\fR where x-coordinate \fIimageX\fR of the image
should be displayed.
.AP int drawableY in
Where to display image in \fIdrawable\fR: this is the y-coordinate
in \fIdrawable\fR where y-coordinate \fIimageY\fR of the image
should be displayed.
.AP "int" widthPtr out
Store width of \fIimage\fR (in pixels) here.
.AP "int" heightPtr out
Store height of \fIimage\fR (in pixels) here.
.BE
.SH DESCRIPTION
.PP
These procedures are invoked by widgets that wish to display images.
\fBTk_GetImage\fR is invoked by a widget when it first decides to
display an image.
\fIname\fR gives the name of the desired image and \fItkwin\fR
identifies the window where the image will be displayed.
\fBTk_GetImage\fR looks up the image in the table of existing
images and returns a token for a new instance of the image.
If the image does not exist then \fBTk_GetImage\fR returns NULL
and leaves an error message in interpreter \fIinterp\fR's result.
.PP
When a widget wishes to actually display an image it must
call \fBTk_RedrawImage\fR, identifying the image (\fIimage\fR),
a region within the image to redisplay (\fIimageX\fR, \fIimageY\fR,
\fIwidth\fR, and \fIheight\fR), and a place to display the
image (\fIdrawable\fR, \fIdrawableX\fR, and \fIdrawableY\fR).
Tk will then invoke the appropriate image manager, which will
display the requested portion of the image before returning.
.PP
A widget can find out the dimensions of an image by calling
\fBTk_SizeOfImage\fR:  the width and height will be stored
in the locations given by \fIwidthPtr\fR and \fIheightPtr\fR,
respectively.
.PP
When a widget is finished with an image (e.g., the widget is
being deleted or it is going to use a different image instead
of the current one), it must call \fBTk_FreeImage\fR to
release the image instance.
The widget should never again use the image token after passing
it to \fBTk_FreeImage\fR.
There must be exactly one call to \fBTk_FreeImage\fR for each
call to \fBTk_GetImage\fR.
.PP
If the contents or size of an image changes, then any widgets
using the image will need to find out about the changes so that
they can redisplay themselves.
The \fIchangeProc\fR and \fIclientData\fR arguments to
\fBTk_GetImage\fR are used for this purpose.
\fIchangeProc\fR will be called by Tk whenever a change occurs
in the image;  it must match the following prototype:
.CS
typedef void \fBTk_ImageChangedProc\fR(
        ClientData \fIclientData\fR,
        int \fIx\fR,
        int \fIy\fR,
        int \fIwidth\fR,
        int \fIheight\fR,
        int \fIimageWidth\fR,
        int \fIimageHeight\fR);
.CE
The \fIclientData\fR argument to \fIchangeProc\fR is the same as the
\fIclientData\fR argument to \fBTk_GetImage\fR.
It is usually a pointer to the widget record for the widget or
some other data structure managed by the widget.
The arguments \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR
identify a region within the image that must be redisplayed;
they are specified in pixels measured from the upper-left
corner of the image.
The arguments \fIimageWidth\fR and \fIimageHeight\fR give
the image's (new) size.
.SH "SEE ALSO"
Tk_CreateImageType
.SH KEYWORDS
images, redisplay
@


1.10
log
@Minor doc updates (removing out of date changebars, improving typedef formatting,
 etc.)
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: GetImage.3,v 1.9 2007/12/13 15:23:43 dgp Exp $
d78 1
a78 1
and leaves an error message in \fIinterp->result\fR.
@


1.9
log
@merge stable branch onto HEAD
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: GetImage.3,v 1.7.2.1 2007/11/01 16:37:13 dgp Exp $
a67 1

d110 8
a117 8
typedef void Tk_ImageChangedProc(
    ClientData \fIclientData\fR,
    int \fIx\fR,
    int \fIy\fR,
    int \fIwidth\fR,
    int \fIheight\fR,
    int \fIimageWidth\fR,
    int \fIimageHeight\fR);
a128 1

a130 1

@


1.8
log
@Lots more GOOBE stuff. Now works with 'make html'!
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: GetImage.3,v 1.7 2007/01/05 00:00:48 nijtmans Exp $
@


1.7
log
@various "const" additions, in line with TIP #27
fix bug #1627732
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: GetImage.3,v 1.6 2004/09/19 16:05:36 dkf Exp $
d78 1
a78 1
If the image doesn't exist then \fBTk_GetImage\fR returns NULL
@


1.7.2.1
log
@merge updates from HEAD
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: GetImage.3,v 1.7 2007/01/05 00:00:48 nijtmans Exp $
d78 1
a78 1
If the image does not exist then \fBTk_GetImage\fR returns NULL
@


1.6
log
@Standardize style of section refs & public symbols. Remove displayed tabs
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: GetImage.3,v 1.5 2002/08/05 04:30:38 dgp Exp $
d33 1
a33 1
.AP "CONST char" *name in
@


1.5
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: GetImage.3,v 1.4 1999/04/21 21:53:22 rjohnson Exp $
d112 7
a118 7
	ClientData \fIclientData\fR,
	int \fIx\fR,
	int \fIy\fR,
	int \fIwidth\fR,
	int \fIheight\fR,
	int \fIimageWidth\fR,
	int \fIimageHeight\fR);
@


1.4
log
@
Merged 8-1-0 into mainline.
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: GetImage.3,v 1.3 1999/04/16 18:26:12 surles Exp $
d33 1
a33 1
.AP char *name in
@


1.4.18.1
log
@merged with trunk at tag macosx-8-4-merge-2002-08-20-trunk
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id$
d33 1
a33 1
.AP "CONST char" *name in
@


1.3
log
@fixed Tk doc bugs
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: GetImage.3,v 1.2 1998/09/14 18:22:49 stanton Exp $
@


1.2
log
@Replaced SCCS strings, fixed binary files
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id$
d82 1
a82 1
call \fBTk_RedrawWidget\fR, identifying the image (\fIimage\fR),
@


1.2.8.1
log
@
Merged with mainline.
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: GetImage.3,v 1.3 1999/04/16 18:26:12 surles Exp $
d82 1
a82 1
call \fBTk_RedrawImage\fR, identifying the image (\fIimage\fR),
@


1.1
log
@Initial revision
@
text
@d8 1
a8 1
'\" SCCS: @@(#) GetImage.3 1.8 96/03/26 18:10:29
@


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


