org.apache.poi.hwpf.usermodel
Class Range

java.lang.Object
  org.apache.poi.hwpf.usermodel.Range

Direct Known Subclasses:

CharacterRun, DocumentPosition, Paragraph, Section, Table, TableCell

public class Range
extends java.lang.Object

This class is the central class of the HWPF object model. All properties that apply to a range of characters in a Word document extend this class. It is possible to insert text and/or properties at the beginning or end of a range. Ranges are only valid if there hasn't been an insert in a prior Range since the Range's creation. Once an element (text, paragraph, etc.) has been inserted into a Range, subsequent Ranges become unstable.

Author:

Ryan Ackley

Field Summary

protected java.util.List<CHPX>	_characters All CharacterRuns that belong to the document this Range belongs to.
protected int	_charEnd The end index in the characterRuns list for this Range.
protected boolean	_charRangeFound Have we loaded the characterRun indexes yet.
protected int	_charStart The start index in the characterRuns list for this Range
protected HWPFDocumentCore	_doc The document this range blongs to.
protected int	_end The ending character offset of this range.
protected java.util.List<PAPX>	_paragraphs All paragraphs that belong to the document this Range belongs to.
protected int	_parEnd The end index in the paragraphs list for this Range.
protected boolean	_parRangeFound Have we loaded the paragraph indexes yet.
protected int	_parStart The start index in the paragraphs list for this Range
protected int	_sectionEnd The end index in the sections list for this Range.
protected java.util.List<SEPX>	_sections All sections that belong to the document this Range belongs to.
protected int	_sectionStart The start index in the sections list for this Range
protected int	_start The starting character offset of this range.
protected java.util.List<TextPiece>	_text All text pieces that belong to the document this Range belongs to.
protected int	_textEnd The end index in the text list for this Range.
protected boolean	_textRangeFound Have we loaded the Text indexes yet
protected int	_textStart The start index in the text list for this Range.
static int	TYPE_CHARACTER
static int	TYPE_LISTENTRY
static int	TYPE_PARAGRAPH
static int	TYPE_SECTION
static int	TYPE_TABLE
static int	TYPE_TEXT
static int	TYPE_UNDEFINED

Constructor Summary

	Range(int start, int end, HWPFDocumentCore doc) Used to construct a Range from a document.
protected	Range(int startIdx, int endIdx, int idxType, Range parent) Constructor used to build a Range from indexes in one of its internal lists.
protected	Range(int start, int end, Range parent) Used to create Ranges that are children of other Ranges.

Method Summary

protected void	adjustFIB(int adjustment) Adjust the value of the various FIB character count fields, eg FIB.CCPText after an insert or a delete...
void	delete()
CharacterRun	getCharacterRun(int index) Gets the character run at index.
protected HWPFDocumentCore	getDocument()
int	getEndOffset()
Paragraph	getParagraph(int index) Gets the paragraph at index.
Section	getSection(int index) Gets the section at index.
int	getStartOffset()
Table	getTable(Paragraph paragraph) Gets the table that starts with paragraph.
protected void	initAll() loads all of the list indexes.
Paragraph	insertAfter(ParagraphProperties props, int styleIndex) Inserts and empty paragraph into the end of this range.
ListEntry	insertAfter(ParagraphProperties props, int listID, int level, int styleIndex) Inserts a list into the beginning of this range.
protected Paragraph	insertAfter(ParagraphProperties props, int styleIndex, java.lang.String text) Inserts a paragraph into the end of this range.
CharacterRun	insertAfter(java.lang.String text) Inserts text onto the end of this range
CharacterRun	insertAfter(java.lang.String text, CharacterProperties props) Inserts text onto the end of this range and gives that text the CharacterProperties specified in props.
Paragraph	insertBefore(ParagraphProperties props, int styleIndex) Inserts and empty paragraph into the front of this range.
ListEntry	insertBefore(ParagraphProperties props, int listID, int level, int styleIndex) Inserts a list into the beginning of this range.
protected Paragraph	insertBefore(ParagraphProperties props, int styleIndex, java.lang.String text) Inserts a paragraph into the front of this range.
CharacterRun	insertBefore(java.lang.String text) Inserts text into the front of this range.
CharacterRun	insertBefore(java.lang.String text, CharacterProperties props) Inserts text into the front of this range and it gives that text the CharacterProperties specified in props.
Table	insertBefore(TableProperties props, int rows) Inserts a simple table into the beginning of this range.
int	numCharacterRuns()
int	numParagraphs() Used to get the number of paragraphs in a range.
int	numSections() Used to get the number of sections in a range.
void	replaceText(java.lang.String pPlaceHolder, java.lang.String pValue) Replace (all instances of) a piece of text with another...
void	replaceText(java.lang.String pPlaceHolder, java.lang.String pValue, int pOffset) Replace (one instance of) a piece of text with another...
static java.lang.String	stripFields(java.lang.String text) Removes any fields (eg macros, page markers etc) from the string.
java.lang.String	text() Gets the text that this Range contains.
int	type() This method is used to determine the type.
boolean	usesUnicode() Does any TextPiece in this Range use unicode?

Methods inherited from class java.lang.Object

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

Field Detail

TYPE_PARAGRAPH

public static final int TYPE_PARAGRAPH

See Also:

Constant Field Values

TYPE_CHARACTER

public static final int TYPE_CHARACTER

See Also:

Constant Field Values

TYPE_SECTION

public static final int TYPE_SECTION

See Also:

Constant Field Values

TYPE_TEXT

public static final int TYPE_TEXT

See Also:

Constant Field Values

TYPE_LISTENTRY

public static final int TYPE_LISTENTRY

See Also:

Constant Field Values

TYPE_TABLE

public static final int TYPE_TABLE

See Also:

Constant Field Values

TYPE_UNDEFINED

public static final int TYPE_UNDEFINED

See Also:

Constant Field Values

_start

protected int _start

The starting character offset of this range.

_end

protected int _end

The ending character offset of this range.

_doc

protected HWPFDocumentCore _doc

The document this range blongs to.

_sections

protected java.util.List<SEPX> _sections

All sections that belong to the document this Range belongs to.

_sectionStart

protected int _sectionStart

The start index in the sections list for this Range

_sectionEnd

protected int _sectionEnd

The end index in the sections list for this Range.

_parRangeFound

protected boolean _parRangeFound

Have we loaded the paragraph indexes yet.

_paragraphs

protected java.util.List<PAPX> _paragraphs

All paragraphs that belong to the document this Range belongs to.

_parStart

protected int _parStart

The start index in the paragraphs list for this Range

_parEnd

protected int _parEnd

The end index in the paragraphs list for this Range.

_charRangeFound

protected boolean _charRangeFound

Have we loaded the characterRun indexes yet.

_characters

protected java.util.List<CHPX> _characters

All CharacterRuns that belong to the document this Range belongs to.

_charStart

protected int _charStart

The start index in the characterRuns list for this Range

_charEnd

protected int _charEnd

The end index in the characterRuns list for this Range.

_textRangeFound

protected boolean _textRangeFound

Have we loaded the Text indexes yet

_text

protected java.util.List<TextPiece> _text

All text pieces that belong to the document this Range belongs to.

_textStart

protected int _textStart

The start index in the text list for this Range.

_textEnd

protected int _textEnd

The end index in the text list for this Range.

Constructor Detail

Range

public Range(int start,
             int end,
             HWPFDocumentCore doc)

Used to construct a Range from a document. This is generally used to create a Range that spans the whole document, or at least one whole part of the document (eg main text, header, comment)

Parameters:

start - Starting character offset of the range.

end - Ending character offset of the range.

doc - The HWPFDocument the range is based on.

Range

protected Range(int start,
                int end,
                Range parent)

Used to create Ranges that are children of other Ranges.

Parameters:

start - Starting character offset of the range.

end - Ending character offset of the range.

parent - The parent this range belongs to.

Range

protected Range(int startIdx,
                int endIdx,
                int idxType,
                Range parent)

Constructor used to build a Range from indexes in one of its internal lists.

Parameters:

startIdx - The starting index in the list.

endIdx - The ending index in the list.

idxType - The list type.

parent - The parent Range this range belongs to.

Method Detail

usesUnicode

public boolean usesUnicode()

Does any TextPiece in this Range use unicode?

Returns:

true if it does and false if it doesn't

text

public java.lang.String text()

Gets the text that this Range contains.

Returns:

The text for this range.

stripFields

public static java.lang.String stripFields(java.lang.String text)

Removes any fields (eg macros, page markers etc) from the string. Normally used to make some text suitable for showing to humans, and the resultant text should not normally be saved back into the document!

numSections

public int numSections()

Used to get the number of sections in a range. If this range is smaller than a section, it will return 1 for its containing section.

Returns:

The number of sections in this range.

numParagraphs

public int numParagraphs()

Used to get the number of paragraphs in a range. If this range is smaller than a paragraph, it will return 1 for its containing paragraph.

Returns:

The number of paragraphs in this range.

numCharacterRuns

public int numCharacterRuns()

Returns:

The number of characterRuns in this range.

insertBefore

public CharacterRun insertBefore(java.lang.String text)

Inserts text into the front of this range.

Parameters:

text - The text to insert

Returns:

The character run that text was inserted into.

insertAfter

public CharacterRun insertAfter(java.lang.String text)

Inserts text onto the end of this range

Parameters:

text - The text to insert

Returns:

The character run the text was inserted into.

insertBefore

public CharacterRun insertBefore(java.lang.String text,
                                 CharacterProperties props)

Inserts text into the front of this range and it gives that text the CharacterProperties specified in props.

Parameters:

text - The text to insert.

props - The CharacterProperties to give the text.

Returns:

A new CharacterRun that has the given text and properties and is n ow a part of the document.

insertAfter

public CharacterRun insertAfter(java.lang.String text,
                                CharacterProperties props)

Inserts text onto the end of this range and gives that text the CharacterProperties specified in props.

Parameters:

text - The text to insert.

props - The CharacterProperties to give the text.

Returns:

A new CharacterRun that has the given text and properties and is n ow a part of the document.

insertBefore

public Paragraph insertBefore(ParagraphProperties props,
                              int styleIndex)

Inserts and empty paragraph into the front of this range.

Parameters:

props - The properties that the new paragraph will have.

styleIndex - The index into the stylesheet for the new paragraph.

Returns:

The newly inserted paragraph.

insertBefore

protected Paragraph insertBefore(ParagraphProperties props,
                                 int styleIndex,
                                 java.lang.String text)

Inserts a paragraph into the front of this range. The paragraph will contain one character run that has the default properties for the paragraph's style. It is necessary for the text to end with the character '\r'

Parameters:

props - The paragraph's properties.

styleIndex - The index of the paragraph's style in the style sheet.

text - The text to insert.

Returns:

A newly inserted paragraph.

insertAfter

public Paragraph insertAfter(ParagraphProperties props,
                             int styleIndex)

Inserts and empty paragraph into the end of this range.

Parameters:

props - The properties that the new paragraph will have.

styleIndex - The index into the stylesheet for the new paragraph.

Returns:

The newly inserted paragraph.

insertAfter

protected Paragraph insertAfter(ParagraphProperties props,
                                int styleIndex,
                                java.lang.String text)

Inserts a paragraph into the end of this range. The paragraph will contain one character run that has the default properties for the paragraph's style. It is necessary for the text to end with the character '\r'

Parameters:

props - The paragraph's properties.

styleIndex - The index of the paragraph's style in the style sheet.

text - The text to insert.

Returns:

A newly inserted paragraph.

delete

public void delete()

insertBefore

public Table insertBefore(TableProperties props,
                          int rows)

Inserts a simple table into the beginning of this range. The number of columns is determined by the TableProperties passed into this function.

Parameters:

props - The table properties for the table.

rows - The number of rows.

Returns:

The empty Table that is now part of the document.

insertBefore

public ListEntry insertBefore(ParagraphProperties props,
                              int listID,
                              int level,
                              int styleIndex)

Inserts a list into the beginning of this range.

Parameters:

props - The properties of the list entry. All list entries are paragraphs.

listID - The id of the list that contains the properties.

level - The indentation level of the list.

styleIndex - The base style's index in the stylesheet.

Returns:

The empty ListEntry that is now part of the document.

insertAfter

public ListEntry insertAfter(ParagraphProperties props,
                             int listID,
                             int level,
                             int styleIndex)

Inserts a list into the beginning of this range.

Parameters:

props - The properties of the list entry. All list entries are paragraphs.

listID - The id of the list that contains the properties.

level - The indentation level of the list.

styleIndex - The base style's index in the stylesheet.

Returns:

The empty ListEntry that is now part of the document.

replaceText

public void replaceText(java.lang.String pPlaceHolder,
                        java.lang.String pValue,
                        int pOffset)

Replace (one instance of) a piece of text with another...

Parameters:

pPlaceHolder - The text to be replaced (e.g., "${organization}")

pValue - The replacement text (e.g., "Apache Software Foundation")

pOffset - The offset or index where the text to be replaced begins (relative to/within this Range)

replaceText

public void replaceText(java.lang.String pPlaceHolder,
                        java.lang.String pValue)

Replace (all instances of) a piece of text with another...

Parameters:

pPlaceHolder - The text to be replaced (e.g., "${organization}")

pValue - The replacement text (e.g., "Apache Software Foundation")

getCharacterRun

public CharacterRun getCharacterRun(int index)

Gets the character run at index. The index is relative to this range.

Parameters:

index - The index of the character run to get.

Returns:

The character run at the specified index in this range.

getSection

public Section getSection(int index)

Gets the section at index. The index is relative to this range.

Parameters:

index - The index of the section to get.

Returns:

The section at the specified index in this range.

getParagraph

public Paragraph getParagraph(int index)

Gets the paragraph at index. The index is relative to this range.

Parameters:

index - The index of the paragraph to get.

Returns:

The paragraph at the specified index in this range.

type

public int type()

This method is used to determine the type. Handy for switch statements compared to the instanceof operator.

Returns:

A TYPE constant.

getTable

public Table getTable(Paragraph paragraph)

Gets the table that starts with paragraph. In a Word file, a table consists of a group of paragraphs with certain flags set.

Parameters:

paragraph - The paragraph that is the first paragraph in the table.

Returns:

The table that starts with paragraph

initAll

protected void initAll()

loads all of the list indexes.

adjustFIB

protected void adjustFIB(int adjustment)

Adjust the value of the various FIB character count fields, eg FIB.CCPText after an insert or a delete... Works on all CCP fields from this range onwards

Parameters:

adjustment - The (signed) value that should be added to the FIB CCP fields

getStartOffset

public int getStartOffset()

getEndOffset

public int getEndOffset()

getDocument

protected HWPFDocumentCore getDocument()