- java.lang.Object
-
- javafx.scene.Node
-
- javafx.scene.Parent
-
- javafx.scene.layout.Region
-
- javafx.scene.control.Control
-
- com.gluonhq.charm.glisten.control.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.
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 styledToggleButton
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 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.layout.Region
background, border, cacheShape, centerShape, height, insets, maxHeight, maxWidth, minHeight, minWidth, opaqueInsets, padding, prefHeight, prefWidth, scaleShape, shape, snapToPixel, width
-
Properties inherited from class javafx.scene.Parent
needsLayout
-
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
-
-
Field Summary
-
Fields inherited from class javafx.scene.layout.Region
USE_COMPUTED_SIZE, USE_PREF_SIZE
-
Fields inherited from class javafx.scene.Node
BASELINE_OFFSET_SAME_AS_HEIGHT
-
-
Constructor Summary
Constructors Constructor Description SettingsPane()
Creates a new instance with an empty collection of optionsSettingsPane(ObservableList<Option> options)
Creates a new instance with the given list of options
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description protected Skin<?>
createDefaultSkin()
Callback<Option,OptionEditor<?>>
getOptionEditorFactory()
Returns the editor factory used by the SettingsPane control to determine whichOptionEditor
to use for a givenOptionBase
ObservableList<Option>
getOptions()
Returns an observable list with the full collection ofoptions
String
getTitleFilter()
boolean
isSearchBoxVisible()
SimpleObjectProperty<Callback<Option,OptionEditor<?>>>
optionEditorFactory()
The property editor factory is used by the SettingsPane control to determine whichOptionEditor
to use for a givenOptionBase
.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(Callback<Option,OptionEditor<?>> factory)
Sets a new editor factory used by the SettingsPane control to determine whichOptionEditor
to use for a givenOptionBase
.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(String filter)
Sets the filter for filtering the options shown on screen.StringProperty
titleFilter()
Regardless of whether thesearch 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.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 class javafx.scene.Parent
getChildren, getChildrenUnmodifiable, getManagedChildren, getStylesheets, isNeedsLayout, layout, lookup, needsLayoutProperty, requestLayout, requestParentLayout, setNeedsLayout, updateBounds
-
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 interface javafx.css.Styleable
getStyleableNode
-
-
-
-
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
-
SettingsPane
public SettingsPane(ObservableList<Option> options)
Creates a new instance with the given list of options- Parameters:
options
- aObservableList
ofoptions
-
-
Method Detail
-
optionEditorFactory
public final SimpleObjectProperty<Callback<Option,OptionEditor<?>>> optionEditorFactory()
The property editor factory is used by the SettingsPane control to determine whichOptionEditor
to use for a givenOptionBase
. A defaultOptionEditor
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 validOptionEditor
-
getOptionEditorFactory
public final Callback<Option,OptionEditor<?>> getOptionEditorFactory()
Returns the editor factory used by the SettingsPane control to determine whichOptionEditor
to use for a givenOptionBase
- Returns:
- a
Callback
with theOptionEditor
used to edit a givenOption
.
-
setOptionEditorFactory
public final void setOptionEditorFactory(Callback<Option,OptionEditor<?>> factory)
Sets a new editor factory used by the SettingsPane control to determine whichOptionEditor
to use for a givenOptionBase
.- Parameters:
factory
- aCallback
with theOptionEditor
used to edit a givenOption
-
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 thesearch 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
- TheString
to be filtered
-
getOptions
public ObservableList<Option> getOptions()
Returns an observable list with the full collection ofoptions
- Returns:
ObservableList
ofoptions
-
createDefaultSkin
protected Skin<?> createDefaultSkin()
- Overrides:
createDefaultSkin
in classControl
-
-