From 4d01de070afd61271e05db43861a6a4b7207c5c8 Mon Sep 17 00:00:00 2001 From: Said Ryan Ackley Date: Mon, 15 Mar 2004 02:57:38 +0000 Subject: [PATCH] javadoc and a minor fix git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@353537 13f79535-47bb-0310-9956-ffa450edef68 --- .../src/org/apache/poi/hwpf/HWPFDocument.java | 2 +- .../src/org/apache/poi/hwpf/QuickTest.java | 72 ++++++++ .../src/org/apache/poi/hwpf/model/CHPX.java | 18 +- .../src/org/apache/poi/hwpf/model/PAPX.java | 20 +-- .../poi/hwpf/usermodel/CharacterRun.java | 91 +++++------ .../poi/hwpf/usermodel/DateAndTime.java | 73 +++------ .../poi/hwpf/usermodel/DropCapSpecifier.java | 24 +++ .../usermodel/{List.java => HWPFList.java} | 33 +++- .../hwpf/usermodel/LineSpacingDescriptor.java | 71 +++----- .../org/apache/poi/hwpf/usermodel/Range.java | 154 +++++++++++------- .../org/apache/poi/hwpf/HWPFTestCase.java | 0 11 files changed, 322 insertions(+), 236 deletions(-) create mode 100644 src/scratchpad/src/org/apache/poi/hwpf/QuickTest.java rename src/scratchpad/src/org/apache/poi/hwpf/usermodel/{List.java => HWPFList.java} (58%) rename src/scratchpad/{src => testcases}/org/apache/poi/hwpf/HWPFTestCase.java (100%) diff --git a/src/scratchpad/src/org/apache/poi/hwpf/HWPFDocument.java b/src/scratchpad/src/org/apache/poi/hwpf/HWPFDocument.java index da505430cd..28d4d9ad80 100644 --- a/src/scratchpad/src/org/apache/poi/hwpf/HWPFDocument.java +++ b/src/scratchpad/src/org/apache/poi/hwpf/HWPFDocument.java @@ -392,7 +392,7 @@ public class HWPFDocument return _dataStream; } - public int registerList(List list) + public int registerList(HWPFList list) { if (_lt == null) { diff --git a/src/scratchpad/src/org/apache/poi/hwpf/QuickTest.java b/src/scratchpad/src/org/apache/poi/hwpf/QuickTest.java new file mode 100644 index 0000000000..5a57f6b0f0 --- /dev/null +++ b/src/scratchpad/src/org/apache/poi/hwpf/QuickTest.java @@ -0,0 +1,72 @@ +package org.apache.poi.hwpf; + +import java.io.*; + +import org.apache.poi.hwpf.usermodel.*; + +public class QuickTest +{ + public QuickTest() + { + } + + public static void main(String[] args) + { + try + { + HWPFDocument doc = new HWPFDocument (new FileInputStream (args[0])); + Range r = doc.getRange(); + + System.out.println("Example you supplied:"); + System.out.println("---------------------"); + for (int x = 0; x < r.numSections(); x++) + { + Section s = r.getSection(x); + for (int y = 0; y < s.numParagraphs(); y++) + { + Paragraph p = s.getParagraph(y); + for (int z = 0; z < p.numCharacterRuns(); z++) + { + //character run + CharacterRun run = p.getCharacterRun(z); + //character run text + String text = run.text(); + // show us the text + System.out.print(text); + } + // use a new line at the paragraph break + System.out.println(); + } + } + + +// System.out.println("\n\nExample using new method:"); +// System.out.println("-------------------------"); +// for (int x = 0; x < r.numSections(); x++) +// { +// Section s = r.getSection(x); +// for (int y = 0; y < s.numParagraphs(); y++) +// { +// Paragraph p = s.getParagraph(y); +// for (int z = 0; z < p.numCharacterRuns(); z++) +// { +// //character run +// CharacterRun run = p.getCharacterRun(z); +// //** get character run/paragraph common text ** +// String text = run.commonText(p); +// // show us the text +// System.out.print(text); +// } +// // use a new line at the paragraph break +// System.out.println(); +// } +// } + + } + catch (Throwable t) + { + t.printStackTrace(); + } + } + +} \ No newline at end of file diff --git a/src/scratchpad/src/org/apache/poi/hwpf/model/CHPX.java b/src/scratchpad/src/org/apache/poi/hwpf/model/CHPX.java index 2e1cf9e330..f6efb296c3 100644 --- a/src/scratchpad/src/org/apache/poi/hwpf/model/CHPX.java +++ b/src/scratchpad/src/org/apache/poi/hwpf/model/CHPX.java @@ -65,7 +65,7 @@ import org.apache.poi.hwpf.sprm.CharacterSprmUncompressor; * @author Ryan Ackley */ -public class CHPX extends CachedPropertyNode +public class CHPX extends PropertyNode { public CHPX(int fcStart, int fcEnd, byte[] grpprl) @@ -84,17 +84,15 @@ public class CHPX extends CachedPropertyNode return ((SprmBuffer)_buf).toByteArray(); } + public SprmBuffer getSprmBuf() + { + return (SprmBuffer)_buf; + } + public CharacterProperties getCharacterProperties(StyleSheet ss, short istd) { - CharacterProperties props = (CharacterProperties)super.getCacheContents(); - if (props == null) - { - CharacterProperties baseStyle = ss.getCharacterStyle(istd); - props = CharacterSprmUncompressor.uncompressCHP(baseStyle, getGrpprl(), 0); - super.fillCache(props); - } + CharacterProperties baseStyle = ss.getCharacterStyle(istd); + CharacterProperties props = CharacterSprmUncompressor.uncompressCHP(baseStyle, getGrpprl(), 0); return props; } - - } 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 473ffd3671..75b516f3cd 100644 --- a/src/scratchpad/src/org/apache/poi/hwpf/model/PAPX.java +++ b/src/scratchpad/src/org/apache/poi/hwpf/model/PAPX.java @@ -69,7 +69,7 @@ import org.apache.poi.hwpf.sprm.SprmOperation; * @author Ryan Ackley */ -public class PAPX extends CachedPropertyNode +public class PAPX extends PropertyNode { private ParagraphHeight _phe; @@ -153,19 +153,17 @@ public class PAPX extends CachedPropertyNode } } - public ParagraphProperties getParagraphProperties(StyleSheet ss) + public SprmBuffer getSprmBuf() { + return (SprmBuffer)_buf; + } - ParagraphProperties props = (ParagraphProperties)super.getCacheContents(); - if (props == null) - { - short istd = getIstd(); - ParagraphProperties baseStyle = ss.getParagraphStyle(istd); - props = ParagraphSprmUncompressor.uncompressPAP(baseStyle, getGrpprl(), 2); - super.fillCache(props); - } + public ParagraphProperties getParagraphProperties(StyleSheet ss) + { + short istd = getIstd(); + ParagraphProperties baseStyle = ss.getParagraphStyle(istd); + ParagraphProperties props = ParagraphSprmUncompressor.uncompressPAP(baseStyle, getGrpprl(), 2); return props; - } public boolean equals(Object o) 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 cc1d4cae11..c1eafe0b89 100644 --- a/src/scratchpad/src/org/apache/poi/hwpf/usermodel/CharacterRun.java +++ b/src/scratchpad/src/org/apache/poi/hwpf/usermodel/CharacterRun.java @@ -1,56 +1,20 @@ /* ==================================================================== - * The Apache Software License, Version 1.1 - * - * Copyright (c) 2003 The Apache Software Foundation. All rights - * reserved. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions - * are met: - * - * 1. Redistributions of source code must retain the above copyright - * notice, this list of conditions and the following disclaimer. - * - * 2. Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in - * the documentation and/or other materials provided with the - * distribution. - * - * 3. The end-user documentation included with the redistribution, - * if any, must include the following acknowledgment: - * "This product includes software developed by the - * Apache Software Foundation (http://www.apache.org/)." - * Alternately, this acknowledgment may appear in the software itself, - * if and wherever such third-party acknowledgments normally appear. - * - * 4. The names "Apache" and "Apache Software Foundation" and - * "Apache POI" must not be used to endorse or promote products - * derived from this software without prior written permission. For - * written permission, please contact apache@apache.org. - * - * 5. Products derived from this software may not be called "Apache", - * "Apache POI", nor may "Apache" appear in their name, without - * prior written permission of the Apache Software Foundation. - * - * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED - * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR - * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF - * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND - * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, - * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT - * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - * SUCH DAMAGE. - * ==================================================================== - * - * This software consists of voluntary contributions made by many - * individuals on behalf of the Apache Software Foundation. For more - * information on the Apache Software Foundation, please see - * . - */ + Copyright 2002-2004 Apache Software Foundation + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +==================================================================== */ + + package org.apache.poi.hwpf.usermodel; @@ -62,6 +26,11 @@ import org.apache.poi.hwpf.model.StyleSheet; import org.apache.poi.hwpf.sprm.SprmBuffer; import org.apache.poi.hwpf.sprm.CharacterSprmCompressor; +/** + * This class represents a run of text that share common properties. + * + * @author Ryan Ackley + */ public class CharacterRun extends Range implements Cloneable @@ -120,6 +89,13 @@ public class CharacterRun SprmBuffer _chpx; CharacterProperties _props; + /** + * + * @param chpx The chpx this object is based on. + * @param ss The stylesheet for the document this run belongs to. + * @param istd The style index if this run's base style. + * @param parent The parent range of this character run (usually a paragraph). + */ CharacterRun(CHPX chpx, StyleSheet ss, short istd, Range parent) { super(Math.max(parent._start, chpx.getStart()), Math.min(parent._end, chpx.getEnd()), parent); @@ -127,6 +103,11 @@ public class CharacterRun _chpx = chpx.getSprmBuf(); } + /** + * Here for runtime type determination using a switch statement convenient. + * + * @return TYPE_CHARACTER + */ public int type() { return TYPE_CHARACTER; @@ -469,6 +450,12 @@ public class CharacterRun _props.setIco24(colour24); } + /** + * Used to create a deep copy of this object. + * + * @return A deep copy. + * @throws CloneNotSupportedException never + */ public Object clone() throws CloneNotSupportedException { diff --git a/src/scratchpad/src/org/apache/poi/hwpf/usermodel/DateAndTime.java b/src/scratchpad/src/org/apache/poi/hwpf/usermodel/DateAndTime.java index aae16ddb60..44436952e2 100644 --- a/src/scratchpad/src/org/apache/poi/hwpf/usermodel/DateAndTime.java +++ b/src/scratchpad/src/org/apache/poi/hwpf/usermodel/DateAndTime.java @@ -1,62 +1,31 @@ /* ==================================================================== - * The Apache Software License, Version 1.1 - * - * Copyright (c) 2003 The Apache Software Foundation. All rights - * reserved. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions - * are met: - * - * 1. Redistributions of source code must retain the above copyright - * notice, this list of conditions and the following disclaimer. - * - * 2. Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in - * the documentation and/or other materials provided with the - * distribution. - * - * 3. The end-user documentation included with the redistribution, - * if any, must include the following acknowledgment: - * "This product includes software developed by the - * Apache Software Foundation (http://www.apache.org/)." - * Alternately, this acknowledgment may appear in the software itself, - * if and wherever such third-party acknowledgments normally appear. - * - * 4. The names "Apache" and "Apache Software Foundation" and - * "Apache POI" must not be used to endorse or promote products - * derived from this software without prior written permission. For - * written permission, please contact apache@apache.org. - * - * 5. Products derived from this software may not be called "Apache", - * "Apache POI", nor may "Apache" appear in their name, without - * prior written permission of the Apache Software Foundation. - * - * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED - * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR - * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF - * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND - * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, - * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT - * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - * SUCH DAMAGE. - * ==================================================================== - * - * This software consists of voluntary contributions made by many - * individuals on behalf of the Apache Software Foundation. For more - * information on the Apache Software Foundation, please see - * . - */ + Copyright 2002-2004 Apache Software Foundation + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +==================================================================== */ + + package org.apache.poi.hwpf.usermodel; import org.apache.poi.util.BitField; import org.apache.poi.util.LittleEndian; +/** + * This class is used to represent a date and time in a Word document. + * + * @author Ryan Ackley + */ public class DateAndTime implements Cloneable { diff --git a/src/scratchpad/src/org/apache/poi/hwpf/usermodel/DropCapSpecifier.java b/src/scratchpad/src/org/apache/poi/hwpf/usermodel/DropCapSpecifier.java index 59d840fad7..513b305149 100644 --- a/src/scratchpad/src/org/apache/poi/hwpf/usermodel/DropCapSpecifier.java +++ b/src/scratchpad/src/org/apache/poi/hwpf/usermodel/DropCapSpecifier.java @@ -1,8 +1,32 @@ +/* ==================================================================== + Copyright 2002-2004 Apache Software Foundation + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +==================================================================== */ + package org.apache.poi.hwpf.usermodel; import org.apache.poi.util.BitField; import org.apache.poi.util.LittleEndian; +/** + * This data structure is used by a paragraph to determine how it should drop + * its first letter. I think its the visual effect that will show a giant first + * letter to a paragraph. I've seen this used in the first paragraph of a + * book + * + * @author Ryan Ackley + */ public class DropCapSpecifier { private short _info; diff --git a/src/scratchpad/src/org/apache/poi/hwpf/usermodel/List.java b/src/scratchpad/src/org/apache/poi/hwpf/usermodel/HWPFList.java similarity index 58% rename from src/scratchpad/src/org/apache/poi/hwpf/usermodel/List.java rename to src/scratchpad/src/org/apache/poi/hwpf/usermodel/HWPFList.java index 709f46695e..66dc3bd300 100644 --- a/src/scratchpad/src/org/apache/poi/hwpf/usermodel/List.java +++ b/src/scratchpad/src/org/apache/poi/hwpf/usermodel/HWPFList.java @@ -1,3 +1,19 @@ +/* ==================================================================== + Copyright 2002-2004 Apache Software Foundation + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +==================================================================== */ + package org.apache.poi.hwpf.usermodel; import org.apache.poi.hwpf.HWPFDocument; @@ -10,15 +26,26 @@ import org.apache.poi.hwpf.model.StyleSheet; import org.apache.poi.hwpf.sprm.CharacterSprmCompressor; import org.apache.poi.hwpf.sprm.ParagraphSprmCompressor; - -public class List +/** + * This class is used to create a list in a Word document. It is used in + * conjunction with {@link + * org.apache.poi.hwpf.HWPFDocument#registerList(HWPFList) registerList} in + * {@link org.apache.poi.hwpf.HWPFDocument HWPFDocument}. + * + * In Word, lists are not ranged entities. Lists only act as properties for + * list entries. Once you register a list, you can add list entries to a + * document that use the list. + * + * @author Ryan Ackley + */ +public class HWPFList { private ListData _listData; private ListFormatOverride _override; private boolean _registered; private StyleSheet _styleSheet; - public List(boolean numbered, StyleSheet styleSheet) + public HWPFList(boolean numbered, StyleSheet styleSheet) { _listData = new ListData((int)(Math.random() * (double)System.currentTimeMillis()), numbered); _override = new ListFormatOverride(_listData.getLsid()); diff --git a/src/scratchpad/src/org/apache/poi/hwpf/usermodel/LineSpacingDescriptor.java b/src/scratchpad/src/org/apache/poi/hwpf/usermodel/LineSpacingDescriptor.java index 35e410c977..e229fcad8a 100644 --- a/src/scratchpad/src/org/apache/poi/hwpf/usermodel/LineSpacingDescriptor.java +++ b/src/scratchpad/src/org/apache/poi/hwpf/usermodel/LineSpacingDescriptor.java @@ -1,61 +1,28 @@ /* ==================================================================== - * The Apache Software License, Version 1.1 - * - * Copyright (c) 2003 The Apache Software Foundation. All rights - * reserved. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions - * are met: - * - * 1. Redistributions of source code must retain the above copyright - * notice, this list of conditions and the following disclaimer. - * - * 2. Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in - * the documentation and/or other materials provided with the - * distribution. - * - * 3. The end-user documentation included with the redistribution, - * if any, must include the following acknowledgment: - * "This product includes software developed by the - * Apache Software Foundation (http://www.apache.org/)." - * Alternately, this acknowledgment may appear in the software itself, - * if and wherever such third-party acknowledgments normally appear. - * - * 4. The names "Apache" and "Apache Software Foundation" and - * "Apache POI" must not be used to endorse or promote products - * derived from this software without prior written permission. For - * written permission, please contact apache@apache.org. - * - * 5. Products derived from this software may not be called "Apache", - * "Apache POI", nor may "Apache" appear in their name, without - * prior written permission of the Apache Software Foundation. - * - * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED - * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR - * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF - * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND - * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, - * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT - * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - * SUCH DAMAGE. - * ==================================================================== - * - * This software consists of voluntary contributions made by many - * individuals on behalf of the Apache Software Foundation. For more - * information on the Apache Software Foundation, please see - * . - */ + Copyright 2002-2004 Apache Software Foundation + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +==================================================================== */ package org.apache.poi.hwpf.usermodel; import org.apache.poi.util.LittleEndian; +/** + * This class is used to determine line spacing for a paragraph. + * + * @author Ryan Ackley + */ public class LineSpacingDescriptor implements Cloneable { 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 b0dfed4c94..f633fc424a 100644 --- a/src/scratchpad/src/org/apache/poi/hwpf/usermodel/Range.java +++ b/src/scratchpad/src/org/apache/poi/hwpf/usermodel/Range.java @@ -1,56 +1,20 @@ /* ==================================================================== - * The Apache Software License, Version 1.1 - * - * Copyright (c) 2003 The Apache Software Foundation. All rights - * reserved. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions - * are met: - * - * 1. Redistributions of source code must retain the above copyright - * notice, this list of conditions and the following disclaimer. - * - * 2. Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in - * the documentation and/or other materials provided with the - * distribution. - * - * 3. The end-user documentation included with the redistribution, - * if any, must include the following acknowledgment: - * "This product includes software developed by the - * Apache Software Foundation (http://www.apache.org/)." - * Alternately, this acknowledgment may appear in the software itself, - * if and wherever such third-party acknowledgments normally appear. - * - * 4. The names "Apache" and "Apache Software Foundation" and - * "Apache POI" must not be used to endorse or promote products - * derived from this software without prior written permission. For - * written permission, please contact apache@apache.org. - * - * 5. Products derived from this software may not be called "Apache", - * "Apache POI", nor may "Apache" appear in their name, without - * prior written permission of the Apache Software Foundation. - * - * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED - * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR - * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF - * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND - * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, - * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT - * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - * SUCH DAMAGE. - * ==================================================================== - * - * This software consists of voluntary contributions made by many - * individuals on behalf of the Apache Software Foundation. For more - * information on the Apache Software Foundation, please see - * . - */ + Copyright 2002-2004 Apache Software Foundation + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +==================================================================== */ + + package org.apache.poi.hwpf.usermodel; @@ -202,7 +166,7 @@ public class Range * * @param start Starting character offset of the range. * @param end Ending character offset of the range. - * @param doc The parent this range belongs to. + * @param parent The parent this range belongs to. */ protected Range(int start, int end, Range parent) { @@ -516,6 +480,14 @@ public class Range return getParagraph(numParagraphs() - 1); } + /** + * Inserts a simple table into the beginning of this range. The number of + * columns is determined by the TableProperties passed into this function. + * + * @param props The table properties for the table. + * @param rows The number of rows. + * @return The empty Table that is now part of the document. + */ public Table insertBefore(TableProperties props, int rows) { ParagraphProperties parProps = new ParagraphProperties(); @@ -538,8 +510,17 @@ public class Range return new Table(_start, _start + (rows * (columns + 1)), this, 0); } + /** + * Inserts a list into the beginning of this range. + * + * @param props The properties of the list entry. All list entries are + * paragraphs. + * @param listID The id of the list that contains the properties. + * @param level The indentation level of the list. + * @param styleIndex The base style's index in the stylesheet. + * @return The empty ListEntry that is now part of the document. + */ public ListEntry insertBefore(ParagraphProperties props, int listID, int level, int styleIndex) - //throws UnsupportedEncodingException { ListTables lt = _doc.getListTables(); if (lt.getLevel(listID, level) == null) @@ -554,6 +535,12 @@ public class Range return (ListEntry)insertBefore(props, styleIndex); } + /** + * Gets the character run at index. The index is relative to this range. + * + * @param index The index of the character run to get. + * @return The character run at the specified index in this range. + */ public CharacterRun getCharacterRun(int index) { initCharacterRuns(); @@ -569,6 +556,12 @@ public class Range return chp; } + /** + * Gets the section at index. The index is relative to this range. + * + * @param index The index of the section to get. + * @return The section at the specified index in this range. + */ public Section getSection(int index) { initSections(); @@ -577,6 +570,13 @@ public class Range return sep; } + /** + * Gets the paragraph at index. The index is relative to this range. + * + * @param index The index of the paragraph to get. + * @return The paragraph at the specified index in this range. + */ + public Paragraph getParagraph(int index) { initParagraphs(); @@ -596,11 +596,24 @@ public class Range return pap; } + /** + * This method is used to determine the type. Handy for switch statements + * compared to the instanceof operator. + * + * @return A TYPE constant. + */ public int type() { return TYPE_UNDEFINED; } + /** + * Gets the table that starts with paragraph. In a Word file, a table consists + * of a group of paragraphs with certain flags set. + * + * @param paragraph The paragraph that is the first paragraph in the table. + * @return The table that starts with paragraph + */ public Table getTable(Paragraph paragraph) { if (!paragraph.isInTable()) @@ -640,6 +653,9 @@ public class Range return new Table(r._parStart, tableEnd, r._doc.getRange(), 1); } + /** + * loads all of the list indexes. + */ private void initAll() { initText(); @@ -648,7 +664,9 @@ public class Range initSections(); } - + /** + * inits the paragraph list indexes. + */ private void initParagraphs() { if (!_parRangeFound) @@ -660,6 +678,9 @@ public class Range } } + /** + * inits the character run list indexes. + */ private void initCharacterRuns() { if (!_charRangeFound) @@ -671,6 +692,9 @@ public class Range } } + /** + * inits the text piece list indexes. + */ private void initText() { if (!_textRangeFound) @@ -682,6 +706,9 @@ public class Range } } + /** + * inits the section list indexes. + */ private void initSections() { if (!_sectionRangeFound) @@ -693,6 +720,16 @@ public class Range } } + /** + * Used to find the list indexes of a particular property. + * + * @param rpl A list of property nodes. + * @param min A hint on where to start looking. + * @param start The starting character offset. + * @param end The ending character offset. + * @return An int array of length 2. The first int is the start index and the + * second int is the end index. + */ private int[] findRange(List rpl, int min, int start, int end) { int x = min; @@ -713,6 +750,9 @@ public class Range return new int[]{x, y + 1}; } + /** + * resets the list indexes. + */ private void reset() { _textRangeFound = false; @@ -721,6 +761,10 @@ public class Range _sectionRangeFound = false; } + /** + * adjust this range after an insert happens. + * @param length the length to adjust for + */ private void adjustForInsert(int length) { _end += length; diff --git a/src/scratchpad/src/org/apache/poi/hwpf/HWPFTestCase.java b/src/scratchpad/testcases/org/apache/poi/hwpf/HWPFTestCase.java similarity index 100% rename from src/scratchpad/src/org/apache/poi/hwpf/HWPFTestCase.java rename to src/scratchpad/testcases/org/apache/poi/hwpf/HWPFTestCase.java -- 2.39.5