2
'\" Copyright (c) 1994 The Australian National University
3
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
5
'\" See the file "license.terms" for information on usage and redistribution
6
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
8
'\" Author: Paul Mackerras (paulus@cs.anu.edu.au),
9
'\" Department of Computer Science,
10
'\" Australian National University.
12
'\" RCS: @(#) $Id: CrtPhImgFmt.3,v 1.2 1998/09/14 18:22:47 stanton Exp $
15
.TH Tk_CreatePhotoImageFormat 3 4.0 Tk "Tk Library Procedures"
18
Tk_CreatePhotoImageFormat \- define new file format for photo images
22
\fB#include <tkPhoto.h>\fR
24
\fBTk_CreatePhotoImageFormat\fR(\fIformatPtr\fR)
26
.AS Tk_PhotoImageFormat *formatPtr
27
.AP Tk_PhotoImageFormat *formatPtr in
28
Structure that defines the new file format.
33
\fBTk_CreatePhotoImageFormat\fR is invoked to define a new file format
34
for image data for use with photo images. The code that implements an
35
image file format is called an image file format handler, or
36
handler for short. The photo image code
37
maintains a list of handlers that can be used to read and
38
write data to or from a file. Some handlers may also
39
support reading image data from a string or converting image data to a
41
The user can specify which handler to use with the \fB\-format\fR
42
image configuration option or the \fB\-format\fR option to the
43
\fBread\fR and \fBwrite\fR photo image subcommands.
45
An image file format handler consists of a collection of procedures
46
plus a Tk_PhotoImageFormat structure, which contains the name of the
47
image file format and pointers to six procedures provided by the
48
handler to deal with files and strings in this format. The
49
Tk_PhotoImageFormat structure contains the following fields:
51
typedef struct Tk_PhotoImageFormat {
53
Tk_ImageFileMatchProc *\fIfileMatchProc\fR;
54
Tk_ImageStringMatchProc *\fIstringMatchProc\fR;
55
Tk_ImageFileReadProc *\fIfileReadProc\fR;
56
Tk_ImageStringReadProc *\fIstringReadProc\fR;
57
Tk_ImageFileWriteProc *\fIfileWriteProc\fR;
58
Tk_ImageStringWriteProc *\fIstringWriteProc\fR;
59
} Tk_PhotoImageFormat;
62
The handler need not provide implementations of all six procedures.
63
For example, the procedures that handle string data would not be
64
provided for a format in which the image data are stored in binary,
65
and could therefore contain null characters. If any procedure is not
66
implemented, the corresponding pointer in the Tk_PhotoImageFormat
67
structure should be set to NULL. The handler must provide the
68
\fIfileMatchProc\fR procedure if it provides the \fIfileReadProc\fR
69
procedure, and the \fIstringMatchProc\fR procedure if it provides the
70
\fIstringReadProc\fR procedure.
74
\fIformatPtr->name\fR provides a name for the image type.
75
Once \fBTk_CreatePhotoImageFormat\fR returns, this name may be used
76
in the \fB\-format\fR photo image configuration and subcommand option.
77
The manual page for the photo image (photo(n)) describes how image
78
file formats are chosen based on their names and the value given to
79
the \fB\-format\fR option.
82
\fIformatPtr->fileMatchProc\fR provides the address of a procedure for
83
Tk to call when it is searching for an image file format handler
84
suitable for reading data in a given file.
85
\fIformatPtr->fileMatchProc\fR must match the following prototype:
87
typedef int Tk_ImageFileMatchProc(
88
Tcl_Channel \fIchan\fR,
90
char *\fIformatString\fR,
92
int *\fIheightPtr\fR);
94
The \fIfileName\fR argument is the name of the file containing the
95
image data, which is open for reading as \fIchan\fR. The
96
\fIformatString\fR argument contains the value given for the
97
\fB\-format\fR option, or NULL if the option was not specified.
98
If the data in the file appears to be in the format supported by this
99
handler, the \fIformatPtr->fileMatchProc\fR procedure should store the
100
width and height of the image in *\fIwidthPtr\fR and *\fIheightPtr\fR
101
respectively, and return 1. Otherwise it should return 0.
104
\fIformatPtr->stringMatchProc\fR provides the address of a procedure for
105
Tk to call when it is searching for an image file format handler for
106
suitable for reading data from a given string.
107
\fIformatPtr->stringMatchProc\fR must match the following prototype:
109
typedef int Tk_ImageStringMatchProc(
111
char *\fIformatString\fR,
113
int *\fIheightPtr\fR);
115
The \fIstring\fR argument points to the string containing the image
116
data. The \fIformatString\fR argument contains the value given for
117
the \fB\-format\fR option, or NULL if the option was not specified.
118
If the data in the string appears to be in the format supported by
119
this handler, the \fIformatPtr->stringMatchProc\fR procedure should
120
store the width and height of the image in *\fIwidthPtr\fR and
121
*\fIheightPtr\fR respectively, and return 1. Otherwise it should
125
\fIformatPtr->fileReadProc\fR provides the address of a procedure for
126
Tk to call to read data from an image file into a photo image.
127
\fIformatPtr->fileReadProc\fR must match the following prototype:
129
typedef int Tk_ImageFileReadProc(
130
Tcl_Interp *\fIinterp\fR,
131
Tcl_Channel \fIchan\fR,
132
char *\fIfileName\fR,
133
char *\fIformatString\fR,
134
PhotoHandle \fIimageHandle\fR,
135
int \fIdestX\fR, int \fIdestY\fR,
136
int \fIwidth\fR, int \fIheight\fR,
137
int \fIsrcX\fR, int \fIsrcY\fR);
139
The \fIinterp\fR argument is the interpreter in which the command was
140
invoked to read the image; it should be used for reporting errors.
141
The image data is in the file named \fIfileName\fR, which is open for
142
reading as \fIchan\fR. The \fIformatString\fR argument contains the
143
value given for the \fB\-format\fR option, or NULL if the option was
144
not specified. The image data in the file, or a subimage of it, is to
145
be read into the photo image identified by the handle
146
\fIimageHandle\fR. The subimage of the data in the file is of
147
dimensions \fIwidth\fR x \fIheight\fR and has its top-left corner at
148
coordinates (\fIsrcX\fR,\fIsrcY\fR). It is to be stored in the photo
149
image with its top-left corner at coordinates
150
(\fIdestX\fR,\fIdestY\fR) using the \fBTk_PhotoPutBlock\fR procedure.
151
The return value is a standard Tcl return value.
154
\fIformatPtr->stringReadProc\fR provides the address of a procedure for
155
Tk to call to read data from a string into a photo image.
156
\fIformatPtr->stringReadProc\fR must match the following prototype:
158
typedef int Tk_ImageStringReadProc(
159
Tcl_Interp *\fIinterp\fR,
161
char *\fIformatString\fR,
162
PhotoHandle \fIimageHandle\fR,
163
int \fIdestX\fR, int \fIdestY\fR,
164
int \fIwidth\fR, int \fIheight\fR,
165
int \fIsrcX\fR, int \fIsrcY\fR);
167
The \fIinterp\fR argument is the interpreter in which the command was
168
invoked to read the image; it should be used for reporting errors.
169
The \fIstring\fR argument points to the image data in string form.
170
The \fIformatString\fR argument contains the
171
value given for the \fB\-format\fR option, or NULL if the option was
172
not specified. The image data in the string, or a subimage of it, is to
173
be read into the photo image identified by the handle
174
\fIimageHandle\fR. The subimage of the data in the string is of
175
dimensions \fIwidth\fR x \fIheight\fR and has its top-left corner at
176
coordinates (\fIsrcX\fR,\fIsrcY\fR). It is to be stored in the photo
177
image with its top-left corner at coordinates
178
(\fIdestX\fR,\fIdestY\fR) using the \fBTk_PhotoPutBlock\fR procedure.
179
The return value is a standard Tcl return value.
182
\fIformatPtr->fileWriteProc\fR provides the address of a procedure for
183
Tk to call to write data from a photo image to a file.
184
\fIformatPtr->fileWriteProc\fR must match the following prototype:
186
typedef int Tk_ImageFileWriteProc(
187
Tcl_Interp *\fIinterp\fR,
188
char *\fIfileName\fR,
189
char *\fIformatString\fR,
190
Tk_PhotoImageBlock *\fIblockPtr\fR);
192
The \fIinterp\fR argument is the interpreter in which the command was
193
invoked to write the image; it should be used for reporting errors.
194
The image data to be written are in memory and are described by the
195
Tk_PhotoImageBlock structure pointed to by \fIblockPtr\fR; see the
196
manual page FindPhoto(3) for details. The \fIfileName\fR argument
197
points to the string giving the name of the file in which to write the
198
image data. The \fIformatString\fR argument contains the
199
value given for the \fB\-format\fR option, or NULL if the option was
200
not specified. The format string can contain extra characters
201
after the name of the format. If appropriate, the
202
\fIformatPtr->fileWriteProc\fR procedure may interpret these
203
characters to specify further details about the image file.
204
The return value is a standard Tcl return value.
207
\fIformatPtr->stringWriteProc\fR provides the address of a procedure for
208
Tk to call to translate image data from a photo image into a string.
209
\fIformatPtr->stringWriteProc\fR must match the following prototype:
211
typedef int Tk_ImageStringWriteProc(
212
Tcl_Interp *\fIinterp\fR,
213
Tcl_DString *\fIdataPtr\fR,
214
char *\fIformatString\fR,
215
Tk_PhotoImageBlock *\fIblockPtr\fR);
217
The \fIinterp\fR argument is the interpreter in which the command was
218
invoked to convert the image; it should be used for reporting errors.
219
The image data to be converted are in memory and are described by the
220
Tk_PhotoImageBlock structure pointed to by \fIblockPtr\fR; see the
221
manual page FindPhoto(3) for details. The data for the string
222
should be appended to the dynamic string given by \fIdataPtr\fR.
223
The \fIformatString\fR argument contains the
224
value given for the \fB\-format\fR option, or NULL if the option was
225
not specified. The format string can contain extra characters
226
after the name of the format. If appropriate, the
227
\fIformatPtr->stringWriteProc\fR procedure may interpret these
228
characters to specify further details about the image file.
229
The return value is a standard Tcl return value.
232
Tk_FindPhoto, Tk_PhotoPutBlock
235
photo image, image file
added
removed
doc/CrtPhImgFmt.3
