Class SettingsPane

  • All Implemented Interfaces:
    Styleable, EventTarget, Skinnable

    @DefaultProperty("options")
    public class SettingsPane
    extends Control

    The SettingsPane control is designed to make it really easy for developers to present to end users a list of options that can be modified, using proper built-in editors according the type of those options.

    Typically a settings pane is the control added to the Settings View, and several options are presented for the end user to customize the application. A proper persistence scheme is advised. See Gluon's StorageService documentation.

    Screenshot of a View

    While it is not mandatory, the best way to add the options to the control is by using a model of properties, typically a JavaFX bean. Each property will be bound bidirectionally to the editor value property, so any change made in either the model or the editor will be immediately reflected in the other.

     
     public class Settings {
       private final BooleanProperty showDate = new SimpleBooleanProperty(this, "showDate", true);
       public final BooleanProperty showDateProperty() { return showDate; }
       public final boolean isShowDate() { return showDate.get(); }
       public final void setShowDate(boolean value) { showDate.set(value); }
     }
     

    Based on this model, an option has to be set for each property, and based on its type, a default editor will be used. DefaultOption is a convenience class for creating this option.

     
     Settings settings = new Settings();
     SettingsPane settingsPane = new SettingsPane();
     final Option<BooleanProperty> dateOption = new DefaultOption(MaterialDesignIcon.DATE_RANGE.graphic(),
                   "Show Date", "Show the date", null, settings.showDateProperty(), true);
    
     settingsPane.getOptions().addAll(dateOption);
     settingsPane.setSearchBoxVisible(false);
     

    In this case, for a BooleanProperty a styled ToggleButton will be used as editor.

    Adding options to the SettingsPane control

    Singular Options

    If the category argument is not null, on top of all the options with the same category value a header will be added, with a label for the category name and without any editor.

    Also, a horizontal separator can be used to divide the pane.

     
        Settings settings = new Settings();
        SettingsPane settingsPane = new SettingsPane();
        final Option<BooleanProperty> dateOption = new DefaultOption(MaterialDesignIcon.DATE_RANGE.graphic(),
                   "Show Date", "Show the date", "Category", settings.showDateProperty(), true);
    
        settingsPane.getOptions().addAll(
               dateOption, 
               new DefaultOption(Option.SEPARATOR));
        settingsPane.setSearchBoxVisible(false);
     

    Categories and Separators

    Custom editors

    Using the optionEditorFactory property, the develper may provide its own editor factory. In this case, all properties should find a proper editor.

    It is more convenient relying on the default factory, providing only the custom editor needed for a given property. For that, this editor must implement OptionEditor.

    This is a sample of a custom editor for boolean properties, that uses a CheckBox:

     
     public class CheckBoxEditor implements OptionEditor<Boolean> {
        private final CheckBox checkBox;
        public CheckBoxEditor(Option<Boolean> option) {
           this.checkBox = new CheckBox();
           valueProperty().bindBidirectional(option.valueProperty());
        }}
       @Override public Node getEditor() { return checkBox; }
       @Override public finalProperty<Boolean> valueProperty() { return checkBox.selectedProperty(); }
       @Override public Boolean getValue() { return checkBox.isSelected(); }
       @Override public void setValue(Boolean value) { checkBox.setSelected(value); }
     

    And now it can be added to the option:

     
       final Option<BooleanProperty> dateOption = new DefaultOption(MaterialDesignIcon.DATE_RANGE.graphic(),
                   "Show Date", "Show the date", "Category", settings.showDateProperty(), true,
                   option -> new CheckBoxEditor((Option<Boolean>) option));
     

    Custom Editor

    Extended Options

    Options that require longer explanations may add a description on a second screen. The editor will be visible only in the second screen, while on the main one the value will be added under the name of the option. A StringConverter can be used to format this value properly.

     
        final DefaultOption<BooleanProperty> dateOption = new DefaultOption(MaterialDesignIcon.DATE_RANGE.graphic(), 
                    "Show Date", "Show the date", null, settings.showDateProperty(), true);
            String extended = "Settings that require longer explanations may add a description on a second screen. \n\n"
                    + "Provide a long description here.";
            dateOption.setExtendedDescription(extended);
            dateOption.setStringConverter(new StringConverter<Boolean>(){
                @Override public String toString(Boolean object) {
                    return object ? "Date is shown" : "Date is hidden";
                }
                @Override public Boolean fromString(String string) {
                    return string.equals("Date is shown");
                }
            });
            settingsPane.getOptions().addAll(dateOption);
     

    Extended options. Parent

    Extended options. Child

    Option subcategories

    Any given set of options can be added as children of a parent option. In this case, the parent won't have any property to edit, and when selecting this option, a new view will be shown with its children.

     
        final Option<BooleanProperty> dateOption = new DefaultOption(MaterialDesignIcon.DATE_RANGE.graphic(),
                   "Show Date", "Show the date", null, settings.showDateProperty(), true);
        final Option parentOption = new DefaultOption("Parent", "Press to access subcategory", null);
        parentOption.getChildren().add(dateOption);
        settingsPane.getOptions().addAll(parentOption);
     

    Subcategories. Parent

    Subcategories. Child

    Since:
    2.0.0
    See Also:
    DefaultOption, OptionBase, OptionEditorBase
    • Property Detail

      • searchBoxVisible

        public final SimpleBooleanProperty searchBoxVisibleProperty
        This property represents whether a text field should be presented to users to allow for them to filter the options in the settings control to only show ones matching the typed input. By default this is true, so setting it to false will hide this search field.
        See Also:
        isSearchBoxVisible(), setSearchBoxVisible(boolean)
    • Constructor Detail

      • SettingsPane

        public SettingsPane()
        Creates a new instance with an empty collection of options
    • Method Detail

      • searchBoxVisibleProperty

        public final SimpleBooleanProperty searchBoxVisibleProperty()
        This property represents whether a text field should be presented to users to allow for them to filter the options in the settings control to only show ones matching the typed input. By default this is true, so setting it to false will hide this search field.
        See Also:
        isSearchBoxVisible(), setSearchBoxVisible(boolean)
      • isSearchBoxVisible

        public final boolean isSearchBoxVisible()
        Returns:
        whether a text field should be presented to users to allow for them to filter the options in the settings control to only show ones matching the typed input.
      • setSearchBoxVisible

        public final void setSearchBoxVisible​(boolean visible)
        Sets whether a text field should be presented to users to allow for them to filter the options in the settings control to only show ones matching the typed input.
        Parameters:
        visible - a boolean value that sets whether a text field should be presented allowing filtering options or not
      • titleFilter

        public final StringProperty titleFilter()
        Regardless of whether the search box is visible or not, it is possible to filter the options shown on screen using this title filter property. If the search box is visible, it will manipulate this property to contain whatever the user types.
        Returns:
        A SimpleStringProperty.
      • getTitleFilter

        public final String getTitleFilter()
        Returns:
        the filter for filtering the options shown on screen
      • setTitleFilter

        public final void setTitleFilter​(String filter)
        Sets the filter for filtering the options shown on screen.
        Parameters:
        filter - The String to be filtered