1QIconSet(3qt)                                                    QIconSet(3qt)
2
3
4

NAME

6       QIconSet - Set of icons with different styles and sizes
7

SYNOPSIS

9       #include <qiconset.h>
10
11   Public Members
12       enum Size { Automatic, Small, Large }
13       enum Mode { Normal, Disabled, Active }
14       enum State { On, Off }
15       QIconSet ()
16       QIconSet ( const QPixmap & pixmap, Size size = Automatic )
17       QIconSet ( const QPixmap & smallPix, const QPixmap & largePix )
18       QIconSet ( const QIconSet & other )
19       virtual ~QIconSet ()
20       void reset ( const QPixmap & pixmap, Size size )
21       virtual void setPixmap ( const QPixmap & pixmap, Size size, Mode mode =
22           Normal, State state = Off )
23       virtual void setPixmap ( const QString & fileName, Size size, Mode mode
24           = Normal, State state = Off )
25       QPixmap pixmap ( Size size, Mode mode, State state = Off ) const
26       QPixmap pixmap ( Size size, bool enabled, State state = Off ) const
27           (obsolete)
28       QPixmap pixmap () const
29       bool isGenerated ( Size size, Mode mode, State state = Off ) const
30       void clearGenerated ()
31       void installIconFactory ( QIconFactory * factory )
32       bool isNull () const
33       void detach ()
34       QIconSet & operator= ( const QIconSet & other )
35
36   Static Public Members
37       void setIconSize ( Size which, const QSize & size )
38       const QSize & iconSize ( Size which )
39

DESCRIPTION

41       The QIconSet class provides a set of icons with different styles and
42       sizes.
43
44       A QIconSet can generate smaller, larger, active, and disabled pixmaps
45       from the set of icons it is given. Such pixmaps are used by
46       QToolButton, QHeader, QPopupMenu, etc. to show an icon representing a
47       particular action.
48
49       The simplest use of QIconSet is to create one from a QPixmap and then
50       use it, allowing Qt to work out all the required icon styles and sizes.
51       For example:
52
53           QToolButton *but = new QToolButton( QIconSet( QPixmap("open.xpm") ), ... );
54
55       Using whichever pixmaps you specify as a base, QIconSet provides a set
56       of six icons, each with a Size and a Mode: Small Normal, Small
57       Disabled, Small Active, Large Normal, Large Disabled, and Large Active.
58
59       An additional set of six icons can be provided for widgets that have an
60       "On" or "Off" state, like checkable menu items or toggleable
61       toolbuttons. If you provide pixmaps for the "On" state, but not for the
62       "Off" state, the QIconSet will provide the "Off" pixmaps. You may
63       specify icons for both states in you wish.
64
65       You can set any of the icons using setPixmap().
66
67       When you retrieve a pixmap using pixmap(Size, Mode, State), QIconSet
68       will return the icon that has been set or previously generated for that
69       size, mode and state combination. If none is available, QIconSet will
70       ask the icon factory. If the icon factory cannot provide any (the
71       default), QIconSet generates a pixmap based on the pixmaps it has been
72       given and returns it.
73
74       The Disabled appearance is computed using an algorithm that produces
75       results very similar to those used in Microsoft Windows 95. The Active
76       appearance is identical to the Normal appearance unless you use
77       setPixmap() to set it to something special.
78
79       When scaling icons, QIconSet uses smooth scaling, which can partially
80       blend the color component of pixmaps. If the results look poor, the
81       best solution is to supply pixmaps in both large and small sizes.
82
83       You can use the static function setIconSize() to set the preferred size
84       of the generated large/small icons. The default small size is 22 x 22,
85       while the default large size is 32 x 32. These sizes only affect
86       generated icons.
87
88       The isGenerated() function returns TRUE if an icon was generated by
89       QIconSet or by a factory; clearGenerated() clears all cached pixmaps.
90

Making Classes that Use QIconSet

92       If you write your own widgets that have an option to set a small
93       pixmap, consider allowing a QIconSet to be set for that pixmap. The Qt
94       class QToolButton is an example of such a widget.
95
96       Provide a method to set a QIconSet, and when you draw the icon, choose
97       whichever icon is appropriate for the current state of your widget. For
98       example:
99
100           void MyWidget::drawIcon( QPainter* p, QPoint pos )
101           {
102               p->drawPixmap( pos, icons->pixmap(
103                                       QIconSet::Small,
104                                       isEnabled() ? QIconSet::Normal :
105                                                     QIconSet::Disabled,
106                                       isEnabled() ? QIconSet::On :
107                                                     QIconSet::Off));
108           }
109
110       You might also make use of the Active mode, perhaps making your widget
111       Active when the mouse is over the widget (see QWidget::enterEvent()),
112       while the mouse is pressed pending the release that will activate the
113       function, or when it is the currently selected item. If the widget can
114       be toggled, the "On" mode might be used to draw a different icon.
115
116       <center>
117                                   [Image Omitted]
118
119       </center>
120
121       See also QIconFactory, QPixmap, QMainWindow::usesBigPixmaps, GUI Design
122       Handbook: Iconic Label, Graphics Classes, Image Processing Classes, and
123       Implicitly and Explicitly Shared Classes.
124
125   Member Type Documentation

QIconSet::Mode

127       This enum type describes the mode for which a pixmap is intended to be
128       used. The currently defined modes are:
129
130       QIconSet::Normal - Display the pixmap when the user is not interacting
131       with the icon, but the functionality represented by the icon is
132       available.
133
134       QIconSet::Disabled - Display the pixmap when the functionality
135       represented by the icon is not available.
136
137       QIconSet::Active - Display the pixmap when the functionality
138       represented by the icon is available and the user is interacting with
139       the icon, for example, moving the mouse over it or clicking it.
140

QIconSet::Size

142       This enum type describes the size at which a pixmap is intended to be
143       used. The currently defined sizes are:
144
145       QIconSet::Automatic - The size of the pixmap is determined from its
146       pixel size. This is a useful default.
147
148       QIconSet::Small - The pixmap is the smaller of two.
149
150       QIconSet::Large - The pixmap is the larger of two.
151
152       If a Small pixmap is not set by QIconSet::setPixmap(), the Large pixmap
153       will be automatically scaled down to the size of a small pixmap to
154       generate the Small pixmap when required. Similarly, a Small pixmap will
155       be automatically scaled up to generate a Large pixmap. The preferred
156       sizes for large/small generated icons can be set using setIconSize().
157
158       See also setIconSize(), iconSize(), setPixmap(), pixmap(), and
159       QMainWindow::usesBigPixmaps.
160

QIconSet::State

162       This enum describes the state for which a pixmap is intended to be
163       used. The state can be:
164
165       QIconSet::Off - Display the pixmap when the widget is in an "off" state
166
167       QIconSet::On - Display the pixmap when the widget is in an "on" state
168
169       See also setPixmap() and pixmap().
170

MEMBER FUNCTION DOCUMENTATION

QIconSet::QIconSet ()

173       Constructs a null icon set.
174
175       See also setPixmap() and reset().
176

QIconSet::QIconSet ( const QPixmap & pixmap, Size size = Automatic )

178       Constructs an icon set for which the Normal pixmap is pixmap, which is
179       assumed to be of size size.
180
181       The default for size is Automatic, which means that QIconSet will
182       determine whether the pixmap is Small or Large from its pixel size.
183       Pixmaps less than the width of a small generated icon are considered to
184       be Small. You can use setIconSize() to set the preferred size of a
185       generated icon.
186
187       See also setIconSize() and reset().
188

QIconSet::QIconSet ( const QPixmap & smallPix, const QPixmap & largePix )

190       Creates an iconset which uses the pixmap smallPix for for displaying a
191       small icon, and the pixmap largePix for displaying a large icon.
192

QIconSet::QIconSet ( const QIconSet & other )

194       Constructs a copy of other. This is very fast.
195

QIconSet::~QIconSet () [virtual]

197       Destroys the icon set and frees any allocated resources.
198

void QIconSet::clearGenerated ()

200       Clears all cached pixmaps, including those obtained from an eventual
201       QIconFactory.
202

void QIconSet::detach ()

204       Detaches this icon set from others with which it may share data.
205
206       You will never need to call this function; other QIconSet functions
207       call it as necessary.
208

const QSize & QIconSet::iconSize ( Size which ) [static]

210       If which is Small, returns the preferred size of a small generated
211       icon; if which is Large, returns the preferred size of a large
212       generated icon.
213
214       See also setIconSize().
215

void QIconSet::installIconFactory ( QIconFactory * factory )

217       Installs factory as the icon factory for this iconset. The icon factory
218       is used to generates pixmaps not set by the user.
219
220       If no icon factory is installed, QIconFactory::defaultFactory() is
221       used.
222

bool QIconSet::isGenerated ( Size size, Mode mode, State state = Off ) const

224       Returns TRUE if the pixmap with size size, mode mode and state state is
225       generated from other pixmaps; otherwise returns FALSE.
226
227       A pixmap obtained from a QIconFactory is considered non-generated.
228

bool QIconSet::isNull () const

230       Returns TRUE if the icon set is empty; otherwise returns FALSE.
231

QIconSet & QIconSet::operator= ( const QIconSet & other )

233       Assigns other to this icon set and returns a reference to this icon
234       set.
235
236       See also detach().
237

QPixmap QIconSet::pixmap ( Size size, Mode mode, State state = Off ) const

239       Returns a pixmap with size size, mode mode and state state, generating
240       one if necessary. Generated pixmaps are cached.
241

QPixmap QIconSet::pixmap ( Size size, bool enabled, State state = Off ) const

243       This is an overloaded member function, provided for convenience. It
244       behaves essentially like the above function.
245
246       This function is obsolete. It is provided to keep old source working.
247       We strongly advise against using it in new code.
248
249       This is the same as pixmap(size, enabled, state).
250

QPixmap QIconSet::pixmap () const

252       This is an overloaded member function, provided for convenience. It
253       behaves essentially like the above function.
254
255       Returns the pixmap originally provided to the constructor or to
256       reset(). This is the Normal pixmap of unspecified Size.
257
258       See also reset().
259

void QIconSet::reset ( const QPixmap & pixmap, Size size )

261       Sets this icon set to use pixmap pixmap for the Normal pixmap, assuming
262       it to be of size size.
263
264       This is equivalent to assigning QIconSet(pixmap, size) to this icon
265       set.
266
267       This function does nothing if pixmap is a null pixmap.
268

void QIconSet::setIconSize ( Size which, const QSize & size ) [static]

270       Set the preferred size for all small or large icons that are generated
271       after this call. If which is Small, sets the preferred size of small
272       generated icons to size. Similarly, if which is Large, sets the
273       preferred size of large generated icons to size.
274
275       Note that cached icons will not be regenerated, so it is recommended
276       that you set the preferred icon sizes before generating any icon sets.
277       Also note that the preferred icon sizes will be ignored for icon sets
278       that have been created using both small and large pixmaps.
279
280       See also iconSize().
281

void QIconSet::setPixmap ( const QPixmap & pixmap, Size size, Mode mode =

283       Normal, State state = Off ) [virtual]
284       Sets this icon set to provide pixmap pixmap for size size, mode mode
285       and state state. The icon set may also use pixmap for generating other
286       pixmaps if they are not explicitly set.
287
288       The size can be one of Automatic, Large or Small. If Automatic is used,
289       QIconSet will determine if the pixmap is Small or Large from its pixel
290       size.
291
292       Pixmaps less than the width of a small generated icon are considered to
293       be Small. You can use setIconSize() to set the preferred size of a
294       generated icon.
295
296       This function does nothing if pixmap is a null pixmap.
297
298       See also reset().
299

void QIconSet::setPixmap ( const QString & fileName, Size size, Mode mode =

301       Normal, State state = Off ) [virtual]
302       This is an overloaded member function, provided for convenience. It
303       behaves essentially like the above function.
304
305       The pixmap is loaded from fileName when it becomes necessary.
306
307

SEE ALSO

309       http://doc.trolltech.com/qiconset.html
310       http://www.trolltech.com/faq/tech.html
311
313       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
314       license file included in the distribution for a complete license
315       statement.
316

AUTHOR

318       Generated automatically from the source code.
319

BUGS

321       If you find a bug in Qt, please report it as described in
322       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
323       help you. Thank you.
324
325       The definitive Qt documentation is provided in HTML format; it is
326       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
327       web browser. This man page is provided as a convenience for those users
328       who prefer man pages, although this format is not officially supported
329       by Trolltech.
330
331       If you find errors in this manual page, please report them to qt-
332       bugs@trolltech.com.  Please include the name of the manual page
333       (qiconset.3qt) and the Qt version (3.3.8).
334
335
336
337Trolltech AS                    2 February 2007                  QIconSet(3qt)
Impressum