3
3
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
4
4
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
5
<!-- /tmp/qt-4.1.4-harald-1150713676011/qt-x11-opensource-src-4.1.4/src/gui/image/qimagereader.cpp -->
6
<!-- /tmp/qt-4.1.4-harald-1150713676011/qt-x11-opensource-src-4.1.4/src/gui/image/qimagereader.cpp -->
5
<!-- /tmp/qt-4.2.0-qt-1159540607313/qt-x11-opensource-src-4.2.0/src/gui/image/qimagereader.cpp -->
8
<title>Qt 4.1: QImageReader Class Reference</title>
9
<style>h3.fn,span.fn { margin-left: 1cm; text-indent: -1cm; }
10
a:link { color: #004faf; text-decoration: none }
11
a:visited { color: #672967; text-decoration: none }
12
td.postheader { font-family: sans-serif }
13
tr.address { font-family: sans-serif }
14
body { background: #ffffff; color: black; }</style>
7
<title>Qt 4.2: QImageReader Class Reference</title>
8
<link href="classic.css" rel="stylesheet" type="text/css" />
17
11
<table border="0" cellpadding="0" cellspacing="0" width="100%">
19
<td align="left" valign="top" width="32"><img src="images/qt-logo.png" align="left" width="32" height="32" border="0" /></td>
13
<td align="left" valign="top" width="32"><a href="http://www.trolltech.com/products/qt"><img src="images/qt-logo.png" align="left" width="32" height="32" border="0" /></a></td>
20
14
<td width="1"> </td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a> · <a href="classes.html"><font color="#004faf">All Classes</font></a> · <a href="mainclasses.html"><font color="#004faf">Main Classes</font></a> · <a href="groups.html"><font color="#004faf">Grouped Classes</font></a> · <a href="modules.html"><font color="#004faf">Modules</font></a> · <a href="functions.html"><font color="#004faf">Functions</font></a></td>
21
<td align="right" valign="top" width="230"><img src="images/trolltech-logo.png" align="right" width="203" height="32" border="0" /></td></tr></table><h1 align="center">QImageReader Class Reference<br /><sup><sup>[<a href="qtgui.html">QtGui</a> module]</sup></sup></h1>
15
<td align="right" valign="top" width="230"><a href="http://www.trolltech.com"><img src="images/trolltech-logo.png" align="right" width="203" height="32" border="0" /></a></td></tr></table><h1 align="center">QImageReader Class Reference<br /><sup><sup>[<a href="qtgui.html">QtGui</a> module]</sup></sup></h1>
22
16
<p>The QImageReader class provides a format independent interface for reading images from files or other devices. <a href="#details">More...</a></p>
23
<pre>#include <QImageReader></pre><p><b>Note:</b> All the functions in this class are <a href="threads.html#reentrant">reentrant</a>.</p>
17
<pre> #include <QImageReader></pre><p><b>Note:</b> All the functions in this class are <a href="threads.html#reentrant">reentrant</a>.</p>
25
19
<li><a href="qimagereader-members.html">List of all members, including inherited members</a></li>
51
45
<li><div class="fn"/>bool <b><a href="qimagereader.html#jumpToNextImage">jumpToNextImage</a></b> ()</li>
52
46
<li><div class="fn"/>int <b><a href="qimagereader.html#loopCount">loopCount</a></b> () const</li>
53
47
<li><div class="fn"/>int <b><a href="qimagereader.html#nextImageDelay">nextImageDelay</a></b> () const</li>
48
<li><div class="fn"/>int <b><a href="qimagereader.html#quality">quality</a></b> () const</li>
54
49
<li><div class="fn"/>QImage <b><a href="qimagereader.html#read">read</a></b> ()</li>
50
<li><div class="fn"/>bool <b><a href="qimagereader.html#read-2">read</a></b> ( QImage * <i>image</i> )</li>
55
51
<li><div class="fn"/>QRect <b><a href="qimagereader.html#scaledClipRect">scaledClipRect</a></b> () const</li>
56
52
<li><div class="fn"/>QSize <b><a href="qimagereader.html#scaledSize">scaledSize</a></b> () const</li>
57
53
<li><div class="fn"/>void <b><a href="qimagereader.html#setBackgroundColor">setBackgroundColor</a></b> ( const QColor & <i>color</i> )</li>
59
55
<li><div class="fn"/>void <b><a href="qimagereader.html#setDevice">setDevice</a></b> ( QIODevice * <i>device</i> )</li>
60
56
<li><div class="fn"/>void <b><a href="qimagereader.html#setFileName">setFileName</a></b> ( const QString & <i>fileName</i> )</li>
61
57
<li><div class="fn"/>void <b><a href="qimagereader.html#setFormat">setFormat</a></b> ( const QByteArray & <i>format</i> )</li>
58
<li><div class="fn"/>void <b><a href="qimagereader.html#setQuality">setQuality</a></b> ( int <i>quality</i> )</li>
62
59
<li><div class="fn"/>void <b><a href="qimagereader.html#setScaledClipRect">setScaledClipRect</a></b> ( const QRect & <i>rect</i> )</li>
63
60
<li><div class="fn"/>void <b><a href="qimagereader.html#setScaledSize">setScaledSize</a></b> ( const QSize & <i>size</i> )</li>
64
61
<li><div class="fn"/>QSize <b><a href="qimagereader.html#size">size</a></b> () const</li>
65
62
<li><div class="fn"/>bool <b><a href="qimagereader.html#supportsAnimation">supportsAnimation</a></b> () const</li>
63
<li><div class="fn"/>bool <b><a href="qimagereader.html#supportsOption">supportsOption</a></b> ( QImageIOHandler::ImageOption <i>option</i> ) const</li>
66
64
<li><div class="fn"/>QString <b><a href="qimagereader.html#text">text</a></b> ( const QString & <i>key</i> ) const</li>
67
65
<li><div class="fn"/>QStringList <b><a href="qimagereader.html#textKeys">textKeys</a></b> () const</li>
81
79
<p>To read an image, you start by constructing a QImageReader object. Pass either a file name or a device pointer, and the image format to QImageReader's constructor. You can then set several options, such as the clip rect (by calling <a href="qimagereader.html#setClipRect">setClipRect</a>()) and scaled size (by calling <a href="qimagereader.html#setScaledSize">setScaledSize</a>()). <a href="qimagereader.html#canRead">canRead</a>() returns the image if the QImageReader can read the image (i.e., the image format is supported and the device is open for reading). Call <a href="qimagereader.html#read">read</a>() to read the image.</p>
82
80
<p>If any error occurs when reading the image, <a href="qimagereader.html#read">read</a>() will return a null <a href="qimage.html">QImage</a>. You can then call <a href="qimagereader.html#error">error</a>() to find the type of error that occurred, or <a href="qimagereader.html#errorString">errorString</a>() to get a human readable description of what went wrong.</p>
83
81
<p>Call <a href="qimagereader.html#supportedImageFormats">supportedImageFormats</a>() for a list of formats that QImageReader can read. QImageReader supports all built-in image formats, in addition to any image format plugins that support reading.</p>
84
<p>Qt supports GIF reading if it is configured that way during installation. If it is, we are required to state that "The Graphics Interchange Format(c) is the Copyright property of CompuServe Incorporated. GIF(sm) is a Service Mark property of CompuServe Incorporated."</p>
82
<div style="padding: 0.5em; background: #e0e0e0; color: black"><p>Qt supports GIF reading if it is configured that way during installation. If it is, we are required to state that "The Graphics Interchange Format(c) is the Copyright property of CompuServe Incorporated. GIF(sm) is a Service Mark property of CompuServe Incorporated."</p>
85
83
<p><b>Warning:</b> If you are in a country that recognizes software patents and in which Unisys holds a patent on LZW compression and/or decompression and you want to use GIF, Unisys may require you to license that technology. Such countries include Canada, Japan, the US, France, Germany, Italy and the UK.</p>
86
84
<p>GIF support may be removed completely in a future version of Qt. We recommend using the MNG or PNG format.</p>
87
<p>See also <a href="qimagewriter.html">QImageWriter</a>, <a href="qimageiohandler.html">QImageIOHandler</a>, and <a href="qimageioplugin.html">QImageIOPlugin</a>.</p>
85
</div><p>See also <a href="qimagewriter.html">QImageWriter</a>, <a href="qimageiohandler.html">QImageIOHandler</a>, and <a href="qimageioplugin.html">QImageIOPlugin</a>.</p>
89
87
<h2>Member Type Documentation</h2>
90
88
<h3 class="fn"><a name="ImageReaderError-enum"></a>enum QImageReader::ImageReaderError</h3>
140
138
<p>See also <a href="qimagereader.html#setFileName">setFileName</a>() and <a href="qimagereader.html#setDevice">setDevice</a>().</p>
141
139
<h3 class="fn"><a name="format"></a><a href="qbytearray.html">QByteArray</a> QImageReader::format () const</h3>
142
140
<p>Returns the format <a href="qimagereader.html">QImageReader</a> uses for reading images.</p>
141
<p>You can call this function after assigning a device to the reader to determine the format of the device. For example:</p>
142
<pre> QImageReader reader("image.png");
143
<span class="comment"> // reader.format() == "png"</span></pre>
143
144
<p>See also <a href="qimagereader.html#setFormat">setFormat</a>().</p>
144
145
<h3 class="fn"><a name="imageCount"></a>int QImageReader::imageCount () const</h3>
145
146
<p>For image formats that support animation, this function returns the total number of images in the animation.</p>
163
164
<h3 class="fn"><a name="nextImageDelay"></a>int QImageReader::nextImageDelay () const</h3>
164
165
<p>For image formats that support animation, this function returns the number of milliseconds to wait until displaying the next frame in the animation. Otherwise, 0 is returned.</p>
165
166
<p>See also <a href="qimagereader.html#supportsAnimation">supportsAnimation</a>() and <a href="qimageiohandler.html#nextImageDelay">QImageIOHandler::nextImageDelay</a>().</p>
167
<h3 class="fn"><a name="quality"></a>int QImageReader::quality () const</h3>
168
<p>Returns the quality level of the image.</p>
169
<p>This function was introduced in Qt 4.2.</p>
170
<p>See also <a href="qimagereader.html#setQuality">setQuality</a>().</p>
166
171
<h3 class="fn"><a name="read"></a><a href="qimage.html">QImage</a> QImageReader::read ()</h3>
167
172
<p>Reads an image from the device. On success, the image that was read is returned; otherwise, a null <a href="qimage.html">QImage</a> is returned. You can then call <a href="qimagereader.html#error">error</a>() to find the type of error that occurred, or <a href="qimagereader.html#errorString">errorString</a>() to get a human readable description of the error.</p>
168
173
<p>For image formats that support animation, calling read() repeatedly will return the next frame. When all frames have been read, a null image will be returned.</p>
169
174
<p>See also <a href="qimagereader.html#canRead">canRead</a>(), <a href="qimagereader.html#supportedImageFormats">supportedImageFormats</a>(), <a href="qimagereader.html#supportsAnimation">supportsAnimation</a>(), and <a href="qmovie.html">QMovie</a>.</p>
175
<h3 class="fn"><a name="read-2"></a>bool QImageReader::read ( <a href="qimage.html">QImage</a> * <i>image</i> )</h3>
176
<p>This is an overloaded member function, provided for convenience.</p>
177
<p>Reads an image from the device into <i>image</i>, which must point to a <a href="qimage.html">QImage</a>. Returns true on success; otherwise, returns false.</p>
178
<p>If <i>image</i> has same format and size as the image data that is about to be read, this function may not need to allocate a new image before reading. Because of this, it can be faster than the other <a href="qimagereader.html#read">read</a>() overload, which always constructs a new image; especially when reading several images with the same format and size.</p>
179
<pre> QImage icon(64, 64, QImage::Format_RGB32);
180
QImageReader reader("icon_64x64.bmp");
181
if (reader.read(&icon)) {
182
<span class="comment">// Display icon</span>
184
<p>For image formats that support animation, calling <a href="qimagereader.html#read">read</a>() repeatedly will return the next frame. When all frames have been read, a null image will be returned.</p>
185
<p>See also <a href="qimagereader.html#canRead">canRead</a>(), <a href="qimagereader.html#supportedImageFormats">supportedImageFormats</a>(), <a href="qimagereader.html#supportsAnimation">supportsAnimation</a>(), and <a href="qmovie.html">QMovie</a>.</p>
170
186
<h3 class="fn"><a name="scaledClipRect"></a><a href="qrect.html">QRect</a> QImageReader::scaledClipRect () const</h3>
171
187
<p>Returns the scaled clip rect of the image.</p>
172
188
<p>See also <a href="qimagereader.html#setScaledClipRect">setScaledClipRect</a>().</p>
190
206
<p>See also <a href="qimagereader.html#fileName">fileName</a>(), <a href="qimagereader.html#setDevice">setDevice</a>(), and <a href="qimagereader.html#supportedImageFormats">supportedImageFormats</a>().</p>
191
207
<h3 class="fn"><a name="setFormat"></a>void QImageReader::setFormat ( const <a href="qbytearray.html">QByteArray</a> & <i>format</i> )</h3>
192
208
<p>Sets the format <a href="qimagereader.html">QImageReader</a> will use when reading images, to <i>format</i>. <i>format</i> is a case insensitive text string. Example:</p>
193
<pre> QImageReader reader;
194
reader.setFormat("png"); // same as reader.setFormat("PNG");</pre>
209
<pre> QImageReader reader;
210
reader.setFormat("png"); <span class="comment">// same as reader.setFormat("PNG");</span></pre>
195
211
<p>You can call <a href="qimagereader.html#supportedImageFormats">supportedImageFormats</a>() for the full list of formats <a href="qimagereader.html">QImageReader</a> supports.</p>
196
212
<p>See also <a href="qimagereader.html#format">format</a>().</p>
213
<h3 class="fn"><a name="setQuality"></a>void QImageReader::setQuality ( int <i>quality</i> )</h3>
214
<p>This is an image format specific function that sets the quality level of the image to <i>quality</i>. For image formats that do not support setting the quality, this value is ignored.</p>
215
<p>The value range of <i>quality</i> depends on the image format. For example, the "jpeg" format supports a quality range from 0 (low quality, high compression) to 100 (high quality, low compression).</p>
216
<p>This function was introduced in Qt 4.2.</p>
217
<p>See also <a href="qimagereader.html#quality">quality</a>().</p>
197
218
<h3 class="fn"><a name="setScaledClipRect"></a>void QImageReader::setScaledClipRect ( const <a href="qrect.html">QRect</a> & <i>rect</i> )</h3>
198
219
<p>Sets the scaled clip rect to <i>rect</i>. The scaled clip rect is the clip rect (also known as ROI, or Region Of Interest) that is applied after the image has been scaled.</p>
199
220
<p>See also <a href="qimagereader.html#scaledClipRect">scaledClipRect</a>() and <a href="qimagereader.html#setScaledSize">setScaledSize</a>().</p>
201
222
<p>Sets the scaled size of the image to <i>size</i>. The scaling is performed after the initial clip rect, but before the scaled clip rect is applied. The algorithm used for scaling depends on the image format. By default (i.e., if the image format does not support scaling), <a href="qimagereader.html">QImageReader</a> will use QImage::scale() with Qt::SmoothScaling.</p>
202
223
<p>See also <a href="qimagereader.html#scaledSize">scaledSize</a>(), <a href="qimagereader.html#setClipRect">setClipRect</a>(), and <a href="qimagereader.html#setScaledClipRect">setScaledClipRect</a>().</p>
203
224
<h3 class="fn"><a name="size"></a><a href="qsize.html">QSize</a> QImageReader::size () const</h3>
204
<p>Returns the size of the image. This function may or may not read the entire image, depending on whether the image format supports checking the size of an image before loading it.</p>
225
<p>Returns the size of the image, without actually reading the image contents.</p>
226
<p>If the image format does not support this feature, this function returns an invalid size. Qt's built-in image handlers all support this feature, but custom image format plugins are not required to do so.</p>
227
<p>See also <a href="qimageiohandler.html#ImageOption-enum">QImageIOHandler::ImageOption</a>, <a href="qimageiohandler.html#option">QImageIOHandler::option</a>(), and <a href="qimageiohandler.html#supportsOption">QImageIOHandler::supportsOption</a>().</p>
205
228
<h3 class="fn"><a name="supportedImageFormats"></a><a href="qlist.html">QList</a><<a href="qbytearray.html">QByteArray</a>> QImageReader::supportedImageFormats () <tt> [static]</tt></h3>
206
229
<p>Returns the list of image formats supported by <a href="qimagereader.html">QImageReader</a>.</p>
207
230
<p>By default, Qt can read the following formats:</p>
208
231
<p><table align="center" cellpadding="2" cellspacing="1" border="0">
209
<tr valign="top" bgcolor="#a2c511"><th>Format</th><th>Description</th></tr>
210
<tr valign="top" bgcolor="#f0f0f0"><td>BMP</td><td>Windows Bitmap</td></tr>
211
<tr valign="top" bgcolor="#e0e0e0"><td>GIF</td><td>Graphic Interchange Format (optional)</td></tr>
212
<tr valign="top" bgcolor="#f0f0f0"><td>JPG</td><td>Joint Photographic Experts Group</td></tr>
213
<tr valign="top" bgcolor="#e0e0e0"><td>JPEG</td><td>Joint Photographic Experts Group</td></tr>
214
<tr valign="top" bgcolor="#f0f0f0"><td>MNG</td><td>Multiple-image Network Graphics</td></tr>
215
<tr valign="top" bgcolor="#e0e0e0"><td>PNG</td><td>Portable Network Graphics</td></tr>
216
<tr valign="top" bgcolor="#f0f0f0"><td>PBM</td><td>Portable Bitmap</td></tr>
217
<tr valign="top" bgcolor="#e0e0e0"><td>PGM</td><td>Portable Graymap</td></tr>
218
<tr valign="top" bgcolor="#f0f0f0"><td>PPM</td><td>Portable Pixmap</td></tr>
219
<tr valign="top" bgcolor="#e0e0e0"><td>XBM</td><td>X11 Bitmap</td></tr>
220
<tr valign="top" bgcolor="#f0f0f0"><td>XPM</td><td>X11 Pixmap</td></tr>
232
<thead><tr valign="top" class="qt-style"><th>Format</th><th>Description</th></tr></thead>
233
<tr valign="top" class="odd"><td>BMP</td><td>Windows Bitmap</td></tr>
234
<tr valign="top" class="even"><td>GIF</td><td>Graphic Interchange Format (optional)</td></tr>
235
<tr valign="top" class="odd"><td>JPG</td><td>Joint Photographic Experts Group</td></tr>
236
<tr valign="top" class="even"><td>JPEG</td><td>Joint Photographic Experts Group</td></tr>
237
<tr valign="top" class="odd"><td>MNG</td><td>Multiple-image Network Graphics</td></tr>
238
<tr valign="top" class="even"><td>PNG</td><td>Portable Network Graphics</td></tr>
239
<tr valign="top" class="odd"><td>PBM</td><td>Portable Bitmap</td></tr>
240
<tr valign="top" class="even"><td>PGM</td><td>Portable Graymap</td></tr>
241
<tr valign="top" class="odd"><td>PPM</td><td>Portable Pixmap</td></tr>
242
<tr valign="top" class="even"><td>XBM</td><td>X11 Bitmap</td></tr>
243
<tr valign="top" class="odd"><td>XPM</td><td>X11 Pixmap</td></tr>
222
245
<p>To configure Qt with GIF support, pass <tt>-qt-gif</tt> to the <tt>configure</tt> script or check the appropriate option in the graphical installer.</p>
223
246
<p>See also <a href="qimagereader.html#setFormat">setFormat</a>(), <a href="qimagewriter.html#supportedImageFormats">QImageWriter::supportedImageFormats</a>(), and <a href="qimageioplugin.html">QImageIOPlugin</a>.</p>
225
248
<p>Returns true if the image format supports animation; otherwise, false is returned.</p>
226
249
<p>This function was introduced in Qt 4.1.</p>
227
250
<p>See also <a href="qmovie.html#supportedFormats">QMovie::supportedFormats</a>().</p>
251
<h3 class="fn"><a name="supportsOption"></a>bool QImageReader::supportsOption ( <a href="qimageiohandler.html#ImageOption-enum">QImageIOHandler::ImageOption</a> <i>option</i> ) const</h3>
252
<p>Returns true if the reader supports <i>option</i>; otherwise returns false.</p>
253
<p>Different image formats support different options. Call this function to determine whether a certain option is supported by the current format. For example, the PNG format allows you to embed text into the image's metadata (see <a href="qimagereader.html#text">text</a>()), and the BMP format allows you to determine the image's size without loading the whole image into memory (see <a href="qimagereader.html#size">size</a>()).</p>
254
<pre> QImageReader reader(":/image.png");
255
if (reader.supportsOption(QImageIOHandler::Size))
256
qDebug() << "Size:" << reader.size();</pre>
257
<p>This function was introduced in Qt 4.2.</p>
258
<p>See also <a href="qimagewriter.html#supportsOption">QImageWriter::supportsOption</a>().</p>
228
259
<h3 class="fn"><a name="text"></a><a href="qstring.html">QString</a> QImageReader::text ( const <a href="qstring.html">QString</a> & <i>key</i> ) const</h3>
229
260
<p>Returns the image text associated with <i>key</i>.</p>
230
261
<p>Support for this option is implemented through <a href="qimageiohandler.html#ImageOption-enum">QImageIOHandler::Description</a>.</p>
added
removed
doc/html/qimagereader.html
