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 In Tk 8.2 and earlier, a different interface was used. Tk 8.3 will
60 still support the old format handlers if the format name is in upper
61 case. If you still want to compile old format handlers with Tk8.3, use
62 the flag -DUSE_OLD_IMAGE. This will restore all function prototypes to
63 match the pre-8.3 situation.
64
67 formatPtr->name provides a name for the image type. Once Tk_CreatePho‐
68 toImageFormat returns, this name may be used in the -format photo image
69 configuration and subcommand option. The manual page for the photo
70 image (photo(n)) describes how image file formats are chosen based on
71 their names and the value given to the -format option. For new format
72 handlers, the name should be in lower case. Pre-8.3 format handlers are
73 assumed to be in upper case.
74
77 formatPtr->fileMatchProc provides the address of a procedure for Tk to
78 call when it is searching for an image file format handler suitable for
79 reading data in a given file. formatPtr->fileMatchProc must match the
80 following prototype:
81 typedef int Tk_ImageFileMatchProc(
82 Tcl_Channel chan,
83 CONST char *fileName,
84 Tcl_Obj *format,
85 int *widthPtr,
86 int *heightPtr,
87 Tcl_Interp *interp);
88 The fileName argument is the name of the file containing the image
89 data, which is open for reading as chan. The format argument contains
90 the value given for the -format option, or NULL if the option was not
91 specified. If the data in the file appears to be in the format sup‐
92 ported by this handler, the formatPtr->fileMatchProc procedure should
93 store the width and height of the image in *widthPtr and *heightPtr
94 respectively, and return 1. Otherwise it should return 0.
95
98 formatPtr->stringMatchProc provides the address of a procedure for Tk
99 to call when it is searching for an image file format handler for suit‐
100 able for reading data from a given string. formatPtr->stringMatchProc
101 must match the following prototype:
102 typedef int Tk_ImageStringMatchProc(
103 Tcl_Obj *data,
104 Tcl_Obj *format,
105 int *widthPtr,
106 int *heightPtr,
107 Tcl_Interp *interp);
108 The data argument points to the object containing the image data. The
109 format argument contains the value given for the -format option, or
110 NULL if the option was not specified. If the data in the string
111 appears to be in the format supported by this handler, the for‐
112 matPtr->stringMatchProc procedure should store the width and height of
113 the image in *widthPtr and *heightPtr respectively, and return 1. Oth‐
114 erwise it should return 0.
115
118 formatPtr->fileReadProc provides the address of a procedure for Tk to
119 call to read data from an image file into a photo image. for‐
120 matPtr->fileReadProc must match the following prototype:
121 typedef int Tk_ImageFileReadProc(
122 Tcl_Interp *interp,
123 Tcl_Channel chan,
124 CONST char *fileName,
125 Tcl_Obj *format,
126 PhotoHandle imageHandle,
127 int destX, int destY,
128 int width, int height,
129 int srcX, int srcY);
130 The interp argument is the interpreter in which the command was invoked
131 to read the image; it should be used for reporting errors. The image
132 data is in the file named fileName, which is open for reading as chan.
133 The format argument contains the value given for the -format option, or
134 NULL if the option was not specified. The image data in the file, or a
135 subimage of it, is to be read into the photo image identified by the
136 handle imageHandle. The subimage of the data in the file is of dimen‐
137 sions width x height and has its top-left corner at coordinates
138 (srcX,srcY). It is to be stored in the photo image with its top-left
139 corner at coordinates (destX,destY) using the Tk_PhotoPutBlock proce‐
140 dure. The return value is a standard Tcl return value.
141
144 formatPtr->stringReadProc provides the address of a procedure for Tk to
145 call to read data from a string into a photo image. for‐
146 matPtr->stringReadProc must match the following prototype:
147 typedef int Tk_ImageStringReadProc(
148 Tcl_Interp *interp,
149 Tcl_Obj *data,
150 Tcl_Obj *format,
151 PhotoHandle imageHandle,
152 int destX, int destY,
153 int width, int height,
154 int srcX, int srcY);
155 The interp argument is the interpreter in which the command was invoked
156 to read the image; it should be used for reporting errors. The data
157 argument points to the image data in object form. The format argument
158 contains the value given for the -format option, or NULL if the option
159 was not specified. The image data in the string, or a subimage of it,
160 is to be read into the photo image identified by the handle imageHan‐
161 dle. The subimage of the data in the string is of dimensions width x
162 height and has its top-left corner at coordinates (srcX,srcY). It is
163 to be stored in the photo image with its top-left corner at coordinates
164 (destX,destY) using the Tk_PhotoPutBlock procedure. The return value
165 is a standard Tcl return value.
166
169 formatPtr->fileWriteProc provides the address of a procedure for Tk to
170 call to write data from a photo image to a file. for‐
171 matPtr->fileWriteProc must match the following prototype:
172 typedef int Tk_ImageFileWriteProc(
173 Tcl_Interp *interp,
174 CONST char *fileName,
175 Tcl_Obj *format,
176 Tk_PhotoImageBlock *blockPtr);
177 The interp argument is the interpreter in which the command was invoked
178 to write the image; it should be used for reporting errors. The image
179 data to be written are in memory and are described by the Tk_PhotoIm‐
180 ageBlock structure pointed to by blockPtr; see the manual page Find‐
181 Photo(3) for details. The fileName argument points to the string giv‐
182 ing the name of the file in which to write the image data. The format
183 argument contains the value given for the -format option, or NULL if
184 the option was not specified. The format string can contain extra
185 characters after the name of the format. If appropriate, the for‐
186 matPtr->fileWriteProc procedure may interpret these characters to spec‐
187 ify further details about the image file. The return value is a stan‐
188 dard Tcl return value.
189
192 formatPtr->stringWriteProc provides the address of a procedure for Tk
193 to call to translate image data from a photo image into a string. for‐
194 matPtr->stringWriteProc must match the following prototype:
195 typedef int Tk_ImageStringWriteProc(
196 Tcl_Interp *interp,
197 Tcl_Obj *format,
198 Tk_PhotoImageBlock *blockPtr);
199 The interp argument is the interpreter in which the command was invoked
200 to convert the image; it should be used for reporting errors. The
201 image data to be converted are in memory and are described by the
202 Tk_PhotoImageBlock structure pointed to by blockPtr; see the manual
203 page FindPhoto(3) for details. The data for the string should be put
204 in the interpreter interp result. The format argument contains the
205 value given for the -format option, or NULL if the option was not spec‐
206 ified. The format string can contain extra characters after the name
207 of the format. If appropriate, the formatPtr->stringWriteProc proce‐
208 dure may interpret these characters to specify further details about
209 the image file. The return value is a standard Tcl return value.
210
213 Tk_FindPhoto, Tk_PhotoPutBlock
214
217 photo image, image file
218Tk 8.3 Tk_CreatePhotoImageFormat(3)