Skip to main content
Preskočiť na obsah

Nastavenie pre Android

Príprava vašej C++ aplikácie pre Android

Úvod

Qt má výbornú podporu systému Android, ale aplikácie vyžadujú značné množstvo úprav, aby na Androide fungovali správne.

Je potrebných niekoľko vecí:

Blueprint Craft je potrebný na zbalenie všetkých závislostí spolu s aplikáciou na vygenerovanie balíka APK pre Android.

qqc2-breeze-style je alternatíva k qqc2-desktop-style, ktorá je zameraná najmä na mobilné platformy, ako sú Android a Plasma Mobile.

Blueprint Craft aplikácie potrebuje podmienený kód, aby sa nemiešali desktopové a mobilné štýly, a C++ kód si vyžaduje osobitnú pozornosť, aby sa nepoužila nesprávna konfigurácia pre desktop a mobil. Kód CMake môže voliteľne tiež potrebovať podmienený kód, hoci sa mu dá vyhnúť.

Zbalenie ikon potrebných na fungovanie aplikácie sa robí pomocou extra-cmake-modules od KDE, nástrojov Qt na zbaľovanie zdrojov a funkcií CMake z Kirigami a Kirigami Addons.

Manifest pre Android deklaruje metadáta a ďalšie súbory, ktoré treba zbaliť s aplikáciou pre Android.

Zostavovací súbor Gradle je potrebný v prípade, že používate integráciu extra-cmake-modules na prenesenie existujúcich metadát vašej aplikácie do zostavenia pre Android, napríklad verzie aplikácie, alebo ak chcete špeciálne voľby zostavenia.

XML súbor úvodnej obrazovky je potrebný v prípade, že chcete pridať úvodnú obrazovku s vlastnou ikonou, pozadím a umiestnením.

Plán Craft

Nastavenie qqc2-breeze-style

Ak chcete začať používať qqc2-breeze-style, musíte ho pridať do Craftu. Keďže sa používa iba pre Android, bude vyžadovať podmienku, najmä ak je aplikácia už nastavená na zostavovanie pre Windows a/alebo Linux pomocou qqc2-desktop-style. To si vyžaduje import modulu 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

Podobnú logiku „ak nie Android, použi qqc2-desktop-style, inak použi qqc2-breeze-style“ treba použiť aj v CMake, ak sa používa niektorý zo spôsobov hľadania qqc2-desktop-style:

if (NOT ANDROID)
    find_package(KF6QQC2DesktopStyle REQUIRED)
    ecm_find_qmlmodule(org.kde.desktop REQUIRED)
endif()

Podmienený kód je potrebný aj v C++.

Na Androide aplikácie KDE nepoužívajú QApplication, ale QGuiApplication. Okrem nastavenia qqc2-breeze-style iba pre Android treba vyriešiť aj poradie inicializácie vo veľmi pravdepodobnom prípade, že vaša aplikácia je už kompatibilná s desktopom. Dá sa to dosiahnuť takto:

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
}

Dodávanie ikon

Prvá vec, ktorú je potrebné urobiť, aby aplikácia používala ikony Breeze, je zahrnúť KIconThemes do vášho projektu.

Na zbalenie ikony vašej aplikácie s aplikáciou sú potrebné niektoré príkazy CMake.

Nakoniec sa dá použiť ďalší príkaz CMake z Kirigami na zbalenie ikon Kirigami do vašej aplikácie (a voliteľne aj ikon Kirigami Addons).

Téma

Dá sa to urobiť takto:

  • Pridanie ako závislosti v Craft:
def setDependencies(self):
    self.runtimeDependencies["kde/frameworks/tier3/kiconthemes"] = None
  • Pridanie ako závislosti v CMake:
find_package(KF6 REQUIRED COMPONENTS IconThemes)

# ...

target_link_libraries(kirigami-hello
    PRIVATE
    # ...
    KF6::IconThemes
)
  • Použitie v C++ kóde, v súbore main.cpp:
#include <KIconTheme>

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

Všimnite si, že hoci názov projektu a volanie CMake používajú množné číslo (KIconThemes, KF6IconThemes), volanie C++ používa jednotné číslo (KIconTheme).

KIconThemes je potrebné inicializovať pred aplikáciou.

Ikona aplikácie

Ak má vaša aplikácia ikonu, musí byť pridaná do vášho projektu ako QML zdroj aj ako súčasť inštalácie ikon.

Bežne v Linuxe sa ikona aplikácie môže jednoducho nainštalovať do správneho adresára a ikona bude aplikáciou načítaná, keď je to potrebné. Zvyčajne ikona aplikácie pozostáva z primárnej SVG ikony, spárovanej s viacerými veľkosťami PNG ikon.

Inštalácia ikony SVG sa v CMake robí takto:

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

A inštalácia ikon PNG sa robí takto:

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)

Keď sa ikona aplikácie nainštaluje v Linuxe, PNG ikona ako 48-apps-myapp.png ide do ${INSTALL_PREFIX}/share/icons/hicolor/48x48/apps/myapp.png a SVG ikona ide do ${INSTALL_PREFIX}/share/icons/hicolor/scalable/apps/org.kde.myapp.svg, kde ${INSTALL_PREFIX} zvyčajne znamená /usr, /usr/local alebo ~/.local. Všimnite si, ako sa v prípade PNG názov ikony premietne do cesty, ktorú bude mať v súborovom systéme.

Keď je ikona nainštalovaná týmto spôsobom, v QML kóde sa dá jednoducho zavolať pomocou myapp alebo org.kde.myapp, ako by sa volalo z QIcon::fromTheme(). Toto sa dá použiť s akýmkoľvek QML ovládacím prvkom, ktorý má vlastnosť icon.name.

Android taký štandardný adresár nemá a inštalácia ikony nemá žiadny efekt; musí byť zbalená s aplikáciou. Na to sa PNG môže odoslať do vlastného inštalačného adresára pomocou ecm_add_app_icon() a PNG alebo SVG súbor sa dá vložiť do aplikácie ako súbor zdrojov Qt v ecm_add_qml_module() alebo ecm_target_qml_sources().

Ikona aplikácie PNG sa inštaluje pomocou:

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

A hlavná ikona aplikácie je zbalená ako Qt zdroj pomocou:

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

Tým sa ikona aplikácie sprístupní ako Qt zdroj pod qrc:/qt/qml/org/kde/myapp/org.kde.myapp.svg. Toto sa dá použiť s akýmkoľvek QML ovládacím prvkom, ktorý má vlastnosť icon.source.

Cesta RESOURCES závisí od miesta, kde sú ikony nainštalované. Tradične sa v koreňovom adresári projektu vytvára priečinok icons/ na uloženie všetkých ikon, pretože sa v skutočnosti nepočítajú ako zdrojové súbory.

Po nainštalovaní ikon (pre Linux) a ich zbalení (pre Windows a Android) ich môžete nastaviť v kóde. V QML kóde by ste pre kompatibilitu so systémami Windows aj Android mali použiť zbalenú ikonu; v C++ kóde, najmä pri nastavovaní ikony okna, môžete predvolene použiť ikonu témy a zbalenú ikonu ako záložnú pre QGuiApplication::setWindowIcon():

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

Ikony Kirigami

Aj keď Android nemá štandardný adresár, kam inštalovať ikony z témy ikon, je možné zbaliť potrebné ikony Kirigami spolu s vašou aplikáciou pre Android.

Na to sú potrebné dve veci:

  • Pripravte projekt s KIconThemes
  • Zahrňte breeze-icons do svojho blueprintu Craft
  • kirigami_package_breeze_icons()

Na nastavenie KIconThemes pozrite vyššie uvedenú sekciu KIconThemes.

Ak chcete pridať breeze-icons ako závislosť vášho projektu, pridajte toto do svojho blueprintu Craft:

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

Vzhľadom na spôsob zostavovania pre Android nie je možné, aby Craft zbalil ikony automaticky. Kirigami preto poskytuje funkciu CMake kirigami_package_breeze_icons(), ktorá pri zostavovaní naklonuje a pripraví ikony na zbalenie. Tento príkaz musí byť pred krokom opísaným vo Funkcia CMake na zbalenie pre Android.

Príkaz CMake kirigami_package_breeze_icons() netreba obaliť podmienkou, pretože sa vždy spúšťa iba na Androide.

Ak vo svojej aplikácii používate Kirigami Addons, môžete navyše odovzdať premennú ${KIRIGAMI_ADDONS_ICONS}, aby sa dodali aj ikony potrebné pre komponenty ako FormCard.AboutPage a podobné.

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

Manifest pre Android

Manifest pre Android je XML súbor, ktorý opisuje aplikáciu pre zostavovacie nástroje Androidu, operačný systém a obchody. Súbor sa musí volať AndroidManifest.xml.

Qt používa manifest pre Android a podporuje ďalšiu konfiguráciu na spustenie nástrojov potrebných na zostavenie APK, ktoré sa dá nainštalovať na Android.

Aplikácie KDE uchovávajú manifest v adresári android/ v koreni projektu.

Manifest pre Android môže vyzerať takto:

<?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>

Ide prevažne o šablónový kód, ktorý sa dá skopírovať a upraviť pre existujúci projekt, ale oplatí sa vedieť, na ktoré časti treba dávať pozor.

V značke <manifest> zodpovedá package názvu, ktorým Android aplikáciu interne identifikuje. Musí používať obrátený zápis DNS. Mal by sa zhodovať s ID aplikácie zadaným v kóde.

V značkách <application> a <activity> by android:label mal byť názov aplikácie zobrazovaný používateľovi. V značke <meta-data> by sa android:value mal zhodovať s názvom cieľa zadaným v CMake.

V značke <application> by android:icon="@drawable/myapp" mala byť ikona uložená v android/res/drawable/ bez prípony súboru. V tomto príklade by súbor bol android/res/drawable/myapp.png. Priečinok res znamená „resources“ (zdroje). Ak nie je zadaná, v ponuke aplikácií a pri výzve na inštaláciu sa namiesto nej zobrazí predvolená zástupná ikona Androidu.

Activity predstavuje, čo bude aplikácia robiť v rôznych stavoch. Napríklad môže vykonávať určité akcie v popredí a iné akcie na pozadí. Aplikácia Qt/KDE má zvyčajne iba jednu aktivitu.

Každá aktivita môže mať jeden alebo viac filtrov zámerov. Zámer (Intent) je niečo, čo aktivita dokáže urobiť, čo je v prípade aplikácie KDE zvyčajne akcia, ale môže to byť aj služba. Napríklad ak má aplikácia v úmysle sa spustiť, musí Androidu oznámiť, že táto aktivita je vstupným bodom aplikácie (android.intent.action.MAIN) a že zámer je typu LAUNCHER, aby sa zobrazila v ponuke aplikácií a dala sa spustiť. Pre väčšinu aplikácií KDE by to vo všeobecnosti malo stačiť.

Značka <meta-data> sa môže opakovať viackrát a mať viacero účelov a možno použiť špeciálne konfigurácie špecifické pre Qt. Metadáta android.app.lib_name sú povinné.

Značka <uses-permission> je jednoduchá a umožňuje aplikácii požiadať o povolenie vykonať určitú akciu. Povolenie sa líši od zámeru tým, že zámer žiada iný komponent o vykonanie akcie súvisiacej s aktivitou, zatiaľ čo povolenie je žiadosť o prístup k funkcii, ktorá predvolene nie je dostupná.

Značka <supports-screens> určuje, ktoré tvarové faktory (veľkosti obrazovky a hustoty pixelov, telefóny alebo tablety) aplikácia podporuje. Keďže aplikácie QML sú konvergentné, „ľubovoľná veľkosť“ by mala byť rozumná predvolená hodnota.

Jediné časti vyššie uvedeného príkladu, ktoré nie sú povinné, sú android:icon="@drawable/myapp" (použije sa iba vtedy, ak vaša aplikácia už má ikonu) a <uses-permissions> (ktoré by sa mali pridať iba vtedy, keď sú skutočne potrebné).

Úvodná obrazovka

Úvodná obrazovka je voliteľná obrazovka so statickým obrázkom alebo animáciou, ktorá sa zobrazí pri spustení aplikácie, aby mala aplikácia niekoľko sekúnd na inicializáciu. Ak úvodná obrazovka nie je zadaná, aplikácia sa zobrazí hneď po otvorení, aj keď nie je pripravená.

Ak ju chcete pridať do svojej aplikácie, musíte ju zadať v metadátach AndroidManifest.xml:

<meta-data android:name="android.app.splash_screen_drawable" android:resource="@drawable/splash"/>

Následne musí existovať súbor 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>

Tento jednoduchý príklad, bežne používaný v aplikáciách KDE, vycentruje ikonu aplikácie na prázdnom pozadí, takže je potrebná ikona aplikácie umiestnená v android/res/drawable/.

Príprava APK

Posledný krok potrebný na samotné zostavenie APK pre Android je jednoduchá funkcia CMake, ktorá používa súbory v adresári android/:

ecm_add_android_apk(myapp
    ANDROID_DIR ${PROJECT_SOURCE_DIR}/android
)

Verzia profilu

Na zostavenie vašej aplikácie pre Android postupujte podľa Zostavovanie aplikácií pre Android.

Zostavenia CI

Ak bol projekt správne nakonfigurovaný na zostavenie v systéme Windows a používa infraštruktúru KDE na hosťovanie kódu (KDE Invent), je možné nakonfigurovať CI/CD úlohy pre Android.

Na to budete musieť pridať príslušné CI šablóny pre Windows so súborom .gitlab-ci.yaml a uviesť vaše závislosti v súbore .kde-ci.yaml, ako je uvedené v časti Systém kontinuálnej integrácie.