# 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.
#
#
=head1 NAME
Tk_GetImage, Tk_RedrawImage, Tk_SizeOfImage, Tk_FreeImage - use an image in a widget
=for category C Programming
=head1 SYNOPSIS
B<#include E<lt>tk.hE<gt>>
Tk_Image
B<Tk_GetImage>(I<interp, tkwin, name, changeProc, clientData>)
B<Tk_RedrawImage>(I<image, imageX, imageY, width, height, drawable, drawableX, drawableY>)
B<Tk_SizeOfImage>(I<image, widthPtr, heightPtr>)
B<Tk_FreeImage>(I<image>)
=head1 ARGUMENTS
=over 4
=item Tcl_Interp *interp (in)
Place to leave error message.
=item Tk_Window tkwin (in)
Window in which image will be used.
=item char *name (in)
Name of image.
=item Tk_ImageChangedProc *changeProc (in)
Procedure for Tk to invoke whenever image content or size changes.
=item ClientData clientData (in)
One-word value for Tk to pass to I<changeProc>.
=item Tk_Image image (in)
Token for image instance; must have been returned by a previous
call to B<Tk_GetImage>.
=item 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).
=item 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).
=item "int" width ((in))
Width of region of image to redisplay.
=item "int" height ((in))
Height of region of image to redisplay.
=item Drawable drawable (in)
Where to display image. Must either be window specified to
B<Tk_GetImage> or a pixmap compatible with that window.
=item int drawableX (in)
Where to display image in I<drawable>: this is the x-coordinate
in I<drawable> where x-coordinate I<imageX> of the image
should be displayed.
=item int drawableY (in)
Where to display image in I<drawable>: this is the y-coordinate
in I<drawable> where y-coordinate I<imageY> of the image
should be displayed.
=item "int" widthPtr (out)
Store width of I<image> (in pixels) here.
=item "int" heightPtr (out)
Store height of I<image> (in pixels) here.
=back
=head1 DESCRIPTION
These procedures are invoked by widgets that wish to display images.
B<Tk_GetImage> is invoked by a widget when it first decides to
display an image.
I<name> gives the name of the desired image and I<tkwin>
identifies the window where the image will be displayed.
B<Tk_GetImage> looks up the image in the table of existing
images and returns a token for a new instance of the image.
If the image doesn't exist then B<Tk_GetImage> returns NULL
and leaves an error message in I<interp-E<gt>result>.
When a widget wishes to actually display an image it must
call B<Tk_RedrawWidget>, identifying the image (I<image>),
a region within the image to redisplay (I<imageX>, I<imageY>,
I<width>, and I<height>), and a place to display the
image (I<drawable>, I<drawableX>, and I<drawableY>).
Tk will then invoke the appropriate image manager, which will
display the requested portion of the image before returning.
A widget can find out the dimensions of an image by calling
B<Tk_SizeOfImage>: the width and height will be stored
in the locations given by I<widthPtr> and I<heightPtr>,
respectively.
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 B<Tk_FreeImage> to
release the image instance.
The widget should never again use the image token after passing
it to B<Tk_FreeImage>.
There must be exactly one call to B<Tk_FreeImage> for each
call to B<Tk_GetImage>.
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 I<changeProc> and I<clientData> arguments to
B<Tk_GetImage> are used for this purpose.
I<changeProc> will be called by Tk whenever a change occurs
in the image; it must match the following prototype:
typedef void Tk_ImageChangedProc(
ClientData clientData,
int x,
int y,
int width,
int height,
int imageWidth,
int imageHeight);
The I<clientData> argument to I<changeProc> is the same as the
I<clientData> argument to B<Tk_GetImage>.
It is usually a pointer to the widget record for the widget or
some other data structure managed by the widget.
The arguments I<x>, I<y>, I<width>, and I<height>
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 I<imageWidth> and I<imageHeight> give
the image's (new) size.
=head1 SEE ALSO
L<Tk::CrtImgType>
=head1 KEYWORDS
images, redisplay