1Tk_CreatePhotoImageFormat(3) Tk Library ProceduresTk_CreatePhotoImageFormat(3)
2______________________________________________________________________________
6
8 Tk_CreatePhotoImageFormat - define new file format for photo images
9
11 #include <tk.h>
12 Tk_CreatePhotoImageFormat(formatPtr)
14
16 Tk_PhotoImageFormat *formatPtr (in) Structure that defines the
17 new file format.
18_________________________________________________________________
19
22 Tk_CreatePhotoImageFormat is invoked to define a new file format for
23 image data for use with photo images. The code that implements an
24 image file format is called an image file format handler, or handler
25 for short. The photo image code maintains a list of handlers that can
26 be used to read and write data to or from a file. Some handlers may
27 also support reading image data from a string or converting image data
28 to a string format. The user can specify which handler to use with the
29 -format image configuration option or the -format option to the read
30 and write photo image subcommands.
31 An image file format handler consists of a collection of procedures
33 plus a Tk_PhotoImageFormat structure, which contains the name of the
34 image file format and pointers to six procedures provided by the han‐
35 dler to deal with files and strings in this format. The Tk_PhotoImage‐
36 Format structure contains the following fields:
37 typedef struct Tk_PhotoImageFormat {
38 char *name;
39 Tk_ImageFileMatchProc *fileMatchProc;
40 Tk_ImageStringMatchProc *stringMatchProc;
41 Tk_ImageFileReadProc *fileReadProc;
42 Tk_ImageStringReadProc *stringReadProc;
43 Tk_ImageFileWriteProc *fileWriteProc;
44 Tk_ImageStringWriteProc *stringWriteProc;
45 } Tk_PhotoImageFormat;
46 The handler need not provide implementations of all six procedures.
48 For example, the procedures that handle string data would not be pro‐
49 vided for a format in which the image data are stored in binary, and
50 could therefore contain null characters. If any procedure is not
51 implemented, the corresponding pointer in the Tk_PhotoImageFormat
52 structure should be set to NULL. The handler must provide the
53 fileMatchProc procedure if it provides the fileReadProc procedure, and
54 the stringMatchProc procedure if it provides the stringReadProc proce‐
55 dure.
56
59 formatPtr->name provides a name for the image type. Once Tk_CreatePho‐
60 toImageFormat returns, this name may be used in the -format photo image
61 configuration and subcommand option. The manual page for the photo
62 image (photo(n)) describes how image file formats are chosen based on
63 their names and the value given to the -format option. The first char‐
64 acter of formatPtr->name must not be an uppercase character from the
65 ASCII character set (that is, one of the characters A-Z). Such names
66 are used only for legacy interface support (see below).
67
70 formatPtr->fileMatchProc provides the address of a procedure for Tk to
71 call when it is searching for an image file format handler suitable for
72 reading data in a given file. formatPtr->fileMatchProc must match the
73 following prototype:
74 typedef int Tk_ImageFileMatchProc(
75 Tcl_Channel chan,
76 const char *fileName,
77 Tcl_Obj *format,
78 int *widthPtr,
79 int *heightPtr,
80 Tcl_Interp *interp);
81 The fileName argument is the name of the file containing the image
82 data, which is open for reading as chan. The format argument contains
83 the value given for the -format option, or NULL if the option was not
84 specified. If the data in the file appears to be in the format sup‐
85 ported by this handler, the formatPtr->fileMatchProc procedure should
86 store the width and height of the image in *widthPtr and *heightPtr
87 respectively, and return 1. Otherwise it should return 0.
88
91 formatPtr->stringMatchProc provides the address of a procedure for Tk
92 to call when it is searching for an image file format handler for suit‐
93 able for reading data from a given string. formatPtr->stringMatchProc
94 must match the following prototype:
95 typedef int Tk_ImageStringMatchProc(
96 Tcl_Obj *data,
97 Tcl_Obj *format,
98 int *widthPtr,
99 int *heightPtr,
100 Tcl_Interp *interp);
101 The data argument points to the object containing the image data. The
102 format argument contains the value given for the -format option, or
103 NULL if the option was not specified. If the data in the string
104 appears to be in the format supported by this handler, the for‐
105 matPtr->stringMatchProc procedure should store the width and height of
106 the image in *widthPtr and *heightPtr respectively, and return 1. Oth‐
107 erwise it should return 0.
108
111 formatPtr->fileReadProc provides the address of a procedure for Tk to
112 call to read data from an image file into a photo image. for‐
113 matPtr->fileReadProc must match the following prototype:
114 typedef int Tk_ImageFileReadProc(
115 Tcl_Interp *interp,
116 Tcl_Channel chan,
117 const char *fileName,
118 Tcl_Obj *format,
119 PhotoHandle imageHandle,
120 int destX, int destY,
121 int width, int height,
122 int srcX, int srcY);
123 The interp argument is the interpreter in which the command was invoked
124 to read the image; it should be used for reporting errors. The image
125 data is in the file named fileName, which is open for reading as chan.
126 The format argument contains the value given for the -format option, or
127 NULL if the option was not specified. The image data in the file, or a
128 subimage of it, is to be read into the photo image identified by the
129 handle imageHandle. The subimage of the data in the file is of dimen‐
130 sions width x height and has its top-left corner at coordinates
131 (srcX,srcY). It is to be stored in the photo image with its top-left
132 corner at coordinates (destX,destY) using the Tk_PhotoPutBlock proce‐
133 dure. The return value is a standard Tcl return value.
134
137 formatPtr->stringReadProc provides the address of a procedure for Tk to
138 call to read data from a string into a photo image. for‐
139 matPtr->stringReadProc must match the following prototype:
140 typedef int Tk_ImageStringReadProc(
141 Tcl_Interp *interp,
142 Tcl_Obj *data,
143 Tcl_Obj *format,
144 PhotoHandle imageHandle,
145 int destX, int destY,
146 int width, int height,
147 int srcX, int srcY);
148 The interp argument is the interpreter in which the command was invoked
149 to read the image; it should be used for reporting errors. The data
150 argument points to the image data in object form. The format argument
151 contains the value given for the -format option, or NULL if the option
152 was not specified. The image data in the string, or a subimage of it,
153 is to be read into the photo image identified by the handle imageHan‐
154 dle. The subimage of the data in the string is of dimensions width x
155 height and has its top-left corner at coordinates (srcX,srcY). It is
156 to be stored in the photo image with its top-left corner at coordinates
157 (destX,destY) using the Tk_PhotoPutBlock procedure. The return value
158 is a standard Tcl return value.
159
162 formatPtr->fileWriteProc provides the address of a procedure for Tk to
163 call to write data from a photo image to a file. for‐
164 matPtr->fileWriteProc must match the following prototype:
165 typedef int Tk_ImageFileWriteProc(
166 Tcl_Interp *interp,
167 const char *fileName,
168 Tcl_Obj *format,
169 Tk_PhotoImageBlock *blockPtr);
170 The interp argument is the interpreter in which the command was invoked
171 to write the image; it should be used for reporting errors. The image
172 data to be written are in memory and are described by the Tk_PhotoIm‐
173 ageBlock structure pointed to by blockPtr; see the manual page Find‐
174 Photo(3) for details. The fileName argument points to the string giv‐
175 ing the name of the file in which to write the image data. The format
176 argument contains the value given for the -format option, or NULL if
177 the option was not specified. The format string can contain extra
178 characters after the name of the format. If appropriate, the for‐
179 matPtr->fileWriteProc procedure may interpret these characters to spec‐
180 ify further details about the image file. The return value is a stan‐
181 dard Tcl return value.
182
185 formatPtr->stringWriteProc provides the address of a procedure for Tk
186 to call to translate image data from a photo image into a string. for‐
187 matPtr->stringWriteProc must match the following prototype:
188 typedef int Tk_ImageStringWriteProc(
189 Tcl_Interp *interp,
190 Tcl_Obj *format,
191 Tk_PhotoImageBlock *blockPtr);
192 The interp argument is the interpreter in which the command was invoked
193 to convert the image; it should be used for reporting errors. The
194 image data to be converted are in memory and are described by the
195 Tk_PhotoImageBlock structure pointed to by blockPtr; see the manual
196 page FindPhoto(3) for details. The data for the string should be put
197 in the interpreter interp result. The format argument contains the
198 value given for the -format option, or NULL if the option was not spec‐
199 ified. The format string can contain extra characters after the name
200 of the format. If appropriate, the formatPtr->stringWriteProc proce‐
201 dure may interpret these characters to specify further details about
202 the image file. The return value is a standard Tcl return value.
203
206 In Tk 8.2 and earlier, the definition of all the function pointer types
207 stored in fields of a Tk_PhotoImageFormat struct were incompatibly dif‐
208 ferent. Legacy programs and libraries dating from those days may still
209 contain code that defines extended Tk photo image formats using the old
210 interface. The Tk header file will still support this legacy interface
211 if the code is compiled with the macro USE_OLD_IMAGE defined. Alterna‐
212 tively, the legacy interfaces are used if the first character of for‐
213 matPtr->name is an uppercase ASCII character (A-Z), and explicit casts
214 are used to forgive the type mismatch. For example,
215 static Tk_PhotoImageFormat myFormat = {
216 "MyFormat",
217 (Tk_ImageFileMatchProc *) FileMatch,
218 NULL,
219 (Tk_ImageFileReadProc *) FileRead,
220 NULL,
221 NULL,
222 NULL
223 };
224 would define a minimal Tk_PhotoImageFormat that operates provide only
225 file reading capability, where FileMatch and FileRead are written
226 according to the legacy interfaces of Tk 8.2 or earlier.
227 Any stub-enabled extension providing an extended photo image format via
229 the legacy interface enabled by the USE_OLD_IMAGE macro that is com‐
230 piled against Tk 8.5 headers and linked against the Tk 8.5 stub library
231 will produce a file that can be loaded only into interps with Tk 8.5 or
232 later; that is, the normal stub-compatibility rules. If a developer
233 needs to generate from such code a file that is loadable into interps
234 with Tk 8.4 or earlier, they must use Tk 8.4 headers and stub libraries
235 to do so.
236 Any new code written today should not make use of the legacy inter‐
238 faces. Expect their support to go away in Tk 9.
239
242 Tk_FindPhoto, Tk_PhotoPutBlock
243
246 photo image, image file
247Tk 8.5 Tk_CreatePhotoImageFormat(3)