مقدمة إلى إضافات Kirigami

تعرف على مكونات إضافات Kirigami

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

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

تستفيد هذه المكونات من مرافق التعريب في كيدي، لذا قبل البدء باستخدامها، سنحتاج إلى إعداد مشروع صغير يستخدم 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.

اربط نماذج C++ بواجهة مستخدم QML الخاصة بك

صفحات حول FormCard