Class HeaderBar

java.lang.Object
javafx.scene.Node
javafx.scene.Parent
javafx.scene.layout.Region
javafx.scene.layout.HeaderBar
All Implemented Interfaces:
Styleable, EventTarget
@Deprecated(since="25") public class HeaderBar extends Region
Deprecated.
This is a preview feature which may be changed or removed in a future release.
A client-area header bar that is used as a replacement for the system-provided header bar in stages with the StageStyle.EXTENDED style. This class enables the click-and-drag to move and double-click to maximize behaviors that are usually afforded by system-provided header bars. The entire HeaderBar background is draggable by default, but its content is not. Applications can specify draggable content nodes of the HeaderBar with the setDragType(Node, HeaderDragType) method.

HeaderBar is a layout container that allows applications to place scene graph nodes in three areas: leading, center, and trailing. All areas can be null. The default minHeight of the HeaderBar is set to match the height of the platform-specific default header buttons.

Single header bar

Most applications should only add a single HeaderBar to the scene graph, placed at the top of the scene and extending its entire width. This ensures that the reported values for leftSystemInset and rightSystemInset, which describe the area reserved for the system-provided window buttons, correctly align with the location of the HeaderBar and are taken into account when the contents of the HeaderBar are laid out.

Multiple header bars

Applications that use multiple header bars might need to configure the additional padding inserted into the layout to account for the system-reserved areas. For example, when two header bars are placed next to each other in the horizontal direction, the default configuration incorrectly adds additional padding between the two header bars. In this case, the leadingSystemPadding and trailingSystemPadding properties can be used to remove the padding that is not needed.

Header button height

Applications can specify the preferred height for system-provided header buttons by setting the static setPrefButtonHeight(Stage, double) property on the Stage associated with the header bar. This can be used to achieve a more cohesive visual appearance by having the system-provided header buttons match the height of the client-area header bar.

Custom header buttons

If more control over the header buttons is desired, applications can opt out of the system-provided header buttons by setting setPrefButtonHeight(Stage, double) to zero and place custom header buttons in the JavaFX scene graph instead. Any JavaFX control can be used as a custom header button by setting its semantic type with the setButtonType(Node, HeaderButtonType) method.

System menu

Some platforms support a system menu that can be summoned by right-clicking the draggable area. The system menu will not be shown when:
  1. the Stage is in full-screen mode, or
  2. the HeaderBar has consumed the ContextMenuEvent.CONTEXT_MENU_REQUESTED event.

Layout constraints

The leading and trailing children will be resized to their preferred widths and extend the height of the HeaderBar. The center child will be resized to fill the available space. HeaderBar honors the minimum, preferred, and maximum sizes of its children. If a child's resizable range prevents it from be resized to fit within its position, it will be vertically centered relative to the available space; this alignment can be customized with a layout constraint.

An application may set constraints on individual children to customize their layout. For each constraint, HeaderBar provides static getter and setter methods.

Layout constraints of HeaderBar
ConstraintTypeDescription
alignmentPos The alignment of the child within its area of the HeaderBar.
margin InsetsMargin space around the outside of the child.

Special layout of centered child

If a child is configured to be centered in the center area (i.e. its alignment constraint is either null, Pos.CENTER, Pos.TOP_CENTER, or Pos.BOTTOM_CENTER), it will be centered with respect to the entire header bar, and not with respect to the center area only. This means that, for a header bar that extends the entire width of the Stage, the child will appear to be horizontally centered within the Stage.

If a child should instead be centered with respect to the center area only, a possible solution is to place another layout container like BorderPane in the center area, and then center the child within the other layout container.

Example

Usually, HeaderBar is placed in a root container like BorderPane to align it with the top of the scene: 

 public class MyApp extends Application {
     @Override
     public void start(Stage stage) {
         var button = new Button("My button");
         HeaderBar.setAlignment(button, Pos.CENTER_LEFT);
         HeaderBar.setMargin(button, new Insets(5));

         var headerBar = new HeaderBar();
         headerBar.setCenter(button);

         var root = new BorderPane();
         root.setTop(headerBar);

         stage.setScene(new Scene(root));
         stage.initStyle(StageStyle.EXTENDED);
         stage.show();
     }
 }
Since:
25

  • Property Details

    • leftSystemInset

      public final ReadOnlyObjectProperty<Dimension2D> leftSystemInsetProperty
      Describes the size of the left system-reserved inset, which is an area reserved for the iconify, maximize, and close window buttons. If there are no window buttons on the left side of the window, the returned area is an empty Dimension2D.

      Note that the left system inset refers to the left side of the window, independent of layout orientation.

      See Also:

    • rightSystemInset

      public final ReadOnlyObjectProperty<Dimension2D> rightSystemInsetProperty
      Describes the size of the right system-reserved inset, which is an area reserved for the iconify, maximize, and close window buttons. If there are no window buttons on the right side of the window, the returned area is an empty Dimension2D.

      Note that the right system inset refers to the right side of the window, independent of layout orientation.

      See Also:

    • minSystemHeight

      public final ReadOnlyDoubleProperty minSystemHeightProperty
      The system-provided minimum recommended height for the HeaderBar, which usually corresponds to the height of the default header buttons. Applications can use this value as a sensible lower limit for the height of the HeaderBar.

      By default, minHeight is set to the value of minSystemHeight, unless minHeight is explicitly set by a stylesheet or application code.

      See Also:

    • leading

      public final ObjectProperty<Node> leadingProperty
      The leading area of the HeaderBar.

      The leading area corresponds to the left area in a left-to-right layout, and to the right area in a right-to-left layout.

      Default value:
      null
      See Also:

    • center

      public final ObjectProperty<Node> centerProperty
      The center area of the HeaderBar.
      Default value:
      null
      See Also:

    • trailing

      public final ObjectProperty<Node> trailingProperty
      The trailing area of the HeaderBar.

      The trailing area corresponds to the right area in a left-to-right layout, and to the left area in a right-to-left layout.

      Default value:
      null
      See Also:

    • leadingSystemPadding

      public final BooleanProperty leadingSystemPaddingProperty
      Specifies whether additional padding should be added to the leading side of the HeaderBar. The size of the additional padding corresponds to the size of the system-reserved area that contains the default header buttons (iconify, maximize, and close). If the system-reserved area contains no header buttons, no additional padding is added to the leading side of the HeaderBar.

      Applications that use a single HeaderBar extending the entire width of the window should set this property to true to prevent the header buttons from overlapping the content of the HeaderBar.

      Default value:
      true
      See Also:

    • trailingSystemPadding

      public final BooleanProperty trailingSystemPaddingProperty
      Specifies whether additional padding should be added to the trailing side of the HeaderBar. The size of the additional padding corresponds to the size of the system-reserved area that contains the default header buttons (iconify, maximize, and close). If the system-reserved area contains no header buttons, no additional padding is added to the trailing side of the HeaderBar.

      Applications that use a single HeaderBar extending the entire width of the window should set this property to true to prevent the header buttons from overlapping the content of the HeaderBar.

      Default value:
      true
      See Also:

  • Field Details

  • Constructor Details

    • HeaderBar

      public HeaderBar()
      Deprecated.
      Creates a new HeaderBar.

    • HeaderBar

      public HeaderBar(Node leading, Node center, Node trailing)
      Deprecated.
      Creates a new HeaderBar with the specified children.
      Parameters:
      leading - the leading node, or null
      center - the center node, or null
      trailing - the trailing node, or null

  • Method Details

    • setDragType

      public static void setDragType(Node child, HeaderDragType value)
      Deprecated.
      Specifies the HeaderDragType of the child, indicating whether it is a draggable part of the HeaderBar.

      Setting the value to null will remove the flag.

      Parameters:
      child - the child node
      value - the HeaderDragType, or null to remove the flag

    • getDragType

      public static HeaderDragType getDragType(Node child)
      Deprecated.
      Returns the HeaderDragType of the specified child.
      Parameters:
      child - the child node
      Returns:
      the HeaderDragType, or null if not set

    • setButtonType

      public static void setButtonType(Node child, HeaderButtonType value)
      Deprecated.
      Specifies the HeaderButtonType of the child, indicating its semantic use in the header bar.

      This property can be set on any Node. Specifying a header button type also provides the behavior associated with the button type. If the default behavior is not desired, applications can register an event filter on the child node that consumes the MouseEvent.MOUSE_RELEASED event.

      Parameters:
      child - the child node
      value - the HeaderButtonType, or null

    • getButtonType

      public static HeaderButtonType getButtonType(Node child)
      Deprecated.
      Returns the HeaderButtonType of the specified child.
      Parameters:
      child - the child node
      Returns:
      the HeaderButtonType, or null

    • setPrefButtonHeight

      public static void setPrefButtonHeight(Stage stage, double height)
      Deprecated.
      Specifies the preferred height of the system-provided header buttons of the specified stage.

      Any value except zero and USE_DEFAULT_SIZE is only a hint for the platform window toolkit. The platform might accommodate the preferred height in various ways, such as by stretching the header buttons (fully or partially) to fill the preferred height, or centering the header buttons (fully or partially) within the preferred height. Some platforms might only accommodate the preferred height within platform-specific constraints, or ignore it entirely.

      Setting the preferred height to zero hides the system-provided header buttons, allowing applications to use custom header buttons instead (see setButtonType(Node, HeaderButtonType)).

      The default value USE_DEFAULT_SIZE indicates that the platform should choose the button height.

      Parameters:
      stage - the Stage
      height - the preferred height, or 0 to hide the system-provided header buttons

    • getPrefButtonHeight

      public static double getPrefButtonHeight(Stage stage)
      Deprecated.
      Returns the preferred height of the system-provided header buttons of the specified stage.
      Parameters:
      stage - the Stage
      Returns:
      the preferred height of the system-provided header buttons

    • setAlignment

      public static void setAlignment(Node child, Pos value)
      Deprecated.
      Sets the alignment for the child when contained in a HeaderBar. If set, will override the header bar's default alignment for the child's position. Setting the value to null will remove the constraint.
      Parameters:
      child - the child node
      value - the alignment position

    • getAlignment

      public static Pos getAlignment(Node child)
      Deprecated.
      Returns the child's alignment in the HeaderBar.
      Parameters:
      child - the child node
      Returns:
      the alignment position for the child, or null if no alignment was set

    • setMargin

      public static void setMargin(Node child, Insets value)
      Deprecated.
      Sets the margin for the child when contained in a HeaderBar. If set, the header bar will lay it out with the margin space around it. Setting the value to null will remove the constraint.
      Parameters:
      child - the child node
      value - the margin of space around the child

    • getMargin

      public static Insets getMargin(Node child)
      Deprecated.
      Returns the child's margin.
      Parameters:
      child - the child node
      Returns:
      the margin for the child, or null if no margin was set

    • leftSystemInsetProperty

      public final ReadOnlyObjectProperty<Dimension2D> leftSystemInsetProperty()
      Deprecated.
      Describes the size of the left system-reserved inset, which is an area reserved for the iconify, maximize, and close window buttons. If there are no window buttons on the left side of the window, the returned area is an empty Dimension2D.

      Note that the left system inset refers to the left side of the window, independent of layout orientation.

      Returns:
      the leftSystemInset property
      See Also:

    • getLeftSystemInset

      public final Dimension2D getLeftSystemInset()
      Deprecated.
      Gets the value of the leftSystemInset property.
      Property description:
      Describes the size of the left system-reserved inset, which is an area reserved for the iconify, maximize, and close window buttons. If there are no window buttons on the left side of the window, the returned area is an empty Dimension2D.

      Note that the left system inset refers to the left side of the window, independent of layout orientation.

      Returns:
      the value of the leftSystemInset property
      See Also:

    • rightSystemInsetProperty

      public final ReadOnlyObjectProperty<Dimension2D> rightSystemInsetProperty()
      Deprecated.
      Describes the size of the right system-reserved inset, which is an area reserved for the iconify, maximize, and close window buttons. If there are no window buttons on the right side of the window, the returned area is an empty Dimension2D.

      Note that the right system inset refers to the right side of the window, independent of layout orientation.

      Returns:
      the rightSystemInset property
      See Also:

    • getRightSystemInset

      public final Dimension2D getRightSystemInset()
      Deprecated.
      Gets the value of the rightSystemInset property.
      Property description:
      Describes the size of the right system-reserved inset, which is an area reserved for the iconify, maximize, and close window buttons. If there are no window buttons on the right side of the window, the returned area is an empty Dimension2D.

      Note that the right system inset refers to the right side of the window, independent of layout orientation.

      Returns:
      the value of the rightSystemInset property
      See Also:

    • minSystemHeightProperty

      public final ReadOnlyDoubleProperty minSystemHeightProperty()
      Deprecated.
      The system-provided minimum recommended height for the HeaderBar, which usually corresponds to the height of the default header buttons. Applications can use this value as a sensible lower limit for the height of the HeaderBar.

      By default, minHeight is set to the value of minSystemHeight, unless minHeight is explicitly set by a stylesheet or application code.

      Returns:
      the minSystemHeight property
      See Also:

    • getMinSystemHeight

      public final double getMinSystemHeight()
      Deprecated.
      Gets the value of the minSystemHeight property.
      Property description:
      The system-provided minimum recommended height for the HeaderBar, which usually corresponds to the height of the default header buttons. Applications can use this value as a sensible lower limit for the height of the HeaderBar.

      By default, minHeight is set to the value of minSystemHeight, unless minHeight is explicitly set by a stylesheet or application code.

      Returns:
      the value of the minSystemHeight property
      See Also:

    • leadingProperty

      public final ObjectProperty<Node> leadingProperty()
      Deprecated.
      The leading area of the HeaderBar.

      The leading area corresponds to the left area in a left-to-right layout, and to the right area in a right-to-left layout.

      Default value:
      null
      Returns:
      the leading property
      See Also:

    • getLeading

      public final Node getLeading()
      Deprecated.
      Gets the value of the leading property.
      Property description:
      The leading area of the HeaderBar.

      The leading area corresponds to the left area in a left-to-right layout, and to the right area in a right-to-left layout.

      Default value:
      null
      Returns:
      the value of the leading property
      See Also:

    • setLeading

      public final void setLeading(Node value)
      Deprecated.
      Sets the value of the leading property.
      Property description:
      The leading area of the HeaderBar.

      The leading area corresponds to the left area in a left-to-right layout, and to the right area in a right-to-left layout.

      Default value:
      null
      Parameters:
      value - the value for the leading property
      See Also:

    • centerProperty

      public final ObjectProperty<Node> centerProperty()
      Deprecated.
      The center area of the HeaderBar.
      Default value:
      null
      Returns:
      the center property
      See Also:

    • getCenter

      public final Node getCenter()
      Deprecated.
      Gets the value of the center property.
      Property description:
      The center area of the HeaderBar.
      Default value:
      null
      Returns:
      the value of the center property
      See Also:

    • setCenter

      public final void setCenter(Node value)
      Deprecated.
      Sets the value of the center property.
      Property description:
      The center area of the HeaderBar.
      Default value:
      null
      Parameters:
      value - the value for the center property
      See Also:

    • trailingProperty

      public final ObjectProperty<Node> trailingProperty()
      Deprecated.
      The trailing area of the HeaderBar.

      The trailing area corresponds to the right area in a left-to-right layout, and to the left area in a right-to-left layout.

      Default value:
      null
      Returns:
      the trailing property
      See Also:

    • getTrailing

      public final Node getTrailing()
      Deprecated.
      Gets the value of the trailing property.
      Property description:
      The trailing area of the HeaderBar.

      The trailing area corresponds to the right area in a left-to-right layout, and to the left area in a right-to-left layout.

      Default value:
      null
      Returns:
      the value of the trailing property
      See Also:

    • setTrailing

      public final void setTrailing(Node value)
      Deprecated.
      Sets the value of the trailing property.
      Property description:
      The trailing area of the HeaderBar.

      The trailing area corresponds to the right area in a left-to-right layout, and to the left area in a right-to-left layout.

      Default value:
      null
      Parameters:
      value - the value for the trailing property
      See Also:

    • leadingSystemPaddingProperty

      public final BooleanProperty leadingSystemPaddingProperty()
      Deprecated.
      Specifies whether additional padding should be added to the leading side of the HeaderBar. The size of the additional padding corresponds to the size of the system-reserved area that contains the default header buttons (iconify, maximize, and close). If the system-reserved area contains no header buttons, no additional padding is added to the leading side of the HeaderBar.

      Applications that use a single HeaderBar extending the entire width of the window should set this property to true to prevent the header buttons from overlapping the content of the HeaderBar.

      Default value:
      true
      Returns:
      the leadingSystemPadding property
      See Also:

    • isLeadingSystemPadding

      public final boolean isLeadingSystemPadding()
      Deprecated.
      Gets the value of the leadingSystemPadding property.
      Property description:
      Specifies whether additional padding should be added to the leading side of the HeaderBar. The size of the additional padding corresponds to the size of the system-reserved area that contains the default header buttons (iconify, maximize, and close). If the system-reserved area contains no header buttons, no additional padding is added to the leading side of the HeaderBar.

      Applications that use a single HeaderBar extending the entire width of the window should set this property to true to prevent the header buttons from overlapping the content of the HeaderBar.

      Default value:
      true
      Returns:
      the value of the leadingSystemPadding property
      See Also:

    • setLeadingSystemPadding

      public final void setLeadingSystemPadding(boolean value)
      Deprecated.
      Sets the value of the leadingSystemPadding property.
      Property description:
      Specifies whether additional padding should be added to the leading side of the HeaderBar. The size of the additional padding corresponds to the size of the system-reserved area that contains the default header buttons (iconify, maximize, and close). If the system-reserved area contains no header buttons, no additional padding is added to the leading side of the HeaderBar.

      Applications that use a single HeaderBar extending the entire width of the window should set this property to true to prevent the header buttons from overlapping the content of the HeaderBar.

      Default value:
      true
      Parameters:
      value - the value for the leadingSystemPadding property
      See Also:

    • trailingSystemPaddingProperty

      public final BooleanProperty trailingSystemPaddingProperty()
      Deprecated.
      Specifies whether additional padding should be added to the trailing side of the HeaderBar. The size of the additional padding corresponds to the size of the system-reserved area that contains the default header buttons (iconify, maximize, and close). If the system-reserved area contains no header buttons, no additional padding is added to the trailing side of the HeaderBar.

      Applications that use a single HeaderBar extending the entire width of the window should set this property to true to prevent the header buttons from overlapping the content of the HeaderBar.

      Default value:
      true
      Returns:
      the trailingSystemPadding property
      See Also:

    • isTrailingSystemPadding

      public final boolean isTrailingSystemPadding()
      Deprecated.
      Gets the value of the trailingSystemPadding property.
      Property description:
      Specifies whether additional padding should be added to the trailing side of the HeaderBar. The size of the additional padding corresponds to the size of the system-reserved area that contains the default header buttons (iconify, maximize, and close). If the system-reserved area contains no header buttons, no additional padding is added to the trailing side of the HeaderBar.

      Applications that use a single HeaderBar extending the entire width of the window should set this property to true to prevent the header buttons from overlapping the content of the HeaderBar.

      Default value:
      true
      Returns:
      the value of the trailingSystemPadding property
      See Also:

    • setTrailingSystemPadding

      public final void setTrailingSystemPadding(boolean value)
      Deprecated.
      Sets the value of the trailingSystemPadding property.
      Property description:
      Specifies whether additional padding should be added to the trailing side of the HeaderBar. The size of the additional padding corresponds to the size of the system-reserved area that contains the default header buttons (iconify, maximize, and close). If the system-reserved area contains no header buttons, no additional padding is added to the trailing side of the HeaderBar.

      Applications that use a single HeaderBar extending the entire width of the window should set this property to true to prevent the header buttons from overlapping the content of the HeaderBar.

      Default value:
      true
      Parameters:
      value - the value for the trailingSystemPadding property
      See Also: