Add util classes for enhanced string conversion and UI interactions

Added classes in com.dlsc.gemsfx.util to provide enhanced formatting for Enums and improved UI interactions. The classes include EnumStringConverter, EnumUtil, SimpleStringConverter, and UIUtil which provide various helper methods for connecting UI and data models. It also includes corresponding demo classes to showcase the usage of the utilities. Additionally, enabled static dependency on org.jetbrains.annotations.

gemsfx-demo/src/main/java/com/dlsc/gemsfx/demo/util/EnumStringConverterDemo.java

@@ -0,0 +1,77 @@
+package com.dlsc.gemsfx.demo.util;
+
+import com.dlsc.gemsfx.util.EnumStringConverter;
+import javafx.application.Application;
+import javafx.geometry.Insets;
+import javafx.geometry.Pos;
+import javafx.scene.Scene;
+import javafx.scene.control.ComboBox;
+import javafx.scene.control.Label;
+import javafx.scene.layout.VBox;
+import javafx.scene.text.Font;
+import javafx.stage.Stage;
+
+
+/**
+ * This class demonstrates the usage of EnumStringConverter, which is a specialized StringConverter implementation
+ * for Enum types. It provides a default mechanism to format Enum values in title case, replaces underscores with spaces,
+ * and capitalizes the first letter of each word. If the Enum value is null, it returns an empty string.
+ * <p>
+ * {@link EnumStringConverter}
+ */
+public class EnumStringConverterDemo extends Application {
+
+    public enum Status {
+        NOT_STARTED,
+        IN_PROGRESS,
+        COMPLETED,
+        CANCELLED
+    }
+
+    @Override
+    public void start(Stage primaryStage) {
+        // Create a ComboBox and populate it with Status objects
+        ComboBox<Status> comboBox = new ComboBox<>();
+        comboBox.getItems().addAll(Status.values());
+        comboBox.getSelectionModel().selectFirst();
+
+        // The traditional way to set a StringConverter on a ComboBox
+        // comboBox.setConverter(new StringConverter<Status>() {
+        //     @Override
+        //     public String toString(Status object) {
+        //         if (object != null) {
+        //             return Arrays.stream(object.name().split("_"))
+        //                     .filter(word -> !word.isEmpty())
+        //                     .map(word -> word.substring(0, 1).toUpperCase() + word.substring(1).toLowerCase())
+        //                     .collect(Collectors.joining(" "));
+        //         }
+        //         return "";
+        //     }
+        //
+        //     @Override
+        //     public Status fromString(String string) {
+        //         return null;
+        //     }
+        // });
+
+        // Set the converter to use EnumStringConverter with the default title case formatting
+        comboBox.setConverter(new EnumStringConverter<>());
+
+        // Create a VBox layout and add the ComboBox to it
+        Label label = new Label("Select a status:");
+        label.setFont(Font.font(15));
+        VBox vbox = new VBox(15, label, comboBox);
+        vbox.setAlignment(Pos.CENTER);
+        vbox.setPadding(new Insets(20));
+        Scene scene = new Scene(vbox,300, 200);
+
+        // Configure and show the primary stage
+        primaryStage.setTitle("EnumStringConverter Demo");
+        primaryStage.setScene(scene);
+        primaryStage.show();
+    }
+
+    public static void main(String[] args) {
+        launch(args);
+    }
+}

gemsfx-demo/src/main/java/com/dlsc/gemsfx/demo/util/SimpleStringConverterDemo.java

@@ -0,0 +1,74 @@
+package com.dlsc.gemsfx.demo.util;
+
+import com.dlsc.gemsfx.util.SimpleStringConverter;
+import javafx.application.Application;
+import javafx.geometry.Insets;
+import javafx.geometry.Pos;
+import javafx.scene.Scene;
+import javafx.scene.control.ComboBox;
+import javafx.scene.control.Label;
+import javafx.scene.layout.VBox;
+import javafx.scene.text.Font;
+import javafx.stage.Stage;
+
+import java.time.LocalDate;
+
+/**
+ * This class demonstrates the usage of SimpleStringConverter, which is a specialized StringConverter implementation
+ * that allows you to define a custom formatting function for the conversion of objects to strings. It also provides
+ * a default mechanism to handle null values and empty strings.
+ * {@link SimpleStringConverter}
+ */
+public class SimpleStringConverterDemo extends Application {
+
+    public record Task(String description, LocalDate dueDate) {
+    }
+
+    @Override
+    public void start(Stage primaryStage) {
+        // Create a ComboBox and populate it with Task objects
+        ComboBox<Task> comboBox = new ComboBox<>();
+        comboBox.getItems().addAll(
+                new Task("Task 1", LocalDate.now().plusWeeks(3)),
+                new Task("Task 2", LocalDate.now().plusWeeks(5)),
+                new Task("Task 3", LocalDate.now().plusWeeks(6))
+        );
+        comboBox.getSelectionModel().selectFirst();
+
+        // The traditional way to set a StringConverter on a ComboBox
+        // comboBox.setConverter(new StringConverter<Task>() {
+        //     @Override
+        //     public String toString(Task object) {
+        //         if (object != null) {
+        //             return object.description() + "  [Due: " + object.dueDate() +"]";
+        //         }
+        //         return "";
+        //     }
+        //
+        //     @Override
+        //     public Task fromString(String string) {
+        //         return null;
+        //     }
+        // });
+
+        // Set the converter to use SimpleStringConverter with the default title case formatting
+        comboBox.setConverter(new SimpleStringConverter<>(task -> task.description() + "  [Due: " + task.dueDate() + "]", ""));
+
+        // Create a VBox layout and add the ComboBox to it
+        Label label = new Label("Select a status:");
+        label.setFont(new Font(16));
+        VBox vbox = new VBox(15, label, comboBox);
+        vbox.setPadding(new Insets(15));
+        vbox.setAlignment(Pos.CENTER);
+        Scene scene = new Scene(vbox, 300, 200);
+
+        // Configure and show the primary stage
+        primaryStage.setTitle("SimpleStringConverter Demo");
+        primaryStage.setScene(scene);
+        primaryStage.show();
+    }
+
+    public static void main(String[] args) {
+        launch(args);
+    }
+}

gemsfx-demo/src/main/java/module-info.java

@@ -19,4 +19,5 @@
 
     exports com.dlsc.gemsfx.demo;
     exports com.dlsc.gemsfx.demo.binding;
+    exports com.dlsc.gemsfx.demo.util;
 }

gemsfx/pom.xml

@@ -46,6 +46,12 @@
 
     <dependencies>
 
+        <dependency>
+            <groupId>org.jetbrains</groupId>
+            <artifactId>annotations</artifactId>
+            <optional>true</optional>
+        </dependency>
+
         <dependency>
             <groupId>net.synedra</groupId>
             <artifactId>validatorfx</artifactId>

gemsfx/src/main/java/com/dlsc/gemsfx/util/EnumStringConverter.java

@@ -0,0 +1,65 @@
+package com.dlsc.gemsfx.util;
+
+import javafx.util.Callback;
+
+/**
+ * A specialized StringConverter implementation for Enum types.
+ * This converter provides a default mechanism to format Enum values
+ * in a title case, replacing underscores with spaces and capitalizing
+ * the first letter of each word. If the enum value is null, it returns an empty string.
+ *
+ * <p>
+ * This class extends SimpleStringConverter and leverages EnumUtil to provide
+ * a default formatting for enum values. It can also accept custom callbacks for
+ * more specific conversion requirements.
+ * </p>
+ *
+ * <p><strong>Usage Example:</strong></p>
+ * <p>Default usage with title case formatting:</p>
+ * <pre>{@code
+ * ComboBox<MyEnum> comboBox = new ComboBox<>();
+ * comboBox.setConverter(new EnumStringConverter<>());
+ * }</pre>
+ *
+ * <p>Custom callback for specific formatting:</p>
+ * <pre>{@code
+ * ComboBox<MyEnum> comboBox = new ComboBox<>();
+ * comboBox.setConverter(new EnumStringConverter<>(myEnum -> "Custom format: " + myEnum.name()));
+ * }</pre>
+ *
+ * @param <T> the type of the Enum to be converted.
+ */
+public class EnumStringConverter<T extends Enum<T>> extends SimpleStringConverter<T> {
+
+    /**
+     * Converts an enum value to title case, replacing underscores with spaces and
+     * capitalizing the first letter of each word. If the enum value is null, returns an empty string.
+     * <p> Example: 1. null -> ""
+     * <p> Example: 2. MY_ENUM_VALUE -> My Enum Value
+     */
+    public EnumStringConverter() {
+        this(EnumUtil::formatEnumNameAsTitleCase);
+    }
+
+    /**
+     * Constructor that accepts a custom callback for converting enum values to strings.
+     * The provided callback should handle conversion from enum value to String, including any necessary null handling.
+     *
+     * @param valueToStringCallback The callback to convert enum value to a String.
+     */
+    public EnumStringConverter(Callback<T, String> valueToStringCallback) {
+        super(valueToStringCallback);
+    }
+
+    /**
+     * Constructor that accepts a custom callback for converting non-null enum values to strings and a default string
+     * to return if the enum value is null.
+     *
+     * @param nonNullValueCallback The callback to convert non-null enum value to a String.
+     * @param nullDefaultValue The default String value to return if the enum value is null.
+     */
+    public EnumStringConverter(Callback<T, String> nonNullValueCallback, String nullDefaultValue) {
+        super(nonNullValueCallback, nullDefaultValue);
+    }
+
+}