Налаштовування і перші кроки

Готуємося до створення нашої першої програми Kirigami

Встановлення Kirigami

Перш ніж почати, нам потрібно встановити Kirigami у нашій машині. Існує три способи зробити це:

Встановлення Kirigami зі сховищ пакунків у вашому дистрибутиві Linux
Користування kde-builder
Встановлення Kirigami за допомогою Craft

Встановлення Kirigami зі сховищ пакунків у вашому дистрибутиві Linux

Нам знадобиться компілятор C++, пакунки для розробки Qt та Kirigami. Відкрийте програму-термінал і віддайте одну з вказаних нижче команд, залежно від дистрибутива Linux, яким ви користуєтеся:

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 groupinstall "Development Tools" "Development Libraries"
sudo dnf install 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

Подальші відомості для інших дистрибутивів наведено тут.

Користування kde-builder

Налаштуйте ваше середовище розробки за допомогою kde-builder. Так ви отримаєте усі потрібні для розробки інструменти і базові бібліотеки, а також зібрані KDE Frameworks з нуля.

Створіть теку ~/kde/src/kirigami-tutorial. У цій теці зберігатимуться файли початкового коду з цього підручника.

Додайте таке наприкінці вашого файла ~/.config/kde-builder.yaml:

project kirigami-tutorial:
  no-src: true

⏳ За допомогою kdesrc-build…

Натисніть, щоб дізнатися про те, як це можна зробити за допомогою kdesrc-build

Цей крок виконується записуванням до ~/.config/kdesrc-buildrc із іншими синтаксисом:

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

Встановлення Kirigami за допомогою Craft

У KDE передбачено нетиповий інструмент для полегшення встановлення більшості бібліотек і програм: Craft. Ним можна скористатися для встановлення Kirigami у Linux, FreeBSD, Windows, Android та macOS.

Вам слід виконати настанови зі встановлення для Craft. Наприкінці налаштовування вам слід запустити файл налаштовування середовища (craftenv.ps1 або craftenv.sh), який надасть у ваше розпорядження оболонку термінала, у якій ви збиратимете вашу програму Kirigami.

Після цього ви можете просто віддати таку команду у терміналі:

craft kirigami kcoreaddons ki18n breeze kiconthemes qqc2-desktop-style

Якщо ви закриєте термінал, ви можете просто ще раз запустити файл налаштовування середовища, щоб зібрати вашу програму.

Структура проєкту

Хоча існують інструменти, за допомогою яких можна просто налаштувати наші файли, ми створимо їх вручну. Це надасть нам змогу краще зрозуміти частини, з яких буде створено нашу нову програму.

Спочатку ми створимо теку нашого проєкту (ви можете скористатися наведеними нижче командами). Назвемо цю теку kirigami-tutorial/.

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

У цій теці ми створимо теку src/ і файл CMakeLists.txt. Зазвичай, вважається за правило розташовувати усі файли основного коду C++ у теці src/. Ми також збережемо у ньому файл Main.qml, оскільки його буде запущено разом із виконуваним файлом.

Підказка

Ви можете швидко створити цю файлову систему ось так:

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

Нотатка

Якщо ви хочете автоматично збирати проєкт за допомогою kde-builder, нетипова назва модуля має бути такою, як назва кореневої теки проєкту (у нашому випадку, це буде «kirigami-tutorial»). Якщо це не так, вам слід змінити source-dir або dest-dir для модуля. Ми припускатимемо, що шляхом до вашого main.cpp буде $HOME/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!")
        }
    }
}

Тут ми працюватимемо із оболонкою нашої програми.

Якщо ви трохи знаєте Javascript, більша частина QML видасться вам знайомою (хоча тут є свої особливості). У документації до Qt є багато матеріалу щодо цієї мови, якщо вам захочеться спробувати щось самостійно. Вивчаючи курс підручника, ми зосередимося на нашому коді QML, де ми використовуватимемо Kirigami, щоб отримати максимальні переваги від цього.

Тепер зосередимо увагу на Main.qml. Спочатку ми імпортуємо декілька важливих модулів:

QtQuick, стандартну бібліотеку, яку використовують програми QML.
QtQuick Controls, які забезпечують роботу декількох стандартних засобів керування, якими ми можемо скористатися для того, щоб зробити наші програми інтерактивними.
QtQuick Layouts, які містять інструменти для розташовування компонентів у вікні програм.
Kirigami, яка містить декілька компонентів, які пристосовано для створення програм, що можуть працювати на різних пристроях і екранах з різними формами та розмірами.

Нотатка

Розташування імпортування елементів керування QtQuick і Kirigami в окремих просторах назв за допомогою ключового слова as є найкращим способом, який забезпечує усування можливих конфліктів між компонентами з однаковими назвами. У різних програмах ви можете бачити різні назви для елементів керування QtQuick, зокрема «QQC» або «QQC2». У цьому підручнику ми використовуватимемо термін «Controls».

Далі, ми перейдемо до нашого базового елемента, Kirigami.ApplicationWindow, який надає певні базові можливості, потрібні для усіх програм Kirigami. Це вікно, які міститиме усі наші сторінки, основні розділи нашого інтерфейсу користувача.

Далі, ми встановимо для властивості id вікна значення 'root'. Ідентифікатори є корисними, оскільки за їх допомогою ми отримуємо унікальну прив'язку до компонента, навіть коли у нас є декілька компонентів одного типу.

Ми також встановимо для властивості вікна title значення «Hello World». Ми зауважимо, що рядок «Hello World» огорнуто у функцію із назвою i18nc(). У цій функції ми деталізуємо контекст рядка, а також вказуємо сам рядок.

Нотатка

Функції i18n() роблять вашу програму придатною до перекладу, оскільки вони повертають версію переданого їм рядка мовою користувача (якщо вашу програму перекладено відповідною мовою). Користувач із англійською мовою інтерфейсу бачитиме заголовок вікна «Hello World», а користувач із іспанською мовою інтерфейсу — «Hola Mundo».

i18nc() побудовано на основі функції i18n(). Ця функція уможливлює для розробників надання перекладачам, які працюватимуть над перекладом програми, певного контексту. Тут ми прояснюємо, що компонент інтерфейсу користувача є заголовком вікна програми, тому ми включили рядок «@title:window» перед «Hello World». Див. підручник програміста щодо ki18n, щоб дізнатися більше.

Далі, ми визначаємо першу сторінку нашого стосу сторінок. Більшість програм Kirigami упорядковано як стос сторінок — кожну сторінку призначено для виконання окремого завдання. У нашому прикладі ми створимо простий стос, який складатиметься із однієї сторінки. pageStack є початково порожнім стосом сторінок, роботу якого забезпечує Kirigami.ApplicationWindow, і за допомогою pageStack.initialPage: Kirigami.Page{...} ми задаємо для першої сторінки, яку буде показано після завантаження програми, значення Kirigami.Page. Відповідна сторінка міститиме усі наші дані.

Нарешті, ми включаємо до нашої сторінки Controls.Label, яка надасть нам змогу розмістити на нашій сторінці текст. Ми використовуємо anchors.centerIn: parent для центрування нашої мітки горизонтально і вертикально у нашому батьківському елементі. У цьому випадку батьківським для компонента нашої мітки буде компонент Kirigami.Page. Нарешті, ми маємо встановити для мітки текст: text: i18n("Hello World!").

org.kde.tutorial.desktop

Основним призначенням файлів стільничних записів є показ вашої програми у засобі запуску програм у Linux. Іншою причиною їхнього існування є визначення піктограм вікна у Wayland, оскільки вони потрібні для надсилання повідомлення засобу композиції «піктограмою цього вікна є така».

Має виконуватися схема іменування зворотного DNS з наступним суфіксом назви .desktop, наприклад 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[sl]=Učbenik Kirigami
Name[sv]=Kirigami-handledning
Name[tr]=Kirigami Öğreticisi
Name[uk]=Підручник з Kirigami
Name[x-test]=xxKirigami Tutorialxx
Name[zh_TW]=Kirigami 教學
Exec=kirigami-hello
Icon=kde
Type=Application
Terminal=false
Categories=Utility

Нотатка

Піктограми вікна та панелі завдань працюватимуть у сеансі Wayland, лише якщо файл desktop програми зберігаються у ~/.local/share/applications або /usr/share/applications. Щоб працювали піктограми з цього розділу підручника, або скопіюйте файл desktop до одного з цих каталогів, або перемкніться на сеанс розробника, як описано у підручнику з kde-builder. Піктограми деяких програм KDE працюватимуть, якщо їх вже встановлено у системі.

CMakeLists.txt

Для використання вибраної системи збирання KDE, CMake, потрібні файли CMakeLists.txt. Наш файл kirigami-tutorial/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
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)

CMakeLists.txt визначає, як збирати ваші проєкти. Більшість даних тут призначено лише для збирання з нуля вашого проєкту. Порядкове глибинне пояснення дій, які описано у цьому файлі CMakeLists, наведено тут.

Найважливішим, про що слід пам'ятати, є те, що залежності збирання для C++ від Qt і KDE Frameworks керуються за допомогою find_package() і динамічні залежності QML є керованими за допомогою ecm_find_qml_module(). У процесі розробки вашої програми вам слід вносити зміни до цих рядків і включати усі додаткові компоненти, які ви вирішите використовувати.

Рядок з add_subdirectory(src) вказує CMake каталог kirigami-tutorial/src/, де зберігається наш початковий код.

Рядок із install() повідомляє CMake, куди слід встановити файл desktop.

Розгляньмо докладніше файл 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})

Робота цього файла складається з п'яти кроків:

створення виконуваного файла
заміна виконуваного файла на модуль QML, який прийматиме файли QML
додавання файлів C++ і QML до виконуваного файла
компонування з бібліотеками, які потрібні для запуску виконуваного файла
встановлення виконуваного файла до належного місця

Наступного разу коли ви захочете додати файли QML, додайте їх до наявного виклику ecm_target_qml_sources(). Файли C++, у яких використано ключове слово QML_ELEMENT, яке ми побачимо пізніше у підручнику, можна додати за допомогою target_sources().

Тепер, коли ми подбали про CMake, погляньмо на файли, з якими ми маємо намір працювати переважний час під час розробки програми.

main.cpp

Файл kirigami-tutorial/src/main.cpp обробляє «ділову логіку» нашої програми. Мова C++ є зручною для цього, оскільки вона є гнучкою і швидкою, хоча і потребує більше знань, ніж деякі інші мови програмування.

Цей файл є також вхідним пунктом нашої програми. Тут налаштовуються і запускаються обидві частини нашого проєкту — модуль обробки і інтерфейс користувача.

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

До цього моменту у нас не було потреби заглиблюватися у подробиці дій, які виконує код нашого main.cpp, але його роль значно зросте, якщо ми вирішимо додати складні функціональні можливості до нашої програми у майбутньому.

Теми у Windows

Натисніть тут, щоб дізнатися більше

Програма має встановити власну тему піктограм, QStyle та стиль засобів керування QtQuick у значення «Breeze», щоб інтерфейс було показано у Windows. Щоб дізнатися більше про це, див. Розбираємося з main.cpp.

Якщо ви вирішите продовжити, ви можете дізнатися більше щодо того, як працює цей main.cpp, з цієї сторінки.

Якщо вам потрібні ще декілька способів удосконалення коду C++, зокрема використання KAboutData для придатних до перекладу метаданих програми, ознайомтеся із нашим підручником з KXmlGui.

Зараз нас цікавитиме цей рядок:

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

Першим аргументом є адреса, яку встановлено у kirigami-tutorial/src/CMakeLists.txt, а другим аргументом є назва модуля QML, яким ми хочемо скористатися (Main, що походить від назви нашого файла Main.qml, яка має починатися з великої літери).

Старий метод

Ви можете зустрітися із цим альтернативним способом завантаження файлів QML у справжньому коді!

Старий метод завантаження файлів QML мав недоліки, і після Qt6 він став суттєво багатослівнішим:

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

Ця адреса ресурсу Qt вище записується у такому шаблоні: <префікс_ресурсу><адреса_імпортування><необов'язковий_каталог_QML><файл>. У цьому випадку:

префікс ресурсу = типовий / у Qt5, /qt/qml у Qt6
адреса імпортування URI = /org/kde/tutorial, що відповідає адресі org.kde.tutorial
необов'язковий каталог QML = /qml, потрібен, якщо файли QML зберігаються у каталозі із назвою qml/
file = файл QML

Збирання і встановлення програми

Ми наблизилися до фінішу. Наприкінці процесу нам слід зібрати і запустити нашу програму. При цьому послідовність дій залежить від програмної платформи.

Linux або FreeBSD

Збирання за допомогою kde-builder

Виконайте настанови з розділу користування kde-builder.

Зберіть потрібні для збирання залежності за допомогою kde-builder, потім зберіть kirigami-tutorial за допомогою таких команд у терміналі:

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

Збирання вручну

Перейдіть до кореневої теки проєкту, а потім віддайте таку команду у терміналі:

cmake -B build/
cmake --build build/
cmake --install build/ --prefix "$HOME/.local"

Програму буде встановлено до $HOME/.local/bin, а її стільничний запис — до $HOME/.local/share/applications.

Windows

Якщо ви збираєте ваш проєкт у Windows після налаштовування Craft, CMake має автоматично визначити належний компілятор:

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

Залежно від способу встановлення компілятора, вам, можливо, на першому кроці слід вказати породжувач CMake, залежно від того, користуєтеся ви для збирання ваших проєктів Visual Studio (msvc) чи MinGW (make).

Якщо це Visual Studio, залежно від компілятора, який ви встановите, це може бути:

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

Або:

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

Якщо MinGW:

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

В обох випадках програму буде встановлено до C:\CraftRoot\bin.

Якщо ви раптом засумніваєтеся у назві компілятора, який має бути використано при виклику cmake, віддайте таку команду:

cmake -G

Буде показано список усіх доступних засобів створення даних.

Запуск програми

Далі, ви можете запустити програму kirigami-hello такою командою:

kirigami-hello # У Linux, вручну
kde-builder --run kirigami-hello # За допомогою kde-builder
kdesrc-build --run --exec kirigami-hello kirigami-tutorial # За допомогою kdesrc-build
kirigami-hello.exe # У Windows

Ось і все! Тепер ви бачите перед собою вашу першу програму Kirigami вашими власними очима.

Знімок вікна створеної програми Kirigami

Щоб запустити нову програму QML у режимі мобільного пристрою, ви можете скористатися QT_QUICK_CONTROLS_MOBILE=1:

QT_QUICK_CONTROLS_MOBILE=1 kirigami-hello

Якщо ви зібрали проєкт вручну за допомогою CMake і з якихось причин хочете вилучити встановлений проєкт, ви можете скористатися такою командою:

cmake --build build/ --target uninstall

Нотатка

Наступного разу, коли створюватимете потрібні файли і теки, можете скористатися KAppTemplate або KDevelop для автоматичного створення відповідної початкової версії проєкту. Ці програми є у сховищах усіх основних дистрибутивів. Крім того, ці програми створюють файли, що містять метадані AppStream і файл .desktop, який містить дані щодо того, як слід показувати пункт програми у засобах запуску програм Linux.

Завдяки магії CMakeLists, ви також можете скористатися комплексними середовищами розробки, зокрема KDevelop або QtCreator для подальшого написання програми у комфортному середовищі із мінімальними зусиллями.

Пояснення щодо сторінок