@DefaultProperty(value="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.
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);
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));
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);
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);
DefaultOption
,
OptionBase
,
OptionEditorBase
Type | Property and 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.
|
contextMenu, skinClassName, skin, tooltip
background, border, cacheShape, centerShape, height, insets, maxHeight, maxWidth, minHeight, minWidth, opaqueInsets, padding, prefHeight, prefWidth, scaleShape, shape, snapToPixel, width
accessibleHelp, accessibleRoleDescription, accessibleRole, accessibleText, blendMode, boundsInLocal, boundsInParent, cacheHint, cache, clip, cursor, depthTest, disabled, disable, effectiveNodeOrientation, effect, eventDispatcher, focused, focusTraversable, hover, id, impl_showMnemonics, impl_treeVisible, 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, visible
Constructor and 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
|
Modifier and Type | Method and 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. |
computeMaxHeight, computeMaxWidth, computeMinHeight, computeMinWidth, computePrefHeight, computePrefWidth, contextMenuProperty, executeAccessibleAction, getBaselineOffset, getClassCssMetaData, getContextMenu, getControlCssMetaData, getCssMetaData, getSkin, getTooltip, impl_cssGetFocusTraversableInitialValue, impl_processCSS, isResizable, layoutChildren, queryAccessibleAttribute, setContextMenu, setSkin, setTooltip, skinClassNameProperty, skinProperty, tooltipProperty
backgroundProperty, borderProperty, cacheShapeProperty, centerShapeProperty, getBackground, getBorder, getHeight, getInsets, getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, getOpaqueInsets, getPadding, getPrefHeight, getPrefWidth, getShape, getUserAgentStylesheet, getWidth, heightProperty, impl_computeContains, impl_computeGeomBounds, impl_computeLayoutBounds, impl_createPeer, impl_notifyLayoutBoundsChanged, impl_pickNodeLocal, impl_updatePeer, 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, snapSize, snapSpace, snapToPixelProperty, widthProperty
getChildren, getChildrenUnmodifiable, getImpl_traversalEngine, getManagedChildren, getStylesheets, impl_getAllParentStylesheets, impl_processMXNode, impl_traversalEngineProperty, isNeedsLayout, layout, lookup, needsLayoutProperty, requestLayout, requestParentLayout, setImpl_traversalEngine, setNeedsLayout, updateBounds
accessibleHelpProperty, accessibleRoleDescriptionProperty, accessibleRoleProperty, accessibleTextProperty, addEventFilter, addEventHandler, applyCss, autosize, blendModeProperty, boundsInLocalProperty, boundsInParentProperty, buildEventDispatchChain, cacheHintProperty, cacheProperty, clipProperty, computeAreaInScreen, contains, contains, containsBounds, 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, 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, hasProperties, hoverProperty, idProperty, impl_clearDirty, impl_computeIntersects, impl_cssGetCursorInitialValue, impl_findStyles, impl_geomChanged, impl_getLeafTransform, impl_getMatchingStyles, impl_getPeer, impl_getPivotX, impl_getPivotY, impl_getPivotZ, impl_getStyleMap, impl_hasTransforms, impl_intersects, impl_intersectsBounds, impl_isDirty, impl_isDirtyEmpty, impl_isShowMnemonics, impl_isTreeVisible, impl_layoutBoundsChanged, impl_markDirty, impl_pickNode, impl_processCSS, impl_reapplyCSS, impl_setShowMnemonics, impl_setStyleMap, impl_showMnemonicsProperty, impl_syncPeer, impl_transformsChanged, impl_traverse, impl_treeVisibleProperty, 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, setVisible, snapshot, snapshot, startDragAndDrop, startFullDrag, styleProperty, toBack, toFront, toString, translateXProperty, translateYProperty, translateZProperty, usesMirroring, visibleProperty
public final javafx.beans.property.SimpleBooleanProperty searchBoxVisibleProperty
isSearchBoxVisible()
,
setSearchBoxVisible(boolean)
public SettingsPane()
public final javafx.beans.property.SimpleObjectProperty<javafx.util.Callback<Option,OptionEditor<?>>> optionEditorFactory()
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.Callback
that returns a
valid OptionEditor
public final javafx.util.Callback<Option,OptionEditor<?>> getOptionEditorFactory()
OptionEditor
to use for a given OptionBase
Callback
with the OptionEditor
used
to edit a given Option
.public final void setOptionEditorFactory(javafx.util.Callback<Option,OptionEditor<?>> factory)
OptionEditor
to use for a given OptionBase
.factory
- a Callback
with the OptionEditor
used
to edit a given Option
public final javafx.beans.property.SimpleBooleanProperty searchBoxVisibleProperty()
isSearchBoxVisible()
,
setSearchBoxVisible(boolean)
public final boolean isSearchBoxVisible()
public final void setSearchBoxVisible(boolean visible)
visible
- a boolean value that sets whether a text field should be presented
allowing filtering options or notpublic final javafx.beans.property.StringProperty titleFilter()
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.public final java.lang.String getTitleFilter()
public final void setTitleFilter(java.lang.String filter)
filter
- The String
to be filteredpublic javafx.collections.ObservableList<Option> getOptions()
options
ObservableList
of options
protected javafx.scene.control.Skin<?> createDefaultSkin()
createDefaultSkin
in class javafx.scene.control.Control