Skip to main content
Перейти к содержимому

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

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

Введение

Qt хорошо поддерживает Android, но для корректной работы в 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
}

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

Чтобы приложение использовало значки 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 необходимо инициализировать до запуска приложения.

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

Если у приложения есть значок, его необходимо добавить в проект и как ресурс 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, как указано в разделе Система непрерывной интеграции.