إعداد أندرويد
مقدمة
تدعم Qt أندرويد دعمًا ممتازًا، لكن التطبيقات تتطلب قدرًا كبيرًا من التعديلات لتعمل بشكل صحيح على أندرويد.
هناك بضعة أشياء مطلوبة:
- مخطط كرافت
- ضبط qqc2-breeze-style
- أيقونات مرفقة مع التطبيق
- بيان أندرويد
- اختياريًا ملف بناء Gradle
- اختياريًا ملف XML لشاشة البداية
- دالة CMake للتجميع لأندرويد
مخطط Craft مطلوب لحزم جميع التبعيات مع التطبيق لتوليد حزمة APK لأندرويد.
qqc2-breeze-style بديل عن qqc2-desktop-style وهو موجَّه خصيصًا للمنصات المحمولة مثل أندرويد وبلازما الجوال.
يحتاج مخطط Craft للتطبيق إلى شيفرة شرطية لعدم خلط تنسيق سطح المكتب والتنسيق المحمول، بينما تحتاج شيفرة C++ إلى عناية خاصة لعدم استخدام الإعداد الخاطئ لسطح المكتب والمحمول. قد تحتاج شيفرة CMake أيضًا اختياريًا إلى شيفرة شرطية، رغم أنه يمكن تجنب ذلك.
تُحزم الأيقونات اللازمة لعمل التطبيق بمساعدة extra-cmake-modules من كيدي، وأدوات حزم موارد Qt، بالإضافة إلى دوال CMake من Kirigami وKirigami Addons.
يعلن بيان أندرويد البيانات الوصفية والملفات الإضافية التي يجب حزمها مع تطبيق أندرويد.
ملف بناء Gradle مطلوب في حال استخدام تكامل extra-cmake-modules لتطبيق البيانات الوصفية الموجودة في تطبيقك على بناء أندرويد، مثل إصدار التطبيق، أو في حال رغبتك في خيارات بناء خاصة.
ملف XML لشاشة البداية مطلوب في حال رغبتك في إضافة شاشة بداية بأيقونة وخلفية وتموضع مخصصة.
مخطط كرافت
ضبط qqc2-breeze-style
لبدء استخدام qqc2-breeze-style، ستحتاج إلى إضافته إلى Craft. ولأنه يُستخدم لأندرويد فقط، فسيتطلب شرطًا، خاصة إذا كان التطبيق معدًّا بالفعل للبناء على ويندوز و/أو لينكس باستخدام نمط qqc2-desktop. يتطلب ذلك استيراد وحدة 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يجب تطبيق منطق مشابه هو "إن لم يكن أندرويد، استخدم 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++.
على أندرويد، لا تستخدم تطبيقات كيدي QApplication، بل QGuiApplication. بالإضافة إلى ضبط qqc2-breeze-style لأندرويد فقط، يجب التعامل مع ترتيب التهيئة في الحالة المرجحة جدًا التي يكون فيها تطبيقك متوافقًا بالفعل مع سطح المكتب. يمكن تحقيق ذلك هكذا:
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).
كي أيقونة ثيمات
يمكن القيام بذلك عبر:
- إضافته كتبعية في كرافت:
def setDependencies(self):
self.runtimeDependencies["kde/frameworks/tier3/kiconthemes"] = None- إضافته كتبعية في سيمايك:
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 وكجزء من تثبيت الأيقونات معًا.
عادةً على لينكس، يمكن ببساطة تثبيت أيقونة التطبيق في الدليل الصحيح، وسيتم جلب الأيقونة بواسطة التطبيق عند الحاجة. تتكون أيقونة التطبيق عادةً من أيقونة 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)عند تثبيت أيقونة التطبيق على لينكس، تذهب أيقونة 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.
لا يمتلك أندرويد مجلدًا قياسيًا كهذا، وتثبيت الأيقونة لا أثر له؛ يجب حزمها مع التطبيق. للقيام بذلك، يمكن إرسال ملف 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/ في جذر المشروع لتخزين جميع الأيقونات، لأنها لا تُعد فعليًا ملفات مصدر.
بعد تثبيت الأيقونات (لينكس) وحزمها (ويندوز وأندرويد)، يمكنك ضبطها في الشيفرة. في شيفرة QML، للتوافق مع ويندوز وأندرويد معًا، ينبغي استخدام الأيقونة المحزومة؛ وفي شيفرة C++، لا سيما عند ضبط أيقونة النافذة، يمكنك استخدام أيقونة السمة مبدئيًا والأيقونة المحزومة كبديل احتياطي لـ QGuiApplication::setWindowIcon():
QGuiApplication::setWindowIcon(QIcon::fromTheme("org.kde.myapp", QIcon(":/qt/qml/org/kde/myapp/org.kde.myapp.svg")));أيقونات كيريغامي
رغم أن أندرويد لا يمتلك مجلدًا قياسيًا لتثبيت الأيقونات من سمة أيقونات، فمن الممكن حزم أيقونات Kirigami اللازمة مع تطبيق أندرويد الخاص بك.
يلزم أمران للقيام بذلك:
- تحضير المشروع باستخدام KIconThemes
- تضمين breeze-icons في مخطط Craft الخاص بك
- kirigami_package_breeze_icons()
لإعداد KIconThemes، راجع القسم أعلاه KIconThemes.
لإضافة breeze-icons كتبعية لمشروعك، أضف هذا إلى مخطط Craft الخاص بك:
def setDependencies(self):
# ...
self.runtimeDependencies["kde/frameworks/tier1/breeze-icons"] = Noneبسبب طريقة إجراء بناء أندرويد، لا يمكن لـ Craft أن يحزم الأيقونات آليًا. لذلك توفر Kirigami دالة CMake هي kirigami_package_breeze_icons() التي تستنسخ الأيقونات وتحضرها للحزم في وقت البناء. يجب أن يأتي هذا الأمر قبل الخطوة المفصلة في دالة CMake للتجميع لأندرويد.
لا يحتاج أمر CMake kirigami_package_breeze_icons() إلى تغليفه بشرط، لأنه لا يعمل إلا على أندرويد.
إضافةً إلى ذلك، إن كنت تستخدم إضافات Kirigami في تطبيقك، يمكنك تمرير المتغير ${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}
)بيان أندرويد
بيان أندرويد هو ملف XML يصف التطبيق لأدوات بناء أندرويد ونظام التشغيل والمتاجر. يجب أن يُسمّى الملف AndroidManifest.xml.
يستخدم Qt بيان أندرويد ويدعم إعدادات إضافية لاستدعاء الأدوات اللازمة لبناء APK يمكن تثبيته على أندرويد.
تحفظ تطبيقات كيدي البيان في مجلد 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 الاسم الذي يعرّف به أندرويد التطبيق داخليًا. يجب أن يستخدم ترميز DNS العكسي. وينبغي أن يطابق معرّف التطبيق المحدد في الشيفرة.
في وسوم <application> و<activity>، ينبغي أن يكون android:label اسم التطبيق الظاهر للمستخدم. وفي وسم <meta-data>، ينبغي أن يطابق android:value اسم الهدف كما هو محدد في CMake.
في وسم <application>، ينبغي أن تكون android:icon="@drawable/myapp" أيقونة مخزنة في android/res/drawable/ دون امتداد الملف. في هذا المثال، سيكون الملف android/res/drawable/myapp.png. ويشير مجلد res إلى "الموارد". وإن لم تُحدَّد، ستُعرض أيقونة أندرويد النائبة المبدئية في قائمة التطبيقات وفي موجه التثبيت بدلًا منها.
يمثّل النشاط ما سيفعله التطبيق في حالات مختلفة. فمثلًا، قد ينفذ إجراءات معينة في المقدمة وإجراءات أخرى في الخلفية. وعادةً ما يملك تطبيق Qt/كيدي نشاطًا واحدًا فقط.
يمكن أن يملك كل نشاط مرشّح نوايا واحدًا أو أكثر. والنوايا هي ما يستطيع النشاط فعله، وهو في حالة تطبيق كيدي عادةً إجراء، لكنه قد يكون خدمة أيضًا. فمثلًا، إن كانت النية إطلاق التطبيق، فعليه أن يشير إلى أندرويد بأن هذا النشاط هو نقطة دخول التطبيق (android.intent.action.MAIN) وأن النية من نوع LAUNCHER لتظهر في شاشة قائمة التطبيقات وتكون قابلة للإطلاق. وهذا يكفي عمومًا لمعظم تطبيقات كيدي.
يمكن تكرار وسم <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>هذا المثال البسيط الشائع في تطبيقات كيدي يوسّط أيقونة التطبيق في خلفية فارغة، لذا تلزم أيقونة تطبيق موجودة في android/res/drawable/.
تحضير APK
الخطوة الأخيرة اللازمة فعلًا للسماح ببناء APK لأندرويد هي دالة CMake بسيطة تستخدم الملفات في مجلد android/:
ecm_add_android_apk(myapp
ANDROID_DIR ${PROJECT_SOURCE_DIR}/android
)البناء
لبناء تطبيقك على أندرويد، اتبع بناء التطبيقات لأندرويد.
بنيات CI
إن كان المشروع مضبوطًا جيدًا للبناء على ويندوز ويستخدم بنية كيدي لاستضافة شيفرته (KDE Invent)، فمن الممكن ضبط مهام CI/CD لأندرويد.
للقيام بذلك، ستحتاج إلى إضافة قوالب CI ذات الصلة لويندوز مع ملف .gitlab-ci.yaml وسرد اعتمادياتك في ملف .kde-ci.yaml كما هو مذكور في نظام التكامل المستمر.