Module javafx.controls
Package javafx.scene.control

# Class ButtonBar

java.lang.Object
javafx.scene.Node
javafx.scene.Parent
javafx.scene.layout.Region
javafx.scene.control.Control
javafx.scene.control.ButtonBar

All Implemented Interfaces:
  `Styleable`, `EventTarget`, `Skinnable`

public class ButtonBar extends Control
A ButtonBar is essentially a `HBox`, with the additional functionality for operating system specific button placement. In other words, any Node may be annotated (via the `setButtonData(Node, ButtonData)` method, placed inside a ButtonBar (via the `getButtons()` list), and will then be positioned relative to all other nodes in the button list based on their annotations, as well as the overarching `button order` specified for the ButtonBar.

## Uniform button sizing

By default all buttons are uniformly sized in a ButtonBar, meaning that all buttons take the width of the widest button. It is possible to opt-out of this on a per-button basis, but calling the `setButtonUniformSize(Node, boolean)` method with a boolean value of false.

If a button is excluded from uniform sizing, it is both excluded from being resized away from its preferred size, and also excluded from the measuring process, so its size will not influence the maximum size calculated for all buttons in the ButtonBar.

## Screenshots

Because a ButtonBar comes with built-in support for Windows, Mac OS and Linux, there are three screenshots shown below, with the same buttons laid out on each of the three operating systems.

Windows:

Mac OS:

Linux:

## Code Samples

Instantiating and using the ButtonBar is simple, simply do the following:

     // Create the ButtonBar instance
     ButtonBar buttonBar = new ButtonBar();

     // Create the buttons to go into the ButtonBar
     Button yesButton = new Button("Yes");
     ButtonBar.setButtonData(yesButton, ButtonData.YES);

     Button noButton = new Button("No");
     ButtonBar.setButtonData(noButton, ButtonData.NO);

     // Add buttons to the ButtonBar
     buttonBar.getButtons().addAll(yesButton, noButton);

The code sample above will position the Yes and No buttons relative to the users operating system. This means that on Windows and Linux the Yes button will come before the No button, whereas on Mac OS it'll be No and then Yes.

In most cases the OS-specific layout is the best choice, but in cases where you want a custom layout, this is achieved be modifying the `button order property`. These are cryptic-looking strings that are shorthand representations for the button order. The built-in orders for Windows, Mac OS and Linux are:

ButtonBar Layout Table
Operating System | Button Order
--- | ---
Windows | L_E+U+FBXI_YNOCAH_R
Mac OS | L_HE+U+FBIX_NCYOA_R
Linux | L_HE+UNYACBXIO_R

You should refer to the `ButtonBar.ButtonData` enumeration for a description of what each of these characters mean. However, if your ButtonBar only consisted of `ButtonBar.ButtonData.YES` and `ButtonBar.ButtonData.NO` buttons, you always wanted the yes buttons before the no buttons, and you wanted the buttons to be `right-aligned`, you could do the following:

     // Create the ButtonBar instance
     ButtonBar buttonBar = new ButtonBar();

     // Set the custom button order
     buttonBar.setButtonOrder("+YN");

Since:
  JavaFX 8u40
See Also:
  - `ButtonBar.ButtonData`

## Property Summary

Properties
Type
Property
Description
`final DoubleProperty`
`buttonMinWidth`
Specifies the minimum width of all buttons placed in this button bar.
`final StringProperty`
`buttonOrder`
The order for the typical buttons in a standard button bar.

### 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`

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static enum`
`ButtonBar.ButtonData`
An enumeration of all available button data annotations.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final String`
`BUTTON_ORDER_LINUX`
The default button ordering on Linux (specifically, GNOME).
`static final String`
`BUTTON_ORDER_MAC_OS`
The default button ordering on Mac OS.
`static final String`
`BUTTON_ORDER_NONE`
A button ordering string that specifies there is no button ordering.
`static final String`
`BUTTON_ORDER_WINDOWS`
The default button ordering on Windows.

### 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
`ButtonBar()`
Creates a default ButtonBar instance using the default properties for the users operating system.
`ButtonBar(String buttonOrder)`
Creates a ButtonBar with the given button order (refer to `buttonOrderProperty()` for more information).

## Method Summary

Modifier and Type
Method
Description
`final DoubleProperty`
`buttonMinWidthProperty()`
Specifies the minimum width of all buttons placed in this button bar.
`final StringProperty`
`buttonOrderProperty()`
The order for the typical buttons in a standard button bar.
`protected Skin<?>`
`createDefaultSkin()`
Create a new instance of the default skin for this control.
`static ButtonBar.ButtonData`
`getButtonData(Node button)`
Returns the previously set ButtonData property on the given button.
`final double`
`getButtonMinWidth()`
Returns the minimum width of all buttons placed in this button bar.
`final String`
`getButtonOrder()`
Returns the current `button order`.
`final ObservableList<Node>`
`getButtons()`
Placing buttons inside this ObservableList will instruct the ButtonBar to position them relative to each other based on their specified `ButtonBar.ButtonData`.
`protected Boolean`
`getInitialFocusTraversable()`
Returns the initial focus traversable state of this control, for use by the JavaFX CSS engine to correctly set its initial value.
`static boolean`
`isButtonUniformSize(Node button)`
Returns whether the given node is part of the uniform sizing calculations or not.
`static void`
`setButtonData(Node button, ButtonBar.ButtonData buttonData)`
Sets the given ButtonData on the given button.
`final void`
`setButtonMinWidth(double value)`
Sets the minimum width of all buttons placed in this button bar.
`final void`
`setButtonOrder(String buttonOrder)`
Sets the `button order`
`static void`
`setButtonUniformSize(Node button, boolean uniformSize)`
By default all buttons are uniformly sized in a ButtonBar, meaning that all buttons take the width of the widest button.

### Methods inherited from class javafx.scene.control.Control

`computeMaxHeight, computeMaxWidth, computeMinHeight, computeMinWidth, computePrefHeight, computePrefWidth, contextMenuProperty, executeAccessibleAction, getBaselineOffset, getClassCssMetaData, getContextMenu, getControlCssMetaData, getCssMetaData, 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 Details

### buttonOrder

public final StringProperty buttonOrderProperty
The order for the typical buttons in a standard button bar. It is one letter per `ButtonBar.ButtonData` enumeration value. Default button orders for operating systems are also available: `BUTTON_ORDER_WINDOWS`, `BUTTON_ORDER_MAC_OS`, and `BUTTON_ORDER_LINUX`.

See Also:
  - `getButtonOrder()`
  - `setButtonOrder(String)`
  - `buttonOrderProperty()`

### buttonMinWidth

public final DoubleProperty buttonMinWidthProperty
Specifies the minimum width of all buttons placed in this button bar.

See Also:
  - `getButtonMinWidth()`
  - `setButtonMinWidth(double)`
  - `buttonMinWidthProperty()`

## Field Details

### BUTTON_ORDER_WINDOWS

public static final String BUTTON_ORDER_WINDOWS
The default button ordering on Windows.

See Also:
  - Constant Field Values

### BUTTON_ORDER_MAC_OS

public static final String BUTTON_ORDER_MAC_OS
The default button ordering on Mac OS.

See Also:
  - Constant Field Values

### BUTTON_ORDER_LINUX

public static final String BUTTON_ORDER_LINUX
The default button ordering on Linux (specifically, GNOME).

See Also:
  - Constant Field Values

### BUTTON_ORDER_NONE

public static final String BUTTON_ORDER_NONE
A button ordering string that specifies there is no button ordering. In other words, buttons will be placed in the order that exist in the `getButtons()` list. The only aspect of layout that makes this different than using an HBox is that the buttons are right-aligned.

See Also:
  - Constant Field Values

## Constructor Details

### ButtonBar

public ButtonBar()
Creates a default ButtonBar instance using the default properties for the users operating system.

### ButtonBar

public ButtonBar(String buttonOrder)
Creates a ButtonBar with the given button order (refer to `buttonOrderProperty()` for more information).

Parameters:
  `buttonOrder` - The button order to use in this button bar instance.

## Method Details

### setButtonData

public static void setButtonData(Node button, ButtonBar.ButtonData buttonData)
Sets the given ButtonData on the given button. If this button is subsequently placed in a `ButtonBar` it will be placed in the correct position relative to all other buttons in the bar.

Parameters:
  `button` - The button to annotate with the given `ButtonBar.ButtonData` value.
  `buttonData` - The ButtonData to designate the button as.

### getButtonData

public static ButtonBar.ButtonData getButtonData(Node button)
Returns the previously set ButtonData property on the given button. If this was never set, this method will return null.

Parameters:
  `button` - The button to return the previously set ButtonData for.
Returns:
  the previously set ButtonData property on the given button

### setButtonUniformSize

public static void setButtonUniformSize(Node button, boolean uniformSize)
By default all buttons are uniformly sized in a ButtonBar, meaning that all buttons take the width of the widest button. It is possible to opt-out of this on a per-button basis, but calling the setButtonUniformSize method with a boolean value of false.

If a button is excluded from uniform sizing, it is both excluded from being resized away from its preferred size, and also excluded from the measuring process, so its size will not influence the maximum size calculated for all buttons in the ButtonBar.

Parameters:
  `button` - The button to include / exclude from uniform sizing.
  `uniformSize` - Boolean true to force uniform sizing on the button, false to exclude the button from uniform sizing.

### isButtonUniformSize

public static boolean isButtonUniformSize(Node button)
Returns whether the given node is part of the uniform sizing calculations or not. By default all nodes that have not opted out (via `setButtonUniformSize(Node, boolean)`) will return true here.

Parameters:
  `button` - the button
Returns:
  true if button is part of the uniform sizing calculations

### createDefaultSkin

protected Skin<?> createDefaultSkin()
Create a new instance of the default skin for this control. This is called to create a skin for the control if no skin is provided via CSS `-fx-skin` or set explicitly in a sub-class with `setSkin(...)`.

Overrides:
  `createDefaultSkin` in class `Control`
Returns:
  new instance of default skin for this control. If null then the control will have no skin unless one is provided by css.

### getButtons

public final ObservableList<Node> getButtons()
Placing buttons inside this ObservableList will instruct the ButtonBar to position them relative to each other based on their specified `ButtonBar.ButtonData`. To set the ButtonData for a button, simply call `setButtonData(Node, ButtonData)`, passing in the relevant ButtonData.

Returns:
  A list containing all buttons currently in the button bar, and allowing for further buttons to be added or removed.

### buttonOrderProperty

public final StringProperty buttonOrderProperty()
The order for the typical buttons in a standard button bar. It is one letter per `ButtonBar.ButtonData` enumeration value. Default button orders for operating systems are also available: `BUTTON_ORDER_WINDOWS`, `BUTTON_ORDER_MAC_OS`, and `BUTTON_ORDER_LINUX`.

Returns:
  the button order property
See Also:
  - `getButtonOrder()`
  - `setButtonOrder(String)`

### setButtonOrder

public final void setButtonOrder(String buttonOrder)
Sets the `button order`

Parameters:
  `buttonOrder` - The currently set button order, which by default will be the OS-specific button order.

### getButtonOrder

public final String getButtonOrder()
Returns the current `button order`.

Returns:
  The current `button order`.

### buttonMinWidthProperty

public final DoubleProperty buttonMinWidthProperty()
Specifies the minimum width of all buttons placed in this button bar.

Returns:
  the minimum width property
See Also:
  - `getButtonMinWidth()`
  - `setButtonMinWidth(double)`

### setButtonMinWidth

public final void setButtonMinWidth(double value)
Sets the minimum width of all buttons placed in this button bar.

Parameters:
  `value` - the minimum width value

### getButtonMinWidth

public final double getButtonMinWidth()
Returns the minimum width of all buttons placed in this button bar.

Returns:
  the minimum width value

### getInitialFocusTraversable

protected Boolean getInitialFocusTraversable()
Returns the initial focus traversable state of this control, for use by the JavaFX CSS engine to correctly set its initial value. This method is overridden as by default UI controls have focus traversable set to true, but that is not appropriate for this control.

Overrides:
  `getInitialFocusTraversable` in class `Control`
Returns:
  the initial focus traversable state of this control
Since:
  9