Class BackgroundSize

java.lang.Object
javafx.scene.layout.BackgroundSize
All Implemented Interfaces:
Interpolatable<BackgroundSize>
public final class BackgroundSize extends Object implements Interpolatable<BackgroundSize>
Defines the size of the area that a BackgroundImage should fill relative to the Region it is styling. There are several properties whose values take precedence over the others. In particular there are 4 key properties, width, height, contain, and cover. Both width and height are independent of each other, however both interact with contain and cover.

From the CSS Specification, cover is defined to:

Scale the image, while preserving its intrinsic aspect ratio (if any), to the smallest size such that both its width and its height can completely cover the background positioning area.
contain is defined to:
Scale the image, while preserving its intrinsic aspect ratio (if any), to the largest size such that both its width and its height can fit inside the background positioning area.
And width and height both specify (in absolute values or percentages) the size to use. These two properties only apply if both cover and contain are false. If both cover and contain are true, then cover will be used.

The width and height may also be set to AUTO, indicating that the area should be sized so as to use the image's intrinsic size, or if it cannot be determined, 100%.

Since:
JavaFX 8.0

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final double
    AUTO
    From the CSS Specification: An "auto" value for one dimension is resolved by using the image's intrinsic ratio and the size of the other dimension, or failing that, using the image's intrinsic size, or failing that, treating it as 100%.
    static final BackgroundSize
    DEFAULT
    The default BackgroundSize used by BackgroundImages when an explicit size is not defined.

  • Constructor Summary

    Constructors
    Constructor
    Description
    BackgroundSize(double width, double height, boolean widthAsPercentage, boolean heightAsPercentage, boolean contain, boolean cover)
    Create a new BackgroundSize.

  • Method Summary

    Modifier and Type
    Method
    Description
    final double
    getHeight()
    The height of the area within the Region where the associated BackgroundImage should render.
    final double
    getWidth()
    The width of the area within the Region where the associated BackgroundImage should render.
    BackgroundSize
    interpolate(BackgroundSize endValue, double t)
    Returns an intermediate value between the value of this Interpolatable and the specified endValue using the linear interpolation factor t, ranging from 0 (inclusive) to 1 (inclusive).
    final boolean
    isContain()
    If true, scale the image, while preserving its intrinsic aspect ratio (if any), to the largest size such that both its width and its height can fit inside the background positioning area.
    final boolean
    isCover()
    If true, scale the image, while preserving its intrinsic aspect ratio (if any), to the smallest size such that both its width and its height can completely cover the background positioning area.
    final boolean
    isHeightAsPercentage()
    Specifies whether the value contained in height should be interpreted as a percentage or as a normal value.
    final boolean
    isWidthAsPercentage()
    Specifies whether the value contained in width should be interpreted as a percentage or as a normal value.

    Methods declared in class java.lang.Object

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

  • Field Details

    • AUTO

      public static final double AUTO
      From the CSS Specification:
      An "auto" value for one dimension is resolved by using the image's intrinsic ratio and the size of the other dimension, or failing that, using the image's intrinsic size, or failing that, treating it as 100%.

      If both values are "auto" then the intrinsic width and/or height of the image should be used, if any, the missing dimension (if any) behaving as "auto" as described above. If the image has neither an intrinsic width nor an intrinsic height, its size is determined as for "contain".

      When set to AUTO, the values for widthAsPercentage and heightAsPercentage are ignored.
      See Also:

    • DEFAULT

      public static final BackgroundSize DEFAULT
      The default BackgroundSize used by BackgroundImages when an explicit size is not defined. By default, the BackgroundSize is AUTO, AUTO for the width and height, and is neither cover nor contain.

  • Constructor Details

    • BackgroundSize

      public BackgroundSize(double width, double height, boolean widthAsPercentage, boolean heightAsPercentage, boolean contain, boolean cover)
      Create a new BackgroundSize.
      Parameters:
      width - The width. Cannot be less than 0, except for the value of AUTO.
      height - The height. Cannot be less than 0, except for the value of AUTO.
      widthAsPercentage - Whether the width is to be interpreted as a percentage
      heightAsPercentage - Whether the height is to be interpreted as a percentage
      contain - Whether the image should be sized to fit within the Region maximally
      cover - Whether the image should be sized to "cover" the Region

  • Method Details

    • getWidth

      public final double getWidth()
      The width of the area within the Region where the associated BackgroundImage should render. If set to AUTO, then widthAsPercentage is ignored. This value has no meaning if either contain or cover are specified. This value cannot be negative, except when set to the value of AUTO.
      Interpolation Type:
      discrete if cover or contain is set, if one value is absolute and the other value is a percentage, or if the width is AUTO; otherwise linear
      Returns:
      the width of the area within the Region where the associated BackgroundImage should render

    • getHeight

      public final double getHeight()
      The height of the area within the Region where the associated BackgroundImage should render. If set to AUTO, then heightAsPercentage is ignored. This value has no meaning if either contain or cover are specified. This value cannot be negative, except when set to the value of AUTO.
      Interpolation Type:
      discrete if cover or contain is set, if one value is absolute and the other value is a percentage, or if the height is AUTO; otherwise linear
      Returns:
      the height of the area within the Region where the associated BackgroundImage should render

    • isWidthAsPercentage

      public final boolean isWidthAsPercentage()
      Specifies whether the value contained in width should be interpreted as a percentage or as a normal value.
      Interpolation Type:
      discrete
      Returns:
      true if width should be interpreted as a percentage

    • isHeightAsPercentage

      public final boolean isHeightAsPercentage()
      Specifies whether the value contained in height should be interpreted as a percentage or as a normal value.
      Interpolation Type:
      discrete
      Returns:
      true if height should be interpreted as a percentage

    • isContain

      public final boolean isContain()
      If true, scale the image, while preserving its intrinsic aspect ratio (if any), to the largest size such that both its width and its height can fit inside the background positioning area.
      Interpolation Type:
      discrete
      Returns:
      true if the image can fit inside the background positioning area

    • isCover

      public final boolean isCover()
      If true, scale the image, while preserving its intrinsic aspect ratio (if any), to the smallest size such that both its width and its height can completely cover the background positioning area.
      Interpolation Type:
      discrete
      Returns:
      true if image can completely cover the background positioning area

    • interpolate

      public BackgroundSize interpolate(BackgroundSize endValue, double t)
      Returns an intermediate value between the value of this Interpolatable and the specified endValue using the linear interpolation factor t, ranging from 0 (inclusive) to 1 (inclusive).

      The returned value might not be a new instance; the implementation might also return one of the two existing instances if the intermediate value would be equal to one of the existing values. However, this is an optimization and applications should not assume any particular identity of the returned value.

      Specified by:
      interpolate in interface Interpolatable<BackgroundSize>
      Parameters:
      endValue - the target value
      t - the interpolation factor
      Returns:
      the intermediate value
      Throws:
      NullPointerException - if endValue is null
      Since:
      24