org.apache.poi.xslf.usermodel

## Class XSLFTextShape

- java.lang.Object
- - org.apache.poi.xslf.usermodel.XSLFShape
  - - org.apache.poi.xslf.usermodel.XSLFSimpleShape
    - - org.apache.poi.xslf.usermodel.XSLFTextShape

- All Implemented Interfaces:
    java.lang.Iterable<XSLFTextParagraph>, IAdjustableShape, PlaceableShape<XSLFShape,XSLFTextParagraph>, Shape<XSLFShape,XSLFTextParagraph>, SimpleShape<XSLFShape,XSLFTextParagraph>, TextShape<XSLFShape,XSLFTextParagraph>, TextContainer
  Direct Known Subclasses:
    XSLFAutoShape, XSLFTableCell

      @Beta
      public abstract class XSLFTextShape
      extends XSLFSimpleShape
      implements TextContainer, TextShape<XSLFShape,XSLFTextParagraph>

  Represents a shape that can hold text.

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.apache.poi.xslf.usermodel.XSLFShape

      `XSLFShape.ReparseFactory<T extends org.apache.xmlbeans.XmlObject>`

    - ### Nested classes/interfaces inherited from interface org.apache.poi.sl.usermodel.TextShape

      `TextShape.TextAutofit, TextShape.TextDirection, TextShape.TextPlaceholder`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `XSLFTextParagraph` | `addNewTextParagraph()` add a new paragraph run to this shape
    `XSLFTextRun` | `appendText(java.lang.String text, boolean newParagraph)` Adds the supplied text onto the end of the TextParagraphs, creating a new RichTextRun for it to sit in.
    `void` | `clearText()` unset text from this shape
    `<R> java.util.Optional<R>` | `findDefinedParagraphProperty(java.util.function.Function<org.openxmlformats.schemas.drawingml.x2006.main.CTTextParagraphProperties,java.lang.Boolean> isSet, java.util.function.Function<org.openxmlformats.schemas.drawingml.x2006.main.CTTextParagraphProperties,R> getter)`
    `<R> java.util.Optional<R>` | `findDefinedRunProperty(java.util.function.Function<org.openxmlformats.schemas.drawingml.x2006.main.CTTextCharacterProperties,java.lang.Boolean> isSet, java.util.function.Function<org.openxmlformats.schemas.drawingml.x2006.main.CTTextCharacterProperties,R> getter)`
    `double` | `getBottomInset()` Returns the distance (in points) between the bottom of the text frame and the bottom of the inscribed rectangle of the shape that contains the text.
    `Insets2D` | `getInsets()`
    `double` | `getLeftInset()` Returns the distance (in points) between the left edge of the text frame and the left edge of the inscribed rectangle of the shape that contains the text.
    `double` | `getRightInset()` Returns the distance (in points) between the right edge of the text frame and the right edge of the inscribed rectangle of the shape that contains the text.
    `java.lang.String` | `getText()` Returns the text contained in this text frame, which has been made safe for printing and other use.
    `TextShape.TextAutofit` | `getTextAutofit()`
    `XDDFTextBody` | `getTextBody()`
    `protected abstract org.openxmlformats.schemas.drawingml.x2006.main.CTTextBody` | `getTextBody(boolean create)`
    `protected org.openxmlformats.schemas.drawingml.x2006.main.CTTextBodyProperties` | `getTextBodyPr()`
    `protected org.openxmlformats.schemas.drawingml.x2006.main.CTTextBodyProperties` | `getTextBodyPr(boolean create)`
    `TextShape.TextDirection` | `getTextDirection()`
    `double` | `getTextHeight()` Compute the cumulative height occupied by the text
    `double` | `getTextHeight(java.awt.Graphics2D graphics)` Compute the cumulative height occupied by the text
    `java.util.List<XSLFTextParagraph>` | `getTextParagraphs()`
    `TextShape.TextPlaceholder` | `getTextPlaceholder()`
    `java.lang.Double` | `getTextRotation()` The text rotation can be independent specified from the shape rotation.
    `Placeholder` | `getTextType()`
    `double` | `getTopInset()` Returns the distance (in points) between the top of the text frame and the top of the inscribed rectangle of the shape that contains the text.
    `VerticalAlignment` | `getVerticalAlignment()` Returns the type of vertical alignment for the text.
    `boolean` | `getWordWrap()`
    `boolean` | `isHorizontalCentered()` Returns if the text is centered.
    `java.util.Iterator<XSLFTextParagraph>` | `iterator()`
    `protected XSLFTextParagraph` | `newTextParagraph(org.openxmlformats.schemas.drawingml.x2006.main.CTTextParagraph p)` Helper method to allow subclasses to provide their own text paragraph
    `java.awt.geom.Rectangle2D` | `resizeToFitText()` Adjust the size of the shape so it encompasses the text inside it.
    `java.awt.geom.Rectangle2D` | `resizeToFitText(java.awt.Graphics2D graphics)` Adjust the size of the shape so it encompasses the text inside it.
    `void` | `setBottomInset(double margin)` Sets the bottom margin.
    `void` | `setHorizontalCentered(java.lang.Boolean isCentered)` Sets if the paragraphs are horizontal centered
    `void` | `setInsets(Insets2D insets)` Sets the shape margins
    `void` | `setLeftInset(double margin)` Sets the left margin.
    `void` | `setPlaceholder(Placeholder placeholder)` Specifies that the corresponding shape should be represented by the generating application as a placeholder.
    `void` | `setRightInset(double margin)` Sets the right margin.
    `XSLFTextRun` | `setText(java.lang.String text)` Sets (overwrites) the current text.
    `void` | `setTextAutofit(TextShape.TextAutofit value)` Specifies that a shape should be auto-fit to fully contain the text described within it.
    `void` | `setTextDirection(TextShape.TextDirection orientation)` sets the vertical orientation
    `void` | `setTextPlaceholder(TextShape.TextPlaceholder placeholder)` Sets the text placeholder
    `void` | `setTextRotation(java.lang.Double rotation)` Sets the text rotation.
    `void` | `setTopInset(double margin)` Sets the top margin.
    `void` | `setVerticalAlignment(VerticalAlignment anchor)` Sets the type of vertical alignment for the text.
    `void` | `setWordWrap(boolean wrap)`

    - ### Methods inherited from class org.apache.poi.xslf.usermodel.XSLFSimpleShape

      `createHyperlink, getAdjustValue, getAnchor, getFillColor, getFillStyle, getFlipHorizontal, getFlipVertical, getGeometry, getHyperlink, getLineCap, getLineColor, getLineCompound, getLineDash, getLineDecoration, getLineHeadDecoration, getLineHeadLength, getLineHeadWidth, getLinePaint, getLineTailDecoration, getLineTailLength, getLineTailWidth, getLineWidth, getRotation, getShadow, getShapeType, getStrokeStyle, getXfrm, setAnchor, setFillColor, setFlipHorizontal, setFlipVertical, setLineCap, setLineColor, setLineCompound, setLineDash, setLineHeadDecoration, setLineHeadLength, setLineHeadWidth, setLineTailDecoration, setLineTailLength, setLineTailWidth, setLineWidth, setRotation, setShapeType, setStrokeStyle`

    - ### Methods inherited from class org.apache.poi.xslf.usermodel.XSLFShape

      `draw, fetchShapeProperty, getBgPr, getBgRef, getChild, getCNvPr, getFillPaint, getGrpSpPr, getParent, getPlaceholder, getPlaceholderDetails, getShapeId, getShapeName, getShapeProperties, getSheet, getSpStyle, getXmlObject, isPlaceholder, selectPaint, selectPaint, selectPaint, selectPaint, selectPaint, selectProperty, selectProperty, setParent`

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface org.apache.poi.sl.usermodel.SimpleShape

      `createHyperlink, getFillColor, getFillStyle, getGeometry, getHyperlink, getLineDecoration, getPlaceholder, getPlaceholderDetails, getShadow, getShapeType, getStrokeStyle, isPlaceholder, setFillColor, setShapeType, setStrokeStyle`

    - ### Methods inherited from interface org.apache.poi.sl.usermodel.Shape

      `draw, getAnchor, getParent, getShapeId, getShapeName, getSheet`

    - ### Methods inherited from interface org.apache.poi.sl.draw.geom.IAdjustableShape

      `getAdjustValue`

    - ### Methods inherited from interface org.apache.poi.sl.usermodel.PlaceableShape

      `getAnchor, getFlipHorizontal, getFlipVertical, getParent, getRotation, getSheet, setAnchor, setFlipHorizontal, setFlipVertical, setRotation`

    - ### Methods inherited from interface java.lang.Iterable

      `forEach, spliterator`

- - ### Method Detail

    - #### getTextBody

          @Beta
          public XDDFTextBody getTextBody()

    - #### iterator

          public java.util.Iterator<XSLFTextParagraph> iterator()

      Specified by:
        `iterator` in interface `java.lang.Iterable<XSLFTextParagraph>`

    - #### getText

          public java.lang.String getText()

      Description copied from interface: `TextShape`
      Returns the text contained in this text frame, which has been made safe for printing and other use.
      Specified by:
        `getText` in interface `TextShape<XSLFShape,XSLFTextParagraph>`
      Returns:
        the text string for this textbox.

    - #### clearText

          public void clearText()

      unset text from this shape

    - #### setText

          public XSLFTextRun setText(java.lang.String text)

      Description copied from interface: `TextShape`
      Sets (overwrites) the current text. Uses the properties of the first paragraph / textrun. Text paragraphs are split by \\r or \\n. New lines within text run are split by \\u000b
      Specified by:
        `setText` in interface `TextShape<XSLFShape,XSLFTextParagraph>`
      Parameters:
        `text` - the text string used by this object.
      Returns:
        the last text run of the - potential split - text

    - #### appendText

          public XSLFTextRun appendText(java.lang.String text,
                                        boolean newParagraph)

      Description copied from interface: `TextShape`
      Adds the supplied text onto the end of the TextParagraphs, creating a new RichTextRun for it to sit in.
      Specified by:
        `appendText` in interface `TextShape<XSLFShape,XSLFTextParagraph>`
      Parameters:
        `text` - the text string to be appended.
        `newParagraph` - if true, a new paragraph will be added, which will contain the added text

    - #### getTextParagraphs

          public java.util.List<XSLFTextParagraph> getTextParagraphs()

      Specified by:
        `getTextParagraphs` in interface `TextShape<XSLFShape,XSLFTextParagraph>`
      Returns:
        the TextParagraphs for this text box

    - #### addNewTextParagraph

          public XSLFTextParagraph addNewTextParagraph()

      add a new paragraph run to this shape
      Returns:
        created paragraph run

    - #### setVerticalAlignment

          public void setVerticalAlignment(VerticalAlignment anchor)

      Description copied from interface: `TextShape`
      Sets the type of vertical alignment for the text.
      Specified by:
        `setVerticalAlignment` in interface `TextShape<XSLFShape,XSLFTextParagraph>`
      Parameters:
        `anchor` - - the type of alignment. A `null` values unsets this property.

    - #### getVerticalAlignment

          public VerticalAlignment getVerticalAlignment()

      Description copied from interface: `TextShape`
      Returns the type of vertical alignment for the text.
      Specified by:
        `getVerticalAlignment` in interface `TextShape<XSLFShape,XSLFTextParagraph>`
      Returns:
        the type of vertical alignment

    - #### setHorizontalCentered

          public void setHorizontalCentered(java.lang.Boolean isCentered)

      Description copied from interface: `TextShape`
      Sets if the paragraphs are horizontal centered
      Specified by:
        `setHorizontalCentered` in interface `TextShape<XSLFShape,XSLFTextParagraph>`
      Parameters:
        `isCentered` - true, if the paragraphs are horizontal centered A `null` values unsets this property.

    - #### isHorizontalCentered

          public boolean isHorizontalCentered()

      Description copied from interface: `TextShape`
      Returns if the text is centered. If true and if the individual paragraph settings allow it, the whole text block will be displayed centered, i.e. its left and right margin will be maximized while still keeping the alignment of the paragraphs
      Specified by:
        `isHorizontalCentered` in interface `TextShape<XSLFShape,XSLFTextParagraph>`
      Returns:
        true, if the text anchor is horizontal centered

    - #### setTextDirection

          public void setTextDirection(TextShape.TextDirection orientation)

      Description copied from interface: `TextShape`
      sets the vertical orientation
      Specified by:
        `setTextDirection` in interface `TextShape<XSLFShape,XSLFTextParagraph>`
      Parameters:
        `orientation` - vertical orientation of the text

    - #### getTextDirection

          public TextShape.TextDirection getTextDirection()

      Specified by:
        `getTextDirection` in interface `TextShape<XSLFShape,XSLFTextParagraph>`
      Returns:
        vertical orientation of the text

    - #### getTextRotation

          public java.lang.Double getTextRotation()

      Description copied from interface: `TextShape`
      The text rotation can be independent specified from the shape rotation. For XSLF this can be an arbitrary degree, for HSLF the degree is given in steps of 90 degrees
      Specified by:
        `getTextRotation` in interface `TextShape<XSLFShape,XSLFTextParagraph>`
      Returns:
        text rotation in degrees, returns null if no rotation is given

    - #### setTextRotation

          public void setTextRotation(java.lang.Double rotation)

      Description copied from interface: `TextShape`
      Sets the text rotation. For XSLF this can ben an arbitrary degree, for HSLF the rotation is rounded to next 90 degree step
      Specified by:
        `setTextRotation` in interface `TextShape<XSLFShape,XSLFTextParagraph>`
      Parameters:
        `rotation` - the text rotation, or null to unset the rotation

    - #### getBottomInset

          public double getBottomInset()

      Returns the distance (in points) between the bottom of the text frame and the bottom of the inscribed rectangle of the shape that contains the text.
      Returns:
        the bottom inset in points

    - #### getLeftInset

          public double getLeftInset()

      Returns the distance (in points) between the left edge of the text frame and the left edge of the inscribed rectangle of the shape that contains the text.
      Returns:
        the left inset in points

    - #### getRightInset

          public double getRightInset()

      Returns the distance (in points) between the right edge of the text frame and the right edge of the inscribed rectangle of the shape that contains the text.
      Returns:
        the right inset in points

    - #### getTopInset

          public double getTopInset()

      Returns the distance (in points) between the top of the text frame and the top of the inscribed rectangle of the shape that contains the text.
      Returns:
        the top inset in points

    - #### setBottomInset

          public void setBottomInset(double margin)

      Sets the bottom margin.
      Parameters:
        `margin` - the bottom margin
      See Also:
        `getBottomInset()`

    - #### setLeftInset

          public void setLeftInset(double margin)

      Sets the left margin.
      Parameters:
        `margin` - the left margin
      See Also:
        `getLeftInset()`

    - #### setRightInset

          public void setRightInset(double margin)

      Sets the right margin.
      Parameters:
        `margin` - the right margin
      See Also:
        `getRightInset()`

    - #### setTopInset

          public void setTopInset(double margin)

      Sets the top margin.
      Parameters:
        `margin` - the top margin
      See Also:
        `getTopInset()`

    - #### getInsets

          public Insets2D getInsets()

      Specified by:
        `getInsets` in interface `TextShape<XSLFShape,XSLFTextParagraph>`
      Returns:
        text shape margin

    - #### setInsets

          public void setInsets(Insets2D insets)

      Description copied from interface: `TextShape`
      Sets the shape margins
      Specified by:
        `setInsets` in interface `TextShape<XSLFShape,XSLFTextParagraph>`
      Parameters:
        `insets` - the new shape margins

    - #### getWordWrap

          public boolean getWordWrap()

      Specified by:
        `getWordWrap` in interface `TextShape<XSLFShape,XSLFTextParagraph>`
      Returns:
        whether to wrap words within the bounding rectangle

    - #### setWordWrap

          public void setWordWrap(boolean wrap)

      Specified by:
        `setWordWrap` in interface `TextShape<XSLFShape,XSLFTextParagraph>`
      Parameters:
        `wrap` - whether to wrap words within the bounding rectangle

    - #### setTextAutofit

          public void setTextAutofit(TextShape.TextAutofit value)

      Specifies that a shape should be auto-fit to fully contain the text described within it. Auto-fitting is when text within a shape is scaled in order to contain all the text inside
      Parameters:
        `value` - type of autofit

    - #### getTextAutofit

          public TextShape.TextAutofit getTextAutofit()

      Returns:
        type of autofit

    - #### getTextBodyPr

          protected org.openxmlformats.schemas.drawingml.x2006.main.CTTextBodyProperties getTextBodyPr()

    - #### getTextBodyPr

          protected org.openxmlformats.schemas.drawingml.x2006.main.CTTextBodyProperties getTextBodyPr(boolean create)

    - #### getTextBody

          protected abstract org.openxmlformats.schemas.drawingml.x2006.main.CTTextBody getTextBody(boolean create)

    - #### setPlaceholder

          public void setPlaceholder(Placeholder placeholder)

      Description copied from interface: `SimpleShape`
      Specifies that the corresponding shape should be represented by the generating application as a placeholder. When a shape is considered a placeholder by the generating application it can have special properties to alert the user that they may enter content into the shape.
      Specified by:
        `setPlaceholder` in interface `SimpleShape<XSLFShape,XSLFTextParagraph>`
      Overrides:
        `setPlaceholder` in class `XSLFShape`
      Parameters:
        `placeholder` - the placeholder or null to remove the reference to the placeholder
      See Also:
        `PlaceholderDetails.setPlaceholder(Placeholder)`

    - #### getTextType

          public Placeholder getTextType()

    - #### getTextHeight

          public double getTextHeight()

      Description copied from interface: `TextShape`
      Compute the cumulative height occupied by the text
      Specified by:
        `getTextHeight` in interface `TextShape<XSLFShape,XSLFTextParagraph>`
      Returns:
        the cumulative height occupied by the text

    - #### getTextHeight

          public double getTextHeight(java.awt.Graphics2D graphics)

      Description copied from interface: `TextShape`
      Compute the cumulative height occupied by the text
      Specified by:
        `getTextHeight` in interface `TextShape<XSLFShape,XSLFTextParagraph>`
      Parameters:
        `graphics` - a customized graphics context, e.g. which contains font mappings
      Returns:
        the cumulative height occupied by the text

    - #### resizeToFitText

          public java.awt.geom.Rectangle2D resizeToFitText()

      Description copied from interface: `TextShape`
      Adjust the size of the shape so it encompasses the text inside it.
      Specified by:
        `resizeToFitText` in interface `TextShape<XSLFShape,XSLFTextParagraph>`
      Returns:
        a `Rectangle2D` that is the bounds of this shape.

    - #### resizeToFitText

          public java.awt.geom.Rectangle2D resizeToFitText(java.awt.Graphics2D graphics)

      Description copied from interface: `TextShape`
      Adjust the size of the shape so it encompasses the text inside it.
      Specified by:
        `resizeToFitText` in interface `TextShape<XSLFShape,XSLFTextParagraph>`
      Parameters:
        `graphics` - a customized graphics context, e.g. which contains font mappings
      Returns:
        a `Rectangle2D` that is the bounds of this shape.

    - #### setTextPlaceholder

          public void setTextPlaceholder(TextShape.TextPlaceholder placeholder)

      Description copied from interface: `TextShape`
      Sets the text placeholder
      Specified by:
        `setTextPlaceholder` in interface `TextShape<XSLFShape,XSLFTextParagraph>`

    - #### getTextPlaceholder

          public TextShape.TextPlaceholder getTextPlaceholder()

      Specified by:
        `getTextPlaceholder` in interface `TextShape<XSLFShape,XSLFTextParagraph>`
      Returns:
        the text placeholder

    - #### newTextParagraph

          protected XSLFTextParagraph newTextParagraph(org.openxmlformats.schemas.drawingml.x2006.main.CTTextParagraph p)

      Helper method to allow subclasses to provide their own text paragraph
      Parameters:
        `p` - the xml reference
      Returns:
        a new text paragraph
      Since:
        POI 3.15-beta2

    - #### findDefinedParagraphProperty

          public <R> java.util.Optional<R> findDefinedParagraphProperty(java.util.function.Function<org.openxmlformats.schemas.drawingml.x2006.main.CTTextParagraphProperties,java.lang.Boolean> isSet,
                                                                        java.util.function.Function<org.openxmlformats.schemas.drawingml.x2006.main.CTTextParagraphProperties,R> getter)

      Specified by:
        `findDefinedParagraphProperty` in interface `TextContainer`

    - #### findDefinedRunProperty

          public <R> java.util.Optional<R> findDefinedRunProperty(java.util.function.Function<org.openxmlformats.schemas.drawingml.x2006.main.CTTextCharacterProperties,java.lang.Boolean> isSet,
                                                                  java.util.function.Function<org.openxmlformats.schemas.drawingml.x2006.main.CTTextCharacterProperties,R> getter)

      Specified by:
        `findDefinedRunProperty` in interface `TextContainer`

Copyright 2020 The Apache Software Foundation or its licensors, as applicable.