org.apache.poi.xwpf.usermodel

Class XWPFRun

java.lang.Object

org.apache.poi.xwpf.usermodel.XWPFRun

All Implemented Interfaces:

IRunElement, ISDTContents

Direct Known Subclasses:

XWPFHyperlinkRun

public class XWPFRun
extends java.lang.Object
implements ISDTContents, IRunElement

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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	XWPFRun.FontCharRange

Constructor Summary

Constructors

Constructor and Description
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

Modifier and Type	Method and Description
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	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	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 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.
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 If this element is not present, the default value is to leave the formatting applied at previous level in the style hierarchy.
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

Methods inherited from class java.lang.Object

equals, 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

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.

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.

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.

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.

Returns:

true if the strike property is applied

isStrike

@Deprecated
public boolean isStrike()

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.

Returns:

true if the double 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.

Parameters:

value - true if the strike property is applied to this run

setStrike

@Deprecated
public void setStrike(boolean value)

Deprecated.

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.

See Also:

for the rules about this

isSmallCaps

public boolean isSmallCaps()

setSmallCaps

public void setSmallCaps(boolean value)

isCapitalized

public boolean isCapitalized()

setCapitalized

public void setCapitalized(boolean value)

isShadowed

public boolean isShadowed()

setShadow

public void setShadow(boolean value)

isImprinted

public boolean isImprinted()

setImprinted

public void setImprinted(boolean value)

isEmbossed

public boolean isEmbossed()

setEmbossed

public void setEmbossed(boolean value)

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()

setKerning

public void setKerning(int kern)

getCharacterSpacing

public int getCharacterSpacing()

setCharacterSpacing

public void setCharacterSpacing(int twips)

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

getFontName

public java.lang.String getFontName()

Alias for getFontFamily()

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)

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

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.

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.

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

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.