Kirigami com C++

Crie seu primeiro aplicativo Kirigami com C++

Instalando o Kirigami

Antes de começar, precisamos instalar o Kirigami em nossa máquina. Há três maneiras de fazer isso:

Instalando o Kirigami a partir dos repositórios da sua distribuição Linux
Usando o kde-builder
Instalando o Kirigami com o Craft

Se você estiver usando uma distribuição suficientemente atualizada, como Debian Testing, a versão mais recente do Ubuntu não-LTS, Fedora, openSUSE Tumbleweed ou Arch, você pode instalar o Kirigami a partir da sua distribuição.

Se você estiver usando uma distribuição desatualizada como Debian Stable ou Ubuntu LTS, você deve usar o kde-builder para este tutorial. Ele deve usar no máximo 2 GB de armazenamento.

Instalando o Kirigami a partir dos repositórios na sua distribuição Linux

Precisamos de um compilador C++, pacotes de desenvolvimento Qt e Kirigami. Abra um aplicativo de terminal e execute um dos seguintes, dependendo da distribuição Linux que você estiver usando:

Kubuntu KDE Neon	sudo apt install build-essential cmake extra-cmake-modules libkirigami-dev libkf6i18n-dev libkf6coreaddons-dev libkf6iconthemes-dev qt6-base-dev qt6-declarative-dev libkf6qqc2desktopstyle-dev
Manjaro Arch	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 install @development-tools @development-libs 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

Mais informações sobre outras distribuições podem ser encontradas aqui.

Usando o kde-builder

Configure seu ambiente de desenvolvimento com o kde-builder. Isso fornecerá as ferramentas de desenvolvimento e as bibliotecas subjacentes necessárias, além de criar o KDE Framework do zero.

Crie uma pasta ~/kde/src/kirigami-tutorial. Nessa pasta, você colocará os arquivos de código-fonte deste tutorial.

Adicione o seguinte no final do seu ~/.config/kde-builder.yaml:

project kirigami-tutorial:
  repository: ""
  no-src: true

⏳ Com o kdesrc-build...

Clique aqui para saber como isso foi feito com kdesrc-build

Esta etapa costumava ser realizada escrevendo em ~/.config/kdesrc-buildrc com uma sintaxe diferente:

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

Instalando o Kirigami com o Craft

O KDE possui uma ferramenta personalizada para instalar facilmente a maioria de suas bibliotecas e programas: Craft. Ela pode ser usada para instalar o Kirigami no Windows, Android e macOS.

Embora o Craft também esteja disponível para Linux e FreeBSD, seu uso pretendido é apenas para AppImages e empacotamento.

Você precisará seguir as instruções de configuração do Craft. Ao final da configuração, você deverá ter executado um arquivo de configuração de ambiente (craftenv.ps1 ou craftenv.sh), que fornecerá um terminal onde você compilará seu aplicativo Kirigami.

Depois disso, você pode simplesmente executar o seguinte em um terminal:

craft kirigami kcoreaddons ki18n breeze kiconthemes qqc2-desktop-style

Isso levará um bom tempo para terminar na primeira execução. Se você fechar o terminal, poderá simplesmente executar o arquivo de configuração do ambiente novamente para compilar seu aplicativo.

Estrutura do projeto

Embora existam ferramentas que podem configurar nossos arquivos facilmente, vamos criá-los manualmente. Isso nos permitirá entender melhor as partes que comporão nosso novo aplicativo.

Primeiro, criamos a pasta do nosso projeto (você pode usar os comandos abaixo). Vamos chamá-la de kirigami-tutorial/.

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

Dentro desta pasta, criaremos uma pasta src/ e CMakeLists.txt. Geralmente, é considerada uma boa prática colocar todos os nossos principais arquivos de código C++ em uma pasta src/. Também colocamos o arquivo Main.qml nela, pois ele será executado junto com o executável.

Dica

Você pode criar rapidamente essa estrutura de arquivo com:

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

Nota

Caso você queira compilar o projeto automaticamente com o kde-builder, o nome do módulo personalizado deve ser o mesmo da pasta raiz do projeto (no nosso caso, será "kirigami-tutorial"); caso contrário, você precisará personalizar o source-dir ou o dest-dir do módulo. Assumiremos que o caminho para o seu main.cpp será ~/kde/src/kirigami-tutorial/src/main.cpp.

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 que manipularemos o frontend do nosso aplicativo.

Se você conhece um pouco de Javascript, grande parte do QML lhe parecerá familiar (embora tenha suas peculiaridades). A documentação do Qt possui um vasto material sobre esta linguagem, caso você queira experimentar algo por conta própria. Ao longo destes tutoriais, concentraremos grande parte da nossa atenção em nosso código QML, onde podemos usar o Kirigami para aproveitá-lo ao máximo.

Por enquanto, vamos nos concentrar em Main.qml. Primeiro, importamos alguns módulos importantes:

QtQuick, a biblioteca padrão usada em aplicativos QML.
QtQuick Controls, que fornece uma série de controles padrão que podemos usar para tornar nossos aplicativos interativos.
QtQuick Layouts, que fornece ferramentas para posicionar componentes na janela do aplicativo.
Kirigami, que fornece uma série de componentes adequados para a criação de aplicativos que funcionam em dispositivos de diferentes formatos e tamanhos.

Nota

Colocar os controles do QtQuick e as importações do Kirigami em namespaces separados usando a palavra-chave as é uma prática recomendada que garante que nenhum componente com o mesmo nome possa entrar em conflito. Você pode ver nomes diferentes para os controles do QtQuick por aí, como "QQC" ou "QQC2". Usaremos "Controles" neste tutorial para maior clareza.

Chegamos então ao nosso elemento base, Kirigami.ApplicationWindow, que fornece alguns recursos básicos necessários para todos os aplicativos Kirigami. Esta é a janela que conterá cada uma das nossas páginas, as principais seções da nossa interface.

Em seguida, definimos a propriedade id da janela como "root". IDs são úteis porque nos permitem referenciar exclusivamente um componente, mesmo que tenhamos vários do mesmo tipo.

Também definimos a propriedade title da janela como "Hello World". Você notará que encapsulamos nossa string "Hello World" em uma função chamada i18nc(), onde detalhamos o contexto da string, bem como a própria string.

Nota

As funções i18n() tornam seu aplicativo mais traduzível, pois retornam uma versão da string fornecida no idioma do usuário (desde que seu aplicativo tenha sido localizado para esse idioma). Enquanto um usuário em inglês pode ver o título da nossa janela como "Hello World", um usuário em espanhol veria "Hola Mundo".

i18nc() baseia-se na função i18n(), permitindo que os desenvolvedores forneçam algum contexto aos tradutores que trabalham no aplicativo. Aqui, esclarecemos que o componente de interface do usuário é o título da janela do aplicativo, portanto, incluímos a string "@title:window" antes de "Hello World". Consulte o Guia do Programador Ki18n para mais detalhes.

Em seguida, definimos a primeira página da nossa pilha de páginas. A maioria dos aplicativos Kirigami é organizada como uma pilha de páginas, cada uma contendo componentes relacionados adequados a uma tarefa específica. Por enquanto, estamos mantendo a simplicidade e nos atendo a uma única página. pageStack é uma pilha de páginas inicialmente vazia fornecida por Kirigami.ApplicationWindow, e com pageStack.initialPage:Kirigami.Page {...} definimos a primeira página apresentada ao carregar o aplicativo como uma Kirigami.Page. Esta página conterá todo o nosso conteúdo.

Por fim, incluímos em nossa página um Controls.Label que nos permite inserir texto em nossa página. Usamos anchors.centerIn:parent para centralizar nosso rótulo horizontal e verticalmente dentro do nosso elemento pai. Neste caso, o componente pai do nosso rótulo é Kirigami.Page. A última coisa que precisamos fazer é definir seu texto: text: i18n("Hello World!").

org.kde.tutorial.desktop

O objetivo principal dos arquivos de entrada de desktop é exibir seu aplicativo no inicializador de aplicativos do Linux. Outro motivo para tê-los é para ter ícones de janela no Wayland, pois eles são necessários para informar ao compositor que "esta janela combina com este ícone".

Ele deve seguir um esquema de nomenclatura DNS reverso seguido pela extensão .desktop, como 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[pt_BR]=Tutorial do Kirigami
Name[sl]=Učbenik Kirigami
Name[sv]=Kirigami-handledning
Name[tr]=Kirigami Öğreticisi
Name[uk]=Підручник з Kirigami
Name[zh_TW]=Kirigami 教學
Exec=kirigami-hello
Icon=kde
Type=Application
Terminal=false
Categories=Utility

Nota

Os ícones de janelas e da barra de tarefas funcionarão em uma sessão do Wayland somente se os arquivos de desktop dos aplicativos estiverem em ~/.local/share/applications ou /usr/share/applications. Para que os ícones funcionem neste tutorial, copie o arquivo de desktop do aplicativo para lá ou alterne para uma sessão de desenvolvimento, conforme as instruções no tutorial do kde-builder. Alguns aplicativos do KDE podem ter ícones funcionais se já estiverem instalados no sistema.

CMakeLists.txt

Os arquivos CMakeLists.txt são necessários para usar o sistema de compilação escolhido pelo KDE, CMake. Nosso arquivo kirigami-tutorial/CMakeLists.txt especificará algumas das características do nosso aplicativo. Ele também inclui algumas das dependências necessárias para compilar nosso projeto.

 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 arquivo CMakeLists.txt define como construir seus projetos. A maior parte do conteúdo aqui serve apenas para inicializar seu projeto. Você pode ler uma explicação detalhada, linha por linha, sobre o que este arquivo CMakeLists faz aqui.

O mais importante a ter em mente é que as dependências de compilação em C++ dos frameworks Qt e KDE são gerenciadas com find_package() e as dependências de tempo de execução em QML são gerenciadas com ecm_find_qml_module(). Você terá que modificar essas linhas e incluir quaisquer componentes adicionais que decidir usar durante o desenvolvimento do seu aplicativo.

A linha com add_subdirectory(src) aponta o CMake para o diretório kirigami-tutorial/src/, onde nosso código-fonte está localizado.

A linha com install() informa ao CMake onde instalar o arquivo de desktop.

Vamos nos aprofundar no arquivo kirigami-tutorial/src/CMakeLists.txt.

 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})

Este arquivo consiste de cinco etapas:

crie um executável
transforme o executável em um módulo QML que aceita arquivos QML
adicione arquivos C++ e QML ao executável
vincule as bibliotecas necessárias para a execução do executável
instale o executável no lugar certo

Da próxima vez que precisar adicionar mais arquivos QML, adicione-os à chamada ecm_target_qml_sources() existente. Arquivos C++ que usam a palavra-chave QML_ELEMENT, que veremos mais adiante neste tutorial, podem ser adicionados usando target_sources().

Agora que cuidamos do CMake, vamos dar uma olhada nos arquivos com os quais passaremos a maior parte do nosso tempo trabalhando.

main.cpp

O arquivo kirigami-tutorial/src/main.cpp gerencia a "lógica de negócios" da nossa aplicação. C++ é útil porque é flexível e rápido, mesmo sendo mais complexo do que outras linguagens de programação.

Ele também funciona como ponto de entrada para o nosso aplicativo. As duas partes do nosso projeto, o backend e a interface do usuário, são 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
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();
}

Por enquanto, não precisamos entrar em muitos detalhes sobre o que nosso código main.cpp faz, mas seu papel se tornará significativamente mais importante quando decidirmos adicionar funcionalidades mais complexas ao nosso aplicativo no futuro.

Tema no Windows

Clique aqui para ler mais

O aplicativo precisa definir o tema de ícones, o QStyle e o estilo dos Controles QtQuick como Breeze para ser exibido no Windows. Para saber mais sobre isso, consulte Descobrindo o main.cpp.

Se quiser se adiantar, você pode ler mais sobre como esse main.cpp funciona em Descobrindo o main.cpp.

Se você quiser ver algumas maneiras de melhorar o código C++, como usar KAboutData para metadados traduzíveis de aplicativos, não deixe de conferir nosso tutorial KXmlGui.

Por enquanto, a parte que nos interessa é esta linha:

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

O primeiro argumento é o URI definido em kirigami-tutorial/src/CMakeLists.txt, e o segundo argumento é o nome do módulo QML que queremos usar (Main, vindo do nome do nosso arquivo Main.qml, que precisa começar com uma letra maiúscula).

O método antigo

Você pode encontrar esta maneira alternativa de carregar arquivos QML em código real!

O método antigo de carregar arquivos QML tinha algumas desvantagens e, após o Qt6, tornou-se excessivamente prolixo:

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

Este URI de recurso Qt acima segue o padrão <prefixo_do_recurso><URI_de_importação><diretório_QML_opcional><arquivo>. Neste caso:

prefixo do recurso = default / no Qt5, /qt/qml no Qt6
URI de importação = /org/kde/tutorial, que corresponde à URI org.kde.tutorial
diretório QML opcional = /qml, necessário se arquivos QML estão armazenados em um diretório chamado qml/
arquivo = o arquivo QML

Compilando e instalando o aplicativo

Estamos quase na linha de chegada. A última coisa que precisamos fazer é compilar e executar nossa aplicação. Isso dependerá da plataforma em que você estiver.

Linux ou FreeBSD

Compilando com o kde-builder

Certifique-se de ter seguido as instruções em Usando o kde-builder.

Compile as dependências de compilação necessárias com o kde-builder e, em seguida, compile o kirigami-tutorial executando os seguintes comandos em um terminal:

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

Compilando manualmente

Altere os diretórios para a pasta raiz do projeto e execute o seguinte comando em um terminal:

cmake -B build/ --install-prefix ~/.local
cmake --build build/
cmake --install build/

O programa será instalado em ~/.local/bin e sua entrada de desktop em ~/.local/share/applications.

Windows

Se você estiver compilando seu projeto no Windows após configurar o Craft, o CMake deverá detectar automaticamente o compilador correto:

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

Dependendo de como você instalou o compilador, pode ser necessário especificar um Gerador CMake para a primeira etapa, dependendo se você está usando o Visual Studio (msvc) ou o MinGW (make) para compilar seus projetos.

Se for o Visual Studio, dependendo do compilador que você escolher instalar, pode ser:

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

Ou:

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

Se for o MinGW:

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

Em ambos os casos, o programa será instalado em C:\CraftRoot\bin.

Caso você tenha alguma dúvida sobre o nome do compilador que deve ser usado na chamada cmake, execute:

cmake -G

Isto listará todos os geradores disponíveis.

Executando o aplicativo

Você pode então executar o programa kirigami-hello com:

kirigami-hello # No Linux, manualmente
kde-builder --run kirigami-hello # Com o kde-builder
kdesrc-build --run --exec kirigami-hello kirigami-tutorial # Com o kdesrc-build
kirigami-hello.exe # No Windows

Pronto! Agora você verá seu primeiro aplicativo Kirigami aparecer diante dos seus próprios olhos.

Captura de tela do aplicativo Kirigami gerado

Para executar o novo aplicativo QML no modo para dispositivo móvel, você pode usar QT_QUICK_CONTROLS_MOBILE=1:

QT_QUICK_CONTROLS_MOBILE=1 kirigami-hello

Se você compilou o projeto manualmente com o CMake e, por algum motivo, deseja desinstalar o projeto, você pode executar:

cmake --build build/ --target uninstall

Nota

Da próxima vez que quiser criar os arquivos e pastas necessários, você pode usar o KAppTemplate ou o KDevelop para gerar automaticamente um projeto adequado para começar. Eles estão disponíveis nos repositórios de cada distribuição principal. Esses aplicativos também gerarão arquivos contendo metadados do AppStream e um arquivo .desktop que contém informações sobre como o aplicativo deve ser exibido em um lançador de aplicativos Linux.

Graças à magia do CMakeLists, você também pode usar IDEs como o KDevelop ou QtCreator para desenvolver este aplicativo em um ambiente confortável com o mínimo de esforço.

Kirigami com o Python