TkGetImage(3) Tk Library Procedures TkGetImage(3)

NAME
       TkGetImage,  TkRedrawImage,  TkSizeOfImage,  TkFreeImage  -  use an
       image in a widget

SYNOPSIS
       ##iinncclluuddee <>

       TkImage
       TTkkGGeettIImmaaggee(interp, tkwin, name, changeProc, clientData)

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

       TTkkSSiizzeeOOffIImmaaggee(image, widthPtr, heightPtr)

       TTkkFFrreeeeIImmaaggee(image)

AARRGGUUMMEENNTTSS
       TclInterp            *interp       (in)      Place to leave error mes-
                                                     sage.

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

       CONST char            *name         (in)      Name of image.

       TkImageChangedProc   *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.

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

       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.

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

       Drawable              drawable      (in)      Where  to  display image.
                                                     Must  either  be   window
                                                     specified  to TTkkGGeettIImmaaggee
                                                     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.
       TTkkGGeettIImmaaggee 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.  TTkkGGeettIImmaaggee 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  TTkkGGeettIImmaaggee
       returns NULL and leaves an error message in interp->result.

       When  a  widget  wishes  to  actually  display  an  image  it must call
       TTkkRReeddrraawwIImmaaggee, 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  TTkkSSiizzee-
       OOffIImmaaggee:  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 TTkkFFrreeeeIImmaaggee to release  the  image  instance.   The
       widget  should  never  again  use  the  image token after passing it to
       TTkkFFrreeeeIImmaaggee.  There must be exactly one call to TTkkFFrreeeeIImmaaggee for  each
       call to TTkkGGeettIImmaaggee.

       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 TTkkGGeettIImm-
       aaggee 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 TkImageChangedProc(
                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 TTkkGGeettIImmaaggee.  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
       TkCreateImageType


KKEEYYWWOORRDDSS
       images, redisplay



Tk                                    4.0                       TkGetImage(3)