Configuração e introdução

Preparar a criação da nossa primeira aplicação do Kirigami

Instalar os pacotes necessários

Antes e começar, é preciso instalar algumas coisas. Precisamos de um compilador de C++, pacotes de desenvolvimento do Qt e o Kirigami.

No Ubuntu, Debian e Neon, podemos instalá-los com o APT:

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 libkf5coreaddons-dev qml-module-qtquick-layouts

Nas distribuições baseadas no Arch (como o Manjaro) podemos usar o Pacman:

sudo pacman -Syu base-devel extra-cmake-modules cmake kirigami2 kde-sdk-meta gettext

Para o Fedora, usamos o DNF:

sudo dnf groupinstall "Development Tools" "Development Libraries"
sudo dnf install extra-cmake-modules cmake qt5-qtbase-devel qt5-qtdeclarative-devel qt5-qtquickcontrols2-devel kf5-kirigami2 kf5-kirigami2-devel kf5-ki18n-devel kf5-kcoreaddons-devel gettext

Para mais informações sobre as outras distribuições, poderá consultá-las aqui.

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
    ├── contents
    │   └── ui
    │       └── main.qml
    ├── main.cpp
    └── resources.qrc

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.

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
// Includes relevant modules used by the QML
import QtQuick 2.6
import QtQuick.Controls 2.0 as Controls
import QtQuick.Layouts 1.2
import org.kde.kirigami 2.13 as Kirigami

// Base element, provides basic features needed for all kirigami applications
Kirigami.ApplicationWindow {
    // ID provides unique identifier to reference this element
    id: root

    // Window title
    // i18nc is useful for adding context for translators, also lets strings be changed for different languages
    title: i18nc("@title:window", "Hello World")

    // Initial page to be loaded on app load
    pageStack.initialPage: Kirigami.Page {

        Controls.Label {
            // Center label horizontally and vertically within parent element
            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 do Kirigami.ApplicationWindow 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.

Nota

As funções i18n() tornam a sua aplicação mais fácil de ser traduzida, dado que devolvem uma versão do texto indicado na língua do utilizador (desde que a sua aplicação tenha sido traduzida para essa língua). Enquanto um utilizador inglês poderá ver o nosso título da janela como 'Hello World', um utilizador português iria ver 'Olá Mundo'.

O i18nc() baseia-se na função i18n(), permitindo aos programadores fornecer algum contexto aos tradutores que estão a tratar da aplicação; é por isso que incluímos o texto "@title" antes de "Hello World".

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. 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
#include <QApplication>
#include <QQmlApplicationEngine>
#include <QtQml>
#include <QUrl>
#include <KLocalizedContext>
#include <KLocalizedString>

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

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

Poderá saber mais sobre os detalhes específicos de como funciona o sistema de recursos do Qt na documentação do Qt.

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
cmake_minimum_required(VERSION 3.16)
project(helloworld)

set(KF_MIN_VERSION "5.68.0")
set(QT_MIN_VERSION "5.12.0")

find_package(ECM ${KF_MIN_VERSION} REQUIRED NO_MODULE)

set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

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

find_package(Qt5 ${QT_MIN_VERSION} REQUIRED NO_MODULE COMPONENTS Core Quick Test Gui QuickControls2 Widgets)
find_package(KF5 ${KF_MIN_VERSION} REQUIRED COMPONENTS Kirigami2 I18n CoreAddons)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

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 'src', onde se encontra o nosso código-fonte. Vamos percorrer o ficheiro CMakeLists.txt aqui.

1
2
add_executable(helloworld main.cpp resources.qrc)
target_link_libraries(helloworld Qt5::Quick Qt5::Qml Qt5::Gui Qt5::QuickControls2 Qt5::Widgets KF5::Kirigami2 KF5::I18n)

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 as bibliotecas usadas no nosso código ao nosso executável.

Nota

Lembre-se que estas bibliotecas deve corresponder aos componentes que incluímos no nosso ficheiro CMakeLists.txt anterior - caso contrário, estes componentes não serão incluídos e a aplicação não irá compilar.

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

Estamos quase na recta final. A última coisa que precisamos de fazer é compilar a nossa aplicação. Para o fazer, precisamos de entrar na nossa pasta 'helloworld' na aplicação de terminal e executar o seguinte comando:

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

E lance-o com:

./build/bin/<project_name>

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

Nota

Da próxima vez que quiser criar os ficheiros e pastas necessários, poderá usar o KAppTemplate ou o KDevelop para gerar automaticamente um projecto adequado para servir de ponto de partida. Os mesmos estão disponíveis nos repositórios das várias distribuições principais. Estas aplicações irão também gerar ficheiros que contêm meta-dados de AppStream e um ficheiro .desktop que contém informações sobre como a aplicação deverá ser apresentada num lançador de aplicações em Linux.

Graças à magia do CMakeLists, também poderá usar os IDE's como o KDevelop ou o QtCreator para desenvolver esta aplicação dentro de um ambiente confortável e com o mínimo esforço.

Explicação das Páginas