Jednotka Kirigami

Inštalácia Kirigami

Pred začiatkom budeme musieť nainštalovať Kirigami a Rust na náš počítač.

ManjaroArch	sudo pacman -S cargo cmake extra-cmake-modules kirigami breeze qqc2-desktop-style
OpenSUSE	sudo zypper install cargo cmake kf6-extra-cmake-modules kf6-kirigami-devel qt6-quickcontrols2-devel kf6-qqc2-desktop-style
Fedora	sudo dnf install cargo cmake extra-cmake-modules kf6-kirigami2-devel kf6-qqc2-desktop-style

Ďalšie informácie pre ostatné distribúcie nájdete v časti Inštalácia závislostí na zostavenie.

Štruktúra projektu

Najprv vytvoríme priečinok nášho projektu (môžete použiť nižšie uvedené príkazy). Náš budeme volať kirigami_rust/. Toto bude štruktúra projektu:

kirigami_rust/
├── CMakeLists.txt
├── Cargo.toml
├── build.rs
├── org.kde.kirigami_rust.desktop
└── src/
    ├── main.rs
    └── qml/
        └── Main.qml

Tento projekt bude na volanie Cargo používať CMake, ktoré zase zostaví projekt.

Projekt sa bude volať kirigami_rust a vygeneruje spustiteľný súbor nazývaný kirigami_hello.

org.kde.kirigami_rust.desktop

Primárnym účelom súborov Desktop Entry je zobraziť vašu aplikáciu v spúšťači aplikácií v Linuxe. Ďalším dôvodom mať ich je mať ikony okien na Waylande, pretože sú potrebné na to, aby povedali kompozitoru "toto okno patrí k tejto ikone".

Musí nasledovať schému pomenovania s obráteným DNS s príponou .desktop, ako napríklad org.kde.kirigami_rust.desktop:

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

[Desktop Entry]
Name=Kirigami Tutorial in Rust
Name[ca]=Guia d'aprenentatge del Kirigami en Rust
Name[es]=Tutorial de Kirigami en Rust
Name[fr]=Tutoriel pour Kirigami en Rust
Name[it]=Esercitazione di Kirigami in Rust
Name[nl]=Kirigami handleiding in Rust
Name[pt_BR]=Tutorial do Kirigami em Rust
Name[ro]=Îndrumar Kirigami în Rust
Name[sk]=Tutoriál Kirigami v Ruste
Name[sl]=Učbenik Kirigami v Rustu
Name[sv]=Kirigami-handledning i Rust
Name[tr]=Rust ile Kirigami Öğreticisi
Name[uk]=Підручник з Kirigami для Rust
Exec=kirigami_hello
Icon=kde
Type=Application
Terminal=false
Categories=Utility

CMakeLists

Súbor CMakeLists.txt bude použitý na spustenie Cargo a na inštaláciu potrebných súborov spolu s našou aplikáciou. Tiež poskytuje určité vylepšenia kvality života, ako napríklad zabezpečenie, že Kirigami je nainštalované počas kompilácie a signalizovanie distribúciám Linux, aby nainštalovali potrebné závislosti s aplikáciou.

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

cmake_minimum_required(VERSION 3.28)

project(kirigami_rust)

find_package(ECM 6.0 REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})
include(KDEInstallDirs)
include(ECMUninstallTarget)

include(ECMFindQmlModule)
ecm_find_qmlmodule(org.kde.kirigami REQUIRED)
find_package(KF6 REQUIRED COMPONENTS QQC2DesktopStyle)

add_custom_target(kirigami_rust
    ALL
    COMMAND cargo build --target-dir ${CMAKE_CURRENT_BINARY_DIR}
)

install(
    PROGRAMS ${CMAKE_CURRENT_BINARY_DIR}/debug/kirigami_hello
    DESTINATION ${KDE_INSTALL_BINDIR}
)

install(FILES org.kde.kirigami_rust.desktop DESTINATION ${KDE_INSTALL_APPDIR})

Prvá vec, ktorú robíme, je pridanie Extra CMake Modules (ECM) od KDE do nášho projektu, aby sme mohli použiť ecm_find_qml_module na kontrolu, či je Kirigami nainštalované pri pokuse o zostavenie aplikácie, a ak nie, okamžite zlyhať. Ďalšou užitočnou funkciou ECM je ECMUninstallTarget, ktorý umožňuje jednoducho odinštalovať aplikáciu pomocou CMake, ak je to žiaduce.

Tiež používame find_package() z CMake, aby sme sa uistili, že máme qqc2-desktop-style, QML štýl KDE pre pracovnú plochu. Toto je jeden z dvoch dôvodov, prečo v tomto tutoriáli používame CMake.

Typicky sa projekty Rust zostavujú pomocou Cargo a tu to nebude iné. Vytvoríme cieľ, ktorý jednoducho spustí Cargo pri spustení, a označíme ho ALL, aby sa zostavoval predvolene. Cargo zostaví spustiteľný súbor vnútri binárneho adresára CMake (typicky build/).

Viac informácií o CMake, cieľoch a binárnom adresári nájdete v časti Manuálne zostavenie softvéru KDE.

Potom jednoducho nainštalujeme spustiteľný súbor kirigami_rust vygenerovaný Cargo v binárnom adresári a nainštalujeme ho do BINDIR, čo je zvyčajne /usr/bin, /usr/local/bin alebo ~/.local/bin. Tiež nainštalujeme potrebný súbor desktop do APPDIR, čo je zvyčajne /usr/share/applications alebo ~/.local/share/applications. Toto je druhý dôvod, prečo v tomto tutoriáli používame CMake.

Viac informácií o tom, kam sa inštaluje softvér KDE, nájdete v časti Manuálne zostavenie softvéru KDE: Krok inštalácie.

Teraz, keď sme sa postarali o CMake, pozrime sa na súbory, s ktorými budeme tráviť väčšinu nášho času.

Cargo.toml

Ďalej máme veľmi jednoduchý Cargo.toml:

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

[package]
name = "kirigami_hello"
version = "0.1.0"
authors = [ "Konqi the Konqueror <konqi@kde.org>" ]
edition = "2021"
license = "GPLv3"

[dependencies]
cxx = "1.0.95"
cxx-qt = "0.7"
cxx-qt-lib = { version="0.7", features = ["qt_full"] }
cxx-qt-lib-extras = "0.7"

[build-dependencies]
# The link_qt_object_files feature is required for statically linking Qt 6.
cxx-qt-build = { version = "0.7", features = [ "link_qt_object_files" ] }

Pozostáva z metadát projektu a zoznamu závislostí, ktoré bude Cargo automaticky sťahovať, konkrétne cxx a cxx-qt, ktoré sú potrebné na spúšťanie aplikácií Qt napísaných v Rust.

build.rs

Kde by ste v C++ typicky registrovali QML prvky pomocou QML_ELEMENT a ecm_add_qml_module pomocou deklaratívnej registrácie, v Rust to budete musieť deklarovať v súbore zostavovacieho skriptu build.rs:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

use cxx_qt_build::{CxxQtBuilder, QmlModule};

fn main() {
    CxxQtBuilder::new()
        .qml_module(QmlModule {
            uri: "org.kde.tutorial",
            qml_files: &["src/qml/Main.qml"],
            rust_files: &["src/main.rs"],
            ..Default::default()
        })
        .build();
}

Toto je potrebné na sprístupnenie QML súboru vo vstupnom bode našej aplikácie, main.rs.

src/main.rs

Súbor kirigami_rust/src/main.rs inicializuje projekt a potom načíta QML súbor, ktorý bude tvoriť používateľské rozhranie aplikácie.

 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

#[cxx_qt::bridge]
mod ffi {
    extern "RustQt" {
        #[qobject]
        type DummyQObject = super::DummyRustStruct;
    }
}

#[derive(Default)]
pub struct DummyRustStruct;

use cxx_qt_lib::{QGuiApplication, QQmlApplicationEngine, QQuickStyle, QString, QUrl};
use cxx_qt_lib_extras::QApplication;
use std::env;

fn main() {
    let mut app = QApplication::new();
    let mut engine = QQmlApplicationEngine::new();

    // To associate the executable to the installed desktop file
    QGuiApplication::set_desktop_file_name(&QString::from("org.kde.kirigami_rust"));
    // To ensure the style is set correctly
    let style = env::var("QT_QUICK_CONTROLS_STYLE");
    if style.is_err() {
        QQuickStyle::set_style(&QString::from("org.kde.desktop"));
    }

    if let Some(engine) = engine.as_mut() {
        engine.load(&QUrl::from("qrc:/qt/qml/org/kde/tutorial/src/qml/Main.qml"));
    }

    if let Some(app) = app.as_mut() {
        app.exec();
    }
}

Prvá časť, ktorá je označená Rust makrom #[cxx_qt::bridge], jednoducho vytvorí figurantový QObject z figurantovej Rust štruktúry. Toto je potrebné len na doplnenie použitia QmlModule v predchádzajúcom zostavovacom skripte build.rs. Toto bude mať väčšiu úlohu v budúcom tutoriáli, ktorý učí, ako vystaviť Rust kód do QML, ale zatiaľ to môžete ignorovať.

Potom začína dôležitá časť:

Riadky 12-13 importujú potrebné Qt knižnice vystavené cez cxx-qt.

Najprv vytvoríme novú inštanciu QApplication, potom vykonáme niekoľko integrácií v riadkoch 20-26.

Potom prichádza časť, ktorá skutočne vytvára okno aplikácie:

28
29
30

    if let Some(engine) = engine.as_mut() {
        engine.load(&QUrl::from("qrc:/qt/qml/org/kde/tutorial/src/qml/Main.qml"));
    }

Dlhé URL qrc:/qt/qml/org/kde/tutorial/src/qml/Main.qml zodpovedá súboru Main.qml podľa systému zdrojov Qt a nasleduje túto schému: <resource_prefix><import_URI><QML_dir><file>.

Inými slovami: predvolený prefix zdrojov qrc:/qt/qml/ + import URI org/kde/tutorial (nastavené v build.rs, oddelené lomkami namiesto bodiek) + QML adresár src/qml/ + QML súbor Main.qml.

src/qml/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

// 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
    title: "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: "Hello World!"
        }
    }
}

Tu budeme spracovávať frontend našej aplikácie.

Ak poznáte trochu Javascript, potom sa vám veľa z QML bude zdať povedomé (aj keď má svoje zvláštnosti). Dokumentácia Qt má rozsiahle množstvo materiálu o tomto jazyku, ak chcete skúsiť niečo na vlastnú päsť. V priebehu týchto tutoriálov sa zameriame veľkú časť pozornosti na náš QML kód, kde môžeme využiť Kirigami na maximum.

Zatiaľ sa zameriame na Main.qml. Najprv importujeme niekoľko dôležitých modulov:

• QtQuick, štandardná knižnica používaná v aplikáciách QML.
• QtQuick Controls, ktorá poskytuje množstvo štandardných ovládacích prvkov, ktoré môžeme použiť na interaktívnosť našich aplikácií.
• QtQuick Layouts, ktorá poskytuje nástroje na umiestňovanie komponentov v rámci okna aplikácie.
• Kirigami, ktorá poskytuje množstvo komponentov vhodných na vytváranie aplikácií fungujúcich na zariadeniach rôznych tvarov a veľkostí.

Potom sa dostávame k nášmu základnému prvku, Kirigami.ApplicationWindow, ktorý poskytuje niektoré základné funkcie potrebné pre všetky aplikácie Kirigami. Toto je okno, ktoré bude obsahovať každú z našich stránok, hlavné sekcie nášho UI.

Potom nastavíme vlastnosť id okna na "root". ID sú užitočné, pretože nám umožňujú jednoznačne odkazovať na komponent, aj keď máme niekoľko rovnakého typu.

Tiež nastavíme vlastnosť title okna na "Hello World".

Potom nastavíme prvú stránku nášho zásobníka stránok. Väčšina aplikácií Kirigami je organizovaná ako zásobník stránok, pričom každá stránka obsahuje súvisiace komponenty vhodné pre konkrétnu úlohu. Zatiaľ to udržujeme jednoduché a zostávame pri jednej stránke. pageStack je pôvodne prázdny zásobník stránok poskytovaný Kirigami.ApplicationWindow a pomocou pageStack.initialPage: Kirigami.Page {...} nastavíme prvú stránku prezentovanú pri načítaní aplikácie na Kirigami.Page. Táto stránka bude obsahovať všetok náš obsah.

Nakoniec zahrnieme na našu stránku Controls.Label, ktorý nám umožní umiestniť text na stránku. Používame anchors.centerIn: parent na vycentrovanie nášho popisku horizontálne a vertikálne v rámci rodičovského prvku. V tomto prípade je rodičovským komponentom nášho popisku Kirigami.Page. Posledná vec, ktorú musíme urobiť, je nastaviť jeho text: text: "Hello World!".

Zostavenie a inštalácia aplikácie

Vygenerovaný spustiteľný súbor kirigami_hello by ste mali nájsť pod build/debug/kirigami_hello a môžete ho spustiť priamo alebo pomocou cargo run, ale bude mu chýbať ikona okna. Na vyriešenie tohto problému aplikáciu najprv nainštalujeme.

Spustite nasledovné:

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

Prvým príkazom CMake vyhľadá Kirigami a qqc2-desktop-style.

Druhým príkazom CMake zostaví cieľ kirigami_rust, ktorý jednoducho zavolá cargo build --target-dir build/. Dokončenie tohto kroku bude chvíľu trvať, ale nabudúce, keď zopakujete druhý príkaz CMake, bude to rýchlejšie alebo nebudete musieť kompilovať vôbec.

V treťom kroku CMake nainštaluje spustiteľný súbor kirigami_hello pod ~/.local/bin/kirigami_hello a súbor desktop pod ~/.local/share/applications a vo vašom menu sa objaví nová položka s názvom "Kirigami Tutorial in Rust".

Otvorte položku menu a voilà! Teraz uvidíte vašu úplne prvú aplikáciu Kirigami priamo pred vašimi očami.

Na spustenie novej QML aplikácie v mobilnom režime môžete použiť QT_QUICK_CONTROLS_MOBILE=1:

QT_QUICK_CONTROLS_MOBILE=1 kirigami_hello

Ak ste skompilovali projekt manuálne pomocou CMake a z nejakého dôvodu by ste chceli projekt odinštalovať, môžete spustiť:

cmake --build build/ --target uninstall