From e04b7c4b7ba2808215825de23cd6d6606cb9102f Mon Sep 17 00:00:00 2001 From: J-P Nurmi Date: Mon, 23 Oct 2017 13:38:46 +0200 Subject: Docs: promote the icon docs on its own page - other controls (textfield, combobox, ...) will eventually gain support for icons too - advertise icon support on the index page amongst other important topics - document the steps for building an icon theme with high-dpi support Change-Id: I35ed76ef005d7e273beb5f5147ca92849adc0d90 Reviewed-by: Mitch Curtis --- .../controls/doc/src/qtquickcontrols2-icons.qdoc | 169 +++++++++++++++++++++ .../controls/doc/src/qtquickcontrols2-index.qdoc | 1 + src/quicktemplates2/qquickabstractbutton.cpp | 54 +------ 3 files changed, 172 insertions(+), 52 deletions(-) create mode 100644 src/imports/controls/doc/src/qtquickcontrols2-icons.qdoc diff --git a/src/imports/controls/doc/src/qtquickcontrols2-icons.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-icons.qdoc new file mode 100644 index 00000000..c35af60c --- /dev/null +++ b/src/imports/controls/doc/src/qtquickcontrols2-icons.qdoc @@ -0,0 +1,169 @@ +/**************************************************************************** +** +** 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-icons.html + \title Icons in Qt Quick Controls 2 + + Qt Quick Controls 2.3 (Qt 5.10) introduced built-in support for icons. Buttons, + item delegates, and menu items are now capable of presenting an icon in addition + to a text label. + + \section1 Using Icons + + \l {AbstractButton::icon}{AbstractButton} and \l {Action::icon}{Action} provide + the following properties through which icons can be set: + \list + \li \c icon.name + \li \c icon.source + \li \c icon.width + \li \c icon.height + \li \c icon.color + \endlist + + Theme icons are referenced by a name, and regular icons by a source URL. Both + \c icon.name and \c icon.source can be set to ensure that an icon will always + be found. If the icon is found in the theme, it will always be used; even if + \c icon.source is also set. If the icon is not found in the theme, \c icon.source + will be used instead. + + \code + Button { + icon.name: "edit-cut" + icon.source: "images/cut.png" + } + \endcode + + Each \l {Styling Qt Quick Controls 2}{Qt Quick Controls 2 style} requests a + default icon size and color according to their guidelines, but it is possible + to override these by setting the \c icon.width, \c icon.height, and \c icon.color + properties. + + The image that is loaded by an icon whose \c width and \c height are not set + depends on the type of icon in use. For theme icons, the closest available size + will be chosen. For regular icons, the behavior is the same as the \l {Image::} + {sourceSize} property of \l Image. + + The icon color is specified by default so that it matches the text color in + different states. In order to use an icon with the original colors, set the + color to \c "transparent". + + \code + Button { + icon.color: "transparent" + icon.source: "images/logo.png" + } + \endcode + + For buttons, the \l {AbstractButton::}{display} property can be used to control + how the icon and text are displayed within the button. + + \section1 Icon Themes + + Compliant icon themes must follow the freedesktop icon theme specification, + which can be obtained here: \l {http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html}. + + Traditionally, only Linux and UNIX support icon themes on the platform level, + but it is possible to bundle a compliant icon theme in an application to use + themed icons on any platform. + + The default \l {QIcon::themeSearchPaths()}{icon theme search paths} depend on + the platform. On Linux and UNIX, the search path will use the \c XDG_DATA_DIRS + environment variable if available. All platforms have the resource directory + \c :/icons as a fallback. Custom icon theme search paths can be set with + \l QIcon::setThemeSearchPaths(). + + The following example bundles an icon theme called \e mytheme into the application's + resources using \l {The Qt Resource System}{Qt's resource system}. + + \badcode + + + icons/mytheme/index.theme + icons/mytheme/32x32/myicon.png + icons/mytheme/32x32@2/myicon.png + + + \endcode + + The \c index.theme file describes the general attributes of the icon theme, and + lists the available theme icon directories: + + \badcode + [Icon Theme] + Name=mytheme + Comment=My Icon Theme + + Directories=32x32,32x32@2 + + [32x32] + Size=32 + Type=Fixed + + [32x32@2] + Size=32 + Scale=2 + Type=Fixed + \endcode + + In order to use the bundled icon theme, an application should call \l QIcon::setThemeName() + before loading the main QML file: + + \code + #include + #include + #include + + int main(int argc, char *argv[]) + { + QGuiApplication app(argc, argv); + + QIcon::setThemeName("mytheme"); // <-- + + QQmlApplicationEngine engine; + engine.load(QUrl(QStringLiteral("qrc:/main.qml"))); + return app.exec(); + } + \endcode + + Now it is possible to use named icons from the bundled icon theme without having + to specify any fallback source: + + \code + Button { + icon.name: "myicon" + } + \endcode + + The \l {Qt Quick Controls 2 - Gallery}{Gallery example} provides a complete runnable + application with a bundled icon theme. + + \section1 Related Information + \list + \li \l {High-DPI Support in Qt Quick Controls 2} + \endlist +*/ diff --git a/src/imports/controls/doc/src/qtquickcontrols2-index.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-index.qdoc index f64901d5..661266aa 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-index.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-index.qdoc @@ -113,6 +113,7 @@ \list \li \l{Qt Quick Controls 2 Guidelines}{Guidelines} \li \l{Styling Qt Quick Controls 2}{Styling} + \li \l{Icons in Qt Quick Controls 2}{Icons} \li \l{Customizing Qt Quick Controls 2}{Customization} \li \l{High-DPI Support in Qt Quick Controls 2}{High-DPI Support} \li \l{Using File Selectors with Qt Quick Controls 2}{Using File Selectors} diff --git a/src/quicktemplates2/qquickabstractbutton.cpp b/src/quicktemplates2/qquickabstractbutton.cpp index 2100dce2..2c77d941 100644 --- a/src/quicktemplates2/qquickabstractbutton.cpp +++ b/src/quicktemplates2/qquickabstractbutton.cpp @@ -68,56 +68,6 @@ static const int AUTO_REPEAT_INTERVAL = 100; radio buttons and check boxes. As an abstract control, it has no delegate implementations, leaving them to the types that derive from it. - \section2 Button Icons - - AbstractButton provides the following properties through which icons can - be set: - - \list - \li \l icon.name - \li \l icon.source - \li \l icon.width - \li \l icon.height - \li \l icon.color - \endlist - - For applications that target platforms that support both - \l {QIcon::fromTheme()}{theme icons} and regular icons, - both \l icon.name and \l icon.source can be set to ensure that an icon will - always be found. If the icon is found in the theme, it will always be used; - even if \l icon.source is also set. If the icon is not found, - \l icon.source will be used instead. - - \code - Button { - icon.name: "edit-cut" - icon.source: "qrc:/icons/edit-cut.png" - } - \endcode - - Each \l {Styling Qt Quick Controls 2}{style} sets a default icon size and - color according to their guidelines, but it is possible to override these - by setting the \l icon.width, \l icon.height, and \l icon.color properties. - - The image that is loaded by an icon whose \c width and \c height are not set - depends on the type of icon in use. For theme icons, the closest available - size will be chosen. For regular icons, the behavior is the same as the - \l {Image::}{sourceSize} property of \l Image. - - The icon color is specified by default so that it matches the text color in - different states. In order to use an icon with the original colors, set the - color to \c "transparent". - - \code - Button { - icon.color: "transparent" - icon.source: "qrc:/icons/logo.png" - } - \endcode - - The \l display property can be used to control how the icon and text are - displayed within the button. - \sa ButtonGroup, {Button Controls} */ @@ -441,7 +391,7 @@ QQuickAbstractButton::~QQuickAbstractButton() \note The text is used for accessibility purposes, so it makes sense to set a textual description even if the content item is an image. - \sa {Control::contentItem}{contentItem} + \sa icon, display, {Control::contentItem}{contentItem} */ QString QQuickAbstractButton::text() const { @@ -686,7 +636,7 @@ void QQuickAbstractButton::setIndicator(QQuickItem *indicator) \include qquickicon.qdocinc grouped-properties - \sa {Button Icons} + \sa text, display, {Icons in Qt Quick Controls 2} */ QQuickIcon QQuickAbstractButton::icon() const -- cgit v1.2.3