javafx.scene.layout.Border.java Source code

Java tutorial

Introduction

Here is the source code for javafx.scene.layout.Border.java

Source

/*
 * Copyright (c) 2012, 2017, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package javafx.scene.layout;

import java.util.Arrays;
import java.util.Collections;
import java.util.List;

import javafx.beans.NamedArg;
import javafx.geometry.Insets;
import javafx.scene.Node;
import javafx.scene.paint.Paint;
import com.sun.javafx.UnmodifiableArrayList;
import javafx.css.CssMetaData;
import com.sun.javafx.css.SubCssMetaData;
import javafx.css.converter.InsetsConverter;
import javafx.css.converter.URLConverter;
import com.sun.javafx.scene.layout.region.BorderImageSlices;
import com.sun.javafx.scene.layout.region.BorderImageWidthConverter;
import com.sun.javafx.scene.layout.region.CornerRadiiConverter;
import com.sun.javafx.scene.layout.region.LayeredBorderPaintConverter;
import com.sun.javafx.scene.layout.region.LayeredBorderStyleConverter;
import com.sun.javafx.scene.layout.region.Margins;
import com.sun.javafx.scene.layout.region.RepeatStruct;
import com.sun.javafx.scene.layout.region.RepeatStructConverter;
import com.sun.javafx.scene.layout.region.SliceSequenceConverter;
import javafx.css.Styleable;

/**
 * The Border of a {@link 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 Regions. Please refer to
 * <a href="../doc-files/cssref.html">JavaFX CSS Reference Guide</a> for a
 * complete description of the CSS rules for styling the border of a Region.
 * <p>
 * Every Border is comprised of {@link #getStrokes() strokes} and / or
 * {@link #getImages() 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 {@link #getInsets() insets}
 * and {@link #getOutsets() outsets} of the Border.
 * <p>
 * The Border's {@link #getOutsets() 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 {@link BorderStroke}s and {@link BorderImage}s specified on this Border.
 * Outsets are strictly non-negative.
 * <p>
 * {@link #getInsets()} 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 {@link Background} and Border
 * and the {@link javafx.scene.layout.Region#getPadding() Region's padding} to determine the
 * Region {@link javafx.scene.layout.Region#getInsets() 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 {@code layoutBounds}, {@code boundsInLocal}, and {@code boundsInParent}).
 * <p>
 * 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
 */
@SuppressWarnings("unchecked")
public final class Border {
    static final CssMetaData<Node, Paint[]> BORDER_COLOR = new SubCssMetaData<Paint[]>("-fx-border-color",
            LayeredBorderPaintConverter.getInstance());

    static final CssMetaData<Node, BorderStrokeStyle[][]> BORDER_STYLE = new SubCssMetaData<BorderStrokeStyle[][]>(
            "-fx-border-style", LayeredBorderStyleConverter.getInstance());

    static final CssMetaData<Node, Margins[]> BORDER_WIDTH = new SubCssMetaData<Margins[]>("-fx-border-width",
            Margins.SequenceConverter.getInstance());

    static final CssMetaData<Node, CornerRadii[]> BORDER_RADIUS = new SubCssMetaData<CornerRadii[]>(
            "-fx-border-radius", CornerRadiiConverter.getInstance());

    static final CssMetaData<Node, Insets[]> BORDER_INSETS = new SubCssMetaData<Insets[]>("-fx-border-insets",
            InsetsConverter.SequenceConverter.getInstance());

    static final CssMetaData<Node, String[]> BORDER_IMAGE_SOURCE = new SubCssMetaData<String[]>(
            "-fx-border-image-source", URLConverter.SequenceConverter.getInstance());

    static final CssMetaData<Node, RepeatStruct[]> BORDER_IMAGE_REPEAT = new SubCssMetaData<RepeatStruct[]>(
            "-fx-border-image-repeat", RepeatStructConverter.getInstance(),
            new RepeatStruct[] { new RepeatStruct(BackgroundRepeat.REPEAT, BackgroundRepeat.REPEAT) });

    static final CssMetaData<Node, BorderImageSlices[]> BORDER_IMAGE_SLICE = new SubCssMetaData<BorderImageSlices[]>(
            "-fx-border-image-slice", SliceSequenceConverter.getInstance(),
            new BorderImageSlices[] { BorderImageSlices.DEFAULT });

    static final CssMetaData<Node, BorderWidths[]> BORDER_IMAGE_WIDTH = new SubCssMetaData<BorderWidths[]>(
            "-fx-border-image-width", BorderImageWidthConverter.getInstance(),
            new BorderWidths[] { BorderWidths.DEFAULT });

    static final CssMetaData<Node, Insets[]> BORDER_IMAGE_INSETS = new SubCssMetaData<Insets[]>(
            "-fx-border-image-insets", InsetsConverter.SequenceConverter.getInstance(),
            new Insets[] { Insets.EMPTY });

    private static final List<CssMetaData<? extends Styleable, ?>> STYLEABLES = (List<CssMetaData<? extends Styleable, ?>>) (List) Collections
            .unmodifiableList(
                    // Unchecked!
                    Arrays.asList(BORDER_COLOR, BORDER_STYLE, BORDER_WIDTH, BORDER_RADIUS, BORDER_INSETS,
                            BORDER_IMAGE_SOURCE, BORDER_IMAGE_REPEAT, BORDER_IMAGE_SLICE, BORDER_IMAGE_WIDTH,
                            BORDER_IMAGE_INSETS));

    /**
     * @return The CssMetaData associated with this class, which may include the
     * CssMetaData of its superclasses.
     */
    public static List<CssMetaData<? extends Styleable, ?>> getClassCssMetaData() {
        return STYLEABLES;
    }

    /**
     * An empty Border, useful to use instead of null.
     */
    public static final Border EMPTY = new Border((BorderStroke[]) null, null);

    /**
     * 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.
     * @return the list of BorderStrokes which together define the stroked
     * portion of this Border
     */
    public final List<BorderStroke> getStrokes() {
        return strokes;
    }

    final List<BorderStroke> strokes;

    /**
     * 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
     * {@link #getStrokes strokes} are not drawn. If this list is null or no images
     * succeeded in loading, then any specified {@code strokes} are drawn.
     * <p>
     * This List is unmodifiable and immutable. It will never be null.
     * It will never contain any null elements.
     * @return the list of BorderImages which together define the images to use
     * instead of stroke for this Border
     */
    public final List<BorderImage> getImages() {
        return images;
    }

    final List<BorderImage> images;

    /**
     * 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.
     * @return the outsets of the border define the outer-most edge of the
     * border to be drawn
     */
    public final Insets getOutsets() {
        return outsets;
    }

    final Insets outsets;

    /**
     * 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 outsets
     * are strictly non-negative.
     * @return the insets define the distance from the edge of the Region to the
     * inner-most edge of the border
     */
    public final Insets getInsets() {
        return insets;
    }

    final Insets insets;

    /**
     * Gets whether the Border is empty. It is empty if there are no strokes or images.
     * @return true if the Border is empty, false otherwise.
     */
    public final boolean isEmpty() {
        return strokes.isEmpty() && images.isEmpty();
    }

    /**
     * The cached hash code computation for the Border. One very big
     * reason for making Border immutable was to make it possible to
     * cache and reuse the same Border instance for multiple
     * Regions. To enable efficient caching, we cache the hash.
     */
    private final int hash;

    /**
     * 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 {@link #getStrokes() strokes}
     * or {@link #getOutsets() outsets} or {@link #getInsets() insets}.
     *
     * @param 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.
     */
    public Border(@NamedArg("strokes") BorderStroke... strokes) {
        this(strokes, null);
    }

    /**
     * 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 {@link #getImages() images}
     * or {@link #getOutsets() outsets} or {@link #getInsets() insets}.
     *
     * @param 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.
     */
    public Border(@NamedArg("images") BorderImage... images) {
        this(null, 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 {@link #getStrokes() strokes}
     * or {@link #getImages() images}, {@link #getOutsets() outsets}, or
     * {@link #getInsets() insets}.
     *
     * @param 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.
     * @param 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.
     */
    public Border(@NamedArg("strokes") List<BorderStroke> strokes, @NamedArg("images") List<BorderImage> images) {
        // NOTE: This constructor had to be supplied in order to cause a Builder
        // to be auto-generated, because otherwise the types of the strokes and images
        // properties didn't match the types of the array based constructor parameters.
        // So a Builder will use this constructor, while the CSS engine uses the
        // array based constructor (for speed).
        this(strokes == null ? null : strokes.toArray(new BorderStroke[strokes.size()]),
                images == null ? null : images.toArray(new BorderImage[images.size()]));
    }

    /**
     * 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 {@link #getStrokes() strokes}
     * or {@link #getImages() images}, {@link #getOutsets() outsets}, or
     * {@link #getInsets() insets}.
     *
     * @param 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.
     * @param 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.
     */
    public Border(@NamedArg("strokes") BorderStroke[] strokes, @NamedArg("images") BorderImage[] images) {
        double innerTop = 0, innerRight = 0, innerBottom = 0, innerLeft = 0;
        double outerTop = 0, outerRight = 0, outerBottom = 0, outerLeft = 0;

        if (strokes == null || strokes.length == 0) {
            this.strokes = Collections.emptyList();
        } else {
            final BorderStroke[] noNulls = new BorderStroke[strokes.length];
            int size = 0;
            for (int i = 0; i < strokes.length; i++) {
                final BorderStroke stroke = strokes[i];
                if (stroke != null) {
                    noNulls[size++] = stroke;

                    // Calculate the insets and outsets. "insets" are the distance
                    // from the edge of the region to the inmost edge of the inmost border.
                    // Outsets are the distance from the edge of the region out towards the
                    // outer-most edge of the outer-most border.
                    final double strokeInnerTop = stroke.innerEdge.getTop();
                    final double strokeInnerRight = stroke.innerEdge.getRight();
                    final double strokeInnerBottom = stroke.innerEdge.getBottom();
                    final double strokeInnerLeft = stroke.innerEdge.getLeft();

                    innerTop = innerTop >= strokeInnerTop ? innerTop : strokeInnerTop;
                    innerRight = innerRight >= strokeInnerRight ? innerRight : strokeInnerRight;
                    innerBottom = innerBottom >= strokeInnerBottom ? innerBottom : strokeInnerBottom;
                    innerLeft = innerLeft >= strokeInnerLeft ? innerLeft : strokeInnerLeft;

                    final double strokeOuterTop = stroke.outerEdge.getTop();
                    final double strokeOuterRight = stroke.outerEdge.getRight();
                    final double strokeOuterBottom = stroke.outerEdge.getBottom();
                    final double strokeOuterLeft = stroke.outerEdge.getLeft();

                    outerTop = outerTop >= strokeOuterTop ? outerTop : strokeOuterTop;
                    outerRight = outerRight >= strokeOuterRight ? outerRight : strokeOuterRight;
                    outerBottom = outerBottom >= strokeOuterBottom ? outerBottom : strokeOuterBottom;
                    outerLeft = outerLeft >= strokeOuterLeft ? outerLeft : strokeOuterLeft;
                }
            }
            this.strokes = new UnmodifiableArrayList<BorderStroke>(noNulls, size);
        }

        if (images == null || images.length == 0) {
            this.images = Collections.emptyList();
        } else {
            final BorderImage[] noNulls = new BorderImage[images.length];
            int size = 0;
            for (int i = 0; i < images.length; i++) {
                final BorderImage image = images[i];
                if (image != null) {
                    noNulls[size++] = image;

                    // The Image width + insets may contribute to the insets / outsets of
                    // this border.
                    final double imageInnerTop = image.innerEdge.getTop();
                    final double imageInnerRight = image.innerEdge.getRight();
                    final double imageInnerBottom = image.innerEdge.getBottom();
                    final double imageInnerLeft = image.innerEdge.getLeft();

                    innerTop = innerTop >= imageInnerTop ? innerTop : imageInnerTop;
                    innerRight = innerRight >= imageInnerRight ? innerRight : imageInnerRight;
                    innerBottom = innerBottom >= imageInnerBottom ? innerBottom : imageInnerBottom;
                    innerLeft = innerLeft >= imageInnerLeft ? innerLeft : imageInnerLeft;

                    final double imageOuterTop = image.outerEdge.getTop();
                    final double imageOuterRight = image.outerEdge.getRight();
                    final double imageOuterBottom = image.outerEdge.getBottom();
                    final double imageOuterLeft = image.outerEdge.getLeft();

                    outerTop = outerTop >= imageOuterTop ? outerTop : imageOuterTop;
                    outerRight = outerRight >= imageOuterRight ? outerRight : imageOuterRight;
                    outerBottom = outerBottom >= imageOuterBottom ? outerBottom : imageOuterBottom;
                    outerLeft = outerLeft >= imageOuterLeft ? outerLeft : imageOuterLeft;
                }
            }
            this.images = new UnmodifiableArrayList<BorderImage>(noNulls, size);
        }

        // Both the BorderStroke and BorderImage class make sure to return the outsets
        // and insets in the right way, such that we don't have to worry about adjusting
        // the sign, etc, unlike in the Background implementation.
        outsets = new Insets(outerTop, outerRight, outerBottom, outerLeft);
        insets = new Insets(innerTop, innerRight, innerBottom, innerLeft);

        // Pre-compute the hash code. NOTE: all variables are prefixed with "this" so that we
        // do not accidentally compute the hash based on the constructor arguments rather than
        // based on the fields themselves!
        int result = this.strokes.hashCode();
        result = 31 * result + this.images.hashCode();
        hash = result;
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public boolean equals(Object o) {
        if (this == o)
            return true;
        if (o == null || getClass() != o.getClass())
            return false;
        Border border = (Border) o;
        if (this.hash != border.hash)
            return false;

        if (!images.equals(border.images))
            return false;
        if (!strokes.equals(border.strokes))
            return false;

        return true;
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public int hashCode() {
        return hash;
    }
}