DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

Tk_GetImage(3tk)




______________________________________________________________________________


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

       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_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(
                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(3)

Man(1) output converted with man2html