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 doesn't exist then Tk_GetImage
       returns NULL and leaves an error message in interp->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

Tk                                                     4.0                                      Tk_GetImage(3tk)