أساسيات JavaFX ورسم المشهد

مشروع: تطبيق JavaFX متكامل

18 دقيقة الدرس 10 من 12

مشروع: تطبيق JavaFX متكامل

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

بحلول نهاية هذا الدرس سيكون لديك برنامج قابل للتشغيل يُظهر الأنماط التي ستستخدمها في كل مشروع JavaFX حقيقي.

ما يفعله التطبيق

لوحتا تحويل جنبًا إلى جنب داخل HBox.
كل لوحة تحتوي على TextField مُوسَم للإدخال وتسمية Label للنتيجة بنمط مميز.
تتحدّث النتائج فورًا أثناء الكتابة، بالاعتماد على ChangeListener على خاصية النص.
يعرض إدخال غير صالح أو فارغ شرطة "—" بدلًا من التعطّل.
زر Reset يمسح الحقلين؛ والضغط على Enter في أي حقل ينفّذ نفس الإجراء.
تمتلك Stage الرئيسية حدًّا أدنى للحجم وعنوانًا مخصّصًا.

هيكل المشروع

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

src/
└── main/
    └── java/
        └── com/example/converter/
            └── ConverterApp.java

أضف وحدات JavaFX SDK إلى ملف Maven pom.xml الخاص بك (أو مسار الوحدة إذا كنت تشغّل من سطر الأوامر):

<dependency>
    <groupId>org.openjfx</groupId>
    <artifactId>javafx-controls</artifactId>
    <version>21</version>
</dependency>

كود المصدر الكامل

package com.example.converter;

import javafx.application.Application;
import javafx.geometry.Insets;
import javafx.geometry.Pos;
import javafx.scene.Scene;
import javafx.scene.control.Button;
import javafx.scene.control.Label;
import javafx.scene.control.TextField;
import javafx.scene.layout.HBox;
import javafx.scene.layout.VBox;
import javafx.scene.paint.Color;
import javafx.scene.text.Font;
import javafx.scene.text.FontWeight;
import javafx.stage.Stage;

public class ConverterApp extends Application {

    // --- حقول لوحة المسافة ---
    private TextField kmField;
    private Label     milesResult;

    // --- حقول لوحة الحرارة ---
    private TextField celsiusField;
    private Label     fahrenheitResult;

    @Override
    public void start(Stage primaryStage) {

        // ── لوحة المسافة ──────────────────────────────────────
        VBox distancePanel = buildPanel(
            "Distance",
            "Kilometres",
            kmField = new TextField(),
            milesResult = new Label("—"),
            () -> convertKmToMiles()
        );

        // ── لوحة الحرارة ────────────────────────────────────────
        VBox tempPanel = buildPanel(
            "Temperature",
            "Celsius",
            celsiusField = new TextField(),
            fahrenheitResult = new Label("—"),
            () -> convertCelsiusToFahrenheit()
        );

        // ── ربط المستمعين المباشرين ──────────────────────────────
        kmField.textProperty().addListener(
            (obs, oldVal, newVal) -> convertKmToMiles()
        );
        celsiusField.textProperty().addListener(
            (obs, oldVal, newVal) -> convertCelsiusToFahrenheit()
        );

        // ── زر إعادة الضبط ─────────────────────────────────────
        Button resetBtn = new Button("Reset");
        resetBtn.setFont(Font.font("System", FontWeight.BOLD, 13));
        resetBtn.setPrefWidth(120);
        resetBtn.setOnAction(e -> reset());

        // ── التخطيط الجذري ──────────────────────────────────────
        HBox panels = new HBox(30, distancePanel, tempPanel);
        panels.setAlignment(Pos.TOP_CENTER);
        panels.setPadding(new Insets(20));

        VBox root = new VBox(20, panels, resetBtn);
        root.setAlignment(Pos.TOP_CENTER);
        root.setPadding(new Insets(20));
        root.setStyle("-fx-background-color: #f4f6f9;");

        // ── المشهد والمرحلة ────────────────────────────────────
        Scene scene = new Scene(root, 500, 280);
        primaryStage.setTitle("Unit Converter");
        primaryStage.setMinWidth(400);
        primaryStage.setMinHeight(240);
        primaryStage.setScene(scene);
        primaryStage.show();
    }

    /** يبني لوحة تحويل مُوسَمة بوصفها VBox. */
    private VBox buildPanel(String heading, String inputLabel,
                            TextField field, Label result,
                            Runnable onEnter) {

        Label title = new Label(heading);
        title.setFont(Font.font("System", FontWeight.BOLD, 16));
        title.setTextFill(Color.web("#2c3e50"));

        Label inputLbl = new Label(inputLabel + ":");
        inputLbl.setTextFill(Color.web("#555555"));

        field.setPromptText("Enter value");
        field.setPrefWidth(180);
        field.setOnAction(e -> onEnter.run());   // مفتاح Enter ينفّذ التحويل

        result.setFont(Font.font("System", FontWeight.BOLD, 22));
        result.setTextFill(Color.web("#27ae60"));

        VBox box = new VBox(10, title, inputLbl, field, result);
        box.setAlignment(Pos.TOP_LEFT);
        box.setPadding(new Insets(16));
        box.setStyle(
            "-fx-background-color: white;" +
            "-fx-border-color: #d0d7de;" +
            "-fx-border-radius: 8;" +
            "-fx-background-radius: 8;"
        );
        box.setPrefWidth(200);
        return box;
    }

    // ── منطق التحويل ─────────────────────────────────────────

    private void convertKmToMiles() {
        try {
            double km    = Double.parseDouble(kmField.getText().trim());
            double miles = km * 0.621371;
            milesResult.setText(String.format("%.3f mi", miles));
            milesResult.setTextFill(Color.web("#27ae60"));
        } catch (NumberFormatException ex) {
            milesResult.setText("—");
            milesResult.setTextFill(Color.web("#999999"));
        }
    }

    private void convertCelsiusToFahrenheit() {
        try {
            double c = Double.parseDouble(celsiusField.getText().trim());
            double f = c * 9.0 / 5.0 + 32;
            fahrenheitResult.setText(String.format("%.2f °F", f));
            fahrenheitResult.setTextFill(Color.web("#27ae60"));
        } catch (NumberFormatException ex) {
            fahrenheitResult.setText("—");
            fahrenheitResult.setTextFill(Color.web("#999999"));
        }
    }

    private void reset() {
        kmField.clear();
        celsiusField.clear();
        milesResult.setText("—");
        milesResult.setTextFill(Color.web("#999999"));
        fahrenheitResult.setText("—");
        fahrenheitResult.setTextFill(Color.web("#999999"));
        kmField.requestFocus();
    }

    public static void main(String[] args) {
        launch(args);
    }
}

شرح القرارات المحورية

دالة مساعدة لبناء اللوحات

تقبل الدالة buildPanel() وسيطًا من نوع Runnable حتى يؤدي الضغط على Enter في أي حقل إلى استدعاء دالة التحويل المقابلة. هذا يتجنّب تكرار الكود مع إبقاء منطق كل لوحة منفصلًا. Runnable هي دالة لامدا: () -> convertKmToMiles(). لاحظ أن الحقل وتسمية Label للنتيجة تُمرَّران كمعاملات حتى يحتفظ الكود المُستدعي (في start()) بمراجع لهما للتحديثات المباشرة ولعملية الإعادة.

التحديثات المباشرة عبر ChangeListener

إرفاق ChangeListener بـ field.textProperty() يعني إعادة الحساب عند كل ضغطة مفتاح. يستقبل المستمع ثلاثة وسيطات — الكائن القابل للمراقبة، القيمة القديمة، والقيمة الجديدة — لكن هذا الكود يهتم فقط بالأثر الجانبي (استدعاء التحويل)، لذا يمكن تجاهل الثلاثة.

لماذا لا نستخدم setOnAction للتحديثات المباشرة؟ setOnAction على TextField يُطلَق فقط عند ضغط المستخدم على Enter. أما ChangeListener على خاصية النص فيُطلَق عند كل تغيير في الأحرف — وهذا ما يمنح التجربة "المباشرة". كلاهما مُوصَّل هنا: Enter ينفّذ نفس التحويل للمستخدمين الذين يعتمدون سير عمل لوحة المفاتيح.

معالجة الأخطاء بأسلوب لطيف

كتلة catch (NumberFormatException ex) لا تعرض حوار خطأ ولا تطبع تتبع المكدس. بدلًا من ذلك تُعيد تسمية النتيجة إلى "—" وتغيّر لونها إلى الرمادي. هذا هو تجربة المستخدم الصحيحة لحقل يتحدّث فورًا — فالمستخدم في منتصف الكتابة ولم يرتكب خطأً بعد؛ رقمه غير مكتمل فحسب.

سلامة الخيوط

كل الكود الموجود في start() ومعالجات الأحداث يعمل على خيط تطبيق JavaFX. لا توجد عمليات خلفية هنا، لذا لا حاجة لـ Platform.runLater(). إذا وسّعت هذا التطبيق لاحقًا لجلب سعر صرف من API ويب، ستُجري طلب الشبكة على خيط خلفي وتحدّث التسمية داخل Platform.runLater() — تمامًا كما تناولنا في درس الخيوط.

CSS المُضمَّن مقابل ورقة الأنماط

التنسيق يُنجَز باستدعاءات setStyle() بدلًا من ملف CSS خارجي. هذا مقبول لمشروع صغير مستقل ويجعل الكود ذاتي الاحتواء. لأي شيء أكبر، يُفضَّل ملف styles.css يُحمَّل بـ scene.getStylesheets().add(...) — فهو يفصل الاهتمامات ويُتيح الثيمات.

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

توسيع المشروع

إليك الخطوات التالية الطبيعية التي يقدّم كل منها مفهومًا جديدًا في JavaFX:

إضافة ComboBox لاختيار الوحدة — يُعرّفك على ربط القيم القابلة للمراقبة وعناصر تحكم ChoiceBox/ComboBox.
تحميل ورقة أنماط خارجية — ينقل قواعد التنسيق إلى converter.css ويُعلّمك نظام CSS في JavaFX.
إضافة سجل تحويل بـ ListView — يُعرّفك على ObservableList وFXCollections.
جلب سعر عملة مباشر — يُجبرك على استخدام Thread أو Task خلفي وPlatform.runLater().

الخلاصة

هذا المشروع صغير عمدًا — كل سطر فيه يخدم غرضًا تعليميًا. لقد رأيت كيف تتناسب نقطة الدخول Application، ورسم المشهد، وحاويات التخطيط، وعناصر التحكم، والخصائص، والمستمعون، ومعالجات الأحداث معًا في كل متماسك. الأنماط التي استخدمتها هنا — بناء المشهد في start()، وربط المستمعين بالخصائص القابلة للمراقبة، وفصل منطق التحويل عن توصيلات الواجهة، ومعالجة الإدخال الخاطئ بأسلوب لطيف — هي نفسها التي ستطبّقها في تطبيقات بأي حجم. من هنا، كل موضوع جديد في JavaFX (FXML، والربطات، والحركات، وعناصر التحكم المخصّصة) هو امتداد لهذا الأساس.