Warning, /frameworks/kirigami/Mainpage.dox is written in an unsupported language. File is not indexed.

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 QtQuick components for building adaptable UIs based on Qt Quick Controls 2. Its goal is to enable creation of 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>.
0014 The target of those components is anybody that wants to do an application using QtQuick as its main UI, especially if targeting a mobile platform, without adding many dependencies. They work on a variety of platforms, such as Plasma Mobile, Desktop Linux, Android, iOS and Windows.
0015 It is a Tier-1 KDE Framework starting with KDE Frameworks 5.37.
0016 
0017 \subsection tutorial Tutorial
0018 A tutorial for Kirigami is available on <a href="https://develop.kde.org/docs/kirigami/">our developer platform</a>.
0019 
0020 \subsection components Main Components
0021 - \link org::kde::kirigami::ApplicationWindow  ApplicationWindow \endlink
0022 - \link org::kde::kirigami::Action Action  \endlink
0023 - \link org::kde::kirigami::GlobalDrawer GlobalDrawer  \endlink
0024 - \link org::kde::kirigami::ContextDrawer ContextDrawer  \endlink
0025 - \link org::kde::kirigami::OverlayDrawer OverlayDrawer  \endlink
0026 - \link org::kde::kirigami::Page Page  \endlink
0027 - \link org::kde::kirigami::ScrollablePage ScrollablePage  \endlink
0028 - \link org::kde::kirigami::templates::OverlaySheet  OverlaySheet \endlink
0029 - \link PageRouter  PageRouter \endlink
0030 - \link PageRoute  PageRoute \endlink
0031 - \link Kirigami::PlatformTheme Theme  \endlink
0032 - \link Kirigami::Units  Units \endlink
0033 - \link Icon Icon  \endlink
0034 - \link org::kde::kirigami::AbstractApplicationHeader AbstractApplicationHeader  \endlink
0035 - \link org::kde::kirigami::AbstractApplicationWindow AbstractApplicationWindow  \endlink
0036 - \link org::kde::kirigami::AbstractListItem AbstractListItem  \endlink
0037 - \link org::kde::kirigami::BasicListItem BasicListItem  \endlink
0038 - \link org::kde::kirigami::ListSectionHeader ListSectionHeader  \endlink
0039 - \link org::kde::kirigami::SwipeListItem  SwipeListItem \endlink
0040 - \link org::kde::kirigami::Heading Heading  \endlink
0041 - \link org::kde::kirigami::Label Label  \endlink
0042 - \link org::kde::kirigami::PlaceholderMessage PlaceholderMessage  \endlink
0043 - \link org::kde::kirigami::Dialog Dialog \endlink
0044 - \link org::kde::kirigami::NavigationTabBar NavigationTabBar \endlink
0045 
0046 
0047 \subsection example Minimal Example
0048 
0049 @code
0050 import QtQuick 2.1
0051 import QtQuick.Controls 2.0 as QQC2
0052 import org.kde.kirigami 2.4 as Kirigami
0053 
0054 Kirigami.ApplicationWindow {
0055     id: root
0056 
0057     globalDrawer: Kirigami.GlobalDrawer {
0058         title: "Hello App"
0059         titleIcon: "applications-graphics"
0060         actions: [
0061             Kirigami.Action {
0062                 text: "View"
0063                 icon.name: "view-list-icons"
0064                 Kirigami.Action {
0065                     text: "action 1"
0066                 }
0067                 Kirigami.Action {
0068                     text: "action 2"
0069                 }
0070                 Kirigami.Action {
0071                     text: "action 3"
0072                 }
0073             },
0074             Kirigami.Action {
0075                 text: "action 3"
0076             },
0077             Kirigami.Action {
0078                 text: "action 4"
0079             }
0080         ]
0081     }
0082     contextDrawer: Kirigami.ContextDrawer {
0083         id: contextDrawer
0084     }
0085     pageStack.initialPage: mainPageComponent
0086     Component {
0087         id: mainPageComponent
0088         Kirigami.ScrollablePage {
0089             title: "Hello"
0090             actions {
0091                 main: Kirigami.Action {
0092                     icon.name: sheet.sheetOpen ? "dialog-cancel" : "document-edit"
0093                     onTriggered: {
0094                         print("Action button in buttons page clicked");
0095                         sheet.sheetOpen = !sheet.sheetOpen
0096                     }
0097                 }
0098                 left: Kirigami.Action {
0099                     icon.name: "go-previous"
0100                     onTriggered: {
0101                         print("Left action triggered")
0102                     }
0103                 }
0104                 right: Kirigami.Action {
0105                     icon.name: "go-next"
0106                     onTriggered: {
0107                         print("Right action triggered")
0108                     }
0109                 }
0110                 contextualActions: [
0111                     Kirigami.Action {
0112                         text:"Action for buttons"
0113                         icon.name: "bookmarks"
0114                         onTriggered: print("Action 1 clicked")
0115                     },
0116                     Kirigami.Action {
0117                         text:"Action 2"
0118                         icon.name: "folder"
0119                         enabled: false
0120                     },
0121                     Kirigami.Action {
0122                         text: "Action for Sheet"
0123                         visible: sheet.sheetOpen
0124                     }
0125                 ]
0126             }
0127             Kirigami.OverlaySheet {
0128                 id: sheet
0129                 onSheetOpenChanged: page.actions.main.checked = sheetOpen
0130                 QQC2.Label {
0131                     wrapMode: Text.WordWrap
0132                     text: "Lorem ipsum dolor sit amet"
0133                 }
0134             }
0135             //Page contents...
0136         }
0137     }
0138 }
0139 @endcode
0140 
0141 \subsection deployment Deployment
0142 CMake is recommended for both building Kirigami and the project using it, qmake is supported as well, so we can have several configurations, depending what is the host build system and how the deployment needs to be done.
0143 Kirigami can be built in two ways: both as a module or statically linked in the application, leading to four combinations:
0144 
0145 - Kirigami built as a module with CMake
0146 - Kirigami statically built with CMake (needed to link statically from applications built with CMake)
0147 - Kirigami built as a module with qmake
0148 - Kirigami statically built with qmake (needed to link statically from applications built with qmake)
0149 
0150 The simplest and recommended way to use Kirigami is to just use the module provided by the Linux distribution, or build it as a module and deploy it together the main application.
0151 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.
0152 
0153 If qmake needs to be used, it's recommended to follow the schema of the example app present in the folder examples/minimalqmake of the Kirigami source code.
0154 
0155 It will use Kirigami statically linked only on Android, while on desktop systems it will use the version provided by the distribution. What platforms use the static version and what the dynamic one can be freely adjusted.
0156 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).
0157 The relevant part in the .pro file is:
0158 
0159 @code
0160 android: {
0161     include(3rdparty/kirigami/kirigami.pri)
0162 }
0163 @endcode
0164 
0165 While the main.cpp file will have something like:
0166 @code
0167 #include <QGuiApplication>
0168 #include <QQmlApplicationEngine>
0169 #ifdef Q_OS_ANDROID
0170 #include "./3rdparty/kirigami/src/kirigamiplugin.h"
0171 #endif
0172 
0173 int main(int argc, char *argv[])
0174 {
0175     QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling);
0176     QGuiApplication app(argc, argv);
0177 
0178     QQmlApplicationEngine engine;
0179 
0180 #ifdef Q_OS_ANDROID
0181     KirigamiPlugin::getInstance().registerTypes(&engine);
0182 #endif
0183 ....
0184 }
0185 @endcode
0186 
0187 @authors
0188 Marco Martin \<notmart@gmail.com\><br>
0189 Sebastian Kuegler \<sebas@kde.org\><br>
0190 Aleix Pol Gonzalez \<aleixpol@kde.org\><br>
0191 Dirk Hohndel \<dirk@hohndel.org\><br>
0192 
0193 @maintainers
0194 Marco Martin \<notmart@gmail.com\>
0195 
0196 @licenses
0197 @lgpl
0198 
0199 */
0200 
0201 
0202 // DOXYGEN_SET_RECURSIVE = YES
0203 // DOXYGEN_SET_EXCLUDE_PATTERNS += *_p.h */private/* */examples/* */doc/*
0204 // DOXYGEN_SET_PROJECT_NAME = Kirigami
0205 // vim:ts=4:sw=4:expandtab:filetype=doxygen