NAME

       Tk_GetImage, Tk_RedrawImage, Tk_SizeOfImage, Tk_FreeImage - use an image in a widget

SYNOPSIS

       #include <tk.h>

       Tk_Image
       Tk_GetImage(interp, tkwin, name, changeProc, clientData)

       Tk_RedrawImage(image, imageX, imageY, width, height, drawable, drawableX, drawableY)

       Tk_SizeOfImage(image, widthPtr, heightPtr)

       Tk_FreeImage(image)

ARGUMENTS

       Tcl_Interp *interp (in)                       Place to leave error message.

       Tk_Window tkwin (in)                          Window in which image will be used.

       const char *name (in)                         Name of image.

       Tk_ImageChangedProc *changeProc (in)          Procedure  for  Tk to invoke whenever image content or size
                                                     changes.

       ClientData clientData (in)                    One-word value for Tk to pass to changeProc.

       Tk_Image image (in)                           Token for image instance;  must have  been  returned  by  a
                                                     previous call to Tk_GetImage.

       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).

       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).

       int width ((in))                              Width of region of image to redisplay.

       int height ((in))                             Height of region of image to redisplay.

       Drawable drawable (in)                        Where to display image.  Must either be window specified to
                                                     Tk_GetImage or a pixmap compatible with that window.

       int drawableX (in)                            Where  to  display  image  in  drawable:  this  is  the  x-
                                                     coordinate  in  drawable  where  x-coordinate imageX of the
                                                     image should be displayed.

       int drawableY (in)                            Where  to  display  image  in  drawable:  this  is  the  y-
                                                     coordinate  in  drawable  where  y-coordinate imageY of the
                                                     image should be displayed.

       int widthPtr (out)                            Store width of image (in pixels) here.

       int heightPtr (out)                           Store height of image (in pixels) here.
________________________________________________________________________________________________________________

DESCRIPTION

       These procedures are invoked by widgets that wish to display images.  Tk_GetImage is invoked by a  widget
       when it first decides to display an image.  name gives the name of the desired image and tkwin identifies
       the window where the image will be displayed.  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 does not exist then Tk_GetImage
       returns NULL and leaves an error message in interpreter interp's result.

       When a widget wishes to actually display an image it must  call  Tk_RedrawImage,  identifying  the  image
       (image),  a  region  within  the  image  to redisplay (imageX, imageY, width, and height), and a place to
       display the image (drawable, drawableX, and 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 Tk_SizeOfImage:  the width and height will be
       stored in the locations given by widthPtr and 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 Tk_FreeImage to release the image instance.
       The widget should never again use the image token after  passing  it  to  Tk_FreeImage.   There  must  be
       exactly one call to Tk_FreeImage for each call to 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  changeProc  and  clientData  arguments  to
       Tk_GetImage  are  used for this purpose.  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 clientData argument to changeProc is the same as the  clientData  argument  to  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 x, y, width, and 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 imageWidth and
       imageHeight give the image's (new) size.

SEE ALSO

       Tk_CreateImageType

KEYWORDS

       images, redisplay