JavaFX 24 · javafx.scene.control · APIdia, the JavaDoc alternative

The JavaFX User Interface Controls (UI Controls or just Controls) are specialized Nodes in the JavaFX Scenegraph especially suited for reuse in many different application contexts. They are designed to be highly customizable visually by designers and developers. They are designed to work well with layout systems. Examples of prominent controls include Button, Label, ListView, and TextField.

Since Controls are Nodes in the scenegraph, they can be freely mixed with Groups, Images, Media, Text, and basic geometric shapes. While writing new UI Controls is not trivial, using and styling them is very easy, especially to existing web developers.

The remainder of this document will describe the basic architecture of the JavaFX UI Control library, how to style existing controls, write custom skins, and how to use controls to build up more complicated user interfaces.

Architecture

Controls follow the classic MVC design pattern. The Control is the "model". It contains both the state and the functions which manipulate that state. The Control class itself does not know how it is rendered or what the user interaction is. These tasks are delegated to the Skin ("view"), which may internally separate out the view and controller functionality into separate classes, although at present there is no public API for the "controller" aspect.

All Controls extend from the Control class, which is in turn a Parent node, and which is a Node. Every Control has a reference to a single Skin, which is the view implementation for the Control. The Control delegates to the Skin the responsibility of computing the min, max, and pref sizes of the Control, the baseline offset, and hit testing (containment and intersection). It is also the responsibility of the Skin, or a delegate of the Skin, to implement and respond to all relevant key events which occur on the Control when it contains the focus.

Control

Control extends from Parent, and as such, is not a leaf node. From the perspective of a developer or designer the Control can be thought of as if it were a leaf node in many cases. For example, the developer or designer can consider a Button as if it were a Rectangle or other simple leaf node.

Since a Control is resizable, a Control will be auto-sized to its preferred size on each scenegraph pulse. Setting the width and height of the Control does not affect its preferred size. When used in a layout container, the layout constraints imposed upon the Control (or manually specified on the Control) will determine how it is positioned and sized.

The Skin of a Control can be changed at any time. Doing so will mark the Control as needing to be laid out since changing the Skin likely has changed the preferred size of the Control. If no Skin is specified at the time that the Control is created, then a default CSS-based skin will be provided for all of the built-in Controls.

Each Control may have an optional tooltip specified. The Tooltip is a Control which displays some (usually textual) information about the control to the user when the mouse hovers over the Control from some period of time. It can be styled from CSS the same as with other Controls.

focusTraversable is overridden in Control to be true by default, whereas with Node it is false by default. Controls which should not be focusable by default (such as Label) override this to be false.

The getMinWidth, getMinHeight, getPrefWidth, getPrefHeight, getMaxWidth, and getMaxHeight functions are delegated directly to the Skin. The baselineOffset method is delegated to the node of the skin. It is not recommended that subclasses alter these delegations.

Styling Controls

There are two methods for customizing the look of a Control. The most difficult and yet most flexible approach is to write a new Skin for the Control which precisely implements the visuals which you desire for the Control. Consult the Skin documentation for more details.

The easiest and yet very powerful method for styling the built in Controls is by using CSS. Please note that in this release the following CSS description applies only to the default Skins provided for the built in Controls. Subsequent releases will make this generally available for any custom third party Controls which desire to take advantage of these CSS capabilities.

Each of the default Skins for the built in Controls is comprised of multiple individually styleable areas or regions. This is much like an HTML page which is made up of <div>'s and then styled from CSS. Each individual region may be drawn with backgrounds, borders, images, padding, margins, and so on. The JavaFX CSS support includes the ability to have multiple backgrounds and borders, and to derive colors. These capabilities make it extremely easy to alter the look of Controls in JavaFX from CSS.

The colors used for drawing the default Skins of the built in Controls are all derived from a base color, an accent color and a background color. Simply by modifying the base color for a Control you can alter the derived gradients and create Buttons or other Controls which visually fit in with the default Skins but visually stand out.

As with all other Nodes in the scenegraph, Controls can be styled by using an external stylesheet, or by specifying the style directly on the Control. Although for examples it is easier to express and understand by specifying the style directly on the Node, it is recommended to use an external stylesheet and use either the styleClass or id of the Control, just as you would use the "class" or id of an HTML element with HTML CSS.

Each UI Control specifies a styleClass which may be used to style controls from an external stylesheet. For example, the Button control is given the "button" CSS style class. The CSS style class names are hyphen-separated lower case as opposed to camel case, otherwise, they are exactly the same. For example, Button is "button", RadioButton is "radio-button", Tooltip is "tooltip" and so on.

The class documentation for each Control defines the default Skin regions which can be styled. For further information regarding the CSS capabilities provided with JavaFX, see the CSS Reference Guide.

Modifier and Type	Interface and Description
public interface	Skin< A subtype of Skinnable that the Skin represents. This allows for Skin implementation to access the `Skinnable` implementation, which is usually a `Control` implementation. C extends Skinnable> An interface for defining the visual representation of user interface controls.
public interface	Skinnable The Skinnable interface is implemented by the `Control` class, and therefore is implemented by all Control implementations.
public interface	Toggle Represents a control that can be toggled between selected and non-selected states.

Class Summary

Modifier and Type	Class and Description
public class	Accordion An accordion is a group of `TitlePanes`.
public class	Alert The Alert class subclasses the `Dialog` class, and provides support for a number of pre-built dialog types that can be easily shown to users to prompt for a response.
public class	Button A simple button control.
public class	ButtonBar A ButtonBar is essentially a `HBox`, with the additional functionality for operating system specific button placement.
public abstract class	ButtonBase Base class for button-like UI Controls, including Hyperlinks, Buttons, ToggleButtons, CheckBoxes, and RadioButtons.
public class	ButtonType The ButtonType class is used as part of the JavaFX `Dialog` API (more specifically, the `DialogPane` API) to specify which buttons should be shown to users in the dialogs.
public class	Cell< The type of the item contained within the Cell. T> The Cell API is used for virtualized controls such as `ListView`, `TreeView`, and `TableView`.
public class	CheckBox A tri-state selection Control typically skinned as a box with a checkmark or tick mark when checked.
public class	CheckBoxTreeItem< The type of the value contained within the TreeItem T> TreeItem subclass that adds support for being in selected, unselected, and indeterminate states.
public class	CheckMenuItem A `MenuItem` that can be toggled between selected and unselected states.
public class	ChoiceBox< the type of the item contained within the ChoiceBox T> The ChoiceBox is used for presenting the user with a relatively small set of predefined choices from which they may choose.
public class	ChoiceDialog< The type of the items to show to the user, and the type that is returned via `getResult()` when the dialog is dismissed. T> A dialog that shows a list of choices to the user, from which they can pick one item at most.
public class	ColorPicker ColorPicker control allows the user to select a color from either a standard palette of colors with a simple one click selection OR define their own custom color.
public class	ComboBox< The type of the value that has been selected or otherwise entered in to this ComboBox T> An implementation of the `ComboBoxBase` abstract class for the most common form of ComboBox, where a popup list is shown to users providing them with a choice that they may select from.
public abstract class	ComboBoxBase< The type of the value that has been selected or otherwise entered in to this ComboBox. T> Abstract base class for ComboBox-like controls.
public abstract class	ConstrainedColumnResizeBase Base class for a constrained column resize policy.
public class	ContextMenu A popup control containing an ObservableList of menu items.
public abstract class	Control Base class for all user interface controls.
pack-priv class	ControlUtils
public class	CustomMenuItem A `MenuItem` that allows for arbitrary nodes to be embedded within it, by assigning a `Node` to the `content` property.
public class	DateCell DateCell is used by `DatePicker` to render the individual grid cells in the calendar month.
public class	DatePicker The DatePicker control allows the user to enter a date as text or to select a date from a calendar popup.
public class	Dialog< The return type of the dialog, via the `result` property. R> A Dialog in JavaFX wraps a `DialogPane` and provides the necessary API to present it to end users.
public class	DialogEvent Event related to dialog showing/hiding actions.
public class	DialogPane DialogPane should be considered to be the root node displayed within a `Dialog` instance.
public abstract class	FocusModel< the type of the focused item T> The abstract base class for FocusModel implementations.
pack-priv abstract class	FXDialog
pack-priv class	HeavyweightDialog
public class	Hyperlink An HTML like label which can be a graphic and/or text which responds to rollovers and clicks.
public class	IndexedCell< The type of the item contained within the Cell. T> An implementation of `Cell` which contains an index property which maps into the data model underlying the visualization.
public class	IndexRange Class representing a contiguous range of integral values.
public class	Label Label is a non-editable text control.
public abstract class	Labeled A Labeled `Control` is one which has as part of its user interface a textual content associated with it.
public class	ListCell< The type of the item contained within the ListCell. T> The `Cell` type used within `ListView` instances.
public class	ListView< This type is used to represent the type of the objects stored in the ListViews `items` ObservableList. It is also used in the `selection model` and `focus model`. T> A ListView displays a horizontal or vertical list of items from which the user may select, or with which the user may interact.
public class	Menu A popup menu of actionable items which is displayed to the user only upon request.
public class	MenuBar A MenuBar control traditionally is placed at the very top of the user interface, and embedded within it are `Menus`.
public class	MenuButton MenuButton is a button which, when clicked or pressed, will show a `ContextMenu`.
public class	MenuItem MenuItem is intended to be used in conjunction with `Menu` to provide options to users.
public abstract class	MultipleSelectionModel< The type of the item contained in the control that can be selected. T> An abstract class that extends `SelectionModel` to add API to support multiple selection.
pack-priv abstract class	MultipleSelectionModelBase< The type of the underlying data model for the UI control. T> An abstract class that implements more of the abstract MultipleSelectionModel abstract class.
public class	Pagination A Pagination control is used for navigation between pages of a single content, which has been divided into smaller parts.
public class	PasswordField Text field that masks entered characters.
public class	PopupControl An extension of PopupWindow that allows for CSS styling.
public class	ProgressBar A specialization of the ProgressIndicator which is represented as a horizontal bar.
public class	ProgressIndicator A circular control which is used for indicating progress, either infinite (aka indeterminate) or finite.
public class	RadioButton RadioButtons create a series of items where only one item can be selected.
public class	RadioMenuItem A RadioMenuItem is a `MenuItem` that can be toggled (it uses the `Toggle` mixin).
public abstract class	ResizeFeaturesBase< the type of the objects contained within the control's items list S> A wrapper class for use by the column resize policies offered by controls such as `TableView` and `TreeTableView`.
public class	ScrollBar Either a horizontal or vertical bar with increment and decrement buttons and a "thumb" with which the user can interact.
public class	ScrollPane A Control that provides a scrolled, clipped viewport of its contents.
public class	ScrollToEvent< the scroll-to event type T> Event related to `ScrollPane` and virtualised controls such as `ListView`, `TableView`, `TreeView` and `TreeTableView`.
public abstract class	SelectionModel< The type of the item contained in the control that can be selected. T> SelectionModel is an abstract class used by UI controls to provide a consistent API for maintaining selection.
public class	Separator A horizontal or vertical separator line.
public class	SeparatorMenuItem A `MenuItem` that as the name suggests allows for a horizontal Separator to be embedded within it, by assigning a `Separator` to the `content` property of the `CustomMenuItem` This is provided for convenience as groups of `menuitems` can be separated by a separator.
public abstract class	SingleSelectionModel< The type of the item contained in the control that can be selected. T> A SelectionModel which enforces the requirement that only a single index be selected at any given time.
public abstract class	SkinBase< the type of the control C extends Control> Base implementation class for defining the visual representation of user interface controls by defining a scene graph of nodes to represent the `skin`.
public class	Slider The Slider Control is used to display a continuous or discrete range of valid numeric choices and allows the user to interact with the control.
public class	SortEvent< the type of control C> Event related to `TableView` and `TreeTableView` sorting.
public class	Spinner< The type of all values that can be iterated through in the Spinner. Common types include Integer and String. T> A single line text field that lets the user select a number or an object value from an ordered sequence.
public abstract class	SpinnerValueFactory< The type of the data this value factory deals with, which must coincide with the type of the Spinner that the value factory is set on. T> The SpinnerValueFactory is the model behind the JavaFX `Spinner control` - without a value factory installed a Spinner is unusable.
public class	SplitMenuButton The SplitMenuButton, like the `MenuButton` is closely associated with the concept of selecting a `MenuItem` from a menu.
public class	SplitPane A control that has two or more sides, each separated by a divider, which can be dragged by the user to give more space to one of the sides, resulting in the other side shrinking by an equal amount.
public class	Tab Tabs are placed within a `TabPane`, where each tab represents a single 'page'.
public class	TableCell< The type of the TableView generic type (i.e. S == TableView<S>). This should also match with the first generic type in TableColumn. S, The type of the item contained within the Cell. T> Represents a single row/column intersection in a `TableView`.
public class	TableColumn< The type of the TableView generic type (i.e. S == TableView<S>) S, The type of the content in all cells in this TableColumn. T> A `TableView` is made up of a number of TableColumn instances.
public abstract class	TableColumnBase< The type of the UI control (e.g. the type of the 'row'). S, The type of the content in all cells in this table column. T> Table-like controls (such as `TableView` and `TreeTableView`) are made up of zero or more instances of a concrete TableColumnBase subclass (`TableColumn` and `TreeTableColumn`, respectively).
public abstract class	TableFocusModel< The type of the underlying data model for the UI control. T, The concrete subclass of `TableColumnBase` that is used by the underlying UI control (e.g. `TableColumn` or `TreeTableColumn`. TC extends TableColumnBase<T, ?>> The abstract base class for FocusModel implementations that are used within table-like controls (most notably `TableView` and `TreeTableView`).
public class	TablePosition< The type of the items contained within the TableView (i.e. the same generic type as the S in TableView<S>). S, The type of the items contained within the TableColumn. T> This class is used to represent a single row/column/cell in a TableView.
public abstract class	TablePositionBase< the type of the TableColumnBase TC extends TableColumnBase<S, T>> This class is used to represent a single row/column/cell in a table.
public class	TableRow< The type of the item contained within the Cell. T> TableRow is an `IndexedCell`, but rarely needs to be used by developers creating TableView instances.
public abstract class	TableSelectionModel< The type of the underlying data model for the UI control. T> The abstract base class for MultipleSelectionModel implementations that are used within table-like controls (most notably `TableView` and `TreeTableView`).
pack-priv class	TableUtil A package protected util class used by TableView and TreeTableView to reduce the level of code duplication.
public class	TableView< The type of the objects contained within the TableView items list. S> The TableView control is designed to visualize an unlimited number of rows of data, broken out into columns.
public class	TabPane A control that allows switching between a group of `Tabs`.
public class	TextArea Text input component that allows a user to enter multiple lines of plain text.
public class	TextField Text input component that allows a user to enter a single line of unformatted text.
public class	TextFormatter< The type of the value V> A Formatter describes a format of a `TextInputControl` text by using two distinct mechanisms: A filter (`getFilter()`) that can intercept and modify user input. This helps to keep the text in the desired format. A default text supplier can be used to provide the initial text. A value converter (`getValueConverter()`) and value (`valueProperty()`) can be used to provide special format that represents a value of type `V`. If the control is editable and the text is changed by the user, the value is then updated to correspond to the text.
public abstract class	TextInputControl Abstract base class for text input controls.
public class	TextInputDialog A dialog that shows a text input control to the user.
public class	TitledPane A TitledPane is a panel with a title that can be opened and closed.
public class	ToggleButton A `ToggleButton` is a specialized control which has the ability to be selected.
public class	ToggleGroup A class which contains a reference to all `Toggles` whose `selected` variables should be managed such that only a single `Toggle` within the `ToggleGroup` may be selected at any one time.
public class	ToolBar A ToolBar is a control which displays items horizontally or vertically.
public class	Tooltip Tooltips are common UI elements which are typically used for showing additional information about a Node in the scenegraph when the Node is hovered over by the mouse.
public class	TreeCell< The type of the value contained within the `TreeItem` property. T> The `Cell` type used with the `TreeView` control.
public class	TreeItem< The type of the `value` property within TreeItem. T> The model for a single node supplying a hierarchy of values to a control such as `TreeView`.
public class	TreeTableCell< The type of the TreeTableView generic type S, The type of the item contained within the Cell. T> Represents a single row/column intersection in a `TreeTableView`.
public class	TreeTableColumn< The type of the TableView generic type (i.e. S == TableView<S>) S, The type of the content in all cells in this TableColumn. T> A `TreeTableView` is made up of a number of TreeTableColumn instances.
public class	TreeTablePosition< The type of the `TreeItem` instances contained within the TreeTableView. S, The type of the items contained within the TreeTableColumn. T> This class is used to represent a single row/column/cell in a TreeTableView.
public class	TreeTableRow< The type of the item contained within the Cell. T> TreeTableRow is an `IndexedCell`, but rarely needs to be used by developers creating TreeTableView instances.
public class	TreeTableView< The type of the TreeItem instances used in this TreeTableView. S> The TreeTableView control is designed to visualize an unlimited number of rows of data, broken out into columns.
pack-priv class	TreeUtil A package protected util class used by TreeView and TreeTableView to reduce the level of code duplication.
public class	TreeView< The type of the item contained within the `TreeItem` value property for all tree items in this TreeView. T> The TreeView control provides a view on to a tree root (of type `TreeItem`).

Modifier and Type	Enum and Description
public enum	ContentDisplay The position to place the content within a Label.
public enum	OverrunStyle Defines the behavior of a labeled Control when the space for rendering the text is smaller than the space needed to render the entire string.
public enum	SelectionMode An enumeration used to specify how many items may be selected in a `MultipleSelectionModel`.
public enum	TreeSortMode Specifies how the tree items in tree-like UI controls should be sorted.

Package javafx.scene.control

Architecture

Control

Styling Controls

Interface Summary

Class Summary

Enum Summary