8357594: Additional geometry-based Text/TextFlow APIs

Reviewed-by: kcr, mstrauss

Author: Andy Goryachev

modules/javafx.graphics/src/main/java/com/sun/javafx/text/TextUtils.java

@@ -55,15 +55,16 @@ public final class TextUtils {
      * @param type the type of geometry to query
      * @param dx the x offset to add to each path element
      * @param dy the y offset to add to each path element
+     * @param lineSpacing the line spacing (applies only to TYPE_TEXT)
      * @return the array of {@code PathElement}s
      */
-    public static PathElement[] getRange(TextLayout layout, int start, int end, int type, double dx, double dy) {
+    public static PathElement[] getRange(TextLayout layout, int start, int end, int type, double dx, double dy, double lineSpacing) {
         ArrayList<PathElement> a = new ArrayList<>();
         layout.getRange(start, end, type, (left, top, right, bottom) -> {
             double leftEdge = left + dx;
             double rightEdge = right + dx;
             double topEdge = top + dy;
-            double bottomEdge = bottom + dy;
+            double bottomEdge = bottom + dy + lineSpacing;
             a.add(new MoveTo(leftEdge, topEdge));
             a.add(new LineTo(rightEdge, topEdge));
             a.add(new LineTo(rightEdge, bottomEdge));

modules/javafx.graphics/src/main/java/javafx/scene/text/Text.java

@@ -1056,13 +1056,13 @@ private int findFirstRunStart() {
         return start;
     }
 
-    private PathElement[] getRange(int start, int end, int type) {
+    private PathElement[] getRange(int start, int end, int type, double lineSpacing) {
         int length = getTextInternal().length();
         if (0 <= start && start < end  && end <= length) {
             TextLayout layout = getTextLayout();
             double dx = getX();
             double dy = getY() - getYRendering();
-            return TextUtils.getRange(layout, start, end, type, dx, dy);
+            return TextUtils.getRange(layout, start, end, type, dx, dy, lineSpacing);
         }
         return EMPTY_PATH_ELEMENT_ARRAY;
     }
@@ -1088,14 +1088,31 @@ public final PathElement[] caretShape(int charIndex, boolean caretBias) {
 
     /**
      * 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) {
-        return getRange(start, end, TextLayout.TYPE_TEXT);
+        return getRange(start, end, TextLayout.TYPE_TEXT, 0.0);
+    }
+
+    /**
+     * 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) {
+        double lineSpacing = includeLineSpacing ? getLineSpacing() : 0.0;
+        return getRange(start, end, TextLayout.TYPE_TEXT, lineSpacing);
     }
 
     /**
@@ -1107,7 +1124,19 @@ public final PathElement[] rangeShape(int start, int end) {
      * @since 9
      */
     public final PathElement[] underlineShape(int start, int end) {
-        return getRange(start, end, TextLayout.TYPE_UNDERLINE);
+        return getRange(start, end, TextLayout.TYPE_UNDERLINE, 0.0);
+    }
+
+    /**
+     * 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) {
+        return getRange(start, end, TextLayout.TYPE_STRIKETHROUGH, 0.0);
     }
 
     private float getYAdjustment(BaseBounds bounds) {
@@ -1769,7 +1798,7 @@ final ReadOnlyObjectProperty<PathElement[]> selectionShapeProperty() {
                     @Override protected PathElement[] computeValue() {
                         int start = getSelectionStart();
                         int end = getSelectionEnd();
-                        return getRange(start, end, TextLayout.TYPE_TEXT);
+                        return getRange(start, end, TextLayout.TYPE_TEXT, 0.0);
                     }
               };
               selectionShape = new SimpleObjectProperty<>(Text.this, "selectionShape");

modules/javafx.graphics/src/main/java/javafx/scene/text/TextFlow.java

@@ -193,11 +193,15 @@ private void checkOrientation() {
 
     /**
      * 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) {
         if (point != null) {
             TextLayout layout = getTextLayout();
@@ -210,42 +214,132 @@ 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) {
+        if (point != null) {
+            TextLayout layout = getTextLayout();
+            double x = point.getX() - snappedLeftInset();
+            double y = point.getY() - snappedTopInset();
+            TextLayout.Hit h = layout.getHitInfo((float)x, (float)y);
+            return new HitInfo(h.getCharIndex(), h.getInsertionIndex(), h.isLeading());
+        } else {
+            return null;
+        }
+    }
+
     /**
      * 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) {
         TextLayout.CaretGeometry g = getTextLayout().getCaretGeometry(charIndex, leading);
-        // TODO padding JDK-8341438?
         return TextUtils.getCaretPathElements(g, 0.0, 0.0);
     }
 
+    /**
+     * 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) {
+        TextLayout.CaretGeometry g = getTextLayout().getCaretGeometry(charIndex, leading);
+        double dx = snappedLeftInset();
+        double dy = snappedTopInset();
+        return TextUtils.getCaretPathElements(g, dx, dy);
+    }
+
     /**
      * 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) {
-        return getRange(start, end, TextLayout.TYPE_TEXT);
+        return getRange(start, end, TextLayout.TYPE_TEXT, false, 0.0);
+    }
+
+    /**
+     * 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 25
+     * @see LayoutInfo#getSelectionGeometry(int, int, boolean)
+     */
+    public final PathElement[] getRangeShape(int start, int end, boolean includeLineSpacing) {
+        double lineSpacing = includeLineSpacing ? getLineSpacing() : 0.0;
+        return getRange(start, end, TextLayout.TYPE_TEXT, true, lineSpacing);
     }
 
     /**
      * 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) {
-        return getRange(start, end, TextLayout.TYPE_UNDERLINE);
+        return getRange(start, end, TextLayout.TYPE_UNDERLINE, false, 0.0);
+    }
+
+    /**
+     * Returns the shape for the underline 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#getUnderlineGeometry(int, int)
+     */
+    public final PathElement[] getUnderlineShape(int start, int end) {
+        return getRange(start, end, TextLayout.TYPE_UNDERLINE, true, 0.0);
+    }
+
+    /**
+     * 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) {
+        return getRange(start, end, TextLayout.TYPE_STRIKETHROUGH, true, 0.0);
     }
 
     @Override
@@ -368,9 +462,18 @@ public boolean usesMirroring() {
         inLayout = false;
     }
 
-    private PathElement[] getRange(int start, int end, int type) {
+    private PathElement[] getRange(int start, int end, int type, boolean accountForInsets, double lineSpacing) {
+        double dx;
+        double dy;
+        if (accountForInsets) {
+            dx = snappedLeftInset();
+            dy = snappedTopInset();
+        } else {
+            dx = 0.0;
+            dy = 0.0;
+        }
         TextLayout layout = getTextLayout();
-        return TextUtils.getRange(layout, start, end, type, 0, 0);
+        return TextUtils.getRange(layout, start, end, type, dx, dy, lineSpacing);
     }
 
     private static class EmbeddedSpan implements TextSpan {