Module javafx.graphics
Package javafx.scene.layout

# Class Border

java.lang.Object
javafx.scene.layout.Border

public final class Border extends Object
The border of a `Region`. A `Border` is an immutable object which encapsulates the entire set of data required to render the border of a `Region`. Because this class is immutable, you can freely reuse the same `Border` on many different `Region`s. Please refer to JavaFX CSS Reference Guide for a complete description of the CSS rules for styling the border of a `Region`.

Every `Border` is comprised of `strokes` and / or `images`. Neither list will ever be `null`, but either or both may be empty. When rendering, if no images are specified or no image succeeds in loading, then all strokes will be rendered in order. If any image is specified and succeeds in loading, then no strokes will be drawn, although they will still contribute to the `insets` and `outsets` of the `Border`.

The `Border`'s `outsets` define any extension of the drawing area of a `Region` which is necessary to account for all border drawing and positioning. These `outsets` are defined by both the `BorderStroke`s and `BorderImage`s specified on this `Border`. `outsets` are strictly non-negative.

`insets` are used to define the inner-most edge of all of the borders. It also is always strictly non-negative. The `Region` uses the insets of the `Background` and `Border`, and the `Region's padding` to determine the `Region` `insets`, which define the content area for any children of the `Region`. The `outsets` of a `Border` together with the `outsets` of a `Background`, and the width and height of the `Region` define the geometric bounds of the `Region` (which in turn contribute to the `layoutBounds`, `boundsInLocal`, and `boundsInParent`).

A `Border` is most often used in cases where you want to skin the `Region` with an image, often used in conjunction with 9-patch scaling techniques. In such cases, you may also specify a stroked border which is only used when the image fails to load for some reason.

Since:
  JavaFX 8.0

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final Border`
  `EMPTY`
  An empty Border, useful to use instead of null.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Border(List<BorderStroke> strokes, List<BorderImage> images)`
  Creates a new Border by supplying a List of BorderStrokes and BorderImages.
  `Border(BorderImage... images)`
  Creates a new Border by supplying an array of BorderImages.
  `Border(BorderStroke... strokes)`
  Creates a new Border by supplying an array of BorderStrokes.
  `Border(BorderStroke[] strokes, BorderImage[] images)`
  Creates a new Border by supplying an array of BorderStrokes and BorderImages.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static List<CssMetaData<? extends Styleable,?>>`
  `getClassCssMetaData()`
  Gets the `CssMetaData` associated with this class, which may include the `CssMetaData` of its superclasses.
  `final List<BorderImage>`
  `getImages()`
  The list of BorderImages which together define the images to use instead of stroke for this Border.
  `final Insets`
  `getInsets()`
  The insets define the distance from the edge of the Region to the inner-most edge of the border, if that distance is non-negative.
  `final Insets`
  `getOutsets()`
  The outsets of the border define the outer-most edge of the border to be drawn.
  `final List<BorderStroke>`
  `getStrokes()`
  The list of BorderStrokes which together define the stroked portion of this Border.
  `final boolean`
  `isEmpty()`
  Gets whether the Border is empty.
  `static Border`
  `stroke(Paint stroke)`
  A convenience factory method for creating a solid `Border` with a single `Paint`.

  ### Methods declared in class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### EMPTY

    public static final Border EMPTY
    An empty Border, useful to use instead of null.

- ## Constructor Details

  - ### Border

    public Border(BorderStroke... strokes)
    Creates a new Border by supplying an array of BorderStrokes. This array may be null, or may contain null values. Any null values will be ignored and will not contribute to the `strokes` or `outsets` or `insets`.
    Parameters:
      `strokes` - The strokes. This may be null, and may contain nulls. Any contained nulls are filtered out and not included in the final List of strokes. A null array becomes an empty List. If both strokes and images are specified, and if any one of the images specified succeeds in loading, then no strokes are shown. In this way, strokes can be defined as a fallback in the case that an image failed to load.

  - ### Border

    public Border(BorderImage... images)
    Creates a new Border by supplying an array of BorderImages. This array may be null, or may contain null values. Any null values will be ignored and will not contribute to the `images` or `outsets` or `insets`.
    Parameters:
      `images` - The images. This may be null, and may contain nulls. Any contained nulls are filtered out and not included in the final List of images. A null array becomes an empty List.

  - ### Border

    public Border(List<BorderStroke> strokes, List<BorderImage> images)
    Creates a new Border by supplying a List of BorderStrokes and BorderImages. These Lists may be null, or may contain null values. Any null values will be ignored and will not contribute to the `strokes` or `images`, `outsets`, or `insets`.
    Parameters:
      `strokes` - The strokes. This may be null, and may contain nulls. Any contained nulls are filtered out and not included in the final List of strokes. A null array becomes an empty List. If both strokes and images are specified, and if any one of the images specified succeeds in loading, then no strokes are shown. In this way, strokes can be defined as a fallback in the case that an image failed to load.
      `images` - The images. This may be null, and may contain nulls. Any contained nulls are filtered out and not included in the final List of images. A null array becomes an empty List.

  - ### Border

    public Border(BorderStroke[] strokes, BorderImage[] images)
    Creates a new Border by supplying an array of BorderStrokes and BorderImages. These arrays may be null, or may contain null values. Any null values will be ignored and will not contribute to the `strokes` or `images`, `outsets`, or `insets`.
    Parameters:
      `strokes` - The strokes. This may be null, and may contain nulls. Any contained nulls are filtered out and not included in the final List of strokes. A null array becomes an empty List. If both strokes and images are specified, and if any one of the images specified succeeds in loading, then no strokes are shown. In this way, strokes can be defined as a fallback in the case that an image failed to load.
      `images` - The images. This may be null, and may contain nulls. Any contained nulls are filtered out and not included in the final List of images. A null array becomes an empty List.

- ## Method Details

  - ### getClassCssMetaData

    public static List<CssMetaData<? extends Styleable,?>> getClassCssMetaData()
    Gets the `CssMetaData` associated with this class, which may include the `CssMetaData` of its superclasses.
    Returns:
      the `CssMetaData`

  - ### getStrokes

    public final List<BorderStroke> getStrokes()
    The list of BorderStrokes which together define the stroked portion of this Border. This List is unmodifiable and immutable. It will never be null. It will never contain any null elements.
    Returns:
      the list of BorderStrokes which together define the stroked portion of this Border

  - ### getImages

    public final List<BorderImage> getImages()
    The list of BorderImages which together define the images to use instead of stroke for this Border. If this list is specified and at least one image within it succeeds in loading, then any specified `strokes` are not drawn. If this list is null or no images succeeded in loading, then any specified `strokes` are drawn.

    This List is unmodifiable and immutable. It will never be null. It will never contain any null elements.

    Returns:
      the list of BorderImages which together define the images to use instead of stroke for this Border

  - ### getOutsets

    public final Insets getOutsets()
    The outsets of the border define the outer-most edge of the border to be drawn. The values in these outsets are strictly non-negative.
    Returns:
      the outsets of the border define the outer-most edge of the border to be drawn

  - ### getInsets

    public final Insets getInsets()
    The insets define the distance from the edge of the Region to the inner-most edge of the border, if that distance is non-negative. The values in these insets are strictly non-negative.
    Returns:
      the insets define the distance from the edge of the Region to the inner-most edge of the border

  - ### isEmpty

    public final boolean isEmpty()
    Gets whether the Border is empty. It is empty if there are no strokes or images.
    Returns:
      true if the Border is empty, false otherwise.

  - ### stroke

    public static Border stroke(Paint stroke)
    A convenience factory method for creating a solid `Border` with a single `Paint`.
    Implementation Requirements:
      This call is equivalent to `new Border(new BorderStroke(stroke, BorderStrokeStyle.SOLID, null, null));`.
    Parameters:
      `stroke` - the stroke of the border (for all sides). If `null`, `Color.BLACK` will be used.
    Returns:
      a new border of the given stroke
    Since:
      18