Configuração e introdução

Installing Kirigami

Before getting started, we will need to install Kirigami on our machine. There are three ways to do so:

• Installing Kirigami from the repositories in your Linux distribution
• Using kde-builder
• Installing Kirigami with Craft

Installing Kirigami from the repositories in your Linux distribution

We need a C++ compiler, Qt development packages, and Kirigami. Open a terminal application and run one of the following, depending on which Linux distribution you are using:

ManjaroArch	sudo pacman -S base-devel extra-cmake-modules cmake kirigami ki18n kcoreaddons breeze kiconthemes qt6-base qt6-declarative qqc2-desktop-style
OpenSUSE	sudo zypper install cmake kf6-extra-cmake-modules kf6-kirigami-devel kf6-ki18n-devel kf6-kcoreaddons-devel kf6-kiconthemes-devel qt6-base-devel qt6-declarative-devel qt6-quickcontrols2-devel kf6-qqc2-desktop-style
Fedora	sudo dnf groupinstall "Development Tools" "Development Libraries" sudo dnf install cmake extra-cmake-modules kf6-kirigami2-devel kf6-ki18n-devel kf6-kcoreaddons-devel kf6-kiconthemes-devel qt6-qtbase-devel qt6-qtdeclarative-devel qt6-qtquickcontrols2-devel kf6-qqc2-desktop-style

Further information for other distributions can be found here.

Using kde-builder

Set up your development environment with kde-builder. That will give you the necessary development tools and underlying libraries, and build the KDE Frameworks from scratch.

Create a folder ~/kde/src/kirigami-tutorial. In that folder you will place the source code files from this tutorial.

Add the following at the end of your ~/.config/kde-builder.yaml:

project kirigami-tutorial:
  no-src: true

# after include ${module-definitions-dir}/kf6-qt6.ksb
module kirigami-tutorial
  no-src
end module

Installing Kirigami with Craft

KDE has a custom tool to easily install most of its libraries and programs: Craft. It can be used to install Kirigami on Linux, FreeBSD, Windows, Android and macOS.

You will need to follow the setup instructions for Craft. By the end of the setup, you should have run an environment setup file (craftenv.ps1 or craftenv.sh), which will give you a terminal shell where you will be compiling your Kirigami application.

After that, you may simply run the following on a terminal:

craft kirigami kcoreaddons ki18n breeze kiconthemes qqc2-desktop-style

If you close your terminal, you can simply run the environment setup file again to compile your app.

Estrutura do projecto

Embora existam ferramentas que nos ajudem a configurar facilmente os nossos ficheiros, vamos criá-los manualmente. Isto permitir-nos-á compreender melhor as componentes que irão compor a nossa nova aplicação.

First we create our project folder (you can use the commands below). We are going to call ours kirigami-tutorial/.

kirigami-tutorial/
├── CMakeLists.txt
├── org.kde.tutorial.desktop
└── src/
    ├── CMakeLists.txt
    ├── main.cpp
    └── Main.qml

Within this folder we are going to create a src/ folder and CMakeLists.txt. It is generally considered good practice to place all our main C++ code files in a src/ folder. We also put the Main.qml file in it since it will be run together with the executable.

mkdir -p kirigami-tutorial/src
touch kirigami-tutorial/{CMakeLists.txt,org.kde.tutorial.desktop}
touch kirigami-tutorial/src/{CMakeLists.txt,main.cpp,Main.qml}

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

// Includes relevant modules used by the QML
import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

// Provides basic features needed for all kirigami applications
Kirigami.ApplicationWindow {
    // Unique identifier to reference this object
    id: root

    width: 400
    height: 300

    // Window title
    // i18nc() makes a string translatable
    // and provides additional context for the translators
    title: i18nc("@title:window", "Hello World")

    // Set the first page that will be loaded when the app opens
    // This can also be set to an id of a Kirigami.Page
    pageStack.initialPage: Kirigami.Page {
        Controls.Label {
            // Center label horizontally and vertically within parent object
            anchors.centerIn: parent
            text: i18n("Hello World!")
        }
    }
}

Aqui está como será tratada a interface da nossa aplicação.

If you know some Javascript, then much of QML will seem familiar to you (though it does have its own peculiarities). Qt's documentation has an extensive amount of material on this language if you feel like trying something on your own. Over the course of these tutorials we will be focusing much of our attention on our QML code, where we can use Kirigami to get the most out of it.

For now, let's focus on Main.qml. First we import a number of important modules:

• O QtQuick, a biblioteca-padrão usada nas aplicações em QML.
• O QtQuick Controls, que oferece um conjunto de controlos-padrão que poderemos usar para tornar as nossas aplicações interactivas.
• O QtQuick Layouts, que oferece ferramentas para colocar os componentes dentro da janela da aplicação.
• O Kirigami, que oferece um conjunto de componentes adequados para criar aplicações que funcionam bem entre dispositivos de formas e tamanhos diferentes.

Iremos então voltar ao nosso elemento de base, o Kirigami.ApplicationWindow que oferece algumas funcionalidades básicas necessárias para todas as aplicações de Kirigami. Esta é a janela que irá conter cada uma das nossas páginas, as secções principais da nossa interface.

Iremos então configurar a propriedade id da janela como 'root'. Os ID's são úteis porque nos ajudam a referenciar um componente de forma unívoca, mesmo que tenhamos vários do mesmo tipo.

Também configuramos a propriedade title da janela como "Hello World" (Olá Mundo). Irá reparar que envolvemos o nosso texto com uma função chamada i18nc(), onde iremos detalhar o contexto do texto, assim como o texto propriamente dito.

Definimos então a primeira página da nossa pilha de páginas. A maioria das aplicações do Kirigami são organizadas como uma pilha de páginas, contendo cada uma os componentes relacionados e adequados para uma dada tarefa. Por agora, iremos mantê-la simples e ficaremos apenas com uma única página. A pageStack é uma pilha inicialmente vazia de páginas fornecidas pelo Kirigami.ApplicationWindow, e com a pageStack.initialPage: Kirigami.Page {...}, iremos configurar a primeira página apresentada ao carregar a aplicação como uma Kirigami.Page, a qual irá conter todo o nosso conteúdo.

Finalmente, incluímos na nossa página um Controls.Label que nos permite colocar texto na nossa página. Usamos o anchors.centerIn: parent para centrar o nosso texto na horizontal e na vertical dentro do nosso elemento-pai. Neste caso, o componente-pai do Controls.Label é o Kirigami.Page. A última coisa que é necessária é definir o texto: text: i18n("Hello World!").

org.kde.tutorial.desktop

The primary purpose of Desktop Entry files is to show your app on the application launcher on Linux. Another reason to have them is to have window icons on Wayland, as they are required to tell the compositor "this window goes with this icon".

It must follow a reverse-DNS naming scheme followed by the .desktop extension such as org.kde.tutorial.desktop:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

[Desktop Entry]
Name=Kirigami Tutorial
Name[ca]=Guia d'aprenentatge del Kirigami
Name[cs]=Tutoriál Kirigami
Name[eo]=Lernilo pri Kirigami
Name[es]=Tutorial de Kirigami
Name[fr]=Tutoriel pour Kirigami
Name[it]=Esercitazione di Kirigami
Name[nl]=Kirigami handleiding
Name[sl]=Učbenik Kirigami
Name[sv]=Kirigami-handledning
Name[tr]=Kirigami Öğreticisi
Name[uk]=Підручник з Kirigami
Name[x-test]=xxKirigami Tutorialxx
Name[zh_TW]=Kirigami 教學
Exec=kirigami-hello
Icon=kde
Type=Application
Terminal=false
Categories=Utility

CMakeLists.txt

CMakeLists.txt files are needed to use KDE's build system of choice, CMake. Our kirigami-tutorial/CMakeLists.txt file is going to specify some of our application's characteristics. It also includes some of the dependencies we need in order to compile our project.

 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
36

cmake_minimum_required(VERSION 3.20)
project(kirigami-tutorial)

find_package(ECM 6.0.0 REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)
include(ECMFindQmlModule)
include(ECMQmlModule)

find_package(Qt6 REQUIRED COMPONENTS
    Core
    Quick
    Test
    Gui
    QuickControls2
    Widgets
)

find_package(KF6 REQUIRED COMPONENTS
    Kirigami
    I18n
    CoreAddons
    QQC2DesktopStyle
    IconThemes
)

ecm_find_qmlmodule(org.kde.kirigami REQUIRED)

add_subdirectory(src)

install(PROGRAMS org.kde.tutorial.desktop DESTINATION ${KDE_INSTALL_APPDIR})

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

O CMakeLists.txt define como compilar os seus projectos. A maioria do conteúdo aqui serve para configurar inicialmente o seu projecto. Poderá ler uma explicação linha-a-linha e aprofundada do que faz este ficheiro CMakeLists aqui.

The most important thing to keep in mind is that the C++ build dependencies of Qt and KDE Frameworks are managed with find_package() and QML runtime dependencies are managed with ecm_find_qml_module(). You will have to modify these lines and include any additional components that you decide to use during the development of your application.

The line with add_subdirectory(src) points CMake to the kirigami-tutorial/src/ directory, where our source code is located.

The line with install() tells CMake where to install the desktop file.

Let's delve into the kirigami-tutorial/src/CMakeLists.txt file in there.

 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

add_executable(kirigami-hello)

ecm_add_qml_module(kirigami-hello
    URI
    org.kde.tutorial
)

target_sources(kirigami-hello
    PRIVATE
    main.cpp
)

ecm_target_qml_sources(kirigami-hello
    SOURCES
    Main.qml
)

target_link_libraries(kirigami-hello
    PRIVATE
    Qt6::Quick
    Qt6::Qml
    Qt6::Gui
    Qt6::QuickControls2
    Qt6::Widgets
    KF6::I18n
    KF6::CoreAddons
    KF6::IconThemes
)

install(TARGETS kirigami-hello ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

This file consists of five steps:

1. create an executable
2. change the executable into a QML module that accepts QML files
3. add C++ and QML files to the executable
4. link the libraries necessary for the executable to run
5. install the executable to the right place

Next time you need to add more QML files, add them to the existing ecm_target_qml_sources() call. C++ files that use the QML_ELEMENT keyword which we will see later in the tutorial can be added using target_sources().

Agora que já tratámos do CMake, vejamos os ficheiros onde iremos gastar a maior parte do tempo a trabalhar.

main.cpp

The file kirigami-tutorial/src/main.cpp handles the "business logic" of our application. C++ is handy because it is flexible and fast, even if it is more involved than other programming languages.

It also functions as the entrypoint to our application. The two parts of our project, the backend and the user interface, are both set up and started here.

 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

#include <QApplication>
#include <QQmlApplicationEngine>
#include <QtQml>
#include <QUrl>
#include <QQuickStyle>
#include <KLocalizedContext>
#include <KLocalizedString>
#include <KIconTheme>

int main(int argc, char *argv[])
{
    KIconTheme::initTheme();
    QApplication app(argc, argv);
    KLocalizedString::setApplicationDomain("tutorial");
    QApplication::setOrganizationName(QStringLiteral("KDE"));
    QApplication::setOrganizationDomain(QStringLiteral("kde.org"));
    QApplication::setApplicationName(QStringLiteral("Kirigami Tutorial"));
    QApplication::setDesktopFileName(QStringLiteral("org.kde.tutorial"));

    QApplication::setStyle(QStringLiteral("breeze"));
    if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE")) {
        QQuickStyle::setStyle(QStringLiteral("org.kde.desktop"));
    }

    QQmlApplicationEngine engine;

    engine.rootContext()->setContextObject(new KLocalizedContext(&engine));
    engine.loadFromModule("org.kde.tutorial", "Main");

    if (engine.rootObjects().isEmpty()) {
        return -1;
    }

    return app.exec();
}

For now, we don't need to go into too much detail regarding what our main.cpp code does, but its role will grow significantly more important once we decide to add more complex functionality to our application in the future.

If you want to get ahead, you can read more about how this main.cpp works in Figuring out main.cpp.

If you want to see a few ways on how the C++ code can be improved, like using KAboutData for translatable application metadata, be sure to check our KXmlGui tutorial.

For now, the part that interests us is this line:

engine.loadFromModule("org.kde.tutorial", "Main");

The first argument is the URI set in kirigami-tutorial/src/CMakeLists.txt, and the second argument is the name of the QML module we want to use (Main, coming from the name of our Main.qml file, which needs to start with an uppercase letter).

engine.load(QUrl(QStringLiteral("qrc:/qt/qml/org/kde/tutorial/qml/Main.qml")));

Compiling and installing the application

We are almost at the finish line. The last thing we need to do is build and run our application. Doing so will depend on which platform you are on.

Linux or FreeBSD

Compiling with kde-builder

Make sure you have followed the instructions in Using kde-builder.

Compile the necessary build dependencies with kde-builder, then compile kirigami-tutorial by running the following commands in a terminal:

kde-builder kirigami ki18n kcoreaddons breeze kiconthemes qqc2-desktop-style
kde-builder kirigami-tutorial

Compiling manually

Change directories to the project's root folder, then run the following command in a terminal:

cmake -B build/
cmake --build build/
cmake --install build/ --prefix "$HOME/.local"

The program will be installed to $HOME/.local/bin and its desktop entry to $HOME/.local/share/applications.

Windows

If you are compiling your project on Windows after having set up Craft, CMake should automatically detect the right compiler:

cmake -B build/
cmake --build build/
cmake --install build/

Depending on how you installed the compiler, you might need to specify a CMake Generator for the first step, depending on whether you are using Visual Studio (msvc) or MinGW (make) to compile your projects.

If Visual Studio, depending on the compiler you chose to install, it might be:

cmake -B build/ -G "Visual Studio 16 2019"

Or:

cmake -B build/ -G "Visual Studio 17 2022"

If MinGW:

cmake -B build/ -G "MinGW Makefiles"
cmake --build build/
cmake --install build/

In both cases, the program will be installed to C:\CraftRoot\bin.

If you ever get in doubt as to the name of the compiler that should be used in the cmake call, run:

cmake -G

It will list all available generators.

Executar a aplicação

You can then run the kirigami-hello program with:

kirigami-hello # On Linux, manually
kde-builder --run kirigami-hello # With kde-builder
kdesrc-build --run --exec kirigami-hello kirigami-tutorial # With kdesrc-build
kirigami-hello.exe # On Windows

Voilá! Agora tem a sua primeira aplicação do Kirigami a funcionar diante dos seus olhos.

To run the new QML application in mobile mode, you can use QT_QUICK_CONTROLS_MOBILE=1:

QT_QUICK_CONTROLS_MOBILE=1 kirigami-hello

If you have compiled the project manually with CMake and for some reason you'd like to uninstall the project, you can run:

cmake --build build/ --target uninstall