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 mes-
                                                     sage.

       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 (mea-
                                                     sured in pixels from  the
                                                     image's  upper-left  cor-
                                                     ner).

       int                   imageY        (in)      Y-coordinate  of   upper-
                                                     left  corner of region of
                                                     image to redisplay  (mea-
                                                     sured  in pixels from the
                                                     image's  upper-left  cor-
                                                     ner).

       int                   width         ((in))    Width  of region of image
                                                     to redisplay.
                                                     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_Size-
       OfImage:  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  redis-
       play  themselves.  The changeProc and clientData arguments to Tk_GetIm-
       age are used for this purpose.  changeProc will be called by  Tk  when-
       ever  a change occurs in the image;  it must match the following proto-
       type:
              typedef void Tk_ImageChangedProc(

SEE ALSO

       Tk_CreateImageType

KEYWORDS

       images, redisplay



Tk                                    4.0                       Tk_GetImage(3)