Getting Started with Kirigami

Basic application

Before getting started you need to install a few things. First of all we need a C++ compiler, the Qt development packages and Kirigami. On Ubuntu, Debian and Neon you can install these with your package manager:

sudo apt install build-essential extra-cmake-modules cmake qtbase5-dev \
                 qtdeclarative5-dev libqt5svg5-dev qtquickcontrols2-5-dev \
                 qml-module-org-kde-kirigami2 kirigami2-dev libkf5i18n-dev \
                 gettext

We will also use KAppTemplate to generate a suitable project to start from. On Debian-based distributions, it can be installed using sudo apt install kapptemplate.

After starting KAppTemplate, skip through to the page that lets you choose a template for your new project. From the Qt category, choose Graphical and then Kirigami Application. If you can’t find the Kirigami template, your installed Kirigami version might be too old.

After choosing the template, follow through the wizard to create your project. Once the wizard finishes, you should get the following folder hierarchy:

├── CMakeLists.txt
├── org.kde.myapp.appdata.xml
├── org.kde.myapp.desktop
└── src
    ├── CMakeLists.txt
    ├── contents
    │   └── ui
    │       └── main.qml
    ├── main.cpp
    └── resources.qrc

org.kde.myapp.appdata.xml contains the AppStream metadata. These are the data that are displayed on Linux software stores and should be filled with care before releasing an application.

org.kde.myapp.desktop is the so called .desktop file that contains information about how the application should be displayed in a linux application launcher.

The two CMakeLists.txt files contains all the information about how the application will be compiled and installed.

resources.qrc contains the list of all the qml files and other files that will be included in the binary. It is important to update it each time a new qml file is added in the application.

main.cpp is the entrypoint to your application. The two parts of your project, the backend and the user interface are both set up and started here. Currently there is only a basic user interface, in the file called main.qml that is being loaded into the QML engine at the end of the main function.

Open the generated folder in an editor or Integrated Development Enviroment of your choice, like QtCreator or KDevelop.

Anatomy of main.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

import QtQuick 2.1
import org.kde.kirigami 2.4 as Kirigami
import QtQuick.Controls 2.0 as Controls

Kirigami.ApplicationWindow {
    id: root

    title: i18n("tests")

    globalDrawer: Kirigami.GlobalDrawer {
        title: i18n("tests")
        titleIcon: "applications-graphics"
        actions: [
            ...
        ]
    }

    contextDrawer: Kirigami.ContextDrawer {
        id: contextDrawer
    }

    pageStack.initialPage: mainPageComponent

    Component {
        id: mainPageComponent

        Kirigami.Page {
            title: i18n("tests")

            actions {
                ...
            }
        }
    }
}

The base element is a Kirigami.ApplicationWindow and it provides some basic features needed for all Kirigami applications.

The Kirigami.GlobalDrawer is the left sidebar of the application and will contain your application’s navigation. The right sidebar is provided by the Kirigami.ContextDrawer and it contains all your context specific actions on mobile.

The last and most important part of main.qml is the Kirigami.Page and contains your content. This is also that we will see in the next part of this tutorial.

Compiling and running the application

In case you are not using a graphical development environment that supports this out of the box, you can build it using:

cmake -B build/ . && cmake --build build/

The resulting binary can be found in ./build/src/<project name> or ./build/bin/<project name> if you are using a recent version of the template.