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

DESCRIPTION

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

TK_GETIMAGEMASTERDATA

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

LEGACY INTERFACE SUPPORT

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

SEE ALSO

244       Tk_ImageChanged, Tk_GetImage,  Tk_FreeImage,  Tk_RedrawImage,  Tk_Size‐
245       OfImage
246

KEYWORDS

248       image manager, image type, instance, master
249
250
251
252Tk                                    8.5                Tk_CreateImageType(3)
Impressum