– الشروع في العمل مع كيريغامي

Docs: الإعداد باستخدام C++

Mon, 01 Jan 0001 00:00:00 +0000

تنصيب كيريغامي

قبل البدء، سنحتاج إلى تنصيب كيريغامي على جهازنا. هناك ثلاث طرق لفعل ذلك:

تنصيب كيريغامي من المستودعات في توزيعة لينكس الخاصة بك
استخدام kde-builder
تنصيب كيريغامي باستخدام كرافت

إذا كنت على توزيعة محدثة بما يكفي مثل دبيان تيستينغ، أو أحدث إصدار غير LTS من أوبونتو، أو فيدورا، أو openSUSE Tumbleweed، أو آرتش، فيمكنك تنصيب كيريغامي من توزيعتك.

إذا كنت على توزيعة غير محدثة مثل دبيان ستيبل أو أوبونتو LTS، فيجب عليك استخدام kde-builder لهذا الدليل. من المفترض أن يستخدم 2 جيجابايت كحد أقصى من التخزين.

تنصيب كيريغامي من المستودعات في توزيعة لينكس الخاصة بك

نحتاج إلى مترجم C++، وحزم تطوير كيوت، وكيريغامي. افتح تطبيق طرفية وشغّل أحد الأوامر التالية، اعتمادًا على توزيعة لينكس التي تستخدمها:

Kubuntu KDE Neon	sudo apt install build-essential cmake extra-cmake-modules libkirigami-dev libkf6i18n-dev libkf6coreaddons-dev libkf6iconthemes-dev qt6-base-dev qt6-declarative-dev libkf6qqc2desktopstyle-dev
Manjaro Arch	sudo pacman -S base-devel extra-cmake-modules cmake kirigami ki18n kcoreaddons breeze kiconthemes qt6-base qt6-declarative qqc2-desktop-style
OpenSUSE	sudo zypper install cmake kf6-extra-cmake-modules kf6-kirigami-devel kf6-ki18n-devel kf6-kcoreaddons-devel kf6-kiconthemes-devel qt6-base-devel qt6-declarative-devel qt6-quickcontrols2-devel kf6-qqc2-desktop-style
Fedora	sudo dnf install @development-tools @development-libs cmake extra-cmake-modules kf6-kirigami2-devel kf6-ki18n-devel kf6-kcoreaddons-devel kf6-kiconthemes-devel qt6-qtbase-devel qt6-qtdeclarative-devel qt6-qtquickcontrols2-devel kf6-qqc2-desktop-style

يمكن العثور على مزيد من المعلومات للتوزيعات الأخرى في تنصيب تبعيات البناء.

استخدام kde-builder

اضبط بيئة التطوير الخاصة بك باستخدام kde-builder. سيمنحك ذلك أدوات التطوير الضرورية والمكتبات الأساسية، ويبني أطر عمل كيدي من الصفر.

أنشئ مجلدًا ~/kde/src/kirigami-tutorial. في ذلك المجلد ستضع ملفات الشيفرة المصدرية من هذا الدليل.

أضف ما يلي في نهاية ملف ~/.config/kde-builder.yaml:

project kirigami-tutorial:
 no-src: true

⏳ مع kdesrc-build...

انقر هنا لتعرف كيف أُنجز هذا باستعمال kdesrc-build

كانت هذه الخطوة تُنجز سابقًا بالكتابة إلى ~/.config/kdesrc-buildrc بدلًا من ذلك بصيغة مختلفة:

# after include ${module-definitions-dir}/kf6-qt6.ksb
module kirigami-tutorial
no-src
end module

تنصيب كيريغامي باستخدام كرافت

لدى كيدي أداة مخصصة لتنصيب معظم مكتباتها وبرامجها بسهولة: كرافت. يمكن استخدامها لتنصيب كيريغامي على ويندوز وأندرويد وماك أو إس.

بينما كرافت متاح أيضًا للينكس وفري بي إس دي، فإن استخدامه المقصود هو فقط لصور التطبيقات AppImages والتغليف.

ستحتاج إلى اتباع تعليمات إعداد كرافت. بنهاية الإعداد، يجب أن تكون قد شغّلت ملف إعداد البيئة (craftenv.ps1 على ويندوز، أو craftenv.sh على جميع المنصات الأخرى)، والذي سيمنحك صدفة طرفية حيث ستُجمّع تطبيق كيريغامي الخاص بك.

بعد ذلك، يمكنك تشغيل ما يلي على طرفية:

craft kirigami kcoreaddons ki18n breeze kiconthemes qqc2-desktop-style

سيستغرق هذا بعض الوقت للانتهاء عند التشغيل الأول. إذا أغلقت طرفيتك، يمكنك تشغيل ملف إعداد البيئة لتجهيز طرفيتك مرة أخرى.

هيكل المشروع

بينما توجد أدوات يمكنها إعداد ملفاتنا بسهولة، سنقوم بإنشائها يدويًا. سيسمح لنا هذا بفهم أفضل للقطع التي ستُشكّل تطبيقنا الجديد.

أولاً ننشئ مجلد مشروعنا (يمكنك استخدام الأوامر أدناه). سنسمي مجلدنا kirigami-tutorial/.

kirigami-tutorial/
├── CMakeLists.txt
├── org.kde.tutorial.desktop
└── src/
├── CMakeLists.txt
├── main.cpp
└── Main.qml

ضمن هذا المجلد سننشئ مجلد src/ وملف CMakeLists.txt. من الممارسات الجيدة عمومًا وضع جميع ملفات شيفرة C++ الرئيسية في مجلد src/. نضع أيضًا ملف Main.qml فيه لأنه سيُشغَّل مع الملف التنفيذي.

تلميح

يمكنك إنشاء هيكل الملفات هذا بسرعة باستخدام:

mkdir -p kirigami-tutorial/src
touch kirigami-tutorial/{CMakeLists.txt,org.kde.tutorial.desktop}
touch kirigami-tutorial/src/{CMakeLists.txt,main.cpp,Main.qml}

ملاحظة

في حال أردت بناء المشروع آليًا باستخدام kde-builder، يجب أن يكون اسم الوحدة المخصصة مطابقًا لمجلد جذر المشروع (في حالتنا سيكون "kirigami-tutorial")، وإلا فستحتاج إلى تخصيص source-dir أو dest-dir للوحدة. سنفترض أن مسار main.cpp سيكون ~/kde/src/kirigami-tutorial/src/main.cpp.

Main.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


// Includes relevant modules used by the QML
import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

// Provides basic features needed for all kirigami applications
Kirigami.ApplicationWindow {
 // Unique identifier to reference this object
 id: root

 width: 400
 height: 300

 // Window title
 // i18nc() makes a string translatable
 // and provides additional context for the translators
 title: i18nc("@title:window", "Hello World")

 // Set the first page that will be loaded when the app opens
 // This can also be set to an id of a Kirigami.Page
 pageStack.initialPage: Kirigami.Page {
 Controls.Label {
 // Center label horizontally and vertically within parent object
 anchors.centerIn: parent
 text: i18n("Hello World!")
 }
 }
}

هنا سنتعامل مع الواجهة الأمامية لتطبيقنا.

إذا كنت تعرف بعض Javascript، فسيبدو لك الكثير من QML مألوفًا (رغم أن له خصائصه الخاصة). توثيق Qt يحتوي على كمية هائلة من المواد حول هذه اللغة إذا شعرت برغبة في تجربة شيء بنفسك. خلال هذه الدروس سنركز كثيرًا على شيفرة QML الخاصة بنا، حيث يمكننا استخدام Kirigami للاستفادة القصوى منها.

الآن، لنركز على Main.qml. أولاً نستورد عددًا من الوحدات المهمة:

QtQuick، المكتبة القياسية المستخدمة في تطبيقات QML.
QtQuick Controls، التي توفر عددًا من عناصر التحكم القياسية التي يمكننا استخدامها لجعل تطبيقاتنا تفاعلية.
QtQuick Layouts، التي توفر أدوات لوضع المكونات داخل نافذة التطبيق.
Kirigami، التي توفر عددًا من المكونات المناسبة لإنشاء تطبيقات تعمل عبر أجهزة بأشكال وأحجام مختلفة.

ملاحظة

وضع استيرادات QtQuick Controls وKirigami في نطاقات أسماء منفصلة باستخدام الكلمة المفتاحية as هو ممارسة مثلى تضمن عدم تعارض أي مكونات بنفس الاسم. قد ترى أسماء مختلفة لـ QtQuick Controls في الممارسة العملية، مثل "QQC" أو "QQC2". سنستخدم "Controls" في هذا الدليل للوضوح.

ثم نصل إلى العنصر الأساسي لدينا، Kirigami.ApplicationWindow، الذي يوفر بعض الميزات الأساسية اللازمة لجميع تطبيقات Kirigami. هذه هي النافذة التي ستحتوي كل صفحة من صفحاتنا، الأقسام الرئيسية لواجهة المستخدم لدينا.

ثم نضبط خاصية id للنافذة على "root". المعرفات مفيدة لأنها تسمح لنا بالإشارة بشكل فريد إلى مكون، حتى لو كان لدينا عدة مكونات من نفس النوع.

نضبط أيضًا خاصية title للنافذة على "Hello World". ستلاحظ أننا لففنا السلسلة النصية "Hello World" في دالة تسمى i18nc()، حيث نفصل سياق السلسلة النصية بالإضافة إلى السلسلة نفسها.

ملاحظة

دوال i18n() تجعل تطبيقك أكثر قابلية للترجمة، لأنها تُرجع نسخة من السلسلة النصية المقدمة بلغة المستخدم (طالما تم توطين تطبيقك لتلك اللغة). بينما قد يرى مستخدم إنجليزي عنوان نافذتنا كـ "Hello World"، سيرى مستخدم إسباني "Hola Mundo".

دالة i18nc() تبني على دالة i18n() بالسماح للمطورين بتقديم بعض السياق للمترجمين العاملين على التطبيق. هنا نوضح أن مكون واجهة المستخدم هو عنوان نافذة التطبيق، لذا أدرجنا السلسلة النصية "@title:window" قبل "Hello World". راجع دليل مبرمج Ki18n لمزيد من التفاصيل.

ثم نضبط الصفحة الأولى من رصة الصفحات لدينا. معظم تطبيقات Kirigami منظمة كرصة من الصفحات، كل صفحة تحتوي على مكونات ذات صلة مناسبة لمهمة محددة. حاليًا، نبقي الأمر بسيطًا ونلتزم بصفحة واحدة. pageStack هي رصة صفحات فارغة في البداية مقدمة من Kirigami.ApplicationWindow، وباستخدام pageStack.initialPage: Kirigami.Page {...} نضبط الصفحة الأولى المعروضة عند تحميل التطبيق على Kirigami.Page. هذه الصفحة ستحتوي على كل محتوانا.

أخيرًا، نضمن في صفحتنا Controls.Label الذي يسمح لنا بوضع نص على صفحتنا. نستخدم anchors.centerIn: parent لتوسيط التسمية أفقيًا وعموديًا داخل العنصر الأب. في هذه الحالة، المكون الأب لتسميتنا هو Kirigami.Page. آخر شيء نحتاج إلى فعله هو ضبط نصها: text: i18n("Hello World!").

org.kde.tutorial.desktop

الغرض الأساسي من ملفات إدخال سطح المكتب هو عرض تطبيقك على مشغل التطبيقات في لينكس. سبب آخر لامتلاكها هو الحصول على أيقونات النوافذ على Wayland، حيث إنها مطلوبة لإخبار المُركِّب "هذه النافذة تذهب مع هذه الأيقونة".

يجب أن يتبع نظام تسمية DNS عكسي متبوعًا بالامتداد .desktop مثل org.kde.tutorial.desktop:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


[Desktop Entry]
Name=Kirigami Tutorial
Name[ar]=درس كيريغامي
Name[ca]=Guia d'aprenentatge del Kirigami
Name[cs]=Tutoriál Kirigami
Name[eo]=Lernilo pri Kirigami
Name[es]=Tutorial de Kirigami
Name[fr]=Tutoriel pour Kirigami
Name[it]=Esercitazione di Kirigami
Name[nl]=Kirigami handleiding
Name[pt_BR]=Tutorial do Kirigami
Name[ro]=Îndrumar Kirigami
Name[sk]=Tutoriál Kirigami
Name[sl]=Učbenik Kirigami
Name[sv]=Kirigami-handledning
Name[tr]=Kirigami Öğreticisi
Name[uk]=Підручник з Kirigami
Name[zh_TW]=Kirigami 教學
Exec=kirigami-hello
Icon=kde
Type=Application
Terminal=false
Categories=Utility

ملاحظة

أيقونات النوافذ وشريط المهام ستعمل في جلسة Wayland فقط إذا وُضعت ملفات سطح المكتب للتطبيقات في ~/.local/share/applications أو /usr/share/applications. لجعل الأيقونات تعمل في هذا الدليل، إما انسخ ملف سطح المكتب للتطبيق هناك أو انتقل إلى جلسة تطوير كما هو موضح في دليل kde-builder. بعض تطبيقات كيدي قد تحتوي على أيقونات عاملة إذا كانت مثبتة بالفعل على النظام.

CMakeLists.txt

ملفات CMakeLists.txt مطلوبة لاستخدام نظام البناء المفضل لكيدي، CMake. ملف kirigami-tutorial/CMakeLists.txt الخاص بنا سيحدد بعض خصائص تطبيقنا. كما يتضمن بعض التبعيات التي نحتاجها لتجميع مشروعنا.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


cmake_minimum_required(VERSION 3.20)
project(kirigami-tutorial)

find_package(ECM 6.0.0 REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)
include(ECMFindQmlModule)
include(ECMQmlModule)

find_package(Qt6 REQUIRED COMPONENTS
 Core
 Quick
 Test
 Gui
 QuickControls2
 Widgets
)

find_package(KF6 REQUIRED COMPONENTS
 Kirigami
 I18n
 CoreAddons
 QQC2DesktopStyle
 IconThemes
)

ecm_find_qmlmodule(org.kde.kirigami REQUIRED)

add_subdirectory(src)

install(PROGRAMS org.kde.tutorial.desktop DESTINATION ${KDE_INSTALL_APPDIR})

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

ملف CMakeLists.txt يحدد كيفية بناء مشاريعك. معظم المحتوى هنا هو فقط لتهيئة مشروعك. يمكنك قراءة شرح سطر بسطر ومتعمق لما يفعله ملف CMakeLists هذا هنا.

أهم شيء يجب تذكره هو أن تبعيات بناء C++ لـ Qt وأطر كيدي تُدار باستخدام find_package() وتبعيات وقت تشغيل QML تُدار باستخدام ecm_find_qml_module(). ستحتاج إلى تعديل هذه الأسطر وتضمين أي مكونات إضافية تقرر استخدامها أثناء تطوير تطبيقك.

السطر الذي يحتوي على add_subdirectory(src) يوجه CMake إلى الدليل kirigami-tutorial/src/، حيث توجد شيفرتنا المصدرية.

يخبر السطر الذي يحتوي على install() CMake أين يُثبّت ملف سطح المكتب.

لنتعمق في ملف kirigami-tutorial/src/CMakeLists.txt الموجود هناك.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


add_executable(kirigami-hello)

ecm_add_qml_module(kirigami-hello
 URI
 org.kde.tutorial
)

target_sources(kirigami-hello
 PRIVATE
 main.cpp
)

ecm_target_qml_sources(kirigami-hello
 SOURCES
 Main.qml
)

target_link_libraries(kirigami-hello
 PRIVATE
 Qt6::Quick
 Qt6::Qml
 Qt6::Gui
 Qt6::QuickControls2
 Qt6::Widgets
 KF6::I18n
 KF6::CoreAddons
 KF6::IconThemes
)

install(TARGETS kirigami-hello ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

يتألف هذا الملف من خمس خطوات:

أنشئ ملفًا تنفيذيًا
حوِّل الملف التنفيذي إلى وحدة QML تقبل ملفات QML
أضف ملفات C++ وQML إلى الملف التنفيذي
اربط المكتبات اللازمة لتشغيل الملف التنفيذي
ثبِّت الملف التنفيذي في المكان الصحيح

في المرة القادمة التي تحتاج فيها إلى إضافة المزيد من ملفات QML، أضفها إلى استدعاء ecm_target_qml_sources() الموجود. يمكن إضافة ملفات C++ التي تستخدم الكلمة المفتاحية QML_ELEMENT والتي سنراها لاحقًا في الدليل باستخدام target_sources().

والآن بعد أن عُولج أمر CMake، دعنا ننظر إلى الملفات التي سنقضي معظم وقتنا في العمل بها.

main.cpp

يتولى الملف kirigami-tutorial/src/main.cpp معالجة "منطق الأعمال" لتطبيقنا. C++ مفيدة لأنها مرنة وسريعة، حتى وإن كانت أكثر تعقيدًا من لغات البرمجة الأخرى.

وتعمل أيضًا كنقطة دخول إلى تطبيقنا. يُعد الجزآن من مشروعنا، الواجهة الخلفية وواجهة المستخدم، ويُبدآن هنا.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


#include <QApplication>
#include <QQmlApplicationEngine>
#include <QtQml>
#include <QUrl>
#include <QQuickStyle>
#include <KLocalizedContext>
#include <KLocalizedString>
#include <KIconTheme>

int main(int argc, char *argv[])
{
 KIconTheme::initTheme();
 QApplication app(argc, argv);
 KLocalizedString::setApplicationDomain("tutorial");
 QApplication::setOrganizationName(QStringLiteral("KDE"));
 QApplication::setOrganizationDomain(QStringLiteral("kde.org"));
 QApplication::setApplicationName(QStringLiteral("Kirigami Tutorial"));
 QApplication::setDesktopFileName(QStringLiteral("org.kde.tutorial"));

 QApplication::setStyle(QStringLiteral("breeze"));
 if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE")) {
 QQuickStyle::setStyle(QStringLiteral("org.kde.desktop"));
 }

 QQmlApplicationEngine engine;

 engine.rootContext()->setContextObject(new KLocalizedContext(&engine));
 engine.loadFromModule("org.kde.tutorial", "Main");

 if (engine.rootObjects().isEmpty()) {
 return -1;
 }

 return app.exec();
}

في الوقت الحالي، لا نحتاج إلى الخوض في تفاصيل كثيرة حول ما يفعله كود main.cpp الخاص بنا، لكن دوره سيزداد أهمية بشكل ملحوظ بمجرد أن نقرر إضافة وظائف أكثر تعقيدًا إلى تطبيقنا في المستقبل.

تطبيق السمة على ويندوز

انقر هنا لقراءة المزيد

يحتاج التطبيق إلى ضبط سمة الأيقونات ونمط QStyle ونمط عناصر تحكم QtQuick على Breeze ليظهر على ويندوز. لمعرفة المزيد عن ذلك، انظر فهم main.cpp.

إذا أردت التقدم، يمكنك قراءة المزيد عن كيفية عمل هذا main.cpp في فهم main.cpp.

إذا أردت رؤية بعض الطرق لتحسين كود C++، مثل استخدام KAboutData لبيانات تعريف التطبيق القابلة للترجمة، فتأكد من الاطلاع على دليل KXmlGui.

في الوقت الحالي، الجزء الذي يهمنا هو هذا السطر:

engine.loadFromModule("org.kde.tutorial", "Main");

الوسيط الأول هو URI المُضبَط في kirigami-tutorial/src/CMakeLists.txt، والوسيط الثاني هو اسم وحدة QML التي نريد استخدامها (Main، آتٍ من اسم ملف Main.qml الخاص بنا، والذي يجب أن يبدأ بحرف كبير).

الطريقة القديمة

قد تصادف هذه الطريقة البديلة لتحميل ملفات QML في الكود الحقيقي!

كانت الطريقة القديمة لتحميل ملفات QML تعاني من بعض العيوب، وبعد Qt6 أصبحت مطولة بشكل مفرط:

engine.load(QUrl(QStringLiteral("qrc:/qt/qml/org/kde/tutorial/qml/Main.qml")));

يتبع URI مورد Qt أعلاه النمط <resource_prefix><import_URI><optional_QML_dir><file>. في هذه الحالة:

بادئة المورد = / الافتراضي في Qt5، /qt/qml في Qt6
URI الاستيراد = /org/kde/tutorial، والذي يطابق URI org.kde.tutorial
دليل QML الاختياري = /qml، ضروري إذا خُزنت ملفات QML في دليل يُسمى qml/
الملف = ملف QML

ترجمة التطبيق وتثبيته

نحن على وشك الوصول إلى خط النهاية. آخر شيء نحتاج إلى فعله هو بناء تطبيقنا وتشغيله. سيعتمد فعل ذلك على المنصة التي تستخدمها.

لينكس أو فري بي إس دي

الترجمة باستخدام kde-builder

تأكد من اتباع التعليمات في استخدام kde-builder.

اربط تبعيات البناء الضرورية باستخدام kde-builder، ثم اربط kirigami-tutorial بتشغيل الأوامر التالية في طرفية:

kde-builder kirigami ki18n kcoreaddons breeze kiconthemes qqc2-desktop-style
kde-builder kirigami-tutorial

الربط يدويًا

غيّر الأدلة إلى المجلد الجذري للمشروع، ثم شغّل الأمر التالي في طرفية:

cmake -B build/ --install-prefix ~/.local
cmake --build build/
cmake --install build/

سيُثبّت البرنامج في ~/.local/bin ومدخل سطح المكتب في ~/.local/share/applications.

ويندوز

إذا كنت تربط مشروعك على ويندوز بعد إعداد Craft، فيجب على CMake أن يكشف المصرّف الصحيح آليًا:

cmake -B build/
cmake --build build/
cmake --install build/

اعتمادًا على كيفية تثبيتك للمصرّف، قد تحتاج إلى تحديد مولد CMake للخطوة الأولى، اعتمادًا على ما إذا كنت تستخدم Visual Studio (msvc) أو MinGW (make) لربط مشاريعك.

إذا كان Visual Studio، اعتمادًا على المصرّف الذي اخترت تثبيته، فقد يكون:

cmake -B build/ -G "Visual Studio 16 2019"

أو:

cmake -B build/ -G "Visual Studio 17 2022"

إذا كان MinGW:

cmake -B build/ -G "MinGW Makefiles"
cmake --build build/
cmake --install build/

في كلتا الحالتين، سيُثبّت البرنامج في C:\CraftRoot\bin.

إذا شككت يومًا في اسم المصرّف الذي يجب استخدامه في استدعاء cmake، فشغّل:

cmake -G

سيسرد جميع المولدات المتاحة.

تشغيل التطبيق

يمكنك بعد ذلك تشغيل برنامج kirigami-hello بـ:

kirigami-hello # على لينكس، يدويًا
kde-builder --run kirigami-hello # باستخدام kde-builder
kdesrc-build --run --exec kirigami-hello kirigami-tutorial # باستخدام kdesrc-build
kirigami-hello.exe # على ويندوز

هكذا! الآن سترى أول تطبيق Kirigami لك يظهر أمام عينيك.

لتشغيل تطبيق QML الجديد في وضع الجوال، يمكنك استخدام QT_QUICK_CONTROLS_MOBILE=1:

QT_QUICK_CONTROLS_MOBILE=1 kirigami-hello

إذا ربطت المشروع يدويًا باستخدام CMake ولسبب ما أردت إلغاء تثبيت المشروع، يمكنك تشغيل:

cmake --build build/ --target uninstall

ملاحظة

في المرة القادمة التي تريد فيها إنشاء الملفات والمجلدات اللازمة، يمكنك استخدام KAppTemplate أو KDevelop لإنشاء مشروع مناسب للبدء منه آليًا. وهما متاحان من مستودعات كل توزيعة رئيسية. ستُنشئ هذه التطبيقات أيضًا ملفات تحتوي على بيانات وصفية لـ AppStream وملف .desktop يحتوي على معلومات حول كيفية عرض التطبيق في مشغل تطبيقات لينكس.

بفضل سحر CMakeLists، يمكنك أيضًا استخدام بيئات تطوير متكاملة مثل KDevelop أو QtCreator لتطوير هذا التطبيق ضمن بيئة مريحة بأقل جهد.

Docs: الإعداد مع بايثون

Mon, 01 Jan 0001 00:00:00 +0000

المتطلبات الأساسية

قبل البدء، سنحتاج إلى تثبيت Kirigami وPySide على جهازنا.

Manjaro Arch

sudo pacman -S python-pipx python-pyqt6 pyside6 kirigami flatpak-builder qqc2-desktop-style appstream

OpenSUSE

sudo zypper install python3-pipx python3-qt6 python3-pyside6 kf6-kirigami-devel flatpak-builder kf6-qqc2-desktop-style AppStream-compose

Fedora

sudo dnf install pipx python3-pyqt6 python3-pyside6 kf6-kirigami-devel flatpak-builder kf6-qqc2-desktop-style appstream-compose

إذا كنت على توزيعة بحزم PySide6 أو PyQt6 قديمة، فهذا الدليل يعمل مع بناء البرمجيات باستخدام distrobox.

هيكل المشروع

أولاً ننشئ مجلد مشروعنا (يمكنك استخدام الأوامر أدناه). سنسمي مجلدنا kirigami_python/.

kirigami_python/
├── README.md
├── LICENSE.txt
├── MANIFEST.in # لإضافة ملفات QML الخاصة بنا
├── pyproject.toml # الملف الرئيسي لإدارة المشروع
├── org.kde.kirigami_python.desktop
└── src/
├── __init__.py # لاستيراد دليل src/ كحزمة
├── __main__.py # لتحديد التطبيق كنقطة دخول
├── app.py
└── qml/
└── Main.qml

اسم الحزمة سيكون kirigami_python، والملف التنفيذي (سكريبت وحدة التحكم) سيُسمى kirigami_hello، ونقطة الدخول ستكون app.

تلميح

لإنشاء هيكل المجلد هذا بسرعة، شغّل: mkdir -p kirigami_python/src/qml/.

لمشروع أكثر شمولاً يتناول تفاصيل إضافية عن هيكل الملفات هذا، انظر المشروع الكامل بلغة بايثون + كيريغامي.

pyproject.toml

تطبيقات بايثون الحديثة تحتاج فقط إلى ملف TOML واحد لتحديد جميع البيانات الوصفية ومعلومات الحزمة والتبعيات وفقًا لـ PEP 621. ما يلي يصلح كنقطة بداية جيدة لتطبيق ويمكن توسيعه لاحقًا.

معظم محتويات هذا الملف هي قالب أساسي، ويمكن رؤية نسخة أكثر اكتمالاً منه في بايثون مع كيريغامي: الهيكل العام.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[project]
name = "kirigami_python"
version = "0.1"
authors = [
 {name = "Konqi", email = "konqi@example.com"}
]
classifiers = [
 "Development Status :: 5 - Production/Stable",
 "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
 "Intended Audience :: End Users/Desktop",
 "Topic :: Utilities",
 "Programming Language :: Python",
 "Operating System :: POSIX :: Linux",
]

[project.scripts]
kirigami_hello = "kirigami_python.app:main"

[tool.setuptools]
packages = ["kirigami_python"]
package-dir = {kirigami_python = "src"}
include-package-data = true

[tool.setuptools.data-files]
"share/applications" = ["org.kde.kirigami_python.desktop"]

لاحظ الأسطر المميزة. كما ذُكر تحت هيكل المشروع، اسم الحزمة هو kirigami_python، اسم الملف التنفيذي هو kirigami_hello، واسم نقطة الدخول هو app. على وجه الخصوص، يجب ملاحظة ما يلي:

يتكون سكريبت المشروع من سكريبت نقطة دخول سيُولد بواسطة setuptools لتشغيل التطبيق، وفي هذه الحالة هو kirigami_hello.
سكريبت المشروع المُولد kirigami_hello يشغّل الدالة main() في سكريبت app.py في حزمة kirigami_python.
الدليل الافتراضي package-dir لمشاريع بايثون هو عادة الدليل الجذر. في هذه الحالة، يُستبدل هذا بالدليل الفرعي src/ ليعمل كالدليل الجذر للحزمة.
بسبب package-dir، سكريبت المشروع المُولد يفعل kirigami_python → app بدلاً من kirigami_python → src → app.
بسبب package-dir أيضًا، استدعاء importlib.resources.files() في app.py يفعل kirigami_python → qml → Main.qml بدلاً من kirigami_python → src → qml → Main.qml.

انظر التشغيل المباشر، كوحدة، وكسكريبت وحدة تحكم للتفاصيل.

org.kde.kirigami_python.desktop

يجب أن يتبع نظام تسمية DNS العكسي متبوعًا بالامتداد .desktop مثل org.kde.kirigami_python.desktop:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


[Desktop Entry]
Name=Kirigami Tutorial in Python
Name[ar]=درس كيريغامي ببايثون
Name[ca]=Guia d'aprenentatge del Kirigami en Python
Name[eo]=Lernilo pri Kirigami en Python
Name[es]=Tutorial de Kirigami en Python
Name[fr]=Tutoriel pour Kirigami en Python
Name[it]=Esercitazione di Kirigami in Python
Name[nl]=Kirigami handleiding in Python
Name[pt_BR]=Tutorial do Kirigami em Python
Name[ro]=Îndrumar Kirigami în Python
Name[sk]=Tutoriál Kirigami v Pythone
Name[sl]=Učbenik Kirigami v Pythonu
Name[sv]=Kirigami-handledning i Python
Name[tr]=Python ile Kirigami Öğreticisi
Name[uk]=Підручник з Kirigami для Python
Exec=kirigami_hello
Icon=kde
Type=Application
Terminal=false
Categories=Utility

ملاحظة

أيقونات النافذة وشريط المهام ستعمل في جلسة Wayland فقط إذا وُضعت ملفات سطح المكتب للتطبيقات في ~/.local/share/applications أو /usr/share/applications. لتشغيل الأيقونات في هذا الدليل، انسخ ملف سطح المكتب للتطبيق هناك.

MANIFEST.in

هذا الملف هو ببساطة إعلان عن ملفات شيفرة مصدرية إضافية يجب أن تكون موجودة في الحزمة عند تشغيل التطبيق. بايثون افتراضيًا لا تتضمن ملفات QML في الحزم، ويجب أن تكون متاحة لتشغيل التطبيق.

1

include src/qml/*.qml

src/app.py

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


#!/usr/bin/env python3

import os
import sys
import signal
from importlib.resources import files

from PySide6.QtGui import QGuiApplication
from PySide6.QtCore import QUrl
from PySide6.QtQml import QQmlApplicationEngine

def main():
 app = QGuiApplication(sys.argv)
 engine = QQmlApplicationEngine()

 """Needed to close the app with Ctrl+C"""
 signal.signal(signal.SIGINT, signal.SIG_DFL)

 """Needed to get proper KDE style outside of Plasma"""
 if not os.environ.get("QT_QUICK_CONTROLS_STYLE"):
 os.environ["QT_QUICK_CONTROLS_STYLE"] = "org.kde.desktop"

 base_path = files('kirigami_python').joinpath('qml', 'Main.qml')
 url = QUrl(f"{base_path}")
 engine.load(url)

 app.exec()

if __name__ == "__main__":
 main()

بما أن هذا تطبيق واجهة رسومية، نريد أن تشتغل الدالة الرئيسية فقط عند تشغيل السكريبت، وليس عند استيراده، لذا نحتاج إلى الشرط if __name__ == "__main__" في نهاية الملف. انظر التشغيل المباشر، كوحدة، وكسكريبت وحدة تحكم للتفاصيل.

ننشئ QGuiApplication ونُهيئ محرك QML، ومع QGuiApplication.exec() سيستمر التطبيق في العمل حتى يُغلق. ثم importlib.resources.files() يلتقط المسار إلى ملف موجود في الحزمة، ألا وهو Main.qml. بذلك المسار، نُحمّل ملف QML في محرك QML كنقطة دخول رئيسية لواجهة التطبيق.

src/init.py

أنشئ ملفًا فارغًا kirigami_python/src/__init__.py. هذا الملف يحتاج فقط إلى الوجود لاستيراد دليل كحزمة.

touch __init__.py

src/main.py

أنشئ ملفًا kirigami_python/src/__main__.py بالمحتويات التالية:

1
2
3


from . import app

app.main()

يُضيف هذا ببساطة محتويات الدليل الحالي (src/) ويستوردها كوحدة باسم app، ثم يُشغّل فورًا دالة main() الخاصة بالتطبيق.

src/qml/Main.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


// Includes relevant modules used by the QML
import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

// Provides basic features needed for all kirigami applications
Kirigami.ApplicationWindow {
 // Unique identifier to reference this object
 id: root

 width: 400
 height: 300

 // Window title
 title: "Hello World"

 // Set the first page that will be loaded when the app opens
 // This can also be set to an id of a Kirigami.Page
 pageStack.initialPage: Kirigami.Page {
 Controls.Label {
 // Center label horizontally and vertically within parent object
 anchors.centerIn: parent
 text: "Hello World!"
 }
 }
}

هنا سنتعامل مع الواجهة الأمامية لتطبيقنا.

الآن، لنركز على Main.qml. أولاً نستورد عددًا من الوحدات المهمة:

QtQuick، المكتبة القياسية المستخدمة في تطبيقات QML.
QtQuick Controls، التي توفر عددًا من عناصر التحكم القياسية التي يمكننا استخدامها لجعل تطبيقاتنا تفاعلية.
QtQuick Layouts، التي توفر أدوات لوضع المكونات داخل نافذة التطبيق.
Kirigami، التي توفر عددًا من المكونات المناسبة لإنشاء تطبيقات تعمل عبر أجهزة بأشكال وأحجام مختلفة.

ملاحظة

نضبط أيضًا خاصية title للنافذة على "Hello World".

أخيرًا، نضمّن في صفحتنا Controls.Label الذي يتيح لنا وضع نص في صفحتنا. نستخدم anchors.centerIn: parent لتوسيط اللصيقة أفقيًا وعموديًا داخل العنصر الأب. في هذه الحالة، المكون الأب للصيقتنا هو Kirigami.Page. آخر ما علينا فعله هو ضبط نصها: text: "Hello World!".

تشغيل التطبيق

يمكنك تشغيل البرنامج النصي لوحدة التحكم kirigami_hello دون حاجة لتثبيته أولًا:

pipx run --system-site-packages --spec . kirigami_hello

العلامة --system-site-packages ضرورية لجعل بايثون قادرًا على الوصول إلى حزم بايثون من توزيعتك. هذا مطلوب لأن كيريغامي وPySide يجب أن يكونا قد بُنيا ضد نفس إصدار كيوتي ليعملا، وهذا هو الحال عندما يأتي كلاهما من التوزيعة.

العلامة --spec تحدد المسار إلى شفرة المصدر أو حزمة العجلة التي تحتوي البرنامج، وkirigami_hello هو البرنامج النصي القابل للتنفيذ الذي سيُشغّل.

لبناء حزمة بايثون وتثبيتها، شغّل:

pipx install --force --system-site-packages .

ستُثبّت الحزمة إلى ~/.local/share/pipx/venvs/kirigami-python، وسيُثبّت برنامج نصي قابل للتنفيذ إلى ~/.local/bin/kirigami_hello.

استخدام pipx مقابل pip

على عكس بايثون مع كيريغامي: إنشاء حزمة بايثون، استخدم هذا الدليل pipx لجعل المشروع أسهل في التشغيل والتثبيت. يمكن تنفيذ نفس الخطوات يدويًا باستخدام venv وbuild وpip كما في الدليل الأكثر اكتمالًا.

pipx مفيد وموصى به وفقًا لـ PEP 668 لتشغيل تطبيقات بايثون، بينما pip متعدد الأغراض ويمكن استخدامه أيضًا لوحدات بايثون القابلة للاستيراد.

بعد هذا، يمكن إطلاق التطبيق بتشغيل:

kirigami_hello

لتشغيل تطبيق QML الجديد في وضع الجوال، يمكنك استخدام QT_QUICK_CONTROLS_MOBILE=1:

QT_QUICK_CONTROLS_MOBILE=1 kirigami_hello

هكذا! الآن سترى أول تطبيق Kirigami لك يظهر أمام عينيك.

Docs: الإعداد مع Rust

Mon, 01 Jan 0001 00:00:00 +0000

تنصيب كيريغامي

قبل البدء، سنحتاج إلى تثبيت كيريغامي وRust على جهازنا.

Manjaro Arch

sudo pacman -S cargo cmake extra-cmake-modules kirigami breeze qqc2-desktop-style

OpenSUSE

sudo zypper install cargo cmake kf6-extra-cmake-modules kf6-kirigami-devel qt6-quickcontrols2-devel kf6-qqc2-desktop-style-devel

Fedora

sudo dnf install cargo cmake extra-cmake-modules kf6-kirigami2-devel kf6-qqc2-desktop-style

يمكن العثور على مزيد من المعلومات للتوزيعات الأخرى في تنصيب تبعيات البناء.

هيكل المشروع

أولًا ننشئ مجلد مشروعنا (يمكنك استخدام الأوامر أدناه). سنسمي مجلدنا kirigami_rust/. سيكون هذا هيكل المشروع:

kirigami_rust/
├── CMakeLists.txt
├── Cargo.toml
├── build.rs
├── org.kde.kirigami_rust.desktop
└── src/
├── main.rs
└── qml/
└── Main.qml

سيستخدم هذا المشروع CMake لاستدعاء Cargo، والذي بدوره سيبني المشروع.

حول CMake وCargo

هذه ليست الطريقة التقليدية لبناء مشروع Rust: تقنيًا، فقط Cargo مطلوب لبنائه، عادةً باستخدام cargo build وcargo run.

لتطبيقات سطح المكتب مع ذلك، CMake (أو ما يعادله مثل Meson المستخدم من قبل GNOME أو Just المستخدم من قبل COSMIC) ضروري للتثبيت لأن Cargo يفتقر إلى الميزات اللازمة لتثبيت تطبيقات سطح المكتب ذات الواجهة الرسومية.

سيُسمى المشروع kirigami_rust وسيُولّد ملفًا قابلًا للتنفيذ يُسمى kirigami_hello.

💡 تلميح

يمكنك إنشاء هيكل الملفات هذا بسرعة باستخدام: mkdir -p kirigami_rust/src/qml/.

org.kde.kirigami_rust.desktop

يجب أن يتبع نظام تسمية DNS عكسي متبوعًا بالامتداد .desktop مثل org.kde.kirigami_rust.desktop:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


[Desktop Entry]
Name=Kirigami Tutorial in Rust
Name[ar]=درس كيريغامي برست
Name[ca]=Guia d'aprenentatge del Kirigami en Rust
Name[es]=Tutorial de Kirigami en Rust
Name[fr]=Tutoriel pour Kirigami en Rust
Name[it]=Esercitazione di Kirigami in Rust
Name[nl]=Kirigami handleiding in Rust
Name[pt_BR]=Tutorial do Kirigami em Rust
Name[ro]=Îndrumar Kirigami în Rust
Name[sk]=Tutoriál Kirigami v Ruste
Name[sl]=Učbenik Kirigami v Rustu
Name[sv]=Kirigami-handledning i Rust
Name[tr]=Rust ile Kirigami Öğreticisi
Name[uk]=Підручник з Kirigami для Rust
Exec=kirigami_hello
Icon=kde
Type=Application
Terminal=false
Categories=Utility

CMakeLists.txt

سيُستخدم ملف CMakeLists.txt لتشغيل Cargo ولتثبيت الملفات الضرورية مع تطبيقنا. كما يوفر ميزات معينة لتحسين جودة الحياة، مثل التأكد من تثبيت كيريغامي أثناء التجميع ولإشارة توزيعات لينكس إلى تثبيت التبعيات الضرورية مع التطبيق.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


cmake_minimum_required(VERSION 3.28)

project(kirigami_rust)

find_package(ECM 6.0 REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})
include(KDEInstallDirs)
include(ECMUninstallTarget)

include(ECMFindQmlModule)
ecm_find_qmlmodule(org.kde.kirigami REQUIRED)
find_package(KF6 REQUIRED COMPONENTS QQC2DesktopStyle)

add_custom_target(kirigami_rust
 ALL
 COMMAND cargo build --target-dir ${CMAKE_CURRENT_BINARY_DIR}
)

install(
 PROGRAMS ${CMAKE_CURRENT_BINARY_DIR}/debug/kirigami_hello
 DESTINATION ${KDE_INSTALL_BINDIR}
)

install(FILES org.kde.kirigami_rust.desktop DESTINATION ${KDE_INSTALL_APPDIR})

أول شيء نفعله هو إضافة وحدات CMake الإضافية من كيدي (ECM) إلى مشروعنا حتى نتمكن من استخدام ecm_find_qml_module للتحقق من تثبيت كيريغامي عند محاولة بناء التطبيق، وإذا لم يكن مثبتًا، نفشل فورًا. ميزة أخرى مفيدة في ECM هي ECMUninstallTarget، والتي تسمح بإلغاء تثبيت التطبيق بسهولة باستخدام CMake إذا رغبت.

نستخدم أيضًا find_package() من CMake للتأكد من وجود qqc2-desktop-style، نمط QML لسطح المكتب من كيدي. هذا أحد السببين لاستخدامنا CMake في هذا الدليل.

عادةً تُبنى مشاريع Rust باستخدام Cargo، ولن يختلف الأمر هنا. ننشئ هدفًا سيشغّل Cargo ببساطة عند تشغيله، ونعلّمه بـ ALL ليُبنى افتراضيًا. سيبني Cargo الملف القابل للتنفيذ داخل دليل CMake الثنائي (عادةً build/).

لمزيد من المعلومات حول CMake والأهداف ودليل الثنائيات، راجع بناء برمجيات كيدي يدويًا.

بعد ذلك، نُثبّت ببساطة الملف التنفيذي kirigami_rust الذي يولّده Cargo في دليل الثنائيات ونُثبّته في BINDIR، وهو عادةً /usr/bin أو /usr/local/bin أو ~/.local/bin. ونُثبّت أيضًا ملف سطح المكتب الضروري في APPDIR، وهو عادةً /usr/share/applications أو ~/.local/share/applications. وهذا هو السبب الثاني لاستخدامنا CMake في هذا الدليل.

لمزيد من المعلومات حول مكان تثبيت برمجيات كيدي، راجع بناء برمجيات كيدي يدويًا: خطوة التثبيت.

والآن بعد أن عُولج أمر CMake، دعنا ننظر إلى الملفات التي سنقضي معظم وقتنا في العمل بها.

Cargo.toml

ثم لدينا ملف Cargo.toml بسيط جدًا:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


[package]
name = "kirigami_hello"
version = "0.1.0"
authors = [ "Konqi the Konqueror <konqi@kde.org>" ]
edition = "2024"
license = "GPLv3"

[dependencies]
cxx = "1.0.194" # Check the latest available version at https://crates.io/crates/cxx

# Check the latest available version of all related cxx-qt crates at https://crates.io/crates/cxx-qt
cxx-qt = "0.8.1"
cxx-qt-lib = { version="0.8.1", features = ["qt_full"] }
cxx-qt-lib-extras = "0.8.1"

[build-dependencies]
# The link_qt_object_files feature is required for statically linking Qt 6.
cxx-qt-build = { version = "0.8.1", features = [ "link_qt_object_files" ] }

يتكون من بيانات وصفية للمشروع وقائمة بالتبعيات التي يسحبها Cargo آليًا، وهي cxx وcxx-qt، واللتان ضروريتان لتشغيل تطبيقات Qt المكتوبة بلغة Rust.

build.rs

حيث تُسجّل في C++ عناصر QML عادةً باستخدام QML_ELEMENT وecm_add_qml_module باستخدام التسجيل التصريحي، مع Rust ستحتاج إلى التصريح بها في ملف نص بناء build.rs:

1
2
3
4
5
6
7
8
9


use cxx_qt_build::{CxxQtBuilder, QmlModule};

fn main() {
 CxxQtBuilder::new_qml_module(
 QmlModule::new("org.kde.tutorial")
 .qml_files(&["src/qml/Main.qml"])
 )
 .build();
}

هذا ضروري لجعل ملف QML متاحًا في نقطة الدخول لتطبيقنا، main.rs.

src/main.rs

يُهيئ الملف kirigami_rust/src/main.rs المشروع ثم يُحمّل ملف QML، الذي سيتكون من واجهة المستخدم للتطبيق.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


use cxx_qt_lib::{QGuiApplication, QQmlApplicationEngine, QQuickStyle};
use cxx_qt_lib_extras::QApplication;
use std::env;

fn main() {
 let mut app = QApplication::new();
 let mut engine = QQmlApplicationEngine::new();

 // To associate the executable to the installed desktop file
 QGuiApplication::set_desktop_file_name(&"org.kde.kirigami_rust".into());
 // To ensure the style is set correctly
 let style = env::var("QT_QUICK_CONTROLS_STYLE");
 if style.is_err() {
 QQuickStyle::set_style(&"org.kde.desktop".into());
 }

 if let Some(engine) = engine.as_mut() {
 engine.load(&"qrc:/qt/qml/org/kde/tutorial/src/qml/Main.qml".into());
 }

 if let Some(app) = app.as_mut() {
 app.exec();
 }
}

الجزء الأول المُوسوم بماكرو Rust #[cxx_qt::bridge] ينشئ كائن QObject وهميًا من بنية Rust وهمية. هذا ضروري فقط لإكمال استخدام QmlModule في نص البناء السابق build.rs. سيلعب هذا دورًا أكبر في دليل مستقبلي يُعلّم كيفية كشف كود Rust لـ QML، لكن الآن يمكنك تجاهله.

بعد هذا يبدأ الجزء المهم:

السطران 12-13 يستوردان مكتبات Qt الضرورية المُكشفة عبر cxx-qt.

ننشئ أولاً مثيلًا جديدًا من QApplication، ثم نُجري بعض التكاملات في الأسطر 20-26.

ثم يأتي الجزء الذي ينشئ نافذة التطبيق فعليًا:

يتوافق عنوان URL الطويل qrc:/qt/qml/org/kde/tutorial/src/qml/Main.qml مع ملف Main.qml وفقًا لنظام موارد Qt، ويتبع هذا المخطط: <بادئة_المورد><URI_الاستيراد><دليل_QML><ملف>.

بعبارة أخرى: بادئة المورد المبدئية qrc:/qt/qml/ + URI الاستيراد org/kde/tutorial (المُضبَط في build.rs، مفصولة بشرطات مائلة بدلاً من النقاط) + دليل QML src/qml/ + ملف QML Main.qml.

src/qml/Main.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


// Includes relevant modules used by the QML
import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

// Provides basic features needed for all kirigami applications
Kirigami.ApplicationWindow {
 // Unique identifier to reference this object
 id: root

 width: 400
 height: 300

 // Window title
 title: "Hello World"

 // Set the first page that will be loaded when the app opens
 // This can also be set to an id of a Kirigami.Page
 pageStack.initialPage: Kirigami.Page {
 Controls.Label {
 // Center label horizontally and vertically within parent object
 anchors.centerIn: parent
 text: "Hello World!"
 }
 }
}

هنا سنتعامل مع الواجهة الأمامية لتطبيقنا.

الآن، لنركز على Main.qml. أولاً نستورد عددًا من الوحدات المهمة:

QtQuick، المكتبة القياسية المستخدمة في تطبيقات QML.
QtQuick Controls، التي توفر عددًا من عناصر التحكم القياسية التي يمكننا استخدامها لجعل تطبيقاتنا تفاعلية.
QtQuick Layouts، التي توفر أدوات لوضع المكونات داخل نافذة التطبيق.
Kirigami، الذي يُوفّر عددًا من المكونات المناسبة لإنشاء تطبيقات تعمل عبر أجهزة بأشكال وأحجام مختلفة.

ملاحظة

ثم نصل إلى عنصرنا الأساسي، Kirigami.ApplicationWindow، الذي يُوفّر بعض الميزات الأساسية اللازمة لجميع تطبيقات Kirigami. هذه هي النافذة التي ستحتوي كل صفحة من صفحاتنا، الأقسام الرئيسية لواجهة المستخدم لدينا.

نضبط أيضًا خاصية title للنافذة على "Hello World".

ثم نضبط الصفحة الأولى من كومة الصفحات لدينا. معظم تطبيقات Kirigami مُنظّمة ككومة من الصفحات، كل صفحة تحتوي على مكونات ذات صلة مناسبة لمهمة محددة. حاليًا، نُبقي الأمر بسيطًا ونلتزم بصفحة واحدة. pageStack هي كومة صفحات فارغة مبدئيًا يُوفّرها Kirigami.ApplicationWindow، ومع pageStack.initialPage: Kirigami.Page {...} نضبط الصفحة الأولى المُقدّمة عند تحميل التطبيق على أنها Kirigami.Page. ستحتوي هذه الصفحة على كل محتوانا.

أخيرًا، نُضمّن في صفحتنا Controls.Label الذي يتيح لنا وضع نص على صفحتنا. نستخدم anchors.centerIn: parent لتوسيط التسمية أفقيًا وعموديًا داخل العنصر الأب. في هذه الحالة، المكون الأب لتسميتنا هو Kirigami.Page. آخر شيء نحتاج فعله هو ضبط نصها: text: "Hello World!".

ترجمة التطبيق وتثبيته

يجب أن تجد الملف التنفيذي المُولّد kirigami_hello تحت build/debug/kirigami_hello ويمكنك تشغيله مباشرة أو باستخدام cargo run، لكنه سيفتقد أيقونة نافذة. لمعالجة هذا، سنُثبّت التطبيق أولاً.

شغّل ما يلي:

cmake -B build --install-prefix ~/.local
cmake --build build/
cmake --install build/

باستخدام الأمر الأول، سيبحث CMake عن Kirigami وqqc2-desktop-style.

باستخدام الأمر الثاني، سيبني CMake الهدف kirigami_rust، الذي يستدعي فقط cargo build --target-dir build/. ستستغرق هذه الخطوة بعض الوقت لإكمالها، لكن في المرة القادمة التي تُكرّر فيها أمر CMake الثاني ستكون أسرع أو لن تحتاج إلى الترجمة على الإطلاق.

في الخطوة الثالثة، سيُثبّت CMake الملف التنفيذي kirigami_hello تحت ~/.local/bin/kirigami_hello وملف سطح المكتب تحت ~/.local/share/applications، وسيظهر مدخل جديد باسم "Kirigami Tutorial in Rust" في قائمتك.

افتح مدخل القائمة وفويلا! الآن سترى أول تطبيق Kirigami لك يظهر أمام عينيك.

لتشغيل تطبيق QML الجديد في وضع الجوال، يمكنك استخدام QT_QUICK_CONTROLS_MOBILE=1:

QT_QUICK_CONTROLS_MOBILE=1 kirigami_hello

إذا ربطت المشروع يدويًا باستخدام CMake ولسبب ما أردت إلغاء تثبيت المشروع، يمكنك تشغيل:

cmake --build build/ --target uninstall

Docs: شرح الصفحات

Mon, 01 Jan 0001 00:00:00 +0000

تطبيقنا

في الدرس السابق، تمكنا من إعداد وبناء وترجمة أول تطبيق كيريغامي لنا. مع وضع الأساسيات، يمكننا بدء رحلتنا نحو إنشاء تطبيق كامل الميزات.

ستركز هذه الدروس على إنشاء تطبيق يتيح للمستخدم رؤية عدد الأيام المتبقية حتى حدث من اختياره.

نوصيك أيضًا بالاطلاع على معرض كيريغامي، الذي يوفر عددًا من أمثلة واجهة المستخدم المفيدة.

في هذا القسم سنركز على الصفحات، أحد العناصر الهيكلية الرئيسية لأي تطبيق كيريغامي.

الصفحات

تُنظَّم تطبيقات كيريغامي عادةً في صفحات باستخدام Kirigami.Page. الصفحات هي "الشاشات" المختلفة للتطبيق. سترغب في تخصيص صفحة لجوانب محددة من تفاعل تطبيقك، ولتسهيل الأمور يمكنك إنشاء ملفات QML مختلفة لكل صفحة.

تُنظَّم الصفحات في كومة صفحات حيث يمكن دفعها وسحبها. على الهاتف، تُعرض الصفحة العليا فقط، بينما على شاشة أكبر (حاسوب مكتبي أو لوحي)، يمكن عرض صفحات متعددة جنبًا إلى جنب إذا رغبت.

صفحة واحدة على الهاتف

صفحتان جنبًا إلى جنب على الحاسوب المكتبي

ملاحظة

ترث Kirigami.Page من Controls.Page، وبالتالي يمكنك استخدام خصائص الأخيرة أيضًا.

عند تصفح وثائق واجهة برمجة تطبيقات QML، تأكد من النظر في الدوال والخصائص الموروثة من واجهة البرمجة التي تتصفحها أيضًا.

لنعد إلى ملف Main.qml الذي أنشأناه في درسنا السابق:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


// Includes relevant modules used by the QML
import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

// Provides basic features needed for all kirigami applications
Kirigami.ApplicationWindow {
 // Unique identifier to reference this object
 id: root

 width: 400
 height: 300

 // Window title
 // i18nc() makes a string translatable
 // and provides additional context for the translators
 title: i18nc("@title:window", "Hello World")

 // Set the first page that will be loaded when the app opens
 // This can also be set to an id of a Kirigami.Page
 pageStack.initialPage: Kirigami.Page {
 Controls.Label {
 // Center label horizontally and vertically within parent object
 anchors.centerIn: parent
 text: i18n("Hello World!")
 }
 }
}

نجعل تطبيقنا يبدأ بصفحة Kirigami.Page. كل ما أدرجناه فيها هو تسمية تحتوي على "Hello World"، لكننا سنحسّن الأمور قليلًا.

الفكرة وراء تطبيقنا هي أننا سنتمكن من عرض مجموعة من العدّادات التنازلية للمستخدم. المشكلة مع Kirigami.Page العادية هي أن لها حجمًا رأسيًا ثابتًا، لذا بدلًا من ذلك يمكننا استخدام Kirigami.ScrollablePage، التي تأتي مع شريط تمرير مدمج خاص بها.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 id: root

 width: 400
 height: 300

 title: i18nc("@title:window", "Day Kountdown")

 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")
 }
}

تتميز صفحات كيريغامي أيضًا بعناوين أنيقة موضوعة داخل شريط الأدوات، تشير بسرعة للمستخدم إلى الصفحة التي يتصفحها. كل ما علينا فعله هو تعيين عنوان الصفحة باستخدام خاصية title من Kirigami.ScrollablePage. في هذه الحالة، استخدمنا إحدى دوال i18nc() التي استكشفناها في درسنا السابق لهذا الغرض.

ملاحظة

يمكنك أيضًا اختيار تعريف صفحتك داخل مستند QML خاص بها. للقيام بذلك، ستنشئ ملف QML الجديد، مثلًا kirigami-tutorial/src/qml/StartPage.qml، وتضيفه إلى ملف kirigami-tutorial/src/CMakeLists.txt، وتضبط الصفحة الأولى للنافذة لتحميله، كما يلي:

pageStack.initialPage: Qt.resolvedUrl("StartPage.qml")

يضبط pageStack.initialPage الصفحة الأولية لكومة صفحات التطبيق، ويحوّل Qt.resolvedUrl المسار النسبي لملف QML إلى مسار مطلق.

توجد معلومات إضافية حول هياكل الصفحات البديلة ضمن وثائق كيريغامي الخاصة بنا.

Docs: التخطيطات، وعروض القوائم، والبطاقات

Mon, 01 Jan 0001 00:00:00 +0000

تخطيط المحتوى الخاص بك

الآن بعد أن فهمنا كيفية عمل الصفحات، حان الوقت لإضافة أشياء إليها. سنستعرض عددًا من مكونات وعناصر التخطيط المهمة التي ستكون مفيدة عند تصميم تطبيقنا.

بنهاية هذا القسم، سيكون لديك تطبيق ذو مظهر أنيق.

قوائم العرض

إن استخدمت يومًا ديسكفر أو نيو تشات أو إعدادات نظام بلازما، فستكون قد صادفت قائمة عرض. ببساطة، تتيح لك عرض البيانات في قائمة.

pageStack.initialPage: Kirigami.ScrollablePage {
 // ...
 Kirigami.CardsListView {
 id: cardsView
 model: kountdownModel
 delegate: kountdownDelegate
 }
}

يبدو هذا غامضًا، لكن لا تقلق. لنبدأ من البداية.

نُضِف هذا المكون داخل صفحة قابلة للتمرير من كيريغامي من الدرس السابق.

نستخدم قائمة عرض بطاقات كيريغامي، وهي قائمة عرض تتيح لنا عرض البطاقات بسهولة في قائمة. لكن قوائم العرض صُممت لعرض بيانات مأخوذة من نموذج - لتعبئة نفسها آليًا من مجموعة بيانات نشير إليها. وهنا تأتي خاصية النموذج: في هذا المثال، تشير إلى kountdownModel.

النموذج

Kirigami.ApplicationWindow {
 // ...
 ListModel {
 id: kountdownModel
 // كل عنصر قائمة هو عنصر في القائمة، يحوي معلومات
 ListElement {
 name: "Dog birthday!!"
 description: "Big doggo birthday blowout."
 date: 100
 }
 }
 // ...
}

نُضِف kountdownModel داخل نافذة تطبيق كيريغامي من الدرس السابق.

يُعرّف النموذج طريقة بنية إدخال البيانات. سيتكون kountdownModel من عنصر واحد فقط حاليًا. بالنظر إلى عنصر القائمة أعلاه، نرى كيف بُنيت بيانات kountdownModel: يحوي اسمًا ووصفًا وتاريخًا. هذا ليس ثابتًا، وقد يكون لديك أنواع مختلفة من البيانات في نموذجك. الأولان مجرد سلاسل نصية، والثالث رقم نستخدمه كعنصر نائب.

ملاحظة

بما أن كيو إم إل مبني على جافا سكريبت، تتوفر العديد من ميزات هذه اللغة للاستخدام في ملفات كيو إم إل. لكن، يجب أن تُسبق متغيرات كيو إم إل بـ property، إلا إذا كانت داخل كتلة كود جافا سكريبت. يمكنك قراءة المزيد عنها في هذه الصفحة.

النماذج مفيدة أيضًا في كيفية تعديلها باستخدام عدة دوال. بعض الدوال المهمة هي:

ListModel.append(yourobject: jsobject) يُضيف كائن جافا سكريبت yourobject إلى نموذج القائمة ويضعه بعد آخر عنصر في النموذج. ليحدث هذا بشكل صحيح، يجب توفير كائن جافا سكريبت بالخصائص الصحيحة وأنواع البيانات المقابلة.
ListModel.get(index: int) يُرجع كائن جافا سكريبت في موقع الفهرس الذي توفره.
ListModel.remove(index: int, count: int) يُزيل كائن جافا سكريبت في موقع index المقدم، وعددًا بعده بقدر ما تضعه في count (1 يشمل فقط كائن جافا سكريبت في الفهرس المقدم)
ListModel.set(index: int, yourobject: jsobject) يُغير العنصر في موقع index المقدم بالقيم المقدمة في yourobject. نفس قواعد append().

المفوّضون

بينما يحوي kountdownModel البيانات التي ستُعرض، سيتولى kountdownDelegate كيفية عرض البيانات في قائمة العرض. لذلك نستخدم قائمة عرض بطاقات كيريغامي المصممة لعرض مفوّضين من نوع بطاقة، وسيُمثل هؤلاء المفوّضون بصريًا عبر بطاقة مجردة من كيريغامي.

يتلقى المفوّضون آليًا خصائص مثيلات عنصر القائمة التي حددناها في نموذجنا. لذلك يمكننا الإشارة إلى خصائص name و description و date كما لو كانت متغيرات تقليدية داخل مفوّضنا.

بناء بطاقة المفوّض

يمكن إضافة المكون الذي سيمثل مفوّضنا داخل نافذة تطبيق كيريغامي. سنتحقق بعد ذلك مما يفعله كل جزء من مكون المفوّض.

Kirigami.ApplicationWindow {
 // ...
 Component {
 id: kountdownDelegate
 Kirigami.AbstractCard {
 contentItem: Item {
 // يُعرّف العرض/الارتفاع الضمني العرض/الارتفاع الطبيعي لعنصر إذا لم يُحدد عرض أو
 // ارتفاع. يُعرّف الإعداد أدناه الحجم المفضل للمكون بناءً على محتواه
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2

 Kirigami.Heading {
 level: 1
 text: date
 }

 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }
 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }
 Controls.Label {
 Layout.fillWidth: true
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: i18n("Edit")
 // عند النقر: سيُفعل... قريبًا!
 }
 }
 }
 }
 }
 // ...
}

العرض الضمني والارتفاع الضمني

الجزء الأول الذي سننظر إليه هو كيفية إدارة عرض وارتفاع مكوننا:

Kirigami.AbstractCard {
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 // ...
 }
 }
}

بالنظر إلى بطاقتنا المجردة من كيريغامي، أول الخصائص التي نضبطها هي العرض الضمني و الارتفاع الضمني. ضبطناها على delegateLayout.implicitWidth و delegateLayout.implicitHeight، أي العرض الضمني و الارتفاع الضمني لعنصر التخطيط الشبكي.

العروض والارتفاعات الضمنية هي خصائص متاحة في أي عنصر تعمل كتلميحات وتُضبط كإعداد مبدئي، أو كخيار احتياطي، إذا لم يُضبط عرض أو ارتفاع صريح لهذه المكونات. هذه القيم مبدئيًا 0x0، لذا من المهم جدًا تعريفها في مكونات العنصر الخام كما فعلنا أعلاه.

هنا ضبطنا implicitWidth و implicitHeight لـ بطاقتنا المجردة من كيريغامي على تلك الخاصة بـ التخطيط الشبكي أدناه لضمان عدم تجاوزها للبطاقة. بهذه الطريقة، تأخذ البطاقة المساحة اللازمة لمحتوياتها.

التخطيطات

التخطيط الشبكي داخل مكون العنصر الذي قدمناه لخاصية عنصر المحتوى. هذا هو العنصر الذي يحوي ما سيُعرض في بطاقتك.

نحتاج أيضًا لاختيار تخطيط لمكوناتنا حتى لا تتراكم فوق بعضها. هناك ثلاثة أنواع رئيسية يمكن الاختيار من بينها:

ColumnLayout يُرتّب مكوّناتك عموديًا، في عمود واحد
RowLayout يُرتّب مكوّناتك أفقيًا، في صف واحد
GridLayout يُرتّب مكوّناتك في شبكة بتوليفة من اختيارك

مع ColumnLayout وRowLayout، كل ما علينا فعله هو كتابة مكوّناتنا داخل مكوّن التخطيط. كما ترى، اخترنا GridLayout، الذي يتطلب جهدًا يدويًا أكثر قليلًا.

GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2
 // ...
}

أول ما تراه هو anchors لدينا. نظام التثبيت في QtQuick يُوفّر طريقة مفيدة لضمان وضع مكوّناتك في أجزاء معيّنة من المكوّن الأب. ثبّتنا GridLayout إلى اليسار والأعلى واليمين من البطاقة الأب، مما يضمن امتداد محتوانا عبر البطاقة بأكملها.

بعد ذلك نحدد التباعد بين الصفوف والأعمدة داخل شبكتنا، حتى لا تتزاحم مكوّناتنا. يُوفّر كيريجامي عددًا من الوحدات المحددة مسبقًا المفيدة لاستخدامها لهذا الغرض:

وحدة كيريجامي	بكسل
smallSpacing	4px
largeSpacing	8px
gridUnit	18px

ملاحظة

مجموعة التصميم البصري لكيدي (VDG) لديها مزيد من المعلومات حول الوحدات المختلفة المُعرّفة داخل بلازما وكيريجامي في دليل الواجهة البشرية.

كما قد تتذكر، root هو مُعرّف Kirigami.ApplicationWindow خاصتنا. يُوفّر الخاصية wideScreen، المُستخدمة لتحديد ما إذا كانت شاشة الجهاز الحالي عريضة (أي شاشة حاسوب أو هاتف في الوضع الأفقي). نستخدم شرطًا ثلاثيًا هنا لتغيير عدد الأعمدة في شبكتنا اعتمادًا على الشاشة التي نستخدمها: إذا كانت عريضة، ستحتوي الشبكة على 4 أعمدة، وإلا فستحتوي على 2.

المكوّنات الداخلية

قد نكتفي بإنشاء ثلاث وسوم داخل مكوّن المفوّض وننتهي، لكن ذلك لن يبدو جميلًا بشكل خاص. سنستفيد من بعض المكوّنات الأكثر ملاءمة:

GridLayout {
 // ...
 Kirigami.Heading {
 Layout.fillHeight: true
 level: 1
 text: date
 }

 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }

 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }

 Controls.Label {
 Layout.fillWidth: true
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }

 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: i18n("Edit")
 }
}

كيف تبدو البطاقة المخصصة

يسارًا، Kirigami.Heading: يستخدم date الخاص بـ ListElement كعنوان من المستوى 1.
وسطًا، ColumnLayout: يحتوي على Kirigami.Heading يعرض اسم المهمة؛ وKirigami.Separator، الذي يُوفّر الخط الأفقي؛ وControls.Label، الذي يعرض وصفًا اختياريًا للمهمة. المكوّنان الأخيران لهما خاصية visible، التي تتحقق مما إذا كان الوصف فارغًا أم لا وتعرض المكوّنين اعتمادًا على نتيجة description.length > 0.
يمينًا، Controls.Button: زر سيفعل شيئًا... قريبًا!

تطبيقنا حتى الآن

Main.qml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 id: root

 width: 400
 height: 300

 title: i18nc("@title:window", "Day Kountdown")

 // ListModel needed for ListView, contains elements to be displayed
 ListModel {
 id: kountdownModel
 // Each ListElement is an element on the list, containing information
 ListElement {
 name: "Dog birthday!!"
 description: "Big doggo birthday blowout."
 date: 100
 }
 }

 Component {
 id: kountdownDelegate
 Kirigami.AbstractCard {
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2

 Kirigami.Heading {
 // Level determines the size of the heading
 level: 1
 text: date
 }

 // Layout for positioning elements vertically
 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }
 // Horizontal rule
 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }
 // Labels contain text
 Controls.Label {
 Layout.fillWidth: true
 // Word wrap makes text stay within box and shift with size
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 // Column spanning within grid layout (vertically in this case)
 Layout.columnSpan: 2
 text: i18n("Edit")
 //onClicked: to be done...
 }
 }
 }
 }
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")

 // List view for card elements
 Kirigami.CardsListView {
 id: cardsView
 // Model contains info to be displayed
 model: kountdownModel
 // Delegate is how the information will be presented in the ListView
 delegate: kountdownDelegate
 }
 }
}

إذن هذه هي بطاقتنا الأساسية!

بهذه الخطوات، وضعنا الآن الأساس لجميع الوظائف التي سنضيفها إلى تطبيقنا.

Docs: إضافة إجراءات

Mon, 01 Jan 0001 00:00:00 +0000

خلاصة

حتى الآن، بنينا تطبيقًا بسيطًا يعرض البطاقات. لكن، لا توجد حاليًا طريقة للمستخدم لإضافة بطاقات جديدة إلى عرض البطاقات.

في هذا الدليل، سننظر إلى إجراءات كيريغامي. ستساعدنا هذه الإجراءات في إضافة التفاعلية إلى تطبيقنا بطريقة متسقة وسريعة ويسيرة الوصول.

الإجراءات

يُغلّف Kirigami.Action إجراء واجهة المستخدم. يمكننا استخدام هذه الإجراءات لتزويد تطبيقاتنا بإجراءات سهلة الوصول ضرورية لوظائفها.

إذا كنت قد استخدمت تطبيقات كيريغامي من قبل، فبالتأكيد تفاعلت مع إجراءات كيريغامي. في هذه الصورة، نرى إجراءات على يمين عنوان الصفحة برموز مختلفة. يمكن عرض إجراءات كيريغامي بعدة طرق ويمكنها فعل مجموعة واسعة من الأشياء.

إضافة العدادات التنازلية

تطبيق العد التنازلي عديم الفائدة إلى حد كبير دون القدرة على إضافة عدادات تنازلية. لننشئ إجراءً يتيح لنا فعل ذلك.

pageStack.initialPage: Kirigami.ScrollablePage {
 // خصائص الصفحة الأخرى...
 actions: [
 Kirigami.Action {
 id: addAction
 icon.name: "list-add-symbolic"
 text: i18nc("@action:button", "Add kountdown")
 onTriggered: kountdownModel.append({
 name: "Kirigami Action added card!",
 description: "Congratulations, your Kirigami Action works!",
 date: 1000
 })
 }
 ]
 // ...
}

نضع Kirigami.Action الخاص بنا داخل صفحتنا الرئيسية من الدروس السابقة. إذا أردنا، يمكننا إضافة المزيد من الإجراءات إلى صفحتنا (وحتى تداخل الإجراءات داخل إجراءات!).

الأقواس [] المستخدمة أعلاه مشابهة لمصفوفات JavaScript، مما يعني أنه يمكنك تمرير شيء أو أكثر إليها، مفصولة بفاصلة:

// مصفوفة جافا سكريبت عامة للمكونات:
variable: [ component1, component2 ]
// تمرير مصفوفة من إجراءات كيريغامي إلى QML:
actions: [ Kirigami.Action {}, Kirigami.Action {} ]

خصائص id و text يجب أن تكون مألوفة من الدروس السابقة. لكن، الخاصية الموروثة Action.icon يجب أن تكون مثيرة للاهتمام: إنها كائن بعدة خصائص تتيح لك عرض رموز معينة لإجراءاتك. لحسن الحظ، لاستخدام رموز كيدي، كل ما نحتاجه هو توفير خاصية الاسم لخاصية الرمز، icon.name.

عرض الرموز المتاحة

انقر هنا لترى كيفية التحقق من الأيقونات المتوفرة في نظامك

مستكشف الأيقونات هو تطبيق كيدي يتيح لك عرض جميع الأيقونات التي يمكنك استعمالها لتطبيقك. يقدم عددًا من الميزات المفيدة مثل معاينات مظهرها عبر السمات المثبتة المختلفة، ومعاينات بأحجام مختلفة، والمزيد. قد تجده أداة مفيدة عند تحديد الأيقونات التي ستستعملها في تطبيقك.

تتبع العديد من رموز كيدي مواصفات تسمية رموز FreeDesktop. لذلك، قد تجد أيضًا من المفيد استشارة موقع مشروع FreeDesktop، الذي يسرد جميع أسماء الرموز المتوافقة عبر أسطح المكتب.

معالج الإشارة onTriggered هو الأهم. هذا ما سيفعله إجراءنا عند استخدامه. ستلاحظ أننا في مثالنا نستخدم طريقة kountdownModel.append من kountdownModel الذي أنشأناه في درسنا السابق. تتيح لنا هذه الطريقة إلحاق عنصر جديد بنموذج القائمة لدينا. نقدم له كائنًا (مشارًا إليه بأقواس معقوفة {}) له الخصائص ذات الصلة بعداداتنا التنازلية (name و description و date كعنصر نائب).

في كل مرة ننقر فيها على زر "Add kountdown" الموجود في أعلى اليمين، يُضاف العد التنازلي المخصص الخاص بنا.

نسخة الجوال

الدرج العام

المكون التالي هو Kirigami.GlobalDrawer. يظهر كقائمة هامبرغر. مبدئيًا، يفتح شريطًا جانبيًا، وهو مفيد بشكل خاص على الجوال، حيث يمكن للمستخدم ببساطة التمرير من جانب الشاشة لفتحه. الأدراج العامة مفيدة للتنقل والإجراءات العامة. سننشئ درجًا عامًا بسيطًا يتضمن زر "خروج".

Kirigami.ApplicationWindow {
 id: root
 // خصائص النافذة الأخرى...
 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }
 // ...
}

هنا، نضع درجنا العام داخل نافذة التطبيق. الخاصية الرئيسية التي نحتاج إلى الانتباه إليها هي GlobalDrawer.actions، والتي تأخذ شكل مصفوفة من مكونات Kirigami.Action. لهذا الإجراء رمز مناسب وينفذ دالة Qt.quit() عند تشغيله، مما يغلق التطبيق.

بما أننا نبقي درجنا العام بسيطًا الآن، نضبط خاصية GlobalDrawer.isMenu على true. يعرض هذا درجنا العام كقائمة تطبيق عادية، تشغل مساحة أقل من لوحة الدرج العام المبدئية.

الدرج العام

الدرج العام كقائمة

تلميح

صفحة المكونات القائمة على الإجراءات من هذه الوثائق تقدم تفاصيل إضافية حول إجراءات كيريغامي وكيفية استخدامها.

الإجراءات سياقية

مكونات كيريغامي مصممة بحيث يكون المكان الذي تضع فيه إجراءات كيريغامي ذا صلة. كما رأينا أعلاه، إذا أضفت إجراءات إلى Kirigami.Page أو Kirigami.ScrollablePage أو أي مكون صفحة مشتق آخر، فستظهر على الجانب الأيمن من الرأس في وضع سطح المكتب، وفي الأسفل في وضع الجوال.

وبالمثل، إذا أُضيفت إجراءات كيريغامي إلى Kirigami.GlobalDrawer، فستظهر في الدرج أو القائمة الناتجة.

أمثلة أخرى على إجراءات كيريغامي التي تظهر بشكل مختلف اعتمادًا على المكون الأصلي لها هي:

Kirigami.ContextDrawer - دليل ContextDrawer هنا
Kirigami.AbstractCard ومشتقاته - دليل البطاقات هنا
Kirigami.Dialog ومشتقاته - دليل الحوارات هنا
Kirigami.ActionToolBar - دليل شريط أدوات الإجراءات هنا

ضمن مكونات كيريجامي الأخرى.

تطبيقنا حتى الآن

Main.qml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 id: root

 width: 400
 height: 300

 title: i18nc("@title:window", "Day Kountdown")

 // Global drawer element with app-wide actions
 globalDrawer: Kirigami.GlobalDrawer {
 // Makes drawer a small menu rather than sliding pane
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }

 ListModel {
 id: kountdownModel
 ListElement {
 name: "Dog birthday!!"
 description: "Big doggo birthday blowout."
 date: 100
 }
 }

 Component {
 id: kountdownDelegate
 Kirigami.AbstractCard {
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2

 Kirigami.Heading {
 Layout.fillHeight: true
 level: 1
 text: date
 }

 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }
 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }
 Controls.Label {
 Layout.fillWidth: true
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: i18n("Edit")
 }
 }
 }
 }
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")

 // Kirigami.Action encapsulates a UI action. Inherits from Controls.Action
 actions: [
 Kirigami.Action {
 id: addAction
 // Name of icon associated with the action
 icon.name: "list-add-symbolic"
 // Action text, i18n function returns translated string
 text: i18nc("@action:button", "Add kountdown")
 // What to do when triggering the action
 onTriggered: kountdownModel.append({
 name: "Kirigami Action added card!",
 description: "Congratulations, your Kirigami Action works!",
 date: 1000
 })
 }
 ]

 Kirigami.CardsListView {
 id: cardsView
 model: kountdownModel
 delegate: kountdownDelegate
 }
 }
}

Docs: إضافة حوار

Mon, 01 Jan 0001 00:00:00 +0000

جعل تطبيقنا مفيدًا

لدينا نافذة، ولدينا بطاقات، ولدينا إجراءات. ومع ذلك، لا يزال يتعين علينا إيجاد طريقة لإدخال اسم ووصف وتاريخ من اختيارنا.

إحدى الطرق لفعل ذلك هي إنشاء صفحة جديدة نضع فيها عناصر الإدخال المطلوبة. لكن، تخصيص صفحة كاملة لتوفير اسم ووصف وتاريخ يبدو مبالغًا فيه بعض الشيء.

بدلاً من ذلك، سنستخدم حوارًا.

فتح الحوار

pageStack.initialPage: Kirigami.ScrollablePage {
 // ...
 actions: [
 Kirigami.Action {
 id: addAction
 icon.name: "list-add"
 text: i18nc("@action:button", "Add kountdown")
 onTriggered: addDialog.open()
 }
 ]
}

أولاً نعدّل الإجراء من الدليل السابق: مجرد Kirigami.Action يُشغّل دالة open() الخاصة بالحوار.

حوارات إضافة العد التنازلي

المكون الجديد الذي نضيفه هو Kirigami.Dialog. تظهر الحوارات في وسط النافذة ويمكن استخدامها لتوفير معلومات إضافية ذات صلة بالمحتوى الحالي. لا يمكن نقلها، لكنها تُكيّف حجمها مع النافذة.

Kirigami.ApplicationWindow {
 // ...
 Kirigami.Dialog {
 id: addDialog
 title: i18nc("@title:window", "Add kountdown")
 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 padding: Kirigami.Units.largeSpacing
 preferredWidth: Kirigami.Units.gridUnit * 20

 // تساعد تخطيطات النماذج في محاذاة وهيكلة تخطيط يحتوي على عدة مدخلات
 Kirigami.FormLayout {
 // تسمح لك حقول النص بإدخال نص في مربع نص رفيع
 Controls.TextField {
 id: nameField
 // يوفر تسمية ملحقة بحقل النص
 Kirigami.FormData.label: i18nc("@label:textbox", "Name*:")
 // ما يجب فعله بعد قبول الإدخال (أي الضغط على Enter). في هذه الحالة، ينقل التركيز
 // إلى الحقل التالي
 onAccepted: descriptionField.forceActiveFocus()
 }
 Controls.TextField {
 id: descriptionField
 Kirigami.FormData.label: i18nc("@label:textbox", "Description:")
 placeholderText: i18n("Optional")
 // مرة أخرى، ينقل التركيز إلى الحقل التالي
 onAccepted: dateField.forceActiveFocus()
 }
 Controls.TextField {
 id: dateField
 Kirigami.FormData.label: i18nc("@label:textbox", "ISO Date*:")
 // D تعني رقمًا مطلوبًا بين 1-9، 9 تعني رقمًا مطلوبًا بين 0-9
 inputMask: "D999-99-99"
 // هنا نؤكد العملية تمامًا مثل النقر على زر موافق
 onAccepted: addDialog.onAccepted()
 }
 Controls.Label {
 text: "* = required fields"
 }
 }
 // منطق الحوار يُوضع هنا
 }
 // ...
}

تحتوي الحوارات مبدئيًا على رأس وتذييل، وكلاهما موروث من Controls.Dialog.

يتضمن الرأس مبدئيًا عنوانًا وزر إغلاق يمكن تعطيله باستخدام showCloseButton. يتضمن التذييل مبدئيًا زر إغلاق، ويمكن تجاوزه باستخدام standardButtons.

نضبطه أولاً لعرض زر "موافق" وزر "إلغاء"، ونضيف بعض الحشو، ونضيف عرضًا مفضلاً معقولاً. العرض المفضل هو الحجم المبدئي المتوقع للحوار، والذي يمكن زيادته إذا لزم الأمر. يمكننا استخدام وحدات كيريجامي القياسية التي سنعود إليها لاحقًا.

ثم نصل إلى Kirigami.FormLayout. على عكس ColumnLayout، فإن تخطيط مكوناته الفرعية تلقائي ومتمركز، مع تسميات اختيارية. كما يوحي الاسم، يُستخدم لإنشاء نماذج إدخال.

صُممت تخطيطات النماذج هذه للعمل مع مجموعة متنوعة من أنواع الإدخال المختلفة، على الرغم من أننا نلتزم بمدخلات Controls.Textfield البسيطة التي تمنحنا مربعات نص بسيطة للكتابة فيها.

أنشأنا عناصر حقل نص تعمل كالتالي:

مدخل لاسم العد التنازلي لدينا
مدخل لوصف العد التنازلي لدينا
مدخل للتاريخ الذي نعد تنازليًا نحوه، ويجب تقديمه بصيغة YYYY-MM-DD

داخل كل عنصر من عناصر Controls.Textfield هذه، نضبط خاصية Kirigami.FormData.label التي تسمح لنا بتعريف لصائق لها. سيعرض النموذج اللصائق الصحيحة إلى يسار كل حقل من حقول إدخال النص هذه.

أخيرًا، نضبط أيضًا الخاصية onAccepted لتشغيل طريقة forceActiveFocus() للحقل التالي؛ سيؤدي هذا إلى تبديل الحقل النشط بمجرد ضغط المستخدم على مفتاح ENTER، مما يحسن قابلية استخدام النموذج.

وضعنا أيضًا خاصية تسمى inputMask على حقل النص الخاص بتاريخنا. ضبط هذا على D999-99-99 يمنع المستخدمين من إدخال شيء قد يعطل وظيفة التطبيق (مثل النص)، ويقيدهم بإدخال الأرقام فقط التي يمكننا بعد ذلك محاولة تحليلها إلى كائن تاريخ.

بمجرد الانتهاء من واجهة المستخدم للحوار، نحتاج إلى تغيير كيفية تصرفه. لهذا نحتاج إلى ثلاثة أشياء:

أظهر زر موافق فقط عند ملء الحقول المطلوبة
أضف معلومات الإدخال إلى النموذج
امسح نموذج الإدخال

Kirigami.Dialog {
 // ... بمجرد تهيئة Kirigami.Dialog، نريد إنشاء ربط مخصص لجعل زر موافق مرئيًا فقط إذا كانت حقول
 // النص المطلوبة ممتلئة. لهذا نستخدم Kirigami.Dialog.standardButton(button):
 Component.onCompleted: {
 const button = standardButton(Kirigami.Dialog.Ok);
 // () => هي دالة سهمية في جافا سكريبت
 button.enabled = Qt.binding( () => requiredFieldsFilled() );
 }
 onAccepted: {
 // تم إنشاء الربط، لكننا ما زلنا بحاجة إلى جعله غير قابل للنقر ما لم تكن الحقول ممتلئة
 if (!addDialog.requiredFieldsFilled()) return;
 appendDataToModel();
 clearFieldsAndClose();
 }
}

أول شيء يجب فعله هو إنشاء ربط بين خاصية enabled لزر موافق والتحقق مما إذا كانت الحقول ممتلئة، والذي يجب في هذه الحالة القيام به باستخدام Qt.binding() في جافا سكريبت. في الواقع، السطر:

button.enabled = Qt.binding( () => requiredFieldsFilled() );

مشابه لروابط QML التي رأيناها حتى الآن، كما في الكود الزائف التالي:

enabled: requiredFieldsFilled()

معالج الإشارة الذي يشغل زر موافق هو onAccepted. يبقى فارغًا ولا يفعل شيئًا إذا كانت الحقول المطلوبة ممتلئة؛ وإلا، سيضيف الإدخال إلى النموذج ويمسح الحوار للمرة التالية التي يُفتح فيها.

Kirigami.Dialog {
 // ... نتحقق من أن nameField ليس فارغًا وأن dateField (الذي يحتوي على inputMask) ممتلئ بالكامل
 function requiredFieldsFilled() {
 return (nameField.text !== "" && dateField.acceptableInput);
 }
 function appendDataToModel() {
 kountdownModel.append({
 name: nameField.text,
 description: descriptionField.text,
 date: new Date(dateField.text)
 });
 }
 function clearFieldsAndClose() {
 nameField.text = ""
 descriptionField.text = ""
 dateField.text = ""
 addDialog.close();
 }
}

بالنسبة لحقل الاسم المطلوب، كل ما نحتاج إليه هو التحقق مما إذا كان نص الحقل سلسلة فارغة. بالنسبة لحقل التاريخ، لأنه يحتوي على قناع إدخال، نحتاج إلى استخدام acceptableInput بدلاً من ذلك، والذي يصبح صحيحًا فقط بمجرد ملء الحقل بالكامل واحتوائه على أحرف مقبولة فقط.

ثم، طريقة append() لنموذج القائمة kountdownModel تضيف كائن جافا سكريبت يتضمن الخصائص التي قدمناها.

أخيرًا، نتأكد من مسح حقول النص عن طريق ضبط خصائص text الخاصة بها إلى سلسلة فارغة، ثم close() إغلاقه.

بمجرد حفظ ملفاتنا وبناء برنامجنا، سنكون قادرين على إضافة عداداتنا التنازلية المخصصة! يمكننا إجراء لمسة أخيرة لتحسين الواجهة، وهي إزالة العد التنازلي الوهمي الذي كان لدينا في الدروس السابقة:

26
27
28


 ListModel {
 id: kountdownModel
 }

ثانيًا، الآن بعد أن أصبح لدينا تاريخ فعلي للعمل به، يمكننا حساب الوقت حتى التاريخ المذكور:

47
48
49
50


 Kirigami.Heading {
 level: 1
 text: i18n("%1 days", Math.round((date-Date.now())/86400000))
 }

وثالثًا، زيادة حجم النافذة بحيث يكون لدينا مساحة أكبر لبطاقاتنا الجديدة:

 9
10


 width: 600
 height: 400

أجمل بكثير.

تطبيقنا حتى الآن

Main.qml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 id: root

 width: 600
 height: 400

 title: i18nc("@title:window", "Day Kountdown")

 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }

 ListModel {
 id: kountdownModel
 }

 Component {
 id: kountdownDelegate
 Kirigami.AbstractCard {
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2

 Kirigami.Heading {
 level: 1
 text: i18n("%1 days", Math.round((date-Date.now())/86400000))
 }

 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }
 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }
 Controls.Label {
 Layout.fillWidth: true
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: i18n("Edit")
 }
 }
 }
 }
 }

 Kirigami.Dialog {
 id: addDialog
 title: i18nc("@title:window", "Add kountdown")
 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 padding: Kirigami.Units.largeSpacing
 preferredWidth: Kirigami.Units.gridUnit * 20

 // Form layouts help align and structure a layout with several inputs
 Kirigami.FormLayout {
 // Textfields let you input text in a thin textbox
 Controls.TextField {
 id: nameField
 // Provides a label attached to the textfield
 Kirigami.FormData.label: i18nc("@label:textbox", "Name*:")
 // What to do after input is accepted (i.e. pressed Enter)
 // In this case, it moves the focus to the next field
 onAccepted: descriptionField.forceActiveFocus()
 }
 Controls.TextField {
 id: descriptionField
 Kirigami.FormData.label: i18nc("@label:textbox", "Description:")
 placeholderText: i18n("Optional")
 // Again, it moves the focus to the next field
 onAccepted: dateField.forceActiveFocus()
 }
 Controls.TextField {
 id: dateField
 Kirigami.FormData.label: i18nc("@label:textbox", "ISO Date*:")
 // D means a required number between 1-9,
 // 9 means a required number between 0-9
 inputMask: "D999-99-99"
 // Here we confirm the operation just like
 // clicking the OK button
 onAccepted: addDialog.onAccepted()
 }
 Controls.Label {
 text: "* = required fields"
 }
 }
 // Once the Kirigami.Dialog is initialized,
 // we want to create a custom binding to only
 // make the Ok button visible if the required
 // text fields are filled.
 // For this we use Kirigami.Dialog.standardButton(button):
 Component.onCompleted: {
 const button = standardButton(Kirigami.Dialog.Ok);
 // () => is a JavaScript arrow function
 button.enabled = Qt.binding( () => requiredFieldsFilled() );
 }
 onAccepted: {
 // The binding is created, but we still need to make it
 // unclickable unless the fields are filled
 if (!addDialog.requiredFieldsFilled()) return;
 appendDataToModel();
 clearFieldsAndClose();
 }
 // We check that the nameField is not empty and that the
 // dateField (which has an inputMask) is completely filled
 function requiredFieldsFilled() {
 return (nameField.text !== "" && dateField.acceptableInput);
 }
 function appendDataToModel() {
 kountdownModel.append({
 name: nameField.text,
 description: descriptionField.text,
 date: new Date(dateField.text)
 });
 }
 function clearFieldsAndClose() {
 nameField.text = ""
 descriptionField.text = ""
 dateField.text = ""
 addDialog.close();
 }
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")

 // Kirigami.Action encapsulates a UI action. Inherits from Controls.Action
 actions: [
 Kirigami.Action {
 id: addAction
 // Name of icon associated with the action
 icon.name: "list-add-symbolic"
 // Action text, i18n function returns translated string
 text: i18nc("@action:button", "Add kountdown")
 // What to do when triggering the action
 onTriggered: addDialog.open()
 }
 ]

 Kirigami.CardsListView {
 id: cardsView
 model: kountdownModel
 delegate: kountdownDelegate
 }
 }
}

Docs: استخدام ملفات منفصلة في مشروع C++

Mon, 01 Jan 0001 00:00:00 +0000

لماذا وكيف

لأول مرة، سنفصل بعض مكوناتنا إلى ملفات QML خاصة بها. إذا استمررنا في إضافة أشياء إلى Main.qml، سيصبح من الصعب سريعًا تمييز ما يفعل كل شيء، وسنخاطر بتشويش شفرتنا.

في هذا الدرس، سنقسم الشفرة في Main.qml إلى Main.qml وAddDialog.qml وKountdownDelegate.qml.

بالإضافة إلى ذلك، حتى عند توزيع الشفرة بين ملفات QML متعددة، يمكن أن يخرج عدد الملفات في المشاريع الحقيقية عن السيطرة. الحل الشائع لهذه المشكلة هو فصل الملفات منطقيًا إلى مجلدات مختلفة. سنلقي نظرة سريعة على ثلاثة أساليب شائعة تُرى في المشاريع الحقيقية، وسننفذ أحدها:

تخزين ملفات QML مع ملفات C++
تخزين ملفات QML في دليل مختلف تحت نفس الوحدة
تخزين ملفات QML في دليل مختلف تحت وحدة مختلفة

بعد التقسيم، سيكون لدينا فصل الاهتمامات بين كل ملف، وستُجرّد تفاصيل التنفيذ، مما يجعل الشفرة أكثر قابلية للقراءة.

تخزين ملفات QML مع ملفات C++

يتكون هذا من الاحتفاظ بملفات QML الخاصة بالمشروع مع ملفات C++ في src/. هذا النوع من الهيكل سيبدو هكذا:

kirigami-tutorial/
├── CMakeLists.txt
├── org.kde.tutorial.desktop
└── src/
├── CMakeLists.txt
├── main.cpp
├── Main.qml
├── AddDialog.qml
└── KountdownDelegate.qml

هذا ما فعلناه سابقًا. في الحالة أعلاه، ستحتاج فقط إلى الاستمرار في إضافة ملفات QML إلى kirigami-tutorial/src/CMakeLists.txt الموجود. لا يوجد فصل منطقي على الإطلاق، وبمجرد أن يحتوي المشروع على أكثر من ملفي QML (وملفات C++ التي تنشئ أنواعًا لاستخدامها في QML)، يمكن أن يصبح المجلد مزدحمًا بسرعة.

تخزين ملفات QML في دليل مختلف تحت نفس الوحدة

يتكون هذا من الاحتفاظ بجميع ملفات QML في مجلد منفصل، عادةً src/qml/. هذا النوع من الهيكل سيبدو هكذا:

kirigami-tutorial/
├── CMakeLists.txt
├── org.kde.tutorial.desktop
└── src/
├── CMakeLists.txt
├── main.cpp
└── qml/
├── Main.qml
├── AddDialog.qml
└── KountdownDelegate.qml

هذا الهيكل شائع جدًا في مشاريع كيدي، وذلك لتجنب وجود ملف CMakeLists.txt إضافي لدليل src/qml/ وإنشاء وحدة منفصلة. تحتفظ هذه الطريقة بالملفات نفسها في مجلد منفصل، لكنك ستحتاج أيضًا إلى إضافتها في kirigami-tutorial/src/CMakeLists.txt. ستنتمي جميع ملفات QML المنشأة بعد ذلك إلى نفس وحدة QML مثل Main.qml.

عمليًا، بمجرد أن يتجاوز المشروع عشرات ملفات QML، فإنه لن يزدحم في دليل src/، بل سيزحم ملف src/CMakeLists.txt. سيصبح من الصعب التفريق بين ملفات C++ التقليدية وملفات C++ التي تحتوي على أنواع مكشوفة لـ QML.

سيكسر أيضًا مفهوم المحلية (توطين تفاصيل التبعيات)، حيث ستحتفظ بوصف تبعياتك في نفس مكان التبعيات نفسها.

تخزين ملفات QML في دليل مختلف تحت وحدة مختلفة

يتكون هذا من الاحتفاظ بجميع ملفات QML في مجلد منفصل مع ملف CMakeLists.txt الخاص به ووحدة QML منفصلة خاصة به. ستبدو هذه البنية هكذا:

kirigami-tutorial/
├── CMakeLists.txt
├── org.kde.tutorial.desktop
└── src/
├── CMakeLists.txt
├── main.cpp
├── Main.qml
└── components/
├── CMakeLists.txt
├── AddDialog.qml
└── KountdownDelegate.qml

هذه البنية ليست شائعة في مشاريع كيدي وتتطلب كتابة ملف CMakeLists.txt إضافي، لكنها الأكثر مرونة. في حالتنا، نسمي مجلدنا "components" لأننا ننشئ مكوني QML جديدين من ملف Main.qml السابق، ونحتفظ بمعلومات عنهما في kirigami-tutorial/src/components/CMakeLists.txt. يبقى ملف Main.qml نفسه في src/ ليُستخدم آليًا عند تشغيل المنفذ، كما في السابق.

لاحقًا، سيكون من الممكن إنشاء المزيد من المجلدات بملفات QML متعددة، مجمعة جميعًا حسب الوظيفة، مثل "models" و"settings"، ويمكن الاحتفاظ بملفات C++ التي تحتوي على أنواع مكشوفة لـ QML (مثل النماذج) مع ملفات QML الأخرى حيثما كان ذلك منطقيًا.

سنستخدم هذه البنية في هذا الدليل.

تحضير CMake للملفات الجديدة

أولاً، أنشئ الملف kirigami-tutorial/src/components/CMakeLists.txt بالمحتويات التالية:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


add_library(kirigami-hello-components)

ecm_add_qml_module(kirigami-hello-components
 URI "org.kde.tutorial.components"
 GENERATE_PLUGIN_SOURCE
)

ecm_target_qml_sources(kirigami-hello-components
 SOURCES
 AddDialog.qml
 KountdownDelegate.qml
)

ecm_finalize_qml_module(kirigami-hello-components)

install(TARGETS kirigami-hello-components ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

ننشئ هدفًا جديدًا يُدعى kirigami-hello-components ثم نحوله إلى وحدة QML باستعمال ecm_add_qml_module() تحت اسم الاستيراد org.kde.tutorial.components ونضيف ملفات QML ذات الصلة.

لأن الهدف مختلف عن المنفذ، سيعمل كوحدة QML مختلفة، وفي هذه الحالة سنحتاج إلى فعل شيئين: جعله يُولّد كودًا ليعمل كملحق Qt باستخدام GENERATE_PLUGIN_SOURCE، وإنهاؤه باستخدام ecm_finalize_qml_module(). ثم نُثبته تمامًا كما في الدروس السابقة.

احتجنا إلى استخدام add_library() لنتمكن من ربط kirigami-hello-components بالمنفذ في استدعاء target_link_libraries() في kirigami-tutorial/src/CMakeLists.txt:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


add_executable(kirigami-hello)

ecm_add_qml_module(kirigami-hello
 URI
 org.kde.tutorial
)

target_sources(kirigami-hello
 PRIVATE
 main.cpp
)

ecm_target_qml_sources(kirigami-hello
 SOURCES
 Main.qml
)

target_link_libraries(kirigami-hello
 PRIVATE
 Qt6::Quick
 Qt6::Qml
 Qt6::Gui
 Qt6::QuickControls2
 Qt6::Widgets
 KF6::I18n
 KF6::CoreAddons
 KF6::IconThemes
 kirigami-hello-components
)

install(TARGETS kirigami-hello ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

add_subdirectory(components)

نحتاج أيضًا إلى استخدام add_subdirectory() ليجد CMake الدليل kirigami-tutorial/src/components/.

في الدروس السابقة، لم نحتج إلى إضافة الاستيراد org.kde.tutorial إلى ملف Main.qml لأنه لم يكن ضروريًا: بكونه نقطة الدخول للتطبيق، كان المنفذ سيشغل الملف فورًا على أي حال. بما أن مكوناتنا في وحدة QML منفصلة، فإن استيرادًا جديدًا في kirigami-tutorial/src/Main.qml ضروري، وهو نفسه المُعرّف سابقًا، org.kde.tutorial.components:

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

// بقية الكود...

ونحن مستعدون للانطلاق.

تقسيم Main.qml

دعنا نلقي نظرة مرة أخرى على Main.qml الأصلي:

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 id: root

 width: 600
 height: 400

 title: i18nc("@title:window", "Day Kountdown")

 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }

 ListModel {
 id: kountdownModel
 }

 Component {
 id: kountdownDelegate
 Kirigami.AbstractCard {
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2

 Kirigami.Heading {
 level: 1
 text: i18n("%1 days", Math.round((date-Date.now())/86400000))
 }

 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }
 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }
 Controls.Label {
 Layout.fillWidth: true
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: i18n("Edit")
 }
 }
 }
 }
 }

 Kirigami.Dialog {
 id: addDialog
 title: i18nc("@title:window", "Add kountdown")
 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 padding: Kirigami.Units.largeSpacing
 preferredWidth: Kirigami.Units.gridUnit * 20

 // Form layouts help align and structure a layout with several inputs
 Kirigami.FormLayout {
 // Textfields let you input text in a thin textbox
 Controls.TextField {
 id: nameField
 // Provides a label attached to the textfield
 Kirigami.FormData.label: i18nc("@label:textbox", "Name*:")
 // What to do after input is accepted (i.e. pressed Enter)
 // In this case, it moves the focus to the next field
 onAccepted: descriptionField.forceActiveFocus()
 }
 Controls.TextField {
 id: descriptionField
 Kirigami.FormData.label: i18nc("@label:textbox", "Description:")
 placeholderText: i18n("Optional")
 // Again, it moves the focus to the next field
 onAccepted: dateField.forceActiveFocus()
 }
 Controls.TextField {
 id: dateField
 Kirigami.FormData.label: i18nc("@label:textbox", "ISO Date*:")
 // D means a required number between 1-9,
 // 9 means a required number between 0-9
 inputMask: "D999-99-99"
 // Here we confirm the operation just like
 // clicking the OK button
 onAccepted: addDialog.onAccepted()
 }
 Controls.Label {
 text: "* = required fields"
 }
 }
 // Once the Kirigami.Dialog is initialized,
 // we want to create a custom binding to only
 // make the Ok button visible if the required
 // text fields are filled.
 // For this we use Kirigami.Dialog.standardButton(button):
 Component.onCompleted: {
 const button = standardButton(Kirigami.Dialog.Ok);
 // () => is a JavaScript arrow function
 button.enabled = Qt.binding( () => requiredFieldsFilled() );
 }
 onAccepted: {
 // The binding is created, but we still need to make it
 // unclickable unless the fields are filled
 if (!addDialog.requiredFieldsFilled()) return;
 appendDataToModel();
 clearFieldsAndClose();
 }
 // We check that the nameField is not empty and that the
 // dateField (which has an inputMask) is completely filled
 function requiredFieldsFilled() {
 return (nameField.text !== "" && dateField.acceptableInput);
 }
 function appendDataToModel() {
 kountdownModel.append({
 name: nameField.text,
 description: descriptionField.text,
 date: new Date(dateField.text)
 });
 }
 function clearFieldsAndClose() {
 nameField.text = ""
 descriptionField.text = ""
 dateField.text = ""
 addDialog.close();
 }
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")

 // Kirigami.Action encapsulates a UI action. Inherits from Controls.Action
 actions: [
 Kirigami.Action {
 id: addAction
 // Name of icon associated with the action
 icon.name: "list-add-symbolic"
 // Action text, i18n function returns translated string
 text: i18nc("@action:button", "Add kountdown")
 // What to do when triggering the action
 onTriggered: addDialog.open()
 }
 ]

 Kirigami.CardsListView {
 id: cardsView
 model: kountdownModel
 delegate: kountdownDelegate
 }
 }
}

يمكن تقسيم المفوض المخصص ذو id: kountdownDelegate بالكامل لأنه مُغلف بالفعل في نوع مكون QML. نستخدم مكونًا لنتمكن من تعريفه دون الحاجة إلى إنشاء مثيل له؛ تعمل ملفات QML المنفصلة بنفس الطريقة.

إذا نقلنا الكود إلى ملفات منفصلة، فلا فائدة من تركه مُغلفًا في مكون: يمكننا تقسيم Kirigami.AbstractCard فقط في الملف المنفصل. إليك KountdownDelegate.qml الناتج:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.AbstractCard {
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2

 Kirigami.Heading {
 level: 1
 text: i18n("%1 days", Math.round((date-Date.now())/86400000))
 }

 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }
 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }
 Controls.Label {
 Layout.fillWidth: true
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: i18n("Edit")
 }
 }
 }
}

حوارنا ذو id: addDialog ليس مُغلفًا في مكون، وليس مكونًا مرئيًا مبدئيًا، لذا يمكن نسخ الكود كما هو إلى AddDialog.qml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.Dialog {
 id: addDialog
 title: i18nc("@title:window", "Add kountdown")
 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 padding: Kirigami.Units.largeSpacing
 preferredWidth: Kirigami.Units.gridUnit * 20

 Kirigami.FormLayout {
 Controls.TextField {
 id: nameField
 Kirigami.FormData.label: i18nc("@label:textbox", "Name*:")
 onAccepted: descriptionField.forceActiveFocus()
 }
 Controls.TextField {
 id: descriptionField
 Kirigami.FormData.label: i18nc("@label:textbox", "Description:")
 onAccepted: dateField.forceActiveFocus()
 }
 Controls.TextField {
 id: dateField
 Kirigami.FormData.label: i18nc("@label:textbox", "ISO Date*:")
 inputMask: "D999-99-99"
 onAccepted: addDialog.accepted()
 }
 Controls.Label {
 text: "* = required fields"
 }
 }
 Component.onCompleted: {
 const button = standardButton(Kirigami.Dialog.Ok);
 button.enabled = Qt.binding( () => requiredFieldsFilled() );
 }
 onAccepted: {
 if (!addDialog.requiredFieldsFilled()) return;
 appendDataToModel();
 clearFieldsAndClose();
 }
 function requiredFieldsFilled() {
 return (nameField.text !== "" && dateField.acceptableInput);
 }
 function appendDataToModel() {
 kountdownModel.append({
 name: nameField.text,
 description: descriptionField.text,
 date: new Date(dateField.text)
 });
 }
 function clearFieldsAndClose() {
 nameField.text = ""
 descriptionField.text = ""
 dateField.text = ""
 addDialog.close();
 }
}

مع تقسيم الكود، يصبح Main.qml أقصر بكثير:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.ApplicationWindow {
 id: root

 width: 600
 height: 400

 title: i18nc("@title:window", "Day Kountdown")

 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }

 ListModel {
 id: kountdownModel
 }

 AddDialog {
 id: addDialog
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")

 actions: [
 Kirigami.Action {
 id: addAction
 icon.name: "list-add-symbolic"
 text: i18nc("@action:button", "Add kountdown")
 onTriggered: addDialog.open()
 }
 ]

 Kirigami.CardsListView {
 id: cardsView
 model: kountdownModel
 delegate: KountdownDelegate {}
 }
 }
}

لدينا الآن ملفا QML إضافيان، AddDialog.qml وKountdownDelegate، ونحتاج إلى إيجاد طريقة لاستخدامهما في Main.qml. طريقة إضافة محتويات الملفات الجديدة إلى Main.qml هي عن طريق إنشاء مثيل لها.

يصبح AddDialog.qml هو AddDialog {}:

31
32
33


 AddDialog {
 id: addDialog
 }

يصبح KountdownDelegate.qml هو KountdownDelegate {}:

47
48
49
50
51


 Kirigami.CardsListView {
 id: cardsView
 model: kountdownModel
 delegate: KountdownDelegate {}
 }

معظم الحالات التي رأيتها لمكون يبدأ بحرف كبير متبوعًا بأقواس كانت إنشاءات مثيل لمكون QML. لهذا تحتاج ملفات QML الجديدة إلى البدء بحرف كبير.

ترجم المشروع وشغّله، ويجب أن تحصل على نافذة وظيفية تتصرف تمامًا كما في السابق، ولكن مع تقسيم الكود إلى أجزاء منفصلة، مما يجعل الأمور أكثر قابلية للإدارة.

Docs: الخطوات التالية

Mon, 01 Jan 0001 00:00:00 +0000

ما بنيناه

على مدار الدروس القليلة الماضية، بنيت تطبيق كيريجامي أساسيًا لكنه وظيفي يتيح لك إضافة وتحرير وحذف العد التنازلي للتواريخ. بذلك تعلمنا عن مكوّنات كيريجامي وكيوت كويك، وبعضًا من كيفية عمل QML، والتخطيطات الأساسية للتطبيقات، والمزيد. ليس سيئًا على الإطلاق!

لديك الآن فهم للأساسيات التي تُشكّل العديد من تطبيقات كيدي الأكثر شعبية. قد تسأل نفسك: ماذا الآن؟

حسنًا، لا تقلق: فقد خصصنا وقتًا لتقديم بعض الإرشادات حول أين يمكنك التوجه من هنا.

المساهمة في مشاريع كيدي

من أفضل طرق تحسين مهاراتك التطويرية هي بوضعها موضع التطبيق. مجتمع كيدي يرحب بالجميع ويبحث دائمًا عن مطورين متحمسين أكثر!

لدينا عدة قطع من الوثائق التي يمكن أن تساعد في توجيهك نحو أن تصبح مساهمًا. نوصي بإلقاء نظرة على صفحات التطوير الأخرى لدينا والتي يمكن أن تساعدك في معرفة المزيد عن سير عمل التطوير لمجتمع كيدي. نوصي أيضًا بإلقاء نظرة على وثائقنا لنسخة كيدي من غيت لاب، المسماة إنفنت، حيث من المحتمل أن تحتاج إلى التفاعل معها أثناء عملية التطوير. يتفاعل مجتمع كيدي بشكل رئيسي عبر ماتريكس، ولدينا أيضًا صفحة على ويكي المجتمع التي ستوجهك خلال إعداد حسابك الخاص.

ملاحظة

أثناء التفاعل مع الآخرين في مجتمع كيدي، يرجى التأكد من الالتزام بـمدونة قواعد السلوك.

بمهاراتك الجديدة، أنت في وضع جيد لبدء المساهمة في مشاريع كيريغامي. لحسن الحظ، العديد من تطبيقات ومكونات كيدي الأكثر شعبية مبنية بهذا الإطار. إليك قائمة بالمشاريع التي نرحب بمساعدتك فيها.

مشاريع كيريغامي صديقة للمبتدئين

المشروع	ما هو	روابط
كاليندوري	تطبيق تقويم صديق للمس مصمم للأجهزة المحمولة.	صفحة تطبيقات كيدي صفحة كيدي إنفنت
كوكو	عارض صور مصمم لأجهزة سطح المكتب واللمس.	صفحة تطبيقات كيدي صفحة كيدي إنفنت
كونتراست	مدقق تباين ألوان يخبرك إذا كانت تركيبات ألوانك متاحة للأشخاص ذوي نقص رؤية الألوان.	صفحة تطبيقات كيدي صفحة كيدي إنفنت
ليسنتيا	تطبيق لمساعدتك في اختيار الترخيص المناسب لمشروعك.	صفحة تطبيقات كيدي صفحة كيدي إنفنت
ترحيب بلازما	تطبيق ترحيب لسطح مكتب بلازما يتيح لك إنشاء صفحات جديدة باستخدام كيو إم إل.	صفحة كيدي إنفنت

مشاريع كيريغامي الأكثر تعقيدًا

المشروع	ما هو	روابط
ديسكوفر	تطبيق يساعدك في العثور على التطبيقات والألعاب والأدوات وتثبيتها.	صفحة تطبيقات كيدي صفحة كيدي إنفنت
إليزا	مشغل موسيقى يسعى ليكون بسيطًا ولطيف الاستخدام.	الصفحة الرئيسية صفحة تطبيقات كيدي صفحة ويكي مجتمع كيدي صفحة كيدي إنفنت
كيدي كونكت	تطبيق متعدد المنصات يسمح لأجهزتك بالتواصل (مثل: هاتفك وحاسوبك).	الصفحة الرئيسية صفحة ويكي مجتمع كيدي صفحة كيدي إنفنت
كونغرس	تطبيق مرافق لحضور المؤتمرات.	صفحة كيدي إنفنت
نيو شات	عميل لماتريكس، بروتوكول الاتصال اللامركزي للمراسلة الفورية.	صفحة تطبيقات كيدي صفحة كيدي إنفنت

تعلم المزيد

لا تشعر بأنك مستعد تمامًا بعد؟ لا بأس بذلك أيضًا.

العديد من المشاريع المذكورة أعلاه هي موارد تعلم لا تُقدر بثمن. يمكنك الاطلاع على الشيفرة ومعرفة كيف أنشأ المطورون ذوو الخبرة تطبيقات كاملة الميزات، واستخدام هذه التقنيات بنفسك.

إذا شعرت أنك بحاجة إلى نهج أكثر لطفًا، فقد جمعنا أيضًا بعض الموارد التي نعتقد أنها قد تكون مفيدة لك.

الواجهة الخلفية وسي++

بينما تعلمنا الكثير عن QML، لم نتطرق كثيرًا إلى كيفية التعامل مع شيفرة الواجهة الخلفية. ومع ذلك، هذا جانب أساسي من تطوير تطبيقات كيدي.

سي++/كيوت مع كيريغامي

في القسم المتقدم من وثائق كيريغامي هذه، لدينا بعض الصفحات التي يمكن أن تساعدك في البدء:

صفحة	الموضوع
فهم CMakeLists	تعلم كل شيء عن CMake وكيفية ترجمة تطبيقاتك.
فهم main.cpp	التعامل مع ملف سي++ المركزي الذي يدير تهيئة تطبيقك.
ربط المنطق بواجهة المستخدم QML الخاصة بك	أضف وظائف متقدمة إلى تطبيق كيريغامي الخاص بك واربطها بواجهة المستخدم الخاصة بك.
صفحة حول	أضف "صفحة حول" إلى واجهة المستخدم الخاصة بك.

موارد سي++ للمبتدئين

إذا كنت جديدًا تمامًا على سي++، فهناك موارد عديدة متاحة على الويب. إليك بعضًا منها قد تكون مفيدة.

مورد	الموضوع
LearnCpp	دروس لإتقان لغة C++
cppreference	موقع مرجعي للغة C++
ويكيبوكس C++	ويكيبوكس شامل بدروس وتمارين C++
W3Schools C++	مجموعة دروس C++ وموارد أخرى موجهة للمبتدئين

نوفر أيضًا قائمة موارد محدثة باستمرار لتعلم C++ في تعلم المزيد.

إنشاء تطبيقات كيدي تقليدية باستخدام QtWidgets

إذا أردت العمل على تطبيقات كيدي مثل دولفين أو كونتاكت أو كيت، فستحتاج إلى تعلم استخدام QtWidgets الذي يستخدم طريقة مختلفة تمامًا لتطوير واجهات المستخدم مع كيوت. تميل تطبيقات كيدي الأكثر تعقيدًا أو التطبيقات التي تتبع تصميمًا تقليديًا إلى البناء باستخدام QtWidgets.

العمل مع QtWidgets أصعب نوعًا ما من QML (وأكثر كثافة في C++ بكثير!). لحسن الحظ، لدينا مجموعة دروس في وثائق كيدي ستساعدك على التعود عليها.

السماء هي الحد!

لا تخف من كل المواد هنا! لا أحد يبدأ قادرًا على إنشاء شيء مثل بلازما من الصفر. لكن كيدي ليست شركة بمليارات الدولارات ذات حاجز دخول مرتفع (ليس لدينا مقابلات برمجة من خمس جولات!) وطالما كنت لطيفًا، فسيتم الترحيب بك.

حظًا موفقًا!

Docs: الألوان والسمات في كيريغامي

Mon, 01 Jan 0001 00:00:00 +0000

تمتلك كيريغامي لوحة ألوان تتبع ألوان النظام لتحسين التكامل مع المنصة التي تعمل عليها (مثل سطح مكتب بلازما، بلازما المحمول، جنوم، أندرويد، إلخ).

جميع مكونات كيريغامي QML وعناصر تحكم QtQuick تتبع هذه اللوحة مبدئيًا، لذا لا حاجة عادةً لتلوين مخصص لهذه العناصر.

يجب تلوين المكونات البدائية مثل Rectangle دائمًا باستخدام لوحة الألوان التي توفرها كيريغامي عبر الخاصية المرفقة Kirigami.Theme.

يُتجنب عادةً الألوان المقننة في QML مثل #32b2fa أو red؛ إذا كانت الحاجة ملحة لعناصر بألوان مخصصة، فيجب أن تكون في منطقة تستخدم ألوانًا مخصصة فقط (عادةً في منطقة المحتوى من التطبيق، وأبدًا في مناطق الإطار مثل أشرطة الأدوات أو الحوارات). مثلًا، لا يمكن استخدام لون أمامي مقنن black فوق خلفية Kirigami.Theme.backgroundColor، لأنه إذا استخدمت المنصة نظام ألوان داكنًا، ستكون النتيجة تباينًا ضعيفًا مع الأسود فوق الأسود تقريبًا. هذه مشكلة وصولية ويجب تجنبها.

ملاحظة

إذا احتجت حقًا لاستخدام ألوان مخصصة، فتفقد Kontrast لضمان أن الألوان التي تختارها ذات تباين جيد ومتوافقة مع WCAG.

السمة

Kirigami.Theme هي خاصية مرفقة، وبالتالي فهي متاحة للاستخدام لأي عنصر QML. تتضمن خصائصها جميع الألوان المتاحة في اللوحة، وأي لوحة يجب استخدامها، مثل خاصية colorSet.

import QtQuick
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 height: 300
 width: 400

 pageStack.initialPage: Kirigami.Page {
 Rectangle {
 anchors.centerIn: parent
 implicitHeight: 100
 implicitWidth: 200
 color: Kirigami.Theme.highlightColor
 }
 }
}

يوفر معرض كيريغامي مثالًا برمجيًا يعرض جميع الألوان المتاحة لكيريغامي عبر Kirigami.Theme. يشمل ذلك جميع حالاتها: إذا نقرت خارج النافذة، تتغير الألوان إلى حالتها غير النشطة، وإذا بدّلت نظامك إلى سمة داكنة، تظهر المتغيرات الداكنة للألوان في الوقت الفعلي.

مكون الألوان في معرض كيريغامي

مجموعة الألوان

اعتمادًا على موقع عنصر التحكم، يجب أن يستخدم مجموعة ألوان مختلفة: مثلًا، عند استخدام نظام ألوان Breeze الفاتح في العروض، تكون الخلفية العادية بيضاء تقريبًا، بينما في مناطق أخرى مثل أشرطة الأدوات أو الحوارات، يكون لون الخلفية العادية رماديًا.

إذا عرّفت مجموعة ألوان لعنصر، فسترثها جميع العناصر الفرعية تلقائيًا بشكل متكرر (إلا إذا ضُبطت الخاصية inherit صراحةً على false، ويجب فعل ذلك دائمًا عندما يريد المطور فرض مجموعة ألوان محددة)، لذا من السهل تغيير الألوان لتسلسل هرمي كامل من العناصر دون لمس أي من العناصر نفسها.

يدعم Kirigami.Theme 5 مجموعات ألوان مختلفة:

العرض: مجموعة ألوان لعروض العناصر، عادةً الأفتح بينها (في سمات الألوان الفاتحة)
النافذة: مجموعة ألوان للنوافذ ومناطق الإطار (هذه أيضًا مجموعة الألوان المبدئية)
الزر: مجموعة ألوان تستخدمها الأزرار
التحديد: مجموعة ألوان تستخدمها المناطق المحددة
التلميح: مجموعة ألوان تستخدمها التلميحات
المكمل: مجموعة ألوان مخصصة لتكون مكملة للنافذة: عادةً داكنة حتى في السمات الفاتحة. قد تُستخدم للتأكيد في مناطق صغيرة من التطبيق

هذا مثال يوضح كيف تُورث مجموعات الألوان ويمكن استخدامها لتمييز المكونات المختلفة. أُضيف حد كبير لتباين الألوان.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83


import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

// The comments assume the system uses the Breeze color theme

Kirigami.ApplicationWindow {
 height: 500
 width: 800

 Rectangle {
 anchors.fill: parent
 border.width: 5

 // A gray color will be used, as the default color set is Window
 color: Kirigami.Theme.backgroundColor

 Controls.Label {
 // The text will be near-black, as defined in the Window color set for light themes
 text: "Rectangle that uses default background color\nfrom the Window color set"
 padding: 100
 }
 Rectangle {
 anchors.bottom: parent.bottom
 border.width: 5
 width: parent.width
 height: Math.round(parent.height / 2)

 // Use the color set used for Views
 Kirigami.Theme.colorSet: Kirigami.Theme.View
 // Do not inherit from the parent
 Kirigami.Theme.inherit: false
 // This will be a near-white color in light themes
 color: Kirigami.Theme.backgroundColor

 Controls.Label {
 text: "Rectangle that does not inherit the default background color\nand uses the Theme.View color set"
 padding: 50

 }

 Rectangle {
 anchors.bottom: parent.bottom
 anchors.left: parent.left
 border.width: 5
 width: Math.round(parent.width / 2)
 height: Math.round(parent.height / 2)

 // This will be a near-white color too, as the color set
 // is inherited from the parent and will be View
 color: Kirigami.Theme.backgroundColor

 Controls.Label {
 // The text will be near-black, as defined in the View color set for light themes
 text: "Rectangle that inherits the Theme.View color set"
 anchors.centerIn: parent
 }
 }

 Rectangle {
 anchors.bottom: parent.bottom
 anchors.right: parent.right
 border.width: 5
 width: Math.round(parent.width / 2)
 height: Math.round(parent.height / 2)

 // Use the Complementary set
 Kirigami.Theme.colorSet: Kirigami.Theme.Complementary
 // Do not inherit from the parent
 Kirigami.Theme.inherit: false
 // This will be near-black as the background color
 // of the Complementary color set is dark in light themes
 color: Kirigami.Theme.backgroundColor

 Controls.Label {
 // The text will be near-white, as defined in the Complementary color set for light themes
 text: "Rectangle that does not inherit the Theme.View\nand uses Theme.Complementary instead"
 anchors.centerIn: parent
 }
 }
 }
 }
}

كيف تختلف مجموعات الألوان في Breeze

كيف تختلف مجموعات الألوان في Breeze الداكن

استخدام الألوان المخصصة

رغم أنه لا يُشجع استخدام الألوان المقننة، تقدم كيريغامي طريقة أكثر قابلية للصيانة لتعيين لوحة مقننة مخصصة لعنصر وجميع أبنائه، مما يسمح بتعريف هذه الألوان المخصصة في مكان واحد فقط:

import QtQuick
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Custom colors"
 height: 300
 width: 300

 Rectangle {
 anchors.fill: parent
 Kirigami.Theme.inherit: false
 // ملاحظة: بغض النظر عن مجموعة الألوان المستخدمة، يُوصى باستبدال جميع الألوان المتاحة في
 // السمة، لتجنب الألوان ضعيفة التباين

 Kirigami.Theme.colorSet: Kirigami.Theme.Window
 Kirigami.Theme.backgroundColor: "#b9d795"
 Kirigami.Theme.textColor: "#465c2b"
 Kirigami.Theme.highlightColor: "#89e51c"
 // أعد تعريف جميع الألوان الأخرى التي تريدها

 // سيكون هذا "#b9d795"
 color: Kirigami.Theme.backgroundColor

 Rectangle {
 // سيكون هذا "#465c2b"
 anchors.centerIn: parent
 height: Math.round(parent.height / 2)
 width: Math.round(parent.width / 2)
 color: Kirigami.Theme.textColor
 }
 }
}

مثال بألوان مخصصة

Docs: الطباعة

Mon, 01 Jan 0001 00:00:00 +0000

لأغراض توضيحية، يستخدم هذا الدليل بطاقة مجردة (AbstractCard) لجعل أمثلة النص أوضح. طريقة أفضل لتحقيق النتائج نفسها هي استخدام بطاقة نموذج إضافات كيريغامي.

العناوين

يوفر كيريغامي عنوانًا يمكن استخدامه لعناوين الصفحات أو الأقسام.

import QtQuick
import QtQuick.Layouts
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Kirigami Heading"
 height: 400
 width: 400

 pageStack.initialPage: Kirigami.Page {
 Kirigami.AbstractCard {
 anchors.fill: parent
 contentItem: ColumnLayout {
 anchors.fill: parent
 Kirigami.Heading {
 text: "Heading level 1"
 level: 1
 }
 Kirigami.Heading {
 text: "Heading level 2"
 level: 2
 }
 Kirigami.Heading {
 text: "Heading level 3"
 level: 3
 }
 Kirigami.Heading {
 text: "Heading level 4"
 level: 4
 }
 Kirigami.Heading {
 text: "Heading level 5"
 level: 5
 }
 }
 }
 }
}

اللصائق

يجب أن تستخدم عناصر النص مكون اللصيقة من أدوات كيوت السريعة 2.

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls Label"
 height: 400
 width: 400

 pageStack.initialPage: Kirigami.Page {
 Kirigami.AbstractCard {
 anchors.fill: parent
 contentItem: Controls.Label {
 text: "My text"
 }
 }
 }
}

محاذاة النص

يمكنك محاذاة عناصر النص باستخدام الخاصيتين horizontalAlignment و verticalAlignment.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls Horizontal Center"
 height: 400
 width: 400

 pageStack.initialPage: Kirigami.Page {
 Kirigami.AbstractCard {
 anchors.fill: parent
 contentItem: ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 horizontalAlignment: Text.AlignHCenter
 text: "Welcome to my application"
 wrapMode: Text.Wrap
 }
 Controls.Label {
 Layout.fillWidth: true
 horizontalAlignment: Text.AlignHCenter
 text: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante."
 wrapMode: Text.Wrap
 }
 }
 }
 }
}

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Horizontal Align Right"
 height: 400
 width: 400

 pageStack.initialPage: Kirigami.Page {
 Kirigami.AbstractCard {
 anchors.fill: parent
 contentItem: ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 horizontalAlignment: Text.AlignRight
 text: "Welcome to my application"
 wrapMode: Text.Wrap
 }
 Controls.Label {
 Layout.fillWidth: true
 horizontalAlignment: Text.AlignRight
 text: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante."
 wrapMode: Text.Wrap
 }
 }
 }
 }
}

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Bottom and Top"
 height: 400
 width: 400

 pageStack.initialPage: Kirigami.Page {
 Kirigami.AbstractCard {
 anchors.fill: parent
 contentItem: ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 Layout.fillHeight: true
 verticalAlignment: Text.AlignBottom
 text: "Welcome to my application"
 wrapMode: Text.WordWrap
 }
 Controls.Label {
 Layout.fillWidth: true
 Layout.fillHeight: true
 verticalAlignment: Text.AlignTop
 text: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante."
 wrapMode: Text.WordWrap
 }
 }
 }
 }
}

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Top and Bottom"
 height: 400
 width: 400

 pageStack.initialPage: Kirigami.Page {
 Kirigami.AbstractCard {
 anchors.fill: parent
 contentItem: ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 Layout.fillHeight: true
 verticalAlignment: Text.AlignTop
 text: "Welcome to my application"
 wrapMode: Text.WordWrap
 }
 Controls.Label {
 Layout.fillWidth: true
 Layout.fillHeight: true
 verticalAlignment: Text.AlignBottom
 text: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante."
 wrapMode: Text.WordWrap
 }
 }
 }
 }
}

نص منسق

تسمح لك كيوإمإل بعرض (وتحرير) النص المنسق. يمكن التحكم في السلوك عبر الخاصية textFormat.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls Label with rich text"
 height: 400
 width: 400

 pageStack.initialPage: Kirigami.Page {
 Kirigami.AbstractCard {
 anchors.fill: parent
 contentItem: Controls.Label {
 text: "<p><strong>List of fruits to purchase</strong></p>
 <ul>
 <li>Apple</li>
 <li>Cherry</li>
 <li>Orange</li>
 <li><del>Banana</del></li>
 </ul>
 <p>Kris already got some bananas yesterday.</p>"
 }
 }
 }
}

السمة

حجم خط سمة كيريغامي متاح كـ Kirigami.Theme.defaultFont.pointSize في تطبيقك.

Docs: المكونات القائمة على الإجراءات

Mon, 01 Jan 0001 00:00:00 +0000

الإجراءات

يتكون Kirigami.Action من إجراء قابل للنقر يعتمد مظهره على مكان إضافته. عادةً ما يكون زرًا برمز ونص.

يمكننا استخدام هذه لتزويد تطبيقاتنا بإجراءات سهلة الوصول إليها وهي أساسية لوظائفها.

ملاحظة

ترث إجراءات كيريغامي من QtQuick.Controls.Action ويمكن إسناد اختصارات إليها.

مثل إجراءات تحكمات كيوت كويك، يمكن إسنادها إلى عناصر القوائم وأزرار أشرطة الأدوات، ولكن أيضًا إلى مكونات كيريغامي أخرى متعددة.

import org.kde.kirigami as Kirigami

Kirigami.Action {
 id: copyAction
 text: i18n("Copy")
 icon.name: "edit-copy"
 shortcut: StandardKey.Copy
 onTriggered: {
 // ...
 }
}

ملاحظة

تأخذ الخاصية icon.name أسماء أيقونات على مستوى النظام وفقًا لمواصفات فري دسكتوب. يمكن عرض هذه الأيقونات وأسمائها باستخدام تطبيق كاتل فيش الخاص بكيدي والمرفوع مع plasma-sdk، أو بزيارة مواصفات تسمية أيقونات فري دسكتوب.

إحدى الميزات التي تقدمها إجراءات كيريغامي فوق إجراءات كيوت كويك هي إمكانية تداخل الإجراءات.

import org.kde.kirigami as Kirigami

Kirigami.Action {
 text: "View"
 icon.name: "view-list-icons"
 Kirigami.Action {
 text: "action 1"
 }
 Kirigami.Action {
 text: "action 2"
 }
 Kirigami.Action {
 text: "action 3"
 }
}

ميزة أخرى لإجراءات كيريغامي هي تقديم تلميحات متنوعة للعناصر التي تستخدم الإجراءات حول كيفية عرضها للإجراء. تُعالج هذه بشكل أساسي بواسطة الخاصيتين displayHint و displayComponent.

سيُحترم هذه الخصائص من قبل العنصر إن أمكن. على سبيل المثال، سيُعرض الإجراء التالي كـ TextField مع محاولة العنصر بذل قصارى جهده لإبقاء نفسه مرئيًا لأطول فترة ممكنة.

import org.kde.kirigami as Kirigami

Kirigami.Action {
 text: "Search"
 icon.name: "search"

 displayComponent: TextField { }

 displayHint: Kirigami.DisplayHints.KeepVisible
}

استخدام الإجراءات في المكونات الأخرى

كما ذُكر في الدليل التمهيدي للإجراءات، فإن إجراءات كيريغامي سياقية، مما يعني أنها تظهر في أماكن مختلفة اعتمادًا على مكان وضعها. بالإضافة إلى ذلك، لها تمثيلات مختلفة لسطح المكتب والجوال.

صفحة

تعرض Kirigami.Page الإجراءات على يمين الرأس العلوي في وضع سطح المكتب، وفي تذييل في وضع الجوال.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Actions Demo"
 width: 600
 height: 600

 globalDrawer: Kirigami.GlobalDrawer {}
 contextDrawer: Kirigami.ContextDrawer {}

 pageStack.initialPage: Kirigami.Page {
 title: "Demo"

 actions: [
 Kirigami.Action {
 icon.name: "go-home"
 onTriggered: showPassiveNotification("Main action triggered")
 },
 Kirigami.Action {
 icon.name: "go-previous"
 onTriggered: showPassiveNotification("Left action triggered")
 },
 Kirigami.Action {
 icon.name: "go-next"
 onTriggered: showPassiveNotification("Right action triggered")
 },
 Kirigami.Action {
 text: "Contextual Action 1"
 icon.name: "bookmarks"
 onTriggered: showPassiveNotification("Contextual action 1 clicked")
 },
 Kirigami.Action {
 text: "Contextual Action 2"
 icon.name: "folder"
 enabled: false
 }
 ]
 }
}

إجراءات الصفحة على سطح المكتب

إجراءات الصفحة على جهاز جوال

الدرج العام

Kirigami.GlobalDrawer هو شريط جانبي يشبه القائمة يوفر تنقلًا قائمًا على الإجراءات لتطبيقك. هنا تكون الإجراءات المتداخلة مفيدة لأنه من الممكن إنشاء تنقل متداخل:

import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Actions Demo"
 globalDrawer: Kirigami.GlobalDrawer {
 title: "Demo"
 titleIcon: "applications-graphics"
 actions: [
 Kirigami.Action {
 text: "View"
 icon.name: "view-list-icons"
 Kirigami.Action {
 text: "View Action 1"
 onTriggered: showPassiveNotification("View Action 1 clicked")
 }
 Kirigami.Action {
 text: "View Action 2"
 onTriggered: showPassiveNotification("View Action 2 clicked")
 }
 },
 Kirigami.Action {
 text: "Action 1"
 onTriggered: showPassiveNotification("Action 1 clicked")
 },
 Kirigami.Action {
 text: "Action 2"
 onTriggered: showPassiveNotification("Action 2 clicked")
 }
 ]
 }
 //...
}

إجراءات الدرج العام على سطح المكتب

يمكنك قراءة المزيد عن الأدراج العامة في صفحة التوثيق للأدراج.

الدرج السياقي

يتكون Kirigami.ContextDrawer من مجموعة إضافية من الإجراءات المخفية خلف قائمة من ثلاث نقاط في أعلى اليمين في وضع سطح المكتب أو في أسفل اليمين في وضع الجوال إذا لم تكن هناك مساحة. يُستخدم لعرض الإجراءات ذات الصلة بصفحة معينة فقط. يمكنك قراءة المزيد عنها في دليل أدراج كيريغامي.

حقول نص الإجراء

يُستخدم Kirigami.ActionTextField لإضافة بعض الإجراءات السياقية إلى حقل نص، على سبيل المثال لمسح النص، أو للبحث عن النص.

Kirigami.ActionTextField {
 id: searchField
 rightActions: [
 Kirigami.Action {
 icon.name: "edit-clear"
 visible: searchField.text !== ""
 onTriggered: {
 searchField.text = ""
 searchField.accepted()
 }
 }
 ]
}

في هذا المثال، ننشئ زر "مسح" لحقل بحث لا يظهر إلا عند إدخال نص.

ملاحظة

نادرًا ما ينبغي استخدام ActionTextField مباشرة. يرث كل من SearchField و PasswordField من ActionTextField ومن المرجح أن يغطيا حالة الاستخدام المرغوبة.

عنصر قائمة السحب

Kirigami.SwipeListItem هو مفوض مصمم لدعم الإجراءات الإضافية. عند استخدام فأرة، ستُعرض إجراءاته دائمًا. على جهاز لمس، يمكن عرضها بسحب العنصر بالمقبض. في الصور التالية، هذه هي الأيقونات على اليمين.

ListView {
 model: myModel
 delegate: SwipeListItem {
 Controls.Label {
 text: model.text
 }
 actions: [
 Action {
 icon.name: "document-decrypt"
 onTriggered: print("Action 1 clicked")
 },
 Action {
 icon.name: model.action2Icon
 onTriggered: //افعل شيئًا
 }
 ]
 }
}

عنصر قائمة السحب على حاسوب

عنصر قائمة السحب على جهاز جوال

شريط أدوات الإجراء

شريط أدوات Kirigami.ActionToolBar هو شريط أدوات مبني من قائمة إجراءات. افتراضيًا، سيمثل كل إجراء يتسع في شريط الأدوات بواسطة ToolButton، مع نقل تلك التي لا تتسع إلى قائمة في نهاية شريط الأدوات.

كما هو الحال مع ActionTextField، قد لا تحتاج إلى استخدام ActionToolBar مباشرة لأنه يُستخدم بواسطة رؤوس الصفحات والبطاقات لتوفير عرض إجراءاتها.

import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Actions Demo"
 width: 350
 height: 350
 header: Kirigami.ActionToolBar {
 actions: [
 Kirigami.Action {
 text: i18n("View Action 1")
 onTriggered: showPassiveNotification(i18n("View Action 1 clicked"))
 },
 Kirigami.Action {
 text: i18n("View Action 2")
 onTriggered: showPassiveNotification(i18n("View Action 2 clicked"))
 },
 Kirigami.Action {
 text: i18n("Action 1")
 onTriggered: showPassiveNotification(i18n("Action 1 clicked"))
 },
 Kirigami.Action {
 text: i18n("Action 2")
 onTriggered: showPassiveNotification(i18n("Action 2 clicked"))
 }
 ]
 }
}

شريط أدوات أفقي يُعرض في أعلى التطبيق

يمكنك قراءة المزيد عن مكونات ActionToolBar في صفحة توثيقها المخصصة.

البطاقات

تُستخدم Kirigami.Card لعرض مجموعة من المعلومات أو الإجراءات معًا. يمكن إضافة هذه الإجراءات إلى مجموعة actions، على غرار المكونات السابقة.

Kirigami.Card {
 actions: [
 Kirigami.Action {
 text: qsTr("Action1")
 icon.name: "add-placemark"
 },
 Kirigami.Action {
 text: qsTr("Action2")
 icon.name: "address-book-new-symbolic"
 },
 // ...
 ]
 banner {
 source: "../banner.jpg"
 title: "Title Alignment"
 titleAlignment: Qt.AlignLeft | Qt.AlignBottom
 }
 contentItem: Controls.Label {
 wrapMode: Text.WordWrap
 text: "My Text"
 }
}

لمزيد من المعلومات، راجع صفحة المكونات الخاصة بالبطاقات.

Docs: صفوف الصفحات وكومات الصفحات

Mon, 01 Jan 0001 00:00:00 +0000

صف من الصفحات

رأينا حتى الآن أن أحد المكونات الأساسية لنافذة كيريغامي هو Kirigami.Page. يمكن لصفحة واحدة أن تغطي شاشة التطبيق بأكملها، أو يمكن عرضها مع صفحات أخرى في نفس الوقت، إذا وُجدت مساحة.

كلما أُضيفت صفحة، أو دُفعت، تظهر إلى يمين الصفحات الموجودة، مشكّلة صفًا. يمكن إدارة هذا الصف من الصفحات باستخدام Kirigami.PageRow المسمى بملاءمة.

قد يبدو صف صفحات أدنى بصفحة واحدة هكذا:

import QtQuick
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Single Page"
 width: 500
 height: 200

 Kirigami.PageRow {
 anchors.fill: parent

 Kirigami.Page {
 id: mainPage
 anchors.fill: parent
 Rectangle {
 anchors.fill: parent
 color: "lightblue"
 }
 }
 }
}

صفحة واحدة بلون أزرق فاتح لإظهار أبعاد الصفحة

هناك تحسينان يمكن إجراؤهما هنا. الأول هو أنه باستخدام initialPage، يمكننا ضبط mainPage لتكون أول صفحة تظهر في صف الصفحات، وتُدار أبعادها بواسطة صف الصفحات بدلاً من المرتكزات اليدوية أو الموضّعات أو المخططات. الثاني هو الحصول على شريط أدوات، يمكن ضبطه بتعريف نمط شريط أدوات باستخدام globalToolBar.style. هناك بضعة أنماط يمكننا الاختيار من بينها، لكننا سنختار Kirigami.ApplicationHeaderStyle.Auto الآن.

import QtQuick
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "With globalToolBar and initialPage"
 width: 500
 height: 200
 Kirigami.PageRow {
 anchors.fill: parent
 globalToolBar.style: Kirigami.ApplicationHeaderStyle.Auto
 initialPage: Kirigami.Page {
 Rectangle {
 anchors.fill: parent
 color: "lightblue"
 }
 }
 }
}

صفحة واحدة مع شريط أدوات بلون أزرق فاتح لإظهار أبعاد الصفحة

هناك طريقتان فقط لإضافة صفحات إلى صف صفحات: بضبط initialPage (الذي يمكنه أخذ مصفوفة من الصفحات اختياريًا) أو باستخدام push(). لحذف صفحة من صف الصفحات، ينبغي استخدام pop()، بينما يمكن استخدام goBack() أو goForward() للتنقل بين الصفحات.

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Multiple pages in a row"
 width: 700
 height: 300
 Kirigami.PageRow {
 id: mainRow
 anchors.fill: parent
 globalToolBar.style: Kirigami.ApplicationHeaderStyle.Auto
 initialPage: Kirigami.Page {
 id: firstPage
 Rectangle {
 anchors.fill: parent
 color: "lightblue"
 Controls.Button {
 anchors.centerIn: parent
 text: "Push!"
 onClicked: mainRow.push(secondPage)
 }
 }
 }

 Component {
 id: secondPage
 Kirigami.Page {
 Rectangle {
 anchors.fill: parent
 color: "lightgreen"
 Controls.Button {
 anchors.centerIn: parent
 text: "Pop!"
 onClicked: mainRow.pop()
 }
 }
 }
 }
 }
}

صفحة أولية بلون أزرق فاتح

عند النقر على "Push!"، تظهر صفحة ثانية بلون أخضر فاتح.

كومة صفحات التطبيق

إذا بدا لك Kirigami.PageRow مع شريط أدوات مألوفًا، فذلك لأنك رأيته من قبل. ApplicationWindow.pageStack ليس سوى صف صفحات شامل ومريح جدًا. كل وظيفة متاحة لـ PageRow متاحة أيضًا لـ pageStack.

يمكن تقليص المثال السابق بشكل كبير باستخدام pageStack، مع الميزة الإضافية لإجراءات التنقل:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Using the pageStack"
 width: 500
 height: 200
 pageStack.initialPage: Kirigami.Page {
 id: firstPage
 Rectangle {
 anchors.fill: parent
 color: "lightblue"
 Controls.Button {
 anchors.centerIn: parent
 text: "Push!"
 onClicked: pageStack.push(secondPage)
 }
 }
 }
 Component {
 id: secondPage
 Kirigami.Page {
 Rectangle {
 anchors.fill: parent
 color: "lightgreen"
 Controls.Button {
 anchors.centerIn: parent
 text: "Pop!"
 onClicked: pageStack.pop()
 }
 }
 }
 }
}

عمومًا سترغب في استخدام pageStack بدلاً من تنفيذ PageRow الخاص بك، خاصة عندما يكبر تطبيقك وتحتاج مكوناتك إلى العيش في ملفات منفصلة. إذا أنشأت نافذتك في Main.qml باستخدام Kirigami.ApplicationWindow، فلا يزال بإمكان مكون موجود في ملف آخر استدعاء pageStack الشامل مباشرة عن طريق استدعاء applicationWindow():

// "Main.qml"
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Pushing a Page from a different QML file"
 width: 700
 height: 400
 pageStack.initialPage: BasicPage {}
}

// "BasicPage.qml"
import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.Page {
 Controls.Button {
 anchors.centerIn: parent
 text: "This pushes page1 from BasicPage\ninto the pageStack from Main.qml!"
 onClicked: {
 applicationWindow().pageStack.push(page1)
 }
 Component {
 id: page1
 Kirigami.Page {
 Controls.Label {
 anchors.centerIn: parent
 text: "page1 was pushed!"
 }
 }
 }
 }
}

النقر على الزر يدفع صفحة جديدة بمساعدة applicationWindow

Docs: الصفحات القابلة للتمرير وعروض القوائم

Mon, 01 Jan 0001 00:00:00 +0000

Kirigami.ScrollablePage

Kirigami.ScrollablePage هي صفحة تحتوي على محتوى قابل للتمرير، مثل ListView. يتم إدارة التمرير ومؤشرات التمرير آليًا.

Kirigami.ScrollablePage {
 id: root
 //سيكون المستطيل قابلًا للتمرير آليًا
 Rectangle {
 width: root.width
 height: 99999
 }
}

في كل الجوانب الأخرى تقريبًا، الصفحة القابلة للتمرير مماثلة للصفحة العادية.

تحذير

لا تضع ScrollView داخل Kirigami.ScrollablePage؛ أبناء Kirigami.ScrollablePage موجودون بالفعل داخل ScrollView.

ListView في ScrollablePage

عندما يمتد الأبناء المباشرون لـ Kirigami.ScrollablePage عموديًا إلى ما يتجاوز حجم الصفحة نفسها، يظهر شريط تمرير على الحافة اليمنى للصفحة وتصبح الصفحة قابلة للتمرير.

صفحتان قابلتان للتمرير، كلتاهما تحتويان على ListView بمحتويات مخصصة (لقطة شاشة من NeoChat)

غالبًا ما يكون لديك أكثر من ابن واحد في Kirigami.ScrollablePage، ويمكن أن يكون وضع العناصر صعبًا—خاصةً مع ListView.

بالنسبة للمكونات غير المرئية، وجودها داخل مكون ListView لن يغير مظهر الصفحة، لذا يمكننا نقلها داخل نطاق عرض القائمة. نفس الشيء ينطبق على العناصر المثبتة في مركز الصفحة، مثل رسائل العناصر النائبة لعروض القوائم الفارغة.
بالنسبة للعناصر الأخرى، قد يكون من المنطقي نقلها إلى الترويسة أو التذييل لـ Kirigami.ScrollablePage. هذا هو الحال غالبًا لأشرطة البحث.

PlaceholderMessage

من الممكن إضافة Kirigami.PlaceholderMessage مع بعض التعليمات في حال كان عرض القائمة فارغًا.

Kirigami.ScrollablePage {
 ListView {
 id: listView
 Kirigami.PlaceholderMessage {
 anchors.centerIn: parent
 width: parent.width - (Kirigami.Units.largeSpacing * 4)
 visible: listView.count === 0
 text: i18n("No data found")
 helpfulAction: Kirigami.Action {
 text: i18n("Load data")
 // المزيد من الشيفرة...
 }
 }
 model: // شيفرة النموذج...
 }
}

البحث في ListView

غالبًا ما يُضاف حقل بحث إلى Kirigami.ScrollablePage لتصفية ListView. يمكن فعل ذلك بتغيير titleDelegate المبدئي لاستخدام Kirigami.SearchField بدلاً من ذلك.

Kirigami.ScrollablePage {
 titleDelegate: Kirigami.SearchField {
 Layout.topMargin: Kirigami.Units.smallSpacing
 Layout.bottomMargin: Kirigami.Units.smallSpacing
 Layout.fillHeight: true
 Layout.fillWidth: true
 onTextChanged: mySortFilterModel.filterText = text
 KeyNavigation.tab: listView
 }

 ListView {
 id: listView
 // باقي شيفرة عرض القائمة...
 }
}

تلميح

يمكنك استخدام KSortFilterProxyModel من KItemModel لإضافة قدرة التصفية بسهولة مباشرة في QML دون أي حاجة لشيفرة C++.

اسحب للتحديث

وظيفة أخرى يوفرها هذا المكون هي إجراء "اسحب للتحديث". لاستخدام هذا، فعّله كالتالي:

Kirigami.ScrollablePage {
 id: view
 supportsRefreshing: true
 onRefreshingChanged: {
 if (refreshing) {
 myModel.refresh();
 }
 }
 ListView {
 // ملاحظة: MyModel لا يأتي من المكونات، إنه مجرد مثال على كيفية استخدامه مع بعض منطق التطبيق
 // الذي يمكنه تحديث نموذج القائمة والإشارة عند الانتهاء.
 model: MyModel {
 onRefreshDone: view.refreshing = false;
 }
 delegate: BasicListItem {}
 }
}

بالسحب لأسفل، يمكنك أيضًا تفعيل وضع خاص بهامش علوي أكبر مما يسهل استخدام التطبيق بيد واحدة.

Docs: البطاقات

Mon, 01 Jan 0001 00:00:00 +0000

تُستخدم أنواع Kirigami AbstractCard و Card لتنفيذ مكون البطاقة الشائع المستخدم على العديد من منصات الجوال والويب. يمكن استخدام البطاقات لعرض مجموعة من المعلومات أو الإجراءات بطريقة جذابة ومميزة.

يقدم Kirigami أيضًا 3 أنواع من العروض و الموضعات لمساعدتك في تقديم بطاقاتك بتخطيطات جميلة ومستجيبة.

AbstractCard

Kirigami.AbstractCard هو أبسط أنواع البطاقات. إنه مجرد مستطيل بظل، يمكن أن يحتوي على أي Item بداخله. يمكنه أيضًا أن تحتوي Items مخصصة لخصائص header أو footer. في هذه الحالة، Kirigami.Heading هو header الخاص به و Controls.Label هو contentItem للبطاقة.

Kirigami.AbstractCard {
 Layout.fillHeight: true
 header: Kirigami.Heading {
 text: qsTr("AbstractCard")
 level: 2
 }
 contentItem: Controls.Label {
 wrapMode: Text.WordWrap
 text: "..."
 }
}

بطاقة

ترث Kirigami.Card من AbstractCard وتوفر المزيد من الميزات مباشرة. ترث البطاقات نفس header و footer من Abstract Card، لكن يُشجع على استخدام banner ومجموعة من Kirigami.Action في مجموعة actions بدلاً من ذلك.

Kirigami.Card {
 actions: [
 Kirigami.Action {
 text: qsTr("Action1")
 icon.name: "add-placemark"
 },
 Kirigami.Action {
 text: qsTr("Action2")
 icon.name: "address-book-new-symbolic"
 },
 // ...
 ]
 banner {
 source: "../banner.jpg"
 title: "Title Alignment"
 // يمكن وضع العنوان في اللافتة
 titleAlignment: Qt.AlignLeft | Qt.AlignBottom
 }
 contentItem: Controls.Label {
 wrapMode: Text.WordWrap
 text: "My Text"
 }
}

CardsLayout

يكون Kirigami.CardsLayout أكثر فائدة عندما لا تكون البطاقات المعروضة منشأة بواسطة نموذج أو تكون منشأة بواسطة نموذج يحتوي دائمًا على عدد قليل جدًا من العناصر. تُعرض كشبكة من عمودين تبقى في المنتصف إذا كان التطبيق واسعًا جدًا، أو تصبح عمودًا واحدًا إذا لم تكن هناك مساحة كافية لعمودين، مثل شاشة الهاتف المحمول.

ملاحظة

CardsListView أنسب للنماذج الأكبر.

هام

يجب أن يكون CardsLayout دائمًا داخل ColumnLayout.

يمكن توجيه البطاقة أفقيًا اختياريًا. في هذه الحالة، ستكون أعرض من طولها، وتكون أنسب لوضعها في ColumnLayout. إذا كان لا بد من وضعها في CardsLayout، فسيكون لها maximumColumns بقيمة 2 مبدئيًا.

ColumnLayout {
 Kirigami.CardsLayout {
 Kirigami.Card {
 contentItem: Controls.Label {
 wrapMode: Text.WordWrap
 text: "My Text2"
 }
 }
 Kirigami.AbstractCard {
 contentItem: Controls.Label {
 wrapMode: Text.WordWrap
 text: "My Text"
 }
 }
 Kirigami.Card {
 headerOrientation: Qt.Horizontal
 contentItem: Controls.Label {
 wrapMode: Text.WordWrap
 text: "My Text2"
 }
 }
 }
}

CardsListView

Kirigami.CardsListView هو عرض قائمة يمكن استخدامه مع مكونات AbstractCard.

سيقوم CardsListView بتمديد البطاقات الفرعية إلى عرضه الخاص. لذلك يجب استخدام هذا المكون فقط مع البطاقات التي ستبدو جيدة بأي حجم أفقي. لا يُنصح باستخدام مكون Card داخله، إلا إذا كان لديه Qt.Horizontal كخاصية headerOrientation.

Kirigami.CardsListView {
 id: view
 model: 100

 delegate: Kirigami.AbstractCard {
 //ملاحظة: لا تضع Layout كـ contentItem أبدًا لأنه سيسبب حلقات ربط
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 //هام: لا تضع الهامش السفلي أبدًا
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: width > Kirigami.Units.gridUnit * 20 ? 4 : 2
 Kirigami.Icon {
 source: "applications-graphics"
 Layout.fillHeight: true
 Layout.maximumHeight: Kirigami.Units.iconSizes.huge
 Layout.preferredWidth: height
 }
 Kirigami.Heading {
 level: 2
 text: qsTr("Product ")+ modelData
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: qsTr("Install")
 }
 }
 }
 }
}

Docs: الأدراج

Mon, 01 Jan 0001 00:00:00 +0000

الأدراج هي لوحات تنزلق من جوانب نافذة التطبيق. يمكن ملؤها بعناصر تفاعلية مثل إجراءات كيريغامي، الأزرار، النصوص، والمزيد.

تأتي الأدراج بأنواع وأشكال وصيغ مختلفة. في هذه الصفحة سنستعرض كل نوع ونقدم نظرة عامة على خصائصه.

الدرج العام

الدرج العام هو ميزة قياسية في تطبيقات كيدي المحمولة ويمكن العثور عليه أحيانًا في إصداراتها المكتبية أيضًا. يحتوي على القائمة الرئيسية للتطبيق: تُدرج هنا أي وظائف ليست خاصة بالصفحة الحالية ولكنها لا تزال مهمة للتنقل العام أو التفاعل داخل التطبيق.

يمكن تفعيله بالنقر على قائمة الهامبرغر أو بالسحب من الحافة اليسرى إلى منتصف الشاشة في وضع اليسار إلى اليمين أو من الحافة اليمنى في وضع اليمين إلى اليسار.

مكونات Kirigami.GlobalDrawer هي ما نستخدمه لإنشاء مثل هذه الأدراج. تُضبط هذه المكونات لخاصية globalDrawer من Kirigami.ApplicationWindow التي تشكل أساس تطبيق كيريغامي الخاص بنا.

import QtQuick
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Drawers App"
 width: 600
 height: 600
 pageStack.initialPage: Kirigami.Page { /* Page code here... */ }

 globalDrawer: Kirigami.GlobalDrawer {
 title: "Global Drawer"
 titleIcon: "applications-graphics"
 actions: [
 Kirigami.Action {
 text: "Kirigami Action 1"
 icon.name: "user-home-symbolic"
 onTriggered: showPassiveNotification("Action 1 clicked")
 },
 Kirigami.Action {
 text: "Kirigami Action 2"
 icon.name: "settings-configure-symbolic"
 onTriggered: showPassiveNotification("Action 2 clicked")
 },
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }
}

ملاحظة

خاصية titleIcon تأخذ أسماء أيقونات على مستوى النظام وفقًا لمواصفات FreeDesktop. يمكن عرض هذه الأيقونات وأسمائها باستخدام تطبيق CuttleFish من كيدي الذي يأتي مع plasma-sdk، أو بزيارة مواصفات تسمية أيقونات FreeDesktop.

الرأس

يمكن استخدام الرؤوس لوضع مكونات لاصقة في أعلى الدرج العام. ستبقى مكونات الرأس في مكانها حتى إذا كان الدرج العام يحتوي على إجراءات كيريغامي متداخلة تحل محل الطبقة الحالية على الدرج العام.

يمكن ضبط مكون الرأس المختار باستخدام خاصية header للدرج العام، وسيحل محل عنوان الدرج العام. هذا مفيد لإضافة Kirigami.SearchField، على سبيل المثال:

import QtQuick
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Drawers App"
 width: 600
 height: 600
 pageStack.initialPage: Kirigami.Page { /* Page code here... */ }

 globalDrawer: Kirigami.GlobalDrawer {
 title: "Global Drawer with searchfield (not visible)"

 header: Kirigami.SearchField {
 id: searchField
 }

 actions: [
 Kirigami.Action {
 text: "Kirigami Action 1"
 icon.name: "user-home-symbolic"
 onTriggered: showPassiveNotification("Action 1 clicked")
 },
 Kirigami.Action {
 text: "Kirigami Action 2"
 icon.name: "settings-configure-symbolic"
 onTriggered: showPassiveNotification("Action 2 clicked")
 },
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }
}

الدرج العام لدينا يعرض الآن مكون شريط البحث الذي ضبطناه كرأس

التكيف مع سطح المكتب

بينما يمكن أن تكون الأدراج العامة على شكل لوحة مفيدة في البيئات المحمولة، فقد تكون كبيرة جدًا على سطح المكتب، خاصة عندما يحتوي التطبيق على إجراءات قليلة.

لحسن الحظ، توفر الأدراج العامة في كيريغامي خاصية isMenu. عند ضبطها على true، تتحول إلى قوائم أكثر تقليدية فقط على سطح المكتب.

ملاحظة

في وضع القائمة هذا، الرؤوس واللافتات غير مرئية.

globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true

 actions: [
 // إجراءات كيريغامي هنا...
 ]
}

درج عام في وضع القائمة، بدون رأس أو لافتة

الأدراج السياقية

بينما يعرض Kirigami.GlobalDrawer الإجراءات العامة المتاحة في جميع أنحاء التطبيق، يجب استخدام Kirigami.ContextDrawer لعرض الإجراءات ذات الصلة فقط في سياقات معينة. يُستخدم هذا عادةً في صفحات منفصلة.

سيتصرف الدرج السياقي بشكل مختلف اعتمادًا على ما إذا كان يُستخدم على منصة محمولة أو على سطح المكتب.

على سطح المكتب، عندما تتوفر مساحة كافية للنافذة، تظهر الإجراءات السياقية كجزء من مجموعة الإجراءات في شريط الأدوات العلوي. عندما تكون المساحة محدودة، كحال جهاز محمول أو نافذة ضيقة، تُخفى الإجراءات السياقية خلف قائمة هامبرغر على الجانب الأيمن. يختلف هذا عن الإجراءات الأخرى في مجموعة actions، وهي actions.main و actions.left و actions.right؛ فهذه لا تُخفى في النوافذ محدودة المساحة، بل تُطوى إلى أيقوناتها الخاصة.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Drawers App"
 height: 600
 width: 1200
 minimumWidth: 500

 globalDrawer: Kirigami.GlobalDrawer {}
 contextDrawer: Kirigami.ContextDrawer {}

 pageStack.initialPage: [ emptyPage, contextDrawerPage ]

 Kirigami.Page {
 title: "Empty page"
 id: emptyPage
 }

 Kirigami.Page {
 id: contextDrawerPage
 title: "Context Drawer page"

 actions: [
 Kirigami.Action {
 icon.name: "media-record"
 },
 Kirigami.Action {
 icon.name: "arrow-left"
 },
 Kirigami.Action {
 icon.name: "arrow-right"
 },
 Kirigami.Action {
 text: "Contextual Action 1"
 icon.name: "media-playback-start"
 },
 Kirigami.Action {
 text: "Contextual Action 2"
 icon.name: "media-playback-stop"
 }
 ]
 }
}

درج سياقي مع إجراءات سياقية مخفية

درج سياقي يعرض جميع الإجراءات السياقية

على الأجهزة المحمولة، يتألف الدرج دائمًا من إجراءات مخفية خلف قائمة هامبرغر. يمكن تفعيله بالنقر على قائمة هامبرغر أو بالسحب من الحافة اليمنى إلى منتصف الشاشة في وضع اليسار إلى اليمين أو من الحافة اليسرى في وضع اليمين إلى اليسار.

نفس المثال أعلاه، يُشغّل في وضع الجهاز المحمول

درج سياقي مفتوح في وضع الجهاز المحمول

الأدراج المشروطة والمضمنة

يقدم كيريغامي نوعين إضافيين من الأدراج، الأدراج المشروطة والأدراج المضمنة. هما متشابهان إلى حد كبير: كلاهما يمتد على كامل عرض التطبيق أو ارتفاعه ويمكن وضعهما على حواف نافذة التطبيق. ومع ذلك، يتفاعلان بشكل مختلف مع تفاعل المستخدم.

الأدراج المشروطة مخفية مبدئيًا وتُظلم باقي التطبيق، وتُرفض عند النقر على منطقة مظلمة.
الأدراج المضمنة معروضة مبدئيًا وتسمح للمستخدم بالتفاعل مع باقي التطبيق دون رفضها، ولا تُظلم المناطق الأخرى.

هذا النوع من الأدراج مفتوح النهاية ومرن، ولكن عمومًا، قد ترغب في استخدام هذا النوع من الأدراج عندما تريد ظهور قائمة صغيرة من الخيارات عند الضغط المطول أو النقر بالزر الأيمن.

هذان الدرجان متشابهان جدًا لأنهما يمكن، في الواقع، تنفيذهما باستخدام نفس مكون كيريغامي: Kirigami.OverlayDrawer. إليك بعض الخصائص الموروثة المهمة لهذا المكون التي يجب تذكرها:

تتحكم Popup.modal في ما إذا كان الدرج سيكون مشروطًا أم مضمنًا اعتمادًا على قيمة منطقية.
تتحكم Drawer.edge في أي حافة من نافذة التطبيق سيظهر الدرج؛ خيارات هذه الخاصية جزء من Edge enum، وهي Qt.TopEdge و Qt.RightEdge و Qt.BottomEdge و Qt.LeftEdge.
يحتوي Popup.contentItem على المكون الذي سيشكل محتوى درجك.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Drawers App"
 width: 400
 height: 600
 pageStack.initialPage: Kirigami.Page {
 title: "OverlayDrawer at the bottom"
 actions: [
 Kirigami.Action {
 text: "Open bottomDrawer"
 onTriggered: bottomDrawer.open()
 }
 ]
 Kirigami.OverlayDrawer {
 id: bottomDrawer
 edge: Qt.BottomEdge
 // اضبط modal إلى false لجعل هذا الدرج مضمنًا!
 modal: true

 contentItem: RowLayout {
 Controls.Label {
 Layout.fillWidth: true
 text: "Say hello to my little drawer!"
 }
 Controls.Button {
 text: "Close"
 onClicked: bottomDrawer.close()
 }
 }
 }
 }
}

الدرج المشروط غير مرئي

درج مشروط على الحافة السفلية للشاشة

Docs: الرقاقات

Mon, 01 Jan 0001 00:00:00 +0000

مكونات Kirigami.Chip هي عناصر صغيرة موروثة من AbstractButton تُستخدم لعرض الخصائص الشائعة أو عوامل تصفية لشيء ما. هذه عادةً عناصر نصية، وهي قابلة للتفاعل وتأتي مع زر حذف اختياري.

بداية سريعة

يمكن إضافة الرقاقات بسهولة باستخدام مكون Kirigami.Chip. بتعيين سلسلة نصية لحقل AbstractButton.text الموروث، نعطي الرقاقات أسماءها.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Chips"

 pageStack.initialPage: Kirigami.Page {
 title: "Chips"

 Kirigami.FormLayout {
 anchors.fill: parent
 Kirigami.Chip {
 text: "Chip 1"
 }
 Kirigami.Chip {
 text: "Chip 2"
 }
 Kirigami.Chip {
 text: "Chip 3"
 }
 }
 }
}

مع المكررات (موصى به)

نظرًا لأن الرقاقات مخصصة للاستخدام أكثر من مرة، فمن المحتمل أن ترغب في استخدام نوع من بنية بيانات القائمة والتكرار عليها لعرض الرقاقات. للقيام بذلك، نحتاج إلى ListModel ومكون Repeater.

يُستخدم ListModel كتخزين للرقاقات. لتعبئة ListModel (وبالتالي الرقاقات)، نعلن عن بضعة مكونات ListElement، والتي تحتوي على حقل يُعرف باسم text. يمكننا استخدام هذه السلسلة النصية المعينة من هنا لحقل text لكل رقاقة مكررة.

يُستخدم المكرر لعرض الرقاقات. أولاً، نحتاج إلى تعيين حقل model للمكرر إلى ListModel الخاص بنا، أو إنشاء ListModel داخل المكرر. ثم، نعلن عن مكون Kirigami.Chip داخل المكرر، ونعين حقل text الخاص به ببيانات العنصر باستخدام الخاصية modelData.

Kirigami.ApplicationWindow {
 id: root
 title: "Chips"

 ListModel {
 id: chips

 ListElement { text: "Chip 1" }
 ListElement { text: "Chip 2" }
 ListElement { text: "Chip 3" }
 }

 pageStack.initialPage: Kirigami.Page {
 title: "Chips"

 Kirigami.FormLayout {
 anchors.fill: parent
 Repeater {
 Layout.fillWidth: true
 model: chips

 Kirigami.Chip {
 id: chip
 text: modelData
 }
 }
 }
 }
}

ملاحظة

يمكنك إلحاق البيانات وإزالتها ديناميكيًا من ListModel، وسيقوم المكرر تلقائيًا بإجراء تلك التغييرات. ومع ذلك، فإن مجرد تغيير عنصر معين من المكرر أو ListModel لا يؤثر على الآخر، ويتطلب تغيير كليهما، ما لم يُستخدم شيء مثل QAbstractListModel. راجع تطبيق مثال لمزيد من المعلومات.

تطبيق مثال

يوضح تطبيق المثال أدناه كيف يمكن استخدام الرقاقات في برامج مثل قوائم المهام.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 id: root
 title: "Chips"

 ListModel {
 id: chips

 ListElement { text: "Chip 1" }
 ListElement { text: "Chip 2" }
 ListElement { text: "Chip 3" }
 }

 pageStack.initialPage: Kirigami.Page {
 title: "Chips"

 Kirigami.OverlaySheet {
 id: editChipPrompt

 property var chip;
 property var index;

 header: Kirigami.Heading {
 text: "Edit Chip"
 }

 footer: DialogButtonBox {
 standardButtons: DialogButtonBox.Ok | DialogButtonBox.Cancel
 onAccepted: {
 // Both the data from the Repeater and ListModel must be
 // edited in order to update both.
 editChipPrompt.chip.text = editTextField.text;
 chips.setProperty(editChipPrompt.index, "text", editTextField.text);
 editChipPrompt.close();
 }
 onRejected: {
 editChipPrompt.close();
 }
 }

 TextField {
 id: editTextField
 }
 }

 Kirigami.FormLayout {
 anchors.fill: parent
 TextField {
 id: insertTextField
 Kirigami.FormData.label: "Item:"
 onAccepted: chips.append({ text: insertTextField.text })
 }
 // Wrapped in ColumnLayout to prevent binding loops.
 ColumnLayout {
 Layout.alignment: Qt.AlignHCenter
 Repeater {
 model: chips

 Kirigami.Chip {
 id: chip
 text: modelData
 onClicked: {
 editTextField.text = modelData;
 editChipPrompt.chip = chip;
 editChipPrompt.index = index;
 editChipPrompt.open();
 }
 onRemoved: chips.remove(index)
 }
 }
 }
 }
 }
}

Docs: أنواع الحوارات

Mon, 01 Jan 0001 00:00:00 +0000

Kirigami.Dialog هو مكون بسيط يمكنك استخدامه لتكملة المحتوى المعروض على صفحة التطبيق. يمكنه عرض محتوى غير تفاعلي (نص فقط) ومحتوى تفاعلي (نماذج، قوائم عرض وأزرار).

يمكن إغلاقها بالنقر أو الضغط خارج مساحتها أو بالنقر على زر الإغلاق في الرأس.

بيئات معزولة

يعمل هذا فورًا لجميع حوارات كيريجامي في البيئات المعزولة (مثل فلاتباك) عبر بوابات سطح المكتب XDG. عند التشغيل في بيئة معزولة، يُستخدم النهاية الخلفية للبوابة المناسبة آليًا، مما يسمح بالوصول المصرح به من المستخدم دون الحاجة إلى معالجة يدوية لـ D-Bus.

حوار

يُستخدم Kirigami.Dialog القياسي لإنشاء حوارات مخصصة. من السهل جدًا توسيعها:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Dialog"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 id: page
 actions: Kirigami.Action {
 icon.name: "list-add"
 text: "Show dialog"
 onTriggered: dialog.open()
 }

 Kirigami.Dialog {
 id: dialog
 title: "A simple dialog"
 padding: Kirigami.Units.largeSpacing
 showCloseButton: false
 standardButtons: Kirigami.Dialog.NoButton
 flatFooterButtons: false
 Controls.Label {
 text: "A generic, easy to make dialog!"
 }
 customFooterActions: Kirigami.Action {
 text: "Copy"
 icon.name: "clipboard"
 }
 }
 }
}

كما هو موضح في الدليل التمهيدي حول الحوارات، من الممكن أيضًا التقاط standardButton(button) لتعيين سلوك له، مثل ربط لتمكينه فقط تحت شروط معينة.

هذا النوع من الحوارات عام وينطبق على معظم حالات الاستخدام، ويعمل جيدًا مع المحتوى التفاعلي المعقد (خاصة العروض):

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Scrollable Dialog"
 width: 600
 height: 600
 pageStack.initialPage: Kirigami.Page {
 id: page
 actions: Kirigami.Action {
 icon.name: "list-add"
 text: scrollableDialog.title
 onTriggered: scrollableDialog.open()
 }

 Kirigami.Dialog {
 id: scrollableDialog
 title: i18n("Select Number")

 ListView {
 id: listView
 // تلميحات لأبعاد الحوار
 implicitWidth: Kirigami.Units.gridUnit * 16
 implicitHeight: Kirigami.Units.gridUnit * 16

 model: 20
 delegate: Controls.RadioDelegate {
 topPadding: Kirigami.Units.smallSpacing * 2
 bottomPadding: Kirigami.Units.smallSpacing * 2
 implicitWidth: listView.width
 text: modelData
 }
 }
 }

 }
}

في معظم الحالات، مع ذلك، سترغب غالبًا في استخدام أحد أنواع الحوارات المشتقة منه، Kirigami.PromptDialog أو Kirigami.MenuDialog.

حوار المطالبة

Kirigami.PromptDialog هو حوار مزود بوسم مدمج وحشوة مبدئية للمحتوى contentPadding يُستخدم لاستدعاء المستخدم لإدخال بعض المعلومات. يُفترض استخدام هذا النوع من الحوارات فقط للطلبات البسيطة بنعم/لا أو الطلبات المختصرة لإدخال المستخدم.

خاصيته الرئيسية هي Kirigami.Dialog.subtitle، التي تُضاف إليها النصوص. إذا أُضيف أي مكون QML كطفل لحوار الطلب، فسيحل ذلك المكون محل العنوان الفرعي بدلاً من ذلك.

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "PromptDialog"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 id: page
 actions: Kirigami.Action {
 icon.name: "list-add"
 text: promptDialog.title
 onTriggered: promptDialog.open()
 }

 Kirigami.PromptDialog {
 id: promptDialog
 title: i18n("Delete file")
 subtitle: i18n("Are you sure you'd like to delete this file?")

 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 onAccepted: console.info("File deleted")
 }
 }
}

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "PromptDialog with a textfield"
 width: 600
 height: 600
 pageStack.initialPage: Kirigami.Page {
 id: page
 actions: Kirigami.Action {
 icon.name: "list-add"
 text: textPromptDialog.title
 onTriggered: textPromptDialog.open()
 }

 Kirigami.PromptDialog {
 id: textPromptDialog
 title: "New Folder"

 standardButtons: Kirigami.Dialog.NoButton
 customFooterActions: [
 Kirigami.Action {
 text: "Create Folder"
 icon.name: "dialog-ok"
 onTriggered: {
 showPassiveNotification("Created");
 textPromptDialog.close();
 }
 },
 Kirigami.Action {
 text: "Cancel"
 icon.name: "dialog-cancel"
 onTriggered: {
 textPromptDialog.close();
 }
 }
 ]
 ColumnLayout {
 Controls.TextField {
 Layout.fillWidth: true
 placeholderText: "Folder name…"
 }
 }
 }
 }
}

حوار القائمة

Kirigami.MenuDialog هو حوار متخصص يُستخدم لعرض مجموعة من الخيارات القابلة للنقر للمستخدم باستخدام خاصية actions.

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "MenuDialog"
 width: 400
 height: 600
 pageStack.initialPage: Kirigami.Page {
 id: page
 actions: Kirigami.Action {
 icon.name: "list-add"
 text: menuDialog.title
 onTriggered: menuDialog.open()
 }

 Kirigami.MenuDialog {
 id: menuDialog
 title: i18n("Track options")
 showCloseButton: false

 actions: [
 Kirigami.Action {
 icon.name: "media-playback-start"
 text: i18n("Play")
 tooltip: i18n("Start playback of the selected track")
 },
 Kirigami.Action {
 enabled: false
 icon.name: "document-open-folder"
 text: i18n("Show in folder")
 tooltip: i18n("Show the file for this song in the file manager")
 },
 Kirigami.Action {
 icon.name: "documentinfo"
 text: i18n("View details")
 tooltip: i18n("Show track metadata")
 },
 Kirigami.Action {
 icon.name: "list-add"
 text: i18n("Play next")
 tooltip: i18n("Add the track to the queue, right after the current track")
 },
 Kirigami.Action {
 icon.name: "list-add"
 text: i18n("Add to queue")
 tooltip: i18n("Enqueue current track")
 }
 ]
 }
 }
}

Docs: عناصر التحكم والعناصر التفاعلية

Mon, 01 Jan 0001 00:00:00 +0000

يستفيد كيريغامي من مجموعة واسعة من العناصر التفاعلية المختلفة من كيوتي التي يمكنك استخدامها في تطبيقاتك. لكل نوع مختلف أنماط تفاعل وأساليب بصرية ووظائف مختلفة قليلاً. استخدام النوع الصحيح من عناصر التحكم في تطبيقك يمكن أن يساعد في جعل واجهة المستخدم أكثر استجابة وبديهية.

الأزرار

في تطبيقات كيريغامي، نستخدم [زر] عناصر تحكم كيوتيك السريعة (https://doc.qt.io/qt-6/qml-qtquick-controls-button.html). استخدامها بسيط جداً: نضبط خاصية النص وأي إجراء نريده أن ينفذ يُضبط لخاصية عند_النقر.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.Button"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 ColumnLayout {
 anchors.fill: parent
 Controls.Button {
 Layout.alignment: Qt.AlignCenter
 text: "Beep!"
 onClicked: showPassiveNotification("Boop!")
 }
 }
 }
}

الأزرار القابلة للتبديل

يمكن تغيير سلوك الأزرار لجعلها قابلة للتبديل: في هذا الوضع، ستبقى مضغوطة حتى يُنقر عليها مرة أخرى. يمكن تفعيل هذا الوضع بضبط خاصية قابل_للتحقق إلى true؛ يمكننا أيضاً ضبط الأزرار لتكون مفعلة مبدئياً بضبط مُحدد إلى true.

يمكننا الاستفادة القصوى من الأزرار القابلة للتبديل باستخدام معالج الإشارة عند_تغير_المحدد والذي يُولد آلياً من إشارة مُحدد. يعمل بشكل مشابه لـ عند_النقر، باستثناء أن الإجراء المعين هنا يُنفذ عندما تتغير حالة الزر. إنها خاصية منطقية، قد تكون مفيدة لحالات استخدام محددة.

في هذا المثال، نضبط رؤية درج مضمّن وفقاً لحالة زر قابل للتبديل:

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.Button (toggleable version)"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 ColumnLayout {
 anchors.fill: parent
 Controls.Button {
 Layout.alignment: Qt.AlignCenter
 text: "Hide inline drawer"
 checkable: true
 checked: true
 onCheckedChanged: myDrawer.visible = checked
 }

 Kirigami.OverlayDrawer {
 id: myDrawer
 edge: Qt.BottomEdge
 modal: false

 contentItem: Controls.Label {
 text: "Peekaboo!"
 }
 }
 }
 }
}

ملاحظة

مع سمة بريز المبدئية في بلازما كيدي قد يكون من الصعب معرفة ما إذا كان الزر مُبدلاً، لأن الأزرار تُلون باللون الأزرق عند النقر عليها. تأكد من أخذ هذا في الاعتبار عند إنشاء تطبيقك: قد يكون عنصر تحكم مختلف أكثر ملاءمة للمستخدم.

أزرار شريط الأدوات

هناك نوع زر محدد مخصص للاستخدام في أشرطة الأدوات، عناصر_تحكم.زر_أداة. الفرق الأكثر وضوحاً بين هذا والزر التقليدي هو التصميم، حيث تكون أزرار الأدوات مسطحة (على الرغم من أن هذا قابل للتغيير باستخدام الخاصية المنطقية مسطح).

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.ToolButton"
 width: 600
 height: 600

 header: Controls.ToolBar {
 RowLayout {
 anchors.fill: parent
 Controls.ToolButton {
 icon.name: "application-menu-symbolic"
 onClicked: showPassiveNotification("Kirigami Pages and Actions are better!")
 }
 Controls.Label {
 text: "Global ToolBar"
 horizontalAlignment: Qt.AlignHCenter
 verticalAlignment: Qt.AlignVCenter
 Layout.fillWidth: true
 }
 Controls.ToolButton {
 text: "Beep!"
 onClicked: showPassiveNotification("ToolButton boop!")
 }
 }
 }
}

عناصر تحكم التحديد

تتيح عناصر تحكم التحديد للمستخدمين اتخاذ خيار أو اختيار خيار. هناك أنواع مختلفة مناسبة بشكل أفضل لمواقف مختلفة.

مربعات الاختيار

عناصر_تحكم.مربع_اختيار مخصص للخيارات حيث تكون الاختيارات غير حصرية وحيث يكون لكل خيار بديل واضح.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.CheckBox"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 ColumnLayout {
 anchors.left: parent.left
 anchors.right: parent.right
 Controls.CheckBox {
 Layout.alignment: Qt.AlignHCenter
 text: "This checkbox is checked!"
 checked: true
 }
 Controls.CheckBox {
 Layout.alignment: Qt.AlignHCenter
 text: "This checkbox is not checked!"
 checked: false
 }
 }
 }
}

كما ترى، فهي بسيطة الاستخدام. خاصية مُحدد تحمل قيمة منطقية تحدد ما إذا تم تحديدها أم لا.

أزرار الراديو

عناصر_تحكم.زر_راديو مصمم للمواقف حيث يجب على المستخدم اختيار خيار واحد من مجموعة من عدة خيارات.

أزرار الراديو حصرية مبدئياً: يمكن تحديد زر واحد فقط في نفس العنصر الأب.

مثل مربعات الاختيار، يمكن ضبطها لتكون محددة أو غير محددة مبدئياً باستخدام خاصية مُحدد.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.RadioButton"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {

 ColumnLayout {
 anchors.left: parent.left
 anchors.right: parent.right
 Controls.RadioButton {
 Layout.alignment: Qt.AlignCenter
 text: "Tick!"
 checked: true
 }
 Controls.RadioButton {
 Layout.alignment: Qt.AlignCenter
 text: "Tock!"
 checked: false
 }
 }
 }
}

المفاتيح

على سطح المكتب، عادةً ما يتضمن تغيير الإعدادات تغيير الإعداد ثم تطبيقه بالنقر على زر "تطبيق" أو "موافق". على الجوال، يمكننا استخدام عناصر_تحكم.مفتاح بدلاً من ذلك.

يمكن تبديل المفاتيح بين حالة تشغيل وإيقاف. يمكن تبديلها بالنقر أو الضغط عليها، أو يمكن سحبها نحو وضع التشغيل أو الإيقاف. مرة أخرى، يمكن ضبط المفاتيح لتكون في وضع التشغيل أو الإيقاف مبدئياً باستخدام خاصية مُحدد.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.Switch"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 ColumnLayout {
 anchors.fill: parent
 Controls.Switch {
 Layout.alignment: Qt.AlignCenter
 text: "Switchy"
 checked: true
 }
 Controls.Switch {
 Layout.alignment: Qt.AlignCenter
 text: "Swootchy"
 checked: false
 }
 }
 }
}

أشرطة التمرير

تسمح أشرطة التمرير للمستخدمين بتحديد قيم معينة بتحريك مقبض على طول مسار. هناك عدة أنواع يمكنك الاختيار من بينها حسب القيم التي ترغب في أن يختارها المستخدمون في تطبيقك.

أشرطة التمرير القياسية والمُعلّمة

يوفر Controls.Slider القياسي للمستخدم تحكمًا دقيقًا جدًا في التحديد الذي يرغب في إجرائه.

في وضع اليسار إلى اليمين، تتحرك أشرطة التمرير من اليسار إلى اليمين للزيادة عند الاتجاه الأفقي، بينما في وضع اليمين إلى اليسار تتحرك في الاتجاه المعاكس. في كلا الوضعين، تتحرك أشرطة التمرير في الاتجاه العمودي من الأسفل إلى الأعلى.

يوفر التلوين مؤشرًا بصريًا لحجم القيمة التي تختارها.

لأشرطة التمرير بعض الخصائص المهمة التي يجب الانتباه إليها:

value: تحتوي على القيمة التي يوضع عندها المقبض، ويمكن ضبطها يدويًا لتوفير قيمة بدء مبدئية
to: تحدد نطاق شريط التمرير بتحديد القيمة القصوى التي يمكن أن يصل إليها
orientation: تسمح بضبط شريط التمرير على اتجاه عمودي باستخدام Qt.Vertical

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.Slider"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 ColumnLayout {
 anchors.fill: parent
 Controls.Slider {
 id: normalSlider
 Layout.alignment: Qt.AlignHCenter
 Layout.fillHeight: true
 orientation: Qt.Vertical
 value: 60
 to: 100
 }
 Controls.Label {
 Layout.alignment: Qt.AlignHCenter
 text: Math.round(normalSlider.value)
 }
 }
 }
}

خاصية مفيدة أخرى يمكن استخدامها هي stepSize. ضبطها على قيمة رقمية يسمح بإنشاء شريط تمرير يلتقط القيم التي هي مضاعفات stepSize المحددة، مع الإشارة إلى هذه المضاعفات بعلامات. لذلك إذا ضبطنا هذه الخاصية على 2.0، فعند سحب المستخدم لمقبض شريط التمرير، سيتمكن فقط من تحديد 0.0، 2.0، 4.0، إلخ حتى القيمة المحددة في الخاصية to.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.Slider (with steps)"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 ColumnLayout {
 anchors.fill: parent
 Controls.Slider {
 id: tickmarkedSlider
 Layout.alignment: Qt.AlignHCenter
 Layout.fillWidth: true
 orientation: Qt.Horizontal
 snapMode: Controls.Slider.SnapAlways
 value: 6.0
 to: 10.0
 stepSize: 2.0
 }
 Controls.Label {
 Layout.alignment: Qt.AlignHCenter
 text: tickmarkedSlider.value
 }
 }
 }
}

أشرطة تمرير النطاق

توفر عناصر تحكم QtQuick أيضًا Controls.RangeSliders. هذه تحتوي على مقبضين، مما يسمح لك بتحديد نطاق من الأرقام بين المقبضين.

خاصيتان جديدتان مهمتان يجب تذكرهما: first.value و second.value، اللتان تحملان قيمتي المقبضين. مثل خاصية value لأشرطة التمرير القياسية، يمكن ضبطهما مسبقًا.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.RangeSlider"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 ColumnLayout {
 anchors.fill: parent
 Controls.RangeSlider {
 id: rangeSlider
 Layout.alignment: Qt.AlignHCenter
 to: 10.0
 first.value: 2.0
 second.value: 8.0
 stepSize: 1.0
 snapMode: Controls.Slider.SnapAlways
 }
 RowLayout {
 Layout.alignment: Qt.AlignHCenter
 Layout.fillWidth: true
 Controls.Label {
 Layout.fillWidth: true
 text: "The slider's first value is: " + Math.round(rangeSlider.first.value)
 }
 Controls.Label {
 Layout.fillWidth: true
 text: "The slider's second value is: " + Math.round(rangeSlider.second.value)
 }
 }
 Controls.Label {
 Layout.alignment: Qt.AlignHCenter
 font.bold: true
 text: "Is the selected range between 2 and 8?"
 }
 Controls.Button {
 Layout.alignment: Qt.AlignHCenter
 icon.name: {
 if (rangeSlider.first.value >= 2 && rangeSlider.second.value <= 8)
 return "emblem-checked"
 else
 return "emblem-error"
 }
 }
 }
 }
}

Docs: تخطيطات النماذج

Mon, 01 Jan 0001 00:00:00 +0000

تسهل مكونات Kirigami.FormLayout عليك إنشاء نماذج تتوافق مع إرشادات واجهة المستخدم البشرية لكيدي. وهي مثالية لحوارات الإعدادات ولمجموعات كبيرة من عناصر التحكم وحقول الإدخال المرتبطة ببعضها البعض.

عند توفير مساحة كافية، ستشغل تخطيطات النموذج عمودين. سيشغل العمود الأيسر باللصائق المقدمة للمكونات الفرعية للنموذج، بينما سيشغل الأيمن بالمكونات الفرعية نفسها. في النوافذ محدودة المساحة (أو على الأجهزة المحمولة)، ستتكون النماذج من عمود رأسي واحد مع وضع لصائق المكونات الفرعية فوق المكون الخاص بها.

نموذج بسيط

مكونات Kirigami.FormLayout مشابهة في الاستخدام لمكونات QtQuick Layout مثل ColumnLayout أو RowLayout. ستُرتّب المكونات الفرعية آليًا وفقًا للحجم المتاح لتخطيط النموذج.

للمكونات الفرعية لـ Kirigami.FormLayout خاصية باسم Kirigami.FormData.label. تتيح لك هذه الخاصية تعيين اللصيقة التي ستُقدم للمكون الفرعي المعني.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 pageStack.initialPage: Kirigami.Page {

 Kirigami.FormLayout {
 anchors.fill: parent

 Controls.TextField {
 Kirigami.FormData.label: "TextField 1:"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 2:"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 3:"
 }
 }
 }
}

تخطيط نموذج بسيط في وضع سطح المكتب

الأقسام والفواصل

يمكن أيضًا تقسيم تخطيطات النموذج إلى أقسام. تعيين مكان بدء القسم سهل كتعيين خاصية Kirigami.FormData.isSection لمكون فرعي إلى true. سيوفر هذا للمكون هامشًا إضافيًا في الأعلى لتحديد بداية القسم الجديد.

مكونات Kirigami.Separator هي الأنسب لبدء أقسام جديدة. تُستخدم الفواصل لرسم خط أفقي رفيع، لتحديد نهاية القسم. إذا كنت تفضل عدم رسم خط بين الأقسام، يمكنك استخدام خاصية QML قياسية Item. بدلاً من ذلك، يمكنك استخدام خاصية Kirigami.FormData.isSection على أي مكون آخر.

ومع ذلك، هذا غير موصى به. على المكونات حيث Kirigami.FormData.isSection مضبوط على true، سيُعرض نص اللصيقة المقدم لخاصية Kirigami.FormData.label لهذا المكون كنص رأس القسم.

تحذير

لا ينطبق هذا على كل مكون، لذا يُوصى باستخدام مكونات Kirigami.Separator أو Item في الأماكن التي ترغب فيها باستخدام نص رأس.

نص الرأس هذا أكبر من نص اللصيقة العادي، ويمنح المستخدمين إشارة بصرية جميلة عن مضمون قسم تخطيط النموذج.

Kirigami.FormLayout {
 anchors.fill: parent

 Controls.TextField {
 Kirigami.FormData.label: "TextField 1:"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 2:"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 3:"
 }
 Kirigami.Separator {
 Kirigami.FormData.isSection: true
 Kirigami.FormData.label: "New Section!"
 }
 ColumnLayout {
 Kirigami.FormData.label: "Radio buttons"
 Controls.RadioButton {
 text: "Radio 1"
 checked: true
 }
 Controls.RadioButton {
 text: "Radio 2"
 }
 Controls.RadioButton {
 text: "Radio 3"
 }
 }
 Item {
 Kirigami.FormData.isSection: true
 Kirigami.FormData.label: "Another Section! (lineless though)"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 4:"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 5:"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 5:"
 }
}

تخطيط نموذج بأقسام

فرض تخطيط سطح مكتب أو هاتف محمول

إذا كنت تفضل أن يبقى تخطيط النموذج ثابتًا بغض النظر عن بيئة تطبيقك، فيمكنك استخدام خاصية wideMode لمكون Kirigami.FormLayout:

عند ضبطه على true، يُنظّم تخطيط النموذج في تخطيط شاشة عريضة محسّن لسطح المكتب (عمود مزدوج)
عند ضبطه على false، يُنظّم تخطيط النموذج في تخطيط هاتف محمول (عمود مفرد)

Kirigami.FormLayout {
 anchors.fill: parent
 wideMode: false

 Controls.TextField {
 Kirigami.FormData.label: "TextField 1:"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 2:"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 3:"
 }
}

تخطيط نموذج بتخطيط هاتف محمول مفروض

محاذاة لصائقك

توجد حالات تريد فيها تعيين لصيقة لمكونات تحتوي على أكثر من سطر أو لقائمة مكونات. يمكن تحقيق ذلك بوضع Kirigami.FormData.label في ColumnLayout، كما قد لاحظت في الأقسام والفواصل. مبدئيًا، تُوضع اللصيقة في المركز العمودي للتخطيط، وهو أمر غير مرغوب دائمًا. يمكننا تغيير ذلك بمساعدة Kirigami.FormData.labelAlignment.

Kirigami.FormLayout {
 anchors.fill: parent

 ColumnLayout {
 Kirigami.FormData.label: "This is a label:"
 Kirigami.FormData.labelAlignment: Qt.AlignTop

 Controls.Label {
 text: "This is some rather long text \nthat should elide to multiple lines \nto show how the label gets aligned."
 elide: Text.elideLeft
 }
 }
}

تخطيط نموذج بلصيقة محاذاة للأعلى

ضبط محاذاة اللصيقة مناسب بشكل خاص لإدارة المكونات أو قوائم المكونات التي لا تعرف حجمها مسبقًا. Elisa مثال جيد جدًا على ذلك:

لصيقة التعليق تُحاذى للأعلى فقط عندما يحتوي مكونها المقابل على أكثر من سطر

يمكننا فعل شيء مشابه لهذا باستخدام عامل ثلاثي في JavaScript:

Kirigami.FormLayout {
 anchors.fill: parent

 ColumnLayout {
 Kirigami.FormData.label: "This is a label:"
 Kirigami.FormData.labelAlignment: labelText.text.lineCount > 1 ? Qt.AlignTop : Qt.AlignVCenter

 Controls.Label {
 id: labelText
 text: "This is some rather long text \nthat should elide to a new line \nso it appears below the Form Label."
 elide: Text.elideLeft
 }
 }
}

Docs: الرسائل المضمنة

Mon, 01 Jan 0001 00:00:00 +0000

توفر الرسائل المضمنة طريقة فورية لإشعار مستخدميك بشيء حدث أثناء استخدام التطبيق.

رسالة مضمنة أساسية

مكونات Kirigami.InlineMessage لها خاصيتان مهمتان يجب مراعاتهما:

visible: مبدئيًا، يُضبط هذا على false، بحيث تظهر الرسالة فقط عندما تريدها صراحة. يمكن تجاوز هذا إذا رغبت بضبطه على true. عندما تُضبط رسالة مضمنة مخفية لتكون مرئية، تحصل على حركة لطيفة.
text: هنا تضبط نص رسالتك المضمنة.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.Page {

 ColumnLayout {
 Kirigami.InlineMessage {
 id: inlineMessage
 Layout.fillWidth: true
 text: "Hello! I am a siiiiiiimple lil' inline message!"
 }

 Controls.Button {
 text: "Show inline message!"
 onClicked: inlineMessage.visible = !inlineMessage.visible
 }
 }
}

أنواع مختلفة

الرسائل المضمنة القياسية تشبه تلك أعلاه: لها خلفية زرقاء وأيقونة مبدئية. يمكننا تغيير ذلك بخاصية type، التي تتيح لنا ضبط رسالتنا المضمنة إلى نوع مختلف. هناك أربعة أنواع يمكننا الاختيار منها:

معلومات (Kirigami.MessageType.Information): المبدئي. له خلفية زرقاء، وأيقونة 'i'، ويُستخدم للإعلان عن نتيجة أو إخبار المستخدم بشيء عام. ليس من الضروري ضبطه يدويًا.
إيجابي (Kirigami.MessageType.Positive): له خلفية خضراء، وأيقونة علامة صح، ويشير إلى أن شيئًا ما سار بشكل جيد.
تحذير (Kirigami.MessageType.Warning): له خلفية برتقالية، وأيقونة علامة تعجب، ويمكن استخدامه لتحذير المستخدم من شيء يجب أن ينتبه إليه.
خطأ (Kirigami.MessageType.Error): له خلفية حمراء، وأيقونة علامة X، ويمكن استخدامه لإخبار المستخدم بأن شيئًا ما قد حدث بشكل خاطئ.

ColumnLayout {

 Kirigami.InlineMessage {
 Layout.fillWidth: true
 text: "Hello! Let me tell you something interesting!"
 visible: true
 }

 Kirigami.InlineMessage {
 Layout.fillWidth: true
 text: "Hey! Let me tell you something positive!"
 type: Kirigami.MessageType.Positive
 visible: true
 }

 Kirigami.InlineMessage {
 Layout.fillWidth: true
 text: "Hmm... You should keep this in mind!"
 type: Kirigami.MessageType.Warning
 visible: true
 }

 Kirigami.InlineMessage {
 Layout.fillWidth: true
 text: "Argh!!! Something went wrong!!"
 type: Kirigami.MessageType.Error
 visible: true
 }

}

تخصيص النص والأيقونات

تدعم الرسائل المضمنة النص المنسق، والذي يمكن تعريفه بترميز بسيط يشبه HTML. يتيح لك ذلك إضافة بعض التنسيق إلى نص رسالتك المضمنة أو حتى تضمين رابط ويب خارجي إذا أردت.

Kirigami.InlineMessage {
 Layout.fillWidth: true
 // لاحظ أنه عند استخدام علامات الاقتباس في سلسلة نصية، سيتعين عليك إفلاتها!
 text: "Check out <a href=\"https://kde.org\">KDE's website!<a/>"
 onLinkActivated: Qt.openUrlExternally(link)
 visible: true
}

يمكنك أيضًا تخصيص الأيقونة التي تظهر في أعلى يسار رسالتك بتوفير اسم أيقونة نظام للخاصية icon.source. يجب أن تتوافق أسماء الأيقونات هذه مع الأيقونات المثبتة على نظامك؛ يمكنك استخدام تطبيق مثل Cuttlefish المقدم من plasma-sdk لتصفح والبحث عن الأيقونات المتوفرة على نظامك، ومعرفة أسمائها.

Kirigami.InlineMessage {
 Layout.fillWidth: true
 text: "Look at me! I look SPECIAL!"
 icon.source: "actor"
 visible: true
}

استخدام الإجراءات في الرسائل المضمنة

إذا كانت رسائلك بحاجة إلى التفاعل، يمكنك إرفاق إجراءات كيريجامي برسائلك المضمنة. كما هو الحال مع الصفحات، يمكنك فعل ذلك بضبط الخاصية InlineMessage.actions إما على Kirigami.Action أو مصفوفة تحتوي على مكونات Kirigami.Action.

ColumnLayout {

 Kirigami.InlineMessage {
 id: actionsMessage
 Layout.fillWidth: true
 visible: true

 readonly property string initialText: "Something is hiding around here..."
 text: initialText

 actions: [
 Kirigami.Action {
 enabled: actionsMessage.text == actionsMessage.initialText
 text: qsTr("Add text")
 icon.name: "list-add"
 onTriggered: {
 actionsMessage.text = actionsMessage.initialText + " Peekaboo!";
 }
 },
 Kirigami.Action {
 enabled: actionsMessage.text != actionsMessage.initialText
 text: qsTr("Reset text")
 icon.name: "list-remove"
 onTriggered: actionsMessage.text = actionsMessage.initialText
 }
 ]
 }
}

أزرار الإغلاق

توفر الرسائل المضمنة زر إغلاق يمكن استخدامه لرفضها بسهولة.

مبدئيًا، يكون زر الإغلاق هذا مخفيًا، ولكن يمكن تجاوز ذلك بضبط الخاصية showCloseButton إلى true.

Kirigami.InlineMessage {
 Layout.fillWidth: true
 text: "Please don't dismiss me..."
 showCloseButton: true
 visible: true
}

Docs: أشرطة أدوات الإجراءات

Mon, 01 Jan 0001 00:00:00 +0000

بينما تسمح لك صفحات Kirigami بوضع مجموعة من الإجراءات بسهولة في رأس الصفحة، فهناك أوقات قد تفضل فيها شيئًا أكثر مرونة.

يوفر Kirigami المكون Kirigami.ActionToolBar. يعرض قائمة من كائنات Kirigami.Action وسيعرض أكبر عدد ممكن منها، مع توفير قائمة فائض لتلك التي لا تتسع. شريط الأدوات ActionToolBar ديناميكي وسينقل الإجراءات من وإلى قائمة الفائض اعتمادًا على المساحة المتاحة له.

ملاحظة

تفترض هذه الصفحة أنك على دراية بكائنات Kirigami.Action. إذا لم تكن كذلك، يمكنك التعرف عليها بالكامل في دليلنا للمبتدئين أو في صفحة التوثيق المخصصة لها.

إنشاء أول شريط أدوات ActionToolBar لدينا

التخطيط والموقع لـ Kirigami.ActionToolBar يعود إليك حقًا، على الرغم من أنه من أجل سهولة الاستخدام، فمن الجيد عادةً الالتزام باتفاقيات واجهة المستخدم ووضع شريط الأدوات بالقرب من أعلى أو أسفل صفحتك وجعله ممتدًا عرضيًا.

مثل معظم المكونات الأخرى الحاملة للإجراءات، يحتوي Kirigami.ActionToolBar على خاصية actions. يمكننا تعيين مصفوفة من مكونات Kirigami.Action لهذه الخاصية.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 id: root

 title: "ActionToolBar App"
 width: 600
 height: 400

 pageStack.initialPage: Kirigami.Page {
 Kirigami.ActionToolBar {
 anchors.left: parent.left
 anchors.right: parent.right

 actions: [
 Kirigami.Action {
 text: "Beep"
 icon.name: "notifications"
 onTriggered: showPassiveNotification("BEEP!")
 },
 Kirigami.Action {
 text: "Action Menu"
 icon.name: "overflow-menu"

 Kirigami.Action {
 text: "Deet";
 icon.name: "notifications"
 onTriggered: showPassiveNotification("DEET!")
 }
 Kirigami.Action {
 text: "Doot";
 icon.name: "notifications"
 onTriggered: showPassiveNotification("DOOT!")
 }
 },
 Kirigami.Action {
 icon.name: "search"
 displayComponent: Kirigami.SearchField { }
 }
 ]
 }
 }
}

شريط أدوات ActionToolBar بمساحة كافية لجميع العناصر الفرعية

شريط أدوات ActionToolBar بقائمة فائض تحتوي على عناصر فرعية

المحاذاة

افتراضيًا، ستكون الإجراءات في Kirigami.ActionToolBar محاذاة إلى اليسار. قد لا يكون هذا مرغوبًا في جميع الحالات. لحسن الحظ، يمكننا تغيير ذلك باستخدام خاصية alignment. يمكننا تعيين هذه الخاصية إلى مجموعة من القيم، لكن الثلاث الأكثر صلة هي Qt.AlignLeft و Qt.AlignCenter و Qt.AlignRight (التي تتعامل مع المحاذاة الأفقية).

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 id: root

 title: "ActionToolBar App"
 width: 600
 height: 400

 pageStack.initialPage: Kirigami.Page {
 Controls.GroupBox {
 anchors.left: parent.left
 anchors.right: parent.right

 Kirigami.ActionToolBar {
 anchors.fill: parent

 alignment: Qt.AlignCenter

 actions: [
 Kirigami.Action {
 text: "Beep"
 icon.name: "notifications"
 onTriggered: showPassiveNotification("BEEP!")
 }
 ]
 }
 }
 }
}

Docs: أشرطة التقدم والمؤشرات

Mon, 01 Jan 0001 00:00:00 +0000

كلما فعل تطبيقك شيئًا يستغرق وقتًا ملحوظًا، سترغب في استخدام عنصر مرئي يخبر المستخدم أن شيئًا ما يحدث في الخلفية.

توفر عناصر تحكم QtQuick مكونين مفيدين يمكنك استخدامهما لهذه الغاية.

شريط التقدم

Controls.ProgressBar هو مكون يتيح لك تضمين أشرطة التقدم بسهولة في تطبيقك. هناك أربع خصائص رئيسية ستحتاج إلى استخدامها:

from: القيمة الدنيا الممثلة ببداية شريط التقدم
to: القيمة القصوى الممثلة بنهاية شريط التقدم
value: القيمة الحالية للإجراء الجاري (مثل تحميل 50%)
indeterminate: إذا لم يكن للإجراء الجاري حاليًا قيمة تقدم واضحة، يمكنك ضبط هذه الخاصية إلى true لإظهار المستخدم أن شيئًا ما يحدث لكن تقدمه ليس واضحًا بعد (لكنه سيكون قريبًا).

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Progressbar App"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 ColumnLayout {
 anchors.left: parent.left
 anchors.right: parent.right
 Controls.ProgressBar {
 Layout.fillWidth: true
 from: 0
 to: 100
 value: 50
 indeterminate: false
 }
 Controls.ProgressBar {
 Layout.fillWidth: true
 from: 0
 to: 100
 // القيمة: 50
 indeterminate: true
 }
 }
 }
}

أعلاه: شريط تقدم عند 50%؛ أدناه: شريط تقدم غير محدد

مؤشر الانشغال

في الحالات التي تكون فيها أوقات التحميل أقصر أو لا يمكن قياس التقدم، يمكنك بدلاً من ذلك استخدام Controls.BusyIndicator. يوفر هذا المكون عجلة دوارة بسيطة تُظهر للمستخدمين أن شيئًا ما يحدث.

إذا أردت إيقاف تشغيل المؤشر، يمكنك فعل ذلك بضبط الخاصية running إلى false، وفي هذه الحالة .

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Progressbar App"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 actions: [
 Kirigami.Action {
 text: "Toggle busy indicator"
 onTriggered: indicator.running ? indicator.running = false : indicator.running = true
 }
 ]
 Controls.BusyIndicator {
 id: indicator
 anchors.centerIn: parent
 }
 }
}

Docs: مناظر القوائم

Mon, 01 Jan 0001 00:00:00 +0000

يمكن أن تساعدك عروض القوائم في عرض الكائنات من نموذج بطريقة جذابة. لاستخدام عرض قائمة، عليك تتبع ثلاثة أشياء:

النموذج، الذي يحتوي على البيانات التي تريد أن يعرضها عرض القائمة الخاص بك
المفوض، الذي يحدد كيف سيُعرض كل عنصر في النموذج
عرض القائمة نفسه، الذي سيعرض المعلومات من النموذج وفقًا للمفوض

إذا كنت ترغب في مزيد من التوضيح، فإن توثيق كيوتي لديه صفحة إعلامية حول الموضوع.

أساسيات النماذج والعروض

عرض القائمة له خاصيتان أساسيتان يجب أن ننتبه إليهما:

model، التي تقبل البيانات أو id الكائن الذي يحمل البيانات
delegate، التي تقبل المكون الذي سنستخدمه لعرض البيانات في النموذج

النموذج غير مرئي، لأنه يحتوي فقط على بيانات. عادةً ما يُلف المفوض في مكون ليكون قابلاً لإعادة الاستخدام: فهو يعمل كمخطط لكيفية إنشاء كل مفوض.

هذا مثال يحتوي على عرض قائمة واحد، ونموذج واحد، ومفوض واحد، باستخدام Kirigami.SubtitleDelegate:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "List of Plasma products"
 width: 600
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 anchors.fill: parent
 model: plasmaProductsModel
 delegate: listDelegate
 }
 ListModel {
 id: plasmaProductsModel
 ListElement { product: "Plasma Desktop"; target: "desktop" }
 ListElement { product: "Plasma Mobile"; target: "mobile" }
 ListElement { product: "Plasma Bigscreen"; target: "TVs" }
 }
 Component {
 id: listDelegate
 Controls.ItemDelegate {
 width: ListView.view.width
 text: `${model.product} is KDE software developed for ${model.target} stored at index ${model.index} of this list`
 }
 }
 }
}

ونفس المثال تمامًا، مضمنًا:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "List of Plasma products (inline)"
 width: 600
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 anchors.fill: parent
 model: ListModel {
 id: plasmaProductsModel
 ListElement { product: "Plasma Desktop"; target: "desktop" }
 ListElement { product: "Plasma Mobile"; target: "mobile" }
 ListElement { product: "Plasma Bigscreen"; target: "TVs" }
 }
 delegate: Controls.ItemDelegate {
 width: ListView.view.width
 text: `${model.product} is KDE software developed for ${model.target} stored at index ${model.index} of this list`
 }
 }
 }
}

فهم النماذج

يحتوي النموذج على البيانات التي ستُستخدم لملء عرض القائمة. الطرق المختلفة لاستخدام النماذج لها طرق مختلفة للوصول إلى البيانات:

طريقة الاستخدام	كيفية الوصول	متى يُستخدم
نماذج كيوتي بأكثر من دور	model.index, model.somerole	في معظم الحالات
نماذج كيوتي بدور واحد	model.index, model.somerole, model.modelData	في معظم الحالات، للنمذجة الأولية
نموذج مصفوفة جافاسكريبت	model.index, model.modelData	للنمذجة الأولية
نموذج عدد صحيح	model.index, model.modelData	للنمذجة الأولية

يمكنك القراءة عن طرق أخرى لاستخدام النماذج في وثائق كيوتي.

في الجدول أعلاه، تشير "نماذج كيوتي" إلى كل من النماذج الخاصة بـ C++ مثل QAbstractListModel والنماذج الخاصة بـ QML مثل ListModel. ستركز صفحة البرنامج التعليمي هذه فقط على النماذج الخاصة بـ QML. في ما بعد نقدم برنامجًا تعليميًا لـ ربط نماذج C++ بـ QML باستخدام QAbstractListModel.

الخاصية model.index متاحة لكل نموذج وتحتوي على الفهرس (الموضع) لكل مفوض. يمكن اختصارها إلى index للتسهيل.

الخاصية model.somerole المذكورة أعلاه هي مجرد عنصر نائب، وليست خاصية محددة تأتي من QML: somerole يمكن أن يكون أي دور يُعرّفه النموذج. في مثال الكود الأول في هذه الصفحة المعروض أعلاه الجدول، نموذج plasmaProductsModel له دور product وtarget، والتي يمكن الوصول إليها بـ model.product وmodel.target على التوالي.

كما يمكن اختصار model.index إلى index، يمكن اختصار كل خاصية model.somerole إلى somerole فقط (مثل product) للتسهيل، لكن يُوصى بتحويلها إلى خصائص مطلوبة:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "List of Plasma products (shortened with required properties)"
 width: 600
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 anchors.fill: parent
 model: plasmaProductsModel
 delegate: listDelegate
 }
 ListModel {
 id: plasmaProductsModel
 ListElement { product: "Plasma Desktop"; target: "desktop" }
 ListElement { product: "Plasma Mobile"; target: "mobile" }
 ListElement { product: "Plasma Bigscreen"; target: "TVs" }
 }
 Component {
 id: listDelegate
 Controls.ItemDelegate {
 width: ListView.view.width
 required property string product
 required property string target
 required property int index
 text: `${product} is KDE software developed for ${target} stored at index ${index} of this list`
 }
 }
 }
}

بالإضافة إلى ذلك، إذا كان النموذج يحتوي على دور واحد فقط أو لا يحتوي على أي دور، يمكن الوصول إلى بياناته أيضًا بالخاصية model.modelData، والتي يمكن اختصارها إلى modelData (وبالتالي ستحتاج أيضًا إلى أن تكون خاصية مطلوبة):

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami


Kirigami.ApplicationWindow {
 title: "List of KDE software"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 anchors.fill: parent
 model: kdeSoftwareModel
 delegate: listDelegate
 }
 ListModel {
 id: kdeSoftwareModel
 ListElement { software: "Dolphin" }
 ListElement { software: "Discover" }
 ListElement { software: "KHelpCenter" }
 ListElement { software: "KCalc" }
 ListElement { software: "Ark" }
 }
 Component {
 id: listDelegate
 Controls.ItemDelegate {
 width: ListView.view.width
 required property string modelData
 text: modelData // هذا يطابق model.software
 }
 }
 }
}

للمقارنة، إليك كيف سيبدو الكود أعلاه مع مصفوفة جافاسكريبت، بدون دور:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "List of KDE software (as JS array)"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 anchors.fill: parent
 model: ["Dolphin", "Discover", "KHelpCenter", "KCalc", "Ark"]
 delegate: listDelegate
 }
 Component {
 id: listDelegate
 Controls.ItemDelegate {
 width: ListView.view.width
 required property string modelData
 text: modelData
 }
 }
 }
}

استخدام عدد صحيح للنموذج يمكن أن يكون مفيدًا لحالات محددة جدًا، وهي النمذجة الأولية والاختبارات:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Simple list of indexes"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 anchors.fill: parent
 model: 30
 delegate: listDelegate
 }
 Component {
 id: listDelegate
 Controls.ItemDelegate {
 width: ListView.view.width
 required property string modelData
 text: `This delegate's index is: ${modelData}`
 }
 }
 }
}

فهم العروض والمفوضين

لنعد إلى المثال الأصلي:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "List of Plasma products"
 width: 600
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 // anchors.fill: parent
 model: plasmaProductsModel
 delegate: listDelegate
 }
 ListModel {
 id: plasmaProductsModel
 ListElement { product: "Plasma Desktop"; target: "desktop" }
 ListElement { product: "Plasma Mobile"; target: "mobile" }
 ListElement { product: "Plasma Bigscreen"; target: "TVs" }
 }
 Component {
 id: listDelegate
 Controls.ItemDelegate {
 width: ListView.view.width
 text: `${model.product} is KDE software developed for ${model.target} stored at index ${model.index} of this list`
 }
 }
 }
}

على عكس النموذج (الذي يحتوي فقط على البيانات) والمفوض Component (الذي يظهر فقط عند إنشاء مثيل له)، فإن العرض هو مكون مرئي يُنشأ مثيله فورًا ولذا يحتاج إما إلى تعيين أبعاده أو استخدام المراسي أو التخطيطات.

نظرًا لأن العروض عادةً ما تكون قوائم محتوى يرغب المستخدم في التمرير خلالها، فعند إضافتها إلى Kirigami.ScrollablePage، تصبح العروض المحتوى الرئيسي مع حشوة صغيرة حولها، ولا حاجة لجعلها تملأ الصفحة. عند إضافة العرض إلى Kirigami.Page بسيط، سيتطلب تعيين أبعاده بشكل صحيح قبل أن يظهر. بعبارة أخرى: في الصفحة القابلة للتمرير أعلاه، anchors.fill: parent غير مطلوب؛ إذا تم استخدام صفحة بسيطة، فسيكون مطلوبًا.

هناك عروض متعددة يمكن استخدامها من واجهات برمجة التطبيقات، بعضها من كيوتي وبعضها من كيريغامي. إليك الأكثر استخدامًا:

ListView من كيوتي
GridView من كيوتي
TableView من كيوتي
TreeView الخاص بكيو تي
CardsListView الخاص بكيريغامي
ColumnView الخاص بكيريغامي

أما المفوض فدائمًا ما يحتاج إلى ضبط أبعاده. عمومًا تُضبط أبعاده لاستخدام العرض الكامل للمنظر فقط.

الأخطاء الشائعة

يعني ما سبق أن المفوضين لا ينبغي أن يكون لهم مراسٍ سفلية، لأن المفوض لا يحتاج إلى نفس ارتفاع المنظر. بعبارة أخرى، ربما لن ترغب أبدًا في استخدام anchors.fill: parent.

بالإضافة إلى ذلك، بينما يمكن ضبط أبعاده باستخدام الأصل والمراسي، وهو عادةً contentItem الخاص بالمنظر، كما يلي:

Controls.ItemDelegate {
 anchors.left: parent.left
 anchors.right: parent.right
 text: // ...
}

ليس مضمونًا أن يكون أصل المفوض منظرًا، لذا ينبغي تجنب ذلك. بدلًا من ذلك، استخدم الخاصية المرفقة ListView.view للإشارة إلى المنظر الأصلي للمفوض:

Controls.ItemDelegate {
 width: ListView.view.width
 text: // ...
}

الاستخدام الأكثر شيوعًا للمفوض يكون ضمن Component، الذي لا يُنشئ المفوض فورًا. عند بناء منظر، يُستخدم المفوض بعدها كمخطط لصنع كل عنصر في المنظر.

بينما يمكنك صنع مكوناتك المخصصة لاستخدامها كمفوضين دون واجهات برمجة تطبيقات كيو تي الخاصة بالمفوضين (مثلًا، تخطيط يحتوي على بضعة عناصر)، توفر عناصر تحكم كويك كيو تي واجهات برمجة تطبيقات للمفوضين يسهل استخدامها:

ItemDelegate (مفوضون بنص فقط)
CheckDelegate (مفوضون بصندوق اختيار)
RadioDelegate (مفوضون بزر اختيار)
SwitchDelegate (مفوضون بمفتاح)
SwipeDelegate (مفوضون يمكن تمريرهم)

ينبغي تفضيل استخدام مفوضات كيو تي الأصلية حيثما أمكن.

فوق مفوضات كيو تي هذه، يوفر كيريغامي مكافئاتها الخاصة، مع وظائف إضافية للعناوين الفرعية والأيقونات:

يمكن ضبط واجهة البرمجة المنتهية بـ "Delegate" كمفوض مباشر للمنظر، تمامًا مثل الأمثلة السابقة التي استخدمت Controls.ItemDelegate:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.kirigami.delegates as KD

Kirigami.ApplicationWindow {
 title: "List of Plasma products"
 width: 600
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 model: plasmaProductsModel
 delegate: listDelegate
 }
 ListModel {
 id: plasmaProductsModel
 ListElement { product: "Plasma Desktop"; target: "desktop" }
 ListElement { product: "Plasma Mobile"; target: "mobile" }
 ListElement { product: "Plasma Bigscreen"; target: "TVs" }
 }
 Component {
 id: listDelegate
 KD.CheckSubtitleDelegate {
 width: ListView.view.width
 text: `${model.product} is KDE software developed for ${model.target}.`
 subtitle: `This delegate is stored at index ${model.index} of this list`
 icon.name: "kde"
 }
 }
 }
}

من المتوقع استخدام كل من TitleSubtitle وIconTitleSubtitle لتجاوز contentItem الخاص بمفوض كيو تي، على سبيل المثال:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.kirigami.delegates as KD

Kirigami.ApplicationWindow {
 title: "List of Plasma products"
 width: 600
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 // anchors.fill: parent
 model: plasmaProductsModel
 delegate: listDelegate
 }
 ListModel {
 id: plasmaProductsModel
 ListElement { product: "Plasma Desktop"; target: "desktop" }
 ListElement { product: "Plasma Mobile"; target: "mobile" }
 ListElement { product: "Plasma Bigscreen"; target: "TVs" }
 }
 Component {
 id: listDelegate
 Controls.ItemDelegate {
 width: ListView.view.width
 text: `${model.product} is KDE software developed for ${model.target}.`
 contentItem: KD.IconTitleSubtitle {
 title: parent.text
 subtitle: `This delegate is stored at index ${model.index} of this list`
 icon.name: "kde"
 }
 }
 }
 }
}

يمكن رؤية مثال عملي لاستخدام مفوضات كيريغامي في ملف ListItemTest في مستودع كيريغامي.

Docs: فهم CMakeLists

Mon, 01 Jan 0001 00:00:00 +0000

CMake

في دليلنا التمهيدي، استخدمنا CMake كنظام بناء لتطبيقنا، لكننا ركزنا فقط على أحد ملفات CMakeLists.txt الخاصة بنا. هنا، سنستعرض كيفية عمله بمزيد من التفصيل.

CMake مفيد لأنه يسمح لنا بأتمتة الكثير من الأمور التي يجب القيام بها قبل التجميع.

ملف CMakeLists.txt الجذر

قد تتذكر ملف CMakeLists.txt هذا من الدليل الأول:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


cmake_minimum_required(VERSION 3.20)
project(kirigami-tutorial)

find_package(ECM 6.0.0 REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)
include(ECMFindQmlModule)
include(ECMQmlModule)

find_package(Qt6 REQUIRED COMPONENTS
 Core
 Quick
 Test
 Gui
 QuickControls2
 Widgets
)

find_package(KF6 REQUIRED COMPONENTS
 Kirigami
 I18n
 CoreAddons
 QQC2DesktopStyle
 IconThemes
)

ecm_find_qmlmodule(org.kde.kirigami REQUIRED)

add_subdirectory(src)

install(PROGRAMS org.kde.tutorial.desktop DESTINATION ${KDE_INSTALL_APPDIR})

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

السطر الأول، cmake_minimum_required() يضبط إصدار CMake الذي سنستدعيه.

بعد ذلك، project(kirigami-tutorial) يُعرِّف اسم المشروع.

ثم نصل إلى قسم حيث نضمّن عددًا من إعدادات CMake وكيدي الضرورية باستخدام extra-cmake-modules. توفر مجموعة من الأدوات المفيدة:

يوفر KDEInstallDirs متغيرات تسهيلية مثل ${KDE_INSTALL_TARGETS_DEFAULT_ARGS} و${KDE_INSTALL_QMLDIR} و${KDE_INSTALL_BINDIR} و${KDE_INSTALL_LIBDIR}.
يوفر KDECMakeSettings أشياء مثل CMAKE_AUTORCC ON، وهدف uninstall يمكن استخدامه مع cmake --build build/ --target uninstall، وENABLE_CLAZY.
يوفر KDECompilerSettings معيار C++ أدنى، وعلميات مترجم مثل -pedantic، ووحدات ماكرو لأفضل الممارسات مثل -DQT_NO_CAST_FROM_ASCII لطلب تحويلات صريحة مثل QStringLiteral().
يوفر ECMFindQmlModule طريقة لضمان العثور على تبعية QML وقت التشغيل في وقت التجميع.
يوفر ECMQmlModule أوامر CMake مثل ecm_add_qml_module() وecm_target_qml_sources().

القسم التالي مهم، لأنه يحدد التبعيات التي سنضيفها في وقت التجميع. لننظر إلى الأول:

13
14
15
16
17
18
19
20
21
22
23
24
25
26


find_package(Qt6 REQUIRED COMPONENTS
 Core
 Quick
 Test
 Gui
 QuickControls2
 Widgets
)

find_package(KF6 REQUIRED COMPONENTS
 Kirigami
 I18n
 CoreAddons
 QQC2DesktopStyle

يجد find_package() المكتبة الخارجية ومكوناتها ويحملها.
يخبر REQUIRED CMake بالخروج مع خطأ إذا تعذر العثور على الحزمة.
COMPONENTS هو معامل يسبق المكونات المحددة للإطار الذي سنضمّنه.
كل كلمة بعد COMPONENTS تشير إلى مكون محدد من المكتبة.

ملاحظة

إذا كنت تبحث عن إضافة أي مكونات مدرجة في توثيق API كيدي إلى تطبيقك، يمكنك التحقق من الشريط الجانبي الأيمن لكيفية إضافة المكون باستخدام CMake. على سبيل المثال، بالنسبة لـ Kirigami، ستجد شيئًا مثل find_package(KF6Kirigami)، والذي مع إضافة ECM يصبح:

find_package(KF6 COMPONENTS Kirigami)

انتبه جيدًا للمكونات المضمّنة، لأن حذف المكونات المستخدمة في الكود سيوقف تطبيقنا عن التجميع.

يوجه سطر التثبيت CMake لتثبيت ملف سطح المكتب في ${KDE_INSTALL_APPDIR}، والذي يُترجم على لينكس إلى $XDG_DATA_DIRS/applications، عادةً /usr/share/applications، وعلى ويندوز يُترجم إلى C:/Program Files/${PROJECT_NAME}/bin/data/applications:

34

install(PROGRAMS org.kde.tutorial.desktop DESTINATION ${KDE_INSTALL_APPDIR})

يسمح السطر الأخير لـ CMake بطباعة الحزم التي وجدها، ويجعل التجميع يفشل فورًا إذا واجه خطأً:

36

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

وفوق ذلك، يشير add_subdirectory(src) إلى CMake داخل الدليل src/، حيث يجد ملف CMakeLists.txt آخر.

src/CMakeLists.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


add_executable(kirigami-hello)

ecm_add_qml_module(kirigami-hello
 URI
 org.kde.tutorial
)

target_sources(kirigami-hello
 PRIVATE
 main.cpp
)

ecm_target_qml_sources(kirigami-hello
 SOURCES
 Main.qml
)

target_link_libraries(kirigami-hello
 PRIVATE
 Qt6::Quick
 Qt6::Qml
 Qt6::Gui
 Qt6::QuickControls2
 Qt6::Widgets
 KF6::I18n
 KF6::CoreAddons
 KF6::IconThemes
)

install(TARGETS kirigami-hello ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

بينما تعامل الملف الأول مع البيانات الوصفية وإيجاد المكتبات، سيتكون هذا الملف من معالجة التبعيات وتثبيت التطبيق. يحتوي على استدعاءات CMake التالية:

ينشئ add_executable() الهدف القابل للتنفيذ الذي سنستخدمه لتشغيل مشروعنا.
ينشئ ecm_add_qml_module() هدف وحدة QML سيكون متاحًا عبر الاستيراد "org.kde.tutorial".
يضيف target_sources() ملفات مصدر C++ إلى الهدف القابل للتنفيذ.
يضيف ecm_target_qml_sources() ملفات QML إلى الوحدة.
يربط target_link_libraries() مكتبات C++ المستخدمة في كودنا بملفنا القابل للتنفيذ. لم تُدرج Kirigami هنا لأننا نستخدم وحدة QML الخاصة بها فقط.
يثبت install() الملف القابل للتنفيذ في النظام.

يمكن العثور على توثيق الأمرين ECM في واجهة برمجة تطبيقات extra-cmake-modules لوحدة ECMQmlModule.

استُخدم استدعاء ecm_add_qml_module() هنا لتعديل الهدف القابل للتنفيذ التقليدي لرمز C++ المصدر وتحويله إلى شيء يمكنه قبول ملفات QML ورمز C++ المصدر الذي يمكن الوصول إليه من QML فيما يُسمى استخدام الملف القابل للتنفيذ كهدف داعم لوحدة QML. هذا يعني أن ملفات QML تُشغّل مباشرة كجزء من التطبيق، وهو الحال غالبًا للتطبيقات.

يمكنك أيضًا إنشاء وحدة QML منفصلة لا تستخدم الملف القابل للتنفيذ كهدف داعم باستخدام ecm_add_qml_module(). في هذه الحالة، ستنشئ هدف مكتبة باستخدام add_library()، وتربطه بهدف قابل للتنفيذ موجود باستخدام target_link_libraries()، وبالإضافة إلى تثبيت المكتبة بـ install() ستحتاج إلى إنهاء وحدة QML بـ ecm_finalize_qml_module() حتى تتمكن من إنشاء ملفين: qmldir و qmltypes. تُستخدم هذه الملفات بواسطة تطبيقات QtQuick لإيجاد وحدات QML المنفصلة.

طريقة إنشاء وحدة QML منفصلة موضحة بشكل أفضل في استخدام ملفات منفصلة.

هذه إضافات مقدمة من extra-cmake-modules لتسهيل استخدام تسجيل Qt التصريحي (بديل ملفات موارد Qt).

ملاحظة

يجب أن تطابق هذه المكتبات المكونات التي أدرجناها في ملف CMakeLists.txt السابق، وإلا فلن تُدرج هذه المكونات ولن يترجم تطبيقنا.

يمكن العثور على توثيق الأوامر الثلاثة في واجهة برمجة تطبيقات extra-cmake-modules لوحدة ECMQmlModule.

src/components/CMakeLists.txt

في البرنامج التعليمي حول كيفية تقسيم كودك إلى ملفات منفصلة، قُدّم ملف CMake جديد للسماح بوحدات QML منفصلة:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


add_library(kirigami-hello-components)

ecm_add_qml_module(kirigami-hello-components
 URI "org.kde.tutorial.components"
 GENERATE_PLUGIN_SOURCE
)

ecm_target_qml_sources(kirigami-hello-components
 SOURCES
 AddDialog.qml
 KountdownDelegate.qml
)

ecm_finalize_qml_module(kirigami-hello-components)

install(TARGETS kirigami-hello-components ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

شرط قراءة هذا الملف بواسطة CMake هو إضافة استدعاء لـ add_subdirectory() في src/CMakeLists.txt يشير إليه.

ينشئ استدعاء add_library() هدفًا جديدًا يُسمى kirigami-hello-components. سيكون لهذا الهدف مجموعته الخاصة من ملفات الكود المصدري وملفات QML ويربط مكتباته الخاصة وهكذا، لكنه يحتاج إلى الربط بالملف القابل للتنفيذ، ولكن بمجرد ترجمته يحتاج إلى الربط بالملف القابل للتنفيذ الذي أُنشئ في src/CMakeLists.txt. يتم ذلك بإضافة اسم الهدف إلى قائمة المكتبات التي سترتبط بالملف القابل للتنفيذ في target_link_libraries().

يغير استدعاء ecm_add_qml_module() المكتبة للسماح لها بقبول ملفات QML كما في السابق، لكن هذه المرة نحتاج إلى استخدام GENERATE_PLUGIN_SOURCE. عندما يُستخدم الملف القابل للتنفيذ كهدف داعم (مثل kirigami-hello) لا يحتاج إلى إنشاء كود إضافة لأنه مدمج في الملف القابل للتنفيذ؛ مع وحدات QML المنفصلة مثل kirigami-hello-components يكون كود الإضافة ضروريًا.

ينشئ qt_add_qml_module() الخاص بـ Qt المنبع افتراضيًا إضافة مع وحدة QML، لكن ecm_add_qml_module() الخاص بـ كيدي لا يفعل ذلك افتراضيًا للتوافق مع الإصدارات السابقة.

شيء آخر ضروري لوحدات QML المنفصلة هو إنهاء الهدف. هذا يعني بشكل أساسي أن CMake ينشئ ملفين، qmldir و qmltypes، يصفان وحدات QML التي لدينا ويصدران رموزها للاستخدام في المكتبة. إنها مهمة عند تثبيت تطبيقك حتى يتمكن الملف القابل للتنفيذ الذي يُشغّل من العثور على مكان ملفات QML لكل وحدة، لذا تُضاف تلقائيًا إلى الهدف.

يمكنك بعد ذلك تثبيت الهدف كما في السابق.

في المرة القادمة التي تحتاج فيها إلى إضافة المزيد من ملفات QML، تذكر تضمينها في هذا الملف. يمكن أيضًا إضافة ملفات C++ التي تستخدم الكلمة المفتاحية QML_ELEMENT والتي سنراها لاحقًا في البرنامج التعليمي هنا باستخدام target_sources(). يمكنك فصل كودك منطقيًا عن طريق إنشاء المزيد من وحدات QML باستيرادات مختلفة حسب الحاجة.

سيكون هذا الإعداد مفيدًا عند تطوير معظم تطبيقات Kirigami.

Docs: فهم main.cpp

Mon, 01 Jan 0001 00:00:00 +0000

دور main.cpp

بينما يُستخدم QML للواجهة الأمامية لتطبيقات كيريغامي، تُكتب الواجهة الخلفية عادةً بلغة C++ بفضل سرعة هذه اللغة ومرونتها. بينما غطينا QML بعمق كبير في الصفحات السابقة، سنحتاج إلى فهم كود C++ للواجهة الخلفية لصنع تطبيقات أكثر فائدة مما يمكن تحقيقه باستخدام QML الخالص.

هنا، سنستعرض ملف main.cpp الذي أنشأناه في صفحة البدء لنفهم بشكل أفضل ما يحدث في ملف C++ المركزي لتطبيقنا. بينما هذا main.cpp أساسي، ستبقى الميزات التي سنستعرضها أساسية بغض النظر عن نوع التطبيق الذي تقرر إنشاءه.

ما يفعله

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


#include <QApplication>
#include <QQmlApplicationEngine>
#include <QtQml>
#include <QUrl>
#include <QQuickStyle>
#include <KLocalizedContext>
#include <KLocalizedString>
#include <KIconTheme>

int main(int argc, char *argv[])
{
 KIconTheme::initTheme();
 QApplication app(argc, argv);
 KLocalizedString::setApplicationDomain("tutorial");
 QApplication::setOrganizationName(QStringLiteral("KDE"));
 QApplication::setOrganizationDomain(QStringLiteral("kde.org"));
 QApplication::setApplicationName(QStringLiteral("Kirigami Tutorial"));
 QApplication::setDesktopFileName(QStringLiteral("org.kde.tutorial"));

 QApplication::setStyle(QStringLiteral("breeze"));
 if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE")) {
 QQuickStyle::setStyle(QStringLiteral("org.kde.desktop"));
 }

 QQmlApplicationEngine engine;

 engine.rootContext()->setContextObject(new KLocalizedContext(&engine));
 engine.loadFromModule("org.kde.tutorial", "Main");

 if (engine.rootObjects().isEmpty()) {
 return -1;
 }

 return app.exec();
}

أولاً، يجب تضمين عدد من ملفات الرأس الخاصة بكيوت، مما يسمح لنا باستخدام دوالها. في هذه الحالة، نضمّن عددًا من رؤوس كيوت التي تعالج منطق التطبيق، وتسمح لنا بقراءة ملفات QML.

ثم ننشئ مثيلاً لـ QApplication نسميه app. تمرير argc و argv إلى المنشئ مطلوب للاستدعاء.

نضبط أيضًا بعض البيانات الوصفية المتعلقة بالتطبيق. تتضمن هذه المنظمة التي أنشأت التطبيق، موقع المنظمة على الويب، واسم التطبيق. نضبط هذه الخصائص باستدعاء QApplication، وإنشاء كائن يأتي من QCoreApplication ويوفر حلقة الأحداث للتطبيقات بغض النظر عن وجود واجهة مستخدم رسومية أم لا (لذا إذا شغّلنا برنامجنا بدون الواجهة الرسومية، ستظل هذه البيانات الوصفية مضبوطة).

لجعل تطبيقنا يبدو جيدًا مع أيقونات Breeze ونمط Breeze في بيئات غير بلازما مثل ويندوز أو جنوم، نحتاج إلى فعل ثلاثة أشياء:

تهيئة مرافق التنسيق لـ KIconThemes على المنصات التي لا تكون فيها سمات الأيقونات جزءًا من النظام (مثل ويندوز أو ماك أو إس) باستخدام KIconTheme::initTheme()
ضبط QStyle باستخدام QApplication::setStyle() لفرض Breeze بدلاً من نمط المنصة الأصلي
ضبط نمط عناصر تحكم QtQuick باستخدام QQuickStyle::setStyle() لفرض Breeze مع qqc2-desktop-style الخاص بكيدي

يجب أن يتم استدعاء KIconTheme::initTheme() قبل إنشاء QApplication ويسمح للتطبيق بالعثور على أيقونات Breeze لاستخدامها. ضبط QStyle إلى Breeze ضروري لأننا استخدمنا QApplication لتطبيقنا بدلاً من QGuiApplication. عناصر التحكم الفعلية في النافذة مثل الأزرار ومربعات الاختيار ستتبع Breeze باستخدام qqc2-desktop-style.

يسمح لنا QQmlApplicationEngine بتحميل تطبيق من ملف QML، وهو ما نقوم به في السطر التالي. في engine.loadFromModule("org.kde.tutorial", "Main"); نقوم بتحميل QML الخاص بنا من استيراد URI المُعرَّف في CMake.

بعد ذلك، نتحقق مما إذا كان المحرك قد حمّل ملف QML بشكل صحيح عن طريق التحقق من أن قائمة rootObjects() للمحرك ليست فارغة. يمكننا بعد ذلك تشغيل تطبيقنا باستخدام app.exec().

Docs: صفحة حول

Mon, 01 Jan 0001 00:00:00 +0000

يتيح لك Kirigami.AboutPage الحصول على صفحة تعرض إشعار حقوق النشر للتطبيق مع قائمة المساهمين وبعض المعلومات عن النظام الأساسي الذي يعمل عليه.

أولاً، سنقوم بتحرير ملف main.cpp الخاص بنا من الدروس السابقة.

main.cpp

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64


#include <QApplication>
#include <QQmlApplicationEngine>
#include <QtQml>
#include <QUrl>
#include <KAboutData>
#include <KLocalizedContext>
#include <KLocalizedString>

int main(int argc, char *argv[])
{
 QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling);

 QApplication app(argc, argv);

 KLocalizedString::setApplicationDomain("helloworld");
 QCoreApplication::setOrganizationName(QStringLiteral("KDE"));
 QCoreApplication::setOrganizationDomain(QStringLiteral("kde.org"));
 QCoreApplication::setApplicationName(QStringLiteral("Hello World"));

 if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE")) {
 QQuickStyle::setStyle(QStringLiteral("org.kde.desktop"));
 }

 KAboutData aboutData(
 QStringLiteral("helloworld"),
 i18nc("@title", "Hello World"),
 QStringLiteral("1.0"),
 i18n("Hello world application"),
 KAboutLicense::GPL,
 i18n("(c) 2021"));

 aboutData.addAuthor(
 i18nc("@info:credit", "Your name"),
 i18nc("@info:credit", "Author Role"),
 QStringLiteral("your@email.com"),
 QStringLiteral("https://yourwebsite.com"));

 // Set aboutData as information about the app
 KAboutData::setApplicationData(aboutData);

 // Register a singleton that will be accessible from QML.
 qmlRegisterSingletonType(
 "org.kde.example", // How the import statement should look like
 1, 0, // Major and minor versions of the import
 "About", // The name of the QML object
 [](QQmlEngine* engine, QJSEngine *) -> QJSValue {
 // Here we retrieve our aboutData and give it to the QML engine
 // to turn it into a QML type
 return engine->toScriptValue(KAboutData::applicationData());
 }
 );

 // Load an application from a QML file
 QQmlApplicationEngine engine;

 engine.rootContext()->setContextObject(new KLocalizedContext(&engine));
 engine.load(QUrl(QStringLiteral("qrc:/main.qml")));

 if (engine.rootObjects().isEmpty()) {
 return -1;
 }

 return app.exec();
}

في ملف main.cpp نضمّن KAboutData، وهو مكون أساسي من أطر عمل كيدي يتيح لنا تخزين معلومات عن تطبيقنا. يمكن بعد ذلك إعادة استخدام هذه المعلومات بواسطة العديد من مكونات أطر عمل كيدي الأخرى. ننشئ كائن aboutData جديدًا بمنشئه المبدئي الكامل إلى حد ما ونضيف معلومات المؤلف.

بعد ضبط كل المعلومات المطلوبة، نستدعي KAboutData::setApplicationData() لتهيئة خصائص كائن QApplication .

ثم ننشئ qmlRegisterSingletonType(). يُستخدم هذا للسماح لنا باستيراد شيفرة C++ كوحدة في main.qml باستخدام import org.kde.example 1.0.

وسيطته الأولى هي URI التي ستُستخدم للاستيراد، والوسيطتان الثانية والثالثة هما الإصداران الرئيسي والثانوي على التوالي، والرابعة هي اسم النوع، الاسم الذي سنستدعيه عند الوصول إلى نوع About، والأخيرة هي مرجع إلى كائن C++ المُعرَّض لـ QML. في حالة الأخير، نستخدم لامدا لإنشاء aboutData لتطبيقنا في مكانه.

main.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

import org.kde.example 1.0

Kirigami.ApplicationWindow {
 id: root

 title: i18nc("@title:window", "Day Kountdown")

 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "gtk-quit"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 },

 Kirigami.Action { // <==== Action to open About page
 text: i18n("About")
 icon.name: "help-about"
 onTriggered: pageStack.layers.push(aboutPage)
 }
 ]
 }

 Component { // <==== Component that instantiates the Kirigami.AboutPage
 id: aboutPage

 Kirigami.AboutPage {
 aboutData: About
 }
 }

 ListModel {
 id: kountdownModel
 }

 AddEditSheet {
 id: addEditSheet
 onAdded: kountdownModel.append({
 "name": name,
 "description": description,
 "date": Date.parse(kdate)
 });
 onEdited: kountdownModel.set(index, {
 "name": name,
 "description": description,
 "date": Date.parse(kdate)
 });
 onRemoved: kountdownModel.remove(index, 1)
 }

 function openPopulatedSheet(mode, index = -1, listName = "", listDesc = "", listDate = "") {
 addEditSheet.mode = mode
 addEditSheet.index = index;
 addEditSheet.name = listName
 addEditSheet.description = listDesc
 addEditSheet.kdate = listDate

 addEditSheet.open()
 }


 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")

 actions: [
 Kirigami.Action {
 id: addAction
 icon.name: "list-add"
 text: i18nc("@action:button", "Add kountdown")
 onTriggered: openPopulatedSheet("add")
 }
 ]

 Kirigami.CardsListView {
 id: layout
 model: kountdownModel
 delegate: KountdownDelegate {}
 }
 }
}

أولًا، نستخدم الاستيراد الذي عرّفناه في ملف main.cpp، أي org.kde.example. ثم نضيف Kirigami.Action إلى الدرج العام الذي سيرسلنا إلى صفحة حول، وننشئ مكونًا يحتوي على Kirigami.AboutPage فيه، والذي يتوقع كائن KAboutData::applicationData(). لقد عرضنا ذلك بالضبط في main.cpp وأسميناه About، لذا يمكننا تمريره هنا.

CMakeLists

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


cmake_minimum_required(VERSION 3.16)
project(helloworld)

find_package(ECM REQUIRED NO_MODULE)

set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)

find_package(Qt6 REQUIRED NO_MODULE COMPONENTS
 Core
 Quick
 Test
 Gui
 QuickControls2
 Widgets
)

find_package(KF6 REQUIRED COMPONENTS
 Kirigami2
 I18n
 CoreAddons
)

add_subdirectory(src)

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

في ملف CMakeLists.txt في مجلدنا الأعلى، تأكد من وجود CoreAddons في استدعاء find_package(). إنه مطلوب لـ KAboutData.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


add_executable(helloworld)

target_sources(helloworld PRIVATE
 main.cpp
 resources.qrc
)

target_link_libraries(helloworld
 Qt6::Quick
 Qt6::Qml
 Qt6::Gui
 Qt6::QuickControls2
 Qt6::Widgets
 KF6::Kirigami2
 KF6::I18n
 KF6::CoreAddons
)

في ملف CMakeLists.txt في دليل src/، لا حاجة لشيء لأننا أنشأنا aboutData في مكانه.

تشغيل التطبيق

الآن إذا شغّلت تطبيقك وفعّلت إجراء "حول" في الدرج العام، يجب أن ترى صفحة حول.

Docs: اربط المنطق بواجهة مستخدم QML الخاصة بك

Mon, 01 Jan 0001 00:00:00 +0000

لدمج المنطق في التطبيق، نحتاج إلى أصناف خلفية C++ يمكنها إجراء الحسابات المهمة. لا يُشجَّع كتابة المنطق في ملفات QML، لذا حاول نقل أكبر قدر ممكن إلى الخلفية بحيث يُستخدم QML فقط لعرض واجهة المستخدم.

سنستخدم شيفرة البرنامج التعليمي استخدام ملفات منفصلة في مشروع C++ كأساس لنا.

هيكل المشروع

kirigami-tutorial/
├── CMakeLists.txt
├── org.kde.tutorial.desktop
└── src/
├── CMakeLists.txt
├── main.cpp
├── Main.qml ----------------------- # Modified
└── components/
├── CMakeLists.txt ------------- # Modified
├── AddDialog.qml
├── KountdownDelegate.qml
├── ExposePage.qml ------------- # New
├── backend.h ------------------ # New
└── backend.cpp ---------------- # New

تغييرات على الشيفرة الموجودة

src/components/backend.h

أولًا، أنشئ ملف الرأس الذي سيحتوي على شيفرة مُعرَّضة لـ QML، أي نوع Backend:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


#pragma once

#include <QObject>
#include <qqmlintegration.h>

class Backend : public QObject
{
 Q_OBJECT
 QML_ELEMENT
 QML_SINGLETON

public:
 explicit Backend(QObject *parent = nullptr);
};

هناك شيئان مطلوبان لعرض شيفرة C++ لـ QML، وأحدهما هو ببساطة استخدام كلية QML_ELEMENT، المتوفرة في ملف الرأس <QtQml/qqmlregistration.h>.

سيُأنشأ الخلفية كمفردة، مما يعني أنها ستُنشأ مرة واحدة فقط وتوجد طوال مدة عمر التطبيق. لهذا، نستخدم كلية QML_SINGLETON.

src/components/backend.cpp

يمكننا إضافة شيفرتنا الأولية للباني إلى backend.cpp:

1
2
3
4
5


#include "backend.h"

Backend::Backend(QObject *parent)
 : QObject(parent)
{}

src/components/ExposePage.qml

من الآن فصاعدًا، ستُعرف الخلفية لـ QML كنوع QML Backend. وهي موجودة في وحدة تُسمى org.kde.tutorial.components.

هذا يعني أنه بمجرد إضافة الاستيراد في ملف QML، يمكن استخدام الشيفرة المُعرَّضة من C++:

import org.kde.tutorial.components

للبدء من صفحة نظيفة باستخدام شيفرة التطبيق الموجودة، أنشئ مكون QML جديدًا يحتوي على صفحة فارغة:

1
2
3
4
5
6
7


import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.Page {
 title: "Exposing to QML Tutorial"
 // ...
}

src/Main.qml

لإظهار الصفحة الجديدة فعليًا، لننشئ خيار قائمة يدفع الصفحة الجديدة إلى التطبيق، فقط لنتمكن من اختبار النموذج بسهولة أكبر.

لهذا، يمكننا استخدام Kirigami.Action جديد مع Qt.createComponent() لتوليد الصفحة أثناء التشغيل:

15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Exposing to QML")
 icon.name: "kde"
 onTriggered: pageStack.push(Qt.createComponent("org.kde.tutorial.components", "ExposePage"))
 },
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }

src/components/CMakeLists.txt

أخيرًا، أضف backend.h و backend.cpp و ExposePage.qml المُنشأة حديثًا إلى CMake:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


add_library(kirigami-hello-components)

ecm_add_qml_module(kirigami-hello-components
 URI "org.kde.tutorial.components"
 GENERATE_PLUGIN_SOURCE
)

ecm_target_qml_sources(kirigami-hello-components
 SOURCES
 AddDialog.qml
 KountdownDelegate.qml
 ExposePage.qml
)

target_sources(kirigami-hello-components
 PRIVATE
 backend.cpp backend.h
)

ecm_finalize_qml_module(kirigami-hello-components)

install(TARGETS kirigami-hello-components ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

إضافة الملفات إلى وحدة QML موجودة في CMake هو الجزء الثاني لعرض الشيفرة لـ QML.

لاحظ أن وحدة QML ينبغي أن تكون قد أُنشئت إما باستخدام ecm_add_qml_module() أو qt_add_qml_module()، حيث أنها مطلوبة لـ التسجيل التصريحي.

الآن ينبغي أن تكون قادرًا على ترجمة وتثبيت المشروع بـ نفس الخطوات السابقة.

جعله فعالًا

src/components/backend.h

الآن وصلنا الصف الذي يحمل المنطق المستقبلي بالتطبيق، لكنه لا يفعل شيئًا بعد. لتغيير ذلك، لنضف خاصية إلى الصف. الخصائص هي أكثر بكثير من مجرد متغير بسيط. يمكنها إعلام واجهة المستخدم بالتغييرات لتتمكن من تحديث المناطق الصحيحة.

أسفل ماكرو QML_SINGLETON مباشرة، أضف Q_PROPERTY جديدة.

Q_PROPERTY(QString introductionText READ introductionText WRITE setIntroductionText NOTIFY introductionTextChanged)

قد يبدو هذا ككثير من الكود لمجرد قراءة وكتابة بعض الكود من الخلفية. لكن نظرة أقرب تكشف أن قراءة الخاصية من واجهة المستخدم يمكنها بالفعل تشغيل بعض المنطق—وكذلك عند الكتابة إليها. في هذه الحالة، ستُعلم تلقائيًا الواجهة الأمامية والخلفية بالتغييرات.

القراءة والكتابة تستندان إلى مفهوم دوال الجلب والضبط. تفضل وأضف سمة خاصة جديدة إلى صفك تحمل البيانات، بالإضافة إلى دوال الجلب والضبط ذات الصلة.

أضف قسمًا خاصًا جديدًا بما يلي:

private:
 QString m_introductionText = QStringLiteral("Hello World!");

وأضف ما يلي إلى القسم العام الموجود:

public:
 QString introductionText() const;
 void setIntroductionText(const QString &introductionText);
 Q_SIGNAL void introductionTextChanged();

الدالة الأولى هي الجالب، والثانية الضابط، والثالثة إشارة تُبعث عندما تُغير الخاصية. تتطابق مع أجزاء READ و WRITE و NOTIFY من Q_PROPERTY أعلاه.

النتيجة ينبغي أن تبدو كما يلي:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


#pragma once

#include <QObject>
#include <qqmlintegration.h>

class Backend : public QObject
{
 Q_OBJECT
 QML_ELEMENT
 QML_SINGLETON
 Q_PROPERTY(QString introductionText READ introductionText WRITE setIntroductionText NOTIFY introductionTextChanged)
public:
 explicit Backend(QObject *parent = nullptr);
 QString introductionText() const;
 void setIntroductionText(const QString &introductionText);
 Q_SIGNAL void introductionTextChanged();
private:
 QString m_introductionText = QStringLiteral("Hello World!");
};

src/components/backend.cpp

الإشارة لا تحتاج أي تنفيذ في ملف backend.cpp، حيث أنها لا تفعل أكثر من البعث، لكن الجالب والضابط يحتاجان إلى تنفيذ مشابه لما يلي:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


#include "backend.h"

Backend::Backend(QObject *parent)
 : QObject(parent)
{}

QString Backend::introductionText() const
{
 return m_introductionText;
}

void Backend::setIntroductionText(const QString &introductionText)
{
 m_introductionText = introductionText;
 Q_EMIT introductionTextChanged();
}

كما ترى، عندما يُستدعى الضابط، ستُبعث الإشارة، وتُعلم واجهة المستخدم والخلفية بالتغيير.

src/components/ExposePage.qml

لعرض النص، أضف Kirigami.Heading إلى src/components/ExposePage.qml تحت خاصية title لمكون Kirigami.Page الذي أضفناه إلى الكود.

الكود الناتج في ذلك الجزء من الملف ينبغي أن يبدو هكذا:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.Page {
 title: "Exposing to QML Tutorial"
 Kirigami.Heading {
 anchors.centerIn: parent
 text: Backend.introductionText
 }
}

تطبيقنا حتى الآن

الكود الموجود:

CMakeLists.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


cmake_minimum_required(VERSION 3.20)
project(kirigami-tutorial)

find_package(ECM 6.0.0 REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)
include(ECMFindQmlModule)
include(ECMQmlModule)

find_package(Qt6 REQUIRED COMPONENTS
 Core
 Quick
 Test
 Gui
 QuickControls2
 Widgets
)

find_package(KF6 REQUIRED COMPONENTS
 Kirigami
 I18n
 CoreAddons
 QQC2DesktopStyle
 IconThemes
)

ecm_find_qmlmodule(org.kde.kirigami REQUIRED)

add_subdirectory(src)

install(PROGRAMS org.kde.tutorial.desktop DESTINATION ${KDE_INSTALL_APPDIR})

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

src/main.cpp

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


#include <QApplication>
#include <QQmlApplicationEngine>
#include <QtQml>
#include <QUrl>
#include <QQuickStyle>
#include <KLocalizedContext>
#include <KLocalizedString>
#include <KIconTheme>

int main(int argc, char *argv[])
{
 KIconTheme::initTheme();
 QApplication app(argc, argv);
 KLocalizedString::setApplicationDomain("tutorial");
 QApplication::setOrganizationName(QStringLiteral("KDE"));
 QApplication::setOrganizationDomain(QStringLiteral("kde.org"));
 QApplication::setApplicationName(QStringLiteral("Kirigami Tutorial"));
 QApplication::setDesktopFileName(QStringLiteral("org.kde.tutorial"));

 QApplication::setStyle(QStringLiteral("breeze"));
 if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE")) {
 QQuickStyle::setStyle(QStringLiteral("org.kde.desktop"));
 }

 QQmlApplicationEngine engine;

 engine.rootContext()->setContextObject(new KLocalizedContext(&engine));
 engine.loadFromModule("org.kde.tutorial", "Main");

 if (engine.rootObjects().isEmpty()) {
 return -1;
 }

 return app.exec();
}

src/CMakeLists.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


add_executable(kirigami-hello)

ecm_add_qml_module(kirigami-hello
 URI
 org.kde.tutorial
)

target_sources(kirigami-hello
 PRIVATE
 main.cpp
)

ecm_target_qml_sources(kirigami-hello
 SOURCES
 Main.qml
)

target_link_libraries(kirigami-hello
 PRIVATE
 Qt6::Quick
 Qt6::Qml
 Qt6::Gui
 Qt6::QuickControls2
 Qt6::Widgets
 KF6::I18n
 KF6::CoreAddons
 KF6::IconThemes
 kirigami-hello-components
)

install(TARGETS kirigami-hello ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

add_subdirectory(components)

src/components/KountdownDelegate.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.AbstractCard {
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2

 Kirigami.Heading {
 level: 1
 text: i18n("%1 days", Math.round((date-Date.now())/86400000))
 }

 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }
 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }
 Controls.Label {
 Layout.fillWidth: true
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: i18n("Edit")
 }
 }
 }
}

src/components/AddDialog.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.Dialog {
 id: addDialog
 title: i18nc("@title:window", "Add kountdown")
 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 padding: Kirigami.Units.largeSpacing
 preferredWidth: Kirigami.Units.gridUnit * 20

 Kirigami.FormLayout {
 Controls.TextField {
 id: nameField
 Kirigami.FormData.label: i18nc("@label:textbox", "Name*:")
 onAccepted: descriptionField.forceActiveFocus()
 }
 Controls.TextField {
 id: descriptionField
 Kirigami.FormData.label: i18nc("@label:textbox", "Description:")
 onAccepted: dateField.forceActiveFocus()
 }
 Controls.TextField {
 id: dateField
 Kirigami.FormData.label: i18nc("@label:textbox", "ISO Date*:")
 inputMask: "D999-99-99"
 onAccepted: addDialog.accepted()
 }
 Controls.Label {
 text: "* = required fields"
 }
 }
 Component.onCompleted: {
 const button = standardButton(Kirigami.Dialog.Ok);
 button.enabled = Qt.binding( () => requiredFieldsFilled() );
 }
 onAccepted: {
 if (!addDialog.requiredFieldsFilled()) return;
 appendDataToModel();
 clearFieldsAndClose();
 }
 function requiredFieldsFilled() {
 return (nameField.text !== "" && dateField.acceptableInput);
 }
 function appendDataToModel() {
 kountdownModel.append({
 name: nameField.text,
 description: descriptionField.text,
 date: new Date(dateField.text)
 });
 }
 function clearFieldsAndClose() {
 nameField.text = ""
 descriptionField.text = ""
 dateField.text = ""
 addDialog.close();
 }
}

الكود المكتوب/المعدل في هذه الصفحة:

src/Main.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.ApplicationWindow {
 id: root

 width: 600
 height: 400

 title: i18nc("@title:window", "Day Kountdown")

 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Exposing to QML")
 icon.name: "kde"
 onTriggered: pageStack.push(Qt.createComponent("org.kde.tutorial.components", "ExposePage"))
 },
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }

 ListModel {
 id: kountdownModel
 }

 AddDialog {
 id: addDialog
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")

 actions: [
 Kirigami.Action {
 id: addAction
 icon.name: "list-add-symbolic"
 text: i18nc("@action:button", "Add kountdown")
 onTriggered: addDialog.open()
 }
 ]

 Kirigami.CardsListView {
 id: cardsView
 model: kountdownModel
 delegate: KountdownDelegate {}
 }
 }
}

src/components/CMakeLists.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


add_library(kirigami-hello-components)

ecm_add_qml_module(kirigami-hello-components
 URI "org.kde.tutorial.components"
 GENERATE_PLUGIN_SOURCE
)

ecm_target_qml_sources(kirigami-hello-components
 SOURCES
 AddDialog.qml
 KountdownDelegate.qml
 ExposePage.qml
)

target_sources(kirigami-hello-components
 PRIVATE
 backend.cpp backend.h
)

ecm_finalize_qml_module(kirigami-hello-components)

install(TARGETS kirigami-hello-components ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

src/components/backend.h

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


#pragma once

#include <QObject>
#include <qqmlintegration.h>

class Backend : public QObject
{
 Q_OBJECT
 QML_ELEMENT
 QML_SINGLETON
 Q_PROPERTY(QString introductionText READ introductionText WRITE setIntroductionText NOTIFY introductionTextChanged)
public:
 explicit Backend(QObject *parent = nullptr);
 QString introductionText() const;
 void setIntroductionText(const QString &introductionText);
 Q_SIGNAL void introductionTextChanged();
private:
 QString m_introductionText = QStringLiteral("Hello World!");
};

src/components/backend.cpp

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


#include "backend.h"

Backend::Backend(QObject *parent)
 : QObject(parent)
{}

QString Backend::introductionText() const
{
 return m_introductionText;
}

void Backend::setIntroductionText(const QString &introductionText)
{
 m_introductionText = introductionText;
 Q_EMIT introductionTextChanged();
}

src/components/ExposePage.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.Page {
 title: "Exposing to QML Tutorial"
 Kirigami.Heading {
 anchors.centerIn: parent
 text: Backend.introductionText
 }
}

الآن ترجم وابدأ برنامجك مرة أخرى. سترى أن الصفحة الجديدة تحتوي على عنوان وسطي يقول "مرحبًا بالعالم!".

تهانينا، تعلمت:

كيف تسجل أنواع الخلفية إلى QML
أضف عناصر جديدة إلى ملف QML
أنشئ صفوفًا فرعية جديدة من QObject
كيف تضيف خصائص وماذا تفعل
ما هي الإشارات

إذا أردت معرفة المزيد عن التكامل بين QML و C++، نوصي بقراءة وثائق Qt الرسمية.

Docs: اربط نماذج C++ بواجهة مستخدم QML الخاصة بك

Mon, 01 Jan 0001 00:00:00 +0000

كما هو موضح في الدرس السابق، يمكنك وصل كود C++ بـ QML بإنشاء صف سيُعامل كمكون آخر في QML. لكن قد ترغب في تمثيل بيانات أكثر تعقيدًا، مثل بيانات تحتاج إلى العمل كنموذج قائمة ListModel مخصص أو تحتاج بطريقة ما إلى التفويض من Repeater.

يمكننا إنشاء نماذج خاصة بنا من جانب C++، وتصريح كيف ينبغي تمثيل البيانات من ذلك النموذج على الواجهة الأمامية لـ QML.

يُوصى بشدة بقراءة البرنامج التعليمي طرق عرض القوائم قبل هذا البرنامج.

سيعتمد الكود المستخدم في هذا البرنامج التعليمي على الصفحة السابقة، اربط المنطق بواجهة مستخدم QML الخاصة بك.

هيكل المشروع

kirigami-tutorial/
├── CMakeLists.txt --------------------- # Modified for didactic purposes
├── org.kde.tutorial.desktop
└── src/
├── CMakeLists.txt
├── main.cpp
├── Main.qml ----------------------- # Modified
└── components/
├── CMakeLists.txt ------------- # Modified
├── AddDialog.qml
├── KountdownDelegate.qml
├── ExposePage.qml
├── ModelsPage.qml ------------- # New
├── model.h -------------------- # New
├── model.cpp ------------------ # New
├── backend.h
└── backend.cpp

إنشاء صفحة جديدة للبرنامج التعليمي للنماذج

قبل فعل أي شيء، لنُضِف صفحة جديدة إلى كود QML الخاص بنا.

أولاً، في src/Main.qml، أضِف الإجراء التالي إلى الدرج العام:

15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Exposing to QML")
 icon.name: "kde"
 onTriggered: pageStack.push(Qt.createComponent("org.kde.tutorial.components", "ExposePage"))
 },
 Kirigami.Action {
 text: i18n("C++ models in QML")
 icon.name: "kde"
 onTriggered: pageStack.push(Qt.createComponent("org.kde.tutorial.components", "ModelsPage"))
 },
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }

ثم، أنشِئ ملفًا جديدًا src/components/ModelsPage.qml بالمحتويات التالية:

1
2
3
4
5
6
7
8
9


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ScrollablePage {
 title: "C++ models in QML"
 // ...
}

وأخيرًا، أضِفه إلى src/components/CMakeLists.txt:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


add_library(kirigami-hello-components)

ecm_add_qml_module(kirigami-hello-components
 URI "org.kde.tutorial.components"
 GENERATE_PLUGIN_SOURCE
)

ecm_target_qml_sources(kirigami-hello-components
 SOURCES
 AddDialog.qml
 KountdownDelegate.qml
 ExposePage.qml
 ModelsPage.qml
)

target_sources(kirigami-hello-components
 PRIVATE
 backend.cpp backend.h
)

ecm_finalize_qml_module(kirigami-hello-components)

install(TARGETS kirigami-hello-components ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

سيكون هذا بمثابة اللوحة لصفحة هذا البرنامج التعليمي.

استخدام السلاسل النصية الخام

لتسهيل فهم كيفية تعبئة النموذج في هذا البرنامج التعليمي، سنعطل ميزة تستخدمها تطبيقات كيدي التي تستخدم وحدات cmake الإضافية (ECM) افتراضيًا والتي تحسّن كود السلاسل النصية. يتيح لنا هذا تجنب كتابة QStringLiteral() في كل مرة تُقدَّم فيها سلسلة نصية في كود C++ الخاص بنا، وهو ما سيكون مفيدًا للكود في ملف الرأس القادم.

في ملف CMakeLists.txt الجذر، أضِف ما يلي:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


cmake_minimum_required(VERSION 3.20)
project(kirigami-tutorial)

find_package(ECM 6.0.0 REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)
include(ECMFindQmlModule)
include(ECMQmlModule)
remove_definitions(-DQT_NO_CAST_FROM_ASCII)

find_package(Qt6 REQUIRED COMPONENTS
 Core
 Quick
 Test
 Gui
 QuickControls2
 Widgets
)

find_package(KF6 REQUIRED COMPONENTS
 Kirigami
 I18n
 CoreAddons
 QQC2DesktopStyle
 IconThemes
)

ecm_find_qmlmodule(org.kde.kirigami REQUIRED)

add_subdirectory(src)

install(PROGRAMS org.kde.tutorial.desktop DESTINATION ${KDE_INSTALL_APPDIR})

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

🚨 لا تفعل هذا في الإنتاج

تعطيل علامة CMake هذه يتم لأغراض تعليمية فقط. يجب أن يستخدم كود الإنتاج QStringLiteral() أو مساحة أسماء حرفيات السلاسل النصية في Qt بدلاً من ذلك حيثما أمكن.

تحضير الصنف

سننشئ صنفًا يحتوي على QMap، حيث يُستخدم QString كمفتاح وكائنات QStringList كقيم. ستتمكن الواجهة الأمامية من قراءة وعرض المفاتيح والقيم وستكون بسيطة الاستخدام تمامًا مثل مصفوفة أحادية البعد. يجب أن تبدو مشابهة لـ QML ListModel.

لفعل هذا، نحتاج إلى إنشاء صنف يرث من QAbstractListModel. لنُضِف أيضًا بعض البيانات إلى QMap. ستكون هذه التصريحات موجودة في model.h.

أنشِئ ملفين جديدين، src/components/model.h و src/components/model.cpp.

أضِف هذين الملفين الجديدين إلى src/components/CMakeLists.txt:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


add_library(kirigami-hello-components)

ecm_add_qml_module(kirigami-hello-components
 URI "org.kde.tutorial.components"
 GENERATE_PLUGIN_SOURCE
)

ecm_target_qml_sources(kirigami-hello-components
 SOURCES
 AddDialog.qml
 KountdownDelegate.qml
 ExposePage.qml
 ModelsPage.qml
)

target_sources(kirigami-hello-components
 PRIVATE
 backend.cpp backend.h
 model.cpp model.h
)

ecm_finalize_qml_module(kirigami-hello-components)

install(TARGETS kirigami-hello-components ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

أضِف ما يلي كمحتويات أولية إلى src/components/model.h:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


#pragma once

#include <QAbstractListModel>
#include <qqmlintegration.h>

class Model : public QAbstractListModel {
 Q_OBJECT
 QML_ELEMENT
public:

private:
 QMap<QString, QStringList> m_list = {
 {"Feline", {"Tigress", "Waai Fuu"}},
 {"Fox", {"Carmelita", "Diane", "Krystal"}},
 {"Goat", {"Sybil", "Toriel"}}
 };
};

بالطبع، لا يمكننا عرض هذا الصنف كما هو. نحتاج أيضًا إلى إخبار QML بكيفية تمثيل هذه البيانات في الصنف. يمكننا فعل ذلك بتجاوز ثلاث دوال افتراضية أساسية:

rowCount() - اعتبر هذه الدالة وسيلة لإخبار QML بعدد العناصر التي يجب أن يعرضها النموذج.
roleNames() - يمكنك اعتبار أسماء الأدوار كأسماء خصائص مرفقة بالبيانات في QML. تسمح لك هذه الدالة بإنشاء تلك الأدوار.
data() - تُستدعى هذه الدالة عندما تريد استرداد البيانات التي تتوافق مع أسماء الأدوار من النموذج.

ملاحظة

أسماء الأدوار المخصصة التي أنشأتها roleNames() قابلة للاستخدام فقط عندما يكون النموذج مفوضًا، وغير قابلة للاستخدام خارجه. انظر النماذج وطرق العرض.

ملاحظة

من الناحية التقنية، يتم تمثيل النماذج في Qt كجداول، بصفوف وأعمدة. لذا، ما يفعله تجاوز rowCount() هو إخبار Qt بعدد الصفوف في النموذج. وبما أننا نتعامل فقط مع مصفوفة أحادية البعد في هذا البرنامج التعليمي، يمكنك فقط اعتبار "الصفوف" على أنها "عدد العناصر."

تجاوز وتنفيذ `rowCount()`

لنتجاوز الدالة في ملف الرأس src/components/model.h. تأتي دالة rowCount() مع معاملها الخاص، لكنه لن يُستخدم في هذا المثال ولذا لا يحتاج إلى تسمية.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


#pragma once

#include <QAbstractListModel>
#include <qqmlintegration.h>

class Model : public QAbstractListModel {
 Q_OBJECT
 QML_ELEMENT
public:
 int rowCount(const QModelIndex &) const override;

private:
 QMap<QString, QStringList> m_list = {
 {"Feline", {"Tigress", "Waai Fuu"}},
 {"Fox", {"Carmelita", "Diane", "Krystal"}},
 {"Goat", {"Sybil", "Toriel"}}
 };
};

ثم، لنُصرِّح بعدد الصفوف في هذا النموذج في src/components/model.cpp:

1
2
3
4
5


#include "model.h"

int Model::rowCount(const QModelIndex &) const {
 return m_list.count();
}

تجاوز وتنفيذ `roleNames()`

قبل أن نتجاوز roleNames()، نحتاج إلى تصريح ما هي الأدوار في جانب C++ باستخدام تعداد عام. السبب في ذلك هو أن قيم التعداد هذه تُمرر إلى data() في كل مرة يصل فيها QML إلى دور مقابل، وبالتالي يمكننا جعل data() تُرجع ما نريد.

لنبدأ بإنشاء التعداد للأدوار في src/components/model.h، حيث كل قيمة هي دور لجانب C++.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


#pragma once

#include <QAbstractListModel>
#include <qqmlintegration.h>

class Model : public QAbstractListModel {
 Q_OBJECT
 QML_ELEMENT
public:
 enum Roles {
 SpeciesRole = Qt::UserRole,
 CharactersRole
 };

 QHash<int, QByteArray> roleNames() const override;
 int rowCount(const QModelIndex &) const override;

private:
 QMap<QString, QStringList> m_list = {
 {"Feline", {"Tigress", "Waai Fuu"}},
 {"Fox", {"Carmelita", "Diane", "Krystal"}},
 {"Goat", {"Sybil", "Toriel"}}
 };
};

بمجرد أن نستقر على ذلك، يمكننا أخيرًا إنشاء ما هي هذه الأدوار في جانب QML باستخدام QHash حيث المفاتيح هي القيم المعدودة مقترنة بـ QByteArrays. يجب أن يذهب هذا إلى src/components/model.cpp. النص في QByteArray هو ما يُستخدم في كود QML الفعلي.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


#include "model.h"

int Model::rowCount(const QModelIndex &) const {
 return m_list.count();
}

QHash<int, QByteArray> Model::roleNames() const {
 return {
 {SpeciesRole, "species"},
 {CharactersRole, "characters"}
 };
}

في نموذجنا المثال، يمكن استخدام الدور "species" لاسترداد مفتاح QString "Feline"، "Fox"، "Goat"، كل في مفوض منفصل. يمكن فعل الشيء نفسه مع قيم QStringList لقائمة أسماء الشخصيات.

تجاوز وتنفيذ `data()`

هناك معلمتان تُمرران إلى data(): index و role. index هو موضع البيانات في النموذج. كما ذُكر سابقًا، يُستخدم role بواسطة QML للحصول على بيانات محددة تُعاد عند الوصول إلى دور.

في data()، يمكننا استخدام جملة switch لإرجاع البيانات ونوع البيانات المناسبين اعتمادًا على الدور، وهذا ممكن لأن data() تُرجع QVariant. ما زلنا بحاجة للتأكد من الحصول على الموقع المناسب للبيانات. في هذا المثال أدناه، يمكنك رؤية أن متغير مكرر جديد يُصرح عنه، ويُضبط من بداية القائمة زائد صف الفهرس، والبيانات التي يشير إليها المكرر هي ما يُعاد.

لا يمكننا فقط إرجاع أي بيانات نريدها. قد نحاول ربط بيانات بخاصية بنوع بيانات غير متوافق، مثل QStringList إلى QString. قد تضطر لإجراء تحويل بيانات لكي تُعرض البيانات بشكل صحيح. لهذا، ننشئ دالة خاصة ثابتة جديدة باسم formatList().

ينتج عن هذا الكود التالي في src/components/model.cpp:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


#include "model.h"

int Model::rowCount(const QModelIndex &) const {
 return m_list.count();
}

QHash<int, QByteArray> Model::roleNames() const {
 return {
 {SpeciesRole, "species"},
 {CharactersRole, "characters"}
 };
}

QVariant Model::data(const QModelIndex &index, int role) const {
 const auto it = std::next(m_list.begin(), index.row());
 switch (role) {
 case SpeciesRole:
 return it.key();
 case CharactersRole:
 return formatList(it.value());
 default:
 return {};
 }
}

QString Model::formatList(const QStringList& list) {
 QString result;
 for (const QString& character : list) {
 result += character;
 if (list.last() != character) {
 result += ", ";
 }
 }
 return result;
}

والكود التالي في src/components/model.h:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


#pragma once

#include <QAbstractListModel>
#include <qqmlintegration.h>

class Model : public QAbstractListModel {
 Q_OBJECT
 QML_ELEMENT
public:
 enum Roles {
 SpeciesRole = Qt::UserRole,
 CharactersRole
 };
 int rowCount(const QModelIndex &) const override;
 QHash<int, QByteArray> roleNames() const override;
 QVariant data(const QModelIndex &index, int role) const override;

private:
 QMap<QString, QStringList> m_list = {
 {"Feline", {"Tigress", "Waai Fuu"}},
 {"Fox", {"Carmelita", "Diane", "Krystal"}},
 {"Goat", {"Sybil", "Toriel"}}
 };
 static QString formatList(const QStringList& list);
};

استخدام الصنف في QML

ملف QML المستخدم سيحتوي فقط على ثلاثة مكونات Kirigami.AbstractCard، حيث المفتاح هو الرأس والقيمة هي المحتوى. تُنشأ هذه البطاقات بتفويض AbstractCard باستخدام Repeater، حيث يعمل النموذج المخصص الذي أنشأناه كنموذج. تُوصل البيانات باستخدام كلمة model، متبوعة بالأدوار التي أعلناها في roleNames().

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ScrollablePage {
 title: "C++ models in QML"
 Model {
 id: customModel
 }
 ColumnLayout {
 anchors.left: parent.left
 anchors.right: parent.right
 Repeater {
 model: customModel
 delegate: Kirigami.AbstractCard {
 header: Kirigami.Heading {
 text: model.species
 level: 2
 }
 contentItem: Controls.Label {
 text: model.characters
 }
 }
 }
 }
}

تعديل البيانات

تحرير البيانات باستخدام `dataChanged()` و `setData()`

قد تواجه موقفًا تريد فيه تعديل البيانات في النموذج، وأن تنعكس التغييرات على جانب الواجهة الأمامية. كل مرة نغير فيها البيانات في النموذج، يجب أن نُصدر إشارة dataChanged() التي ستطبق تلك التغييرات على جانب الواجهة الأمامية في الخلايا المحددة في وسائطها. في هذا الدليل، يمكننا فقط استخدام وسيطة index لـ setData().

setData() هي دالة افتراضية يمكنك تجاوزها بحيث أن تعديل البيانات من جانب الواجهة الأمامية يعكس تلقائيًا تلك التغييرات على جانب الخلفية. تتطلب ثلاث معاملات:

index - موقع البيانات.
value - محتويات البيانات الجديدة.
role - في هذا السياق، يُستخدم الدور هنا لإخبار العروض كيف يجب أن تتعامل مع البيانات. يجب أن يكون الدور هنا Qt::EditRole.

معامل role في هذه الحالة يُستخدم لضمان أن setData() يمكن تحريرها عبر إدخال المستخدم (Qt::EditRole). باستخدام index، يمكننا استخدام ذلك لتحديد موقع حيث يجب تحرير البيانات بمحتويات value.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


#include "model.h"

int Model::rowCount(const QModelIndex &) const {
 return m_list.count();
}

QHash<int, QByteArray> Model::roleNames() const {
 return {
 {SpeciesRole, "species"},
 {CharactersRole, "characters"}
 };
}

QVariant Model::data(const QModelIndex &index, int role) const {
 const auto it = std::next(m_list.begin(), index.row());
 switch (role) {
 case SpeciesRole:
 return it.key();
 case CharactersRole:
 return formatList(it.value());
 default:
 return {};
 }
}

QString Model::formatList(const QStringList& list) {
 QString result;
 for (const QString& character : list) {
 result += character;
 if (list.last() != character) {
 result += ", ";
 }
 }
 return result;
}

bool Model::setData(const QModelIndex &index, const QVariant &value, int role) {
 if (!value.canConvert<QString>() && role != Qt::EditRole) {
 return false;
 }

 auto it = std::next(m_list.begin(), index.row());
 QString charactersUnformatted = value.toString();
 QStringList characters = charactersUnformatted.split(", ");

 m_list[it.key()] = characters;
 Q_EMIT dataChanged(index, index);

 return true;
}

ملاحظة

setData() لا تُصدر تلقائيًا dataChanged() ويجب فعل ذلك يدويًا.

مع الإضافة المقابلة في src/components/model.h:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


#pragma once

#include <QAbstractListModel>
#include <qqmlintegration.h>

class Model : public QAbstractListModel {
 Q_OBJECT
 QML_ELEMENT
public:
 enum Roles {
 SpeciesRole = Qt::UserRole,
 CharactersRole
 };
 int rowCount(const QModelIndex &) const override;
 QHash<int, QByteArray> roleNames() const override;
 QVariant data(const QModelIndex &index, int role) const override;
 bool setData(const QModelIndex &index, const QVariant &value, int role) override;
private:
 QMap<QString, QStringList> m_list = {
 {"Feline", {"Tigress", "Waai Fuu"}},
 {"Fox", {"Carmelita", "Diane", "Krystal"}},
 {"Goat", {"Sybil", "Toriel"}}
 };
 static QString formatList(const QStringList& list);
};

لنحدث كود QML بحيث يمكننا فتح موجه يسمح لنا بتحرير النموذج باستخدام Controls.Button ملحق بالبطاقات.

أضف التالي Kirigami.PromptDialog إلى src/components/ModelsPage.qml، مع زر تحرير جديد:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.ScrollablePage {
 title: "C++ models in QML"
 Model {
 id: customModel
 }
 ColumnLayout {
 anchors.left: parent.left
 anchors.right: parent.right
 Repeater {
 model: customModel
 delegate: Kirigami.AbstractCard {
 Layout.fillHeight: true
 header: Kirigami.Heading {
 text: model.species
 level: 2
 }
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 ColumnLayout {
 id: delegateLayout
 Controls.Label {
 text: model.characters
 }
 Controls.Button {
 text: "Edit"
 onClicked: {
 editPrompt.text = model.characters;
 editPrompt.model = model;
 editPrompt.open();
 }
 }
 }
 }
 }
 }
 }
 Kirigami.PromptDialog {
 id: editPrompt
 property var model
 property alias text: editPromptText.text
 title: "Edit Characters"
 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 onAccepted: {
 const model = editPrompt.model;
 model.characters = editPromptText.text;
 editPrompt.close();
 }
 Controls.TextField {
 id: editPromptText
 onAccepted: editPrompt.accept()
 }
 }
}

الآن، كلما تغيرت قيم النموذج في الواجهة الأمامية، يجب أن تُحدث التغييرات تلقائيًا في الخلفية.

إضافة صفوف

أضفنا طريقة لتعديل البيانات في المفاتيح الموجودة لـ QMap، وفي الواجهة الأمامية، ينعكس هذا كتعديل المحتويات داخل AbstractCards. لكن ماذا لو احتجنا لإضافة إدخال مفتاح جديد في QMap وجعل ذلك ينعكس على جانب QML؟ لنفعل هذا بإنشاء طريقة جديدة قابلة للاستدعاء على جانب QML لأداء هذه المهمة.

لجعل الطريقة مرئية في QML، يجب أن نبدأ تعريف الطريقة بماكرو Q_INVOKABLE. ستتضمن هذه الطريقة أيضًا معامل سلسلة نصية، والذي يُقصد به أن يكون المفتاح الجديد في QMap.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


#pragma once

#include <QAbstractListModel>
#include <qqmlintegration.h>

class Model : public QAbstractListModel {
 Q_OBJECT
 QML_ELEMENT
public:
 enum Roles {
 SpeciesRole = Qt::UserRole,
 CharactersRole
 };
 int rowCount(const QModelIndex &) const override;
 QHash<int, QByteArray> roleNames() const override;
 QVariant data(const QModelIndex &index, int role) const override;
 Q_INVOKABLE void addSpecies(const QString &species);

private:
 QMap<QString, QStringList> m_list = {
 {"Feline", {"Tigress", "Waai Fuu"}},
 {"Fox", {"Carmelita", "Diane", "Krystal"}},
 {"Goat", {"Sybil", "Toriel"}}
 };
 static QString formatList(const QStringList& list);
};

داخل هذه الطريقة، نحتاج إلى إخبار كيوت بأننا نريد إنشاء المزيد من الصفوف في النموذج. يُفعل ذلك باستدعاء beginInsertRows() لبدء عملية إضافة الصفوف، يليه إدراج ما نحتاجه، ثم استخدام endInsertRows() لإنهاء العملية. ومع ذلك، لا يزال يتعين علينا إصدار dataChanged() في النهاية. هذه المرة، سنقوم بتحديث جميع الصفوف، من الصف الأول إلى الأخير، لأن QMap قد يعيد تنظيم نفسه أبجديًا، ونحتاج إلى التقاط ذلك عبر جميع الصفوف.

عند استدعاء beginInsertRows()، نحتاج أولاً إلى تمرير فئة QModelIndex لتحديد موقع إضافة الصفوف الجديدة، يليه ما سيكون عليه رقما الصف الأول والأخير الجديدان. في هذا الدليل، ستكون الوسيطة الأولى مجرد QModelIndex() حيث لا حاجة لاستخدام المعامل هنا. يمكننا فقط استخدام حجم الصف الحالي لرقمي الصف الأول والأخير، لأننا سنضيف صفًا واحدًا فقط في نهاية النموذج.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57


#include "model.h"

int Model::rowCount(const QModelIndex &) const {
 return m_list.count();
}

QHash<int, QByteArray> Model::roleNames() const {
 return {
 {SpeciesRole, "species"},
 {CharactersRole, "characters"}
 };
}

QVariant Model::data(const QModelIndex &index, int role) const {
 const auto it = std::next(m_list.begin(), index.row());
 switch (role) {
 case SpeciesRole:
 return it.key();
 case CharactersRole:
 return formatList(it.value());
 default:
 return {};
 }
}

QString Model::formatList(const QStringList& list) {
 QString result;
 for (const QString& character : list) {
 result += character;
 if (list.last() != character) {
 result += ", ";
 }
 }
 return result;
}

bool Model::setData(const QModelIndex &index, const QVariant &value, int role) {
 if (!value.canConvert<QString>() && role != Qt::EditRole) {
 return false;
 }

 auto it = std::next(m_list.begin(), index.row());
 QString charactersUnformatted = value.toString();
 QStringList characters = charactersUnformatted.split(", ");

 m_list[it.key()] = characters;
 Q_EMIT dataChanged(index, index);

 return true;
}

void Model::addSpecies(const QString& species) {
 beginInsertRows(QModelIndex(), m_list.size() - 1, m_list.size() - 1);
 m_list.insert(species, {});
 endInsertRows();
 Q_EMIT dataChanged(index(0), index(m_list.size() - 1));
}

ملاحظة

تستخدم دالة dataChanged() QModelIndex كنوع بيانات لمعاملاتها. ومع ذلك، يمكننا تحويل الأعداد الصحيحة إلى أنواع بيانات QModelIndex باستخدام دالة index().

لنقم بتحديث كود QML لنمنح القدرة على إضافة مفتاح جديد إلى QMap.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.ScrollablePage {
 title: "C++ models in QML"
 actions: [
 Kirigami.Action {
 icon.name: "list-add-symbolic"
 text: "Add New Species"
 onTriggered: {
 addPrompt.open();
 }
 }
 ]
 Model {
 id: customModel
 }
 ColumnLayout {
 // ...
 }
 Kirigami.PromptDialog {
 id: addPrompt
 title: "Add New Species"
 standardButtons: Kirigami.Dialog.Ok
 onAccepted: {
 customModel.addSpecies(addPromptText.text);
 addPromptText.text = ""; // Clear TextField every time it's done
 addPrompt.close();
 }
 Controls.TextField {
 id: addPromptText
 Layout.fillWidth: true
 onAccepted: addPrompt.accept()
 }
 }
 Kirigami.PromptDialog {
 id: editPrompt
 // ...
 }
}

الآن، يجب أن يُمنحنا إجراء جديد في أعلى التطبيق يعرض موجهًا يسمح بإضافة عنصر جديد إلى النموذج، مع بياناتنا المخصصة.

إزالة الصفوف

طريقة إزالة الصفوف مشابهة لإضافة الصفوف. لننشئ طريقة أخرى سنستدعيها في QML. هذه المرة، سنستخدم معاملًا إضافيًا، وهو عدد صحيح يمثل رقم الصف. يُستخدم اسم النوع لحذف المفتاح من QMap، بينما يُستخدم رقم الصف لحذف الصف في الواجهة الأمامية.

أضف دالة Q_INVOKABLE جديدة باسم deleteSpecies() في src/components/model.h:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


#pragma once

#include <QAbstractListModel>
#include <qqmlintegration.h>

class Model : public QAbstractListModel {
 Q_OBJECT
 QML_ELEMENT
public:
 enum Roles {
 SpeciesRole = Qt::UserRole,
 CharactersRole
 };
 int rowCount(const QModelIndex &) const override;
 QHash<int, QByteArray> roleNames() const override;
 QVariant data(const QModelIndex &index, int role) const override;
 Q_INVOKABLE void addSpecies(const QString &species);
 Q_INVOKABLE void deleteSpecies(const QString &speciesName, const int &rowIndex);

private:
 QMap<QString, QStringList> m_list = {
 {"Feline", {"Tigress", "Waai Fuu"}},
 {"Fox", {"Carmelita", "Diane", "Krystal"}},
 {"Goat", {"Sybil", "Toriel"}}
 };
 static QString formatList(const QStringList& list);
};

مع تطبيق مطابق في src/components/model.cpp:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64


#include "model.h"

int Model::rowCount(const QModelIndex &) const {
 return m_list.count();
}

QHash<int, QByteArray> Model::roleNames() const {
 return {
 {SpeciesRole, "species"},
 {CharactersRole, "characters"}
 };
}

QVariant Model::data(const QModelIndex &index, int role) const {
 const auto it = std::next(m_list.begin(), index.row());
 switch (role) {
 case SpeciesRole:
 return it.key();
 case CharactersRole:
 return formatList(it.value());
 default:
 return {};
 }
}

QString Model::formatList(const QStringList& list) {
 QString result;
 for (const QString& character : list) {
 result += character;
 if (list.last() != character) {
 result += ", ";
 }
 }
 return result;
}

bool Model::setData(const QModelIndex &index, const QVariant &value, int role) {
 if (!value.canConvert<QString>() && role != Qt::EditRole) {
 return false;
 }

 auto it = std::next(m_list.begin(), index.row());
 QString charactersUnformatted = value.toString();
 QStringList characters = charactersUnformatted.split(", ");

 m_list[it.key()] = characters;
 Q_EMIT dataChanged(index, index);

 return true;
}

void Model::addSpecies(const QString& species) {
 beginInsertRows(QModelIndex(), m_list.size() - 1, m_list.size() - 1);
 m_list.insert(species, {});
 endInsertRows();
 Q_EMIT dataChanged(index(0), index(m_list.size() - 1));
}

void Model::deleteSpecies(const QString &speciesName, const int& rowIndex) {
 beginRemoveRows(QModelIndex(), rowIndex, rowIndex);
 m_list.remove(speciesName);
 endRemoveRows();
 Q_EMIT dataChanged(index(0), index(m_list.size() - 1));
}

الآن، لنقم بتحديث التطبيق ليظهر زر "حذف" في RowLayout بجانب زر التحرير داخل AbstractCard، وربطه بطريقة الحذف لدينا.

24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60


 Repeater {
 model: customModel
 delegate: Kirigami.AbstractCard {
 Layout.fillHeight: true
 header: Kirigami.Heading {
 text: model.species
 level: 2
 }
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 ColumnLayout {
 id: delegateLayout
 Controls.Label {
 text: model.characters
 }
 RowLayout {
 Layout.fillWidth: true
 Controls.Button {
 text: "Edit"
 onClicked: {
 editPrompt.text = model.characters;
 editPrompt.model = model;
 editPrompt.open();
 }
 }
 Controls.Button {
 text: "Delete"
 onClicked: {
 customModel.deleteSpecies(model.species, index);
 }
 }
 }
 }
 }
 }
 }

تطبيقنا حتى الآن

الكود الموجود:

src/CMakeLists.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


add_executable(kirigami-hello)

ecm_add_qml_module(kirigami-hello
 URI
 org.kde.tutorial
)

target_sources(kirigami-hello
 PRIVATE
 main.cpp
)

ecm_target_qml_sources(kirigami-hello
 SOURCES
 Main.qml
)

target_link_libraries(kirigami-hello
 PRIVATE
 Qt6::Quick
 Qt6::Qml
 Qt6::Gui
 Qt6::QuickControls2
 Qt6::Widgets
 KF6::I18n
 KF6::CoreAddons
 KF6::IconThemes
 kirigami-hello-components
)

install(TARGETS kirigami-hello ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

add_subdirectory(components)

src/main.cpp

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


#include <QApplication>
#include <QQmlApplicationEngine>
#include <QtQml>
#include <QUrl>
#include <QQuickStyle>
#include <KLocalizedContext>
#include <KLocalizedString>
#include <KIconTheme>

int main(int argc, char *argv[])
{
 KIconTheme::initTheme();
 QApplication app(argc, argv);
 KLocalizedString::setApplicationDomain("tutorial");
 QApplication::setOrganizationName(QStringLiteral("KDE"));
 QApplication::setOrganizationDomain(QStringLiteral("kde.org"));
 QApplication::setApplicationName(QStringLiteral("Kirigami Tutorial"));
 QApplication::setDesktopFileName(QStringLiteral("org.kde.tutorial"));

 QApplication::setStyle(QStringLiteral("breeze"));
 if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE")) {
 QQuickStyle::setStyle(QStringLiteral("org.kde.desktop"));
 }

 QQmlApplicationEngine engine;

 engine.rootContext()->setContextObject(new KLocalizedContext(&engine));
 engine.loadFromModule("org.kde.tutorial", "Main");

 if (engine.rootObjects().isEmpty()) {
 return -1;
 }

 return app.exec();
}

src/components/KountdownDelegate.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.AbstractCard {
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2

 Kirigami.Heading {
 level: 1
 text: i18n("%1 days", Math.round((date-Date.now())/86400000))
 }

 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }
 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }
 Controls.Label {
 Layout.fillWidth: true
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: i18n("Edit")
 }
 }
 }
}

src/components/AddDialog.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.Dialog {
 id: addDialog
 title: i18nc("@title:window", "Add kountdown")
 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 padding: Kirigami.Units.largeSpacing
 preferredWidth: Kirigami.Units.gridUnit * 20

 Kirigami.FormLayout {
 Controls.TextField {
 id: nameField
 Kirigami.FormData.label: i18nc("@label:textbox", "Name*:")
 onAccepted: descriptionField.forceActiveFocus()
 }
 Controls.TextField {
 id: descriptionField
 Kirigami.FormData.label: i18nc("@label:textbox", "Description:")
 onAccepted: dateField.forceActiveFocus()
 }
 Controls.TextField {
 id: dateField
 Kirigami.FormData.label: i18nc("@label:textbox", "ISO Date*:")
 inputMask: "D999-99-99"
 onAccepted: addDialog.accepted()
 }
 Controls.Label {
 text: "* = required fields"
 }
 }
 Component.onCompleted: {
 const button = standardButton(Kirigami.Dialog.Ok);
 button.enabled = Qt.binding( () => requiredFieldsFilled() );
 }
 onAccepted: {
 if (!addDialog.requiredFieldsFilled()) return;
 appendDataToModel();
 clearFieldsAndClose();
 }
 function requiredFieldsFilled() {
 return (nameField.text !== "" && dateField.acceptableInput);
 }
 function appendDataToModel() {
 kountdownModel.append({
 name: nameField.text,
 description: descriptionField.text,
 date: new Date(dateField.text)
 });
 }
 function clearFieldsAndClose() {
 nameField.text = ""
 descriptionField.text = ""
 dateField.text = ""
 addDialog.close();
 }
}

src/components/ExposePage.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.Page {
 title: "Exposing to QML Tutorial"
 Kirigami.Heading {
 anchors.centerIn: parent
 text: Backend.introductionText
 }
}

src/components/backend.h

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


#pragma once

#include <QObject>
#include <qqmlintegration.h>

class Backend : public QObject
{
 Q_OBJECT
 QML_ELEMENT
 QML_SINGLETON
 Q_PROPERTY(QString introductionText READ introductionText WRITE setIntroductionText NOTIFY introductionTextChanged)
public:
 explicit Backend(QObject *parent = nullptr);
 QString introductionText() const;
 void setIntroductionText(const QString &introductionText);
 Q_SIGNAL void introductionTextChanged();
private:
 QString m_introductionText = QStringLiteral("Hello World!");
};

src/components/backend.cpp

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


#include "backend.h"

Backend::Backend(QObject *parent)
 : QObject(parent)
{}

QString Backend::introductionText() const
{
 return m_introductionText;
}

void Backend::setIntroductionText(const QString &introductionText)
{
 m_introductionText = introductionText;
 Q_EMIT introductionTextChanged();
}

الكود المكتوب/المعدل في هذه الصفحة:

CMakeLists.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


cmake_minimum_required(VERSION 3.20)
project(kirigami-tutorial)

find_package(ECM 6.0.0 REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)
include(ECMFindQmlModule)
include(ECMQmlModule)
remove_definitions(-DQT_NO_CAST_FROM_ASCII)

find_package(Qt6 REQUIRED COMPONENTS
 Core
 Quick
 Test
 Gui
 QuickControls2
 Widgets
)

find_package(KF6 REQUIRED COMPONENTS
 Kirigami
 I18n
 CoreAddons
 QQC2DesktopStyle
 IconThemes
)

ecm_find_qmlmodule(org.kde.kirigami REQUIRED)

add_subdirectory(src)

install(PROGRAMS org.kde.tutorial.desktop DESTINATION ${KDE_INSTALL_APPDIR})

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

src/Main.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.ApplicationWindow {
 id: root

 width: 600
 height: 400

 title: i18nc("@title:window", "Day Kountdown")

 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Exposing to QML Tutorial")
 icon.name: "kde"
 onTriggered: pageStack.push(Qt.createComponent("org.kde.tutorial.components", "ExposePage"))
 },
 Kirigami.Action {
 text: i18n("C++ models in QML tutorial")
 icon.name: "kde"
 onTriggered: pageStack.push(Qt.createComponent("org.kde.tutorial.components", "ModelsPage"))
 },
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }

 ListModel {
 id: kountdownModel
 }

 AddDialog {
 id: addDialog
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")

 actions: [
 Kirigami.Action {
 id: addAction
 icon.name: "list-add-symbolic"
 text: i18nc("@action:button", "Add kountdown")
 onTriggered: addDialog.open()
 }
 ]

 Kirigami.CardsListView {
 id: cardsView
 model: kountdownModel
 delegate: KountdownDelegate {}
 }
 }
}

src/components/CMakeLists.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


add_library(kirigami-hello-components)

ecm_add_qml_module(kirigami-hello-components
 URI "org.kde.tutorial.components"
 GENERATE_PLUGIN_SOURCE
)

ecm_target_qml_sources(kirigami-hello-components
 SOURCES
 AddDialog.qml
 KountdownDelegate.qml
 ExposePage.qml
 ModelsPage.qml
)

target_sources(kirigami-hello-components
 PRIVATE
 backend.cpp backend.h
 model.cpp model.h
)

ecm_finalize_qml_module(kirigami-hello-components)

install(TARGETS kirigami-hello-components ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

src/components/ModelsPage.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.ScrollablePage {
 title: "C++ models in QML"
 actions: [
 Kirigami.Action {
 icon.name: "list-add-symbolic"
 text: "Add New Species"
 onTriggered: {
 addPrompt.open();
 }
 }
 ]
 Model {
 id: customModel
 }
 ColumnLayout {
 anchors.left: parent.left
 anchors.right: parent.right
 Repeater {
 model: customModel
 delegate: Kirigami.AbstractCard {
 Layout.fillHeight: true
 header: Kirigami.Heading {
 text: model.species
 level: 2
 }
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 ColumnLayout {
 id: delegateLayout
 Controls.Label {
 text: model.characters
 }
 RowLayout {
 Layout.fillWidth: true
 Controls.Button {
 text: "Edit"
 onClicked: {
 editPrompt.text = model.characters;
 editPrompt.model = model;
 editPrompt.open();
 }
 }
 Controls.Button {
 text: "Delete"
 onClicked: {
 customModel.deleteSpecies(model.species, index);
 }
 }
 }
 }
 }
 }
 }
 }
 Kirigami.PromptDialog {
 id: addPrompt
 title: "Add New Species"
 standardButtons: Kirigami.Dialog.Ok
 onAccepted: {
 customModel.addSpecies(addPromptText.text);
 addPromptText.text = ""; // Clear TextField every time it's done
 addPrompt.close();
 }
 Controls.TextField {
 id: addPromptText
 Layout.fillWidth: true
 onAccepted: addPrompt.accept()
 }
 }

 Kirigami.PromptDialog {
 id: editPrompt
 property var model
 property alias text: editPromptText.text
 title: "Edit Characters"
 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 onAccepted: {
 const model = editPrompt.model;
 model.characters = editPromptText.text;
 editPrompt.close();
 }
 Controls.TextField {
 id: editPromptText
 onAccepted: editPrompt.accept()
 }
 }
}

src/components/model.h

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


#pragma once

#include <QAbstractListModel>
#include <qqmlintegration.h>

class Model : public QAbstractListModel {
 Q_OBJECT
 QML_ELEMENT
public:
 enum Roles {
 SpeciesRole = Qt::UserRole,
 CharactersRole
 };
 int rowCount(const QModelIndex &) const override;
 QHash<int, QByteArray> roleNames() const override;
 QVariant data(const QModelIndex &index, int role) const override;
 bool setData(const QModelIndex &index, const QVariant &value, int role) override;
 Q_INVOKABLE void addSpecies(const QString &species);
 Q_INVOKABLE void deleteSpecies(const QString &speciesName, const int &rowIndex);
private:
 QMap<QString, QStringList> m_list = {
 {"Feline", {"Tigress", "Waai Fuu"}},
 {"Fox", {"Carmelita", "Diane", "Krystal"}},
 {"Goat", {"Sybil", "Toriel"}}
 };
 static QString formatList(const QStringList& list);
};

src/components/model.cpp

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64


#include "model.h"

int Model::rowCount(const QModelIndex &) const {
 return m_list.count();
}

QHash<int, QByteArray> Model::roleNames() const {
 return {
 {SpeciesRole, "species"},
 {CharactersRole, "characters"}
 };
}

QVariant Model::data(const QModelIndex &index, int role) const {
 const auto it = std::next(m_list.begin(), index.row());
 switch (role) {
 case SpeciesRole:
 return it.key();
 case CharactersRole:
 return formatList(it.value());
 default:
 return {};
 }
}

QString Model::formatList(const QStringList& list) {
 QString result;
 for (const QString& character : list) {
 result += character;
 if (list.last() != character) {
 result += ", ";
 }
 }
 return result;
}

bool Model::setData(const QModelIndex &index, const QVariant &value, int role) {
 if (!value.canConvert<QString>() && role != Qt::EditRole) {
 return false;
 }

 auto it = std::next(m_list.begin(), index.row());
 QString charactersUnformatted = value.toString();
 QStringList characters = charactersUnformatted.split(", ");

 m_list[it.key()] = characters;
 Q_EMIT dataChanged(index, index);

 return true;
}

void Model::addSpecies(const QString& species) {
 beginInsertRows(QModelIndex(), m_list.size() - 1, m_list.size() - 1);
 m_list.insert(species, {});
 endInsertRows();
 Q_EMIT dataChanged(index(0), index(m_list.size() - 1));
}

void Model::deleteSpecies(const QString &speciesName, const int& rowIndex) {
 beginRemoveRows(QModelIndex(), rowIndex, rowIndex);
 m_list.remove(speciesName);
 endRemoveRows();
 Q_EMIT dataChanged(index(0), index(m_list.size() - 1));
}

مزيد من المعلومات

لمزيد من المعلومات، انظر استخدام نماذج C++ مع عروض Qt Quick و برمجة النموذج/العرض.

Docs: مقدمة إلى إضافات Kirigami

Mon, 01 Jan 0001 00:00:00 +0000

ملحقات كيريغامي هي مجموعة إضافية من المكونات البصرية التي تعمل بشكل جيد على الجوال والحاسوب المكتبي ومضمونة أن تكون عبر المنصات. تستخدم كيريغامي في الخلفية لإنشاء مكوناتها.

هنا ستقوم بإعداد مشروع إضافات كيريغامي الجديد الخاص بك وستتعرف على بعض المكونات المفيدة.

تستفيد هذه المكونات من مرافق التعريب في كيدي، لذا قبل البدء باستخدامها، سنحتاج إلى إعداد مشروع صغير يستخدم KLocalizedContext.

إعداد مشروعك

سيكون هيكل المشروع الأولي على النحو التالي:

addonsexample/
├── CMakeLists.txt
├── main.cpp
└── Main.qml

تلميح

يمكنك إنشاء هيكل الملفات هذا بسرعة باستخدام:

mkdir -p addonsexample/contents/ui
touch addonsexample/{CMakeLists.txt,main.cpp}
touch addonsexample/Main.qml

نبدأ باستخدام ملف CMakeLists.txt قياسي جدًا:

cmake_minimum_required(VERSION 3.20)

project(FormCardTutorial)

find_package(ECM REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECompilerSettings)
include(KDECMakeSettings)
include(ECMQmlModule)

find_package(Qt6 REQUIRED COMPONENTS
 Widgets # For QApplication
 Quick # For QML
 QuickControls2 # For QQuickStyle
)
find_package(KF6 REQUIRED COMPONENTS
 CoreAddons # For KAboutData
 I18n # For KLocalizedContext
)
qt_policy(SET QTP0001 NEW)

add_executable(addonsexample)

target_sources(addonsexample PRIVATE main.cpp)

ecm_add_qml_module(addonsexample
 GENERATE_PLUGIN_SOURCE
 URI org.kde.addonsexample
)

ecm_target_qml_sources(addonsexample SOURCES
 Main.qml
 SettingsPage.qml
 JsonAboutPage.qml
)

target_link_libraries(addonsexample PRIVATE
 Qt::Widgets
 Qt::Quick
 Qt::QuickControls2
 KF6::CoreAddons
 KF6::I18n
)

install(TARGETS addonsexample DESTINATION ${KDE_INSTALL_BINDIR})

الجزء المثير للاهتمام سيكون ملف main.cpp:

#include <QtQml>
#include <QApplication>
#include <QQmlApplicationEngine>
#include <QIcon>
#include <QQuickStyle>
#include <KAboutData>
#include <KLocalizedContext>
#include <KLocalizedString>

int main(int argCount, char* argVector[])
{
 QApplication app(argCount, argVector);
 KLocalizedString::setApplicationDomain("org.kde.addonsexample");

 KAboutData aboutData(
 QStringLiteral("addonsexample"),
 i18nc("@title:window", "Addons Example"),
 QStringLiteral("1.0"),
 i18nc("@info", "This program shows how to use Kirigami Addons"),
 KAboutLicense::GPL_V3,
 QStringLiteral("(C) 2023"),
 i18nc("@info", "Optional text shown in the About"),
 QStringLiteral("https://kde.org"));

 aboutData.addAuthor(i18nc("@info:credit", "John Doe"),
 i18nc("@info:credit", "Maintainer"));

 KAboutData::setApplicationData(aboutData);

 if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE")) {
 QQuickStyle::setStyle(QStringLiteral("org.kde.desktop"));
 }
 QApplication::setWindowIcon(QIcon::fromTheme(QStringLiteral("kde")));

 QQmlApplicationEngine engine;
 engine.rootContext()->setContextObject(new KLocalizedContext(&engine));
 engine.loadFromModule("org.kde.addonsexample", "Main");
 app.exec();
}

إذا كنت قد قرأت دليل KXmlGui أو دليل Kirigami الأخير حول صفحة حول Kirigami، فسيبدو الكثير من هذا مألوفًا لك.

ننشئ تطبيقنا ونستخدم المنشئ المبدئي لـ KAboutData لإضافة البيانات الوصفية لتطبيقنا، ونضيف أنفسنا كمؤلف، ثم نستخدم setApplicationData() لإنهاء العملية. لاحقًا، نضبط أيضًا أيقونة التطبيق التي تأتي من سمة النظام.

ثم نستخدم تعبير لامدا في qmlRegisterSingletonType() لإرسال البيانات الوصفية لتطبيقنا مباشرة إلى جانب QML، مع كشف خصائصها.

ثم ننشئ محرك QML الخاص بنا، ونضبط سياقه لاستخدام KLocalizedContext الخاص بكيدي، المستخدم لدمج السلاسل المترجمة، مع تمرير المحرك الذي أنشأناه للتو كمعامل.

نقوم ببساطة بتحميل ملف QML الخاص بنا من ملف المورد، والآن نحتاج فقط إلى الاهتمام بملف QML الأولي.

FormCard وFormButtonDelegate

فكرة تطبيقنا هي تصميم معرض إضافات Kirigami الخاص بنا، يعرض مكونات متعددة، واحد لكل صفحة. ستحتوي الصفحة الرئيسية على قائمة بسيطة من الأزرار في ColumnLayout، كل منها يفتح صفحة منفصلة.

في البداية، يجب أن يبدو ملف Main.qml الخاص بنا هكذا:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


import QtQuick
import QtQuick.Layouts

import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

import org.kde.about 1.0

Kirigami.ApplicationWindow {
 id: root
 width: 600
 height: 700

 pageStack.initialPage: Kirigami.ScrollablePage {
 ColumnLayout {
 // Our code will go here
 }
 }
}

نستخدم pageStack المفيد لضبط الصفحة الأولية على Kirigami.ScrollablePage.

بينما يمكننا استخدام FormLayout مع مكونات QtQuick Controls لتحقيق هدفنا، هنا سيتم تعريفك بـ FormCard.

الغرض الرئيسي من FormCard هو العمل كحاوية للمكونات الأخرى مع اتباع لون مختلف عن الخلفية، بطريقة مماثلة لـ Kirigami.Card، ولكن لنوافذ الإعدادات. يمكن أن يكون لديك عدة FormCards في تطبيقك للإشارة إلى أقسام مختلفة. من المتوقع أيضًا أن يكون FormCard الخاص بك ابنًا مباشرًا لـ ColumnLayout.

استيراد org.kde.kirigamiaddons.formcard يجعل جميع مكونات FormCard متاحة لملف QML الخاص بك.

سيكون لدينا قسم واحد فقط في صفحتنا الرئيسية، لذا نضيف FormCard واحدًا:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


import QtQuick
import QtQuick.Layouts

import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

import org.kde.about 1.0

Kirigami.ApplicationWindow {
 id: root
 width: 600
 height: 700

 pageStack.initialPage: Kirigami.ScrollablePage {
 ColumnLayout {
 FormCard.FormCard {
 // Our buttons will go here
 }
 }
 }
}

الشيء الرائع في FormCard هو أنه يقوم بالتخطيط التلقائي لك. بمعنى آخر، مجرد ترتيب مكوناته كافٍ للإشارة إلى موضعها داخل FormCard، ولا حاجة لـ خصائص Layout المرفقة ومن المتوقع ألا تستخدم المراسي أو الموضّعات.

يمكننا ببساطة إضافة بضعة أزرار داخل FormCard الخاص بنا:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


import QtQuick
import QtQuick.Layouts

import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

import org.kde.about 1.0

Kirigami.ApplicationWindow {
 id: root
 width: 600
 height: 700

 pageStack.initialPage: Kirigami.ScrollablePage {
 ColumnLayout {
 FormCard.FormCard {
 FormCard.FormButtonDelegate {
 id: aboutKDEButton
 icon.name: "kde"
 text: i18n("About KDE Page")
 }
 FormCard.FormButtonDelegate {
 id: aboutPageButton
 icon.name: "applications-utilities"
 text: i18n("About Addons Example")
 }
 FormCard.FormButtonDelegate {
 id: settingsButton
 icon.name: "settings-configure"
 text: i18n("Single Settings Page")
 }
 }
 }
 }
}

هذا كل شيء! الأزرار غير قابلة للاستخدام بعد، لكننا الآن جاهزون للعب بصفحات حول الخاصة بنا!

ثم نبني ونشغله على النحو التالي:

cmake -B build/ -DCMAKE_INSTALL_PREFIX=~/kde5/usr
cmake --build build/
cmake --install build/
aboutexample

لرؤية طرق أخرى لبناء تطبيقك (على سبيل المثال، على ويندوز)، راجع صفحة البدء مع Kirigami.

Docs: صفحات حول FormCard

Mon, 01 Jan 0001 00:00:00 +0000

تسمح لك بعض تلك المكونات بنسب الفضل لعملك وعمل المساهمين الآخرين في مشروعك، بالإضافة إلى ذكر الأطر المستخدمة في تطبيقك: AboutKDE و AboutPage.

حول كيدي

ينبغي أن يفتح كل زر جديد أنشأناه في الخطوة السابقة صفحة جديدة. يمكنك إضافة صفحات جديدة عن طريق إنشاء مثيلات لها كمكونات Components ثم استخدام pageStack.layers.push() لكل زر لتحميل تلك الصفحة في ملف Main.qml الخاص بنا:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


import QtQuick
import QtQuick.Layouts

import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

import org.kde.about 1.0

Kirigami.ApplicationWindow {
 id: root
 width: 600
 height: 700

 Component {
 id: aboutkde
 FormCard.AboutKDE {}
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 ColumnLayout {
 FormCard.FormCard {
 FormCard.FormButtonDelegate {
 id: aboutKDEButton
 icon.name: "kde"
 text: i18n("About KDE Page")
 onClicked: root.pageStack.layers.push(aboutkde)
 }

 FormCard.FormButtonDelegate {
 id: aboutPageButton
 icon.name: "applications-utilities"
 text: i18n("About Addons Example")
 }

 FormCard.FormButtonDelegate {
 id: settingsButton
 icon.name: "settings-configure"
 text: i18n("Single Settings Page")
 }
 }
 }
 }
}

هذا كل شيء حقاً! كل ما يلزم هو إنشاء مثيل لـ FormCard.AboutKDE. ينبغي أن ترى شيئاً كهذا بعد النقر على زر AboutKDE:

صفحة حول

AboutPage الخاصة بالتطبيق أكثر تعقيداً قليلاً، لكنها لا تزال بسيطة جداً في الاستخدام.

للحصول على صفحة حول بسيطة تستخدم البيانات المُعينة بواسطة KAboutData::setApplicationData(aboutData); في main.cpp أضف التالي إلى ملف Main.qml الخاص بك:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49


import QtQuick
import QtQuick.Layouts

import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

import org.kde.about 1.0

Kirigami.ApplicationWindow {
 id: root
 width: 600
 height: 700

 Component {
 id: aboutkde
 FormCard.AboutKDE {}
 }

 Component {
 id: aboutpage
 FormCard.AboutPage {}
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 ColumnLayout {
 FormCard.FormCard {
 FormCard.FormButtonDelegate {
 id: aboutKDEButton
 icon.name: "kde"
 text: i18n("About KDE Page")
 onClicked: root.pageStack.layers.push(aboutkde)
 }

 FormCard.FormButtonDelegate {
 id: aboutPageButton
 icon.name: "applications-utilities"
 text: i18n("About Addons Example")
 onClicked: root.pageStack.layers.push(aboutpage)
 }

 FormCard.FormButtonDelegate {
 id: settingsButton
 icon.name: "settings-configure"
 text: i18n("Single Settings Page")
 }
 }
 }
 }
}

ينبغي أن تبدو صفحة حول لتطبيقنا هكذا:

استخدام JSON بدلاً من KAboutData

بدلاً من ترك صفحة حول تحصل على المعلومات من KAboutData، من الممكن تمرير كائن JSON مباشرة. ستظل بحاجة إلى استخدام QApplication::setWindowIcon() في ملف main.cpp الخاص بك لكي يظهر أيقونة تطبيقك.

أنشئ ملف MyAboutPage.qml هكذا:

import org.kde.kirigamiaddons.formcard as FormCard
import org.kde.about

FormCard.AboutPage {
 title: i18nc("@action:button", "About")
 aboutData: {
 "displayName" : "Addons Example",
 "productName" : "",
 "componentName" : "addonsexample",
 "shortDescription" : "This program shows how to use AboutKDE and AboutPage",
 "homepage" : "https://kde.org",
 "bugAddress" : "",
 "version" : "1.0",
 "otherText" : "Optional text shown in the About",
 "authors" : [
 {
 "name" : "John Doe",
 "task" : "Maintainer",
 "emailAddress" : "",
 "webAddress" : "",
 "ocsUsername" : ""
 }
 ],
 "credits" : [],
 "translators" : [],
 "licenses" : [
 {
 "name" : "GPL v3",
 "text" : "Long license text goes here",
 "spdx" : "GPL-3.0"
 }
 ],
 "copyrightStatement" : "© 2023",
 "desktopFileName" : ""
 }

}

ثم اضبط ملف Main.qml الخاص بك ليتضمن صفحة حول الجديدة:

يحتوي كائن JSON الرئيسي هنا على المفاتيح displayName و productName و homepage وهكذا. يمكن تمرير مصفوفة من الكائنات لكل من المفاتيح authors و credits و translators و licenses. تشترك الكائنات الممررة إلى authors و credits و translators في نفس المفاتيح بحيث يمكن عرض كل منها في قسمه الخاص، بينما يتضمن licenses المفاتيح name و text و spdx لكل ترخيص مضاف، حيث أنه ليس من غير المألوف أن يتضمن نفس المشروع تراخيص متعددة.

هذه المفاتيح اختيارية، لكن يُتوقع حد أدنى معقول من المفاتيح لجعل تطبيقك لا يحتوي على حقول فارغة: displayName و version و description و homepage و copyrightStatement و authors. ومع ذلك، يُشجعك على ملء أكبر عدد ممكن من المفاتيح.

Docs: مفوضو النموذج في صفحات الإعدادات الخاصة بك

Mon, 01 Jan 0001 00:00:00 +0000

تعلمت كيفية إضافة صفحات حول وحول كيدي إلى تطبيقك. الآن ستتمكن من استخدام نفس مكوناتها الداخلية لإنشاء صفحات الإعدادات الخاصة بك.

ينبغي أن يبدو هيكل المشروع هكذا:

addonsexample
├── CMakeLists.txt
├── main.cpp
├── Main.qml
├── MyAboutPage.qml
└── SettingsPage.qml

التغييرات المطلوبة

غيّر Main.qml لتضمين صفحة الإعدادات الجديدة:

import QtQuick
import QtQuick.Layouts

import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

import org.kde.about 1.0

Kirigami.ApplicationWindow {
 id: root
 width: 600
 height: 700

 Component {
 id: aboutkde
 FormCard.AboutKDE {}
 }

 Component {
 id: aboutpage
 MyAboutPage {}
 }

 Component {
 id: settingspage
 SettingsPage {}
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 ColumnLayout {
 FormCard.FormCard {
 FormCard.FormButtonDelegate {
 id: aboutKDEButton
 icon.name: "kde"
 text: i18n("About KDE Page")
 onClicked: root.pageStack.layers.push(aboutkde)
 }

 FormCard.FormButtonDelegate {
 id: aboutPageButton
 icon.name: "applications-utilities"
 text: i18n("About Addons Example")
 onClicked: root.pageStack.layers.push(aboutpage)
 }

 FormCard.FormButtonDelegate {
 id: settingsButton
 icon.name: "settings-configure"
 text: i18n("Single Settings Page")
 onClicked: root.pageStack.layers.push(settingspage)
 }
 }
 }
 }
}

يمكننا الآن البدء في استعراض المكونات المستخدمة لإنشاء صفحة الإعدادات: بطاقة النموذج ومفوضوها.

مفوضو النموذج

FormCard و FormCardPage

FormCard.FormCard هو المكون الرئيسي الذي سنستخدمه لتجميع جميع مكوناته الفرعية، وهم المفوضون.

استخدمنا بطاقة نموذج سابقًا في مقدمة إضافات كيريغامي. غرضها الرئيسي هو العمل كحاوية للمكونات الأخرى مع اتباع لون مختلف عن الخلفية، بطريقة مماثلة لـ Kirigami.Card.

أنشئ ملفًا جديدًا باسم SettingsPage.qml:

import QtQuick
import org.kde.kirigamiaddons.formcard as FormCard

FormCard.FormCardPage {
 FormCard.FormCard {
 // هذا هو مكان وضع جميع المفوضين!
 }

 FormCard.FormCard {
 // هذا هو مكان وضع جميع المفوضين!
 }
}

بما أننا نصنع ملف QML منفصلًا لصفحة الإعدادات، وبما أننا بحاجة للاستعداد للتمرير المحتمل في صفحتنا، نستخدم FormCard.FormCardPage، والذي يرث Kirigami.ScrollablePage.

الشيء الجميل في صفحة بطاقة النموذج هو أنها تأتي بتخطيط داخلي، لذا لا حاجة لـ ColumnLayout إضافي ويمكن إضافة مفوضينا إليها مباشرة.

ملاحظة

من الممكن استخدام مفوضي FormCard مباشرة مع Kirigami.ScrollablePage، لكن في هذه الحالة ستحتاج لإضافة تخطيطاتك الخاصة.

رأس النموذج

لكل FormCard تريد إنشاءه، يمكنك إنشاء FormHeader قبله مباشرة. يستخدم الرأس نصًا عريضًا ويظهر فوق بطاقة النموذج مباشرة.

import org.kde.kirigamiaddons.formcard as FormCard

FormCard.FormCardPage {
 FormCard.FormHeader {
 title: i18n("General")
 }

 FormCard.FormCard {
 // مفوضوّنا يوضعون هنا...
 }

 FormCard.FormHeader {
 title: i18n("Accounts")
 }

 FormCard.FormCard {
 // مفوضوّنا يوضعون هنا...
 }
}

FormTextDelegate و FormSectionText

لنبدأ ببساطة، بنص عادي.

FormSectionText يضيف ببساطة مفوضًا رفيعًا يحتوي على لصيقة. FormTextDelegate يحتوي على نص ووصف باهت.

import QtQuick
import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

FormCard.FormCardPage {
 FormCard.FormHeader {
 title: i18n("General")
 }

 FormCard.FormCard {
 FormCard.FormTextDelegate {
 text: i18n("Current Color Scheme")
 description: "Breeze"
 }
 }

 FormCard.FormHeader {
 title: i18n("Accounts")
 }

 FormCard.FormCard {
 FormCard.FormSectionText {
 text: i18n("Online Account Settings")
 }
 FormCard.FormTextDelegate {
 leading: Kirigami.Icon {source: "user"}
 text: "John Doe"
 description: i18n("The Maintainer ™️")
 }
 }
}

نضيف بعض النص الوهمي للكشف الافتراضي عن السمة. إذا أردنا كشفًا فعليًا لنظام الألوان، في المستقبل يمكن فعله بشكل مشابه لـ Neochat (الكود هنا)، باستخدام نموذج C++ مع KColorSchemeManager.

في قسم الحسابات عبر الإنترنت، نرى خاصية إضافية، leading. يمكننا إضافة Item إليها ليظهر قبل النص. الخاصية المقابلة لها، trailing، ستكون قادرة على إظهار Item بعد النص، لكننا لن نستخدمها في برنامجنا.

نستخدم Kirigami.Icon هنا للبساطة، لكن يمكن أيضًا تنفيذ هذا باستخدام Avatar من إضافات كيريغامي الذي يجلب المعلومات من نموذج، كما فُعل في Neochat.

ينبغي أن يبدو شكله النهائي هكذا:

مفوّض زر النموذج

يشبه FormButtonDelegate بصريًا FormTextDelegate، لكنه قابل للنقر ويظهر سهمًا يشير إلى اليمين. استخدمناه سابقًا في مقدمة إضافات كيريغامي.

بينما كان لدى FormTextDelegate الخاصيتان leading و trailing لإظهار عنصر قبل وبعد المحتوى الرئيسي، فإن FormButtonDelegate لديه فقط الخاصية leading، لأن الجانب الأيمن مشغول بالسهم.

import QtQuick
import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

FormCard.FormCardPage {
 FormCard.FormHeader {
 title: i18n("General")
 }

 FormCard.FormCard {
 FormCard.FormTextDelegate {
 text: i18n("Current Color Scheme")
 description: "Breeze"
 }
 }

 FormCard.FormHeader {
 title: i18n("Accounts")
 }

 FormCard.FormCard {
 FormCard.FormSectionText {
 text: i18n("Online Account Settings")
 }
 FormCard.FormTextDelegate {
 leading: Kirigami.Icon {source: "user"}
 text: "John Doe"
 description: i18n("The Maintainer ™️")
 }
 FormCard.FormButtonDelegate {
 icon.name: "list-add"
 text: i18n("Add a new account")
 onClicked: console.info("Clicked!")
 }
 }
}

نستخدم خاصية icon.name لتعيين أيقونة زائد (+) لتظهر بعد المساحة التي سيظهر فيها leading، وقبل المحتوى الرئيسي. هذا نمط شائع للإشارة إلى أن زرّك سيضيف شيئًا إلى قائمة.

بما أن هذا المثال لأغراض توضيحية بسيطة، لا نتعمق في ما سيفعل عند النقر على الزر: فهو يطبع فقط "Clicked!" إلى الطرفية. يمكننا إنشاء صفحة جديدة لإنشاء حساب تضيف مستخدمًا آخر إلى نموذج، ثم دفع الصفحة إلى العرض، بشكل مشابه لما فعلناه في Main.qml.

FormRadioDelegate و FormCheckDelegate و FormSwitchDelegate

أزرار الاختيار (RadioButton) ومربعات الاختيار (CheckBox) والمفاتيح (Switch) هي مكونات شائعة الاستخدام جدًا في أي واجهة مستخدم. توفرها إضافات كيريغامي كـ FormRadioDelegate و FormCheckDelegate و FormSwitchDelegate.

خصائصها الرئيسية الوحيدة هي text و description. وهي مختلفة في الاستخدام لأنها جميعًا ترث AbstractButton، ولذا يُتوقع منك استخدام إشاراتها ومعالجاتها: checked و onChecked، toggled و onToggled، clicked و onClicked.

نريد إنشاء وظيفة حفظ آلي في تطبيقنا، ونريد إظهار إعداداتها فقط إذا فعّل المستخدم هذه الوظيفة. أنشئ قسمًا جديدًا باستخدام FormCard و FormHeader، ثم أضف FormSwitchDelegate و FormRadioDelegate.

FormCard.FormHeader {
 title: i18n("Autosave")
}

FormCard.FormCard {
 FormCard.FormSwitchDelegate {
 id: autosave
 text: i18n("Enabled")
 }
 FormCard.FormRadioDelegate {
 text: i18n("After every change")
 visible: autosave.checked
 }
 FormCard.FormRadioDelegate {
 text: i18n("Every 10 minutes")
 visible: autosave.checked
 }
 FormCard.FormRadioDelegate {
 text: i18n("Every 30 minutes")
 visible: autosave.checked
 }
}

نربط رؤية كل زر اختيار بمفتاح، فتظهر فقط عندما يكون المفتاح مفعّلاً.

أفضل الممارسات

انقر هنا لتقرأ المزيد

إذا كانت لديك خلفية برمجية في لغات أمرية مثل C++، فقد تميل إلى تعيين خاصية checked للمفتاح لجعل رؤية أزرار الاختيار true باستخدام تعيين JavaScript مثل:

checked: {
 radio1.visible = true;
 radio2.visible = true;
 radio3.visible = true;
}

هذا ليس فعالاً جدًا للغة QML التصريحية وإشاراتها ومقابسها. حاول استخدام روابط QML مثل حالة visible: autosave.checked قدر الإمكان بدلاً من تعبيرات JavaScript.

انظر هذه الصفحة للتفاصيل.

لاختبار خانة الاختيار لدينا، يمكننا إضافة FormCheckDelegate جديد إلى قسمنا العام.

FormCard.FormHeader {
 title: i18n("General")
}

FormCard.FormCard {
 FormCard.FormTextDelegate {
 text: i18n("Current Color Scheme")
 description: "Breeze"
 }
 FormCard.FormCheckDelegate {
 text: i18n("Show Tray Icon")
 onToggled: {
 if (checkState) {
 console.info("A tray icon appears on your system!")
 } else {
 console.info("The tray icon disappears!")
 }
 }
 }
}

هنا نستخدم معالج الإشارة المسمى onToggled لعرض نص وهمي لمحاكاة ظهور أيقونة علبة النظام. إذا أردت حقًا، يمكنك بسهولة تنفيذ أيقونة علبة نظام باستخدام KStatusNotifierItem من كيدي أو SystemTrayIcon من كيوت.

حتى الآن يجب أن يبدو تطبيقنا هكذا:

FormComboBoxDelegate

يمكن إنشاء المكون ComboBox الشائع باستخدام FormComboBoxDelegate.

يحتوي مربع التحرير والسرد هذا على عدة خصائص مفيدة يمكننا استخدامها: editable، و displayText، و displayMode.

تعيين editable: true يسمح للمستخدم بتحرير نص مربع التحرير والسرد، وهو مفيد في حالة الحاجة إلى إضافة خيارات جديدة لمربع التحرير والسرد:

عندما تحتاج إلى إظهار نص إضافي قبل كل خيار، يمكنك استخدام شيء مثل displayText: "Profile: " + currentText:

والأكثر إثارة للاهتمام، والذي سنستخدمه في مثالنا، هو displayMode. يمكن أن يكون له ثلاثة خيارات:

FormComboBoxDelegate.ComboBox: المربع الصغير القياسي الذي يعرض قائمة من الخيارات.

FormComboBoxDelegate.Dialog: حوار يعرض قائمة من الخيارات في منتصف النافذة، مثل Kirigami.OverlaySheet.

FormComboBoxDelegate.Page: صفحة جديدة تحتوي على قائمة من الخيارات تُعرض في نافذة منفصلة.

أضف ما يلي بين مفوضي "Current Color Scheme" و "Show Tray Icon" في بطاقة النموذج "General" الخاصة بك.

FormCard.FormComboBoxDelegate {
 text: i18n("Default Profile")
 description: i18n("The profile to be loaded by default.")
 displayMode: FormCard.FormComboBoxDelegate.ComboBox
 currentIndex: 0
 editable: false
 model: ["Work", "Personal"]
}

مع خانة الاختيار، يجب أن تبدو صفحة الإعدادات لدينا هكذا:

FormDelegateSeparator

صفحة الإعدادات لدينا تأخذ شكلها، لكن كل قسم بدأ يطول. يمكننا إضافة بضع نسخ من FormDelegateSeparator لجعل صفحتنا أكثر ترتيبًا:

import QtQuick
import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

FormCard.FormCardPage {
 id: root

 title: i18nc("@title", "Settings")

 FormCard.FormHeader {
 title: i18nc("@title:group", "General")
 }

 FormCard.FormCard {
 FormCard.FormTextDelegate {
 text: i18nc("@info", "Current Color Scheme")
 description: "Breeze"
 }

 FormCard.FormComboBoxDelegate {
 id: combobox
 text: i18nc("@label:listbox", "Default Profile")
 description: i18nc("@info:whatsthis", "The profile to be loaded by default.")
 displayMode: FormCard.FormComboBoxDelegate.ComboBox
 currentIndex: 0
 editable: false
 model: ["Work", "Personal"]
 }

 FormCard.FormDelegateSeparator {
 above: combobox
 below: checkbox
 }

 FormCard.FormCheckDelegate {
 id: checkbox
 text: i18nc("@option:check", "Show Tray Icon")
 onToggled: {
 if (checkState) {
 console.info("A tray icon appears on your system!")
 } else {
 console.info("The tray icon disappears!")
 }
 }
 }
 }

 FormCard.FormHeader {
 title: i18nc("@title:group", "Autosave")
 }

 FormCard.FormCard {
 FormCard.FormSwitchDelegate {
 id: autosave
 text: i18nc("@option:check", "Enabled")
 }
 FormCard.FormDelegateSeparator {
 above: autosave
 below: firstradio
 visible: autosave.checked
 }
 FormCard.FormRadioDelegate {
 id: firstradio
 text: i18nc("@option:radio", "After every change")
 visible: autosave.checked
 }
 FormCard.FormRadioDelegate {
 text: i18nc("@option:radio", "Every 10 minutes")
 visible: autosave.checked
 }
 FormCard.FormRadioDelegate {
 text: i18nc("@option:radio", "Every 30 minutes")
 visible: autosave.checked
 }
 }

 FormCard.FormHeader {
 title: i18nc("@title:group", "Accounts")
 }

 FormCard.FormCard {
 FormCard.FormSectionText {
 text: i18nc("@info:whatsthis", "Online Account Settings")
 }
 FormCard.FormTextDelegate {
 id: lastaccount
 leading: Kirigami.Icon {source: "user"}
 text: "John Doe"
 description: i18nc("@info:credit", "The Maintainer ™️")
 }
 FormCard.FormDelegateSeparator {
 above: lastaccount
 below: addaccount
 }
 FormCard.FormButtonDelegate {
 id: addaccount
 icon.name: "list-add"
 text: i18nc("@action:button", "Add a new account")
 onClicked: console.info("Clicked!")
 }
 }
}

بشكل عام، يمكنك استخدام الفواصل كلما رأيت تمييزات رئيسية بين المكونات، على الرغم من أن اختيار مكان وضعها يعود لك في النهاية. على سبيل المثال، في القسم العام، تختلف خانة الاختيار عن مكوناتها السابقة لأنها لا تبدأ بنص؛ في قسم الحفظ الآلي، يجمع الفاصل أزرار الاختيار معًا؛ وفي قسم الحسابات، إضافة فاصل بين آخر حساب والزر يوفر تركيزًا إضافيًا على الزر.

خصائص above و below واضحة بذاتها إلى حد ما عندما يتعلق الأمر باستخدامها: تمرر id المكونات أعلى وأسفل الفاصل. عند تعيينها، سيختفي الفاصل بسرعة كلما تم تمييز/تحويم العنصر الأعلى أو الأسفل. وهي مفيدة جدًا، على سبيل المثال، عندما تحتاج إلى توليد مكونات ديناميكيًا ولا يمكنك افتراض أي عنصر سيأتي مباشرة قبل أو بعد الفاصل تلقائيًا. سيكون هذا هو الحال في قسم الحسابات في تطبيقنا بمجرد تنفيذ منطق إضافة حسابات جديدة فعليًا، وفي هذه الحالة يمكننا دائمًا الحصول على آخر عنصر في النموذج للقيام بذلك.

لاحظ كيف لا يظهر الفاصل فوق إعداد أيقونة علبة النظام أثناء تحويمه.

Docs: إعداد ويندوز

Mon, 01 Jan 0001 00:00:00 +0000

مقدمة

لدى Qt دعم ممتاز لويندوز، لذا فإن التطبيقات التي تستخدم Qt ووحدات cmake الإضافية لكيدي لن تتطلب تعديلات كثيرة لتعمل بشكل صحيح على ويندوز.

ثلاثة أشياء مطلوبة:

مخطط كرافت
ضبط نمط بريز
أيقونات مرفقة مع التطبيق

مخطط كرافت ضروري لضم جميع التبعيات مع التطبيق لتوليد ملف تنفيذي.

يمكن استخدام توجيه المعالج المسبق #ifdef Q_OS_WIN لكتابة كود يُطبق فقط عند بناء التطبيق على ويندوز. هذا ضروري مرة واحدة على الأقل لفرض نمط بريز على التطبيق ليبدو جيدًا على ويندوز، لكن حسب التطبيق قد يتطلب المزيد.

ضم الأيقونات الضرورية ليعمل التطبيق على ويندوز هو الخطوة الأكثر تعقيدًا، لكن كلًا من وحدات كيدي الإضافية لسيمايك (ECM) وكيوت يوفران وسائل لتسهيل هذه المهمة.

مخطط كرافت

للبدء، يجب أولًا اتباع بناء برمجيات كيدي على ويندوز باستخدام كرافت لتحصل على مخطط كرافت وظيفي وتستطيع على الأقل بناء تطبيقك على ويندوز.

بمجرد أن تتمكن من بناء المشروع، ستحصل على أخطاء ترجمة وتشغيل ستساعدك في إصلاح أي مشكلات توافق مع ويندوز.

نمط بريز

من المفترض أن يكون دليل كيريغامي متوافقًا مع ويندوز في الغالب، لكن الخطوات اللازمة لتحقيق ذلك تحتاج إلى توضيح.

التعديلان اللذان يجب إجراؤهما لضمان استخدام نمط بريز هما ضبط QStyle على breeze وضبط نمط عناصر تحكم كيوت كويك على org.kde.desktop.

QStyle هو ما يتحكم في معظم مظهر تطبيق كيوت ويدجتس. هذا ضروري في تطبيق كيوت كويك لدينا لأننا نهيئ التطبيق باستخدام QApplication (المستخدم تقليديًا مع كيوت ويدجتس).

من ناحية أخرى، نمط عناصر تحكم كيوت كويك يتحكم في معظم مظهر تطبيق كيوت كويك. هذا يؤثر على شكل عناصر تحكم كيوإمإل. نمط كيدي org.kde.desktop (المعروف أيضًا باسم qqc2-desktop-style) مميز ويحاول إزالة التكرار باشتقاق عناصر التنسيق من QStyle الخاص بالتطبيق (ولهذا يُستخدم QApplication). بهذه الطريقة، يمكن لتطبيقات كيوت ويدجتس وكيوت كويك أن تبدو متشابهة في الغالب وتعيد استخدام مكونات التنسيق.

تطبيقات كيوت كويك/كيريغامي تحتاج إلى ضبط كليهما في كود سي++. لضبط QStyle، يجب إضافته في مكانين.

في كرافت:

def setDependencies(self):
 self.runtimeDependencies["kde/plasma/breeze"] = None

وفي سي++:

QApplication::setStyle("breeze");

هذا ما يُستخدم في دليل كيريغامي. يمكنك بدلًا من ذلك تحميل نمط بريز فقط على ويندوز حيث يكون هذا الأكثر صلة باستخدام ifdef:

#ifdef Q_OS_WIN
 QApplication::setStyle("breeze");
#endif

نمط عناصر تحكم كيوت كويك يحتاج إلى الإضافة في ثلاثة أماكن.

في كرافت:

def setDependencies(self):
 self.runtimeDependencies["kde/frameworks/tier3/qqc2-desktop-style"] = None

في سي++، حيث يحتاج إلى أن يكون شرطيًا:

if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE"))
{
 QQuickStyle::setStyle("org.kde.desktop");
}

واختياريًا في سيمايك، بإحدى طريقتين:

find_package(KF6 REQUIRED COMPONENTS QQC2DesktopStyle)
# or
ecm_find_qmlmodule(org.kde.desktop REQUIRED)

نظرًا لأنه تبعية وقت تشغيل، فليس مطلوبًا ضبطها في سيمايك المستخدم في وقت الترجمة. لكن هذا يمكن أن يشير لك وللآخرين إلى ما إذا كانت البيئة صحيحة وستكون قادرة على تشغيل التطبيق الناتج، مما يسمح لك بالعثور على الحزم المفقودة أو التهيئات الخاطئة بسهولة أكبر.

الأمر find_package() يبحث تحديدًا عن ملفات تهيئة سيمايك لـ qqc2-desktop-style، بينما ecm_find_qmlmodule() أقل صرامة ويبحث فقط عن وحدة كيوإمإل. الأخير يتطلب تضمين ECMFindQmlModule:

include(ECMFindQmlModule)

شحن الأيقونات

أول شيء مطلوب لجعل التطبيق يستخدم أيقونات بريز هو تضمين KIconThemes في مشروعك.

بعد ذلك، بعض أوامر سيمايك مطلوبة لضم أيقونة تطبيقك مع التطبيق.

كي أيقونة ثيمات

يمكن القيام بذلك بالخطوات الثلاث التالية:

إضافته كتبعية في كرافت:

def setDependencies(self):
 self.runtimeDependencies["kde/frameworks/tier3/kiconthemes"] = None

إضافته كتبعية في سيمايك:

find_package(KF6 REQUIRED COMPONENTS IconThemes)

# ...

target_link_libraries(myapp
 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 وكجزء من تثبيت الأيقونة.

عادةً على لينكس، يمكن ببساطة تثبيت أيقونة التطبيق في الدليل الصحيح، وسيتم جلب الأيقونة بواسطة التطبيق عند الحاجة. تتكون أيقونة التطبيق عادةً من أيقونة SVG رئيسية، مقترنة بأحجام أيقونات PNG متعددة.

يتم تثبيت أيقونة SVG هكذا في CMake:

install(FILES ${PROJECT_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++، ولا سيما عند ضبط أيقونة النافذة، يمكنك استخدام أيقونة السمة مبدئيًا والأيقونة المضمنة كبديل احتياطي مع QIcon::fromTheme() في استدعاء QGuiApplication::setWindowIcon():

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

أيقونات كيريغامي

بينما لا يوجد لدى ويندوز دليل قياسي لتثبيت أيقونات من سمة أيقونات، فمن الممكن تضمين أيقونات بريز الضرورية مع تطبيق ويندوز الخاص بك.

يتم هذا بواسطة كرافت تلقائيًا عندما يتم إعداد KIconThemes بشكل صحيح للمشروع ويتم تضمين أيقونات بريز كاعتمادية في مشروعك.

لإعداد KIconThemes، راجع القسم أعلاه KIconThemes.

لإضافة أيقونات بريز كاعتمادية لمشروعك، أضف هذا إلى مخطط كرافت الخاص بك:

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

بهذه الطريقة، لن تحتاج إلى تضمين أي أيقونات بريز يدويًا في تطبيقك كمورد: يمكنك فقط استخدام اسم QIcon::fromTheme()، مثل kde أو application-exit-symbolic.

البناء

لبناء تطبيقك على ويندوز، اتبع بناء برمجيات كيدي على ويندوز مع كرافت: بناء مشاريعك الخاصة على ويندوز.

بنيات CI

إذا تم تكوين المشروع بشكل صحيح للبناء على ويندوز ويستخدم بنية كيدي التحتية لاستضافة الشيفرة (كيدي إنفنت)، فمن الممكن تكوين وظائف CI/CD لويندوز.

للقيام بذلك، ستحتاج إلى إضافة قوالب CI ذات الصلة لويندوز مع ملف .gitlab-ci.yaml وسرد اعتمادياتك في ملف .kde-ci.yaml كما هو مذكور في نظام التكامل المستمر.

استكشاف الأخطاء وإصلاحها

إذا كانت لديك مشاكل في تكييف تطبيقك مع ويندوز، يمكنك زيارة الغرف التالية على ماتريكس: