frameworks/kirigami/Mainpage.dox

0001 /*
0002  *  This file is part of Kirigami
0003  *  SPDX-FileCopyrightText: 2016 Marco Martin <mart@kde.org>
0004  *
0005  *  SPDX-License-Identifier: LGPL-2.0-or-later
0006  */
0007
0008
0009 /** \mainpage kirigami
0010
0011
0012 \subsection overview Introduction
0013 Kirigami is a set of <a href="https://doc.qt.io/qt-6/qtquick-index.html">QtQuick</a> components for building adaptable UIs based on <a href="https://doc.qt.io/qt-6/qtquickcontrols-index.html">QtQuick Controls 2</a>.
0014
0015 Its goal is to enable creation of convergent applications that look and feel great on mobile as well as desktop devices and follow the <a href="https://develop.kde.org/hig">KDE Human Interface Guidelines</a> while being easy to use and not adding many dependencies.
0016
0017 Kirigami works on a variety of platforms, such as <a href="https://plasma-mobile.org/">Plasma Mobile</a>, Desktop Linux, Android, MacOS, and Windows.
0018
0019 It was introduced in <a href="https://kde.org/announcements/frameworks/5/5.37.0/">KDE Frameworks 5.37</a> as a <a href="https://api.kde.org/frameworks/#sg-tier_1">Tier-1 KDE Framework</a>.
0020
0021 \subsection tutorial Tutorial
0022 A tutorial for Kirigami is available on <a href="https://develop.kde.org/docs/getting-started/kirigami/">our developer platform</a>.
0023
0024 It is possible to make short mockups using QtQuick and Kirigami in the <a href="https://qmlonline.kde.org/">QML Online website</a> and briefly test individual QML files using the <a href="https://doc.qt.io/qt-6/qtquick-qml-runtime.html">qml tool</a>.
0025
0026 A list of additional QML learning resources is available in the <a href="https://community.kde.org/Get_Involved/development/Learn#QtQuick/QML">Community Wiki</a>. If you are not familiar with QML at all, the <a href="https://www.qt.io/product/qt6/qml-book">QML book</a> should be a good head start.
0027
0028 If you have any questions about Kirigami, feel free to drop by the <a href="https://go.kde.org/matrix/#/#kirigami:kde.org">Kirigami group on Matrix</a>.
0029
0030 \subsection components Main Window Components
0031 - \link org::kde::kirigami::ApplicationWindow  ApplicationWindow \endlink
0032 - \link org::kde::kirigami::Action Action  \endlink
0033 - \link org::kde::kirigami::GlobalDrawer GlobalDrawer  \endlink
0034 - \link org::kde::kirigami::ContextDrawer ContextDrawer  \endlink
0035 - \link org::kde::kirigami::OverlayDrawer OverlayDrawer  \endlink
0036 - \link org::kde::kirigami::Page Page  \endlink
0037 - \link org::kde::kirigami::ScrollablePage ScrollablePage  \endlink
0038 - \link org::kde::kirigami::AboutPage AboutPage \endlink
0039 - \link org::kde::kirigami::PageRow PageRow \endlink
0040 - \link org::kde::kirigami::FormLayout FormLayout \endlink
0041 - \link org::kde::kirigami::CardsLayout CardsLayout \endlink
0042 - \link SizeGroup SizeGroup \endlink
0043 - \link Kirigami::PlatformTheme Theme  \endlink
0044 - \link Kirigami::Units  Units \endlink
0045
0046 \subsection controls Common Kirigami Controls
0047
0048 - \link org::kde::kirigami::Card Card \endlink
0049 - \link org::kde::kirigami::templates::OverlaySheet  OverlaySheet \endlink
0050 - \link org::kde::kirigami::SwipeListItem  SwipeListItem \endlink
0051 - \link org::kde::kirigami::Heading Heading  \endlink
0052 - \link org::kde::kirigami::PlaceholderMessage PlaceholderMessage  \endlink
0053 - \link org::kde::kirigami::SearchField SearchField \endlink
0054 - \link org::kde::kirigami::Dialog Dialog \endlink
0055 - \link org::kde::kirigami::NavigationTabBar NavigationTabBar \endlink
0056 - \link Icon Icon  \endlink
0057
0058 \subsection example Minimal Example
0059
0060 @code
0061 import QtQuick 2.15
0062 import QtQuick.Controls 2.15 as Controls
0063 import org.kde.kirigami 2.20 as Kirigami
0064
0065 Kirigami.ApplicationWindow {
0066     id: root
0067
0068     width: 500
0069     height: 400
0070
0071     globalDrawer: Kirigami.GlobalDrawer {
0072         actions: [
0073             Kirigami.Action {
0074                 text: "View"
0075                 icon.name: "view-list-icons"
0076                 Kirigami.Action {
0077                     text: "action 1"
0078                 }
0079                 Kirigami.Action {
0080                     text: "action 2"
0081                 }
0082                 Kirigami.Action {
0083                     text: "action 3"
0084                 }
0085             },
0086             Kirigami.Action {
0087                 text: "action 3"
0088             },
0089             Kirigami.Action {
0090                 text: "action 4"
0091             }
0092         ]
0093     }
0094     contextDrawer: Kirigami.ContextDrawer {
0095         id: contextDrawer
0096     }
0097     pageStack.initialPage: mainPageComponent
0098     Component {
0099         id: mainPageComponent
0100         Kirigami.ScrollablePage {
0101             id: page
0102             title: "Hello"
0103             actions {
0104                 main: Kirigami.Action {
0105                     icon.name: sheet.sheetOpen ? "dialog-cancel" : "document-edit"
0106                     onTriggered: {
0107                         print("Action button in buttons page clicked");
0108                         sheet.sheetOpen = !sheet.sheetOpen
0109                     }
0110                 }
0111                 left: Kirigami.Action {
0112                     icon.name: "go-previous"
0113                     onTriggered: {
0114                         print("Left action triggered")
0115                     }
0116                 }
0117                 right: Kirigami.Action {
0118                     icon.name: "go-next"
0119                     onTriggered: {
0120                         print("Right action triggered")
0121                     }
0122                 }
0123                 contextualActions: [
0124                     Kirigami.Action {
0125                         text:"Action for buttons"
0126                         icon.name: "bookmarks"
0127                         onTriggered: print("Action 1 clicked")
0128                     },
0129                     Kirigami.Action {
0130                         text:"Action 2"
0131                         icon.name: "folder"
0132                         enabled: false
0133                     },
0134                     Kirigami.Action {
0135                         text: "Action for Sheet"
0136                         visible: sheet.sheetOpen
0137                     }
0138                 ]
0139             }
0140             Kirigami.OverlaySheet {
0141                 id: sheet
0142                 onSheetOpenChanged: page.actions.main.checked = sheetOpen
0143                 Controls.Label {
0144                     wrapMode: Text.WordWrap
0145                     text: "Lorem ipsum dolor sit amet"
0146                 }
0147             }
0148             //Page contents...
0149             Rectangle {
0150                 anchors.fill: parent
0151                 color: "lightblue"
0152             }
0153         }
0154     }
0155 }
0156 @endcode
0157
0158 @image html MinimalExample.webp
0159
0160 \subsection deployment Deployment
0161 CMake is used for both building Kirigami and projects using it, allowing for several configurations depending on how the deployment needs to be done.
0162
0163 Kirigami can be built in two ways: both as a module or statically linked to the application, leading to four combinations:
0164
0165 - Kirigami built as a module with CMake
0166 - Kirigami statically built with CMake (needed to link statically from applications built with CMake)
0167
0168 The simplest and recommended way to use Kirigami is to just use the packages provided by your Linux distribution, or build it as a module and deploy it together with the main application.
0169
0170 For example, when building an application on Android with CMake, if Kirigami for Android is built and installed in the same temporary directory before the application, the create-apk step of the application will include the Kirigami files as well in the APK.
0171
0172 Statically linked Kirigami will be used only on Android, while on desktop systems it will use the version provided by the distribution. Which platforms use the static version and which use the dynamic one can be freely adjusted.
0173
0174 The application needs to have a folder called "3rdparty" containing clones of two KDE repositories: kirigami and breeze-icons (available at git://anongit.kde.org/kirigami.git and git://anongit.kde.org/breeze-icons.git).
0175
0176 The main.cpp file should then have something like:
0177
0178 @code
0179 #include <QGuiApplication>
0180 #include <QQmlApplicationEngine>
0181 #ifdef Q_OS_ANDROID
0182 #include "./3rdparty/kirigami/src/kirigamiplugin.h"
0183 #endif
0184
0185 int main(int argc, char *argv[])
0186 {
0187     QGuiApplication app(argc, argv);
0188
0189     QQmlApplicationEngine engine;
0190
0191 #ifdef Q_OS_ANDROID
0192     KirigamiPlugin::getInstance().registerTypes(&engine);
0193 #endif
0194     ...
0195 }
0196 @endcode
0197
0198 @authors
0199 Marco Martin \<notmart@gmail.com\><br>
0200 Sebastian Kuegler \<sebas@kde.org\><br>
0201 Aleix Pol Gonzalez \<aleixpol@kde.org\><br>
0202 Dirk Hohndel \<dirk@hohndel.org\><br>
0203
0204 @maintainers
0205 Marco Martin \<notmart@gmail.com\>
0206
0207 @licenses
0208 @lgpl
0209
0210 */
0211
0212
0213 // DOXYGEN_SET_RECURSIVE = YES
0214 // DOXYGEN_SET_EXCLUDE_PATTERNS += *_p.h */private/* */examples/* */doc/* */styles/*
0215 // DOXYGEN_SET_PROJECT_NAME = Kirigami
0216 // vim:ts=4:sw=4:expandtab:filetype=doxygen