Nastavenie 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í:
- Plán Craft
- Nastavenie qqc2-breeze-style
- Ikony zabalené s aplikáciou
- Manifest pre Android
- Voliteľne zostavovací súbor Gradle
- Voliteľne XML súbor úvodnej obrazovky
- Funkcia CMake na zbalenie pre Android
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"] = NonePodobnú 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
}Použitie KirigamiAppDefaults
Ak používate KirigamiAppDefaults::Apply(), vyššie uvedený C++ kód je už za vás vyriešený.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.
Použitie KirigamiAppDefaults
Ak používate KirigamiAppDefaults::Apply(), vyššie uvedená inicializácia KIconThemes v C++ kóde je už za vás vyriešená.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"] = NoneVzhľ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.