From a6f921a88395407d739bc5284acfd36f47eb7d5e Mon Sep 17 00:00:00 2001 From: Said Ryan Ackley Date: Fri, 12 Mar 2004 12:34:35 +0000 Subject: [PATCH] javadocs and feature enhancements git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@353536 13f79535-47bb-0310-9956-ffa450edef68 --- .../apache/poi/hwpf/model/PAPBinTable.java | 5 + .../poi/hwpf/model/PAPFormattedDiskPage.java | 38 +++- .../src/org/apache/poi/hwpf/model/PAPX.java | 4 +- .../poi/hwpf/usermodel/CharacterRun.java | 2 +- .../apache/poi/hwpf/usermodel/Paragraph.java | 2 +- .../org/apache/poi/hwpf/usermodel/Range.java | 184 ++++++++++++++++-- .../apache/poi/hwpf/usermodel/Section.java | 2 +- 7 files changed, 218 insertions(+), 19 deletions(-) diff --git a/src/scratchpad/src/org/apache/poi/hwpf/model/PAPBinTable.java b/src/scratchpad/src/org/apache/poi/hwpf/model/PAPBinTable.java index 0954e2291..318153b1c 100644 --- a/src/scratchpad/src/org/apache/poi/hwpf/model/PAPBinTable.java +++ b/src/scratchpad/src/org/apache/poi/hwpf/model/PAPBinTable.java @@ -65,6 +65,11 @@ import org.apache.poi.hwpf.sprm.SprmBuffer; import org.apache.poi.poifs.common.POIFSConstants; import org.apache.poi.util.LittleEndian; +/** + * This class represents the bin table of Word document but it also serves as a + * holder for all of the paragraphs of document that have been loaded into + * memory. + */ public class PAPBinTable { ArrayList _paragraphs = new ArrayList(); diff --git a/src/scratchpad/src/org/apache/poi/hwpf/model/PAPFormattedDiskPage.java b/src/scratchpad/src/org/apache/poi/hwpf/model/PAPFormattedDiskPage.java index a778648f6..42cd566b2 100644 --- a/src/scratchpad/src/org/apache/poi/hwpf/model/PAPFormattedDiskPage.java +++ b/src/scratchpad/src/org/apache/poi/hwpf/model/PAPFormattedDiskPage.java @@ -109,16 +109,38 @@ public class PAPFormattedDiskPage extends FormattedDiskPage _dataStream = dataStream; } + /** + * Fills the queue for writing. + * + * @param filler a List of PAPXs + */ public void fill(List filler) { _papxList.addAll(filler); } - public ArrayList getOverflow() + /** + * Used when writing out a Word docunment. This method is part of a sequence + * that is necessary because there is no easy and efficient way to + * determine the number PAPX's that will fit into one FKP. THe sequence is + * as follows: + * + * fill() + * toByteArray() + * getOverflow() + * + * @return The remaining PAPXs that didn't fit into this FKP. + */ + ArrayList getOverflow() { return _overFlow; } + /** + * Gets the PAPX at index. + * @param index The index to get the PAPX for. + * @return The PAPX at index. + */ public PAPX getPAPX(int index) { return (PAPX)_papxList.get(index); @@ -148,6 +170,13 @@ public class PAPFormattedDiskPage extends FormattedDiskPage return papx; } + /** + * Creates a byte array representation of this data structure. Suitable for + * writing to a Word document. + * + * @param fcMin The file offset in the main stream where text begins. + * @return A byte array representing this data structure. + */ protected byte[] toByteArray(int fcMin) { byte[] buf = new byte[512]; @@ -250,7 +279,7 @@ public class PAPFormattedDiskPage extends FormattedDiskPage // store grpprl at hugeGrpprlOffset System.arraycopy(grpprl, 2, _dataStream, hugeGrpprlOffset + 2, - grpprl.length - 2); + grpprl.length); LittleEndian.putUShort(_dataStream, hugeGrpprlOffset, grpprl.length); // grpprl = grpprl containing only a sprmPHugePapx2 @@ -299,6 +328,11 @@ public class PAPFormattedDiskPage extends FormattedDiskPage return buf; } + /** + * Used to get the ParagraphHeight of a PAPX at a particular index. + * @param index + * @return The ParagraphHeight + */ private ParagraphHeight getParagraphHeight(int index) { int pheOffset = _offset + 1 + (((_crun + 1) * 4) + (index * 13)); diff --git a/src/scratchpad/src/org/apache/poi/hwpf/model/PAPX.java b/src/scratchpad/src/org/apache/poi/hwpf/model/PAPX.java index 6683b17e1..473ffd367 100644 --- a/src/scratchpad/src/org/apache/poi/hwpf/model/PAPX.java +++ b/src/scratchpad/src/org/apache/poi/hwpf/model/PAPX.java @@ -108,12 +108,12 @@ public class PAPX extends CachedPropertyNode int grpprlSize = LittleEndian.getShort(datastream, hugeGrpprlOffset); if( hugeGrpprlOffset+grpprlSize < datastream.length) { - byte[] hugeGrpprl = new byte[grpprlSize]; + byte[] hugeGrpprl = new byte[grpprlSize + 2]; // copy original istd into huge Grpprl hugeGrpprl[0] = grpprl[0]; hugeGrpprl[1] = grpprl[1]; // copy Grpprl from dataStream System.arraycopy(datastream, hugeGrpprlOffset + 2, hugeGrpprl, 2, - grpprlSize-2); + grpprlSize); // save a pointer to where we got the huge Grpprl from _hugeGrpprlOffset = hugeGrpprlOffset; return new SprmBuffer(hugeGrpprl); diff --git a/src/scratchpad/src/org/apache/poi/hwpf/usermodel/CharacterRun.java b/src/scratchpad/src/org/apache/poi/hwpf/usermodel/CharacterRun.java index 8446a24fe..cc1d4cae1 100644 --- a/src/scratchpad/src/org/apache/poi/hwpf/usermodel/CharacterRun.java +++ b/src/scratchpad/src/org/apache/poi/hwpf/usermodel/CharacterRun.java @@ -122,7 +122,7 @@ public class CharacterRun CharacterRun(CHPX chpx, StyleSheet ss, short istd, Range parent) { - super(chpx.getStart(), chpx.getEnd(), parent); + super(Math.max(parent._start, chpx.getStart()), Math.min(parent._end, chpx.getEnd()), parent); _props = chpx.getCharacterProperties(ss, istd); _chpx = chpx.getSprmBuf(); } diff --git a/src/scratchpad/src/org/apache/poi/hwpf/usermodel/Paragraph.java b/src/scratchpad/src/org/apache/poi/hwpf/usermodel/Paragraph.java index cb0134e32..cf929a9b6 100644 --- a/src/scratchpad/src/org/apache/poi/hwpf/usermodel/Paragraph.java +++ b/src/scratchpad/src/org/apache/poi/hwpf/usermodel/Paragraph.java @@ -140,7 +140,7 @@ public class Paragraph protected Paragraph(PAPX papx, Range parent) { - super(papx.getStart(), papx.getEnd(), parent); + super(Math.max(parent._start, papx.getStart()), Math.min(parent._end, papx.getEnd()), parent); _props = papx.getParagraphProperties(_doc.getStyleSheet()); _papx = papx.getSprmBuf(); _istd = papx.getIstd(); diff --git a/src/scratchpad/src/org/apache/poi/hwpf/usermodel/Range.java b/src/scratchpad/src/org/apache/poi/hwpf/usermodel/Range.java index 77bd8f357..b0dfed4c9 100644 --- a/src/scratchpad/src/org/apache/poi/hwpf/usermodel/Range.java +++ b/src/scratchpad/src/org/apache/poi/hwpf/usermodel/Range.java @@ -92,6 +92,15 @@ import java.util.NoSuchElementException; import java.io.UnsupportedEncodingException; import java.lang.ref.WeakReference; +/** + * 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. + * + * @author Ryan Ackley + */ public class Range { @@ -103,32 +112,79 @@ public class Range public static final int TYPE_TABLE = 5; public static final int TYPE_UNDEFINED = 6; + /** Needed so inserts and deletes will ripple up through containing Ranges */ private WeakReference _parent; + + /** The starting character offset of this range.*/ protected int _start; + + /** The ending character offset of this range.*/ protected int _end; + + /** The document this range blongs to.*/ protected HWPFDocument _doc; + + /** Have we loaded the section indexes yet*/ boolean _sectionRangeFound; + + /** All sections that belong to the document this Range belongs to.*/ protected List _sections; - int _sectionStart; - int _sectionEnd; - boolean _parRangeFound; + + /** The start index in the sections list for this Range*/ + protected int _sectionStart; + + /** The end index in the sections list for this Range.*/ + protected int _sectionEnd; + + /** Have we loaded the paragraph indexes yet.*/ + protected boolean _parRangeFound; + + /** All paragraphs that belong to the document this Range belongs to.*/ protected List _paragraphs; + + /** The start index in the paragraphs list for this Range*/ protected int _parStart; + + /** The end index in the paragraphs list for this Range.*/ protected int _parEnd; - boolean _charRangeFound; + + /** Have we loaded the characterRun indexes yet.*/ + protected boolean _charRangeFound; + + /** All CharacterRuns that belong to the document this Range belongs to.*/ protected List _characters; - int _charStart; - int _charEnd; - boolean _textRangeFound; + + /** The start index in the characterRuns list for this Range*/ + protected int _charStart; + + /** The end index in the characterRuns list for this Range. */ + protected int _charEnd; + + /** Have we loaded the Text indexes yet*/ + protected boolean _textRangeFound; + + /** All text pieces that belong to the document this Range belongs to.*/ protected List _text; - int _textStart; - int _textEnd; + + /** The start index in the text list for this Range.*/ + protected int _textStart; + + /** The end index in the text list for this Range.*/ + protected int _textEnd; // protected Range() // { // // } + /** + * Used to construct a Range from a document. This is generally used to + * create a Range that spans the whole document. + * + * @param start Starting character offset of the range. + * @param end Ending character offset of the range. + * @param doc The HWPFDocument the range is based on. + */ public Range(int start, int end, HWPFDocument doc) { _start = start; @@ -141,6 +197,13 @@ public class Range _parent = new WeakReference(null); } + /** + * Used to create Ranges that are children of other Ranges. + * + * @param start Starting character offset of the range. + * @param end Ending character offset of the range. + * @param doc The parent this range belongs to. + */ protected Range(int start, int end, Range parent) { _start = start; @@ -153,6 +216,15 @@ public class Range _parent = new WeakReference(parent); } + /** + * Constructor used to build a Range from indexes in one of its internal + * lists. + * + * @param startIdx The starting index in the list. + * @param endIdx The ending index in the list. + * @param idxType The list type. + * @param parent The parent Range this range belongs to. + */ protected Range(int startIdx, int endIdx, int idxType, Range parent) { _doc = parent._doc; @@ -195,6 +267,11 @@ public class Range } } + /** + * Gets the text that this Range contains. + * + * @return The text for this range. + */ public String text() { initText(); @@ -211,24 +288,48 @@ public class Range return sb.toString(); } + /** + * 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. + * + * @return The number of sections in this range. + */ public int numSections() { initSections(); return _sectionEnd - _sectionStart; } + /** + * 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. + * + * @return The number of paragraphs in this range. + */ + public int numParagraphs() { initParagraphs(); return _parEnd - _parStart; } + /** + * + * @return The number of characterRuns in this range. + */ + public int numCharacterRuns() { initCharacterRuns(); return _charEnd - _charStart; } + /** + * Inserts text into the front of this range. + * + * @param text The text to insert + * @return The character run that text was inserted into. + */ public CharacterRun insertBefore(String text) //throws UnsupportedEncodingException { @@ -250,6 +351,12 @@ public class Range return getCharacterRun(0); } + /** + * Inserts text onto the end of this range + * + * @param text The text to insert + * @return The character run the text was inserted into. + */ public CharacterRun insertAfter(String text) { initAll(); @@ -269,6 +376,15 @@ public class Range } + /** + * Inserts text into the front of this range and it gives that text the + * CharacterProperties specified in props. + * + * @param text The text to insert. + * @param props The CharacterProperties to give the text. + * @return A new CharacterRun that has the given text and properties and is n + * ow a part of the document. + */ public CharacterRun insertBefore(String text, CharacterProperties props) //throws UnsupportedEncodingException { @@ -285,6 +401,15 @@ public class Range return insertBefore(text); } + /** + * Inserts text onto the end of this range and gives that text the + * CharacterProperties specified in props. + * + * @param text The text to insert. + * @param props The CharacterProperties to give the text. + * @return A new CharacterRun that has the given text and properties and is n + * ow a part of the document. + */ public CharacterRun insertAfter(String text, CharacterProperties props) //throws UnsupportedEncodingException { @@ -301,13 +426,31 @@ public class Range return insertAfter(text); } - + /** + * Inserts and empty paragraph into the front of this range. + * + * @param props The properties that the new paragraph will have. + * @param styleIndex The index into the stylesheet for the new paragraph. + * @return The newly inserted paragraph. + */ public Paragraph insertBefore(ParagraphProperties props, int styleIndex) //throws UnsupportedEncodingException { return this.insertBefore(props, styleIndex, "\r"); } + /** + * 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' + * + * @param props The paragraph's properties. + * @param styleIndex The index of the paragraph's style in the style sheet. + * @param text The text to insert. + * @return A newly inserted paragraph. + */ protected Paragraph insertBefore(ParagraphProperties props, int styleIndex, String text) //throws UnsupportedEncodingException { @@ -327,6 +470,13 @@ public class Range return getParagraph(0); } + /** + * Inserts and empty paragraph into the end of this range. + * + * @param props The properties that the new paragraph will have. + * @param styleIndex The index into the stylesheet for the new paragraph. + * @return The newly inserted paragraph. + */ public Paragraph insertAfter(ParagraphProperties props, int styleIndex) //throws UnsupportedEncodingException @@ -334,6 +484,18 @@ public class Range return this.insertAfter(props, styleIndex, "\r"); } + /** + * 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' + * + * @param props The paragraph's properties. + * @param styleIndex The index of the paragraph's style in the style sheet. + * @param text The text to insert. + * @return A newly inserted paragraph. + */ protected Paragraph insertAfter(ParagraphProperties props, int styleIndex, String text) //throws UnsupportedEncodingException { @@ -354,8 +516,6 @@ public class Range return getParagraph(numParagraphs() - 1); } - - public Table insertBefore(TableProperties props, int rows) { ParagraphProperties parProps = new ParagraphProperties(); diff --git a/src/scratchpad/src/org/apache/poi/hwpf/usermodel/Section.java b/src/scratchpad/src/org/apache/poi/hwpf/usermodel/Section.java index e0f88d179..d0f58aa61 100644 --- a/src/scratchpad/src/org/apache/poi/hwpf/usermodel/Section.java +++ b/src/scratchpad/src/org/apache/poi/hwpf/usermodel/Section.java @@ -64,7 +64,7 @@ public class Section public Section(SEPX sepx, Range parent) { - super(sepx.getStart(), sepx.getEnd(), parent); + super(Math.max(parent._start, sepx.getStart()), Math.min(parent._end, sepx.getEnd()), parent); _props = sepx.getSectionProperties(); }