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