Shift comments support over onto new style XSSFModel, in preparation for readings and writing existing ones

git-svn-id: https://svn.apache.org/repos/asf/poi/branches/ooxml@643204 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Nick Burch 2008-03-31 23:15:38 +00:00
parent 117e95f063
commit 4361861502
11 changed files with 217 additions and 75 deletions

View File

@ -1155,7 +1155,8 @@ Examples:
degenerate case of Named Range in that the 'group of cells' contains exactly one
cell. You can create as well as refer to cells in a workbook by their named range.
When working with Named Ranges, the classes: org.apache.poi.hssf.util.CellReference and
& org.apache.poi.hssf.util.AreaReference are used.
& org.apache.poi.hssf.util.AreaReference are used (these
work for both XSSF and HSSF, despite the package name).
</p>
<p>
Creating Named Range / Named Cell
@ -1163,28 +1164,27 @@ Examples:
<source>
// setup code
String sname = "TestSheet", cname = "TestName", cvalue = "TestVal";
HSSFWorkbook wb = new HSSFWorkbook();
HSSFSheet sheet = wb.createSheet(sname);
Workbook wb = new HSSFWorkbook();
Sheet sheet = wb.createSheet(sname);
sheet.createRow(0).createCell((short) 0).setCellValue(cvalue);
// 1. create named range for a single cell using areareference
HSSFName namedCell = wb.createName();
Name namedCell = wb.createName();
namedCell.setNameName(cname);
String reference = sname+"!A1:A1"; // area reference
namedCell.setReference(reference);
// 2. create named range for a single cell using cellreference
HSSFName namedCell = wb.createName();
Name namedCell = wb.createName();
namedCell.setNameName(cname);
String reference = sname+"!A1"; // cell reference
namedCell.setReference(reference);
// 3. create named range for an area using AreaReference
HSSFName namedCell = wb.createName();
Name namedCell = wb.createName();
namedCell.setNameName(cname);
String reference = sname+"!A1:C5"; // area reference
namedCell.setReference(reference);
</source>
<p>
Reading from Named Range / Named Cell
@ -1192,19 +1192,19 @@ Examples:
<source>
// setup code
String cname = "TestName";
HSSFWorkbook wb = getMyWorkbook(); // retrieve workbook
Workbook wb = getMyWorkbook(); // retrieve workbook
// retrieve the named range
int namedCellIdx = wb.getNameIndex(cellName);
HSSFName aNamedCell = wb.getNameAt(namedCellIdx);
Name aNamedCell = wb.getNameAt(namedCellIdx);
// retrieve the cell at the named range and test its contents
AreaReference aref = new AreaReference(aNamedCell.getReference());
CellReference[] crefs = aref.getAllReferencedCells();
for (int i=0; i&lt;crefs.length; i++) {
HSSFSheet s = wb.getSheet(crefs[i].getSheetName());
HSSFRow r = sheet.getRow(crefs[i].getRow());
HSSFCell c = r.getCell(crefs[i].getCol());
Sheet s = wb.getSheet(crefs[i].getSheetName());
Row r = sheet.getRow(crefs[i].getRow());
Cell c = r.getCell(crefs[i].getCol());
// extract the cell contents based on cell type etc.
}
</source>
@ -1214,12 +1214,12 @@ Examples:
<source>
// Setup code
String cname = "TestName";
HSSFWorkbook wb = getMyWorkbook(); // retrieve workbook
Workbook wb = getMyWorkbook(); // retrieve workbook
// Retrieve the named range
// Will be something like "$C$10,$D$12:$D$14";
int namedCellIdx = wb.getNameIndex(cellName);
HSSFName aNamedCell = wb.getNameAt(namedCellIdx);
Name aNamedCell = wb.getNameAt(namedCellIdx);
// Retrieve the cell at the named range and test its contents
// Will get back one AreaReference for C10, and
@ -1231,18 +1231,18 @@ Examples:
CellReference[] crefs = arefs[i].getCells();
for (int j=0; j&lt;crefs.length; j++) {
// Check it turns into real stuff
HSSFSheet s = wb.getSheet(crefs[j].getSheetName());
HSSFRow r = s.getRow(crefs[j].getRow());
HSSFCell c = r.getCell(crefs[j].getCol());
Sheet s = wb.getSheet(crefs[j].getSheetName());
Row r = s.getRow(crefs[j].getRow());
Cell c = r.getCell(crefs[j].getCol());
// Do something with this corner cell
}
}
</source>
</section>
<anchor id="CellComments"/>
<section><title>Cell Comments</title>
<section><title>Cell Comments - HSSF</title>
<p>
In Excel a comment is a kind of a text shape,
In HSSF Excel, a comment is a kind of a text shape,
so inserting a comment is very similar to placing a text box in a worksheet:
</p>
<source>
@ -1320,6 +1320,90 @@ Examples:
comment = sheet.getCellComment(3, 1);
</source>
</section>
<section><title>Cell Comments - XSSF</title>
<p>
In XSSF Excel, a comment is still a kind of a text shape, but
things are generally much simpler.
</p>
<source>
Workbook wb = new XSSFWorkbook();
CreationHelper createHelper = wb.getCreationHelper();
Sheet sheet = wb.createSheet("Cell comments in POI XSSF");
//create a cell in row 3
Cell cell1 = sheet.createRow(3).createCell((short)1);
cell1.setCellValue(createHelper.createRichTextString("Hello, World"));
//anchor defines size and position of the comment in worksheet
Comment comment1 = createHelper.createComment();
// set text in the comment
comment1.setString(createHelper.createRichTextString(
"We can set comments in POI"));
//set comment author.
//you can see it in the status bar when moving mouse over the commented cell
comment1.setAuthor("Apache Software Foundation");
// The first way to assign comment to a cell is via HSSFCell.setCellComment method
cell1.setCellComment(comment1);
//create another cell in row 6
Cell cell2 = sheet.createRow(6).createCell((short)1);
cell2.setCellValue(36.6);
Comment comment2 = createHelper.createComment();
//modify background color of the comment
comment2.setFillColor(204, 236, 255);
RichTextString string = createHelper.createRichTextString(
"Normal body temperature");
//apply custom font to the text in the comment
Font font = wb.createFont();
font.setFontName("Arial");
font.setFontHeightInPoints((short)10);
font.setBoldweight(Font.BOLDWEIGHT_BOLD);
font.setColor(Color.RED.index);
string.applyFont(font);
comment2.setString(string);
//by default comments are hidden. This one is always visible.
comment2.setVisible(true);
comment2.setAuthor("Bill Gates");
/**
* The second way to assign comment to a cell is to implicitly specify its row and column.
* Note, it is possible to set row and column of a non-existing cell.
* It works, the commnet is visible.
*/
comment2.setRow(6);
comment2.setColumn((short)1);
FileOutputStream out = new FileOutputStream("poi_comment.xls");
wb.write(out);
out.close();
</source>
<p>
Reading cell comments
</p>
<source>
Cell cell = sheet.get(3).getColumn((short)1);
Comment comment = cell.getCellComment();
if (comment != null) {
RichTextString str = comment.getString();
String author = comment.getAuthor();
}
// alternatively you can retrieve cell comments by (row, column)
comment = sheet.getCellComment(3, 1);
</source>
</section>
<anchor id="Autofit"/>
<section><title>Adjust column width to fit the contents</title>
<source>

View File

@ -0,0 +1,38 @@
/* ====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.ss.usermodel;
/**
* Allows the getting and saving of cell comments,
* associated with a given sheet.
*/
public interface CommentsSource {
public String getAuthor(long authorId);
public int findAuthor(String author);
public Comment findCellComment(int row, int column);
public Comment findCellComment(String cellRef);
public void setCellComment (int row, int column, Comment comment);
public void setCellComment (String cellRef, Comment comment);
public Comment addComment();
}

View File

@ -17,8 +17,6 @@
package org.apache.poi.ss.usermodel;
import java.io.IOException;
/**
* Allows the getting and saving of shared strings
*/

View File

@ -14,27 +14,61 @@
See the License for the specific language governing permissions and
limitations under the License.
==================================================================== */
package org.apache.poi.xssf.usermodel.extensions;
package org.apache.poi.xssf.model;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import org.apache.poi.ss.usermodel.Comment;
import org.apache.poi.ss.usermodel.CommentsSource;
import org.apache.poi.xssf.usermodel.XSSFComment;
import org.apache.poi.xssf.util.CellReference;
import org.apache.xmlbeans.XmlException;
import org.apache.xmlbeans.XmlOptions;
import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTAuthors;
import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTComment;
import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTCommentList;
import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTComments;
import org.openxmlformats.schemas.spreadsheetml.x2006.main.CommentsDocument;
public class XSSFComments {
public class CommentsTable implements CommentsSource, XSSFModel {
private CTComments comments;
public XSSFComments() {
this(CTComments.Factory.newInstance());
public CommentsTable(InputStream is) throws IOException {
readFrom(is);
}
public XSSFComments(CTComments comments) {
public CommentsTable() {
comments = CTComments.Factory.newInstance();
}
/**
* For unit testing only!
*/
public CommentsTable(CTComments comments) {
this.comments = comments;
}
public void readFrom(InputStream is) throws IOException {
try {
CommentsDocument doc = CommentsDocument.Factory.parse(is);
comments = doc.getComments();
} catch (XmlException e) {
throw new IOException(e.getLocalizedMessage());
}
}
public void writeTo(OutputStream out) throws IOException {
XmlOptions options = new XmlOptions();
options.setSaveOuter();
options.setUseDefaultNamespace();
// Requests use of whitespace for easier reading
options.setSavePrettyPrint();
CommentsDocument doc = CommentsDocument.Factory.newInstance(options);
doc.setComments(comments);
doc.save(out, options);
}
public String getAuthor(long authorId) {
return getCommentsAuthors().getAuthorArray((int)authorId);
}
@ -61,17 +95,17 @@ public class XSSFComments {
return null;
}
public void setCellComment (int row, int column, XSSFComment comment) {
public void setCellComment (int row, int column, Comment comment) {
XSSFComment current = findCellComment(row, column);
if (current == null) {
current = addComment();
}
current = comment;
current = (XSSFComment)comment;
current.setRow(row);
current.setColumn((short) column);
}
public void setCellComment (String cellRef, XSSFComment comment) {
public void setCellComment (String cellRef, Comment comment) {
CellReference cellReference = new CellReference(cellRef);
setCellComment(cellReference.getRow(), cellReference.getCol(), comment);
}
@ -99,5 +133,4 @@ public class XSSFComments {
getCommentsAuthors().insertAuthor(index, author);
return index;
}
}
}

View File

@ -17,8 +17,8 @@
package org.apache.poi.xssf.usermodel;
import org.apache.poi.ss.usermodel.Comment;
import org.apache.poi.ss.usermodel.CommentsSource;
import org.apache.poi.ss.usermodel.RichTextString;
import org.apache.poi.xssf.usermodel.extensions.XSSFComments;
import org.apache.poi.xssf.usermodel.helpers.RichTextStringHelper;
import org.apache.poi.xssf.util.CellReference;
import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTComment;
@ -27,14 +27,14 @@ import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTRst;
public class XSSFComment implements Comment {
private CTComment comment;
private XSSFComments comments;
private CommentsSource comments;
public XSSFComment(XSSFComments comments, CTComment comment) {
public XSSFComment(CommentsSource comments, CTComment comment) {
this.comment = comment;
this.comments = comments;
}
public XSSFComment(XSSFComments sheetComments) {
public XSSFComment(CommentsSource sheetComments) {
this(sheetComments, CTComment.Factory.newInstance());
}

View File

@ -27,20 +27,19 @@ import org.apache.poi.hssf.util.PaneInformation;
import org.apache.poi.hssf.util.Region;
import org.apache.poi.ss.usermodel.CellStyle;
import org.apache.poi.ss.usermodel.Comment;
import org.apache.poi.ss.usermodel.CommentsSource;
import org.apache.poi.ss.usermodel.Footer;
import org.apache.poi.ss.usermodel.Header;
import org.apache.poi.ss.usermodel.Patriarch;
import org.apache.poi.ss.usermodel.PrintSetup;
import org.apache.poi.ss.usermodel.Row;
import org.apache.poi.ss.usermodel.Sheet;
import org.apache.poi.xssf.usermodel.extensions.XSSFComments;
import org.apache.poi.xssf.model.CommentsTable;
import org.apache.poi.xssf.usermodel.helpers.ColumnHelper;
import org.apache.poi.xssf.util.CellReference;
import org.apache.xmlbeans.XmlOptions;
import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTBreak;
import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTCol;
import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTCols;
import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTComments;
import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTDialogsheet;
import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTHeaderFooter;
import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTPageBreak;
@ -59,15 +58,13 @@ import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTWorksheet;
public class XSSFSheet implements Sheet {
protected CTSheet sheet;
protected CTWorksheet worksheet;
protected CTDialogsheet dialogsheet;
protected CTComments comments;
protected List<Row> rows;
protected ColumnHelper columnHelper;
protected XSSFWorkbook workbook;
protected XSSFComments sheetComments;
protected CommentsSource sheetComments;
public static final short LeftMargin = 0;
public static final short RightMargin = 1;
@ -76,7 +73,7 @@ public class XSSFSheet implements Sheet {
public static final short HeaderMargin = 4;
public static final short FooterMargin = 5;
public XSSFSheet(CTSheet sheet, CTWorksheet worksheet, XSSFWorkbook workbook, XSSFComments sheetComments) {
public XSSFSheet(CTSheet sheet, CTWorksheet worksheet, XSSFWorkbook workbook, CommentsSource sheetComments) {
this(sheet, worksheet, workbook);
this.sheetComments = sheetComments;
}
@ -908,18 +905,10 @@ public class XSSFSheet implements Sheet {
this.sheet = sheet;
}
private XSSFComments getComments() {
private CommentsSource getComments() {
if (sheetComments == null) {
sheetComments = new XSSFComments(getCTComments());
sheetComments = new CommentsTable();
}
return sheetComments;
}
private CTComments getCTComments() {
if (comments == null) {
comments = CTComments.Factory.newInstance();
}
return comments;
}
}

View File

@ -15,7 +15,7 @@
limitations under the License.
==================================================================== */
package org.apache.poi.xssf.usermodel.extensions;
package org.apache.poi.xssf.model;
import org.apache.poi.xssf.usermodel.XSSFComment;
import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTComment;
@ -26,7 +26,7 @@ import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTRst;
import junit.framework.TestCase;
public class TestXSSFComments extends TestCase {
public class TestCommentsTable extends TestCase {
private static final String TEST_A2_TEXT = "test A2 text";
private static final String TEST_A1_TEXT = "test A1 text";
@ -34,7 +34,7 @@ public class TestXSSFComments extends TestCase {
public void testfindAuthor() {
CTComments comments = CTComments.Factory.newInstance();
XSSFComments sheetComments = new XSSFComments(comments);
CommentsTable sheetComments = new CommentsTable(comments);
assertEquals(0, sheetComments.findAuthor(TEST_AUTHOR));
assertEquals(1, sheetComments.findAuthor("another author"));
@ -43,7 +43,7 @@ public class TestXSSFComments extends TestCase {
public void testGetCellComment() {
CTComments comments = CTComments.Factory.newInstance();
XSSFComments sheetComments = new XSSFComments(comments);
CommentsTable sheetComments = new CommentsTable(comments);
CTCommentList commentList = comments.addNewCommentList();
// Create 2 comments for A1 and A" cells
@ -69,7 +69,7 @@ public class TestXSSFComments extends TestCase {
public void testSetCellComment() {
CTComments comments = CTComments.Factory.newInstance();
XSSFComments sheetComments = new XSSFComments(comments);
CommentsTable sheetComments = new CommentsTable(comments);
CTCommentList commentList = comments.addNewCommentList();
assertEquals(0, commentList.sizeOfCommentArray());
XSSFComment comment = new XSSFComment(sheetComments);

View File

@ -33,7 +33,7 @@ import org.apache.poi.ss.usermodel.Row;
import org.apache.poi.ss.usermodel.SharedStringSource;
import org.apache.poi.ss.usermodel.Sheet;
import org.apache.poi.ss.usermodel.Workbook;
import org.apache.poi.xssf.usermodel.extensions.XSSFComments;
import org.apache.poi.xssf.model.CommentsTable;
import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTCell;
import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTComment;
import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTComments;
@ -235,7 +235,7 @@ public class TestXSSFCell extends TestCase {
CTSheet ctSheet = CTSheet.Factory.newInstance();
CTWorksheet ctWorksheet = CTWorksheet.Factory.newInstance();
CTComments ctComments = CTComments.Factory.newInstance();
XSSFComments sheetComments = new XSSFComments(ctComments);
CommentsTable sheetComments = new CommentsTable(ctComments);
XSSFSheet sheet = new XSSFSheet(ctSheet, ctWorksheet, workbook, sheetComments);
assertNotNull(sheet);
@ -261,7 +261,7 @@ public class TestXSSFCell extends TestCase {
CTSheet ctSheet = CTSheet.Factory.newInstance();
CTWorksheet ctWorksheet = CTWorksheet.Factory.newInstance();
CTComments ctComments = CTComments.Factory.newInstance();
XSSFComments comments = new XSSFComments(ctComments);
CommentsTable comments = new CommentsTable(ctComments);
XSSFSheet sheet = new XSSFSheet(ctSheet, ctWorksheet, workbook, comments);
assertNotNull(sheet);

View File

@ -19,7 +19,7 @@ package org.apache.poi.xssf.usermodel;
import org.apache.poi.hssf.usermodel.HSSFRichTextString;
import org.apache.poi.ss.usermodel.RichTextString;
import org.apache.poi.xssf.usermodel.extensions.XSSFComments;
import org.apache.poi.xssf.model.CommentsTable;
import org.apache.poi.xssf.util.CellReference;
import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTAuthors;
import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTComment;
@ -34,7 +34,7 @@ public class TestXSSFComment extends TestCase {
private static final String TEST_AUTHOR = "test_author";
public void testConstructors() {
XSSFComments sheetComments = new XSSFComments();
CommentsTable sheetComments = new CommentsTable();
XSSFComment comment = new XSSFComment(sheetComments);
assertNotNull(comment);
@ -44,7 +44,7 @@ public class TestXSSFComment extends TestCase {
}
public void testGetColumn() {
XSSFComments sheetComments = new XSSFComments();
CommentsTable sheetComments = new CommentsTable();
CTComment ctComment = CTComment.Factory.newInstance();
ctComment.setRef("A1");
XSSFComment comment = new XSSFComment(sheetComments, ctComment);
@ -55,7 +55,7 @@ public class TestXSSFComment extends TestCase {
}
public void testGetRow() {
XSSFComments sheetComments = new XSSFComments();
CommentsTable sheetComments = new CommentsTable();
CTComment ctComment = CTComment.Factory.newInstance();
ctComment.setRef("A1");
XSSFComment comment = new XSSFComment(sheetComments, ctComment);
@ -72,14 +72,14 @@ public class TestXSSFComment extends TestCase {
ctAuthors.insertAuthor(0, TEST_AUTHOR);
ctComment.setAuthorId(0);
XSSFComments sheetComments = new XSSFComments(ctComments);
CommentsTable sheetComments = new CommentsTable(ctComments);
XSSFComment comment = new XSSFComment(sheetComments, ctComment);
assertNotNull(comment);
assertEquals(TEST_AUTHOR, comment.getAuthor());
}
public void testSetColumn() {
XSSFComments sheetComments = new XSSFComments();
CommentsTable sheetComments = new CommentsTable();
CTComment ctComment = CTComment.Factory.newInstance();
XSSFComment comment = new XSSFComment(sheetComments, ctComment);
comment.setColumn((short)3);
@ -92,7 +92,7 @@ public class TestXSSFComment extends TestCase {
}
public void testSetRow() {
XSSFComments sheetComments = new XSSFComments();
CommentsTable sheetComments = new CommentsTable();
CTComment ctComment = CTComment.Factory.newInstance();
XSSFComment comment = new XSSFComment(sheetComments, ctComment);
comment.setRow(20);
@ -105,7 +105,7 @@ public class TestXSSFComment extends TestCase {
}
public void testSetAuthor() {
XSSFComments sheetComments = new XSSFComments();
CommentsTable sheetComments = new CommentsTable();
CTComment ctComment = CTComment.Factory.newInstance();
XSSFComment comment = new XSSFComment(sheetComments, ctComment);
comment.setAuthor(TEST_AUTHOR);
@ -113,7 +113,7 @@ public class TestXSSFComment extends TestCase {
}
public void testSetString() {
XSSFComments sheetComments = new XSSFComments();
CommentsTable sheetComments = new CommentsTable();
CTComment ctComment = CTComment.Factory.newInstance();
XSSFComment comment = new XSSFComment(sheetComments, ctComment);
RichTextString richTextString = new HSSFRichTextString(TEST_RICHTEXTSTRING);

View File

@ -23,7 +23,7 @@ import org.apache.poi.ss.usermodel.Cell;
import org.apache.poi.ss.usermodel.Row;
import org.apache.poi.ss.usermodel.Sheet;
import org.apache.poi.ss.usermodel.Workbook;
import org.apache.poi.xssf.usermodel.extensions.XSSFComments;
import org.apache.poi.xssf.model.CommentsTable;
import org.apache.poi.xssf.usermodel.helpers.ColumnHelper;
import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTCol;
import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTComment;
@ -490,7 +490,7 @@ public class TestXSSFSheet extends TestCase {
CTSheet ctSheet = CTSheet.Factory.newInstance();
CTWorksheet ctWorksheet = CTWorksheet.Factory.newInstance();
CTComments ctComments = CTComments.Factory.newInstance();
XSSFComments sheetComments = new XSSFComments(ctComments);
CommentsTable sheetComments = new CommentsTable(ctComments);
XSSFSheet sheet = new XSSFSheet(ctSheet, ctWorksheet, workbook, sheetComments);
assertNotNull(sheet);
@ -509,7 +509,7 @@ public class TestXSSFSheet extends TestCase {
XSSFSheet sheet = new XSSFSheet(ctSheet, ctWorksheet, workbook);
Cell cell = sheet.createRow(0).createCell((short)0);
CTComments ctComments = CTComments.Factory.newInstance();
XSSFComments comments = new XSSFComments(ctComments);
CommentsTable comments = new CommentsTable(ctComments);
XSSFComment comment = comments.addComment();
sheet.setCellComment("A1", comment);