qiconset.3qt

Trolltech公司发布的基于C++图形开发环境

'\" t
.TH QIconSet 3qt "24 January 2005" "Trolltech AS" \" -*- nroff -*-
.\" Copyright 1992-2001 Trolltech AS.  All rights reserved.  See the
.\" license file included in the distribution for a complete license
.\" statement.
.\"
.ad l
.nh
.SH NAME
QIconSet \- Set of differently styled and sized icons
.br
.PP
\fC#include <qiconset.h>\fR
.PP
.SS "Public Members"
.in +1c
.ti -1c
.BI "enum \fBSize\fR { Automatic, Small, Large }"
.br
.ti -1c
.BI "enum \fBMode\fR { Normal, Disabled, Active }"
.br
.ti -1c
.BI "\fBQIconSet\fR () "
.br
.ti -1c
.BI "\fBQIconSet\fR ( const QPixmap &, Size = Automatic ) "
.br
.ti -1c
.BI "\fBQIconSet\fR ( const QPixmap & " "smallPix" ", const QPixmap & largePix ) "
.br
.ti -1c
.BI "\fBQIconSet\fR ( const QIconSet & ) "
.br
.ti -1c
.BI "virtual \fB~QIconSet\fR () "
.br
.ti -1c
.BI "void \fBreset\fR ( const QPixmap &, Size ) "
.br
.ti -1c
.BI "virtual void \fBsetPixmap\fR ( const QPixmap &, Size, Mode = Normal ) "
.br
.ti -1c
.BI "virtual void \fBsetPixmap\fR ( const QString &, Size, Mode = Normal ) "
.br
.ti -1c
.BI "QPixmap \fBpixmap\fR ( Size, Mode ) const"
.br
.ti -1c
.BI "QPixmap \fBpixmap\fR ( Size " "s" ", bool enabled ) const"
.br
.ti -1c
.BI "QPixmap \fBpixmap\fR () const"
.br
.ti -1c
.BI "bool \fBisGenerated\fR ( Size, Mode ) const"
.br
.ti -1c
.BI "bool \fBisNull\fR () const"
.br
.ti -1c
.BI "void \fBdetach\fR () "
.br
.ti -1c
.BI "QIconSet& \fBoperator=\fR ( const QIconSet & ) "
.br
.in -1c
.SH DESCRIPTION
The QIconSet class provides a set of differently styled and sized icons.
.PP
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.
.PP
The simplest usage of QIconSet is to create one from a QPixmap then use it, allowing Qt to work out all the required icon sizes. For example:
.PP
.nf
.br
  QToolButton *tb = new QToolButton( QIconSet( QPixmap("open.xpm") ), ... );
.fi
.PP
Using whichever pixmaps you specify as a base, QIconSet provides a set of six icons each with a Size and a Mode:
.TP
\fISmall Normal\fR - can only be calculated from Large Normal.
.TP
\fISmall Disabled\fR - calculated from Large Disabled or Small Normal.
.TP
\fISmall Active\fR - same as Small Normal unless you set it.
.TP
\fILarge Normal\fR - can only be calculated from Small Normal.
.TP
\fILarge Disabled\fR - calculated from Small Disabled or Large Normal.
.TP
\fILarge Active\fR - same as Large Normal unless you set it.
.PP
You can set any of the icons using setPixmap() and when you retrieve one using pixmap(Size,Mode), QIconSet will compute it from the closest other icon and cache it for later.
.PP
The \fCDisabled\fR appearance is computed using a "shadow" algorithm which produces results very similar to that used in Microsoft Windows 95.
.PP
The \fCActive\fR appearance is identical to the \fCNormal\fR appearance unless you use setPixmap() to set it to something special.
.PP
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 pixmap.
.PP
QIconSet provides a function, isGenerated(), that indicates whether an icon was set by the application programmer or computed by QIconSet itself.
.SH "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.
.PP
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:
.PP
.nf
.br
  void YourWidget::drawIcon( QPainter* p, QPoint pos )
.br
  {
.br
      p->drawPixmap( pos, icons->pixmap(isEnabled(), QIconSet::Small) );
.br
  }
.fi
.PP
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.
.PP
See also QPixmap, QLabel, QToolButton, QPopupMenu, QIconViewItem::setViewMode(), QMainWindow::setUsesBigPixmaps() and GUI Design Handbook: Iconic Label
.SS "Member Type Documentation"
.SH "QIconSet::Mode"
This enum type describes the mode for which a pixmap is intended to be provided. The currently defined modes are:
.TP
\fCNormal\fR - the pixmap to be displayed when the user is not interacting with the icon, but when the functionality represented by the icon is available.
.TP
\fCDisabled\fR - the pixmap to be displayed when the functionality represented by the icon is not available.
.TP
\fCActive\fR - the pixmap to be displayed when the functionality represented by the icon is available and the user is interacting with the icon, such as by pointing at it or by invoking it.
.SH "QIconSet::Size"
This enum type describes the size for which a pixmap is intended to be provided. The currently defined sizes are:
.TP
\fCAutomatic\fR - the size of the pixmap is determined from its pixel size. This is a useful default.
.TP
\fCSmall\fR - the pixmap is the smaller of two.
.TP
\fCLarge\fR - the pixmap is the larger of two
.PP
If a Small pixmap is not set by QIconSet::setPixmap(), then the Large pixmap may be automatically scaled to two-thirds of its size to generate the Small pixmap. Conversely, a Small pixmap will be automatically scaled up by 50% to create a Large pixmap if needed.
.PP
See also setPixmap(), pixmap(), QIconViewItem::setViewMode() and QMainWindow::setUsesBigPixmaps().
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QIconSet::QIconSet ()"
Constructs an icon set of null pixmaps. Use setPixmap(), reset(), or operator=() to set some pixmaps.
.PP
See also reset().
.SH "QIconSet::QIconSet ( const QPixmap & pixmap, Size size = Automatic )"
Constructs an icon set for which the Normal pixmap is \fIpixmap,\fR which is assumed to be the given \fIsize.\fR
.PP
The default for \fIsize\fR is \fCAutomatic,\fR which means that QIconSet will determine if the pixmap is Small or Large from its pixel size. Pixmaps less than 23 pixels wide are considered to be Small.
.PP
See also reset().
.SH "QIconSet::QIconSet ( const QPixmap & smallPix, const QPixmap & largePix )"
Creates an iconset which uses the pixmap \fIsmallPix\fR for for displaying small a small icon, and \fIlargePix\fR for displaying a large one.
.SH "QIconSet::QIconSet ( const QIconSet & other )"
Constructs a copy of \fIother.\fR This is very fast.
.SH "QIconSet::~QIconSet () \fC[virtual]\fR"
Destructs the icon set and frees any allocated resources.
.SH "void QIconSet::detach ()"
Detaches this icon set from others with which it may share data.
.PP
You will never need to call this function; other QIconSet functions call it as necessary.
.SH "bool QIconSet::isGenerated ( Size s, Mode m ) const"
Returns TRUE if the variant with size \fIs\fR and mode \fIm\fR was automatically generated, and FALSE if it was not. This mainly useful for development purposes.
.SH "bool QIconSet::isNull () const"
Returns TRUE if the icon set is empty. Currently, a QIconSet is never empty (although it may contain null pixmaps).
.SH "QIconSet & QIconSet::operator= ( const QIconSet & other )"
Assigns \fIother\fR to this icon set and returns a reference to this icon set.
.PP
This is very fast.
.PP
See also detach().
.SH "QPixmap QIconSet::pixmap () const"
Returns the pixmap originally provided to the constructor or to reset(). This is the Normal pixmap of unspecified Size.
.PP
See also reset().
.SH "QPixmap QIconSet::pixmap ( Size s, Mode m ) const"
Returns a pixmap with size \fIs\fR and mode \fIm,\fR generating one if needed. Generated pixmaps are cached.
.SH "QPixmap QIconSet::pixmap ( Size s, bool enabled ) const"
Returns a pixmap with size \fIs,\fR and Mode either Normal or Disabled, depending on the value of \fIenabled.\fR
.SH "void QIconSet::reset ( const QPixmap & pm, Size s )"
Sets this icon set to provide \fIpm\fR for the Normal pixmap, assuming it to be of size \fIs.\fR
.PP
This is equivalent to assigning QIconSet(pm,s) to this icon set.
.SH "void QIconSet::setPixmap ( const QPixmap & pm, Size size, Mode mode = Normal )"
Sets this icon set to provide \fIpm\fR for a \fIsize\fR and \fImode.\fR It may also use \fIpm\fR for deriving some other varieties if those are not set.
.PP
The \fIsize\fR 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 23 pixels wide are considered to be Small.
.PP
See also reset().
.SH "void QIconSet::setPixmap ( const QString & fileName, Size s, Mode m = Normal )"
Sets this icon set to load \fIfileName\fR as a pixmap and provide it for size \fIs\fR and mode \fIm.\fR It may also use the pixmap for deriving some other varieties if those are not set.
.PP
The \fIsize\fR 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 23 pixels wide are considered to be Small.
.SH "SEE ALSO"
.BR http://doc.trolltech.com/qiconset.html
.BR http://www.trolltech.com/faq/tech.html
.SH COPYRIGHT
Copyright 1992-2001 Trolltech AS, http://www.trolltech.com.  See the
license file included in the distribution for a complete license
statement.
.SH AUTHOR
Generated automatically from the source code.
.SH BUGS
If you find a bug in Qt, please report it as described in
.BR http://doc.trolltech.com/bughowto.html .
Good bug reports make our job much simpler. Thank you.
.P
In case of content or formattting problems with this manual page, please
report them to
.BR [e-mail] .
Please include the name of the manual page (qiconset.3qt) and the Qt
version (2.3.10).