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.

Kubuntu KDE Neon	sudo apt install build-essential cmake extra-cmake-modules qtbase5-dev qtdeclarative5-dev qtquickcontrols2-5-dev kirigami2-dev libkf5i18n-dev gettext libkf5coreaddons-dev
Manjaro Arch	sudo pacman -S base-devel extra-cmake-modules cmake qt5-base qt5-declarative qt5-quickcontrols2 kirigami2 ki18n kcoreaddons breeze
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-breeze-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-breeze-style

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

Sugestão

Pode criar rapidamente esta estrutura de ficheiros com:

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

Em alternativa poderá querer usar o modelo-padrão do Kirigami que é fornecido pelo KDevelop, o IDE principal do KDE para programar em C++ e QML. O KAppTemplate também está disponível se só precisar de um modelo rápido para começar a programar no seu IDE ou editor de texto favoritos.

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.

Nota

Colocar as importações do QtQuick Controls e do Kirigami em espaços de nomes separados com a palavra-chave as é uma boa prática que garante que os componentes que tenham o mesmo nome não entrem em conflito. Poderá ver diferentes nomes para os controlos do QtQuick por aí, como por exemplo "QQC" ou "QQC2". Iremos usar "Controls" neste tutorial por questões de clareza.

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.

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.window" antes de "Hello World". Veja o Manual do Programador do Ki18n para obter mais detalhes.

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

int main(int argc, char *argv[])
{
    QCoreApplication::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 é 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
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 helloworld/src/, onde se encontra o nosso código-fonte. Vamos percorrer o ficheiro helloworld/src/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 de forma dinâmica 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 os seguintes comandos:

cmake -B build/
cmake --build build/

E lance-o com:

./build/bin/helloworld

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