diff options
Diffstat (limited to 'src/imports/controls/doc')
4 files changed, 608 insertions, 0 deletions
diff --git a/src/imports/controls/doc/src/includes/qquickimaginestyle.qdocinc b/src/imports/controls/doc/src/includes/qquickimaginestyle.qdocinc new file mode 100644 index 00000000..861be8eb --- /dev/null +++ b/src/imports/controls/doc/src/includes/qquickimaginestyle.qdocinc @@ -0,0 +1,14 @@ +//! [conf] +TODO +//! [conf] + +//! [env] +\table + \header + \li Variable + \li Description + \row + \li \c QT_QUICK_CONTROLS_IMAGINE_PATH + \li TODO +\endtable +//! [env] diff --git a/src/imports/controls/doc/src/qtquickcontrols2-environment.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-environment.qdoc index 5652d8f5..39ee005b 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-environment.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-environment.qdoc @@ -63,6 +63,10 @@ The value can be set to \c 0 or \c 1 to disable or enable hover effects, respectively. \endtable + \l {Imagine style} specific environment variables: + + \include qquickimaginestyle.qdocinc env + \l {Material style} specific environment variables: \include qquickmaterialstyle.qdocinc env diff --git a/src/imports/controls/doc/src/qtquickcontrols2-imagine.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-imagine.qdoc new file mode 100644 index 00000000..c3c938ff --- /dev/null +++ b/src/imports/controls/doc/src/qtquickcontrols2-imagine.qdoc @@ -0,0 +1,589 @@ +/**************************************************************************** +** +** 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 +*/ diff --git a/src/imports/controls/doc/src/qtquickcontrols2-styles.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-styles.qdoc index 03be5320..97f5e926 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-styles.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-styles.qdoc @@ -127,6 +127,7 @@ \list \li \l {Default Style} \li \l {Fusion Style} + \li \l {Imagine Style} \li \l {Material Style} \li \l {Universal Style} \li \l {Using File Selectors with Qt Quick Controls 2} |