path: root/src/imports/controls/doc/src/qtquickcontrols2-imagine.qdoc

/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page qtquickcontrols2-imagine.html
    \title Imagine Style

    The Imagine Style is based on configurable image assets. \l{detailed-desc-imagine}{More...}

    \styleimport {QtQuick.Controls.Imagine 2.3} {Qt 5.10}

    \section1 Attached Properties

    \list
        \li \l {imagine-path-attached-prop}{\b path} : string
    \endlist

    \section1 Detailed Description
    \target detailed-desc-imagine

    The Imagine style is based on image assets. The style comes with a default
    set of images, but the images can be easily changed by providing a directory
    with images using a predefined naming convention.

    \image qtquickcontrols2-imagine.png
    \caption The Imagine style with the default images

    To run an application with the Imagine style, see
    \l {Using Styles in Qt Quick Controls 2}.

    \section2 File Names

    The image files are named using the following convention:

    \c <control>-<element>-<states>

    The \c <control> and \c <element> sections are mandatory, but the
    \c <states> section is optional. For example, if a single file named
    \c "button-background.9.png" is provided for \l {Button}, it will be used
    for every state that \c Button supports. It is up to the developer to
    decide the set of states that they will provide images for. However, it
    is recommended to provide images for the most common control states where
    possible, such as \c disabled, \c pressed, etc. This will ensure that
    interactive controls visually behave as the end user would expect them to.

    TODO: mention priority order, scoring system?

    The following table lists which elements are supported for each control,
    along with the possible states for that element, and the file extension
    that it expects. An element is an image that represents a certain visual
    part of the control. For example, \c {Button}'s \c "background" element
    represents its \l {Control::}{background}.

    \table
        \header
            \li Control
            \li Element
            \li States
            \li Extension
        \row
            \li \l ApplicationWindow
            \li background
            \li active
            \li .9.png (or .png)
        \row
            \li
            \li overlay
            \li modal
            \li .9.png (or .png)
        \row
            \li \l BusyIndicator
            \li animation
            \li disabled, running, mirrored, hovered
            \li .webp
        \row
            \li
            \li background
            \li same as above
            \li .webp
        \row
            \li \l Button
            \li background
            \li disabled, pressed, checked, checkable, focused, highlighted, flat, mirrored, hovered
            \li .9.png
        \row
            \li \l CheckBox
            \li background
            \li disabled, pressed, checked, partially-checked, focused, mirrored, hovered
            \li .9.png (or .png)
        \row
            \li
            \li indicator
            \li same as above
            \li .png
        \row
            \li \l CheckDelegate
            \li background
            \li disabled, pressed, checked, partially-checked, focused, highlighted, mirrored, hovered
            \li .9.png (or .png)
        \row
            \li
            \li indicator
            \li same as above
            \li .png
        \row
            \li \l ComboBox
            \li background
            \li disabled, pressed, editable, open, focused, mirrored, hovered, flat
            \li .9.png (or .png)
        \row
            \li
            \li indicator
            \li same as above
            \li .png
        \row
            \li
            \li popup
            \li same as above
            \li .9.png (or .png)
        \row
            \li \l DelayButton
            \li background, progress, mask
            \li disabled, pressed, checked, checkable, focused, mirrored, hovered
            \li .9.png (or .png)
        \row
            \li
            \li progress
            \li same as above
            \li .9.png (or .png)
        \row
            \li
            \li mask
            \li same as above
            \li .9.png (or .png)
        \row
            \li \l Dial
            \li background
            \li disabled, pressed, focused, mirrored, hovered
            \li .9.png (or .png)
        \row
            \li
            \li handle
            \li same as above
            \li .9.png (or .png)
        \row
            \li \l Dialog
            \li background
            \li modal, dim
            \li .9.png (or .png)
        \row
            \li
            \li title
            \li same as above
            \li .9.png (or .png)
        \row
            \li
            \li overlay
            \li modal
            \li .9.png (or .png)
        \row
            \li \l DialogButtonBox
            \li background
            \li disabled, mirrored
            \li .9.png (or .png)
        \row
            \li \l Drawer
            \li background
            \li modal, dim, top, left, right, bottom
            \li .9.png (or .png)
        \row
            \li
            \li overlay
            \li modal
            \li .9.png (or .png)
        \row
            \li \l Frame
            \li background
            \li disabled, mirrored
            \li .9.png (or .png)
        \row
            \li \l GroupBox
            \li background
            \li disabled, mirrored
            \li .9.png (or .png)
        \row
            \li
            \li title
            \li same as above
            \li .9.png (or .png)
        \row
            \li \l ItemDelegate
            \li background
            \li disabled, pressed, focused, highlighted, mirrored, hovered
            \li .9.png (or .png)
        \row
            \li \l Label
            \li background
            \li disabled, mirrored, hovered
            \li .9.png (or .png)
        \row
            \li \l Menu
            \li background
            \li modal, dim
            \li .9.png (or .png)
        \row
            \li
            \li overlay
            \li modal
            \li .9.png (or .png)
        \row
            \li \l MenuItem
            \li arrow
            \li disabled, pressed, checked, focused, highlighted, mirrored, hovered
            \li .png
        \row
            \li
            \li background
            \li same as above
            \li .9.png (or .png)
        \row
            \li
            \li indicator
            \li same as above
            \li .png
        \row
            \li \l MenuSeparator
            \li background, separator
            \li disabled, mirrored
            \li .9.png (or .png)
        \row
            \li \l Page
            \li background
            \li disabled, mirrored
            \li .9.png (or .png)
        \row
            \li \l PageIndicator
            \li background
            \li disabled, mirrored, hovered
            \li .9.png (or .png)
        \row
            \li
            \li delegate
            \li disabled, pressed, current, mirrored, hovered
            \li .png
        \row
            \li \l Pane
            \li background
            \li disabled, mirrored
            \li .9.png (or .png)
        \row
            \li \l Popup
            \li background
            \li modal, dim
            \li .9.png (or .png)
        \row
            \li
            \li overlay
            \li modal
            \li .9.png (or .png)
        \row
            \li \l ProgressBar
            \li animation
            \li disabled, mirrored, hovered
            \li .png
        \row
            \li
            \li background
            \li disabled, indeterminate, mirrored, hovered
            \li .9.png (or .png)
        \row
            \li
            \li mask
            \li same as above
            \li .9.png (or .png)
        \row
            \li
            \li progress
            \li same as above
            \li .9.png (or .png)
        \row
            \li \l RadioButton
            \li background, indicator
            \li disabled, pressed, checked, focused, mirrored, hovered
            \li .9.png (or .png)
        \row
            \li
            \li indicator
            \li same as above
            \li .png
        \row
            \li \l RadioDelegate
            \li background
            \li disabled, pressed, checked, focused, highlighted, mirrored, hovered
            \li .9.png (or .png)
        \row
            \li
            \li indicator
            \li same as above
            \li .png
        \row
            \li \l RangeSlider
            \li background
            \li vertical, horizontal, disabled, focused, mirrored, hovered
            \li .9.png (or .png)
        \row
            \li \l RangeSlider
            \li progress
            \li same as above
            \li .9.png (or .png)
        \row
            \li
            \li handle
            \li first, second, vertical, horizontal, disabled, pressed, focused, mirrored, hovered
            \li .png
        \row
            \li \l RoundButton
            \li background
            \li disabled, pressed, checked, checkable, focused, highlighted, flat, mirrored, hovered
            \li .9.png (or .png)
        \row
            \li \l ScrollBar
            \li background
            \li vertical, horizontal, disabled, interactive, pressed, mirrored, hovered
            \li .9.png (or .png)
        \row
            \li
            \li handle
            \li same as above
            \li .9.png (or .png)
        \row
            \li \l ScrollIndicator
            \li background
            \li vertical, horizontal, disabled, mirrored, hovered
            \li .9.png (or .png)
        \row
            \li
            \li handle
            \li same as above
            \li .9.png (or .png)
        \row
            \li \l ScrollView
            \li background
            \li disabled, mirrored
            \li .9.png (or .png)
        \row
            \li \l Slider
            \li background
            \li vertical, horizontal, disabled, pressed, focused, mirrored, hovered
            \li .9.png (or .png)
        \row
            \li
            \li handle
            \li same as above
            \li .9.png (or .png)
        \row
            \li
            \li progress
            \li same as above
            \li .9.png (or .png)
        \row
            \li \l SpinBox
            \li background
            \li disabled, editable, focused, mirrored, hovered
            \li .9.png (or .png)
        \row
            \li
            \li editor
            \li disabled, focused, mirrored, hovered
            \li .9.png (or .png)
        \row
            \li
            \li indicator
            \li up, down, disabled, editable, pressed, focused, mirrored, hovered
            \li .9.png (or .png)
        \row
            \li \l StackView
            \li background
            \li disabled, mirrored
            \li .9.png (or .png)
        \row
            \li \l SwipeDelegate
            \li background
            \li disabled, pressed, focused, highlighted, mirrored, hovered
            \li .9.png (or .png)
        \row
            \li \l SwipeView
            \li background
            \li vertical, horizontal, disabled, interactive, focused, mirrored
            \li .9.png (or .png)
        \row
            \li \l Switch
            \li background, handle, indicator
            \li disabled, pressed, checked, focused, mirrored, hovered
            \li .9.png (or .png)
        \row
            \li
            \li handle
            \li same as above
            \li .9.png (or .png)
        \row
            \li
            \li indicator
            \li same as above
            \li .9.png (or .png)
        \row
            \li \l SwitchDelegate
            \li background, handle, indicator
            \li disabled, pressed, checked, focused, highlighted, mirrored, hovered
            \li .9.png (or .png)
        \row
            \li
            \li handle
            \li same as above
            \li .9.png (or .png)
        \row
            \li
            \li indicator
            \li same as above
            \li .9.png (or .png)
        \row
            \li \l TabBar
            \li background
            \li disabled, header, footer, mirrored
            \li .9.png (or .png)
        \row
            \li \l TabButton
            \li background
            \li disabled, pressed, checked, focused, mirrored, hovered
            \li .9.png (or .png)
        \row
            \li \l TextArea
            \li background
            \li disabled, focused, mirrored, hovered
            \li .9.png (or .png)
        \row
            \li \l TextField
            \li background
            \li disabled, focused, mirrored, hovered
            \li .9.png (or .png)
        \row
            \li \l ToolBar
            \li background
            \li disabled, header, footer, mirrored
            \li .9.png (or .png)
        \row
            \li \l ToolButton
            \li background
            \li disabled, pressed, checked, checkable, focused, highlighted, flat, mirrored, hovered
            \li .9.png (or .png)
        \row
            \li \l ToolSeparator
            \li background, separator
            \li vertical, horizontal, disabled, mirrored
            \li .9.png (or .png)
        \row
            \li \l ToolTip
            \li background
            \li
            \li .9.png (or .png)
        \row
            \li \l Tumbler
            \li background
            \li disabled, focused, mirrored, hovered
            \li .9.png (or .png)
    \endtable

    \section2 9 Patch Images

    ...

    \section2 Animated Images

    ...

    \section2 Palette

    \section2 Customization

    The Imagine style allows customizing the \l {imagine-path-attached-prop}{path}
    that is used to do the image asset selection. The path can be specified for any
    window or item, and it automatically propagates to children in the same manner as
    \l {Control::font}{fonts}. In the following example, the window and all three radio
    buttons appear with dark image assets (files that are located in "qrc:/themes/dark").

    \table
        \row
            \li
                \qml
                import QtQuick 2.0
                import QtQuick.Controls 2.3
                import QtQuick.Controls.Imagine 2.3

                ApplicationWindow {
                    visible: true

                    Imagine.path: "qrc:/themes/dark"

                    Column {
                        anchors.centerIn: parent

                        RadioButton { text: qsTr("Small") }
                        RadioButton { text: qsTr("Medium"); checked: true }
                        RadioButton { text: qsTr("Large") }
                    }
                }
                \endqml
            \li
                \image qtquickcontrols2-imagine-dark.png
    \endtable

    In addition to specifying the path in QML, it is also possible to specify
    it via an environment variable or in a configuration file. Attributes
    specified in QML take precedence over all other methods.

    \section3 Configuration File

    \include qquickimaginestyle.qdocinc conf

    See \l {Qt Quick Controls 2 Configuration File} for more details about the
    configuration file.

    \section3 Environment Variables

    \include qquickimaginestyle.qdocinc env

    See \l {Supported Environment Variables in Qt Quick Controls 2} for the full
    list of supported environment variables.

    \section2 Dependency

    The Imagine style must be separately imported to gain access to the
    attributes that are specific to the Imagine style. It should be noted
    that regardless of the references to the Imagine style, the same
    application code runs with any other style. Imagine-specific attributes
    only have an effect when the application is run with the Imagine style.

    If the Imagine style is imported in a QML file that is always loaded, the
    Imagine style must be deployed with the application in order to be able
    to run the application regardless of which style the application is run with.
    By using \l {Using File Selectors with Qt Quick Controls 2}{file selectors},
    style-specific tweaks can be applied without creating a hard dependency to
    a style.

    \b {See also} \l {Styling Qt Quick Controls 2}

    \section1 Attached Property Documentation

    \styleproperty {Imagine.path} {string} {imagine-path-attached-prop}
    \target imagine-path-attached-prop
    This attached property holds the path to the image assets...

    \code
    Button {
        Imagine.path: "qrc:/themes/dark"
    }
    \endcode

    \endstyleproperty

    \section1 Related Information

    \list
      \li \l{Styling Qt Quick Controls 2}
    \endlist
*/