Add prompt text property to SelectionBox

Introduced `promptTextProperty` to `SelectionBox` allowing optional display text when no item is selected. Updated the demo application to include an option to change the prompt text, and adapted the skin to handle prompt text updates.

gemsfx-demo/src/main/java/com/dlsc/gemsfx/demo/SelectionBoxApp.java

@@ -64,6 +64,17 @@ private Node getControlPanel() {
         CheckBox visibleExtraButtonsCheckBox = new CheckBox("Show Extra Buttons");
         visibleExtraButtonsCheckBox.selectedProperty().bindBidirectional(selectionBox.showExtraButtonsProperty());
 
+        // prompt text
+        CheckBox promptTextCheckBox = new CheckBox("Change Prompt Text");
+        promptTextCheckBox.setOnAction(evt -> {
+            selectionBox.getSelectionModel().clearSelection();
+            if (promptTextCheckBox.isSelected()) {
+                selectionBox.setPromptText("Select");
+            } else {
+                selectionBox.setPromptText("No Selection");
+            }
+        });
+
         // change extra buttons
         Button changeExtraButtonsButton = new Button("Change Extra Buttons");
         changeExtraButtonsButton.setMaxWidth(Double.MAX_VALUE);
@@ -213,6 +224,7 @@ public List<String> fromString(String string) {
                 "SelectionBox",
                 new SimpleControlPane.ControlItem("Show Popup", showButton),
                 new SimpleControlPane.ControlItem("Selection Mode", selectionModeComboBox),
+                new SimpleControlPane.ControlItem("Change Prompt Text", promptTextCheckBox),
                 new SimpleControlPane.ControlItem("Show Extra Buttons", visibleExtraButtonsCheckBox),
                 new SimpleControlPane.ControlItem("Change Extra Buttons", changeExtraButtonsButton),
                 new SimpleControlPane.ControlItem("Extra Buttons Position", extraButtonsPositionComboBox),

gemsfx/src/main/java/com/dlsc/gemsfx/SelectionBox.java

@@ -8,6 +8,8 @@
 import javafx.beans.property.SimpleBooleanProperty;
 import javafx.beans.property.SimpleListProperty;
 import javafx.beans.property.SimpleObjectProperty;
+import javafx.beans.property.SimpleStringProperty;
+import javafx.beans.property.StringProperty;
 import javafx.collections.FXCollections;
 import javafx.collections.ObservableList;
 import javafx.css.CssMetaData;
@@ -156,7 +158,7 @@ public final void setExtraButtonsProvider(Callback<MultipleSelectionModel<T>, Li
      * The button will be styled with the "extra-button" class and will adjust its visibility
      * based on its managed property. The button's maximum width will be set to the maximum double value.
      *
-     * @param text the text to be displayed on the button
+     * @param text   the text to be displayed on the button
      * @param action the action to be executed when the button is clicked
      * @return the created Button instance
      */
@@ -169,9 +171,9 @@ public Button createExtraButton(String text, Runnable action) {
      * The created button will be styled with "extra-button" class and will adjust its visibility
      * based on its managed property. The button's maximum width will be set to the maximum double value.
      *
-     * @param text the text to be displayed on the button
+     * @param text    the text to be displayed on the button
      * @param graphic the graphic node to be displayed on the button
-     * @param action the action to be executed when the button is clicked
+     * @param action  the action to be executed when the button is clicked
      * @return the created Button instance
      */
     public Button createExtraButton(String text, Node graphic, Runnable action) {
@@ -253,6 +255,31 @@ public final Node getGraphic() {
         return graphic == null ? null : graphic.get();
     }
 
+    // promptText
+
+    private StringProperty promptText;
+
+    /**
+     * Returns the prompt text property of this SelectionBox. The prompt text is an optional
+     * text that can be displayed in the picker when no item is selected.
+     *
+     * @return the StringProperty containing the prompt text.
+     */
+    public final StringProperty promptTextProperty() {
+        if (promptText == null) {
+            promptText = new SimpleStringProperty(this, "promptText");
+        }
+        return promptText;
+    }
+
+    public final void setPromptText(String promptText) {
+        promptTextProperty().set(promptText);
+    }
+
+    public final String getPromptText() {
+        return promptText == null ? null : promptText.get();
+    }
+
     // autoHideOnSelection
 
     private BooleanProperty autoHideOnSelection;
@@ -301,6 +328,9 @@ public final void setAutoHideOnSelection(boolean autoHideOnSelection) {
      * this list to display as "1, 2, 3, 4, 5". By setting a custom converter, it is possible to modify
      * the display to any desired format, such as "1~5".
      * <p>
+     * If the selected items list is {@code null} or empty, the {@code promptTextProperty()} value will
+     * be used instead, so there is no need to handle these cases within the converter.
+     * <p>
      * The {@code selectedItemsConverterProperty} provides a way to bind the display logic to UI components,
      * enabling dynamic updates whenever the selected items change or the converter is redefined.
      *

gemsfx/src/main/java/com/dlsc/gemsfx/skins/SelectionBoxSkin.java

@@ -119,6 +119,7 @@ private void addListenerToControl() {
 
         control.itemConverterProperty().addListener((obs, oldConverter, newConverter) -> updateDisplayLabelText());
         control.selectedItemsConverterProperty().addListener((obs, oldConverter, newConverter) -> updateDisplayLabelText());
+        control.promptTextProperty().addListener((obs, oldText, newText) -> updateDisplayLabelText());
 
         control.getSelectionModel().selectedItemProperty().addListener(selectItemChangedListener);
         control.getSelectionModel().getSelectedItems().addListener(selectItemsChangeListener);
@@ -227,11 +228,16 @@ public void updateDisplayLabelText() {
 
         StringConverter<List<T>> stringConverter = control.getSelectedItemsConverter();
         String text;
-        if (stringConverter != null) {
-            text = stringConverter.toString(selectedItems);
+
+        if (selectedItems.isEmpty()) {
+            text = control.getPromptText();
         } else {
-            // Use default conversion logic
-            text = getDefaultDisplayText(selectedItems);
+            if (stringConverter != null) {
+                text = stringConverter.toString(selectedItems);
+            } else {
+                // Use default conversion logic
+                text = getDefaultDisplayText(selectedItems);
+            }
         }
         displayLabel.setText(text);
     }
@@ -384,7 +390,7 @@ private class SelectionPopupSkin implements Skin<SelectionPopup> {
         public SelectionPopupSkin(SelectionPopup popup) {
             this.popup = popup;
 
-            contentBox = new VBox(){
+            contentBox = new VBox() {
                 @Override
                 public String getUserAgentStylesheet() {
                     return Objects.requireNonNull(SelectionBox.class.getResource("selection-box.css")).toExternalForm();