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.

       char                  *name         (in)      Name      of
                                                     image.

       Tk_ImageChangedProc   *changeProc   (in)      Procedure
                                                     for   Tk  to
                                                     invoke when­
                                                     ever   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.
                                                     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 spec­
                                                     ified     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
                                                     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 dis­
       play 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 call­
       ing Tk_SizeOfImage:  the width and height will  be  stored

       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 wid­
       gets  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