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ø <[email protected]>

2 files changed, 62 insertions, 39 deletions

diff --git a/src/gui/doc/snippets/code/src_gui_image_qicon.cpp b/src/gui/doc/snippets/code/src_gui_image_qicon.cpp
index d446f16c3cd..f7875b7c7cf 100644
--- a/src/gui/doc/snippets/code/src_gui_image_qicon.cpp
+++ b/src/gui/doc/snippets/code/src_gui_image_qicon.cpp
@@ -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]
 
diff --git a/src/gui/image/qicon.cpp b/src/gui/image/qicon.cpp
index 414ff22f3fe..193b2648462 100644
--- a/src/gui/image/qicon.cpp
+++ b/src/gui/image/qicon.cpp
@@ -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
+
+  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}.
 
-  \note Since Qt 4.2, an icon engine that supports SVG is included.
+  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().
-
-  \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}.
+  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}.
 
-  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]