From 26590b2c5cc70503bf691ad8b7290196fb1124af Mon Sep 17 00:00:00 2001 From: J-P Nurmi Date: Mon, 24 Oct 2016 22:41:59 +0200 Subject: Doc: configuration file Change-Id: I3de16850673488a8c67afc6b45a79d5bb86f9013 Reviewed-by: Mitch Curtis --- .../doc/src/includes/qquickmaterialstyle.qdocinc | 32 ++++++++ .../doc/src/includes/qquickuniversalstyle.qdocinc | 27 +++++++ .../doc/src/qtquickcontrols2-configuration.qdoc | 94 ++++++++++++++++++++++ .../doc/src/qtquickcontrols2-environment.qdoc | 3 +- .../controls/doc/src/qtquickcontrols2-index.qdoc | 1 + .../doc/src/qtquickcontrols2-material.qdoc | 12 ++- .../controls/doc/src/qtquickcontrols2-styles.qdoc | 40 +-------- .../doc/src/qtquickcontrols2-universal.qdoc | 12 ++- 8 files changed, 178 insertions(+), 43 deletions(-) create mode 100644 src/imports/controls/doc/src/qtquickcontrols2-configuration.qdoc (limited to 'src') diff --git a/src/imports/controls/doc/src/includes/qquickmaterialstyle.qdocinc b/src/imports/controls/doc/src/includes/qquickmaterialstyle.qdocinc index 593e0588..c5d94279 100644 --- a/src/imports/controls/doc/src/includes/qquickmaterialstyle.qdocinc +++ b/src/imports/controls/doc/src/includes/qquickmaterialstyle.qdocinc @@ -1,3 +1,35 @@ +//! [conf] +\table + \header + \li Variable + \li Description + \row + \li \c Theme + \li Specifies the default \l {material-theme-attached-prop}{Material theme}. + The value can be one of the available themes, for example \c "Dark". + \row + \li \c Accent + \li Specifies the default \l {material-accent-attached-prop}{Material accent color}. + The value can be any \l {colorbasictypedocs}{color}, but it is recommended to use + one of the \l {pre-defined Material colors}, for example \c "Teal". + \row + \li \c Primary + \li Specifies the default \l {material-primary-attached-prop}{Material primary color}. + The value can be any \l {colorbasictypedocs}{color}, but it is recommended to use + one of the \l {pre-defined Material colors}, for example \c "BlueGrey". + \row + \li \c Foreground + \li Specifies the default \l {material-foreground-attached-prop}{Material foreground color}. + The value can be any \l {colorbasictypedocs}{color}, or one of the \l {pre-defined Material colors}, + for example \c "Brown". + \row + \li \c Background + \li Specifies the default \l {material-background-attached-prop}{Material background color}. + The value can be any \l {colorbasictypedocs}{color}, or one of the \l {pre-defined Material colors}, + for example \c "Grey". +\endtable +//! [conf] + //! [env] \table \header diff --git a/src/imports/controls/doc/src/includes/qquickuniversalstyle.qdocinc b/src/imports/controls/doc/src/includes/qquickuniversalstyle.qdocinc index d3f4ad4f..a7ecbaef 100644 --- a/src/imports/controls/doc/src/includes/qquickuniversalstyle.qdocinc +++ b/src/imports/controls/doc/src/includes/qquickuniversalstyle.qdocinc @@ -1,3 +1,30 @@ +//! [conf] +\table + \header + \li Variable + \li Description + \row + \li \c Theme + \li Specifies the default \l {universal-theme-attached-prop}{Universal theme}. + The value can be one of the available themes, for example \c "Dark". + \row + \li \c Accent + \li Specifies the default \l {universal-accent-attached-prop}{Universal accent color}. + The value can be any \l {colorbasictypedocs}{color}, but it is recommended to use + one of the \l {pre-defined Universal colors}, for example \c "Violet". + \row + \li \c Foreground + \li Specifies the default \l {universal-foreground-attached-prop}{Universal foreground color}. + The value can be any \l {colorbasictypedocs}{color}, or one of the \l {pre-defined Universal colors}, + for example \c "Brown". + \row + \li \c Background + \li Specifies the default \l {universal-background-attached-prop}{Universal background color}. + The value can be any \l {colorbasictypedocs}{color}, or one of the \l {pre-defined Universal colors}, + for example \c "Steel". +\endtable +//! [conf] + //! [env] \table \header diff --git a/src/imports/controls/doc/src/qtquickcontrols2-configuration.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-configuration.qdoc new file mode 100644 index 00000000..29bfc99c --- /dev/null +++ b/src/imports/controls/doc/src/qtquickcontrols2-configuration.qdoc @@ -0,0 +1,94 @@ +/**************************************************************************** +** +** Copyright (C) 2016 The Qt Company Ltd. +** Contact: http://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 http://www.qt.io/terms-conditions. For further +** information use the contact form at http://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: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qtquickcontrols2-configuration.html + \title Qt Quick Controls 2 Configuration File + + Qt Quick Controls 2 support a special configuration file, \c :/qtquickcontrols2.conf, + that is built into an application's resources. + + The configuration file can specify the preferred style and certain style-specific + attributes. The following example specifies that the preferred style is the \l {Material style}. + Furthermore, when the application is run with the Material style, its theme is light and the + accent and primary colors are teal and blue grey, respectively. However, if the application + is run with the \l {Universal style} instead, the theme is dark and the accent color is red. + + \code + [Controls] + Style=Material + + [Universal] + Theme=Dark + Accent=Red + + [Material] + Theme=Light + Accent=Teal + Primary=BlueGrey + \endcode + + \l {Material style} specific values that can be specified in a \c Material + section of the configuration file: + + \include qquickmaterialstyle.qdocinc conf + + \l {Universal style} specific values that can be specified in a \c Universal + section of the configuration file: + + \include qquickuniversalstyle.qdocinc conf + + In order to make it possible for Qt Quick Controls 2 to find the configuration file, + it must be built into application's resources using the \l {The Qt Resource System}. + Here's an example \c .qrc file: + + \code + + + qtquickcontrols2.conf + + + \endcode + + \note Qt Quick Controls 2 uses a file selector to load the configuration file. It + is possible to provide a different configuration file for different platforms and + locales. See \l QFileSelector documentation for more details. + + Finally, the \c .qrc file must be listed in the application's \c .pro file so that + the build system knows about it. For example: + + \code + RESOURCES = application.qrc + \endcode + + \section1 Related Information + + \list + \li \l{Styling Qt Quick Controls 2} + \li \l{Supported Environment Variables in Qt Quick Controls 2} + \endlist +*/ diff --git a/src/imports/controls/doc/src/qtquickcontrols2-environment.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-environment.qdoc index 9795471d..7c1b1c16 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-environment.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-environment.qdoc @@ -44,7 +44,7 @@ or the path to a custom style such as \c ":/mystyle". \row \li \c QT_QUICK_CONTROLS_CONF - \li Specifies the location of the Qt Quick Controls 2 configuration file. + \li Specifies the location of the \l {Qt Quick Controls 2 configuration file}. By default, the configuration file is loaded from the application's resources in \c ":/qtquickcontrols2.conf". \endtable @@ -61,5 +61,6 @@ \list \li \l{Styling Qt Quick Controls 2} + \li \l{Qt Quick Controls 2 Configuration File} \endlist */ diff --git a/src/imports/controls/doc/src/qtquickcontrols2-index.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-index.qdoc index 23f1e7e5..cdb20a27 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-index.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-index.qdoc @@ -69,6 +69,7 @@ \li \l{Using File Selectors with Qt Quick Controls 2} \li \l{Differences between Qt Quick Controls} \li \l{Deploying Qt Quick Controls 2 Applications} + \li \l{Qt Quick Controls 2 Configuration File} \li \l{Supported Environment Variables in Qt Quick Controls 2} \endlist diff --git a/src/imports/controls/doc/src/qtquickcontrols2-material.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-material.qdoc index 187b51ea..9842fee6 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-material.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-material.qdoc @@ -112,9 +112,15 @@ \endtable In addition to specifying the attributes in QML, it is also possible to - specify them via environment variables or in a \l {qtquickcontrols2-conf} - {configuration file}. Attributes specified in QML take precedence over all - other methods. + specify them via environment variables or in a configuration file. Attributes + specified in QML take precedence over all other methods. + + \section3 Configuration File + + \include qquickmaterialstyle.qdocinc conf + + See \l {Qt Quick Controls 2 Configuration File} for more details about the + configuration file. \section3 Environment Variables diff --git a/src/imports/controls/doc/src/qtquickcontrols2-styles.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-styles.qdoc index 2b44b50d..dc0db600 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-styles.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-styles.qdoc @@ -130,54 +130,21 @@ of supported environment variables. \section2 Configuration file - \target qtquickcontrols2-conf Qt Quick Controls 2 support a special configuration file, \c :/qtquickcontrols2.conf, that is built into an application's resources. The configuration file can specify the preferred style (may be overridden by either of the methods described earlier) and certain style-specific attributes. The following - example specifies that the preferred style is the Material style. Furthermore, when the - application is run with the Material style, its theme is light and the accent and primary - colors are teal and blue grey, respectively. However, if the application is run with the - Universal style instead, the theme is dark and the accent color is red. + example specifies that the preferred style is the Material style. \code [Controls] Style=Material - - [Universal] - Theme=Dark - Accent=Red - - [Material] - Theme=Light - Accent=Teal - Primary=BlueGrey - \endcode - - In order to make it possible for Qt Quick Controls 2 to find the configuration file, - it must be built into application's resources using the \l {The Qt Resource System}. - Here's an example \c .qrc file: - - \code - - - qtquickcontrols2.conf - - \endcode - \note Qt Quick Controls 2 uses a file selector to load the configuration file. It - is possible to provide a different configuration file for different platforms and - locales. See \l QFileSelector documentation for more details. - - Finally, the \c .qrc file must be listed in the application's \c .pro file so that - the build system knows about it. For example: - - \code - RESOURCES = application.qrc - \endcode + See \l {Qt Quick Controls 2 Configuration File} for more details about the + configuration file. \section1 Related Information \list @@ -186,6 +153,7 @@ \li \l {Universal Style} \li \l{Using File Selectors with Qt Quick Controls 2} \li \l {Deploying Qt Quick Controls 2 Applications} + \li \l {Qt Quick Controls 2 Configuration File} \li \l {Supported Environment Variables in Qt Quick Controls 2} \endlist */ diff --git a/src/imports/controls/doc/src/qtquickcontrols2-universal.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-universal.qdoc index 5ae99bef..c0e2daee 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-universal.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-universal.qdoc @@ -111,9 +111,15 @@ \endtable In addition to specifying the attributes in QML, it is also possible to - specify them via environment variables or in a \l {qtquickcontrols2-conf} - {configuration file}. Attributes specified in QML take precedence over all - other methods. + specify them via environment variables or in a configuration file. Attributes + specified in QML take precedence over all other methods. + + \section3 Configuration File + + \include qquickuniversalstyle.qdocinc conf + + See \l {Qt Quick Controls 2 Configuration File} for more details about the + configuration file. \section3 Environment Variables -- cgit v1.2.3