Настройка для Android
Введение
Qt хорошо поддерживает Android, но для корректной работы в Android приложения требуют существенных изменений.
Потребуется следующее:
- Чертёж Craft
- Настройка qqc2-breeze-style
- Значки в составе приложения
- Манифест Android
- Необязательно: файл сборки Gradle
- Необязательно: XML-файл заставки
- Функция CMake для создания пакета Android
Чертёж Craft требуется, чтобы объединить все зависимости вместе с приложением и создать пакет APK для Android.
qqc2-breeze-style — альтернатива qqc2-desktop-style, рассчитанная прежде всего на мобильные платформы, такие как Android и Plasma Mobile.
В чертеже Craft приложения нужен условный код, чтобы не смешивать стили для настольных и мобильных систем, а в коде C++ необходимо следить, чтобы для настольной и мобильной системы не применялась чужая конфигурация. В коде CMake условный код тоже может понадобиться, хотя без него можно обойтись.
Необходимые для работы приложения значки включаются в его состав с помощью extra-cmake-modules из KDE, средств Qt для упаковки ресурсов, а также функций CMake из Kirigami и Kirigami Addons.
Манифест Android объявляет метаданные и дополнительные файлы, которые нужно включить в состав приложения для Android.
Файл сборки Gradle нужен, если с помощью интеграции extra-cmake-modules в сборку для Android передаются уже имеющиеся метаданные приложения, например его версия, или если требуются особые параметры сборки.
XML-файл заставки нужен, если требуется добавить заставку со своим значком, фоном и расположением.
Чертёж Craft
Настройка qqc2-breeze-style
Чтобы начать использовать qqc2-breeze-style, его нужно добавить в Craft. Поскольку он используется только для Android, потребуется условие, особенно если приложение уже настроено для сборки в Windows и (или) Linux с qqc2-desktop-style. Для этого нужно импортировать модуль CraftCore:
from CraftCore import CraftCore
# …
def setDependencies(self):
# …
if not CraftCore.compiler.isAndroid:
self.runtimeDependencies["kde/frameworks/tier1/breeze-icons"] = None
self.runtimeDependencies["kde/frameworks/tier3/qqc2-desktop-style"] = None
else:
self.runtimeDependencies["kde/plasma/qqc2-breeze-style"] = NoneПохожую логику «если не Android — qqc2-desktop-style, иначе — qqc2-breeze-style» нужно применить и в CMake, каким бы способом там ни искался qqc2-desktop-style:
if (NOT ANDROID)
find_package(KF6QQC2DesktopStyle REQUIRED)
ecm_find_qmlmodule(org.kde.desktop REQUIRED)
endif()Условный код требуется и в C++.
В Android приложения KDE используют не QApplication, а QGuiApplication. Помимо того что qqc2-breeze-style задаётся только для Android, нужно позаботиться о порядке инициализации, ведь скорее всего приложение уже работает в настольной системе. Это можно сделать так:
int main(int argc, char* argv[])
{
KIconTheme::initTheme();
#ifdef Q_OS_ANDROID
QGuiApplication app(argc, argv);
QQuickStyle::setStyle("org.kde.breeze");
#else
QIcon::setFallbackThemeName("breeze");
if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE"))
{
QQuickStyle::setStyle("org.kde.desktop");
}
QApplication app(argc, argv);
// …
#endif
}Использование KirigamiAppDefaults
Если используется KirigamiAppDefaults::Apply(), приведённый выше код C++ уже выполняется за вас.Поставка значков
Чтобы приложение использовало значки Breeze, сначала нужно включить KIconThemes в проект.
Чтобы включить значок приложения в его состав, потребуется несколько команд CMake.
Наконец, дополнительной командой CMake из Kirigami можно включить в состав приложения значки Kirigami (и при желании значки Kirigami Addons).
KIconThemes
Это делается так:
- Добавление его в Craft в качестве зависимости:
def setDependencies(self):
self.runtimeDependencies["kde/frameworks/tier3/kiconthemes"] = None- Добавление его в качестве зависимости в CMake:
find_package(KF6 REQUIRED COMPONENTS IconThemes)
# ...
target_link_libraries(kirigami-hello
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 необходимо инициализировать до запуска приложения.
Использование KirigamiAppDefaults
Если используется KirigamiAppDefaults::Apply(), приведённая выше инициализация KIconThemes в коде C++ уже выполняется за вас.Значок приложения
Если у приложения есть значок, его необходимо добавить в проект и как ресурс QML, и как часть установки значка.
Обычно в Linux значок приложения можно просто установить в нужную папку, и при необходимости приложение само извлечёт значок. Как правило, значок приложения состоит из основного значка SVG и нескольких значков PNG разных размеров.
Установка значка SVG в CMake выполняется так:
install(FILES ${CMAKE_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 имя значка превращается в путь, который он получит в файловой системе.
После установки значка таким способом его можно вызвать в коде QML просто как myapp или org.kde.myapp — так же, как при вызове из QIcon::fromTheme(). Это можно использовать с любым элементом управления QML, имеющим свойство icon.name.
В Android такой стандартной папки нет, поэтому установка значка ничего не даёт: его необходимо включить в состав приложения. Для этого 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++, в частности при задании значка окна, можно по умолчанию использовать значок из темы значков, а значок, включённый в приложение, — как запасной вариант для QGuiApplication::setWindowIcon():
QGuiApplication::setWindowIcon(QIcon::fromTheme("org.kde.myapp", QIcon(":/qt/qml/org/kde/myapp/org.kde.myapp.svg")));Значки Kirigami
Хотя в Android нет стандартной папки для установки значков из темы значков, необходимые значки Kirigami можно включить в приложение для Android.
Для этого нужно следующее:
- Подготовить проект с KIconThemes
- Включить breeze-icons в чертёж Craft
- kirigami_package_breeze_icons()
Чтобы настроить KIconThemes, см. раздел KIconThemes выше.
Чтобы добавить breeze-icons в качестве зависимости проекта, добавьте в чертёж Craft следующее:
def setDependencies(self):
# …
self.runtimeDependencies["kde/frameworks/tier1/breeze-icons"] = NoneИз-за особенностей сборки для Android Craft не может включить значки в приложение автоматически. Поэтому Kirigami предоставляет функцию CMake kirigami_package_breeze_icons(), которая во время сборки клонирует значки и готовит их к упаковке. Эта команда должна идти до шага, описанного в разделе Функция CMake для создания пакета Android.
Команду CMake kirigami_package_breeze_icons() не нужно помещать в условие: она выполняется только в Android.
Кроме того, если в приложении используется Kirigami Addons, можно передать переменную ${KIRIGAMI_ADDONS_ICONS}, чтобы поставлять и значки, нужные таким компонентам, как FormCard.AboutPage и подобным.
kirigami_package_breeze_icons(ICONS
org.kde.myapp insert-image-symbolic kde application-exit-symbolic
edit-clear-all-symbolic edit-undo-symbolic document-save-symbolic
applications-development-symbolic system-user-list donate-symbolic
${KIRIGAMI_ADDONS_ICONS}
)Манифест Android
Манифест Android — это XML-файл, описывающий приложение для средств сборки Android, операционной системы и магазинов приложений. Файл должен называться AndroidManifest.xml.
Qt использует манифест Android и поддерживает дополнительную настройку, чтобы вызвать средства, необходимые для сборки APK, который можно установить в Android.
Приложения KDE хранят манифест в папке android/ в корне проекта.
Манифест Android может выглядеть так:
<?xml version='1.0' encoding='utf-8'?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="org.kde.myapp"
android:installLocation="auto">
<application android:name="org.qtproject.qt.android.bindings.QtApplication" android:label="MyApp" android:usesCleartextTraffic="true" android:icon="@drawable/myapp">
<activity android:configChanges="orientation|uiMode|screenLayout|screenSize|smallestScreenSize|layoutDirection|locale|fontScale|keyboard|keyboardHidden|navigation"
android:name="org.qtproject.qt.android.bindings.QtActivity"
android:label="MyApp"
android:windowSoftInputMode="adjustResize"
android:launchMode="singleTop"
android:exported="true">
<intent-filter>
<action android:name="android.intent.action.MAIN"/>
<category android:name="android.intent.category.LAUNCHER"/>
</intent-filter>
<meta-data android:name="android.app.lib_name" android:value="myapp"/>
</activity>
</application>
<uses-permission android:name="android.permission.INTERNET" />
<supports-screens android:largeScreens="true" android:normalScreens="true" android:anyDensity="true" android:smallScreens="true"/>
</manifest>В основном это шаблонный код, его можно скопировать в существующий проект и изменить, но стоит разобраться, какие его части требуют внимания.
В теге <manifest> атрибут package соответствует имени, по которому Android внутренне идентифицирует приложение. Оно должно быть записано в обратной нотации DNS и совпадать с идентификатором приложения, указанным в коде.
В тегах <application> и <activity> атрибут android:label должен содержать видимое пользователю название приложения. В теге <meta-data> атрибут android:value должен совпадать с именем цели, указанным в CMake.
В теге <application> атрибут android:icon="@drawable/myapp" должен указывать на значок из папки android/res/drawable/, без расширения файла. В этом примере файлом будет android/res/drawable/myapp.png. Папка res означает «resources» (ресурсы). Если значок не указан, в меню приложений и в запросе на установку вместо него будет показан стандартный значок-заглушка Android.
Активность (Activity) описывает, что приложение делает в разных состояниях. Например, на переднем плане оно может выполнять одни действия, а в фоне — другие. Обычно у приложения Qt/KDE только одна активность.
У каждой активности может быть один или несколько фильтров намерений (Intent Filters). Намерение (Intent) — это то, что активность умеет делать; для приложения KDE это обычно действие, но может быть и служба. Например, если приложение намерено запускаться, оно должно сообщить Android, что эта активность — точка входа приложения (android.intent.action.MAIN) и что намерение относится к типу LAUNCHER, чтобы приложение появилось на экране меню приложений и его можно было запустить. Для большинства приложений KDE этого обычно достаточно.
Тег <meta-data> может повторяться несколько раз и служить разным целям; в нём можно использовать особые параметры, специфичные для Qt. Метаданные android.app.lib_name обязательны.
Тег <uses-permission> устроен просто: он позволяет приложению запросить разрешение на определённое действие. Разрешение отличается от намерения тем, что намерение просит другой компонент выполнить действие, связанное с активностью, а разрешение — это запрос доступа к функциям, по умолчанию недоступным.
Тег <supports-screens> указывает, какие форм-факторы (размеры экрана и плотность пикселей, телефоны или планшеты) поддерживает приложение. Поскольку приложения QML адаптивны, разумно по умолчанию указывать «любой размер».
Необязательны в приведённом примере только android:icon="@drawable/myapp" (используется, лишь если у приложения уже есть значок) и <uses-permissions> (добавлять только при реальной необходимости).
Заставка
Заставка — необязательный экран со статичным изображением или анимацией, который показывается при запуске приложения и даёт ему несколько секунд на инициализацию. Если заставка не задана, приложение появляется сразу после открытия, даже если оно ещё не готово.
Чтобы добавить её в приложение, укажите её в метаданных AndroidManifest.xml:
<meta-data android:name="android.app.splash_screen_drawable" android:resource="@drawable/splash"/>В свою очередь, должен существовать файл android/res/drawable/splash.xml:
<?xml version="1.0" encoding="utf-8"?>
<layer-list xmlns:android="http://schemas.android.com/apk/res/android">
<item android:width="128dp" android:height="128dp" android:gravity="center">
<bitmap
android:layout_width="fill_parent"
android:layout_height="fill_parent"
android:scaleType="fitXY"
android:src="@drawable/myapp"/>
</item>
</layer-list>Этот простой пример, часто встречающийся в приложениях KDE, помещает значок приложения в центр пустого фона, поэтому требуется значок приложения в папке android/res/drawable/.
Подготовка APK
Последний шаг, который нужен, чтобы APK для Android действительно собирался, — простая функция CMake, использующая файлы из папки android/:
ecm_add_android_apk(myapp
ANDROID_DIR ${PROJECT_SOURCE_DIR}/android
)Сборка
Чтобы собрать приложение для Android, выполните инструкции из раздела Сборка приложений для Android.
Сборки в системе непрерывной интеграции
Если проект правильно настроен для сборки в Windows и использует инфраструктуру KDE для размещения кода (KDE Invent), можно настроить задания CI/CD для Android.
Для этого потребуется добавить соответствующие шаблоны CI для Windows с помощью файла .gitlab-ci.yaml и перечислить зависимости в файле .kde-ci.yaml, как указано в разделе Система непрерывной интеграции.