Manual Pages for UNIX Operating System command usage for man Tk_FreeImage

Tk Library Procedures                            Tk_GetImage(3TK)



_________________________________________________________________

NAME
     Tk_GetImage, Tk_RedrawImage, Tk_SizeOfImage, Tk_FreeImage  -
     use an image in a widget

SYNOPSIS
     #include 

     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



Tk                      Last change: 4.0                        1






Tk Library Procedures                            Tk_GetImage(3TK)



                                                   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  speci-
                                                   fied        to
                                                   Tk_GetImage or
                                                   a pixmap  com-
                                                   patible   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



Tk                      Last change: 4.0                        2






Tk Library Procedures                            Tk_GetImage(3TK)



                                                   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 pix-
                                                   els) 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.




Tk                      Last change: 4.0                        3






Tk Library Procedures                            Tk_GetImage(3TK)



     If the contents or size of an image changes, then any  widg-
     ets  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 pur-
     pose.  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

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     _______________________________________
    |   ATTRIBUTE TYPE   |  ATTRIBUTE VALUE|
    |____________________|__________________|_
    | Availability       |  runtime/tk-8   |
    |____________________|__________________|_
    | Interface Stability|  Uncommitted    |
    |____________________|_________________|

NOTES
     Source for Tk is available on http://opensolaris.org.










Tk                      Last change: 4.0                        4