#  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