TextFlow (JavaFX 17)

Module javafx.graphics
Package javafx.scene.text

## Class TextFlow

- java.lang.Object
- - javafx.scene.Node
  - - javafx.scene.Parent
    - - javafx.scene.layout.Region
      - - javafx.scene.layout.Pane
        - - javafx.scene.text.TextFlow

- All Implemented Interfaces:
    `Styleable`, `EventTarget`

      public class TextFlow
      extends Pane

  TextFlow is special layout designed to lay out rich text. It can be used to layout several `Text` nodes in a single text flow. The TextFlow uses the text and the font of each `Text` node inside of it plus its own width and text alignment to determine the location for each child. A single `Text` node can span over several lines due to wrapping, and the visual location of `Text` node can differ from the logical location due to bidi reordering.

  Any Node, other than Text, will be treated as an embedded object in the text layout. It will be inserted in the content using its preferred width, height, and baseline offset.

  When a `Text` node is inside of a TextFlow, some of its properties are ignored. For example, the x and y properties of the `Text` node are ignored since the location of the node is determined by the parent. Likewise, the wrapping width in the `Text` node is ignored since the width used for wrapping is the TextFlow's width. The value of the `pickOnBounds` property of a `Text` is set to `false` when it is laid out by the TextFlow. This happens because the content of a single `Text` node can divided and placed in the different locations on the TextFlow (usually due to line breaking and bidi reordering).

  The wrapping width of the layout is determined by the region's current width. It can be specified by the application by setting the textflow's preferred width. If no wrapping is desired, the application can either set the preferred with to Double.MAX_VALUE or Region.USE_COMPUTED_SIZE.

  Paragraphs are separated by `'\n'` present in any Text child.

  Example of a TextFlow:

           Text text1 = new Text("Big italic red text");
           text1.setFill(Color.RED);
           text1.setFont(Font.font("Helvetica", FontPosture.ITALIC, 40));
           Text text2 = new Text(" little bold blue text");
           text2.setFill(Color.BLUE);
           text2.setFont(Font.font("Helvetica", FontWeight.BOLD, 10));
           TextFlow textFlow = new TextFlow(text1, text2);

  TextFlow lays out each managed child regardless of the child's visible property value; unmanaged children are ignored for all layout calculations.

  TextFlow may be styled with backgrounds and borders using CSS. See `Region` superclass for details.

  ## Resizable Range

  A textflow's parent will resize the textflow within the textflow's range during layout. By default the textflow computes this range based on its content as outlined in the tables below.

  TextFlow Resize Table
  | width | height
  minimum | left/right insets | top/bottom insets plus the height of the text content
  preferred | left/right insets plus the width of the text content | top/bottom insets plus the height of the text content
  maximum | Double.MAX_VALUE | Double.MAX_VALUE

  A textflow's unbounded maximum width and height are an indication to the parent that it may be resized beyond its preferred size to fill whatever space is assigned to it.

  TextFlow provides properties for setting the size range directly. These properties default to the sentinel value Region.USE_COMPUTED_SIZE, however the application may set them to other values as needed:

           textflow.setMaxWidth(500);

  Applications may restore the computed values by setting these properties back to Region.USE_COMPUTED_SIZE.

  TextFlow does not clip its content by default, so it is possible that childrens' bounds may extend outside its own bounds if a child's pref size is larger than the space textflow has to allocate for it.

  Since:
    JavaFX 8.0

- - ### Property Summary

    Properties
    Type | Property | Description
    --- | --- | ---
    `DoubleProperty` | `lineSpacing` | Defines the vertical space in pixel between lines.
    `IntegerProperty` | `tabSize` | The size of a tab stop in spaces.
    `ObjectProperty<TextAlignment>` | `textAlignment` | Defines horizontal text alignment.

    - ### Properties declared in class javafx.scene.layout.Region

      `background, border, cacheShape, centerShape, height, insets, maxHeight, maxWidth, minHeight, minWidth, opaqueInsets, padding, prefHeight, prefWidth, scaleShape, shape, snapToPixel, width`

    - ### Properties declared in class javafx.scene.Parent

      `needsLayout`

    - ### Properties declared in class javafx.scene.Node

      `accessibleHelp, accessibleRoleDescription, accessibleRole, accessibleText, blendMode, boundsInLocal, boundsInParent, cacheHint, cache, clip, cursor, depthTest, disabled, disable, effectiveNodeOrientation, effect, eventDispatcher, focused, focusTraversable, hover, id, inputMethodRequests, layoutBounds, layoutX, layoutY, localToParentTransform, localToSceneTransform, managed, mouseTransparent, nodeOrientation, onContextMenuRequested, onDragDetected, onDragDone, onDragDropped, onDragEntered, onDragExited, onDragOver, onInputMethodTextChanged, onKeyPressed, onKeyReleased, onKeyTyped, onMouseClicked, onMouseDragEntered, onMouseDragExited, onMouseDragged, onMouseDragOver, onMouseDragReleased, onMouseEntered, onMouseExited, onMouseMoved, onMousePressed, onMouseReleased, onRotate, onRotationFinished, onRotationStarted, onScrollFinished, onScroll, onScrollStarted, onSwipeDown, onSwipeLeft, onSwipeRight, onSwipeUp, onTouchMoved, onTouchPressed, onTouchReleased, onTouchStationary, onZoomFinished, onZoom, onZoomStarted, opacity, parent, pickOnBounds, pressed, rotate, rotationAxis, scaleX, scaleY, scaleZ, scene, style, translateX, translateY, translateZ, viewOrder, visible`

  - ### Field Summary

    - ### Fields declared in class javafx.scene.layout.Region

      `USE_COMPUTED_SIZE, USE_PREF_SIZE`

    - ### Fields declared in class javafx.scene.Node

      `BASELINE_OFFSET_SAME_AS_HEIGHT`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `TextFlow()` | Creates an empty TextFlow layout.
    `TextFlow​(Node... children)` | Creates a TextFlow layout with the given children.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `PathElement[]` | `caretShape​(int charIndex, boolean leading)` | Returns shape of caret in local coordinates.
    `static List<CssMetaData<? extends Styleable,​?>>` | `getClassCssMetaData()` |
    `double` | `getLineSpacing()` | Gets the value of the property lineSpacing.
    `int` | `getTabSize()` | Gets the value of the property tabSize.
    `TextAlignment` | `getTextAlignment()` | Gets the value of the property textAlignment.
    `HitInfo` | `hitTest​(Point2D point)` | Maps local point to index in the content.
    `DoubleProperty` | `lineSpacingProperty()` | Defines the vertical space in pixel between lines.
    `PathElement[]` | `rangeShape​(int start, int end)` | Returns shape for the range of the text in local coordinates.
    `void` | `setLineSpacing​(double spacing)` | Sets the value of the property lineSpacing.
    `void` | `setTabSize​(int spaces)` | Sets the value of the property tabSize.
    `void` | `setTextAlignment​(TextAlignment value)` | Sets the value of the property textAlignment.
    `IntegerProperty` | `tabSizeProperty()` | The size of a tab stop in spaces.
    `ObjectProperty<TextAlignment>` | `textAlignmentProperty()` | Defines horizontal text alignment.

    - ### Methods declared in class javafx.scene.layout.Pane

      `getChildren`

    - ### Methods declared in class javafx.scene.layout.Region

      `backgroundProperty, borderProperty, cacheShapeProperty, centerShapeProperty, computeMaxHeight, computeMaxWidth, computeMinHeight, computeMinWidth, computePrefHeight, computePrefWidth, getBackground, getBorder, getCssMetaData, getHeight, getInsets, getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, getOpaqueInsets, getPadding, getPrefHeight, getPrefWidth, getShape, getUserAgentStylesheet, getWidth, heightProperty, insetsProperty, isCacheShape, isCenterShape, isResizable, isScaleShape, isSnapToPixel, layoutInArea, layoutInArea, layoutInArea, layoutInArea, maxHeight, maxHeightProperty, maxWidth, maxWidthProperty, minHeight, minHeightProperty, minWidth, minWidthProperty, opaqueInsetsProperty, paddingProperty, positionInArea, positionInArea, prefHeight, prefHeightProperty, prefWidth, prefWidthProperty, resize, scaleShapeProperty, setBackground, setBorder, setCacheShape, setCenterShape, setHeight, setMaxHeight, setMaxSize, setMaxWidth, setMinHeight, setMinSize, setMinWidth, setOpaqueInsets, setPadding, setPrefHeight, setPrefSize, setPrefWidth, setScaleShape, setShape, setSnapToPixel, setWidth, shapeProperty, snappedBottomInset, snappedLeftInset, snappedRightInset, snappedTopInset, snapPosition, snapPositionX, snapPositionY, snapSize, snapSizeX, snapSizeY, snapSpace, snapSpaceX, snapSpaceY, snapToPixelProperty, widthProperty`

    - ### Methods declared in class javafx.scene.Parent

      `getBaselineOffset, getChildrenUnmodifiable, getManagedChildren, getStylesheets, isNeedsLayout, layout, layoutChildren, needsLayoutProperty, requestLayout, requestParentLayout, setNeedsLayout, updateBounds`

    - ### Methods declared in class javafx.scene.Node

      `accessibleHelpProperty, accessibleRoleDescriptionProperty, accessibleRoleProperty, accessibleTextProperty, addEventFilter, addEventHandler, applyCss, autosize, blendModeProperty, boundsInLocalProperty, boundsInParentProperty, buildEventDispatchChain, cacheHintProperty, cacheProperty, clipProperty, computeAreaInScreen, contains, contains, cursorProperty, depthTestProperty, disabledProperty, disableProperty, effectiveNodeOrientationProperty, effectProperty, eventDispatcherProperty, executeAccessibleAction, fireEvent, focusedProperty, focusTraversableProperty, getAccessibleHelp, getAccessibleRole, getAccessibleRoleDescription, getAccessibleText, getBlendMode, getBoundsInLocal, getBoundsInParent, getCacheHint, getClip, getContentBias, getCursor, getDepthTest, getEffect, getEffectiveNodeOrientation, getEventDispatcher, getId, getInitialCursor, getInitialFocusTraversable, getInputMethodRequests, getLayoutBounds, getLayoutX, getLayoutY, getLocalToParentTransform, getLocalToSceneTransform, getNodeOrientation, getOnContextMenuRequested, getOnDragDetected, getOnDragDone, getOnDragDropped, getOnDragEntered, getOnDragExited, getOnDragOver, getOnInputMethodTextChanged, getOnKeyPressed, getOnKeyReleased, getOnKeyTyped, getOnMouseClicked, getOnMouseDragEntered, getOnMouseDragExited, getOnMouseDragged, getOnMouseDragOver, getOnMouseDragReleased, getOnMouseEntered, getOnMouseExited, getOnMouseMoved, getOnMousePressed, getOnMouseReleased, getOnRotate, getOnRotationFinished, getOnRotationStarted, getOnScroll, getOnScrollFinished, getOnScrollStarted, getOnSwipeDown, getOnSwipeLeft, getOnSwipeRight, getOnSwipeUp, getOnTouchMoved, getOnTouchPressed, getOnTouchReleased, getOnTouchStationary, getOnZoom, getOnZoomFinished, getOnZoomStarted, getOpacity, getParent, getProperties, getPseudoClassStates, getRotate, getRotationAxis, getScaleX, getScaleY, getScaleZ, getScene, getStyle, getStyleableParent, getTransforms, getTranslateX, getTranslateY, getTranslateZ, getTypeSelector, getUserData, getViewOrder, hasProperties, hoverProperty, idProperty, inputMethodRequestsProperty, intersects, intersects, isCache, isDisable, isDisabled, isFocused, isFocusTraversable, isHover, isManaged, isMouseTransparent, isPickOnBounds, isPressed, isVisible, layoutBoundsProperty, layoutXProperty, layoutYProperty, localToParent, localToParent, localToParent, localToParent, localToParent, localToParentTransformProperty, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToSceneTransformProperty, localToScreen, localToScreen, localToScreen, localToScreen, localToScreen, lookup, lookupAll, managedProperty, mouseTransparentProperty, nodeOrientationProperty, notifyAccessibleAttributeChanged, onContextMenuRequestedProperty, onDragDetectedProperty, onDragDoneProperty, onDragDroppedProperty, onDragEnteredProperty, onDragExitedProperty, onDragOverProperty, onInputMethodTextChangedProperty, onKeyPressedProperty, onKeyReleasedProperty, onKeyTypedProperty, onMouseClickedProperty, onMouseDragEnteredProperty, onMouseDragExitedProperty, onMouseDraggedProperty, onMouseDragOverProperty, onMouseDragReleasedProperty, onMouseEnteredProperty, onMouseExitedProperty, onMouseMovedProperty, onMousePressedProperty, onMouseReleasedProperty, onRotateProperty, onRotationFinishedProperty, onRotationStartedProperty, onScrollFinishedProperty, onScrollProperty, onScrollStartedProperty, onSwipeDownProperty, onSwipeLeftProperty, onSwipeRightProperty, onSwipeUpProperty, onTouchMovedProperty, onTouchPressedProperty, onTouchReleasedProperty, onTouchStationaryProperty, onZoomFinishedProperty, onZoomProperty, onZoomStartedProperty, opacityProperty, parentProperty, parentToLocal, parentToLocal, parentToLocal, parentToLocal, parentToLocal, pickOnBoundsProperty, pressedProperty, pseudoClassStateChanged, queryAccessibleAttribute, relocate, removeEventFilter, removeEventHandler, requestFocus, resizeRelocate, rotateProperty, rotationAxisProperty, scaleXProperty, scaleYProperty, scaleZProperty, sceneProperty, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, screenToLocal, screenToLocal, screenToLocal, setAccessibleHelp, setAccessibleRole, setAccessibleRoleDescription, setAccessibleText, setBlendMode, setCache, setCacheHint, setClip, setCursor, setDepthTest, setDisable, setDisabled, setEffect, setEventDispatcher, setEventHandler, setFocused, setFocusTraversable, setHover, setId, setInputMethodRequests, setLayoutX, setLayoutY, setManaged, setMouseTransparent, setNodeOrientation, setOnContextMenuRequested, setOnDragDetected, setOnDragDone, setOnDragDropped, setOnDragEntered, setOnDragExited, setOnDragOver, setOnInputMethodTextChanged, setOnKeyPressed, setOnKeyReleased, setOnKeyTyped, setOnMouseClicked, setOnMouseDragEntered, setOnMouseDragExited, setOnMouseDragged, setOnMouseDragOver, setOnMouseDragReleased, setOnMouseEntered, setOnMouseExited, setOnMouseMoved, setOnMousePressed, setOnMouseReleased, setOnRotate, setOnRotationFinished, setOnRotationStarted, setOnScroll, setOnScrollFinished, setOnScrollStarted, setOnSwipeDown, setOnSwipeLeft, setOnSwipeRight, setOnSwipeUp, setOnTouchMoved, setOnTouchPressed, setOnTouchReleased, setOnTouchStationary, setOnZoom, setOnZoomFinished, setOnZoomStarted, setOpacity, setPickOnBounds, setPressed, setRotate, setRotationAxis, setScaleX, setScaleY, setScaleZ, setStyle, setTranslateX, setTranslateY, setTranslateZ, setUserData, setViewOrder, setVisible, snapshot, snapshot, startDragAndDrop, startFullDrag, styleProperty, toBack, toFront, toString, translateXProperty, translateYProperty, translateZProperty, usesMirroring, viewOrderProperty, visibleProperty`

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

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

    - ### Methods declared in interface javafx.css.Styleable

      `getStyleableNode, getStyleClass`

- - ### Property Detail

    - #### textAlignment

          public final ObjectProperty<TextAlignment> textAlignmentProperty

      Defines horizontal text alignment.
      Default value:
        TextAlignment.LEFT
      See Also:
        `getTextAlignment()`, `setTextAlignment(TextAlignment)`

    - #### lineSpacing

          public final DoubleProperty lineSpacingProperty

      Defines the vertical space in pixel between lines.
      Default value:
        0
      Since:
        JavaFX 8.0
      See Also:
        `getLineSpacing()`, `setLineSpacing(double)`

    - #### tabSize

          public final IntegerProperty tabSizeProperty

      The size of a tab stop in spaces. Values less than 1 are treated as 1. This value overrides the `tabSize` of contained `Text` nodes.
      Default value:
        8
      Since:
        14
      See Also:
        `getTabSize()`, `setTabSize(int)`

  - ### Constructor Detail

    - #### TextFlow

          public TextFlow()

      Creates an empty TextFlow layout.

    - #### TextFlow

          public TextFlow​(Node... children)

      Creates a TextFlow layout with the given children.
      Parameters:
        `children` - children.

  - ### Method Detail

    - #### hitTest

          public final HitInfo hitTest​(Point2D point)

      Maps local point to index in the content.
      Parameters:
        `point` - the specified point to be tested
      Returns:
        a `HitInfo` representing the character index found
      Since:
        9

    - #### caretShape

          public PathElement[] caretShape​(int charIndex,
                                          boolean leading)

      Returns shape of caret in local coordinates.
      Parameters:
        `charIndex` - the character index for the caret
        `leading` - whether the caret is biased on the leading edge of the character
      Returns:
        an array of `PathElement` which can be used to create a `Shape`
      Since:
        9

    - #### rangeShape

          public final PathElement[] rangeShape​(int start,
                                                int end)

      Returns shape for the range of the text in local coordinates.
      Parameters:
        `start` - the beginning character index for the range
        `end` - the end character index (non-inclusive) for the range
      Returns:
        an array of `PathElement` which can be used to create a `Shape`
      Since:
        9

    - #### setTextAlignment

          public final void setTextAlignment​(TextAlignment value)

      Sets the value of the property textAlignment.
      Property description:
        Defines horizontal text alignment.
      Default value:
        TextAlignment.LEFT

    - #### getTextAlignment

          public final TextAlignment getTextAlignment()

      Gets the value of the property textAlignment.
      Property description:
        Defines horizontal text alignment.
      Default value:
        TextAlignment.LEFT

    - #### textAlignmentProperty

          public final ObjectProperty<TextAlignment> textAlignmentProperty()

      Defines horizontal text alignment.
      Default value:
        TextAlignment.LEFT
      See Also:
        `getTextAlignment()`, `setTextAlignment(TextAlignment)`

    - #### setLineSpacing

          public final void setLineSpacing​(double spacing)

      Sets the value of the property lineSpacing.
      Property description:
        Defines the vertical space in pixel between lines.
      Default value:
        0
      Since:
        JavaFX 8.0

    - #### getLineSpacing

          public final double getLineSpacing()

      Gets the value of the property lineSpacing.
      Property description:
        Defines the vertical space in pixel between lines.
      Default value:
        0
      Since:
        JavaFX 8.0

    - #### lineSpacingProperty

          public final DoubleProperty lineSpacingProperty()

      Defines the vertical space in pixel between lines.
      Default value:
        0
      Since:
        JavaFX 8.0
      See Also:
        `getLineSpacing()`, `setLineSpacing(double)`

    - #### tabSizeProperty

          public final IntegerProperty tabSizeProperty()

      The size of a tab stop in spaces. Values less than 1 are treated as 1. This value overrides the `tabSize` of contained `Text` nodes.
      Default value:
        8
      Since:
        14
      See Also:
        `getTabSize()`, `setTabSize(int)`

    - #### getTabSize

          public final int getTabSize()

      Gets the value of the property tabSize.
      Property description:
        The size of a tab stop in spaces. Values less than 1 are treated as 1. This value overrides the `tabSize` of contained `Text` nodes.
      Default value:
        8
      Since:
        14

    - #### setTabSize

          public final void setTabSize​(int spaces)

      Sets the value of the property tabSize.
      Property description:
        The size of a tab stop in spaces. Values less than 1 are treated as 1. This value overrides the `tabSize` of contained `Text` nodes.
      Default value:
        8
      Since:
        14

    - #### getClassCssMetaData

          public static List<CssMetaData<? extends Styleable,​?>> getClassCssMetaData()

      Returns:
        The CssMetaData associated with this class, which may include the CssMetaData of its superclasses.