frameworks/qqc2-desktop-style/README.md

0001 # QQC2 Desktop Style
0002
0003 This is a style for Qt Quick Controls (also known as QQC2 in Qt5) which uses the application's [QStyle](https://doc.qt.io/qt-6/qstyle.html) to paint the controls in order to give them native look and feel.
0004
0005 This framework has no public API, applications should not (and cannot) use it directly. Instead, developers should add this framework as a dependency of their desktop apps.
0006
0007 ## Usage
0008
0009 The name of the style is `org.kde.desktop`.
0010
0011 On Plasma, this style is picked up automatically without the need to set an environment variable as long as both [Breeze](https://invent.kde.org/plasma/breeze) and [Plasma Integration](https://invent.kde.org/plasma/plasma-integration) are installed.
0012
0013 To support non-Plasma environments like Windows or GNOME, applications will need to define this style in code like [any other QQC style](https://doc.qt.io/qt-6/qtquickcontrols2-styles.html#using-styles-in-qt-quick-controls), e.g.:
0014
0015 ```c++
0016 #include <QQuickStyle>
0017
0018 int main(int argc, char *argv[])
0019 {
0020     QApplication app(argc, argv);
0021
0022     // Default to org.kde.desktop style unless the user forces another style
0023     if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE")) {
0024         QQuickStyle::setStyle(QStringLiteral("org.kde.desktop"));
0025     }
0026
0027     QQmlApplicationEngine engine;
0028     ...
0029 }
0030 ```
0031
0032 **NOTE: the application must be a QApplication rather than a QGuiApplication instance in order for this style to be used.**
0033
0034 If the application supports Android, check if  `Q_OS_ANDROID` is defined first:
0035
0036 ```c++
0037 #ifdef Q_OS_ANDROID
0038     QGuiApplication app(argc, argv);
0039     // Set your preferred Android QQC style here, in this case QQC2 Breeze Style
0040     QQuickStyle::setStyle(QStringLiteral("org.kde.breeze"));
0041 #else
0042     QApplication app(argc, argv);
0043     if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE")) {
0044         QQuickStyle::setStyle(QStringLiteral("org.kde.desktop"));
0045     }
0046 #endif
0047 ```
0048
0049 ## Differences from QQC2 Breeze Style
0050
0051 QQC2 Desktop Style should be used in desktop applications thanks to its native QStyling, making it look and feel like a QtWidgets application. However it has a noticeable performance impact on mobile systems like Plasma Mobile and Android. It's also desirable to avoid using QtWidgets on those platforms too.
0052
0053 It's recommended to use [QQC2 Breeze Style](https://invent.kde.org/plasma/qqc2-breeze-style) as shown above for those platforms. It replicates the Breeze visual design without depending on QStyle.
0054
0055 ## Building
0056
0057 The easiest way to make changes and test QQC2 Desktop Style during development is to [build it with kdesrc-build](https://community.kde.org/Get_Involved/development/Build_software_with_kdesrc-build).
0058
0059 ## Contributing
0060
0061 Like other projects in the KDE ecosystem, contributions are welcome from all. This repository is managed in [KDE Invent](https://invent.kde.org/frameworks/qqc2-desktop-style), our GitLab instance.
0062
0063 * Want to contribute code? See the [GitLab wiki page](https://community.kde.org/Infrastructure/GitLab) for a tutorial on how to send a merge request.
0064 * Reporting a bug? Please submit it on the [KDE Bugtracking System](https://bugs.kde.org/enter_bug.cgi?format=guided&product=frameworks-qqc2-desktop-style). Please do not use the Issues tab to report bugs.
0065
0066 If you get stuck or need help with anything at all, head over to the [KDE New Contributors room](https://go.kde.org/matrix/#/#kde-welcome:kde.org) on Matrix. For questions about QQC2 Desktop Style, please ask in the [KDE Development room](https://go.kde.org/matrix/#/#kde-devel:kde.org). See [Matrix](https://community.kde.org/Matrix) for more details.
0067