1Tk_GetImage(3)               Tk Library Procedures              Tk_GetImage(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tk_GetImage,  Tk_RedrawImage,  Tk_SizeOfImage,  Tk_FreeImage  -  use an
9       image in a widget
10

SYNOPSIS

12       #include <tk.h>
13
14       Tk_Image
15       Tk_GetImage(interp, tkwin, name, changeProc, clientData)
16
17       Tk_RedrawImage(image, imageX, imageY, width, height, drawable, drawableX, drawableY)
18
19       Tk_SizeOfImage(image, widthPtr, heightPtr)
20
21       Tk_FreeImage(image)
22

ARGUMENTS

24       Tcl_Interp            *interp       (in)      Place to leave error mes‐
25                                                     sage.
26
27       Tk_Window             tkwin         (in)      Window   in  which  image
28                                                     will be used.
29
30       CONST char            *name         (in)      Name of image.
31
32       Tk_ImageChangedProc   *changeProc   (in)      Procedure   for   Tk   to
33                                                     invoke   whenever   image
34                                                     content or size changes.
35
36       ClientData            clientData    (in)      One-word value for Tk  to
37                                                     pass to changeProc.
38
39       Tk_Image              image         (in)      Token for image instance;
40                                                     must have  been  returned
41                                                     by  a  previous  call  to
42                                                     Tk_GetImage.
43
44       int                   imageX        (in)      X-coordinate  of   upper-
45                                                     left  corner of region of
46                                                     image to redisplay  (mea‐
47                                                     sured  in pixels from the
48                                                     image's  upper-left  cor‐
49                                                     ner).
50
51       int                   imageY        (in)      Y-coordinate   of  upper-
52                                                     left corner of region  of
53                                                     image  to redisplay (mea‐
54                                                     sured in pixels from  the
55                                                     image's  upper-left  cor‐
56                                                     ner).
57
58       int                   width         ((in))    Width of region of  image
59                                                     to redisplay.
60
61       int                   height        ((in))    Height of region of image
62                                                     to redisplay.
63
64       Drawable              drawable      (in)      Where to  display  image.
65                                                     Must   either  be  window
66                                                     specified to  Tk_GetImage
67                                                     or  a  pixmap  compatible
68                                                     with that window.
69
70       int                   drawableX     (in)      Where to display image in
71                                                     drawable:  this is the x-
72                                                     coordinate  in   drawable
73                                                     where x-coordinate imageX
74                                                     of the  image  should  be
75                                                     displayed.
76
77       int                   drawableY     (in)      Where to display image in
78                                                     drawable: this is the  y-
79                                                     coordinate   in  drawable
80                                                     where y-coordinate imageY
81                                                     of  the  image  should be
82                                                     displayed.
83
84       int                   widthPtr      (out)     Store width of image  (in
85                                                     pixels) here.
86
87       int                   heightPtr     (out)     Store height of image (in
88                                                     pixels) here.
89_________________________________________________________________
90
91

DESCRIPTION

93       These procedures are invoked by widgets that wish  to  display  images.
94       Tk_GetImage  is invoked by a widget when it first decides to display an
95       image.  name gives the name of the desired image and  tkwin  identifies
96       the window where the image will be displayed.  Tk_GetImage looks up the
97       image in the table of existing images and returns a  token  for  a  new
98       instance  of  the  image.   If the image doesn't exist then Tk_GetImage
99       returns NULL and leaves an error message in interp->result.
100
101       When a widget  wishes  to  actually  display  an  image  it  must  call
102       Tk_RedrawImage,  identifying  the  image  (image),  a region within the
103       image to redisplay (imageX, imageY, width, and height), and a place  to
104       display  the  image (drawable, drawableX, and drawableY).  Tk will then
105       invoke the appropriate image manager, which will display the  requested
106       portion of the image before returning.
107
108       A  widget  can  find out the dimensions of an image by calling Tk_Size‐
109       OfImage:  the width and height will be stored in the locations given by
110       widthPtr and heightPtr, respectively.
111
112       When  a  widget  is  finished  with an image (e.g., the widget is being
113       deleted or it is going to use a different image instead of the  current
114       one),  it  must  call  Tk_FreeImage to release the image instance.  The
115       widget should never again use the  image  token  after  passing  it  to
116       Tk_FreeImage.   There must be exactly one call to Tk_FreeImage for each
117       call to Tk_GetImage.
118
119       If the contents or size of an image changes, then any widgets using the
120       image  will  need to find out about the changes so that they can redis‐
121       play themselves.  The changeProc and clientData arguments to  Tk_GetIm‐
122       age  are  used for this purpose.  changeProc will be called by Tk when‐
123       ever a change occurs in the image;  it must match the following  proto‐
124       type:
125              typedef void Tk_ImageChangedProc(
126                ClientData clientData,
127                int x,
128                int y,
129                int width,
130                int height,
131                int imageWidth,
132                int imageHeight);
133       The  clientData  argument  to  changeProc is the same as the clientData
134       argument to Tk_GetImage.  It is usually a pointer to the widget  record
135       for the widget or some other data structure managed by the widget.  The
136       arguments x, y, width, and height identify a region  within  the  image
137       that  must  be  redisplayed; they are specified in pixels measured from
138       the upper-left corner of  the  image.   The  arguments  imageWidth  and
139       imageHeight give the image's (new) size.
140
141

SEE ALSO

143       Tk_CreateImageType
144
145

KEYWORDS

147       images, redisplay
148
149
150
151Tk                                    4.0                       Tk_GetImage(3)
Impressum