diff options
Diffstat (limited to 'src/imports/controls/doc/src/qtquickcontrols2-icons.qdoc')
| -rw-r--r-- | src/imports/controls/doc/src/qtquickcontrols2-icons.qdoc | 169 |
1 files changed, 169 insertions, 0 deletions
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 + <RCC> + <qresource prefix="/"> + <file>icons/mytheme/index.theme</file> + <file>icons/mytheme/32x32/myicon.png</file> + <file>icons/mytheme/32x32@2/myicon.png</file> + </qresource> + </RCC> + \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 <QGuiApplication> + #include <QQmlApplicationEngine> + #include <QIcon> + + 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 +*/ |