Initial import of statemachine branch from the old kinetic repository

1 files changed, 794 insertions, 0 deletions

diff --git a/doc/src/examples/icons.qdoc b/doc/src/examples/icons.qdoc
new file mode 100644
index 0000000..750ef2e
--- /dev/null
+++ b/doc/src/examples/icons.qdoc
@@ -0,0 +1,794 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example widgets/icons
+    \title Icons Example
+
+    The Icons example shows how QIcon can generate pixmaps reflecting
+    an icon's state, mode and size. These pixmaps are generated from
+    the set of pixmaps made available to the icon, and are used by Qt
+    widgets to show an icon representing a particular action.
+
+    \image icons-example.png Screenshot of the Icons example
+
+    Contents:
+
+    \tableofcontents
+
+    \section1 QIcon Overview
+
+    The QIcon class provides scalable icons in different modes and
+    states. An icon's state and mode are depending on the intended use
+    of the icon. Qt currently defines four modes:
+
+    \table
+    \header \o Mode \o Description
+    \row
+    \o QIcon::Normal
+    \o Display the pixmap when the user is not interacting with the
+       icon, but the functionality represented by the icon is
+       available.
+    \row
+    \o QIcon::Active
+    \o Display the pixmap when the functionality represented by the
+       icon is available and the user is interacting with the icon,
+       for example, moving the mouse over it or clicking it.
+    \row
+    \o QIcon::Disabled
+    \o Display the pixmap when the functionality represented by
+       the icon is not available.
+    \row
+    \o QIcon::Selected
+    \o Display the pixmap when the icon is selected.
+    \endtable
+
+    QIcon's states are QIcon::On and QIcon::Off, which will display
+    the pixmap when the widget is in the respective state. The most
+    common usage of QIcon's states are when displaying checkable tool
+    buttons or menu entries (see QAbstractButton::setCheckable() and
+    QAction::setCheckable()). When a tool button or menu entry is
+    checked, the QIcon's state is \l{QIcon::}{On}, otherwise it's
+    \l{QIcon::}{Off}. You can, for example, use the QIcon's states to
+    display differing pixmaps depending on whether the tool button or
+    menu entry is checked or not.
+
+    A QIcon can generate smaller, larger, active, disabled, and
+    selected pixmaps from the set of pixmaps it is given. Such
+    pixmaps are used by Qt widgets to show an icon representing a
+    particular action.
+
+    \section1 Overview of the Icons Application
+
+    With the Icons application you get a preview of an icon's
+    generated pixmaps reflecting its different states, modes and size.
+
+    When an image is loaded into the application, it is converted into
+    a pixmap and becomes a part of the set of pixmaps available to the
+    icon. An image can be excluded from this set by checking off the
+    related checkbox. The application provides a sub directory
+    containing sets of images explicitly designed to illustrate how Qt
+    renders an icon in different modes and states.
+
+    The application allows you to manipulate the icon size with some
+    predefined sizes and a spin box. The predefined sizes are style
+    dependent, but most of the styles have the same values: Only the
+    Macintosh style differ by using 32 pixels, instead of 16 pixels,
+    for toolbar buttons. You can navigate between the available styles
+    using the \gui View menu.
+
+    \image icons-view-menu.png Screenshot of the View menu
+
+    The \gui View menu also provide the option to make the application
+    guess the icon state and mode from an image's file name. The \gui
+    File menu provide the options of adding an image and removing all
+    images. These last options are also available through a context
+    menu that appears if you press the right mouse button within the
+    table of image files. In addition, the \gui File menu provide an
+    \gui Exit option, and the \gui Help menu provide information about
+    the example and about Qt.
+
+    \image icons_find_normal.png Screenshot of the Find Files
+
+    The screenshot above shows the application with one image file
+    loaded. The \gui {Guess Image Mode/State} is enabled and the
+    style is Plastique.
+
+    When QIcon is provided with only one available pixmap, that
+    pixmap is used for all the states and modes. In this case the
+    pixmap's icon mode is set to normal, and the generated pixmaps
+    for the normal and active modes will look the same. But in
+    disabled and selected mode, Qt will generate a slightly different
+    pixmap.
+
+    The next screenshot shows the application with an additional file
+    loaded, providing QIcon with two available pixmaps. Note that the
+    new image file's mode is set to disabled. When rendering the \gui
+    Disabled mode pixmaps, Qt will now use the new image. We can see
+    the difference: The generated disabled pixmap in the first
+    screenshot is slightly darker than the pixmap with the originally
+    set disabled mode in the second screenshot.
+
+    \image icons_find_normal_disabled.png Screenshot of the Find Files
+
+    When Qt renders the icon's pixmaps it searches through the set of
+    available pixmaps following a particular algorithm. The algorithm
+    is documented in QIcon, but we will describe some particular cases
+    below.
+
+    \image icons_monkey_active.png Screenshot of the Find Files
+
+    In the screenshot above, we have set \c monkey_on_32x32 to be an
+    Active/On pixmap and \c monkey_off_64x64 to be Normal/Off. To
+    render the other six mode/state combinations, QIcon uses the
+    search algorithm described in the table below:
+
+    \table
+    \header \o{2,1} Requested Pixmap \o{8,1} Preferred Alternatives (mode/state)
+    \header \o Mode \o State \o 1  \o 2 \o 3 \o 4 \o 5 \o 6 \o 7 \o 8
+    \row \o{1,2} Normal \o Off \o \bold N0 \o A0 \o N1 \o A1 \o D0 \o S0 \o D1 \o S1
+    \row \o On \o N1 \o \bold A1 \o N0 \o A0 \o D1 \o S1 \o D0 \o S0
+    \row \o{1,2} Active \o Off \o A0 \o \bold N0 \o A1 \o N1 \o D0 \o S0 \o D1 \o S1
+    \row \o On \o \bold A1 \o N1 \o A0 \o N0 \o D1 \o S1 \o D0 \o S0
+    \row \o{1,2} Disabled \o Off \o D0 \o \bold {N0'} \o A0' \o D1 \o N1' \o A1' \o S0' \o S1'
+    \row \o On \o D1 \o N1' \o \bold {A1'} \o D0 \o N0' \o A0' \o S1' \o S0'
+    \row \o{1,2} Selected \o Off \o S0 \o \bold {N0''} \o A0'' \o S1 \o N1'' \o A1'' \o D0'' \o D1''
+    \row \o On \o S1 \o N1'' \o \bold {A1''} \o S0 \o N0'' \o A0'' \o D1'' \o D0''
+    \endtable
+
+    In the table, "0" and "1" stand for Off" and "On", respectively.
+    Single quotes indicates that QIcon generates a disabled ("grayed
+    out") version of the pixmap; similarly, double quuote indicate
+    that QIcon generates a selected ("blued out") version of the
+    pixmap.
+
+    The alternatives used in the screenshot above are shown in bold.
+    For example, the Disabled/Off pixmap is derived by graying out
+    the Normal/Off pixmap (\c monkey_off_64x64).
+
+    In the next screenshots, we loaded the whole set of monkey
+    images. By checking or unchecking file names from the image list,
+    we get different results:
+
+    \table
+    \row
+    \o \inlineimage icons_monkey.png Screenshot of the Monkey Files
+    \o \inlineimage icons_monkey_mess.png Screenshot of the Monkey Files
+    \endtable
+
+    For any given mode/state combination, it is possible to specify
+    several images at different resolutions. When rendering an
+    icon, QIcon will automatically pick the most suitable image
+    and scale it down if necessary. (QIcon never scales up images,
+    because this rarely looks good.)
+
+    The screenshots below shows what happens when we provide QIcon
+    with three images (\c qt_extended_16x16.png, \c qt_extended_32x32.png, \c
+    qt_extended_48x48.png) and try to render the QIcon at various
+    resolutions:
+
+    \table
+    \row
+    \o
+    \o \inlineimage icons_qt_extended_8x8.png Qt Extended icon at 8 x 8
+    \o \inlineimage icons_qt_extended_16x16.png Qt Extended icon at 16 x 16
+    \o \inlineimage icons_qt_extended_17x17.png Qt Extended icon at 17 x 17
+    \row
+    \o
+    \o 8 x 8
+    \o \bold {16 x 16}
+    \o 17 x 17
+    \row
+    \o \inlineimage icons_qt_extended_32x32.png Qt Extended icon at 32 x 32
+    \o \inlineimage icons_qt_extended_33x33.png Qt Extended icon at 33 x 33
+    \o \inlineimage icons_qt_extended_48x48.png Qt Extended icon at 48 x 48
+    \o \inlineimage icons_qt_extended_64x64.png Qt Extended icon at 64 x 64
+    \row
+    \o \bold {32 x 32}
+    \o 33 x 33
+    \o \bold {48 x 48}
+    \o 64 x 64
+    \endtable
+
+    For sizes up to 16 x 16, QIcon uses \c qt_extended_16x16.png and
+    scales it down if necessary. For sizes between 17 x 17 and 32 x
+    32, it uses \c qt_extended_32x32.png. For sizes above 32 x 32, it uses
+    \c qt_extended_48x48.png.
+
+    \section1 Line-by-Line Walkthrough
+
+    The Icons example consists of four classes:
+
+    \list
+    \o \c MainWindow inherits QMainWindow and is the main application
+       window.
+    \o \c IconPreviewArea is a custom widget that displays all
+       combinations of states and modes for a given icon.
+    \o \c IconSizeSpinBox is a subclass of QSpinBox that lets the
+       user enter icon sizes (e.g., "48 x 48").
+    \o \c ImageDelegate is a subclass of QItemDelegate that provides
+       comboboxes for letting the user set the mode and state
+       associated with an image.
+    \endlist
+
+    We will start by reviewing the \c IconPreviewArea class before we
+    take a look at the \c MainWindow class. Finally, we will review the
+    \c IconSizeSpinBox and \c ImageDelegate classes.
+
+    \section2 IconPreviewArea Class Definition
+
+    An \c IconPreviewArea widget consists of a group box containing a grid of
+    QLabel widgets displaying headers and pixmaps.
+
+    \image icons_preview_area.png Screenshot of IconPreviewArea.
+
+    \snippet examples/widgets/icons/iconpreviewarea.h 0
+
+    The \c IconPreviewArea class inherits QWidget. It displays the
+    generated pixmaps corresponding to an icon's possible states and
+    modes at a given size.
+
+    We need two public functions to set the current icon and the
+    icon's size. In addition the class has three private functions: We
+    use the \c createHeaderLabel() and \c createPixmapLabel()
+    functions when constructing the preview area, and we need the \c
+    updatePixmapLabels() function to update the preview area when
+    the icon or the icon's size has changed.
+
+    The \c NumModes and \c NumStates constants reflect \l{QIcon}'s
+    number of currently defined modes and states.
+
+    \section2 IconPreviewArea Class Implementation
+
+    \snippet examples/widgets/icons/iconpreviewarea.cpp 0
+
+    In the constructor we create the labels displaying the headers and
+    the icon's generated pixmaps, and add them to a grid layout.
+
+    When creating the header labels, we make sure the enums \c
+    NumModes and \c NumStates defined in the \c .h file, correspond
+    with the number of labels that we create. Then if the enums at
+    some point are changed, the \c Q_ASSERT() macro will alert that this
+    part of the \c .cpp file needs to be updated as well.
+
+    If the application is built in debug mode, the \c Q_ASSERT()
+    macro will expand to
+
+    \snippet doc/src/snippets/code/doc_src_examples_icons.qdoc 0
+
+    In release mode, the macro simply disappear. The mode can be set
+    in the application's \c .pro file. One way to do so is to add an
+    option to \c qmake when building the application:
+
+    \snippet doc/src/snippets/code/doc_src_examples_icons.qdoc 1
+
+    or
+
+    \snippet doc/src/snippets/code/doc_src_examples_icons.qdoc 2
+
+    Another approach is to add this line directly to the \c .pro
+    file.
+
+    \snippet examples/widgets/icons/iconpreviewarea.cpp 1
+    \codeline
+    \snippet examples/widgets/icons/iconpreviewarea.cpp 2
+
+    The public \c setIcon() and \c setSize() functions change the icon
+    or the icon size, and make sure that the generated pixmaps are
+    updated.
+
+    \snippet examples/widgets/icons/iconpreviewarea.cpp 3
+    \codeline
+    \snippet examples/widgets/icons/iconpreviewarea.cpp 4
+
+    We use the \c createHeaderLabel() and \c createPixmapLabel()
+    functions to create the preview area's labels displaying the
+    headers and the icon's generated pixmaps. Both functions return
+    the QLabel that is created.
+
+    \snippet examples/widgets/icons/iconpreviewarea.cpp 5
+
+    We use the private \c updatePixmapLabel() function to update the
+    generated pixmaps displayed in the preview area.
+
+    For each mode, and for each state, we retrieve a pixmap using the
+    QIcon::pixmap() function, which generates a pixmap corresponding
+    to the given state, mode and size.
+
+    \section2 MainWindow Class Definition
+
+    The \c MainWindow widget consists of three main elements: an
+    images group box, an icon size group box and a preview area.
+
+    \image icons-example.png Screenshot of the Icons example
+
+    \snippet examples/widgets/icons/mainwindow.h 0
+
+    The MainWindow class inherits from QMainWindow. We reimplement the
+    constructor, and declare several private slots:
+
+    \list
+    \o The \c about() slot simply provides information about the example.
+    \o The \c changeStyle() slot changes the application's GUI style and
+       adjust the style dependent size options.
+    \o The \c changeSize() slot changes the size of the preview area's icon.
+    \o The \c changeIcon() slot updates the set of pixmaps available to the
+       icon displayed in the preview area.
+    \o The \c addImage() slot allows the user to load a new image into the
+       application.
+    \endlist
+
+    In addition we declare several private functions to simplify the
+    constructor.
+
+    \section2 MainWindow Class Implementation
+
+    \snippet examples/widgets/icons/mainwindow.cpp 0
+
+    In the constructor we first create the main window's central
+    widget and its child widgets, and put them in a grid layout. Then
+    we create the menus with their associated entries and actions.
+
+    Before we resize the application window to a suitable size, we set
+    the window title and determine the current style for the
+    application. We also enable the icon size spin box by clicking the
+    associated radio button, making the current value of the spin box
+    the icon's initial size.
+
+    \snippet examples/widgets/icons/mainwindow.cpp 1
+
+    The \c about() slot displays a message box using the static
+    QMessageBox::about() function. In this example it displays a
+    simple box with information about the example.
+
+    The \c about() function looks for a suitable icon in four
+    locations: It prefers its parent's icon if that exists. If it
+    doesn't, the function tries the top-level widget containing
+    parent, and if that fails, it tries the active window. As a last
+    resort it uses the QMessageBox's Information icon.
+
+    \snippet examples/widgets/icons/mainwindow.cpp 2
+
+    In the \c changeStyle() slot we first check the slot's
+    parameter. If it is false we immediately return, otherwise we find
+    out which style to change to, i.e. which action that triggered the
+    slot, using the QObject::sender() function.
+
+    This function returns the sender as a QObject pointer. Since we
+    know that the sender is a QAction object, we can safely cast the
+    QObject. We could have used a C-style cast or a C++ \c
+    static_cast(), but as a defensive programming technique we use a
+    \l qobject_cast(). The advantage is that if the object has the
+    wrong type, a null pointer is returned. Crashes due to null
+    pointers are much easier to diagnose than crashes due to unsafe
+    casts.
+
+    \snippet examples/widgets/icons/mainwindow.cpp 3
+    \snippet examples/widgets/icons/mainwindow.cpp 4
+
+    Once we have the action, we extract the style name using
+    QAction::data(). Then we create a QStyle object using the static
+    QStyleFactory::create() function.
+
+    Although we can assume that the style is supported by the
+    QStyleFactory: To be on the safe side, we use the \c Q_ASSERT()
+    macro to check if the created style is valid before we use the
+    QApplication::setStyle() function to set the application's GUI
+    style to the new style. QApplication will automatically delete
+    the style object when a new style is set or when the application
+    exits.
+
+    The predefined icon size options provided in the application are
+    style dependent, so we need to update the labels in the icon size
+    group box and in the end call the \c changeSize() slot to update
+    the icon's size.
+
+    \snippet examples/widgets/icons/mainwindow.cpp 5
+
+    The \c changeSize() slot sets the size for the preview area's
+    icon.
+
+    To determine the new size we first check if the spin box is
+    enabled. If it is, we extract the extent of the new size from the
+    box. If it's not, we search through the predefined size options,
+    extract the QStyle::PixelMetric and use the QStyle::pixelMetric()
+    function to determine the extent. Then we create a QSize object
+    based on the extent, and use that object to set the size of the
+    preview area's icon.
+
+    \snippet examples/widgets/icons/mainwindow.cpp 12
+
+    The first thing we do when the \c addImage() slot is called, is to
+    show a file dialog to the user. The easiest way to create a file
+    dialog is to use QFileDialog's static functions. Here we use the
+    \l {QFileDialog::getOpenFileNames()}{getOpenFileNames()} function
+    that will return one or more existing files selected by the user.
+
+    For each of the files the file dialog returns, we add a row to the
+    table widget. The table widget is listing the images the user has
+    loaded into the application.
+
+    \snippet examples/widgets/icons/mainwindow.cpp 13
+    \snippet examples/widgets/icons/mainwindow.cpp 14
+
+    We retrieve the image name using the QFileInfo::baseName()
+    function that returns the base name of the file without the path,
+    and create the first table widget item in the row. Then we add the
+    file's complete name to the item's data. Since an item can hold
+    several information pieces, we need to assign the file name a role
+    that will distinguish it from other data. This role can be Qt::UserRole
+    or any value above it.
+
+    We also make sure that the item is not editable by removing the
+    Qt::ItemIsEditable flag. Table items are editable by default.
+
+    \snippet examples/widgets/icons/mainwindow.cpp 15
+    \snippet examples/widgets/icons/mainwindow.cpp 16
+    \snippet examples/widgets/icons/mainwindow.cpp 17
+
+    Then we create the second and third items in the row making the
+    default mode Normal and the default state Off. But if the \gui
+    {Guess Image Mode/State} option is checked, and the file name
+    contains "_act", "_dis", or "_sel", the modes are changed to
+    Active, Disabled, or Selected. And if the file name contains
+    "_on", the state is changed to On. The sample files in the
+    example's \c images subdirectory respect this naming convension.
+
+    \snippet examples/widgets/icons/mainwindow.cpp 18
+    \snippet examples/widgets/icons/mainwindow.cpp 19
+
+    In the end we add the items to the associated row, and use the
+    QTableWidget::openPersistentEditor() function to create
+    comboboxes for the mode and state columns of the items.
+
+    Due to the the connection between the table widget's \l
+    {QTableWidget::itemChanged()}{itemChanged()} signal and the \c
+    changeIcon() slot, the new image is automatically converted into a
+    pixmap and made part of the set of pixmaps available to the icon
+    in the preview area. So, corresponding to this fact, we need to
+    make sure that the new image's check box is enabled.
+
+    \snippet examples/widgets/icons/mainwindow.cpp 6
+    \snippet examples/widgets/icons/mainwindow.cpp 7
+
+    The \c changeIcon() slot is called when the user alters the set
+    of images listed in the QTableWidget, to update the QIcon object
+    rendered by the \c IconPreviewArea.
+
+    We first create a QIcon object, and then we run through the
+    QTableWidget, which lists the images the user has loaded into the
+    application.
+
+    \snippet examples/widgets/icons/mainwindow.cpp 8
+    \snippet examples/widgets/icons/mainwindow.cpp 9
+    \snippet examples/widgets/icons/mainwindow.cpp 10
+
+    We also extract the image file's name using the
+    QTableWidgetItem::data() function. This function takes a
+    Qt::DataItemRole as an argument to retrieve the right data
+    (remember that an item can hold several pieces of information)
+    and returns it as a QVariant. Then we use the
+    QVariant::toString() function to get the file name as a QString.
+
+    To create a pixmap from the file, we need to first create an
+    image and then convert this image into a pixmap using
+    QPixmap::fromImage(). Once we have the final pixmap, we add it,
+    with its associated mode and state, to the QIcon's set of
+    available pixmaps.
+
+    \snippet examples/widgets/icons/mainwindow.cpp 11
+
+    After running through the entire list of images, we change the
+    icon of the preview area to the one we just created.
+
+    \snippet examples/widgets/icons/mainwindow.cpp 20
+
+    In the \c removeAllImages() slot, we simply set the table widget's
+    row count to zero, automatically removing all the images the user
+    has loaded into the application. Then we update the set of pixmaps
+    available to the preview area's icon using the \c changeIcon()
+    slot.
+
+    \image icons_images_groupbox.png Screenshot of the images group box
+
+    The \c createImagesGroupBox() function is implemented to simplify
+    the constructor. The main purpose of the function is to create a
+    QTableWidget that will keep track of the images the user has
+    loaded into the application.
+
+    \snippet examples/widgets/icons/mainwindow.cpp 21
+
+    First we create a group box that will contain the table widget.
+    Then we create a QTableWidget and customize it to suit our
+    purposes.
+
+    We call QAbstractItemView::setSelectionMode() to prevent the user
+    from selecting items.
+
+    The QAbstractItemView::setItemDelegate() call sets the item
+    delegate for the table widget. We create a \c ImageDelegate that
+    we make the item delegate for our view.
+
+    The QItemDelegate class can be used to provide an editor for an item view
+    class that is subclassed from QAbstractItemView. Using a delegate
+    for this purpose allows the editing mechanism to be customized and
+    developed independently from the model and view.
+
+    In this example we derive \c ImageDelegate from QItemDelegate.
+    QItemDelegate usually provides line editors, while our subclass
+    \c ImageDelegate, provides comboboxes for the mode and state
+    fields.
+
+    \snippet examples/widgets/icons/mainwindow.cpp 22
+    \snippet examples/widgets/icons/mainwindow.cpp 23
+
+    Then we customize the QTableWidget's horizontal header, and hide
+    the vertical header.
+
+    \snippet examples/widgets/icons/mainwindow.cpp 24
+    \snippet examples/widgets/icons/mainwindow.cpp 25
+
+    At the end, we connect the QTableWidget::itemChanged() signal to
+    the \c changeIcon() slot to ensuret that the preview area is in
+    sync with the image table.
+
+    \image icons_size_groupbox.png Screenshot of the icon size group box
+
+    The \c createIconSizeGroupBox() function is called from the
+    constructor. It creates the widgets controlling the size of the
+    preview area's icon.
+
+    \snippet examples/widgets/icons/mainwindow.cpp 26
+
+    First we create a group box that will contain all the widgets;
+    then we create the radio buttons and the spin box.
+
+    The spin box is not a regular QSpinBox but an \c IconSizeSpinBox.
+    The \c IconSizeSpinBox class inherits QSpinBox and reimplements
+    two functions: QSpinBox::textFromValue() and
+    QSpinBox::valueFromText(). The \c IconSizeSpinBox is designed to
+    handle icon sizes, e.g., "32 x 32", instead of plain integer
+    values.
+
+    \snippet examples/widgets/icons/mainwindow.cpp 27
+
+    Then we connect all of the radio buttons
+    \l{QRadioButton::toggled()}{toggled()} signals and the spin box's
+    \l {QSpinBox::valueChanged()}{valueChanged()} signal to the \c
+    changeSize() slot to make sure that the size of the preview
+    area's icon is updated whenever the user changes the icon size.
+    In the end we put the widgets in a layout that we install on the
+    group box.
+
+    \snippet examples/widgets/icons/mainwindow.cpp 28
+
+    In the \c createActions() function we create and customize all the
+    actions needed to implement the functionality associated with the
+    menu entries in the application.
+
+    In particular we create the \c styleActionGroup based on the
+    currently available GUI styles using
+    QStyleFactory. QStyleFactory::keys() returns a list of valid keys,
+    typically including "windows", "motif", "cde", and
+    "plastique". Depending on the platform, "windowsxp" and
+    "macintosh" may be available.
+
+    We create one action for each key, and adds the action to the
+    action group. Also, for each action, we call QAction::setData()
+    with the style name. We will retrieve it later using
+    QAction::data().
+
+    \snippet examples/widgets/icons/mainwindow.cpp 29
+
+    In the \c createMenu() function, we add the previously created
+    actions to the \gui File, \gui View and \gui Help menus.
+
+    The QMenu class provides a menu widget for use in menu bars,
+    context menus, and other popup menus. We put each menu in the
+    application's menu bar, which we retrieve using
+    QMainWindow::menuBar().
+
+    \snippet examples/widgets/icons/mainwindow.cpp 30
+
+    QWidgets have a \l{QWidget::contextMenuPolicy}{contextMenuPolicy}
+    property that controls how the widget should behave when the user
+    requests a context menu (e.g., by right-clicking). We set the
+    QTableWidget's context menu policy to Qt::ActionsContextMenu,
+    meaning that the \l{QAction}s associated with the widget should
+    appear in its context menu.
+
+    Then we add the \gui{Add Image} and \gui{Remove All Images}
+    actions to the table widget. They will then appear in the table
+    widget's context menu.
+
+    \snippet examples/widgets/icons/mainwindow.cpp 31
+
+    In the \c checkCurrentStyle() function we go through the group of
+    style actions, looking for the current GUI style.
+
+    For each action, we first extract the style name using
+    QAction::data(). Since this is only a QStyleFactory key (e.g.,
+    "macintosh"), we cannot compare it directly to the current
+    style's class name. We need to create a QStyle object using the
+    static QStyleFactory::create() function and compare the class
+    name of the created QStyle object with that of the current style.
+    As soon as we are done with a QStyle candidate, we delete it.
+
+    For all QObject subclasses that use the \c Q_OBJECT macro, the
+    class name of an object is available through its
+    \l{QObject::metaObject()}{meta-object}.
+
+    We can assume that the style is supported by
+    QStyleFactory, but to be on the safe side we use the \c
+    Q_ASSERT() macro to make sure that QStyleFactory::create()
+    returned a valid pointer.
+
+    \section2 IconSizeSpinBox Class Definition
+
+    \snippet examples/widgets/icons/iconsizespinbox.h 0
+
+    The \c IconSizeSpinBox class is a subclass of QSpinBox. A plain
+    QSpinBox can only handle integers. But since we want to display
+    the spin box's values in a more sophisticated way, we need to
+    subclass QSpinBox and reimplement the QSpinBox::textFromValue()
+    and QSpinBox::valueFromText() functions.
+
+    \image icons_size_spinbox.png Screenshot of the icon size spinbox
+
+    \section2 IconSizeSpinBox Class Implementation
+
+    \snippet examples/widgets/icons/iconsizespinbox.cpp 0
+
+    The constructor is trivial.
+
+    \snippet examples/widgets/icons/iconsizespinbox.cpp 2
+
+    QSpinBox::textFromValue() is used by the spin box whenever it
+    needs to display a value. The default implementation returns a
+    base 10 representation of the \c value parameter.
+
+    Our reimplementation returns a QString of the form "32 x 32".
+
+    \snippet examples/widgets/icons/iconsizespinbox.cpp 1
+
+    The QSpinBox::valueFromText() function is used by the spin box
+    whenever it needs to interpret text typed in by the user. Since
+    we reimplement the \c textFromValue() function we also need to
+    reimplement the \c valueFromText() function to interpret the
+    parameter text and return the associated int value.
+
+    We parse the text using a regular expression (a QRegExp). We
+    define an expression that matches one or several digits,
+    optionally followed by whitespace, an "x" or the times symbol,
+    whitespace and one or several digits again.
+
+    The first digits of the regular expression are captured using
+    parentheses. This enables us to use the QRegExp::cap() or
+    QRegExp::capturedTexts() functions to extract the matched
+    characters. If the first and second numbers of the spin box value
+    differ (e.g., "16 x 24"), we use the first number.
+
+    When the user presses \key Enter, QSpinBox first calls
+    QSpinBox::valueFromText() to interpret the text typed by the
+    user, then QSpinBox::textFromValue() to present it in a canonical
+    format (e.g., "16 x 16").
+
+    \section2 ImageDelegate Class Definition
+
+    \snippet examples/widgets/icons/imagedelegate.h 0
+
+    The \c ImageDelegate class is a subclass of QItemDelegate. The
+    QItemDelegate class provides display and editing facilities for
+    data items from a model. A single QItemDelegate object is
+    responsible for all items displayed in a item view (in our case,
+    a QTableWidget).
+
+    A QItemDelegate can be used to provide an editor for an item view
+    class that is subclassed from QAbstractItemView. Using a delegate
+    for this purpose allows the editing mechanism to be customized and
+    developed independently from the model and view.
+
+    \snippet examples/widgets/icons/imagedelegate.h 1
+
+    The default implementation of QItemDelegate creates a QLineEdit.
+    Since we want the editor to be a QComboBox, we need to subclass
+    QItemDelegate and reimplement the QItemDelegate::createEditor(),
+    QItemDelegate::setEditorData() and QItemDelegate::setModelData()
+    functions.
+
+    \snippet examples/widgets/icons/imagedelegate.h 2
+
+    The \c emitCommitData() slot is used to emit the
+    QImageDelegate::commitData() signal with the appropriate
+    argument.
+
+    \section2 ImageDelegate Class Implementation
+
+    \snippet examples/widgets/icons/imagedelegate.cpp 0
+
+    The constructor is trivial.
+
+    \snippet examples/widgets/icons/imagedelegate.cpp 1
+
+    The default QItemDelegate::createEditor() implementation returns
+    the widget used to edit the item specified by the model and item
+    index for editing. The parent widget and style option are used to
+    control the appearance of the editor widget.
+
+    Our reimplementation create and populate a combobox instead of
+    the default line edit. The contents of the combobox depends on
+    the column in the table for which the editor is requested. Column
+    1 contains the QIcon modes, whereas column 2 contains the QIcon
+    states.
+
+    In addition, we connect the combobox's \l
+    {QComboBox::activated()}{activated()} signal to the \c
+    emitCommitData() slot to emit the
+    QAbstractItemDelegate::commitData() signal whenever the user
+    chooses an item using the combobox. This ensures that the rest of
+    the application notices the change and updates itself.
+
+    \snippet examples/widgets/icons/imagedelegate.cpp 2
+
+    The QItemDelegate::setEditorData() function is used by
+    QTableWidget to transfer data from a QTableWidgetItem to the
+    editor. The data is stored as a string; we use
+    QComboBox::findText() to locate it in the combobox.
+
+    Delegates work in terms of models, not items. This makes it
+    possible to use them with any item view class (e.g., QListView,
+    QListWidget, QTreeView, etc.). The transition between model and
+    items is done implicitly by QTableWidget; we don't need to worry
+    about it.
+
+    \snippet examples/widgets/icons/imagedelegate.cpp 3
+
+    The QItemDelegate::setEditorData() function is used by QTableWidget
+    to transfer data back from the editor to the \l{QTableWidgetItem}.
+
+    \snippet examples/widgets/icons/imagedelegate.cpp 4
+
+    The \c emitCommitData() slot simply emit the
+    QAbstractItemDelegate::commitData() signal for the editor that
+    triggered the slot. This signal must be emitted when the editor
+    widget has completed editing the data, and wants to write it back
+    into the model.
+*/