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

NAME

8       Tk_CreateImageType,     Tk_GetImageMasterData,    Tk_GetImageModelData,
9       Tk_InitImageArgs - define new kind of image
10

SYNOPSIS

12       #include <tk.h>
13
14       Tk_CreateImageType(typePtr)
15
16       ClientData
17       Tk_GetImageMasterData(interp, name, typePtrPtr)
18
19       ClientData                                                              │
20       Tk_GetImageModelData(interp, name, typePtrPtr)                          │
21
22       Tk_InitImageArgs(interp, argc, argvPtr)
23

ARGUMENTS

25       const Tk_ImageType *typePtr (in)             Structure that defines the
26                                                    new type of image.  For Tk
27                                                    8.4 and earlier this  must
28                                                    be  static:  a  pointer to
29                                                    this structure is retained
30                                                    by  the image code.  In Tk
31                                                    8.5, this  limitation  was
32                                                    relaxed.
33
34       Tcl_Interp *interp (in)                      Interpreter in which image
35                                                    was created.
36
37       const char *name (in)                        Name of existing image.
38
39       Tk_ImageType **typePtrPtr (out)              Points to word in which to
40                                                    store  a  pointer  to type
41                                                    information for the  given
42                                                    image, if it exists.
43
44       int argc (in)                                Number of arguments
45
46       char ***argvPtr (in/out)                     Pointer to argument list
47______________________________________________________________________________
48

DESCRIPTION

50       Tk_CreateImageType  is invoked to define a new kind of image.  An image
51       type corresponds to a particular value of the type argument for the im‐
52       age  create  command.   There  may  exist any number of different image
53       types, and new types may be defined dynamically by calling Tk_CreateIm‐
54       ageType.  For example, there might be one type for 2-color bitmaps, an‐
55       other for multi-color images, another for dithered images, another  for
56       video, and so on.
57
58       The  code  that implements a new image type is called an image manager.
59       It consists of a collection of procedures plus three different kinds of
60       data structures.  The first data structure is a Tk_ImageType structure,
61       which contains the name of the image type and pointers to  five  proce‐
62       dures provided by the image manager to deal with images of this type:
63              typedef struct Tk_ImageType {
64                  const char *name;
65                  Tk_ImageCreateProc *createProc;
66                  Tk_ImageGetProc *getProc;
67                  Tk_ImageDisplayProc *displayProc;
68                  Tk_ImageFreeProc *freeProc;
69                  Tk_ImageDeleteProc *deleteProc;
70              } Tk_ImageType;
71       The  fields of this structure will be described in later subsections of
72       this entry.
73
74       The second major data structure manipulated  by  an  image  manager  is
75       called an image model;  it contains overall information about a partic‐
76       ular image, such as the values of the configuration  options  specified
77       in  an image create command.  There will usually be one of these struc‐
78       tures for each invocation of the image create command.
79
80       The third data structure related to images is an image instance.  There
81       will usually be one of these structures for each usage of an image in a
82       particular widget.  It is possible for a single image to appear  simul‐
83       taneously  in multiple widgets, or even multiple times in the same wid‐
84       get.  Furthermore, different instances may be on different  screens  or
85       displays.   The image instance data structure describes things that may
86       vary from instance to instance, such as colors  and  graphics  contexts
87       for redisplay.  There is usually one instance structure for each -image
88       option specified for a widget or canvas item.
89
90       The following subsections describe the fields of a Tk_ImageType in more
91       detail.
92
93   NAME
94       typePtr->name  provides  a  name for the image type.  Once Tk_CreateIm‐
95       ageType returns, this name may be used in image create commands to cre‐
96       ate  images of the new type.  If there already existed an image type by
97       this name then the new image type replaces the old one.
98
99   CREATEPROC
100       typePtr->createProc provides the address of a procedure for Tk to  call
101       whenever  image  create  is invoked to create an image of the new type.
102       typePtr->createProc must match the following prototype:
103              typedef int Tk_ImageCreateProc(
104                      Tcl_Interp *interp,
105                      const char *name,
106                      int objc,
107                      Tcl_Obj *const objv[],
108                      const Tk_ImageType *typePtr,
109                      Tk_ImageMaster model,
110                      ClientData *modelDataPtr);
111       The interp argument is the interpreter in which the image  command  was
112       invoked, and name is the name for the new image, which was either spec‐
113       ified explicitly in the image command or generated automatically by the
114       image command.  The objc and objv arguments describe all the configura‐
115       tion options for the new image (everything after the name  argument  to
116       image).   The model argument is a token that refers to Tk's information
117       about this image;  the image manager must return this token to Tk  when
118       invoking  the  Tk_ImageChanged  procedure.   Typically  createProc will
119       parse objc and objv and create an image model data  structure  for  the
120       new image.  createProc may store an arbitrary one-word value at *model‐
121       DataPtr, which will be passed back to  the  image  manager  when  other
122       callbacks  are  invoked.  Typically the value is a pointer to the model
123       data structure for the image.
124
125       If createProc encounters an error, it should leave an error message  in
126       the  interpreter  result and return TCL_ERROR;  otherwise it should re‐
127       turn TCL_OK.
128
129       createProc should call Tk_ImageChanged in order to set the size of  the
130       image and request an initial redisplay.
131
132   GETPROC
133       typePtr->getProc  is  invoked by Tk whenever a widget calls Tk_GetImage
134       to use a particular image.  This procedure  must  match  the  following
135       prototype:
136              typedef ClientData Tk_ImageGetProc(
137                      Tk_Window tkwin,
138                      ClientData modelData);
139       The  tkwin  argument  identifies  the window in which the image will be
140       used and modelData is the value returned by createProc when  the  image
141       model  was  created.   getProc will usually create a data structure for
142       the new instance, including such things as the resources needed to dis‐
143       play  the  image in the given window.  getProc returns a one-word token
144       for the instance, which is typically the address of the  instance  data
145       structure.   Tk will pass this value back to the image manager when in‐
146       voking its displayProc and freeProc procedures.
147
148   DISPLAYPROC
149       typePtr->displayProc is invoked by Tk whenever an  image  needs  to  be
150       displayed  (i.e., whenever a widget calls Tk_RedrawImage).  displayProc
151       must match the following prototype:
152              typedef void Tk_ImageDisplayProc(
153                      ClientData instanceData,
154                      Display *display,
155                      Drawable drawable,
156                      int imageX,
157                      int imageY,
158                      int width,
159                      int height,
160                      int drawableX,
161                      int drawableY);
162       The instanceData will be the same as the value returned by getProc when
163       the  instance was created.  display and drawable indicate where to dis‐
164       play the image;  drawable may be a pixmap rather than the window speci‐
165       fied  to  getProc (this is usually the case, since most widgets double-
166       buffer their redisplay to get smoother visual  effects).   imageX,  im‐
167       ageY,  width,  and height identify the region of the image that must be
168       redisplayed.  This region will always be within the size of  the  image
169       as specified in the most recent call to Tk_ImageChanged.  drawableX and
170       drawableY indicate where in drawable the  image  should  be  displayed;
171       displayProc  should display the given region of the image so that point
172       (imageX, imageY) in the image  appears  at  (drawableX,  drawableY)  in
173       drawable.
174
175   FREEPROC
176       typePtr->freeProc  contains the address of a procedure that Tk will in‐
177       voke when an image instance is released (i.e., when Tk_FreeImage is in‐
178       voked).   This  can  happen, for example, when a widget is deleted or a
179       image item in a canvas is deleted, or when the  image  displayed  in  a
180       widget  or  canvas  item is changed.  freeProc must match the following
181       prototype:
182              typedef void Tk_ImageFreeProc(
183                      ClientData instanceData,
184                      Display *display);
185       The instanceData will be the same as the value returned by getProc when
186       the  instance  was  created,  and display is the display containing the
187       window for the instance.  freeProc should release any resources associ‐
188       ated  with  the  image  instance, since the instance will never be used
189       again.
190
191   DELETEPROC
192       typePtr->deleteProc is a procedure that Tk invokes when an image is be‐
193       ing  deleted  (i.e.  when the image delete command is invoked).  Before
194       invoking deleteProc Tk will invoke freeProc for each of the image's in‐
195       stances.  deleteProc must match the following prototype:
196              typedef void Tk_ImageDeleteProc(
197                      ClientData modelData);
198       The  modelData argument will be the same as the value stored in *model‐
199       DataPtr by createProc when the image was  created.   deleteProc  should
200       release any resources associated with the image.
201

TK_GETIMAGEMODELDATA

203       The procedure Tk_GetImageMasterData may be invoked to retrieve informa‐
204       tion about an image.  For example, an image manager can use this proce‐
205       dure  to  locate its image model data for an image.  If there exists an
206       image named name in the interpreter given by interp,  then  *typePtrPtr
207       is  filled  in  with  type information for the image (the typePtr value
208       passed to Tk_CreateImageType when the image type  was  registered)  and
209       the  return  value  is  the ClientData value returned by the createProc
210       when the image was created (this is typically a pointer  to  the  image
211       model  data  structure).  If no such image exists then NULL is returned
212       and NULL is stored at *typePtrPtr.
213
214       Tk_GetImageModelData is synonym for Tk_GetImageMasterData               
215

LEGACY INTERFACE SUPPORT

217       In Tk 8.2 and earlier, the definition of Tk_ImageCreateProc was  incom‐
218       patibly different, with the following prototype:
219              typedef int Tk_ImageCreateProc(
220                      Tcl_Interp *interp,
221                      char *name,
222                      int argc,
223                      char **argv,
224                      Tk_ImageType *typePtr,
225                      Tk_ImageMaster model,
226                      ClientData *modelDataPtr);
227       Legacy  programs and libraries dating from those days may still contain
228       code that defines extended Tk image types using the old interface.  The
229       Tk  header file will still support this legacy interface if the code is
230       compiled with the macro USE_OLD_IMAGE defined.
231
232       Tk_ImageModel is synonym for Tk_ImageMaster
233
234       When the USE_OLD_IMAGE legacy support is enabled, you may see the  rou‐
235       tine Tk_InitImageArgs in use.  This was a migration tool used to create
236       stub-enabled extensions that could be loaded  into  interps  containing
237       all  versions of Tk 8.1 and later.  Tk 8.5 no longer provides this rou‐
238       tine, but uses a macro to convert any attempted calls of  this  routine
239       into  an  empty  comment.   Any stub-enabled extension providing an ex‐
240       tended image type via the legacy interface that is compiled against  Tk
241       8.5  headers  and linked against the Tk 8.5 stub library will produce a
242       file that can be loaded only into interps with Tk 8.5  or  later;  that
243       is,  the normal stub-compatibility rules.  If a developer needs to gen‐
244       erate from such code a file that is loadable into interps with  Tk  8.4
245       or earlier, they must use Tk 8.4 headers and stub libraries to do so.
246
247       Any  new  code  written  today should not make use of the legacy inter‐
248       faces.  Expect their support to go away in Tk 9.
249

SEE ALSO

251       Tk_ImageChanged, Tk_GetImage,  Tk_FreeImage,  Tk_RedrawImage,  Tk_Size‐
252       OfImage
253

KEYWORDS

255       image manager, image type, instance, model
256
257
258
259Tk                                    8.5                Tk_CreateImageType(3)
Impressum