/****************************************************************************

**

** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (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 Technology Preview License Agreement accompanying

** this package.

**

** 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.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@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 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.