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
• Building Kirigami with kdesrc-build
• 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:

KubuntuKDE Neon	sudo apt install build-essential cmake extra-cmake-modules qtbase5-dev qtdeclarative5-dev qtquickcontrols2-5-dev kirigami2-dev libkf5i18n-dev gettext libkf5coreaddons-dev qml-module-org-kde-qqc2desktopstyle
ManjaroArch	sudo pacman -S base-devel extra-cmake-modules cmake qt5-base qt5-declarative qt5-quickcontrols2 kirigami2 ki18n kcoreaddons breeze qqc2-desktop-style
OpenSUSE	sudo zypper install --type pattern devel_C_C++ sudo zypper install cmake extra-cmake-modules libQt5Core-devel libqt5-qtdeclarative-devel libQt5QuickControls2-devel kirigami2-devel ki18n-devel kcoreaddons-devel qqc2-desktop-style
Fedora	sudo dnf groupinstall "Development Tools" "Development Libraries" sudo dnf install cmake extra-cmake-modules qt5-qtbase-devel qt5-qtdeclarative-devel qt5-qtquickcontrols2-devel kf5-kirigami2-devel kf5-ki18n-devel kf5-kcoreaddons-devel qqc2-desktop-style

Further information for other distributions can be found here.

If you wish to build Kirigami with Qt6, this is currently not possible with only distribution packages on Linux. You will need to resort to kdesrc-build instead.

Building Kirigami with kdesrc-build

KDE has a custom tool to easily build all of its libraries and programs: kdesrc-build. It can be used to build Kirigami on Linux and FreeBSD.

For this tutorial, you will need to follow the setup instructions for kdesrc-build but using a ~/kde5 directory instead, then copy the sample KF5 file to your home:

cp ~/kde5/src/kdesrc-build/kdesrc-buildrc-kf5-sample ~/.config/kdesrc-buildrc

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

kdesrc-build kirigami kcoreaddons ki18n breeze plasma-integration qqc2-desktop-style
source ~/kde5/build/kirigami/prefix.sh

And then you may compile your Kirigami projects on the same terminal shell you used to source the prefix file. If you close your terminal, you can simply source the file again to compile your app.

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.

Em primeiro lugar, criamos a pasta do nosso projecto. Iremos chamar ao nosso "helloworld".

helloworld/
├── CMakeLists.txt
└── src/
    ├── CMakeLists.txt
    ├── main.cpp
    ├── resources.qrc
    └── contents/
        └── ui/
            └── main.qml

Dentro desta pasta iremos criar uma pasta src/ e um ficheiro CMakeLists.txt. É uma boa prática generalizada colocar todos os nossos ficheiros de código numa pasta src/. A nossa pasta src/ por sua vez irá conter uma pasta chamada contents/, que por sua vez irá conter uma pasta chamada ui/. Aqui é onde serão criados os nossos ficheiros em QML.

mkdir -p helloworld/src/contents/ui
touch helloworld/CMakeLists.txt
touch helloworld/src/{CMakeLists.txt,main.cpp,resources.qrc}
touch helloworld/src/contents/ui/main.qml

Esta é uma convenção do KDE, mas nem todos os projectos do KDE usam esta estrutura. Está à vontade para configurar as coisas de forma diferente, mas terá de ter isso em conta quando criar os seus ficheiros CMakeLists.txt e resources.qrc.

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

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

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

    // 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.

Se souber alguma coisa de Javascript, então muito do QML parecer-lhe-á familiar (ainda que tenha as suas particularidades). A documentação do Qt tem uma quantidade extensa de material sobre esta linguagem se se sentir à vontade para experimentar algo você mesmo. Ao longo destes tutoriais, focar-nos-emos a nível de atenção no nosso código em QML, onde poderemos usar o Kirigami para tirar o máximo partido.

Por agora, vamo-nos focar no main.qml. Primeiro iremos importar um conjunto de módulos importantes:

• 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!").

main.cpp

O main.cpp lida com a "lógica de negócio" da nossa aplicação. O C++ é útil porque é flexível e rápido, mesmo que esteja mais envolvido que outras linguagens de programação.

O main.cpp também é o ponto de entrada da nossa aplicação. As duas partes do nosso projecto, a infra-estrutura e a interface de utilizador, são ambas configuradas e iniciadas aqui.

 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

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

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    KLocalizedString::setApplicationDomain("helloworld");
    QCoreApplication::setOrganizationName(QStringLiteral("KDE"));
    QCoreApplication::setOrganizationDomain(QStringLiteral("kde.org"));
    QCoreApplication::setApplicationName(QStringLiteral("Hello World"));

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

    QQmlApplicationEngine engine;

    engine.rootContext()->setContextObject(new KLocalizedContext(&engine));
    engine.load(QUrl(QStringLiteral("qrc:/main.qml")));

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

    return app.exec();
}

Por agora, não precisamos de entrar em grandes detalhes em relação ao que faz o código no nosso ficheiro main.cpp, mas o seu papel ficará cada vez mais importante assim que optarmos por adicionar funcionalidades mais complexas à nossa aplicação no futuro. Se quiser evoluir, poderá ler mais sobre o funcionamento deste main.cpp nesta página.

resources.qrc

O resources.qrc é um ficheiro de recursos do Qt. Ele contém a lista de todos os ficheiros QML, assim como de outros ficheiros (como os ícones personalizados) que serão incluídos no executável.

1
2
3
4
5

<RCC>
    <qresource prefix="/">
        <file alias="main.qml">contents/ui/main.qml</file>
    </qresource>
</RCC>

Repare na linha <file alias="main.qml">contents/ui/main.qml</file>. A mesma refere quais os ficheiros QML que serão incluídos no processo de compilação. No nosso caso, só iremos usar o main.qml, mas se quisermos adicionar mais ficheiros QML ao nosso código, teríamos de confirmar que os mesmos seriam incluídos no ficheiro resources.qrc, adicionando outra linha como esta.

Este ficheiro de recursos deixa-nos usar a localização "qrc:" + "/main.qml" no nosso main.cpp, em vez de ser necessário definir toda a localização "contents/ui/main.qml".

CMakeLists.txt

Os ficheiros CMakeLists.txt são necessários para usar o sistema de compilação escolhido pelo KDE, o CMake. O ficheiro CMakeLists.txt na nossa pasta de topo vai definir algumas das características da nossa aplicação. Também inclui algumas das dependências que necessitamos para a compilar.

 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

cmake_minimum_required(VERSION 3.16)
project(helloworld)

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

include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)

find_package(Qt${QT_MAJOR_VERSION} REQUIRED NO_MODULE COMPONENTS
    Core
    Quick
    Test
    Gui
    QuickControls2
    Widgets
)

find_package(KF${QT_MAJOR_VERSION} REQUIRED COMPONENTS
    Kirigami2
    I18n
    CoreAddons
)

add_subdirectory(src)

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.

O ponto mais importante a ter em mente é que as dependências do Qt e das Plataformas do KDE são geridas pelo find_package(). Terá de modificar essas linhas e incluir os componentes adicionais que tiver decidido usar durante o desenvolvimento da sua aplicação.

A linha final, o add_subdirectory(src), aponta o CMake para a pasta helloworld/src/, onde se encontra o nosso código-fonte. Vamos percorrer o ficheiro helloworld/src/CMakeLists.txt aqui.

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

add_executable(helloworld)

target_sources(helloworld PRIVATE
    main.cpp
    resources.qrc
)

target_link_libraries(helloworld
    Qt${QT_MAJOR_VERSION}::Quick
    Qt${QT_MAJOR_VERSION}::Qml
    Qt${QT_MAJOR_VERSION}::Gui
    Qt${QT_MAJOR_VERSION}::QuickControls2
    Qt${QT_MAJOR_VERSION}::Widgets
    KF${QT_MAJOR_VERSION}::I18n
)

install(TARGETS helloworld ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

Este é um bocado mais curto! Vamos perceber o que faz:

• O add_executable() cria um executável a partir dos ficheiros de código indicados.
• O target_link_libraries() liga de forma dinâmica as bibliotecas usadas no nosso código ao nosso executável.

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

Compilar e executar a aplicação

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.

If you are running your project on Linux, you will need to specify the place where the program will be installed. To do that, we need to change directories to our helloworld/ folder in our terminal application of choice and run the following commands:

cmake -B build/ -DCMAKE_INSTALL_PREFIX="~/kde5/usr"
cmake --build build/
cmake --install build/

The program will be installed to ~/kde5/usr/bin.

If you are compiling your project with Craft on Windows, you might need to specify a CMake Generator for the first step, depending on whether you are using Visual Studio 2019 (msvc) or MinGW (make) to compile your projects.

If Visual Studio:

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

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.

You can then run the helloworld program with:

helloworld # On Linux
helloworld.exe # On Windows

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