Skip to main content
تخط المحتوى

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

أنشئ أول تطبيق Kirigami لك باستخدام C++

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

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

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

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

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

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

logo of Linux operating system KubuntuKubuntulogo of Linux operating system KDE neonKDE 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
logo of Linux operating system ManjaroManjarologo of Linux operating system Arch LinuxArch
sudo pacman -S base-devel extra-cmake-modules cmake kirigami ki18n kcoreaddons breeze kiconthemes qt6-base qt6-declarative qqc2-desktop-style
logo of Linux operating system openSUSEOpenSUSE
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
logo of Linux operating system FedoraFedora
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

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

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

بينما كرافت متاح أيضًا للينكس وفري بي إس دي، فإن استخدامه المقصود هو فقط لصور التطبيقات 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 فيه لأنه سيُشغَّل مع الملف التنفيذي.

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، التي توفر عددًا من المكونات المناسبة لإنشاء تطبيقات تعمل عبر أجهزة بأشكال وأحجام مختلفة.

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

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

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

ثم نضبط الصفحة الأولى من رصة الصفحات لدينا. معظم تطبيقات 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

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

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

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

في المرة القادمة التي تحتاج فيها إلى إضافة المزيد من ملفات 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 الخاص بنا، لكن دوره سيزداد أهمية بشكل ملحوظ بمجرد أن نقرر إضافة وظائف أكثر تعقيدًا إلى تطبيقنا في المستقبل.

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

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

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

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

الوسيط الأول هو URI المُضبَط في kirigami-tutorial/src/CMakeLists.txt، والوسيط الثاني هو اسم وحدة QML التي نريد استخدامها (Main، آتٍ من اسم ملف Main.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 لك يظهر أمام عينيك.

لقطة شاشة لتطبيق Kirigami المُنشأ

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

QT_QUICK_CONTROLS_MOBILE=1 kirigami-hello

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

cmake --build build/ --target uninstall