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 im‐
9       age 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  in‐
33                                                     voke  whenever image con‐
34                                                     tent 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

DESCRIPTION

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

SEE ALSO

141       Tk_CreateImageType
142

KEYWORDS

144       images, redisplay
145
146
147
148Tk                                    4.0                       Tk_GetImage(3)
Impressum