org.apache.poi.hwpf.usermodel
Class Range

java.lang.Object
  extended by org.apache.poi.hwpf.usermodel.Range
Direct Known Subclasses:
CharacterRun, DocumentPosition, Paragraph, Section, Table, TableCell, TableRow

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
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.
 
Method Summary
 void delete()
           
 CharacterRun getCharacterRun(int index)
          Gets the character run at index.
 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.
 Paragraph insertAfter(ParagraphProperties props, int styleIndex)
          Deprecated. Use code shall not work with ParagraphProperties
 ListEntry insertAfter(ParagraphProperties props, int listID, int level, int styleIndex)
          Deprecated. Use code shall not work with ParagraphProperties
 CharacterRun insertAfter(java.lang.String text)
          Inserts text onto the end of this range
 CharacterRun insertAfter(java.lang.String text, CharacterProperties props)
          Deprecated. User code should not work with CharacterProperties
 Paragraph insertBefore(ParagraphProperties props, int styleIndex)
          Deprecated. Use code shall not work with ParagraphProperties
 ListEntry insertBefore(ParagraphProperties props, int listID, int level, int styleIndex)
          Deprecated. Use code shall not work with ParagraphProperties
 CharacterRun insertBefore(java.lang.String text)
          Inserts text into the front of this range.
 CharacterRun insertBefore(java.lang.String text, CharacterProperties props)
          Deprecated. User code should not work with CharacterProperties
 Table insertBefore(TableProperties props, int rows)
          Deprecated. Use code shall not work with TableProperties. Use insertTableBefore(short, int) instead
 Table insertTableBefore(short columns, 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 newText, boolean addAfter)
          Replace range text with new one, adding it to the range and deleting original text from document
 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...
 boolean sanityCheck()
          Method for debug purposes.
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.
 java.lang.String toString()
           
 int type()
          This method is used to determine the type.
 boolean usesUnicode()
          Deprecated. Range is not linked to any text piece anymore, so to check if unicode is used please access TextPieceTable during document load time
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, 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
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.
Method Detail

usesUnicode

public boolean usesUnicode()
Deprecated. Range is not linked to any text piece anymore, so to check if unicode is used please access TextPieceTable during document load time

Returns:
always return true

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)
Deprecated. User code should not work with CharacterProperties

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)
Deprecated. User code should not work with CharacterProperties

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)
Deprecated. Use code shall not work with ParagraphProperties

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.

insertAfter

public Paragraph insertAfter(ParagraphProperties props,
                             int styleIndex)
Deprecated. Use code shall not work with ParagraphProperties

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.

delete

public void delete()

insertBefore

public Table insertBefore(TableProperties props,
                          int rows)
Deprecated. Use code shall not work with TableProperties. Use insertTableBefore(short, int) instead

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.

insertTableBefore

public Table insertTableBefore(short columns,
                               int rows)
Inserts a simple table into the beginning of this range.

Parameters:
columns - The number of columns
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)
Deprecated. Use code shall not work with ParagraphProperties

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)
Deprecated. Use code shall not work with ParagraphProperties

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 newText,
                        boolean addAfter)
Replace range text with new one, adding it to the range and deleting original text from document

Parameters:
newText - The text to be replaced with
addAfter - if true the text will be added at the end of current range, otherwise to the beginning

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

getStartOffset

public int getStartOffset()
Returns:
Starting character offset of the range

getEndOffset

public int getEndOffset()
Returns:
The ending character offset of this range

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

sanityCheck

public boolean sanityCheck()
Method for debug purposes. Checks that all resolved elements are inside of current range.