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-5/qtquick-index.html">QtQuick</a> components for building adaptable UIs based on <a href="https://doc.qt.io/qt-5/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 <a href="https://doc.qt.io/qt-5/qtquick-qmlscene.html">qmlscene</a> or the <a href="https://doc.qt.io/qt-5/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::BasicListItem BasicListItem  \endlink
0051 - \link org::kde::kirigami::SwipeListItem  SwipeListItem \endlink
0052 - \link org::kde::kirigami::Heading Heading  \endlink
0053 - \link org::kde::kirigami::PlaceholderMessage PlaceholderMessage  \endlink
0054 - \link org::kde::kirigami::SearchField SearchField \endlink
0055 - \link org::kde::kirigami::Dialog Dialog \endlink
0056 - \link org::kde::kirigami::NavigationTabBar NavigationTabBar \endlink
0057 - \link Icon Icon  \endlink
0058
0059 \subsection example Minimal Example
0060
0061 @code
0062 import QtQuick 2.15
0063 import QtQuick.Controls 2.15 as Controls
0064 import org.kde.kirigami 2.20 as Kirigami
0065
0066 Kirigami.ApplicationWindow {
0067     id: root
0068
0069     width: 500
0070     height: 400
0071
0072     globalDrawer: Kirigami.GlobalDrawer {
0073         title: "Hello App"
0074         titleIcon: "applications-graphics"
0075         actions: [
0076             Kirigami.Action {
0077                 text: "View"
0078                 icon.name: "view-list-icons"
0079                 Kirigami.Action {
0080                     text: "action 1"
0081                 }
0082                 Kirigami.Action {
0083                     text: "action 2"
0084                 }
0085                 Kirigami.Action {
0086                     text: "action 3"
0087                 }
0088             },
0089             Kirigami.Action {
0090                 text: "action 3"
0091             },
0092             Kirigami.Action {
0093                 text: "action 4"
0094             }
0095         ]
0096     }
0097     contextDrawer: Kirigami.ContextDrawer {
0098         id: contextDrawer
0099     }
0100     pageStack.initialPage: mainPageComponent
0101     Component {
0102         id: mainPageComponent
0103         Kirigami.ScrollablePage {
0104             id: page
0105             title: "Hello"
0106             actions {
0107                 main: Kirigami.Action {
0108                     icon.name: sheet.sheetOpen ? "dialog-cancel" : "document-edit"
0109                     onTriggered: {
0110                         print("Action button in buttons page clicked");
0111                         sheet.sheetOpen = !sheet.sheetOpen
0112                     }
0113                 }
0114                 left: Kirigami.Action {
0115                     icon.name: "go-previous"
0116                     onTriggered: {
0117                         print("Left action triggered")
0118                     }
0119                 }
0120                 right: Kirigami.Action {
0121                     icon.name: "go-next"
0122                     onTriggered: {
0123                         print("Right action triggered")
0124                     }
0125                 }
0126                 contextualActions: [
0127                     Kirigami.Action {
0128                         text:"Action for buttons"
0129                         icon.name: "bookmarks"
0130                         onTriggered: print("Action 1 clicked")
0131                     },
0132                     Kirigami.Action {
0133                         text:"Action 2"
0134                         icon.name: "folder"
0135                         enabled: false
0136                     },
0137                     Kirigami.Action {
0138                         text: "Action for Sheet"
0139                         visible: sheet.sheetOpen
0140                     }
0141                 ]
0142             }
0143             Kirigami.OverlaySheet {
0144                 id: sheet
0145                 onSheetOpenChanged: page.actions.main.checked = sheetOpen
0146                 Controls.Label {
0147                     wrapMode: Text.WordWrap
0148                     text: "Lorem ipsum dolor sit amet"
0149                 }
0150             }
0151             //Page contents...
0152             Rectangle {
0153                 anchors.fill: parent
0154                 color: "lightblue"
0155             }
0156         }
0157     }
0158 }
0159 @endcode
0160
0161 @image html MinimalExample.webp
0162
0163 \subsection deployment Deployment
0164 CMake is used for both building Kirigami and projects using it, allowing for several configurations depending on how the deployment needs to be done.
0165
0166 Kirigami can be built in two ways: both as a module or statically linked to the application, leading to four combinations:
0167
0168 - Kirigami built as a module with CMake
0169 - Kirigami statically built with CMake (needed to link statically from applications built with CMake)
0170
0171 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.
0172
0173 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.
0174
0175 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.
0176
0177 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).
0178
0179 The main.cpp file should then have something like:
0180
0181 @code
0182 #include <QGuiApplication>
0183 #include <QQmlApplicationEngine>
0184 #ifdef Q_OS_ANDROID
0185 #include "./3rdparty/kirigami/src/kirigamiplugin.h"
0186 #endif
0187
0188 int main(int argc, char *argv[])
0189 {
0190     QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling);
0191     QGuiApplication app(argc, argv);
0192
0193     QQmlApplicationEngine engine;
0194
0195 #ifdef Q_OS_ANDROID
0196     KirigamiPlugin::getInstance().registerTypes(&engine);
0197 #endif
0198     ...
0199 }
0200 @endcode
0201
0202 @authors
0203 Marco Martin \<notmart@gmail.com\><br>
0204 Sebastian Kuegler \<sebas@kde.org\><br>
0205 Aleix Pol Gonzalez \<aleixpol@kde.org\><br>
0206 Dirk Hohndel \<dirk@hohndel.org\><br>
0207
0208 @maintainers
0209 Marco Martin \<notmart@gmail.com\>
0210
0211 @licenses
0212 @lgpl
0213
0214 */
0215
0216
0217 // DOXYGEN_SET_RECURSIVE = YES
0218 // DOXYGEN_SET_EXCLUDE_PATTERNS += *_p.h */private/* */examples/* */doc/* */styles/*
0219 // DOXYGEN_SET_PROJECT_NAME = Kirigami
0220 // vim:ts=4:sw=4:expandtab:filetype=doxygen