QIcon: Clean up documentation
Structure the overview documentation a bit more around the different ways to create a QIcon (from resources or theme). Replace the use of QIcon::pixmap with a call to QIcon::paint in the example widget, and tighten the High-DPI documentation a bit. This does not add any mentioning of the upcoming "native icon library" support. Change-Id: I9cc7eab1fb5d134e5119660b534c2efdb0b03730 Reviewed-by: Tor Arne Vestbø <tor.arne.vestbo@qt.io>bb10
Volker Hilsheimer
parent
7be14ea88b
commit
dcfd68c827
|
|
@ -8,7 +8,7 @@ namespace src_gui_image_qicon {
|
|||
|
||||
struct MyWidget : public QWidget
|
||||
{
|
||||
void drawIcon(QPainter *painter, QPoint pos);
|
||||
void drawIcon(QPainter *painter, const QRect &rect);
|
||||
bool isChecked() { return true; }
|
||||
QIcon icon;
|
||||
};
|
||||
|
|
@ -17,9 +17,13 @@ void wrapper0() {
|
|||
|
||||
//! [0]
|
||||
QToolButton *button = new QToolButton;
|
||||
button->setIcon(QIcon("open.xpm"));
|
||||
button->setIcon(QIcon("open.png"));
|
||||
//! [0]
|
||||
|
||||
//! [addFile]
|
||||
QIcon openIcon("open.png");
|
||||
openIcon.addFile("open-disabled.png", QIcon::Disabled);
|
||||
//! [addFile]
|
||||
|
||||
//! [1]
|
||||
button->setIcon(QIcon());
|
||||
|
|
@ -29,14 +33,12 @@ button->setIcon(QIcon());
|
|||
|
||||
|
||||
//! [2]
|
||||
void MyWidget::drawIcon(QPainter *painter, QPoint pos)
|
||||
void MyWidget::drawIcon(QPainter *painter, const QRect &rect)
|
||||
{
|
||||
QPixmap pixmap = icon.pixmap(QSize(22, 22),
|
||||
isEnabled() ? QIcon::Normal
|
||||
: QIcon::Disabled,
|
||||
isChecked() ? QIcon::On
|
||||
: QIcon::Off);
|
||||
painter->drawPixmap(pos, pixmap);
|
||||
icon.paint(painter, rect, Qt::AlignCenter, isEnabled() ? QIcon::Normal
|
||||
: QIcon::Disabled,
|
||||
isChecked() ? QIcon::On
|
||||
: QIcon::Off);
|
||||
}
|
||||
//! [2]
|
||||
|
||||
|
|
|
|||
|
|
@ -546,15 +546,26 @@ QFactoryLoader *qt_iconEngineFactoryLoader()
|
|||
|
||||
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.
|
||||
UI components to show an icon representing a particular action.
|
||||
|
||||
The simplest use of QIcon is to create one from a QPixmap file or
|
||||
resource, and then use it, allowing Qt to work out all the required
|
||||
icon styles and sizes. For example:
|
||||
\section1 Creating an icon from image files
|
||||
|
||||
The simplest way to construct a QIcon is to create one from one or
|
||||
several image files or resources. For example:
|
||||
|
||||
\snippet code/src_gui_image_qicon.cpp 0
|
||||
|
||||
To undo a QIcon, simply set a null icon in its place:
|
||||
QIcon can store several images for different states, and Qt will
|
||||
select the image that is the closest match for the action's current
|
||||
state.
|
||||
|
||||
\snippet code/src_gui_image_qicon.cpp addFile
|
||||
|
||||
Qt will generate the required icon styles and sizes when needed,
|
||||
e.g. the pixmap for the QIcon::Disabled state might be generated by
|
||||
graying out one of the provided pixmaps.
|
||||
|
||||
To clear the icon, simply set a null icon in its place:
|
||||
|
||||
\snippet code/src_gui_image_qicon.cpp 1
|
||||
|
||||
|
|
@ -562,19 +573,23 @@ QFactoryLoader *qt_iconEngineFactoryLoader()
|
|||
QImageWriter::supportedImageFormats() functions to retrieve a
|
||||
complete list of the supported file formats.
|
||||
|
||||
When you retrieve a pixmap using pixmap(QSize, Mode, State), and no
|
||||
pixmap for this given size, mode and state has been added with
|
||||
addFile() or addPixmap(), then QIcon will generate one on the
|
||||
fly. This pixmap generation happens in a QIconEngine. 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 QIconEnginePlugin it is possible to register different
|
||||
icon engines for different file suffixes, making it possible for
|
||||
third parties to provide additional icon engines to those included
|
||||
with Qt.
|
||||
\section1 Creating an icon from a theme or icon library
|
||||
|
||||
\note Since Qt 4.2, an icon engine that supports SVG is included.
|
||||
The most convenient way to construct an icon is by using the
|
||||
\l{QIcon::}{fromTheme()} factory function. Qt implements access to
|
||||
the native icon library on platforms that support the
|
||||
\l {Freedesktop Icon Theme Specification}.
|
||||
|
||||
Applications can use the same theming specification to provide
|
||||
their own icon library. See below for an example theme description
|
||||
and the corresponding directory structure for the image files.
|
||||
|
||||
In addition, it is possible to provide custom \l {QIconEngine}
|
||||
{icon engines}. This allows applications to customize every aspect
|
||||
of generated icons. With QIconEnginePlugin it is possible to register
|
||||
different icon engines for different file suffixes, making it possible
|
||||
for third parties to provide additional icon engines to those included
|
||||
with Qt.
|
||||
|
||||
\section1 Making Classes that Use QIcon
|
||||
|
||||
|
|
@ -582,11 +597,19 @@ QFactoryLoader *qt_iconEngineFactoryLoader()
|
|||
pixmap, consider allowing a QIcon to be set for that pixmap. The
|
||||
Qt class QToolButton is an example of such a widget.
|
||||
|
||||
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:
|
||||
Provide a method to set a QIcon, and paint the QIcon with
|
||||
\l{QIcon::}{paint}, choosing the appropriate parameters based
|
||||
on the current state of your widget. For example:
|
||||
|
||||
\snippet code/src_gui_image_qicon.cpp 2
|
||||
|
||||
When you retrieve a pixmap using pixmap(QSize, Mode, State), and no
|
||||
pixmap for this given size, mode and state has been added with
|
||||
addFile() or addPixmap(), then QIcon will generate one on the
|
||||
fly. This pixmap generation happens in a QIconEngine. The default
|
||||
engine scales pixmaps down if required, but never up, and it uses
|
||||
the current style to calculate a disabled appearance.
|
||||
|
||||
You might also make use of the \c Active mode, perhaps making your
|
||||
widget \c Active when the mouse is over the widget (see \l
|
||||
QWidget::enterEvent()), while the mouse is pressed pending the
|
||||
|
|
@ -600,17 +623,15 @@ QFactoryLoader *qt_iconEngineFactoryLoader()
|
|||
|
||||
\section1 High DPI Icons
|
||||
|
||||
There are two ways that QIcon supports \l {High DPI}{high DPI}
|
||||
icons: via \l addFile() and \l fromTheme().
|
||||
When providing your own image files via \l addFile(), then QIcon will
|
||||
use Qt's \l {High Resolution Versions of Images}{"@nx" high DPI syntax}.
|
||||
This is useful if you have your own custom directory structure and do not
|
||||
use follow \l {Freedesktop Icon Theme Specification}.
|
||||
|
||||
\l addFile() is useful if you have your own custom directory structure and do
|
||||
not need to use the \l {Freedesktop Icon Theme Specification}. Icons
|
||||
created via this approach use Qt's \l {High Resolution Versions of Images}
|
||||
{"@nx" high DPI syntax}.
|
||||
|
||||
Using \l fromTheme() is necessary if you plan on following the Icon Theme
|
||||
Specification. To make QIcon use the high DPI version of an image, add an
|
||||
additional entry to the appropriate \c index.theme file:
|
||||
When providing an application theme, then you need to follow the Icon Theme
|
||||
Specification to specify which files to use for different resolutions.
|
||||
To make QIcon use the high DPI version of an image, add an additional entry
|
||||
to the appropriate \c index.theme file:
|
||||
|
||||
\badcode
|
||||
[Icon Theme]
|
||||
|
|
|
|||
Loading…
Reference in New Issue