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
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
     
  • Constructor Summary

    Constructors
    Constructor
    Description
    XWPFRun(org.openxmlformats.schemas.wordprocessingml.x2006.main.CTR r, IRunBody p)
     
    XWPFRun(org.openxmlformats.schemas.wordprocessingml.x2006.main.CTR r, XWPFParagraph p)
    Deprecated.
  • Method Summary

    Modifier and Type
    Method
    Description
    void
    Specifies that a break shall be placed at the current location in the run content.
    void
    Specifies that a break shall be placed at the current location in the run content.
    void
    Specifies that a break shall be placed at the current location in the run content.
    void
    Specifies that a carriage return shall be placed at the current location in the run content.
    org.openxmlformats.schemas.drawingml.x2006.wordprocessingDrawing.CTInline
    addChart(String chartRelId)
    this method add chart template into document
    addPicture(InputStream pictureData, int pictureType, String filename, int width, int height)
    Adds a picture to the run.
    void
    Specifies that a tab shall be placed at the current location in the run content.
    int
     
    Get text color.
    org.openxmlformats.schemas.wordprocessingml.x2006.main.CTR
    Get the currently used CTR object
     
    Returns the embedded pictures of the run.
    org.openxmlformats.schemas.wordprocessingml.x2006.main.STEm.Enum
    Get the emphasis mark value for the run.
    Gets the fonts which shall be used to display the text contents of this run.
    Gets the font family for the specified font char range.
    Alias for getFontFamily()
    int
    Specifies the font size which shall be applied to all non complex script characters in the contents of this run when displayed.
    int
     
    Get the language tag associated with this run, if any.
    Deprecated.
    use getParent() instead
    Get the currently referenced paragraph/SDT object
     
    Returns text embedded in pictures
    Deprecated.
    use
    invalid reference
    XWPFRun.getVerticalAlignment
    getText(int pos)
    Return the string content of this text run
    org.openxmlformats.schemas.wordprocessingml.x2006.main.STHighlightColor.Enum
    Gets the highlight color for the run
    int
    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.
    int
    Gets the current text scale value.
    Get the underline setting for the run.
    Get the underline color for the run's underline, if any.
    org.openxmlformats.schemas.wordprocessingml.x2006.main.STThemeColor.Enum
    Get the underline theme color for the run's underline, if any.
    org.openxmlformats.schemas.wordprocessingml.x2006.main.STVerticalAlignRun.Enum
    Get the vertical alignment value
    boolean
    Whether the bold property shall be applied to all non-complex script characters in the contents of this run when displayed in a document
    boolean
     
    boolean
    Specifies that the contents of this run shall be displayed with a double horizontal line through the center of the line.
    boolean
     
    boolean
     
    boolean
     
    boolean
    Whether the italic property should be applied to all non-complex script characters in the contents of this run when displayed in a document.
    boolean
     
    boolean
     
    boolean
    Deprecated.
    boolean
    Specifies that the contents of this run shall be displayed with a single horizontal line through the center of the line.
    boolean
    Get the vanish (hidden text) value
    void
     
    void
     
    void
     
    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.
    void
    setCapitalized(boolean value)
     
    void
     
    void
    setColor(String rgbStr)
    Set text color.
    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.
    void
    setEmbossed(boolean value)
     
    void
    Set the emphasis mark for the run.
    void
    setFontFamily(String fontFamily)
    Specifies the fonts which shall be used to display the text contents of this run.
    void
    Specifies the fonts which shall be used to display the text contents of this run.
    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.
    void
    setImprinted(boolean value)
     
    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
    void
    setKerning(int kern)
     
    void
    setShadow(boolean value)
     
    void
    setSmallCaps(boolean value)
     
    void
    setStrike(boolean value)
    Deprecated.
    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.
    void
    setStyle(String styleId)
    Set the style ID for the run.
    void
    Specifies the alignment which shall be applied to the contents of this run in relation to the default appearance of the run's text.
    void
    setText(String value)
    Sets the text of this text run
    void
    setText(String value, int pos)
    Sets the text of this text run in the
    void
    Set the highlight color for the run.
    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.
    void
    setTextScale(int percentage)
    Set the text expand/collapse scale value.
    void
    Specifies that the contents of this run should be displayed along with an underline appearing directly below the character height.
    void
    Set the underline color for the run's underline, if any.
    void
    Set the underline theme color for the run's underline, if any.
    void
    setVanish(boolean value)
    The vanish (hidden text) property for the run.
    void
    setVerticalAlignment(String verticalAlignment)
    Set the vertical alignment of the run.
    Returns the string version of the text, with tabs and carriage returns in place of their xml equivalents.
    Returns the string version of the text and the phonetic string

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
  • Constructor Details

    • XWPFRun

      public XWPFRun(org.openxmlformats.schemas.wordprocessingml.x2006.main.CTR r, IRunBody p)
      Parameters:
      r - the CTR bean which holds the run attributes
      p - the parent paragraph
    • XWPFRun

      @Deprecated public XWPFRun(org.openxmlformats.schemas.wordprocessingml.x2006.main.CTR r, XWPFParagraph p)
      Deprecated.
  • Method Details

    • getCTR

      @Internal public org.openxmlformats.schemas.wordprocessingml.x2006.main.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
    • 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".
    • 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
    • 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
    • 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 org.openxmlformats.schemas.wordprocessingml.x2006.main.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
    • getSubscript

      @Removal(version="4.2") public VerticalAlign getSubscript()
      Deprecated.
      use
      invalid reference
      XWPFRun.getVerticalAlignment
      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.
      Returns:
      VerticalAlign
    • 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

      public int getFontSize()
      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
    • 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.
    • 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()
    • 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:
    • addChart

      @Internal public org.openxmlformats.schemas.drawingml.x2006.wordprocessingDrawing.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").
    • 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 (
      invalid reference
      STHightlightColor
      )
      Since:
      4.0.0
    • getTextHightlightColor

      public org.openxmlformats.schemas.wordprocessingml.x2006.main.STHighlightColor.Enum getTextHightlightColor()
      Gets the highlight color for the run
      Returns:
      STHighlightColor for the run.
      Since:
      4.0.0
    • 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.wordprocessingml.x2006.main.STVerticalAlignRun.Enum getVerticalAlignment()
      Get the vertical alignment value
      Returns:
      STVerticalAlignRun.Enum value (see 22.9.2.17 ST_VerticalAlignRun (Vertical Positioning Location))
      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 org.openxmlformats.schemas.wordprocessingml.x2006.main.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).
      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