Classes - Annotated - Tree - Functions - Home - Structure

QIconSet Class Reference

The QIconSet class provides a set of differently styled and sized icons. More...

#include <qiconset.h>

List of all member functions.

Public Members

Static Public Members


Detailed Description

The QIconSet class provides a set of differently styled and sized icons.

Once a QIconSet is fed some pixmaps it can generate smaller, larger, active, and disabled pixmaps. Such pixmaps are used by QToolButton, QHeader, QPopupMenu, etc. to show an icon representing a piece of functionality.

The simplest usage of QIconSet is to create one from a QPixmap and then use it, allowing Qt to work out all the required icon sizes. For example:

  QToolButton *tb = new QToolButton( QIconSet( QPixmap("open.xpm") ), ... );
  

Using whichever pixmaps you specify as a base, QIconSet provides a set of six icons, each with a Size and a Mode:

An additional set of six icons can be provided for widgets that have an "On" or "Off" state, like checkable menuitems or toggleable toolbuttons. An QIconSet cannot only have pixmaps for the "On" state, and those pixmaps have to be set explicitely using setPixmap().

You can set any of the icons using setPixmap(). When you retrieve one using pixmap(Size,Mode,State), QIconSet will compute it from the closest other icon and cache it for later.

The Disabled appearance is computed using a "shadow" algorithm that produces results very similar to those used in Microsoft Windows 95.

The Active appearance is identical to the Normal appearance unless you use setPixmap() to set it to something special.

When scaling icons, QIconSet uses smooth scaling, which can partially blend the color component of pixmaps. If the results look poor, the best solution is to supply both large and small sizes of pixmaps.

You can use the static function setIconSize() to set the preferred size of the generated large/small icons. The default small size is 22x22 (compatible with the 2.x system), while the default large size is 32x32. Please note that these sizes only affect generated icons.

QIconSet provides a function, isGenerated(), that indicates whether an icon was set by the application programmer or computed by QIconSet itself.

Making Classes that use QIconSet

If you write your own widgets that have an option to set a small pixmap, you should consider (instead, or additionally) allowing a QIconSet to be set for that pixmap. The Qt class QToolButton is an example of such a widget.

Provide a method to set a QIconSet, and when you draw the icon, choose whichever icon is appropriate for the current state of your widget. For example:

  void YourWidget::drawIcon( QPainter* p, QPoint pos )
  {
      p->drawPixmap( pos, icons->pixmap(QIconSet::Small, isEnabled()) );
  }
  

You might also make use of the Active mode, perhaps making your widget Active when the mouse in inside the widget (see QWidget::enterEvent), while the mouse is pressed pending the release that will activate the function, or when it is the currently selected item. If you widget can be toggled, the On mode might be used to draw a different icon.

See also QPixmap, QLabel, QToolButton, QPopupMenu, QIconViewItem::setViewMode(), QMainWindow::usesBigPixmaps, GUI Design Handbook: Iconic Label and Microsoft Icon Gallery.


Member Type Documentation

QIconSet::Mode

This enum type describes the mode for which a pixmap is intended to be provided. The currently defined modes are:

QIconSet::Size

This enum type describes the size for which a pixmap is intended to be provided. The currently defined sizes are:

If a Small pixmap is not set by QIconSet::setPixmap(), the Large pixmap may be automatically scaled down to the size of a small generated icon. Conversely, a Small pixmap will be automatically scaled up to create a Large pixmap if needed. The preferred sizes for large/small generated icons can be set using setIconSize().

See also setIconSize(), iconSize(), setPixmap(), pixmap(), QIconViewItem::setViewMode() and QMainWindow::usesBigPixmaps.

QIconSet::State

This enum describes the state for which a pixmap is intended to be provided. The state can be:

See also setPixmap() and pixmap().


Member Function Documentation

QIconSet::QIconSet ()

Constructs a null icon set. Use setPixmap(), reset(), or operator=() to set some pixmaps.

See also reset().

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

Constructs an icon set for which the Normal pixmap is pixmap, which is assumed to be the given size.

The default for size is Automatic, which means that QIconSet will determine whether the pixmap is Small or Large from its pixel size. Pixmaps less than the width of a small generated icon are considered to be Small. You can use setIconSize() to set the preferred size of a generated icon.

See also setIconSize() and reset().

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

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

QIconSet::QIconSet ( const QIconSet & other )

Constructs a copy of other. This is very fast.

QIconSet::~QIconSet () [virtual]

Destroys the icon set and frees any allocated resources.

void QIconSet::detach ()

Detaches this icon set from others with which it may share data.

You will never need to call this function; other QIconSet functions call it as necessary.

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

Returns the size of the large/small generated icons.

See also setIconSize().

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

Returns TRUE if the variant with size, mode and state have been generated, and FALSE if they have not.

bool QIconSet::isNull () const

Returns TRUE if the icon set is empty.

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

Assigns other to this icon set and returns a reference to this icon set.

This is very fast.

See also detach().

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

Returns a pixmap with size, mode and state, generating one if needed. Generated pixmaps are cached.

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

Returns a pixmap with size, state and Mode either Normal or Disabled, depending on the value of enabled.

QPixmap QIconSet::pixmap () const

Returns the pixmap originally provided to the constructor or to reset(). This is the Normal pixmap of unspecified Size.

See also reset().

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

Sets this icon set to provide pm for the Normal pixmap, assuming it to be of size.

This is equivalent to assigning QIconSet(pm, size) to this icon set.

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

Set the preferred size for the large/small generated icons. Note that this will not cause cached icon sets to be regenerated, so you should set the preferred icon sizes before creating any QIconSets.

See also iconSize().

void QIconSet::setPixmap ( const QPixmap & pm, Size size, Mode mode = Normal, State state = Off ) [virtual]

Sets this icon set to provide pm for a size, mode and state. It may also use pm for deriving some other varieties if those are not set.

The size can be one of Automatic, Large or Small. If Automatic is used, QIconSet will determine if the pixmap is Small or Large from its pixel size. Pixmaps less than the width of a small generated icon are considered to be Small. You can use setIconSize() to set the preferred size of a generated icon.

See also reset().

void QIconSet::setPixmap ( const QString & fileName, Size size, Mode mode = Normal, State state = Off ) [virtual]

Sets this icon set to load fileName as a pixmap and provide it for size, mode and state. It may also use the pixmap for deriving some other varieties if those are not set.

The size can be one of Automatic, Large or Small. If Automatic is used, QIconSet will determine if the pixmap is Small or Large from its pixel size. Pixmaps less than the width of a small generated icon are considered to be Small. You can use setIconSize() to set the preferred size of a generated icon.


Search the documentation, FAQ, qt-interest archive and more (uses www.trolltech.com):


This file is part of the Qt toolkit, copyright © 1995-2001 Trolltech, all rights reserved.


Copyright © 2001 TrolltechTrademarks
Qt version 3.0.0-beta1-beta1