Mainpage.dox

/*
   This file is part of Kirigami
   Copyright (C) 2016 Marco Martin <mart@kde.org>

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU Library General Public License as
   published by the Free Software Foundation; either version 2, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU Library General Public License for more details

   You should have received a copy of the GNU Library General Public
   License along with this program; if not, write to the
   Free Software Foundation, Inc.,
   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
*/


/** \mainpage kirigami


\section overview Introduction
Kirigami is a set of QtQuick components at the moment targeted for mobile use (in the future desktop as well) targeting both Plasma Mobile and Android. It’s not a whole set of components, all the “Primitive” ones like buttons and textboxes are a job for QtQuickControls (soon QtQuickControls2) but it’s a set of high level components to make the creation of applications that look and feel great on mobile as well as desktop devices and follow the <a href="https://community.kde.org/KDE_Visual_Design_Group/KirigamiHIG">Kirigami Human Interface Guidelines</a> .
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 and Windows.
It will eventually become a Tier-1 KDE Framework.

\section components Main Components
- \link org::kde::kirigami::ApplicationWindow  ApplicationWindow \endlink
- \link org::kde::kirigami::Action Action  \endlink
- \link org::kde::kirigami::GlobalDrawer GlobalDrawer  \endlink
- \link org::kde::kirigami::ContextDrawer ContextDrawer  \endlink
- \link org::kde::kirigami::OverlayDrawer OverlayDrawer  \endlink
- \link org::kde::kirigami::Page Page  \endlink
- \link org::kde::kirigami::ScrollablePage ScrollablePage  \endlink
- \link org::kde::kirigami::OverlaySheet  OverlaySheet \endlink
- \link org::kde::kirigami::Theme Theme  \endlink
- \link org::kde::kirigami::Units  Units \endlink
- \link org::kde::kirigami::Icon Icon  \endlink
- \link org::kde::kirigami::BasicListItem BasicListItem  \endlink
- \link org::kde::kirigami::AbstractApplicationHeader AbstractApplicationHeader  \endlink
- \link org::kde::kirigami::AbstractApplicationWindow AbstractApplicationWindow  \endlink
- \link org::kde::kirigami::AbstractListItem AbstractListItem  \endlink
- \link org::kde::kirigami::ApplicationHeader ApplicationHeader  \endlink
- \link org::kde::kirigami::BasicListItem BasicListItem  \endlink
- \link org::kde::kirigami::SwipeListItem  SwipeListItem \endlink
- \link org::kde::kirigami::Heading Heading  \endlink
- \link org::kde::kirigami::Label Label  \endlink


\section example Minimal Example

@code
import QtQuick 2.1
import QtQuick.Controls 2.0 as QQC2
import org.kde.kirigami 2.0 as Kirigami

Kirigami.ApplicationWindow {
    id: root

    header: Kirigami.ApplicationHeader {}

    globalDrawer: Kirigami.GlobalDrawer {
        title: "Hello App"
        titleIcon: "applications-graphics"
        actions: [
            Kirigami.Action {
                text: "View"
                iconName: "view-list-icons"
                Kirigami.Action {
                    text: "action 1"
                }
                Kirigami.Action {
                    text: "action 2"
                }
                Kirigami.Action {
                    text: "action 3"
                }
            },
            Kirigami.Action {
                text: "action 3"
            },
            Kirigami.Action {
                text: "action 4"
            }
            ]
    }
    contextDrawer: Kirigami.ContextDrawer {
        id: contextDrawer
    }
    pageStack.initialPage: mainPageComponent
    Component {
        id: mainPageComponent
        Kirigami.ScrollablePage {
            title: "Hello"
            actions {
                main: Kirigami.Action {
                    iconName: sheet.sheetOpen ? "dialog-cancel" : "document-edit"
                    onTriggered: {
                        print("Action button in buttons page clicked");
                        sheet.sheetOpen = !sheet.sheetOpen
                    }
                }
                left: Kirigami.Action {
                    iconName: "go-previous"
                    onTriggered: {
                        print("Left action triggered")
                    }
                }
                right: Kirigami.Action {
                    iconName: "go-next"
                    onTriggered: {
                        print("Right action triggered")
                    }
                }
                contextualActions: [
                    Kirigami.Action {
                        text:"Action for buttons"
                        iconName: "bookmarks"
                        onTriggered: print("Action 1 clicked")
                    },
                    Kirigami.Action {
                        text:"Action 2"
                        iconName: "folder"
                        enabled: false
                    },
                    Kirigami.Action {
                        text: "Action for Sheet"
                        visible: sheet.sheetOpen
                    }
                ]
            }
            Kirigami.OverlaySheet {
                id: sheet
                onSheetOpenChanged: page.actions.main.checked = sheetOpen
                QQC2.Label {
                    wrapMode: Text.WordWrap
                    text: "Lorem ipsum dolor sit amet"
                }
            }
            //Page contents...
        }
    }
}
@endcode

\section deployment Deployment
CMake is recomended 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.
Kirigami can be built in two ways: both as a module or statically linked in the application, leading to four combinations:
* Kirigami built as a module with CMake
* Kirigami statically built with CMake (needed to link statically from applications built with CMake)
* Kirigami built as a module with QMake
* Kirigami statically built with QMake (needed to link statically from applications built with QMake)

The simplest and recomended 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.
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.

If QMake needs to be used, it's recomended to follow the schema of the example app present in the folder examples/minimalqmake of the Kirigami source code.

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.
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).
The relevant part in the .pro file is:

@code
android: {
    include(3rdparty/kirigami/kirigami.pri)
}
@endcode

While the main.cpp file will have something like:
@code
#include <QGuiApplication>
#include <QQmlApplicationEngine>
#ifdef Q_OS_ANDROID
#include "./3rdparty/kirigami/src/kirigamiplugin.h"
#endif

int main(int argc, char *argv[])
{
    QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling);
    QGuiApplication app(argc, argv);

    QQmlApplicationEngine engine;

#ifdef Q_OS_ANDROID
    KirigamiPlugin::getInstance().registerTypes();
#endif
....
}
@endcode

@authors
Marco Martin \<notmart@gmail.com\><br>
Sebastian Kuegler \<sebas@kde.org\><br>
Aleix Pol Gonzalez \<aleixpol@kde.org\><br>
Dirk Hohndel \<dirk@hohndel.org\><br>

@maintainers
Marco Martin \<notmart@gmail.com\>

@licenses
@lgpl

*/


// DOXYGEN_SET_RECURSIVE = YES
// DOXYGEN_SET_EXCLUDE_PATTERNS += *_p.h */private/* */examples/*
// DOXYGEN_SET_PROJECT_NAME = Kirigami
// vim:ts=4:sw=4:expandtab:filetype=doxygen