Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 java.lang.Object
implements ISDTContents, IRunElement, CharacterRun

XWPFRun object defines a region of text with a common set of properties

Nested Class Summary
`static class` | `XWPFRun.FontCharRange`

Constructor Summary
`XWPFRun(org.openxmlformats.schemas.wordprocessingml.x2006.main.CTR r, IRunBody p)`
`XWPFRun(org.openxmlformats.schemas.wordprocessingml.x2006.main.CTR r, XWPFParagraph p)` Deprecated. Use `XWPFRun(CTR, IRunBody)`

Method Summary
`void` | `addBreak()` Specifies that a break shall be placed at the current location in the run content.
`void` | `addBreak(BreakClear clear)` Specifies that a break shall be placed at the current location in the run content.
`void` | `addBreak(BreakType type)` Specifies that a break shall be placed at the current location in the run content.
`void` | `addCarriageReturn()` Specifies that a carriage return shall be placed at the current location in the run content.
`XWPFPicture` | `addPicture(java.io.InputStream pictureData, int pictureType, java.lang.String filename, int width, int height)` Adds a picture to the run.
`void` | `addTab()` Specifies that a tab shall be placed at the current location in the run content.
`int` | `getCharacterSpacing()`
`java.lang.String` | `getColor()` Get text color.
`org.openxmlformats.schemas.wordprocessingml.x2006.main.CTR` | `getCTR()` Get the currently used CTR object
`XWPFDocument` | `getDocument()`
`java.util.List<XWPFPicture>` | `getEmbeddedPictures()` Returns the embedded pictures of the run.
`java.lang.String` | `getFontFamily()` Gets the fonts which shall be used to display the text contents of this run.
`java.lang.String` | `getFontFamily(XWPFRun.FontCharRange fcr)` Gets the font family for the specified font char range.
`java.lang.String` | `getFontName()` Alias for `getFontFamily()`
`int` | `getFontSize()` Specifies the font size which shall be applied to all non complex script characters in the contents of this run when displayed.
`int` | `getKerning()`
`XWPFParagraph` | `getParagraph()` Deprecated. use `getParent()` instead
`IRunBody` | `getParent()` Get the currently referenced paragraph/SDT object
`java.lang.String` | `getPhonetic()`
`java.lang.String` | `getPictureText()` Returns text embedded in pictures
`VerticalAlign` | `getSubscript()` Specifies the alignment which shall be applied to the contents of this run in relation to the default appearance of the run's text.
`java.lang.String` | `getText(int pos)` Return the string content of this text run
`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.
`UnderlinePatterns` | `getUnderline()` Specifies that the contents of this run should be displayed along with an underline appearing directly below the character heigh
`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
`boolean` | `isCapitalized()`
`boolean` | `isDoubleStrikeThrough()` Specifies that the contents of this run shall be displayed with a double horizontal line through the center of the line.
`boolean` | `isEmbossed()`
`boolean` | `isHighlighted()`
`boolean` | `isImprinted()`
`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.
`boolean` | `isShadowed()`
`boolean` | `isSmallCaps()`
`boolean` | `isStrike()` Deprecated.
`boolean` | `isStrikeThrough()` Specifies that the contents of this run shall be displayed with a single horizontal line through the center of the line.
`void` | `removeBreak()`
`void` | `removeCarriageReturn()`
`void` | `removeTab()`
`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` | `setCharacterSpacing(int twips)`
`void` | `setColor(java.lang.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` | `setFontFamily(java.lang.String fontFamily)` Specifies the fonts which shall be used to display the text contents of this run.
`void` | `setFontFamily(java.lang.String fontFamily, XWPFRun.FontCharRange fcr)` 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` | `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.
`void` | `setText(java.lang.String value)` Sets the text of this text run
`void` | `setText(java.lang.String value, int pos)` Sets the text of this text run in the
`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` | `setUnderline(UnderlinePatterns value)` Specifies that the contents of this run should be displayed along with an underline appearing directly below the character heigh
`java.lang.String` | `text()` Returns the string version of the text, with tabs and carriage returns in place of their xml equivalents.
`java.lang.String` | `toString()` 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 Detail

### 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

    public XWPFRun(org.openxmlformats.schemas.wordprocessingml.x2006.main.CTR r,
                   XWPFParagraph p)

  Deprecated. Use `XWPFRun(CTR, IRunBody)`

Method Detail

### 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

    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.

### 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 java.lang.String getColor()

  Get text color. The returned value is a string in the hex form "RRGGBB".

### setColor

    public void setColor(java.lang.String rgbStr)

  Set text color.

  Parameters:
    `rgbStr` - - the desired color, in the hex form "RRGGBB".

### getText

    public java.lang.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 java.lang.String getPictureText()

  Returns text embedded in pictures

### setText

    public void setText(java.lang.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(java.lang.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()

  Specifies that the contents of this run should be displayed along with an underline appearing directly below the character heigh

  Returns:
    the Underline pattern applyed to this run
  See Also:
    `UnderlinePatterns`

### 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 heigh

  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:
    `: all possible patterns that could be applied`

### 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:
    `for the rules about this`

### 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

    public VerticalAlign getSubscript()

  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
  See Also:
    `all possible value that could be applyed to this run`

### 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` -
  See Also:
    `VerticalAlign`

### 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 java.lang.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(java.lang.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` -
  See Also:
    `XWPFRun.FontCharRange`

### getFontName

    public java.lang.String getFontName()

  Alias for `getFontFamily()`

  Specified by:
    `getFontName` in interface `CharacterRun`
  Returns:
    a string representing the font

### getFontFamily

    public java.lang.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(java.lang.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` -
    `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` -

### 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` -

### 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:
    `addCarriageReturn()`

### 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:
    `BreakType`

### 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:
    `BreakClear`

### 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(java.io.InputStream pictureData,
                                  int pictureType,
                                  java.lang.String filename,
                                  int width,
                                  int height)
                           throws InvalidFormatException,
                                  java.io.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`
    `java.io.IOException`
  See Also:
    `Document.PICTURE_TYPE_EMF`, `Document.PICTURE_TYPE_WMF`, `Document.PICTURE_TYPE_PICT`, `Document.PICTURE_TYPE_JPEG`, `Document.PICTURE_TYPE_PNG`, `Document.PICTURE_TYPE_DIB`

### getEmbeddedPictures

    public java.util.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

### toString

    public java.lang.String toString()

  Returns the string version of the text and the phonetic string

  Overrides:
    `toString` in class `java.lang.Object`

### text

    public java.lang.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 java.lang.String getPhonetic()

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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