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

NAME

8       Tk_CreateImageType,  Tk_GetImageMasterData,  Tk_InitImageArgs  - define
9       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       Tk_InitImageArgs(interp, argc, argvPtr)
20

ARGUMENTS

22       Tk_ImageType *typePtr (in)             Structure that defines  the  new
23                                              type  of image.  Must be static:
24                                              a pointer to this  structure  is
25                                              retained by the image code.
26
27       Tcl_Interp *interp (in)                Interpreter  in  which image was
28                                              created.
29
30       const char *name (in)                  Name of existing image.
31
32       Tk_ImageType **typePtrPtr (out)        Points to word in which to store
33                                              a  pointer  to  type information
34                                              for  the  given  image,  if   it
35                                              exists.
36
37       int argc (in)                          Number of arguments
38
39       char ***argvPtr (in/out)               Pointer to argument list
40_________________________________________________________________
41
42

DESCRIPTION

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

TK_GETIMAGEMASTERDATA

204       The procedure Tk_GetImageMasterData may be invoked to retrieve informa‐
205       tion about an image.  For example, an image manager can use this proce‐
206       dure  to locate its image master data for an image.  If there exists an
207       image named name in the interpreter given by interp,  then  *typePtrPtr
208       is  filled  in  with  type information for the image (the typePtr value
209       passed to Tk_CreateImageType when the image type  was  registered)  and
210       the  return  value  is  the ClientData value returned by the createProc
211       when the image was created (this is typically a pointer  to  the  image
212       master  data structure).  If no such image exists then NULL is returned
213       and NULL is stored at *typePtrPtr.
214
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 master,
226                  ClientData *masterDataPtr);
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       When the USE_OLD_IMAGE legacy support is enabled, you may see the  rou‐
233       tine Tk_InitImageArgs in use.  This was a migration tool used to create
234       stub-enabled extensions that could be loaded  into  interps  containing
235       all  versions of Tk 8.1 and later.  Tk 8.5 no longer provides this rou‐
236       tine, but uses a macro to convert any attempted calls of  this  routine
237       into  an  empty  comment.   Any  stub-enabled  extension  providing  an
238       extended image type via the legacy interface that is  compiled  against
239       Tk  8.5 headers and linked against the Tk 8.5 stub library will produce
240       a file that can be loaded only into interps with Tk 8.5 or later;  that
241       is,  the normal stub-compatibility rules.  If a developer needs to gen‐
242       erate from such code a file that is loadable into interps with  Tk  8.4
243       or earlier, they must use Tk 8.4 headers and stub libraries to do so.
244
245       Any  new  code  written  today should not make use of the legacy inter‐
246       faces.  Expect their support to go away in Tk 9.
247
248

SEE ALSO

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

KEYWORDS

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