Package org.apache.poi.xwpf.usermodel

Class XWPFRun

java.lang.Object
org.apache.poi.xwpf.usermodel.XWPFRun
All Implemented Interfaces:
CharacterRun, IRunElement, ISDTContents
Direct Known Subclasses:
XWPFFieldRun, XWPFHyperlinkRun
public class XWPFRun extends Object implements ISDTContents, IRunElement, CharacterRun
XWPFRun object defines a region of text with a common set of properties

  • Constructor Details

  • Method Details

    • getCTR

      @Internal public CTR getCTR()
      Get the currently used CTR object
      Returns:
      ctr object

    • getParent

      public IRunBody getParent()
      Get the currently referenced paragraph/SDT object
      Returns:
      current parent

    • getParagraph

      @Deprecated public XWPFParagraph getParagraph()
      Deprecated.
      use getParent() instead
      Get the currently referenced paragraph, or null if a SDT object

    • getDocument

      public XWPFDocument getDocument()
      Returns:
      The XWPFDocument instance, this run belongs to, or null if parent structure (paragraph > document) is not properly set.

    • getLang

      public String getLang()
      Get the language tag associated with this run, if any.
      Returns:
      the language tag associated with this run, if any

    • setLang

      public void setLang(String lang)
      Set the language tag associated with this run.
      Parameters:
      lang - the language tag associated with this run
      Since:
      4.1.0

    • isBold

      public boolean isBold()
      Whether the bold property shall be applied to all non-complex script characters in the contents of this run when displayed in a document
      Specified by:
      isBold in interface CharacterRun
      Returns:
      true if the bold property is applied

    • setBold

      public void setBold(boolean value)
      Whether the bold property shall be applied to all non-complex script characters in the contents of this run when displayed in a document.

      This formatting property is a toggle property, which specifies that its behavior differs between its use within a style definition and its use as direct formatting. When used as part of a style definition, setting this property shall toggle the current state of that property as specified up to this point in the hierarchy (i.e. applied to not applied, and vice versa). Setting it to false (or an equivalent) shall result in the current setting remaining unchanged. However, when used as direct formatting, setting this property to true or false shall set the absolute state of the resulting property.

      If this element is not present, the default value is to leave the formatting applied at previous level in the style hierarchy. If this element is never applied in the style hierarchy, then bold shall not be applied to non-complex script characters.

      Specified by:
      setBold in interface CharacterRun
      Parameters:
      value - true if the bold property is applied to this run

    • getColor

      public String getColor()
      Get text color. The returned value is a string in the hex form "RRGGBB". This can be null.

    • setColor

      public void setColor(String rgbStr)
      Set text color.
      Parameters:
      rgbStr - - the desired color, in the hex form "RRGGBB".

    • getText

      public String getText(int pos)
      Return the string content of this text run
      Returns:
      the text of this text run or null if not set

    • getPictureText

      public String getPictureText()
      Returns text embedded in pictures

    • setText

      public void setText(String value)
      Sets the text of this text run
      Parameters:
      value - the literal text which shall be displayed in the document

    • setText

      public void setText(String value, int pos)
      Sets the text of this text run in the
      Parameters:
      value - the literal text which shall be displayed in the document
      pos - - position in the text array (NB: 0 based)

    • isItalic

      public boolean isItalic()
      Whether the italic property should be applied to all non-complex script characters in the contents of this run when displayed in a document.
      Specified by:
      isItalic in interface CharacterRun
      Returns:
      true if the italic property is applied

    • setItalic

      public void setItalic(boolean value)
      Whether the bold property shall be applied to all non-complex script characters in the contents of this run when displayed in a document

      This formatting property is a toggle property, which specifies that its behavior differs between its use within a style definition and its use as direct formatting. When used as part of a style definition, setting this property shall toggle the current state of that property as specified up to this point in the hierarchy (i.e. applied to not applied, and vice versa). Setting it to false (or an equivalent) shall result in the current setting remaining unchanged. However, when used as direct formatting, setting this property to true or false shall set the absolute state of the resulting property.

      If this element is not present, the default value is to leave the formatting applied at previous level in the style hierarchy. If this element is never applied in the style hierarchy, then bold shall not be applied to non-complex script characters.

      Specified by:
      setItalic in interface CharacterRun
      Parameters:
      value - true if the italic property is applied to this run

    • getUnderline

      public UnderlinePatterns getUnderline()
      Get the underline setting for the run.
      Returns:
      the Underline pattern applied to this run
      See Also:

    • setUnderline

      public void setUnderline(UnderlinePatterns value)
      Specifies that the contents of this run should be displayed along with an underline appearing directly below the character height.

      If this element is not present, the default value is to leave the formatting applied at previous level in the style hierarchy. If this element is never applied in the style hierarchy, then an underline shall not be applied to the contents of this run.

      Parameters:
      value - - underline type
      See Also:

    • setUnderlineColor

      public void setUnderlineColor(String color)
      Set the underline color for the run's underline, if any.
      Parameters:
      color - An RGB color value (e.g, "a0C6F3") or "auto".
      Since:
      4.0.0

    • setUnderlineThemeColor

      public void setUnderlineThemeColor(String themeColor)
      Set the underline theme color for the run's underline, if any.
      Parameters:
      themeColor - A theme color name (see STThemeColor.Enum).
      Since:
      4.0.0

    • getUnderlineThemeColor

      public STThemeColor.Enum getUnderlineThemeColor()
      Get the underline theme color for the run's underline, if any.
      Returns:
      The STThemeColor.Enum.
      Since:
      4.0.0

    • getUnderlineColor

      public String getUnderlineColor()
      Get the underline color for the run's underline, if any.
      Returns:
      The RGB color value as as a string of hexadecimal digits (e.g., "A0B2F1") or "auto".
      Since:
      4.0.0

    • isStrikeThrough

      public boolean isStrikeThrough()
      Specifies that the contents of this run shall be displayed with a single horizontal line through the center of the line.
      Specified by:
      isStrikeThrough in interface CharacterRun
      Returns:
      true if the strike property is applied

    • setStrikeThrough

      public void setStrikeThrough(boolean value)
      Specifies that the contents of this run shall be displayed with a single horizontal line through the center of the line.

      This formatting property is a toggle property, which specifies that its behaviour differs between its use within a style definition and its use as direct formatting. When used as part of a style definition, setting this property shall toggle the current state of that property as specified up to this point in the hierarchy (i.e. applied to not applied, and vice versa). Setting it to false (or an equivalent) shall result in the current setting remaining unchanged. However, when used as direct formatting, setting this property to true or false shall set the absolute state of the resulting property.

      If this element is not present, the default value is to leave the formatting applied at previous level in the style hierarchy. If this element is never applied in the style hierarchy, then strikethrough shall not be applied to the contents of this run.

      Specified by:
      setStrikeThrough in interface CharacterRun
      Parameters:
      value - true if the strike property is applied to this run

    • isStrike

      @Deprecated public boolean isStrike()
      Deprecated.

    • setStrike

      @Deprecated public void setStrike(boolean value)
      Deprecated.

    • isDoubleStrikeThrough

      public boolean isDoubleStrikeThrough()
      Specifies that the contents of this run shall be displayed with a double horizontal line through the center of the line.
      Specified by:
      isDoubleStrikeThrough in interface CharacterRun
      Returns:
      true if the double strike property is applied

    • setDoubleStrikethrough

      public void setDoubleStrikethrough(boolean value)
      Specifies that the contents of this run shall be displayed with a double horizontal line through the center of the line.
      Specified by:
      setDoubleStrikethrough in interface CharacterRun
      See Also:

    • isSmallCaps

      public boolean isSmallCaps()
      Specified by:
      isSmallCaps in interface CharacterRun

    • setSmallCaps

      public void setSmallCaps(boolean value)
      Specified by:
      setSmallCaps in interface CharacterRun

    • isCapitalized

      public boolean isCapitalized()
      Specified by:
      isCapitalized in interface CharacterRun

    • setCapitalized

      public void setCapitalized(boolean value)
      Specified by:
      setCapitalized in interface CharacterRun

    • isShadowed

      public boolean isShadowed()
      Specified by:
      isShadowed in interface CharacterRun

    • setShadow

      public void setShadow(boolean value)
      Specified by:
      setShadow in interface CharacterRun

    • isImprinted

      public boolean isImprinted()
      Specified by:
      isImprinted in interface CharacterRun

    • setImprinted

      public void setImprinted(boolean value)
      Specified by:
      setImprinted in interface CharacterRun

    • isEmbossed

      public boolean isEmbossed()
      Specified by:
      isEmbossed in interface CharacterRun

    • setEmbossed

      public void setEmbossed(boolean value)
      Specified by:
      setEmbossed in interface CharacterRun

    • setSubscript

      public void setSubscript(VerticalAlign valign)
      Specifies the alignment which shall be applied to the contents of this run in relation to the default appearance of the run's text. This allows the text to be repositioned as subscript or superscript without altering the font size of the run properties.

      If this element is not present, the default value is to leave the formatting applied at previous level in the style hierarchy. If this element is never applied in the style hierarchy, then the text shall not be subscript or superscript relative to the default baseline location for the contents of this run.

      Parameters:
      valign - Type of vertical align to apply
      See Also:

    • getKerning

      public int getKerning()
      Specified by:
      getKerning in interface CharacterRun

    • setKerning

      public void setKerning(int kern)
      Specified by:
      setKerning in interface CharacterRun

    • isHighlighted

      public boolean isHighlighted()
      Specified by:
      isHighlighted in interface CharacterRun

    • getCharacterSpacing

      public int getCharacterSpacing()
      Specified by:
      getCharacterSpacing in interface CharacterRun

    • setCharacterSpacing

      public void setCharacterSpacing(int twips)
      Specified by:
      setCharacterSpacing in interface CharacterRun

    • getFontFamily

      public String getFontFamily()
      Gets the fonts which shall be used to display the text contents of this run. Specifies a font which shall be used to format all characters in the ASCII range (0 - 127) within the parent run
      Returns:
      a string representing the font family

    • setFontFamily

      public void setFontFamily(String fontFamily)
      Specifies the fonts which shall be used to display the text contents of this run. Specifies a font which shall be used to format all characters in the ASCII range (0 - 127) within the parent run.

      Also sets the other font ranges, if they haven't been set before

      Parameters:
      fontFamily - The font family to apply
      See Also:

    • getFontName

      public String getFontName()
      Alias for getFontFamily()
      Specified by:
      getFontName in interface CharacterRun
      Returns:
      a string representing the font

    • getFontFamily

      public String getFontFamily(XWPFRun.FontCharRange fcr)
      Gets the font family for the specified font char range. If fcr is null, the font char range "ascii" is used
      Parameters:
      fcr - the font char range, defaults to "ansi"
      Returns:
      a string representing the font famil

    • setFontFamily

      public void setFontFamily(String fontFamily, XWPFRun.FontCharRange fcr)
      Specifies the fonts which shall be used to display the text contents of this run. The default handling for fcr == null is to overwrite the ascii font char range with the given font family and also set all not specified font ranges
      Parameters:
      fontFamily - The font family to apply
      fcr - FontCharRange or null for default handling

    • getFontSize

      @Deprecated @Removal(version="6.0.0") public int getFontSize()
      Deprecated.
      use getFontSizeAsDouble()
      Specifies the font size which shall be applied to all non complex script characters in the contents of this run when displayed.
      Specified by:
      getFontSize in interface CharacterRun
      Returns:
      value representing the font size (non-integer size will be rounded with half rounding up, -1 is returned if size not set)

    • getFontSizeAsDouble

      public Double getFontSizeAsDouble()
      Specifies the font size which shall be applied to all non complex script characters in the contents of this run when displayed.
      Specified by:
      getFontSizeAsDouble in interface CharacterRun
      Returns:
      value representing the font size (can be null if size not set)
      Since:
      POI 5.0.0

    • setFontSize

      public void setFontSize(int size)
      Specifies the font size which shall be applied to all non complex script characters in the contents of this run when displayed.

      If this element is not present, the default value is to leave the value applied at previous level in the style hierarchy. If this element is never applied in the style hierarchy, then any appropriate font size may be used for non complex script characters.

      Specified by:
      setFontSize in interface CharacterRun
      Parameters:
      size - The font size as number of point measurements.
      See Also:

    • setFontSize

      public void setFontSize(double size)
      Specifies the font size which shall be applied to all non complex script characters in the contents of this run when displayed.

      If this element is not present, the default value is to leave the value applied at previous level in the style hierarchy. If this element is never applied in the style hierarchy, then any appropriate font size may be used for non complex script characters.

      Specified by:
      setFontSize in interface CharacterRun
      Parameters:
      size - The font size as number of point measurements.
      Since:
      POI 5.0.0
      See Also:

    • getTextPosition

      public int getTextPosition()
      This element specifies the amount by which text shall be raised or lowered for this run in relation to the default baseline of the surrounding non-positioned text. This allows the text to be repositioned without altering the font size of the contents.
      Returns:
      a big integer representing the amount of text shall be "moved"

    • setTextPosition

      public void setTextPosition(int val)
      This element specifies the amount by which text shall be raised or lowered for this run in relation to the default baseline of the surrounding non-positioned text. This allows the text to be repositioned without altering the font size of the contents.

      If the val attribute is positive, then the parent run shall be raised above the baseline of the surrounding text by the specified number of half-points. If the val attribute is negative, then the parent run shall be lowered below the baseline of the surrounding text by the specified number of half-points.

      If this element is not present, the default value is to leave the formatting applied at previous level in the style hierarchy. If this element is never applied in the style hierarchy, then the text shall not be raised or lowered relative to the default baseline location for the contents of this run.

      Parameters:
      val - Positive values will raise the baseline of the text, negative values will lower it.

    • removeBreak

      public void removeBreak()
      Not yet implemented.

    • addBreak

      public void addBreak()
      Specifies that a break shall be placed at the current location in the run content. A break is a special character which is used to override the normal line breaking that would be performed based on the normal layout of the document's contents.
      See Also:

    • addBreak

      public void addBreak(BreakType type)
      Specifies that a break shall be placed at the current location in the run content. A break is a special character which is used to override the normal line breaking that would be performed based on the normal layout of the document's contents.

      The behavior of this break character (the location where text shall be restarted after this break) shall be determined by its type values.

      See Also:

    • addBreak

      public void addBreak(BreakClear clear)
      Specifies that a break shall be placed at the current location in the run content. A break is a special character which is used to override the normal line breaking that would be performed based on the normal layout of the document's contents.

      The behavior of this break character (the location where text shall be restarted after this break) shall be determined by its type (in this case is BreakType.TEXT_WRAPPING as default) and clear attribute values.

      See Also:

    • addTab

      public void addTab()
      Specifies that a tab shall be placed at the current location in the run content.

    • removeTab

      public void removeTab()

    • addCarriageReturn

      public void addCarriageReturn()
      Specifies that a carriage return shall be placed at the current location in the run content. A carriage return is used to end the current line of text in Wordprocess. The behavior of a carriage return in run content shall be identical to a break character with null type and clear attributes, which shall end the current line and find the next available line on which to continue. The carriage return character forced the following text to be restarted on the next available line in the document.

    • removeCarriageReturn

      public void removeCarriageReturn()

    • addPicture

      public XWPFPicture addPicture(InputStream pictureData, int pictureType, String filename, int width, int height) throws InvalidFormatException, IOException
      Adds a picture to the run. This method handles attaching the picture data to the overall file.
      Parameters:
      pictureData - The raw picture data
      pictureType - The type of the picture, eg Document.PICTURE_TYPE_JPEG
      width - width in EMUs. To convert to / from points use Units
      height - height in EMUs. To convert to / from points use Units
      Throws:
      InvalidFormatException - If the format of the picture is not known.
      IOException - If reading the picture-data from the stream fails.
      See Also:

    • addPicture

      public XWPFPicture addPicture(InputStream pictureData, PictureType pictureType, String filename, int width, int height) throws InvalidFormatException, IOException
      Adds a picture to the run. This method handles attaching the picture data to the overall file.
      Parameters:
      pictureData - The raw picture data
      pictureType - The PictureType of the picture
      width - width in EMUs. To convert to / from points use Units
      height - height in EMUs. To convert to / from points use Units
      Throws:
      InvalidFormatException - If the format of the picture is not known.
      IOException - If reading the picture-data from the stream fails.
      Since:
      POI 5.2.3

    • addChart

      @Internal public CTInline addChart(String chartRelId) throws InvalidFormatException, IOException
      this method add chart template into document
      Parameters:
      chartRelId - relation id of chart in document relation file
      Throws:
      InvalidFormatException
      IOException
      Since:
      POI 4.0.0

    • getEmbeddedPictures

      public List<XWPFPicture> getEmbeddedPictures()
      Returns the embedded pictures of the run. These are pictures which reference an external, embedded picture image such as a .png or .jpg

    • setStyle

      public void setStyle(String styleId)
      Set the style ID for the run.
      Parameters:
      styleId - ID (not name) of the style to set for the run, e.g. "BoldItalic" (not "Bold Italic").
      Since:
      POI 4.1.1

    • getStyle

      public String getStyle()
      Return this run's style ID. If this run has no style (no run properties or properties without a style), an empty string is returned.
      Since:
      4.1.1

    • toString

      public String toString()
      Returns the string version of the text and the phonetic string
      Overrides:
      toString in class Object

    • text

      public String text()
      Returns the string version of the text, with tabs and carriage returns in place of their xml equivalents.
      Specified by:
      text in interface CharacterRun
      Returns:
      The text of the run, including any tabs/spaces/etc

    • getPhonetic

      public String getPhonetic()
      Returns:
      the phonetic (ruby) string associated with this run or an empty String if none exists

    • setTextScale

      public void setTextScale(int percentage)
      Set the text expand/collapse scale value.
      Parameters:
      percentage - The percentage to expand or compress the text
      Since:
      4.0.0

    • getTextScale

      public int getTextScale()
      Gets the current text scale value.
      Returns:
      Value is an integer percentage
      Since:
      4.0.0

    • setTextHighlightColor

      public void setTextHighlightColor(String colorName)
      Set the highlight color for the run. Silently does nothing of colorName is not a recognized value.
      Parameters:
      colorName - The name of the color as defined in the ST_HighlightColor simple type (STHighlightColor)
      Since:
      4.0.0

    • getTextHightlightColor

      @Deprecated @Removal(version="7.0.0") public STHighlightColor.Enum getTextHightlightColor()
      Deprecated.
      use getTextHighlightColor() instead
      Gets the highlight color for the run
      Returns:
      STHighlightColor for the run.
      Since:
      4.0.0

    • getTextHighlightColor

      public STHighlightColor.Enum getTextHighlightColor()
      Gets the highlight color for the run
      Returns:
      STHighlightColor for the run. The default is NONE;
      Since:
      5.2.3

    • isVanish

      public boolean isVanish()
      Get the vanish (hidden text) value
      Returns:
      True if the run is hidden text.
      Since:
      4.0.0

    • setVanish

      public void setVanish(boolean value)
      The vanish (hidden text) property for the run.
      Parameters:
      value - Set to true to make the run hidden text.
      Since:
      4.0.0

    • getVerticalAlignment

      public org.openxmlformats.schemas.officeDocument.x2006.sharedTypes.STVerticalAlignRun.Enum getVerticalAlignment()
      Get the vertical alignment value
      Returns:
      STVerticalAlignRun.Enum value (see 22.9.2.17 ST_VerticalAlignRun (Vertical Positioning Location)). The default is BASELINE.
      Since:
      4.0.0

    • setVerticalAlignment

      public void setVerticalAlignment(String verticalAlignment)
      Set the vertical alignment of the run.
      Parameters:
      verticalAlignment - Vertical alignment value, one of "baseline", "superscript", or "subscript".
      Since:
      4.0.0

    • getEmphasisMark

      public STEm.Enum getEmphasisMark()
      Get the emphasis mark value for the run.
      Returns:
      STEm.Enum emphasis mark type enumeration. See 17.18.24 ST_Em (Emphasis Mark Type). The default is NONE.
      Since:
      4.0.0

    • setEmphasisMark

      public void setEmphasisMark(String markType)
      Set the emphasis mark for the run. The emphasis mark goes above or below the run text.
      Parameters:
      markType - Emphasis mark type name, e.g., "dot" or "none". See 17.18.24 ST_Em (Emphasis Mark Type)
      Since:
      4.0.0