Composite GUI Elements - jMonkeyEngine-Contributions/Lemur GitHub Wiki
Composite GUI Elements
These are documented separately because these elements compose a set of child elements together to form a more complex UI element. Typically, these use only the previously documented Base Elements. The documentation here will differ a little since it will also note what the style element IDs are for the children as that becomes extremely important when tweaking custom styles.
In most cases, the composite elements also provide direct access to their children for direct configuration when styling is not enough or isn't desired. See the element-specific javadoc for child getters as they are not documented here.
Slider
Presents an adjustable value to the user as a sliding button with increment/decrement buttons at each end. The slider can either be x-axis aligned or y-axis aligned. (Z-axis alignment is not yet supported.)
Example of x-axis and y-axis sliders in 'glass' style.
The slider gets the value it displays by watching a RangedValueModel object and sets edited values by setting them back to that model. DefaultRangedValueModel provides default support for the observability required but developers are free to write their own RangedValueModel implementation that directly talks to their data model objects if necessary.
Properties:
- model: The RangedValueModel object that provides access to the value that the slider displays/edits. The default value is a DefaultRangedValueModel set from 0 to 100.
- delta: The amount to adjust the value up or down when the increment and decrement buttons are used.
For styling, each nested element's style element ID is based on the element ID used when creating the slider. By default this is "slider". The relative IDs are as follows:
- .up.button: In y-axis orientation, this is the increment button.
- .down.button: In y-axis orientation, this is the decrement button.
- .left.button: In x-axis orientation, this is the decrement button.
- .right.button: In x-axis orientation, this is the increment button.
- .thumb.button: The button that slides to change the value.
- .range: The background of the area between the increment and decrement buttons.
ProgressBar
Presents a changing progress value as a bar that fills as the value reaches 100% of some bounded range. The component can also optionally display the value itself and/or other text super-imposed over the progress bar.
Example of ProgressBar with a message using the 'glass' style.
The progress value can be set directly on the ProgressBar which internally keeps a RangedValueModel. Alternately, callers are free to provide their own RangedValueModel as appropriate.
Properties:
- progressPercent: The progress value as a value between 0 and 1.0. This delegates directly to the ProgressBar's RangedValueModel.
- progressValue: The raw value relative to the range. This delegates directly to the ProgressBar's RangedValueModel.
- model: The RangedValueModel that the progress bar uses as a display value. Defaults to a DefaultRangedValueModel set for 0 to 100.
- message: The text that is displayed over the progess area.
For styling, each nested element's style element ID is based on the element ID used when creating the slider. By default this is "progress". The relative IDs are as follows:
- .container: The actual style element ID of the progress bar itself. Note: it is not a Container but a Panel the name is semantic with respect to it's relationship to the other child elements.
- .label: The label that displays the progress message.
- .value: The Panel that grows/shrinks to show the progress value within the .container.
Selector aka Dropdown (proto)
Presents a single option with a button to open up a floating listbox with all the available choices
ListBox (proto)
Presents a list of values to the user that can be selected. A scroll bar is provided to allow presenting more values than would otherwise fit in one view.
TabbedPanel
Presents a set of multiple 'tabs' that each contain child panels. One tab is displayed at a time. This is a useful way of breaking up complex user interfaces into multiple sections.
RollupPanel
Presents a child panel with a 'rollup' button that will expand/collapse the child. This is a useful way to stack multiple complex panels together in a way where they user can choose which ones are relevant at any particular moment and 'rollup' the rest to save space.
GridPanel (proto)
Presents a subset grid of Panels as defined by a GridModel. The GridModel can logically contain more values than can be displayed and the GridPanel will display a localized subset based on the current row/column and visibleRows/visibleColumns values. This is the foundation for list box and table GUI elements.
OptionPanel and State (proto)
OptionPanel presents an option title, a message, and a set of option actions to the user. The message portion of the panel can be augmented with additional components as needed. This is similar to Swing's JOptionPane in functionality and can be used for quickly presenting info, error, or warning types of messages to the user. It can also be extended to ask for specific values (say if the message element is enhanced to have a TextField or other selector).
OptionPanelState provides modal option panel support where the option panel is the only thing that can receive mouse/touch input until closed. Simply add this once to the state manager and the app can easily present modal messages to the user using the convenience show() and showError() methods.
See also: OptionPanel javadoc and: OptionPanelState javadoc
ActionButton (proto)
Extends Button to wrap an Action object. Actions are 'command' objects (in the 'Command Pattern' sense) that additional provide observable properties for name, icon, etc.. This is convenient for code that wants to fully define some application function without worrying about how it will be used or displayed. The same Action can be used in multiple Buttons and so it's also a convenient way to have commands that can alter their own button's state even when shared across multiple Buttons. For example, an Action that appears in a menu might have both icon and state while an Action that appears in a toolbar might only have icon. If they share the same Action object then changing the icon on the action would change it in both places in the user interface.
This is quite similar to Swing's Action support.