Introdução aos Addons do Kirigami

Os Addons do Kirigami é um conjunto adicional de componentes visuais que funcionam bem em dispositivos móveis e desktops, com garantia de compatibilidade entre plataformas. Ele utiliza Kirigami internamente para criar seus componentes.

Aqui você configurará seu novo projeto com Addons do Kirigami e conhecerá alguns componentes úteis.

Esses componentes utilizam os recursos de localização do KDE, portanto, antes de começarmos a usá-los, precisaremos configurar um pequeno projeto que utilize KLocalizedContext.

Configurando seu projeto

A estrutura inicial do projeto será semelhante a esta:

addonsexample/
├── CMakeLists.txt
├── main.cpp
└── Main.qml

mkdir -p addonsexample/contents/ui
touch addonsexample/{CMakeLists.txt,main.cpp}
touch addonsexample/Main.qml

Começamos usando um CMakeLists.txt muito padrão:

cmake_minimum_required(VERSION 3.20)

project(FormCardTutorial)

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

include(KDEInstallDirs)
include(KDECompilerSettings)
include(KDECMakeSettings)
include(ECMQmlModule)

find_package(Qt6 REQUIRED COMPONENTS
    Widgets        # For QApplication
    Quick          # For QML
    QuickControls2 # For QQuickStyle
)
find_package(KF6 REQUIRED COMPONENTS
    CoreAddons # For KAboutData
    I18n       # For KLocalizedContext
)
qt_policy(SET QTP0001 NEW)

add_executable(addonsexample)

target_sources(addonsexample PRIVATE main.cpp)

ecm_add_qml_module(addonsexample
    GENERATE_PLUGIN_SOURCE
    URI org.kde.addonsexample
)

ecm_target_qml_sources(addonsexample SOURCES
    Main.qml
    SettingsPage.qml
    JsonAboutPage.qml
)

target_link_libraries(addonsexample PRIVATE
    Qt::Widgets
    Qt::Quick
    Qt::QuickControls2
    KF6::CoreAddons
    KF6::I18n
)

install(TARGETS addonsexample DESTINATION ${KDE_INSTALL_BINDIR})

A parte interessante será o main.cpp:

#include <QtQml>
#include <QApplication>
#include <QQmlApplicationEngine>
#include <QIcon>
#include <QQuickStyle>
#include <KAboutData>
#include <KLocalizedContext>
#include <KLocalizedString>

int main(int argCount, char* argVector[])
{
    QApplication app(argCount, argVector);
    KLocalizedString::setApplicationDomain("org.kde.addonsexample");

    KAboutData aboutData(
        QStringLiteral("addonsexample"),
        i18nc("@title:window", "Addons Example"),
        QStringLiteral("1.0"),
        i18nc("@info", "This program shows how to use Kirigami Addons"),
        KAboutLicense::GPL_V3,
        QStringLiteral("(C) 2023"),
        i18nc("@info", "Optional text shown in the About"),
        QStringLiteral("https://kde.org"));

    aboutData.addAuthor(i18nc("@info:credit", "John Doe"),
                        i18nc("@info:credit", "Maintainer"));

    KAboutData::setApplicationData(aboutData);

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

    QQmlApplicationEngine engine;
    engine.rootContext()->setContextObject(new KLocalizedContext(&engine));
    engine.loadFromModule("org.kde.addonsexample", "Main");
    app.exec();
}

Se você leu nosso tutorial KXmlGui ou o último tutorial do Kirigami na página Sobre o Kirigami, muito disso lhe parecerá familiar.

Criamos nosso aplicativo e usamos o construtor do KAboutData padrão para adicionar os metadados do nosso aplicativo, nos adicionamos como autores e, em seguida, usamos o setApplicationData() para finalizar o processo. Para mais tarde, também definimos um ícone de aplicativo que vem do tema do sistema.

Em seguida, usamos um lambda em qmlRegisterSingletonType() para enviar diretamente os metadados do nosso aplicativo para o lado QML, expondo suas propriedades.

Em seguida, instanciamos nosso mecanismo QML e definimos seu contexto para usar o KLocalizedContext do KDE, usado para integrar strings traduzidas, passando o mecanismo recém-criado como parâmetro.

Simplesmente carregamos nosso arquivo QML a partir do arquivo de recursos e agora precisamos apenas cuidar do nosso arquivo QML inicial.

FormCard e FormButtonDelegate

A ideia do nosso aplicativo é criar nossa própria galeria de Addons do Kirigami, exibindo vários componentes, um por página. A página principal conterá uma lista simples de botões em um ColumnLayout, cada um abrindo uma página separada.

Inicialmente, nosso Main.qml deve ficar assim:

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

import QtQuick
import QtQuick.Layouts

import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

import org.kde.about 1.0

Kirigami.ApplicationWindow {
    id: root
    width: 600
    height: 700

    pageStack.initialPage: Kirigami.ScrollablePage {
        ColumnLayout {
            // Our code will go here
        }
    }
}

Usamos nosso prático pageStack para definir a página inicial como Kirigami.ScrollablePage.

Embora pudéssemos usar um FormLayout juntamente com componentes do QtQuick Controls para atingir nosso objetivo, aqui você será apresentado ao FormCard.

O principal objetivo de um FormCard é servir como um contêiner para outros componentes, seguindo uma cor diferente do fundo, de forma semelhante a um Kirigami.Card, mas para janelas de configuração. Você pode ter vários FormCards em sua aplicação para indicar seções diferentes. Seu FormCard também deve ser um filho direto de um ColumnLayout.

Importar org.kde.kirigamiaddons.formcard torna todos os componentes do FormCard disponíveis no seu arquivo QML.

Teremos apenas uma seção em nossa página principal, então adicionamos um único FormCard:

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

import QtQuick
import QtQuick.Layouts

import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

import org.kde.about 1.0

Kirigami.ApplicationWindow {
    id: root
    width: 600
    height: 700

    pageStack.initialPage: Kirigami.ScrollablePage {
        ColumnLayout {
            FormCard.FormCard {
                // Our buttons will go here
            }
        }
    }
}

O melhor do FormCard é que ele faz o layout automaticamente para você. Em outras palavras, apenas a ordem de seus componentes é suficiente para indicar sua posição dentro do FormCard, nenhuma propriedade anexada ao layout é necessária e você não deve usar âncoras ou posicionadores.

Podemos simplesmente adicionar alguns botões dentro do nosso FormCard:

 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

import QtQuick
import QtQuick.Layouts

import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

import org.kde.about 1.0

Kirigami.ApplicationWindow {
    id: root
    width: 600
    height: 700

    pageStack.initialPage: Kirigami.ScrollablePage {
        ColumnLayout {
            FormCard.FormCard {
                FormCard.FormButtonDelegate {
                    id: aboutKDEButton
                    icon.name: "kde"
                    text: i18n("About KDE Page")
                }
                FormCard.FormButtonDelegate {
                    id: aboutPageButton
                    icon.name: "applications-utilities"
                    text: i18n("About Addons Example")
                }
                FormCard.FormButtonDelegate {
                    id: settingsButton
                    icon.name: "settings-configure"
                    text: i18n("Single Settings Page")
                }
            }
        }
    }
}

Pronto! Os botões ainda não estão utilizáveis, mas agora estamos prontos para brincar com nossas páginas Sobre!

Então compilamos e executamos assim:

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

Para ver outras maneiras de compilar seu aplicativo (por exemplo, no Windows), consulte a página Introdução ao Kirigami.