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 const Tk_PhotoImageFormat *formatPtr (in) Structure that
17 defines the new file
18 format.
19______________________________________________________________________________
20
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 const 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 NAME
58 formatPtr->name provides a name for the image type. Once Tk_CreatePho‐
59 toImageFormat returns, this name may be used in the -format photo image
60 configuration and subcommand option. The manual page for the photo
61 image (photo(n)) describes how image file formats are chosen based on
62 their names and the value given to the -format option. The first char‐
63 acter of formatPtr->name must not be an uppercase character from the
64 ASCII character set (that is, one of the characters A-Z). Such names
65 are used only for legacy interface support (see below).
66 FILEMATCHPROC
68 formatPtr->fileMatchProc provides the address of a procedure for Tk to
69 call when it is searching for an image file format handler suitable for
70 reading data in a given file. formatPtr->fileMatchProc must match the
71 following prototype:
72 typedef int Tk_ImageFileMatchProc(
73 Tcl_Channel chan,
74 const char *fileName,
75 Tcl_Obj *format,
76 int *widthPtr,
77 int *heightPtr,
78 Tcl_Interp *interp);
79 The fileName argument is the name of the file containing the image
80 data, which is open for reading as chan. The format argument contains
81 the value given for the -format option, or NULL if the option was not
82 specified. If the data in the file appears to be in the format sup‐
83 ported by this handler, the formatPtr->fileMatchProc procedure should
84 store the width and height of the image in *widthPtr and *heightPtr
85 respectively, and return 1. Otherwise it should return 0.
86 STRINGMATCHPROC
88 formatPtr->stringMatchProc provides the address of a procedure for Tk
89 to call when it is searching for an image file format handler for suit‐
90 able for reading data from a given string. formatPtr->stringMatchProc
91 must match the following prototype:
92 typedef int Tk_ImageStringMatchProc(
93 Tcl_Obj *data,
94 Tcl_Obj *format,
95 int *widthPtr,
96 int *heightPtr,
97 Tcl_Interp *interp);
98 The data argument points to the object containing the image data. The
99 format argument contains the value given for the -format option, or
100 NULL if the option was not specified. If the data in the string
101 appears to be in the format supported by this handler, the for‐
102 matPtr->stringMatchProc procedure should store the width and height of
103 the image in *widthPtr and *heightPtr respectively, and return 1. Oth‐
104 erwise it should return 0.
105 FILEREADPROC
107 formatPtr->fileReadProc provides the address of a procedure for Tk to
108 call to read data from an image file into a photo image. for‐
109 matPtr->fileReadProc must match the following prototype:
110 typedef int Tk_ImageFileReadProc(
111 Tcl_Interp *interp,
112 Tcl_Channel chan,
113 const char *fileName,
114 Tcl_Obj *format,
115 PhotoHandle imageHandle,
116 int destX, int destY,
117 int width, int height,
118 int srcX, int srcY);
119 The interp argument is the interpreter in which the command was invoked
120 to read the image; it should be used for reporting errors. The image
121 data is in the file named fileName, which is open for reading as chan.
122 The format argument contains the value given for the -format option, or
123 NULL if the option was not specified. The image data in the file, or a
124 subimage of it, is to be read into the photo image identified by the
125 handle imageHandle. The subimage of the data in the file is of dimen‐
126 sions width x height and has its top-left corner at coordinates
127 (srcX,srcY). It is to be stored in the photo image with its top-left
128 corner at coordinates (destX,destY) using the Tk_PhotoPutBlock proce‐
129 dure. The return value is a standard Tcl return value.
130 STRINGREADPROC
132 formatPtr->stringReadProc provides the address of a procedure for Tk to
133 call to read data from a string into a photo image. for‐
134 matPtr->stringReadProc must match the following prototype:
135 typedef int Tk_ImageStringReadProc(
136 Tcl_Interp *interp,
137 Tcl_Obj *data,
138 Tcl_Obj *format,
139 PhotoHandle imageHandle,
140 int destX, int destY,
141 int width, int height,
142 int srcX, int srcY);
143 The interp argument is the interpreter in which the command was invoked
144 to read the image; it should be used for reporting errors. The data
145 argument points to the image data in object form. The format argument
146 contains the value given for the -format option, or NULL if the option
147 was not specified. The image data in the string, or a subimage of it,
148 is to be read into the photo image identified by the handle imageHan‐
149 dle. The subimage of the data in the string is of dimensions width x
150 height and has its top-left corner at coordinates (srcX,srcY). It is
151 to be stored in the photo image with its top-left corner at coordinates
152 (destX,destY) using the Tk_PhotoPutBlock procedure. The return value
153 is a standard Tcl return value.
154 FILEWRITEPROC
156 formatPtr->fileWriteProc provides the address of a procedure for Tk to
157 call to write data from a photo image to a file. for‐
158 matPtr->fileWriteProc must match the following prototype:
159 typedef int Tk_ImageFileWriteProc(
160 Tcl_Interp *interp,
161 const char *fileName,
162 Tcl_Obj *format,
163 Tk_PhotoImageBlock *blockPtr);
164 The interp argument is the interpreter in which the command was invoked
165 to write the image; it should be used for reporting errors. The image
166 data to be written are in memory and are described by the Tk_PhotoIm‐
167 ageBlock structure pointed to by blockPtr; see the manual page Find‐
168 Photo(3) for details. The fileName argument points to the string giv‐
169 ing the name of the file in which to write the image data. The format
170 argument contains the value given for the -format option, or NULL if
171 the option was not specified. The format string can contain extra
172 characters after the name of the format. If appropriate, the for‐
173 matPtr->fileWriteProc procedure may interpret these characters to spec‐
174 ify further details about the image file. The return value is a stan‐
175 dard Tcl return value.
176 STRINGWRITEPROC
178 formatPtr->stringWriteProc provides the address of a procedure for Tk
179 to call to translate image data from a photo image into a string. for‐
180 matPtr->stringWriteProc must match the following prototype:
181 typedef int Tk_ImageStringWriteProc(
182 Tcl_Interp *interp,
183 Tcl_Obj *format,
184 Tk_PhotoImageBlock *blockPtr);
185 The interp argument is the interpreter in which the command was invoked
186 to convert the image; it should be used for reporting errors. The
187 image data to be converted are in memory and are described by the
188 Tk_PhotoImageBlock structure pointed to by blockPtr; see the manual
189 page FindPhoto(3) for details. The data for the string should be put
190 in the interpreter interp result. The format argument contains the
191 value given for the -format option, or NULL if the option was not spec‐
192 ified. The format string can contain extra characters after the name
193 of the format. If appropriate, the formatPtr->stringWriteProc proce‐
194 dure may interpret these characters to specify further details about
195 the image file. The return value is a standard Tcl return value.
196
198 In Tk 8.2 and earlier, the definition of all the function pointer types
199 stored in fields of a Tk_PhotoImageFormat struct were incompatibly dif‐
200 ferent. Legacy programs and libraries dating from those days may still
201 contain code that defines extended Tk photo image formats using the old
202 interface. The Tk header file will still support this legacy interface
203 if the code is compiled with the macro USE_OLD_IMAGE defined. Alterna‐
204 tively, the legacy interfaces are used if the first character of for‐
205 matPtr->name is an uppercase ASCII character (A-Z), and explicit casts
206 are used to forgive the type mismatch. For example,
207 static Tk_PhotoImageFormat myFormat = {
208 "MyFormat",
209 (Tk_ImageFileMatchProc *) FileMatch,
210 NULL,
211 (Tk_ImageFileReadProc *) FileRead,
212 NULL,
213 NULL,
214 NULL
215 };
216 would define a minimal Tk_PhotoImageFormat that operates provide only
217 file reading capability, where FileMatch and FileRead are written
218 according to the legacy interfaces of Tk 8.2 or earlier.
219 Any stub-enabled extension providing an extended photo image format via
221 the legacy interface enabled by the USE_OLD_IMAGE macro that is com‐
222 piled against Tk 8.5 headers and linked against the Tk 8.5 stub library
223 will produce a file that can be loaded only into interps with Tk 8.5 or
224 later; that is, the normal stub-compatibility rules. If a developer
225 needs to generate from such code a file that is loadable into interps
226 with Tk 8.4 or earlier, they must use Tk 8.4 headers and stub libraries
227 to do so.
228 Any new code written today should not make use of the legacy inter‐
230 faces. Expect their support to go away in Tk 9.
231
233 Tk_FindPhoto, Tk_PhotoPutBlock
234
236 photo image, image file
237Tk 8.5 Tk_CreatePhotoImageFormat(3)