~oif-team/ubuntu/natty/qt4-x11/xi2.1

<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="annotated.html"><font color="#004faf">Annotated</font></a> · <a href="groups.html"><font color="#004faf">Grouped Classes</font></a> · <a href="functions.html"><font color="#004faf">Functions</font></a></td>

<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">QIcon Class Reference</h1>

<p>The QIcon class provides scalable icons in different modes and states. <a href="#details">More...</a></p>

<pre>#include <QIcon></pre><p>Part of the <a href="qtgui.html">QtGui</a> module.</p>

<ul>

<li><a href="qicon-members.html">List of all members, including inherited members</a></li>

<li><a href="qicon-qt3.html">Qt 3 support members</a></li>

</ul>

<h3>Public Types</h3>

<ul>

<li><div class="fn"/>enum <b><a href="qicon.html#Mode-enum">Mode</a></b> { Normal, Disabled, Active }</li>

<li><div class="fn"/>enum <b><a href="qicon.html#State-enum">State</a></b> { Off, On }</li>

</ul>

<h3>Public Functions</h3>

<ul>

<li><div class="fn"/><b><a href="qicon.html#QIcon">QIcon</a></b> ()</li>

<li><div class="fn"/><b><a href="qicon.html#QIcon-2">QIcon</a></b> ( const QPixmap & <i>pixmap</i> )</li>

<li><div class="fn"/><b><a href="qicon.html#QIcon-3">QIcon</a></b> ( const QIcon & <i>other</i> )</li>

<li><div class="fn"/><b><a href="qicon.html#QIcon-4">QIcon</a></b> ( const QString & <i>fileName</i> )</li>

<li><div class="fn"/><b><a href="qicon.html#QIcon-5">QIcon</a></b> ( QIconEngine * <i>engine</i> )</li>

<li><div class="fn"/><b><a href="qicon.html#dtor.QIcon">~QIcon</a></b> ()</li>

<li><div class="fn"/>QSize <b><a href="qicon.html#actualSize">actualSize</a></b> ( const QSize & <i>size</i>, Mode <i>mode</i> = Normal, State <i>state</i> = Off ) const</li>

<li><div class="fn"/>void <b><a href="qicon.html#addFile">addFile</a></b> ( const QString & <i>fileName</i>, const QSize & <i>size</i> = QSize(), Mode <i>mode</i> = Normal, State <i>state</i> = Off )</li>

<li><div class="fn"/>void <b><a href="qicon.html#addPixmap">addPixmap</a></b> ( const QPixmap & <i>pixmap</i>, Mode <i>mode</i> = Normal, State <i>state</i> = Off )</li>

<li><div class="fn"/>bool <b><a href="qicon.html#isNull">isNull</a></b> () const</li>

<li><div class="fn"/>void <b><a href="qicon.html#paint">paint</a></b> ( QPainter * <i>painter</i>, const QRect & <i>rect</i>, Qt::Alignment <i>alignment</i> = Qt::AlignCenter, Mode <i>mode</i> = Normal, State <i>state</i> = Off ) const</li>

<li><div class="fn"/>void <b><a href="qicon.html#paint-2">paint</a></b> ( QPainter * <i>painter</i>, int <i>x</i>, int <i>y</i>, int <i>w</i>, int <i>h</i>, Qt::Alignment <i>alignment</i> = Qt::AlignCenter, Mode <i>mode</i> = Normal, State <i>state</i> = Off ) const</li>

<li><div class="fn"/>QPixmap <b><a href="qicon.html#pixmap">pixmap</a></b> ( const QSize & <i>size</i>, Mode <i>mode</i> = Normal, State <i>state</i> = Off ) const</li>

<li><div class="fn"/>QPixmap <b><a href="qicon.html#pixmap-5">pixmap</a></b> ( int <i>w</i>, int <i>h</i>, Mode <i>mode</i> = Normal, State <i>state</i> = Off ) const</li>

<li><div class="fn"/>QPixmap <b><a href="qicon.html#pixmap-6">pixmap</a></b> ( int <i>extent</i>, Mode <i>mode</i> = Normal, State <i>state</i> = Off ) const</li>

<li><div class="fn"/>int <b><a href="qicon.html#serialNumber">serialNumber</a></b> () const</li>

<li><div class="fn"/><b><a href="qicon.html#operator-QVariant">operator QVariant</a></b> () const</li>

<li><div class="fn"/>QIcon & <b><a href="qicon.html#operator-eq">operator=</a></b> ( const QIcon & <i>other</i> )</li>

</ul>

<hr />

<h2>Detailed Description</h2>

<p>The QIcon class provides scalable icons in different modes and states.</p>

<p>A QIcon can generate smaller, larger, active, and disabled pixmaps from the set of pixmaps it is given. Such pixmaps are used by Qt widgets to show an icon representing a particular action.</p>

<p>The simplest use of QIcon is to create one from a <a href="qpixmap.html">QPixmap</a> file or resource, and then use it, allowing Qt to work out all the required icon styles and sizes. For example:</p>

<pre>  QToolButton *button = new QToolButton;

button->setIcon(QIcon("open.xpm"));</pre>

<p>When you retrieve a pixmap using pixmap(<a href="qsize.html">QSize</a>, Mode, State), and no pixmap for this given size, mode and state has been added with <a href="qicon.html#addFile">addFile</a>() or <a href="qicon.html#addPixmap">addPixmap</a>(), then QIcon will generate one on the fly. This pixmap generation happens in a <a href="qiconengine.html">QIconEngine</a>. The default engine scales pixmaps down if required, but never up, and it uses the current style to calculate a disabled appearance. By using custom icon engines, you can customize every aspect of generated icons. With <a href="qiconengineplugin.html">QIconEnginePlugin</a> it is possible to register different icon engines for different file suffixes, so you could provide a SVG icon engine or any other scalable format.</p>

<h3>Making Classes that Use QIcon</h3>

<p>If you write your own widgets that have an option to set a small pixmap, consider allowing a QIcon to be set for that pixmap. The Qt class <a href="qtoolbutton.html">QToolButton</a> is an example of such a widget.</p>

<p>Provide a method to set a QIcon, and when you draw the icon, choose whichever pixmap is appropriate for the current state of your widget. For example:</p>

<pre>  void MyWidget::drawIcon(QPainter *painter, QPoint pos)

{

QPixmap pixmap = icon.pixmap(QSize(22, 22),

isEnabled() ? QIcon::Normal

: QIcon::Disabled,

isOn() ? QIcon::On

: QIcon::Off);

painter->drawPixmap(pos, pixmap);

}</pre>

<p>You might also make use of the <tt>Active</tt> mode, perhaps making your widget <tt>Active</tt> when the mouse is over the widget (see <a href="qwidget.html#enterEvent">QWidget::enterEvent</a>()), while the mouse is pressed pending the release that will activate the function, or when it is the currently selected item. If the widget can be toggled, the "On" mode might be used to draw a different icon.</p>

<center><img src="images/icon.png" alt="QIcon" /></center><p>See also <a href="guibooks.html#fowler">GUI Design Handbook: Iconic Label</a>.</p>

<hr />

<h2>Member Type Documentation</h2>

<h3 class="fn"><a name="Mode-enum"></a>enum QIcon::Mode</h3>

<p>This enum type describes the mode for which a pixmap is intended to be used. The currently defined modes are:</p>

<tr><th width="25%">Constant</th><th width="15%">Value</th><th width="60%">Description</th></tr>

<tr><td valign="top"><tt>QIcon::Normal</tt></td><td align="center" valign="top"><tt>0</tt></td><td valign="top">Display the pixmap when the user is not interacting with the icon, but the functionality represented by the icon is available.</td></tr>

<tr><td valign="top"><tt>QIcon::Disabled</tt></td><td align="center" valign="top"><tt>1</tt></td><td valign="top">Display the pixmap when the functionality represented by the icon is not available.</td></tr>

<tr><td valign="top"><tt>QIcon::Active</tt></td><td align="center" valign="top"><tt>2</tt></td><td valign="top">Display the pixmap when the functionality represented by the icon is available and the user is interacting with the icon, for example, moving the mouse over it or clicking it.</td></tr>

</table>

<h3 class="fn"><a name="State-enum"></a>enum QIcon::State</h3>

<p>This enum describes the state for which a pixmap is intended to be used. The <i>state</i> can be:</p>

<tr><th width="25%">Constant</th><th width="15%">Value</th><th width="60%">Description</th></tr>

<tr><td valign="top"><tt>QIcon::Off</tt></td><td align="center" valign="top"><tt>1</tt></td><td valign="top">Display the pixmap when the widget is in an "off" state</td></tr>

<tr><td valign="top"><tt>QIcon::On</tt></td><td align="center" valign="top"><tt>0</tt></td><td valign="top">Display the pixmap when the widget is in an "on" state</td></tr>

</table>

<hr />

<h2>Member Function Documentation</h2>

<h3 class="fn"><a name="QIcon"></a>QIcon::QIcon ()</h3>

<p>Constructs a null icon.</p>

100

<h3 class="fn"><a name="QIcon-2"></a>QIcon::QIcon ( const <a href="qpixmap.html">QPixmap</a> & <i>pixmap</i> )</h3>

101

<p>Constructs an icon from a <i>pixmap</i>.</p>

102

<h3 class="fn"><a name="QIcon-3"></a>QIcon::QIcon ( const QIcon & <i>other</i> )</h3>

103

<p>Constructs a copy of <i>other</i>. This is very fast.</p>

104

<h3 class="fn"><a name="QIcon-4"></a>QIcon::QIcon ( const <a href="qstring.html">QString</a> & <i>fileName</i> )</h3>

105

<p>Constructs an icon from the file with the given <i>fileName</i>. The file will be loaded on demand. If the file does not exist or is of an unknown format, the icon becomes a null icon.</p>

106

<p>If <i>fileName</i> contains a relative path (e.g. the filename only) the relevant file must be found relative to the runtime working directory.</p>

107

<p>The file name can be either refer to an actual file on disk or to one of the application's embedded resources. See the <a href="resources.html">Resource System</a> overview for details on how to embed images and other resource files in the application's executable.</p>

108

<h3 class="fn"><a name="QIcon-5"></a>QIcon::QIcon ( <a href="qiconengine.html">QIconEngine</a> * <i>engine</i> )</h3>

109

<p>Creates an icon with a specific icon <i>engine</i>. The icon takes ownership of the engine.</p>

110

<h3 class="fn"><a name="dtor.QIcon"></a>QIcon::~QIcon ()</h3>

111

<p>Destroys the icon.</p>

112

<h3 class="fn"><a name="actualSize"></a><a href="qsize.html">QSize</a> QIcon::actualSize ( const <a href="qsize.html">QSize</a> & <i>size</i>, <a href="qicon.html#Mode-enum">Mode</a> <i>mode</i> = Normal, <a href="qicon.html#State-enum">State</a> <i>state</i> = Off ) const</h3>

113

<p>Returns the actual size of the icon for the requested <i>size</i>, <i>mode</i>, and <i>state</i>. The result might be smaller than requested, but never larger.</p>

114

<p>See also <a href="qicon.html#pixmap">pixmap</a>() and <a href="qicon.html#paint">paint</a>().</p>

115

<h3 class="fn"><a name="addFile"></a>void QIcon::addFile ( const <a href="qstring.html">QString</a> & <i>fileName</i>, const <a href="qsize.html">QSize</a> & <i>size</i> = QSize(), <a href="qicon.html#Mode-enum">Mode</a> <i>mode</i> = Normal, <a href="qicon.html#State-enum">State</a> <i>state</i> = Off )</h3>

116

<p>Adds a pixmap from the file with the given <i>fileName</i> to the icon, as a specialization for <i>size</i>, <i>mode</i> and <i>state</i>. The file will be loaded on demand. Note: custom icon engines are free to ignore additionally added pixmaps.</p>

117

<p>If <i>fileName</i> contains a relative path (e.g. the filename only) the relevant file must be found relative to the runtime working directory.</p>

118

119

<p>See also <a href="qicon.html#addPixmap">addPixmap</a>().</p>

120

<h3 class="fn"><a name="addPixmap"></a>void QIcon::addPixmap ( const <a href="qpixmap.html">QPixmap</a> & <i>pixmap</i>, <a href="qicon.html#Mode-enum">Mode</a> <i>mode</i> = Normal, <a href="qicon.html#State-enum">State</a> <i>state</i> = Off )</h3>

121

<p>Adds <i>pixmap</i> to the icon, as a specialization for <i>mode</i> and <i>state</i>.</p>

122

<p>Custom icon engines are free to ignore additionally added pixmaps.</p>

123

<p>See also <a href="qicon.html#addFile">addFile</a>().</p>

124

<h3 class="fn"><a name="isNull"></a>bool QIcon::isNull () const</h3>

125

<p>Returns true if the icon is empty; otherwise returns false.</p>

126

<h3 class="fn"><a name="paint"></a>void QIcon::paint ( <a href="qpainter.html">QPainter</a> * <i>painter</i>, const <a href="qrect.html">QRect</a> & <i>rect</i>, <a href="qt.html#AlignmentFlag-enum">Qt::Alignment</a> <i>alignment</i> = Qt::AlignCenter, <a href="qicon.html#Mode-enum">Mode</a> <i>mode</i> = Normal, <a href="qicon.html#State-enum">State</a> <i>state</i> = Off ) const</h3>

127

<p>Uses the <i>painter</i> to paint the icon with specified <i>alignment</i>, required <i>mode</i>, and <i>state</i> into the rectangle <i>rect</i>.</p>

128

<p>See also <a href="qicon.html#actualSize">actualSize</a>() and <a href="qicon.html#pixmap">pixmap</a>().</p>

129

<h3 class="fn"><a name="paint-2"></a>void QIcon::paint ( <a href="qpainter.html">QPainter</a> * <i>painter</i>, int <i>x</i>, int <i>y</i>, int <i>w</i>, int <i>h</i>, <a href="qt.html#AlignmentFlag-enum">Qt::Alignment</a> <i>alignment</i> = Qt::AlignCenter, <a href="qicon.html#Mode-enum">Mode</a> <i>mode</i> = Normal, <a href="qicon.html#State-enum">State</a> <i>state</i> = Off ) const</h3>

130

<p>This is an overloaded member function, provided for convenience. It behaves essentially like the above function.</p>

131

<p>Paints the icon into the rectangle <a href="qrect.html">QRect</a>(<i>x</i>, <i>y</i>, <i>w</i>, <i>h</i>).</p>

132

<h3 class="fn"><a name="pixmap"></a><a href="qpixmap.html">QPixmap</a> QIcon::pixmap ( const <a href="qsize.html">QSize</a> & <i>size</i>, <a href="qicon.html#Mode-enum">Mode</a> <i>mode</i> = Normal, <a href="qicon.html#State-enum">State</a> <i>state</i> = Off ) const</h3>

133

<p>Returns a pixmap with the requested <i>size</i>, <i>mode</i>, and <i>state</i>, generating one if necessary. The pixmap might be smaller than requested, but never larger.</p>

134

<p>See also <a href="qicon.html#actualSize">actualSize</a>() and <a href="qicon.html#paint">paint</a>().</p>

135

<h3 class="fn"><a name="pixmap-5"></a><a href="qpixmap.html">QPixmap</a> QIcon::pixmap ( int <i>w</i>, int <i>h</i>, <a href="qicon.html#Mode-enum">Mode</a> <i>mode</i> = Normal, <a href="qicon.html#State-enum">State</a> <i>state</i> = Off ) const</h3>

136

<p>This is an overloaded member function, provided for convenience. It behaves essentially like the above function.</p>

137

<p>Returns a pixmap of size <a href="qsize.html">QSize</a>(<i>w</i>, <i>h</i>).</p>

138

<h3 class="fn"><a name="pixmap-6"></a><a href="qpixmap.html">QPixmap</a> QIcon::pixmap ( int <i>extent</i>, <a href="qicon.html#Mode-enum">Mode</a> <i>mode</i> = Normal, <a href="qicon.html#State-enum">State</a> <i>state</i> = Off ) const</h3>

139

<p>This is an overloaded member function, provided for convenience. It behaves essentially like the above function.</p>

140

<p>Returns a pixmap of size <a href="qsize.html">QSize</a>(<i>extent</i>, <i>extent</i>).</p>

141

<h3 class="fn"><a name="serialNumber"></a>int QIcon::serialNumber () const</h3>

142

<p>Returns a number that uniquely identifies the contents of this <a href="qicon.html">QIcon</a> object. This means that multiple <a href="qicon.html">QIcon</a> objects can have the same serial number as long as they refer to the same contents.</p>

143

<p>A null icon always has a serial number of 0.</p>

144

<p>See also <a href="qpixmap.html#serialNumber">QPixmap::serialNumber</a>().</p>

145

<h3 class="fn"><a name="operator-QVariant"></a>QIcon::operator QVariant () const</h3>

146

<p>Returns the icon as a <a href="qvariant.html">QVariant</a>.</p>

147

<h3 class="fn"><a name="operator-eq"></a>QIcon & QIcon::operator= ( const QIcon & <i>other</i> )</h3>

148

<p>Assigns the <i>other</i> icon to this icon and returns a reference to this icon.</p>

149

150

151

152

<td width="40%" align="center"><a href="trademarks.html">Trademarks</a></td>

153

154

</tr></table></div></address></body>

155

</html>

Older »