Package com.gluonhq.charm.glisten.control

Class SettingsPane

java.lang.Object

javafx.scene.Node

javafx.scene.Parent

javafx.scene.layout.Region

javafx.scene.control.Control

com.gluonhq.charm.glisten.control.SettingsPane

@DefaultProperty("options")
public class SettingsPane
extends javafx.scene.control.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.

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.

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

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

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

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

Since:

2.0.0

See Also:

DefaultOption, OptionBase, OptionEditorBase

Property Summary

Properties

Type	Property	Description
javafx.beans.property.SimpleBooleanProperty	searchBoxVisible	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.

Properties inherited from class javafx.scene.control.Control

contextMenu, skin, tooltip

Properties inherited from class javafx.scene.Node

accessibleHelp, accessibleRoleDescription, accessibleRole, accessibleText, blendMode, boundsInLocal, boundsInParent, cacheHint, cache, clip, cursor, depthTest, disabled, disable, effectiveNodeOrientation, effect, eventDispatcher, focused, focusTraversable, hover, id, inputMethodRequests, layoutBounds, layoutX, layoutY, localToParentTransform, localToSceneTransform, managed, mouseTransparent, nodeOrientation, onContextMenuRequested, onDragDetected, onDragDone, onDragDropped, onDragEntered, onDragExited, onDragOver, onInputMethodTextChanged, onKeyPressed, onKeyReleased, onKeyTyped, onMouseClicked, onMouseDragEntered, onMouseDragExited, onMouseDragged, onMouseDragOver, onMouseDragReleased, onMouseEntered, onMouseExited, onMouseMoved, onMousePressed, onMouseReleased, onRotate, onRotationFinished, onRotationStarted, onScrollFinished, onScroll, onScrollStarted, onSwipeDown, onSwipeLeft, onSwipeRight, onSwipeUp, onTouchMoved, onTouchPressed, onTouchReleased, onTouchStationary, onZoomFinished, onZoom, onZoomStarted, opacity, parent, pickOnBounds, pressed, rotate, rotationAxis, scaleX, scaleY, scaleZ, scene, style, translateX, translateY, translateZ, viewOrder, visible

Properties inherited from class javafx.scene.Parent

needsLayout

Properties inherited from class javafx.scene.layout.Region

background, border, cacheShape, centerShape, height, insets, maxHeight, maxWidth, minHeight, minWidth, opaqueInsets, padding, prefHeight, prefWidth, scaleShape, shape, snapToPixel, width

Field Summary

Fields inherited from class javafx.scene.Node

BASELINE_OFFSET_SAME_AS_HEIGHT

Fields inherited from class javafx.scene.layout.Region

USE_COMPUTED_SIZE, USE_PREF_SIZE

Constructor Summary

Constructors

Constructor	Description
SettingsPane()	Creates a new instance with an empty collection of options
SettingsPane(javafx.collections.ObservableList<Option> options)	Creates a new instance with the given list of options

Method Summary

Modifier and Type	Method	Description
protected javafx.scene.control.Skin<?>	createDefaultSkin()
javafx.util.Callback<Option,OptionEditor<?>>	getOptionEditorFactory()	Returns the editor factory used by the SettingsPane control to determine which OptionEditor to use for a given OptionBase
javafx.collections.ObservableList<Option>	getOptions()	Returns an observable list with the full collection of options
java.lang.String	getTitleFilter()
boolean	isSearchBoxVisible()
javafx.beans.property.SimpleObjectProperty<javafx.util.Callback<Option,OptionEditor<?>>>	optionEditorFactory()	The property editor factory is used by the SettingsPane control to determine which OptionEditor to use for a given OptionBase.
javafx.beans.property.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.
void	setOptionEditorFactory(javafx.util.Callback<Option,OptionEditor<?>> factory)	Sets a new editor factory used by the SettingsPane control to determine which OptionEditor to use for a given OptionBase.
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.
void	setTitleFilter(java.lang.String filter)	Sets the filter for filtering the options shown on screen.
javafx.beans.property.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.

Methods inherited from class javafx.scene.control.Control

computeMaxHeight, computeMaxWidth, computeMinHeight, computeMinWidth, computePrefHeight, computePrefWidth, contextMenuProperty, executeAccessibleAction, getBaselineOffset, getClassCssMetaData, getContextMenu, getControlCssMetaData, getCssMetaData, getInitialFocusTraversable, getSkin, getTooltip, isResizable, layoutChildren, queryAccessibleAttribute, setContextMenu, setSkin, setTooltip, skinProperty, tooltipProperty

Methods inherited from class javafx.scene.Node

accessibleHelpProperty, accessibleRoleDescriptionProperty, accessibleRoleProperty, accessibleTextProperty, addEventFilter, addEventHandler, applyCss, autosize, blendModeProperty, boundsInLocalProperty, boundsInParentProperty, buildEventDispatchChain, cacheHintProperty, cacheProperty, clipProperty, computeAreaInScreen, contains, contains, cursorProperty, depthTestProperty, disabledProperty, disableProperty, effectiveNodeOrientationProperty, effectProperty, eventDispatcherProperty, fireEvent, focusedProperty, focusTraversableProperty, getAccessibleHelp, getAccessibleRole, getAccessibleRoleDescription, getAccessibleText, getBlendMode, getBoundsInLocal, getBoundsInParent, getCacheHint, getClip, getContentBias, getCursor, getDepthTest, getEffect, getEffectiveNodeOrientation, getEventDispatcher, getId, getInitialCursor, getInputMethodRequests, getLayoutBounds, getLayoutX, getLayoutY, getLocalToParentTransform, getLocalToSceneTransform, getNodeOrientation, getOnContextMenuRequested, getOnDragDetected, getOnDragDone, getOnDragDropped, getOnDragEntered, getOnDragExited, getOnDragOver, getOnInputMethodTextChanged, getOnKeyPressed, getOnKeyReleased, getOnKeyTyped, getOnMouseClicked, getOnMouseDragEntered, getOnMouseDragExited, getOnMouseDragged, getOnMouseDragOver, getOnMouseDragReleased, getOnMouseEntered, getOnMouseExited, getOnMouseMoved, getOnMousePressed, getOnMouseReleased, getOnRotate, getOnRotationFinished, getOnRotationStarted, getOnScroll, getOnScrollFinished, getOnScrollStarted, getOnSwipeDown, getOnSwipeLeft, getOnSwipeRight, getOnSwipeUp, getOnTouchMoved, getOnTouchPressed, getOnTouchReleased, getOnTouchStationary, getOnZoom, getOnZoomFinished, getOnZoomStarted, getOpacity, getParent, getProperties, getPseudoClassStates, getRotate, getRotationAxis, getScaleX, getScaleY, getScaleZ, getScene, getStyle, getStyleableParent, getStyleClass, getTransforms, getTranslateX, getTranslateY, getTranslateZ, getTypeSelector, getUserData, getViewOrder, hasProperties, hoverProperty, idProperty, inputMethodRequestsProperty, intersects, intersects, isCache, isDisable, isDisabled, isFocused, isFocusTraversable, isHover, isManaged, isMouseTransparent, isPickOnBounds, isPressed, isVisible, layoutBoundsProperty, layoutXProperty, layoutYProperty, localToParent, localToParent, localToParent, localToParent, localToParent, localToParentTransformProperty, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToSceneTransformProperty, localToScreen, localToScreen, localToScreen, localToScreen, localToScreen, lookupAll, managedProperty, mouseTransparentProperty, nodeOrientationProperty, notifyAccessibleAttributeChanged, onContextMenuRequestedProperty, onDragDetectedProperty, onDragDoneProperty, onDragDroppedProperty, onDragEnteredProperty, onDragExitedProperty, onDragOverProperty, onInputMethodTextChangedProperty, onKeyPressedProperty, onKeyReleasedProperty, onKeyTypedProperty, onMouseClickedProperty, onMouseDragEnteredProperty, onMouseDragExitedProperty, onMouseDraggedProperty, onMouseDragOverProperty, onMouseDragReleasedProperty, onMouseEnteredProperty, onMouseExitedProperty, onMouseMovedProperty, onMousePressedProperty, onMouseReleasedProperty, onRotateProperty, onRotationFinishedProperty, onRotationStartedProperty, onScrollFinishedProperty, onScrollProperty, onScrollStartedProperty, onSwipeDownProperty, onSwipeLeftProperty, onSwipeRightProperty, onSwipeUpProperty, onTouchMovedProperty, onTouchPressedProperty, onTouchReleasedProperty, onTouchStationaryProperty, onZoomFinishedProperty, onZoomProperty, onZoomStartedProperty, opacityProperty, parentProperty, parentToLocal, parentToLocal, parentToLocal, parentToLocal, parentToLocal, pickOnBoundsProperty, pressedProperty, pseudoClassStateChanged, relocate, removeEventFilter, removeEventHandler, requestFocus, resizeRelocate, rotateProperty, rotationAxisProperty, scaleXProperty, scaleYProperty, scaleZProperty, sceneProperty, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, screenToLocal, screenToLocal, screenToLocal, setAccessibleHelp, setAccessibleRole, setAccessibleRoleDescription, setAccessibleText, setBlendMode, setCache, setCacheHint, setClip, setCursor, setDepthTest, setDisable, setDisabled, setEffect, setEventDispatcher, setEventHandler, setFocused, setFocusTraversable, setHover, setId, setInputMethodRequests, setLayoutX, setLayoutY, setManaged, setMouseTransparent, setNodeOrientation, setOnContextMenuRequested, setOnDragDetected, setOnDragDone, setOnDragDropped, setOnDragEntered, setOnDragExited, setOnDragOver, setOnInputMethodTextChanged, setOnKeyPressed, setOnKeyReleased, setOnKeyTyped, setOnMouseClicked, setOnMouseDragEntered, setOnMouseDragExited, setOnMouseDragged, setOnMouseDragOver, setOnMouseDragReleased, setOnMouseEntered, setOnMouseExited, setOnMouseMoved, setOnMousePressed, setOnMouseReleased, setOnRotate, setOnRotationFinished, setOnRotationStarted, setOnScroll, setOnScrollFinished, setOnScrollStarted, setOnSwipeDown, setOnSwipeLeft, setOnSwipeRight, setOnSwipeUp, setOnTouchMoved, setOnTouchPressed, setOnTouchReleased, setOnTouchStationary, setOnZoom, setOnZoomFinished, setOnZoomStarted, setOpacity, setPickOnBounds, setPressed, setRotate, setRotationAxis, setScaleX, setScaleY, setScaleZ, setStyle, setTranslateX, setTranslateY, setTranslateZ, setUserData, setViewOrder, setVisible, snapshot, snapshot, startDragAndDrop, startFullDrag, styleProperty, toBack, toFront, toString, translateXProperty, translateYProperty, translateZProperty, usesMirroring, viewOrderProperty, visibleProperty

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from class javafx.scene.Parent

getChildren, getChildrenUnmodifiable, getManagedChildren, getStylesheets, isNeedsLayout, layout, lookup, needsLayoutProperty, requestLayout, requestParentLayout, setNeedsLayout, updateBounds

Methods inherited from class javafx.scene.layout.Region

backgroundProperty, borderProperty, cacheShapeProperty, centerShapeProperty, getBackground, getBorder, getHeight, getInsets, getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, getOpaqueInsets, getPadding, getPrefHeight, getPrefWidth, getShape, getUserAgentStylesheet, getWidth, heightProperty, insetsProperty, isCacheShape, isCenterShape, isScaleShape, isSnapToPixel, layoutInArea, layoutInArea, layoutInArea, layoutInArea, maxHeight, maxHeightProperty, maxWidth, maxWidthProperty, minHeight, minHeightProperty, minWidth, minWidthProperty, opaqueInsetsProperty, paddingProperty, positionInArea, positionInArea, prefHeight, prefHeightProperty, prefWidth, prefWidthProperty, resize, scaleShapeProperty, setBackground, setBorder, setCacheShape, setCenterShape, setHeight, setMaxHeight, setMaxSize, setMaxWidth, setMinHeight, setMinSize, setMinWidth, setOpaqueInsets, setPadding, setPrefHeight, setPrefSize, setPrefWidth, setScaleShape, setShape, setSnapToPixel, setWidth, shapeProperty, snappedBottomInset, snappedLeftInset, snappedRightInset, snappedTopInset, snapPosition, snapPositionX, snapPositionY, snapSize, snapSizeX, snapSizeY, snapSpace, snapSpaceX, snapSpaceY, snapToPixelProperty, widthProperty

Methods inherited from interface javafx.css.Styleable

getStyleableNode

Property Detail

searchBoxVisible

public final javafx.beans.property.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

SettingsPane

public SettingsPane(javafx.collections.ObservableList<Option> options)

Creates a new instance with the given list of options

Parameters:

options - a ObservableList of options

Method Detail

optionEditorFactory

public final javafx.beans.property.SimpleObjectProperty<javafx.util.Callback<Option,OptionEditor<?>>> optionEditorFactory()

The property editor factory is used by the SettingsPane control to determine which OptionEditor to use for a given OptionBase. A default OptionEditor factory is used, but this may be replaced or extended by developers wishing to add in (or substitute) their own option editors.

Returns:

A SimpleObjectproperty with a Callback that returns a valid OptionEditor

getOptionEditorFactory

public final javafx.util.Callback<Option,OptionEditor<?>> getOptionEditorFactory()

Returns the editor factory used by the SettingsPane control to determine which OptionEditor to use for a given OptionBase

Returns:

a Callback with the OptionEditor used to edit a given Option.

setOptionEditorFactory

public final void setOptionEditorFactory(javafx.util.Callback<Option,OptionEditor<?>> factory)

Sets a new editor factory used by the SettingsPane control to determine which OptionEditor to use for a given OptionBase.

Parameters:

factory - a Callback with the OptionEditor used to edit a given Option

searchBoxVisibleProperty

public final javafx.beans.property.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 javafx.beans.property.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 java.lang.String getTitleFilter()

Returns:

the filter for filtering the options shown on screen

setTitleFilter

public final void setTitleFilter(java.lang.String filter)

Sets the filter for filtering the options shown on screen.

Parameters:

filter - The String to be filtered

getOptions

public javafx.collections.ObservableList<Option> getOptions()

Returns an observable list with the full collection of options

Returns:

ObservableList of options

createDefaultSkin

protected javafx.scene.control.Skin<?> createDefaultSkin()

Overrides:

createDefaultSkin in class javafx.scene.control.Control