1QImageIO(3qt) QImageIO(3qt)
2
6 QImageIO - Parameters for loading and saving images
7
9 #include <qimage.h>
10 Public Members
12 QImageIO ()
13 QImageIO ( QIODevice * ioDevice, const char * format )
14 QImageIO ( const QString & fileName, const char * format )
15 ~QImageIO ()
16 const QImage & image () const
17 int status () const
18 const char * format () const
19 QIODevice * ioDevice () const
20 QString fileName () const
21 int quality () const
22 QString description () const
23 const char * parameters () const
24 float gamma () const
25 void setImage ( const QImage & image )
26 void setStatus ( int status )
27 void setFormat ( const char * format )
28 void setIODevice ( QIODevice * ioDevice )
29 void setFileName ( const QString & fileName )
30 void setQuality ( int q )
31 void setDescription ( const QString & description )
32 void setParameters ( const char * parameters )
33 void setGamma ( float gamma )
34 bool read ()
35 bool write ()
36 Static Public Members
38 const char * imageFormat ( const QString & fileName )
39 const char * imageFormat ( QIODevice * d )
40 QStrList inputFormats ()
41 QStrList outputFormats ()
42 void defineIOHandler ( const char * format, const char * header, const
43 char * flags, image_io_handler readImage, image_io_handler
44 writeImage )
45
47 The QImageIO class contains parameters for loading and saving images.
48 QImageIO contains a QIODevice object that is used for image data I/O.
50 The programmer can install new image file formats in addition to those
51 that Qt provides.
52 Qt currently supports the following image file formats: PNG, BMP, XBM,
54 XPM and PNM. It may also support JPEG, MNG and GIF, if specially
55 configured during compilation. The different PNM formats are: PBM (P1
56 or P4), PGM (P2 or P5), and PPM (P3 or P6).
57 You don't normally need to use this class; QPixmap::load(),
59 QPixmap::save(), and QImage contain sufficient functionality.
60 For image files that contain sequences of images, only the first is
62 read. See QMovie for loading multiple images.
63 PBM, PGM, and PPM format output is always in the more condensed raw
65 format. PPM and PGM files with more than 256 levels of intensity are
66 scaled down when reading.
67 Warning: If you are in a country which recognizes software patents and
69 in which Unisys holds a patent on LZW compression and/or decompression
70 and you want to use GIF, Unisys may require you to license the
71 technology. Such countries include Canada, Japan, the USA, France,
72 Germany, Italy and the UK.
73 GIF support may be removed completely in a future version of Qt. We
75 recommend using the PNG format.
76 See also QImage, QPixmap, QFile, QMovie, Graphics Classes, Image
78 Processing Classes, and Input/Output and Networking.
79
82 Constructs a QImageIO object with all parameters set to zero.
83
85 Constructs a QImageIO object with the I/O device ioDevice and a format
86 tag.
87
89 Constructs a QImageIO object with the file name fileName and a format
90 tag.
91
93 Destroys the object and all related data.
94
96 const char * flags, image_io_handler readImage, image_io_handler
97 writeImage ) [static]
98 Defines an image I/O handler for the image format called format, which
99 is recognized using the regular expression header, read using readImage
100 and written using writeImage.
101 flags is a string of single-character flags for this format. The only
103 flag defined currently is T (upper case), so the only legal value for
104 flags are "T" and the empty string. The "T" flag means that the image
105 file is a text file, and Qt should treat all newline conventions as
106 equivalent. (XPM files and some PPM files are text files for example.)
107 format is used to select a handler to write a QImage; header is used to
109 select a handler to read an image file.
110 If readImage is a null pointer, the QImageIO will not be able to read
112 images in format. If writeImage is a null pointer, the QImageIO will
113 not be able to write images in format. If both are null, the QImageIO
114 object is valid but useless.
115 Example:
117 void readGIF( QImageIO *image )
119 {
120 // read the image using the image->ioDevice()
121 }
122 void writeGIF( QImageIO *image )
123 {
124 // write the image using the image->ioDevice()
125 }
126 // add the GIF image handler
127 QImageIO::defineIOHandler( "GIF",
128 "^GIF[0-9][0-9][a-z]",
129 0,
130 readGIF,
131 writeGIF );
132 Before the regex test, all the 0 bytes in the file header are converted
134 to 1 bytes. This is done because when Qt was ASCII-based, QRegExp could
135 not handle 0 bytes in strings.
136 The regexp is only applied on the first 14 bytes of the file.
138 Note that Qt assumes that there is only one handler per format; if two
140 handlers support the same format, Qt will choose one arbitrarily. It is
141 not possible to have one handler support reading, and another support
142 writing.
143
145 Returns the image description string.
146 See also setDescription().
148
150 Returns the file name currently set.
151 See also setFileName().
153
155 Returns the image format string or 0 if no format has been explicitly
156 set.
157
159 Returns the gamma value at which the image will be viewed.
160 See also setGamma().
162
164 Returns the image currently set.
165 See also setImage().
167
169 Returns a string that specifies the image format of the file fileName,
170 or null if the file cannot be read or if the format is not recognized.
171
173 This is an overloaded member function, provided for convenience. It
174 behaves essentially like the above function.
175 Returns a string that specifies the image format of the image read from
177 IO device d, or 0 if the device cannot be read or if the format is not
178 recognized.
179 Make sure that d is at the right position in the device (for example,
181 at the beginning of the file).
182 See also QIODevice::at().
184
186 Returns a sorted list of image formats that are supported for image
187 input.
188
190 Returns the IO device currently set.
191 See also setIODevice().
193
195 Returns a sorted list of image formats that are supported for image
196 output.
197 Example: scribble/scribble.cpp.
199
201 Returns the image's parameters string.
202 See also setParameters().
204
206 Returns the quality of the written image, related to the compression
207 ratio.
208 See also setQuality() and QImage::save().
210
212 Reads an image into memory and returns TRUE if the image was
213 successfully read; otherwise returns FALSE.
214 Before reading an image you must set an IO device or a file name. If
216 both an IO device and a file name have been set, the IO device will be
217 used.
218 Setting the image file format string is optional.
220 Note that this function does not set the format used to read the image.
222 If you need that information, use the imageFormat() static functions.
223 Example:
225 QImageIO iio;
227 QPixmap pixmap;
228 iio.setFileName( "vegeburger.bmp" );
229 if ( image.read() ) // ok
230 pixmap = iio.image(); // convert to pixmap
231 See also setIODevice(), setFileName(), setFormat(), write(), and
233 QPixmap::load().
234
236 Sets the image description string for image handlers that support image
237 descriptions to description.
238 Currently, no image format supported by Qt uses the description string.
240
242 Sets the name of the file to read or write an image from to fileName.
243 See also setIODevice().
245
247 Sets the image format to format for the image to be read or written.
248 It is necessary to specify a format before writing an image, but it is
250 not necessary to specify a format before reading an image.
251 If no format has been set, Qt guesses the image format before reading
253 it. If a format is set the image will only be read if it has that
254 format.
255 See also read(), write(), and format().
257
259 Sets the gamma value at which the image will be viewed to gamma. If the
260 image format stores a gamma value for which the image is intended to be
261 used, then this setting will be used to modify the image. Setting to
262 0.0 will disable gamma correction (i.e. any specification in the file
263 will be ignored).
264 The default value is 0.0.
266 See also gamma().
268
270 Sets the IO device to be used for reading or writing an image.
271 Setting the IO device allows images to be read/written to any block-
273 oriented QIODevice.
274 If ioDevice is not null, this IO device will override file name
276 settings.
277 See also setFileName().
279
281 Sets the image to image.
282 See also image().
284
286 Sets the image's parameter string to parameters. This is for image
287 handlers that require special parameters.
288 Although the current image formats supported by Qt ignore the
290 parameters string, it may be used in future extensions or by
291 contributions (for example, JPEG).
292 See also parameters().
294
296 Sets the quality of the written image to q, related to the compression
297 ratio.
298 q must be in the range -1..100. Specify 0 to obtain small compressed
300 files, 100 for large uncompressed files. (-1 signifies the default
301 compression.)
302 See also quality() and QImage::save().
304
306 Sets the image IO status to status. A non-zero value indicates an
307 error, whereas 0 means that the IO operation was successful.
308 See also status().
310
312 Returns the image's IO status. A non-zero value indicates an error,
313 whereas 0 means that the IO operation was successful.
314 See also setStatus().
316
318 Writes an image to an IO device and returns TRUE if the image was
319 successfully written; otherwise returns FALSE.
320 Before writing an image you must set an IO device or a file name. If
322 both an IO device and a file name have been set, the IO device will be
323 used.
324 The image will be written using the specified image format.
326 Example:
328 QImageIO iio;
330 QImage im;
331 im = pixmap; // convert to image
332 iio.setImage( im );
333 iio.setFileName( "vegeburger.bmp" );
334 iio.setFormat( "BMP" );
335 if ( iio.write() )
336 // returned TRUE if written successfully
337 See also setIODevice(), setFileName(), setFormat(), read(), and
339 QPixmap::save().
340
343 http://doc.trolltech.com/qimageio.html
344 http://www.trolltech.com/faq/tech.html
345
347 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
348 license file included in the distribution for a complete license
349 statement.
350
352 Generated automatically from the source code.
353
355 If you find a bug in Qt, please report it as described in
356 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
357 help you. Thank you.
358 The definitive Qt documentation is provided in HTML format; it is
360 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
361 web browser. This man page is provided as a convenience for those users
362 who prefer man pages, although this format is not officially supported
363 by Trolltech.
364 If you find errors in this manual page, please report them to qt-
366 bugs@trolltech.com. Please include the name of the manual page
367 (qimageio.3qt) and the Qt version (3.3.8).
368Trolltech AS 2 February 2007 QImageIO(3qt)