Skip to main content
Перейти к содержимому
Редактировать эту страницу See source code Создать задачу по документации Formatting guidelines Style guidelines

Настройка для Windows

Подготовка приложения на C++ для Windows

Введение

Qt хорошо поддерживает Windows, поэтому приложения, использующие Qt и extra-cmake-modules из KDE, не потребуют множества изменений для корректной работы в Windows.

Требуются три вещи:

Чертёж Craft требуется, чтобы объединить все зависимости вместе с приложением и создать исполняемый файл.

Директиву препроцессора #ifdef Q_OS_WIN можно использовать для написания кода, который будет применяться только при сборке приложения в Windows. Это необходимо как минимум один раз, чтобы принудительно применить к приложению стиль Breeze и оно хорошо выглядело в Windows, но в зависимости от приложения может потребоваться больше.

Включение в приложение необходимых значков для его работы в Windows — самый сложный этап, но и extra-cmake-modules (ECM) из KDE, и Qt предоставляют средства, упрощающие эту задачу.

Чертёж Craft

Чтобы начать, сначала необходимо выполнить инструкции из раздела Сборка программного обеспечения KDE в Windows с помощью Craft, чтобы получить работоспособную чертёж Craft и хотя бы собрать приложение в Windows.

Как только проект удастся собрать, появятся ошибки компиляции и времени выполнения, которые помогут устранить проблемы совместимости с Windows.

Стиль Breeze

Учебное руководство Kirigami уже должно быть в основном совместимо с Windows, но шаги для этого следует описать явно.

Чтобы обеспечить использование стиля Breeze, нужно внести два изменения: задать для QStyle значение breeze, а для стиля Qt Quick Controls — значение org.kde.desktop.

QStyle управляет большей частью внешнего вида приложения QtWidgets. Это необходимо в приложении QtQuick, поскольку приложение инициализируется с помощью QApplication (традиционно используемого с QtWidgets).

Стиль Qt Quick Controls, напротив, определяет большую часть внешнего вида приложения QtQuick. Это влияет на то, как будут выглядеть элементы управления QML. Стиль KDE org.kde.desktop (также известный как qqc2-desktop-style) особенный: он пытается устранить дублирование, заимствуя элементы оформления из QStyle приложения (поэтому и используется QApplication). Благодаря этому приложения QtWidgets и QtQuick могут в основном выглядеть одинаково и совместно использовать компоненты оформления.

Приложениям QtQuick / Kirigami необходимо задать оба стиля в коде C++. Чтобы задать QStyle, его нужно добавить в двух местах.

В Craft:

def setDependencies(self):
    self.runtimeDependencies["kde/plasma/breeze"] = None

А в C++:

QApplication::setStyle("breeze");

Это то, что используется в учебном руководстве Kirigami. В противном случае можно загружать стиль Breeze только в Windows, где это наиболее актуально, с помощью ifdef:

#ifdef Q_OS_WIN
    QApplication::setStyle("breeze");
#endif

Стиль Qt Quick Controls нужно добавить в трёх местах.

В Craft:

def setDependencies(self):
    self.runtimeDependencies["kde/frameworks/tier3/qqc2-desktop-style"] = None

В C++, где требуется условная компиляция:

if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE"))
{
    QQuickStyle::setStyle("org.kde.desktop");
}

А также, при необходимости, в CMake одним из двух способов:

find_package(KF6 REQUIRED COMPONENTS QQC2DesktopStyle)
# or
ecm_find_qmlmodule(org.kde.desktop REQUIRED)

Так как это зависимость времени выполнения, её не требуется задавать в CMake, который используется на этапе компиляции. Однако это может послужить сигналом — как для себя, так и для других — о том, правильно ли настроено окружение и сможет ли оно запустить полученное приложение, что позволит легче находить отсутствующие пакеты или ошибки в настройке.

Команда find_package() выполняет поиск именно файлов конфигурации CMake для qqc2-desktop-style, тогда как ecm_find_qmlmodule() менее строга и ищет только модуль QML. Для последней требуется подключить ECMFindQmlModule:

include(ECMFindQmlModule)

Поставка значков

Чтобы приложение использовало значки Breeze, сначала нужно включить KIconThemes в проект.

После этого потребуется несколько команд CMake, чтобы включить значок приложения в состав приложения.

KIconThemes

Для этого нужно выполнить следующие три шага:

  • Добавление его в Craft в качестве зависимости:
def setDependencies(self):
    self.runtimeDependencies["kde/frameworks/tier3/kiconthemes"] = None
  • Добавление его в качестве зависимости в CMake:
find_package(KF6 REQUIRED COMPONENTS IconThemes)

# ...

target_link_libraries(myapp
    PRIVATE
    # ...
    KF6::IconThemes
)
  • Использование в коде C++ в файле main.cpp:
#include <KIconTheme>

// …
int main(int argc, char* argv[])
{
    KIconTheme::initTheme();
    QApplication app(argc, argv);
    // …
}

Учтите, что, хотя в названии проекта и в вызове CMake используется множественное число (KIconThemes, KF6IconThemes), в вызове C++ используется единственное число (KIconTheme).

KIconThemes необходимо инициализировать до запуска приложения.

Значок приложения

Если у приложения есть значок, его необходимо добавить в проект и как ресурс QML, и как часть установки значка.

Обычно в Linux значок приложения можно просто установить в нужную папку, и при необходимости приложение само извлечёт значок. Как правило, значок приложения состоит из основного значка SVG и нескольких значков PNG разных размеров.

Установка значка SVG в CMake выполняется так:

install(FILES ${PROJECT_SOURCE_DIR}/icons/org.kde.myapp.svg DESTINATION ${KDE_INSTALL_FULL_ICONDIR}/hicolor/scalable/apps)

А установка значков PNG выполняется так:

ecm_install_icons(ICONS
    16-apps-myapp.png
    24-apps-myapp.png
    32-apps-myapp.png
    48-apps-myapp.png
    64-apps-myapp.png
    128-apps-myapp.png
    256-apps-myapp.png
    512-apps-myapp.png    
    DESTINATION share/icons)

При установке значка приложения в Linux PNG-значок, например 48-apps-myapp.png, помещается в ${INSTALL_PREFIX}/share/icons/hicolor/48x48/apps/myapp.png, а SVG-значок — в ${INSTALL_PREFIX}/share/icons/hicolor/scalable/apps/org.kde.myapp.svg, где ${INSTALL_PREFIX} обычно означает /usr, /usr/local или ~/.local. Обратите внимание, как в случае PNG имя значка превращается в путь, который он получит в файловой системе.

Подробнее об установке файлов можно прочитать в разделе Сборка программного обеспечения KDE вручную: шаг установки.

После установки значка таким способом его можно вызвать в коде QML просто как myapp или org.kde.myapp — так же, как при вызове из QIcon::fromTheme(). Это можно использовать с любым элементом управления QML, имеющим свойство icon.name.

В Windows такого стандартной папки нет, поэтому установка значка ничего не даёт: его необходимо включить в состав приложения. Для этого PNG-файл можно поместить в собственную папку установки с помощью ecm_add_app_icon(), а файл PNG или SVG можно встроить в приложение как файл ресурсов Qt в ecm_add_qml_module() или ecm_target_qml_sources().

Значок приложения в формате PNG устанавливается с помощью:

ecm_add_app_icon(myapp ICONS ${PROJECT_SOURCE_DIR}/icons/256-apps-myapp.png)

А основной значок приложения включается в состав как ресурс Qt с помощью:

ecm_add_qml_module(myapp URI org.kde.myapp)
ecm_target_qml_sources(myapp SOURCES Main.qml RESOURCES ../icons/org.kde.myapp.svg)

Благодаря этому значок приложения будет доступен как ресурс Qt по пути qrc:/qt/qml/org/kde/myapp/org.kde.myapp.svg. Это можно использовать с любым элементом управления QML, у которого есть свойство icon.source.

Путь RESOURCES зависит от того, где расположены значки. Традиционно в корне проекта создаётся папка icons/ для хранения всех значков, поскольку они не считаются исходными файлами.

После установки значков (в Linux) и включения их в приложение (в Windows и Android) значок можно задать в коде. В коде QML для совместимости с Windows и Android следует использовать значок, включённый в приложение; в коде C++, в частности при задании значка окна, можно по умолчанию использовать значок из темы значков, а значок, включённый в приложение, — как запасной вариант с помощью QIcon::fromTheme() в вызове QGuiApplication::setWindowIcon():

QGuiApplication::setWindowIcon(QIcon::fromTheme("org.kde.myapp", QIcon(":/qt/qml/org/kde/myapp/org.kde.myapp.svg")));

Значки Kirigami

Хотя в Windows нет стандартной папки для установки значков из темы значков, необходимые значки Breeze можно включить в приложение Windows.

Craft выполняет это автоматически, если для проекта правильно настроен KIconThemes, а значки Breeze включены в проект как зависимость.

Чтобы настроить KIconThemes, см. раздел KIconThemes выше.

Чтобы добавить значки Breeze в качестве зависимости проекта, добавьте в чертёж Craft следующее:

def setDependencies(self):
    # …
    self.runtimeDependencies["kde/frameworks/tier1/breeze-icons"] = None

Таким образом, не потребуется вручную включать значки Breeze в состав приложения как ресурс: достаточно использовать имя QIcon::fromTheme(), например kde или application-exit-symbolic.

Сборка

Чтобы собрать приложение в Windows, необходимо выполнить инструкции из раздела Сборка программного обеспечения KDE в Windows с помощью Craft: сборка собственных проектов в Windows.

Сборки в системе непрерывной интеграции

Если проект правильно настроен для сборки в Windows и использует инфраструктуру KDE для размещения кода (KDE Invent), можно настроить задания CI/CD для Windows.

Для этого потребуется добавить соответствующие шаблоны CI для Windows с помощью файла .gitlab-ci.yaml и перечислить зависимости в файле .kde-ci.yaml, как указано в разделе Система непрерывной интеграции.

Устранение неполадок

Если возникли проблемы с адаптацией приложения к Windows, можно посетить следующие комнаты в Matrix:

Previous
Делегаты форм на страницах параметров