Настройка проекта на C++

Создание первого приложения Kirigami на C++

Установка Kirigami

Прежде чем начать, необходимо установить Kirigami на компьютере. Сделать это можно тремя способами:

Установка Kirigami из репозиториев дистрибутива Linux
Использование kde-builder
Установка Kirigami с помощью Craft

Если используется достаточно актуальный дистрибутив, например Debian Testing, последняя версия Ubuntu без долгосрочной поддержки, Fedora, openSUSE Tumbleweed или Arch, можно установить Kirigami из дистрибутива.

Если используется устаревший дистрибутив, например Debian Stable или Ubuntu LTS, для работы с этим руководством следует использовать kde-builder. Ему потребуется не более 2 ГБ дискового пространства.

Установка Kirigami из репозиториев дистрибутива Linux

Требуются компилятор C++, пакеты разработки Qt и Kirigami. Откройте терминал и выполните одну из следующих команд в зависимости от используемого дистрибутива Linux:

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-kirigami-devel kf6-ki18n-devel kf6-kcoreaddons-devel kf6-kiconthemes-devel qt6-qtbase-devel qt6-qtdeclarative-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 в Windows, Android и macOS.

Хотя Craft также доступен для Linux и FreeBSD, он предназначен только для AppImage и упаковки.

Необходимо выполнить инструкции по настройке Craft. К концу настройки должен быть запущен файл настройки окружения (craftenv.ps1 в Windows или 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 будет таким: ~/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 Controls и Kirigami в отдельных пространствах имён с помощью ключевого слова as — рекомендуемая практика, гарантирующая, что компоненты с одинаковыми именами не будут конфликтовать. В разных источниках можно встретить другие имена для QtQuick Controls, например «QQC» или «QQC2». В этом руководстве для ясности будет использоваться «Controls».

Далее следует базовый элемент — Kirigami.ApplicationWindow, который предоставляет ряд основных возможностей, необходимых всем приложениям Kirigami. Это окно, в котором будут размещаться все страницы — основные разделы пользовательского интерфейса.

Затем свойству id окна присваивается значение «root». Идентификаторы полезны, поскольку позволяют однозначно ссылаться на компонент, даже если имеется несколько компонентов одного типа.

Кроме того, свойству title окна присваивается значение «Hello World». Можно заметить, что строка «Hello World» обёрнута в функцию i18nc(), в которой указывается как контекст строки, так и сама строка.

Примечание

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

Функция i18nc() основана на функции i18n() и позволяет разработчикам предоставлять переводчикам, работающим над приложением, контекст. Здесь уточняется, что компонент интерфейса — это заголовок окна приложения, поэтому перед «Hello World» добавлена строка «@title:window». Дополнительные сведения см. в руководстве программиста 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

Основное назначение файлов .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
21
22
23
24
[Desktop Entry]
Name=Kirigami Tutorial
Name[ar]=درس كيريغامي
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[ro]=Îndrumar Kirigami
Name[ru]=Учебное руководство по Kirigami
Name[sk]=Tutoriál 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

Примечание

Значки окон и панели задач будут работать в сеансе 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

Нажмите здесь, чтобы узнать больше

Чтобы приложение показывалось в Windows, ему необходимо задать тему значков, QStyle и стиль Qt Quick Controls как Breeze. Подробнее об этом см. в разделе Разбор main.cpp.

Чтобы забежать вперёд, можно подробнее прочитать о том, как работает main.cpp, в разделе Разбор main.cpp.

Чтобы узнать о нескольких способах улучшения кода на C++, например об использовании KAboutData для переводимых метаданных приложения, ознакомьтесь с руководством по KXmlGui.

Пока что нас интересует эта строка:

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

Первый аргумент — это URI, заданный в 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")));

Приведённый выше URI ресурса Qt соответствует шаблону <resource_prefix><import_URI><optional_QML_dir><file>. В этом случае:

префикс ресурса = по умолчанию / в Qt5, /qt/qml в Qt6
import URI = /org/kde/tutorial, что соответствует URI 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/ --install-prefix ~/.local
cmake --build build/
cmake --install build/

Приложение будет установлено в ~/.local/bin, а его файл .desktop — в ~/.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.

Чтобы запустить новое приложение 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 можно также использовать такие IDE, как KDevelop или QtCreator, для разработки этого приложения в комфортной среде с минимальными усилиями.

Настройка проекта на Python