Summary

This change adds new methods to the TextFlow which work correctly in the presence of non-empty insets (borders/padding). For backward compatibility, the old buggy methods are getting deprecated (not for removal). Also, adds new methods in Text which provide missing functionality.

Problem

A number of methods in TextFlow fail to return correct values in the presence of non-empty insets (i.e. when either padding or border are set): - caretShape - hitTest - rangeShape

Additionally, the current API fail to provide strike-through shape, and account for line spacing in the range shape, a problem shared between the TextFlow and the Text classes.

Solution

The solution is two-fold: 1. deprecate the buggy methods (not for removal), adding explanations in their javadoc comments 2) add new methods that behave correctly in the presence of non-empty insets and/or implementing the missing functionality.

The proposed solution retains the buggy methods for the purposes of backward compatibility in applications which employ the workarounds, while providing new APIs with additional parameters similar to those offered by the new TextLayout API https://bugs.openjdk.org/browse/JDK-8341670

Specification

javafx.scene.text.Text

         /**
          * Returns the shape for the range of the text in local coordinates.
    +     * The returned value does not include line spacing.
          *
          * @param start the beginning character index for the range
          * @param end the end character index (non-inclusive) for the range
          * @return an array of {@code PathElement} which can be used to create a {@code Shape}
          * @since 9
    +     * @see #getRangeShape(int, int, boolean)
          */
         public final PathElement[] rangeShape(int start, int end)

    +    /**
    +     * Returns the shape for the range of the text in local coordinates,
    +     * with or without line spacing.
    +     *
    +     * @param start the beginning character index for the range
    +     * @param end the end character index (non-inclusive) for the range
    +     * @param includeLineSpacing whether the shapes include line spacing
    +     * @return an array of {@code PathElement} which can be used to create a {@code Shape}
    +     * @since 25
    +     */
    +    public final PathElement[] getRangeShape(int start, int end, boolean includeLineSpacing)

    +    /**
    +     * Returns the shape for the strike-through in local coordinates.
    +     *
    +     * @param start the beginning character index for the range
    +     * @param end the end character index (non-inclusive) for the range
    +     * @return an array of {@code PathElement} which can be used to create a {@code Shape}
    +     * @since 25
    +     */
    +    public final PathElement[] getStrikeThroughShape(int start, int end) 

javafx.scene.text.TextFlow

         /**
          * Maps local point to {@link HitInfo} in the content.
    +     * <p>
    +     * NOTE: this method does not take border or padding into account.
          *
          * @param point the specified point to be tested
          * @return a {@code HitInfo} representing the character index found
          * @since 9
    +     * @deprecated replaced by {@link #getHitInfo(javafx.geometry.Point2D)}
          */
    +    @Deprecated(since="25")
         public final HitInfo hitTest(javafx.geometry.Point2D point)

         /**
    +     * Maps local point to {@link HitInfo} in the content.
    +     *
    +     * @param point the specified point to be tested
    +     * @return a {@code HitInfo} representing the character index found
    +     * @since 25
    +     */
    +    public final HitInfo getHitInfo(javafx.geometry.Point2D point)

    +    /**
          * Returns shape of caret in local coordinates.
    +     * <p>
    +     * NOTE: this method does not take border or padding into account.
          *
          * @param charIndex the character index for the caret
          * @param leading whether the caret is biased on the leading edge of the character
          * @return an array of {@code PathElement} which can be used to create a {@code Shape}
          * @since 9
    +     * @deprecated replaced by {@link #getCaretShape(int, boolean)}
          */
    +    @Deprecated(since="25")
         public PathElement[] caretShape(int charIndex, boolean leading)

         /**
    +     * Returns shape of caret in local coordinates.
    +     *
    +     * @param charIndex the character index for the caret
    +     * @param leading whether the caret is biased on the leading edge of the character
    +     * @return an array of {@code PathElement} which can be used to create a {@code Shape}
    +     * @since 25
    +     */
    +    public PathElement[] getCaretShape(int charIndex, boolean leading)

    +    /**
    +     * Returns shape for the range of the text in local coordinates.
    +     * <p>
    +     * NOTES:
    +     * <ul>
    +     * <li>this method does not take border or padding into account
    +     * <li>the shapes returned do not include line spacing
    +     * </ul>
    +     *
    +     * @param start the beginning character index for the range
    +     * @param end the end character index (non-inclusive) for the range
    +     * @return an array of {@code PathElement} which can be used to create a {@code Shape}
    +     * @since 9
    +     * @deprecated replaced by {@link #getRangeShape(int, int, boolean)}
    +     */
    +    @Deprecated(since="25")
    +    public final PathElement[] rangeShape(int start, int end)

    +    /**
          * Returns shape for the range of the text in local coordinates.
          *
          * @param start the beginning character index for the range
          * @param end the end character index (non-inclusive) for the range
    +     * @param includeLineSpacing determines whether the result includes the line spacing
          * @return an array of {@code PathElement} which can be used to create a {@code Shape}
    -     * @since 9
    +     * @since 25
    +     * @see LayoutInfo#getSelectionGeometry(int, int, boolean)
          */
    -    public final PathElement[] rangeShape(int start, int end)
    +    public final PathElement[] getRangeShape(int start, int end, boolean includeLineSpacing)

    +    /**
    +     * Returns the shape for the underline in local coordinates.
    +     * <p>
    +     * NOTE: this method does not take border or padding into account.
    +     *
    +     * @param start the beginning character index for the range
    +     * @param end the end character index (non-inclusive) for the range
    +     * @return an array of {@code PathElement} which can be used to create a {@code Shape}
    +     * @since 21
    +     * @deprecated replaced by {@link #getUnderlineShape(int, int)}
    +     */
    +    @Deprecated(since="25")
    +    public final PathElement[] underlineShape(int start, int end)

         /**
          * @param start the beginning character index for the range
          * @param end the end character index (non-inclusive) for the range
          * @return an array of {@code PathElement} which can be used to create a {@code Shape}
    -     * @since 21
    +     * @since 25
    +     * @see LayoutInfo#getUnderlineGeometry(int, int)
          */
    -    public final PathElement[] underlineShape(int start, int end)
    +    public final PathElement[] getUnderlineShape(int start, int end)

    +    /**
    +     * Returns the shape for the strike-through in local coordinates.
    +     *
    +     * @param start the beginning character index for the range
    +     * @param end the end character index (non-inclusive) for the range
    +     * @return an array of {@code PathElement} which can be used to create a {@code Shape}
    +     * @since 25
    +     * @see LayoutInfo#getStrikeThroughGeometry(int, int)
    +     */
    +    public final PathElement[] getStrikeThroughShape(int start, int end)