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

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
97       instance  of  the  image.  If the image does not exist then Tk_GetImage
98       returns NULL and  leaves  an  error  message  in  interpreter  interp's
99       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

SEE ALSO

142       Tk_CreateImageType
143

KEYWORDS

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