| blob | 28e2374338743d514fa0155552b5c64a04dd59a9 |
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3 ====================================================================
4 Licensed to the Apache Software Foundation (ASF) under one or more
5 contributor license agreements. See the NOTICE file distributed with
6 this work for additional information regarding copyright ownership.
7 The ASF licenses this file to You under the Apache License, Version 2.0
8 (the "License"); you may not use this file except in compliance with
9 the License. You may obtain a copy of the License at
11 http://www.apache.org/licenses/LICENSE-2.0
13 Unless required by applicable law or agreed to in writing, software
14 distributed under the License is distributed on an "AS IS" BASIS,
15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 See the License for the specific language governing permissions and
17 limitations under the License.
18 ====================================================================
19 -->
20 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
22 <document>
23 <header>
24 <title>Busy Developers' Guide to HSSF Features</title>
25 <authors>
26 <person email="user@poi.apache.org" name="Glen Stampoultzis" id="CO"/>
27 <person email="user@poi.apache.org" name="Yegor Kozlov" id="YK"/>
28 </authors>
29 </header>
30 <body>
31 <section><title>Busy Developers' Guide to Features</title>
32 <p>
33 Want to use HSSF read and write spreadsheets in a hurry? This guide is for you. If you're after
34 more in-depth coverage of the HSSF user-API please consult the <link href="how-to.html">HOWTO</link>
35 guide as it contains actual descriptions of how to use this stuff.
36 </p>
37 <section><title>Index of Features</title>
38 <ul>
39 <li><link href="#NewWorkbook">How to create a new workbook</link></li>
40 <li><link href="#NewSheet">How to create a sheet</link></li>
41 <li><link href="#CreateCells">How to create cells</link></li>
42 <li><link href="#CreateDateCells">How to create date cells</link></li>
43 <li><link href="#CellTypes">Working with different types of cells</link></li>
44 <li><link href="#Iterator">Iterate over rows and cells</link></li>
45 <li><link href="#TextExtraction">Text Extraction</link></li>
46 <li><link href="#Alignment">Aligning cells</link></li>
47 <li><link href="#Borders">Working with borders</link></li>
48 <li><link href="#FrillsAndFills">Fills and color</link></li>
49 <li><link href="#MergedCells">Merging cells</link></li>
50 <li><link href="#WorkingWithFonts">Working with fonts</link></li>
51 <li><link href="#CustomColors">Custom colors</link></li>
52 <li><link href="#ReadWriteWorkbook">Reading and writing</link></li>
53 <li><link href="#NewLinesInCells">Use newlines in cells.</link></li>
54 <li><link href="#DataFormats">Create user defined data formats</link></li>
55 <li><link href="#FitTo">Fit Sheet to One Page</link></li>
56 <li><link href="#PrintArea2">Set print area for a sheet</link></li>
57 <li><link href="#FooterPageNumbers">Set page numbers on the footer of a sheet</link></li>
58 <li><link href="#ShiftRows">Shift rows</link></li>
59 <li><link href="#SelectSheet">Set a sheet as selected</link></li>
60 <li><link href="#Zoom">Set the zoom magnification for a sheet</link></li>
61 <li><link href="#Splits">Create split and freeze panes</link></li>
62 <li><link href="#Repeating">Repeating rows and columns</link></li>
63 <li><link href="#HeaderFooter">Headers and Footers</link></li>
64 <li><link href="#DrawingShapes">Drawing Shapes</link></li>
65 <li><link href="#StylingShapes">Styling Shapes</link></li>
66 <li><link href="#Graphics2d">Shapes and Graphics2d</link></li>
67 <li><link href="#Outlining">Outlining</link></li>
68 <li><link href="#Images">Images</link></li>
69 <li><link href="#NamedRanges">Named Ranges and Named Cells</link></li>
70 <li><link href="#CellComments">How to set cell comments</link></li>
71 <li><link href="#Autofit">How to adjust column width to fit the contents</link></li>
72 <li><link href="#Hyperlinks">Hyperlinks</link></li>
73 </ul>
74 </section>
75 <section><title>Features</title>
76 <anchor id="NewWorkbook"/>
77 <section><title>New Workbook</title>
78 <source>
79 HSSFWorkbook wb = new HSSFWorkbook();
80 FileOutputStream fileOut = new FileOutputStream("workbook.xls");
81 wb.write(fileOut);
82 fileOut.close();
83 </source>
84 </section>
85 <anchor id="NewSheet"/>
86 <section><title>New Sheet</title>
87 <source>
88 HSSFWorkbook wb = new HSSFWorkbook();
89 HSSFSheet sheet1 = wb.createSheet("new sheet");
90 HSSFSheet sheet2 = wb.createSheet("second sheet");
91 FileOutputStream fileOut = new FileOutputStream("workbook.xls");
92 wb.write(fileOut);
93 fileOut.close();
94 </source>
95 </section>
96 <anchor id="CreateCells"/>
97 <section><title>Creating Cells</title>
98 <source>
99 HSSFWorkbook wb = new HSSFWorkbook();
100 HSSFSheet sheet = wb.createSheet("new sheet");
102 // Create a row and put some cells in it. Rows are 0 based.
103 HSSFRow row = sheet.createRow((short)0);
104 // Create a cell and put a value in it.
105 HSSFCell cell = row.createCell((short)0);
106 cell.setCellValue(1);
108 // Or do it on one line.
109 row.createCell((short)1).setCellValue(1.2);
110 row.createCell((short)2).setCellValue("This is a string");
111 row.createCell((short)3).setCellValue(true);
113 // Write the output to a file
114 FileOutputStream fileOut = new FileOutputStream("workbook.xls");
115 wb.write(fileOut);
116 fileOut.close();
117 </source>
118 </section>
119 <anchor id="CreateDateCells"/>
120 <section><title>Creating Date Cells</title>
121 <source>
122 HSSFWorkbook wb = new HSSFWorkbook();
123 HSSFSheet sheet = wb.createSheet("new sheet");
125 // Create a row and put some cells in it. Rows are 0 based.
126 HSSFRow row = sheet.createRow((short)0);
128 // Create a cell and put a date value in it. The first cell is not styled
129 // as a date.
130 HSSFCell cell = row.createCell((short)0);
131 cell.setCellValue(new Date());
133 // we style the second cell as a date (and time). It is important to
134 // create a new cell style from the workbook otherwise you can end up
135 // modifying the built in style and effecting not only this cell but other cells.
136 HSSFCellStyle cellStyle = wb.createCellStyle();
137 cellStyle.setDataFormat(HSSFDataFormat.getBuiltinFormat("m/d/yy h:mm"));
138 cell = row.createCell((short)1);
139 cell.setCellValue(new Date());
140 cell.setCellStyle(cellStyle);
142 // Write the output to a file
143 FileOutputStream fileOut = new FileOutputStream("workbook.xls");
144 wb.write(fileOut);
145 fileOut.close();
146 </source>
147 </section>
148 <anchor id="CellTypes"/>
149 <section><title>Working with different types of cells</title>
150 <source>
151 HSSFWorkbook wb = new HSSFWorkbook();
152 HSSFSheet sheet = wb.createSheet("new sheet");
153 HSSFRow row = sheet.createRow((short)2);
154 row.createCell((short) 0).setCellValue(1.1);
155 row.createCell((short) 1).setCellValue(new Date());
156 row.createCell((short) 2).setCellValue("a string");
157 row.createCell((short) 3).setCellValue(true);
158 row.createCell((short) 4).setCellType(HSSFCell.CELL_TYPE_ERROR);
160 // Write the output to a file
161 FileOutputStream fileOut = new FileOutputStream("workbook.xls");
162 wb.write(fileOut);
163 fileOut.close();
164 </source>
165 </section>
166 <anchor id="Alignment"/>
167 <section><title>Demonstrates various alignment options</title>
168 <source>
169 public static void main(String[] args)
170 throws IOException
171 {
172 HSSFWorkbook wb = new HSSFWorkbook();
173 HSSFSheet sheet = wb.createSheet("new sheet");
174 HSSFRow row = sheet.createRow((short) 2);
175 createCell(wb, row, (short) 0, HSSFCellStyle.ALIGN_CENTER);
176 createCell(wb, row, (short) 1, HSSFCellStyle.ALIGN_CENTER_SELECTION);
177 createCell(wb, row, (short) 2, HSSFCellStyle.ALIGN_FILL);
178 createCell(wb, row, (short) 3, HSSFCellStyle.ALIGN_GENERAL);
179 createCell(wb, row, (short) 4, HSSFCellStyle.ALIGN_JUSTIFY);
180 createCell(wb, row, (short) 5, HSSFCellStyle.ALIGN_LEFT);
181 createCell(wb, row, (short) 6, HSSFCellStyle.ALIGN_RIGHT);
183 // Write the output to a file
184 FileOutputStream fileOut = new FileOutputStream("workbook.xls");
185 wb.write(fileOut);
186 fileOut.close();
188 }
190 /**
191 * Creates a cell and aligns it a certain way.
192 *
193 * @param wb the workbook
194 * @param row the row to create the cell in
195 * @param column the column number to create the cell in
196 * @param align the alignment for the cell.
197 */
198 private static void createCell(HSSFWorkbook wb, HSSFRow row, short column, short align)
199 {
200 HSSFCell cell = row.createCell(column);
201 cell.setCellValue("Align It");
202 HSSFCellStyle cellStyle = wb.createCellStyle();
203 cellStyle.setAlignment(align);
204 cell.setCellStyle(cellStyle);
205 }
206 </source>
207 </section>
208 <anchor id="Borders"/>
209 <section><title>Working with borders</title>
210 <source>
211 HSSFWorkbook wb = new HSSFWorkbook();
212 HSSFSheet sheet = wb.createSheet("new sheet");
214 // Create a row and put some cells in it. Rows are 0 based.
215 HSSFRow row = sheet.createRow((short) 1);
217 // Create a cell and put a value in it.
218 HSSFCell cell = row.createCell((short) 1);
219 cell.setCellValue(4);
221 // Style the cell with borders all around.
222 HSSFCellStyle style = wb.createCellStyle();
223 style.setBorderBottom(HSSFCellStyle.BORDER_THIN);
224 style.setBottomBorderColor(HSSFColor.BLACK.index);
225 style.setBorderLeft(HSSFCellStyle.BORDER_THIN);
226 style.setLeftBorderColor(HSSFColor.GREEN.index);
227 style.setBorderRight(HSSFCellStyle.BORDER_THIN);
228 style.setRightBorderColor(HSSFColor.BLUE.index);
229 style.setBorderTop(HSSFCellStyle.BORDER_MEDIUM_DASHED);
230 style.setTopBorderColor(HSSFColor.BLACK.index);
231 cell.setCellStyle(style);
233 // Write the output to a file
234 FileOutputStream fileOut = new FileOutputStream("workbook.xls");
235 wb.write(fileOut);
236 fileOut.close();
237 </source>
238 </section>
239 <anchor id="Iterator"/>
240 <section><title>Iterate over rows and cells</title>
241 <p>Sometimes, you'd like to just iterate over all the rows in
242 a sheet, or all the cells in a row. This is possible with
243 a simple for loop.</p>
244 <p>Luckily, this is very easy. HSSFRow defines a
245 <em>CellIterator</em> inner class to handle iterating over
246 the cells (get one with a call to <em>row.cellIterator()</em>),
247 and HSSFSheet provides a <em>rowIterator()</em> method to
248 give an iterator over all the rows.</p>
249 <p>(Unfortunately, due to the broken and
250 backwards-incompatible way that Java 5 foreach loops were
251 implemented, it isn't possible to use them on a codebase
252 that supports Java 1.4, as POI does)</p>
253 <source>
254 HSSFSheet sheet = wb.getSheetAt(0);
255 for (Iterator rit = sheet.rowIterator(); rit.hasNext(); ) {
256 HSSFRow row = (HSSFRow)rit.next();
257 for (Iterator cit = row.cellIterator(); cit.hasNext(); ) {
258 HSSFCell cell = (HSSFCell)cit.next();
259 // Do something here
260 }
261 }
262 </source>
263 <source>
264 HSSFSheet sheet = wb.getSheetAt(0);
265 for (Iterator<HSSFRow> rit = (Iterator<HSSFRow>)sheet.rowIterator(); rit.hasNext(); ) {
266 HSSFRow row = rit.next();
267 for (Iterator<HSSFCell> cit = (Iterator<HSSFCell>)row.cellIterator(); cit.hasNext(); ) {
268 HSSFCell cell = cit.next();
269 // Do something here
270 }
271 }
272 </source>
273 </section>
274 <section><title>Iterate over rows and cells using Java 1.5 foreach loops - OOXML Branch Only</title>
275 <p>Sometimes, you'd like to just iterate over all the rows in
276 a sheet, or all the cells in a row. If you are using Java
277 5 or later, then this is especially handy, as it'll allow the
278 new foreach loop support to work.</p>
279 <p>Luckily, this is very easy. Both HSSFSheet and HSSFRow
280 implement <em>java.lang.Iterable</em> to allow foreach
281 loops. For HSSFRow this allows access to the
282 <em>CellIterator</em> inner class to handle iterating over
283 the cells, and for HSSFSheet gives the
284 <em>rowIterator()</em> to iterator over all the rows.</p>
285 <source>
286 HSSFSheet sheet = wb.getSheetAt(0);
287 for (HSSFRow row : sheet.rowIterator()) {
288 for (HSSFCell cell : row.cellIterator()) {
289 // Do something here
290 }
291 }
292 </source>
293 <note>This only works on the OOXML branch of POI</note>
294 </section>
295 <anchor id="TextExtraction"/>
296 <section><title>Text Extraction</title>
297 <p>For most text extraction requirements, the standard
298 ExcelExtractor class should provide all you need.</p>
299 <source>
300 InputStream inp = new FileInputStream("workbook.xls");
301 HSSFWorkbook wb = new HSSFWorkbook(new POIFSFileSystem(inp));
302 ExcelExtractor extractor = new ExcelExtractor(wb);
304 extractor.setFormulasNotResults(true);
305 extractor.setIncludeSheetNames(false);
306 String text = extractor.getText();
307 </source>
308 <p>For very fancy text extraction, XLS to CSV etc,
309 take a look at
310 <em>/src/scratchpad/examples/src/org/apache/poi/hssf/eventusermodel/examples/XLS2CSVmra.java</em>
311 </p>
312 </section>
313 <anchor id="FillsAndFrills"/>
314 <section><title>Fills and colors</title>
315 <source>
316 HSSFWorkbook wb = new HSSFWorkbook();
317 HSSFSheet sheet = wb.createSheet("new sheet");
319 // Create a row and put some cells in it. Rows are 0 based.
320 HSSFRow row = sheet.createRow((short) 1);
322 // Aqua background
323 HSSFCellStyle style = wb.createCellStyle();
324 style.setFillBackgroundColor(HSSFColor.AQUA.index);
325 style.setFillPattern(HSSFCellStyle.BIG_SPOTS);
326 HSSFCell cell = row.createCell((short) 1);
327 cell.setCellValue("X");
328 cell.setCellStyle(style);
330 // Orange "foreground", foreground being the fill foreground not the font color.
331 style = wb.createCellStyle();
332 style.setFillForegroundColor(HSSFColor.ORANGE.index);
333 style.setFillPattern(HSSFCellStyle.SOLID_FOREGROUND);
334 cell = row.createCell((short) 2);
335 cell.setCellValue("X");
336 cell.setCellStyle(style);
338 // Write the output to a file
339 FileOutputStream fileOut = new FileOutputStream("workbook.xls");
340 wb.write(fileOut);
341 fileOut.close();
342 </source>
343 </section>
344 <anchor id="MergedCells"/>
345 <section><title>Merging cells</title>
346 <source>
347 HSSFWorkbook wb = new HSSFWorkbook();
348 HSSFSheet sheet = wb.createSheet("new sheet");
350 HSSFRow row = sheet.createRow((short) 1);
351 HSSFCell cell = row.createCell((short) 1);
352 cell.setCellValue("This is a test of merging");
354 sheet.addMergedRegion(new Region(1,(short)1,1,(short)2));
356 // Write the output to a file
357 FileOutputStream fileOut = new FileOutputStream("workbook.xls");
358 wb.write(fileOut);
359 fileOut.close();
360 </source>
361 </section>
362 <anchor id="WorkingWithFonts"/>
363 <section><title>Working with fonts</title>
364 <source>
365 HSSFWorkbook wb = new HSSFWorkbook();
366 HSSFSheet sheet = wb.createSheet("new sheet");
368 // Create a row and put some cells in it. Rows are 0 based.
369 HSSFRow row = sheet.createRow((short) 1);
371 // Create a new font and alter it.
372 HSSFFont font = wb.createFont();
373 font.setFontHeightInPoints((short)24);
374 font.setFontName("Courier New");
375 font.setItalic(true);
376 font.setStrikeout(true);
378 // Fonts are set into a style so create a new one to use.
379 HSSFCellStyle style = wb.createCellStyle();
380 style.setFont(font);
382 // Create a cell and put a value in it.
383 HSSFCell cell = row.createCell((short) 1);
384 cell.setCellValue("This is a test of fonts");
385 cell.setCellStyle(style);
387 // Write the output to a file
388 FileOutputStream fileOut = new FileOutputStream("workbook.xls");
389 wb.write(fileOut);
390 fileOut.close();
391 </source>
392 <p>
393 Note, the maximum number of unique fonts in a workbook is limited to 32767 (
394 the maximum positive short). You should re-use fonts in your apllications instead of
395 creating a font for each cell.
396 Examples:
397 </p>
398 <p><strong>Wrong:</strong></p>
399 <source>
400 for (int i = 0; i < 10000; i++) {
401 HSSFRow row = sheet.createRow(i);
402 HSSFCell cell = row.createCell((short) 0);
404 HSSFCellStyle style = workbook.createCellStyle();
405 HSSFFont font = workbook.createFont();
406 font.setBoldweight(HSSFFont.BOLDWEIGHT_BOLD);
407 style.setFont(font);
408 cell.setCellStyle(style);
409 }
410 </source>
411 <p><strong>Correct:</strong></p>
412 <source>
414 HSSFCellStyle style = workbook.createCellStyle();
415 HSSFFont font = workbook.createFont();
416 font.setBoldweight(HSSFFont.BOLDWEIGHT_BOLD);
417 style.setFont(font);
418 for (int i = 0; i < 10000; i++) {
419 HSSFRow row = sheet.createRow(i);
420 HSSFCell cell = row.createCell((short) 0);
421 cell.setCellStyle(style);
422 }
423 </source>
425 </section>
426 <anchor id="CustomColors"/>
427 <section><title>Custom colors</title>
428 <source>
429 HSSFWorkbook wb = new HSSFWorkbook();
430 HSSFSheet sheet = wb.createSheet();
431 HSSFRow row = sheet.createRow((short) 0);
432 HSSFCell cell = row.createCell((short) 0);
433 cell.setCellValue("Default Palette");
435 //apply some colors from the standard palette,
436 // as in the previous examples.
437 //we'll use red text on a lime background
439 HSSFCellStyle style = wb.createCellStyle();
440 style.setFillForegroundColor(HSSFColor.LIME.index);
441 style.setFillPattern(HSSFCellStyle.SOLID_FOREGROUND);
443 HSSFFont font = wb.createFont();
444 font.setColor(HSSFColor.RED.index);
445 style.setFont(font);
447 cell.setCellStyle(style);
449 //save with the default palette
450 FileOutputStream out = new FileOutputStream("default_palette.xls");
451 wb.write(out);
452 out.close();
454 //now, let's replace RED and LIME in the palette
455 // with a more attractive combination
456 // (lovingly borrowed from freebsd.org)
458 cell.setCellValue("Modified Palette");
460 //creating a custom palette for the workbook
461 HSSFPalette palette = wb.getCustomPalette();
463 //replacing the standard red with freebsd.org red
464 palette.setColorAtIndex(HSSFColor.RED.index,
465 (byte) 153, //RGB red (0-255)
466 (byte) 0, //RGB green
467 (byte) 0 //RGB blue
468 );
469 //replacing lime with freebsd.org gold
470 palette.setColorAtIndex(HSSFColor.LIME.index, (byte) 255, (byte) 204, (byte) 102);
472 //save with the modified palette
473 // note that wherever we have previously used RED or LIME, the
474 // new colors magically appear
475 out = new FileOutputStream("modified_palette.xls");
476 wb.write(out);
477 out.close();
478 </source>
479 </section>
480 <anchor id="ReadWriteWorkbook"/>
481 <section><title>Reading and Rewriting Workbooks</title>
482 <source>
483 POIFSFileSystem fs =
484 new POIFSFileSystem(new FileInputStream("workbook.xls"));
485 HSSFWorkbook wb = new HSSFWorkbook(fs);
486 HSSFSheet sheet = wb.getSheetAt(0);
487 HSSFRow row = sheet.getRow(2);
488 HSSFCell cell = row.getCell((short)3);
489 if (cell == null)
490 cell = row.createCell((short)3);
491 cell.setCellType(HSSFCell.CELL_TYPE_STRING);
492 cell.setCellValue("a test");
494 // Write the output to a file
495 FileOutputStream fileOut = new FileOutputStream("workbook.xls");
496 wb.write(fileOut);
497 fileOut.close();
498 </source>
499 </section>
500 <anchor id="NewLinesInCells"/>
501 <section><title>Using newlines in cells</title>
502 <source>
503 HSSFWorkbook wb = new HSSFWorkbook();
504 HSSFSheet s = wb.createSheet();
505 HSSFRow r = null;
506 HSSFCell c = null;
507 HSSFCellStyle cs = wb.createCellStyle();
508 HSSFFont f = wb.createFont();
509 HSSFFont f2 = wb.createFont();
511 cs = wb.createCellStyle();
513 cs.setFont( f2 );
514 //Word Wrap MUST be turned on
515 cs.setWrapText( true );
517 r = s.createRow( (short) 2 );
518 r.setHeight( (short) 0x349 );
519 c = r.createCell( (short) 2 );
520 c.setCellType( HSSFCell.CELL_TYPE_STRING );
521 c.setCellValue( "Use \n with word wrap on to create a new line" );
522 c.setCellStyle( cs );
523 s.setColumnWidth( (short) 2, (short) ( ( 50 * 8 ) / ( (double) 1 / 20 ) ) );
525 FileOutputStream fileOut = new FileOutputStream( "workbook.xls" );
526 wb.write( fileOut );
527 fileOut.close();</source>
528 </section>
529 <anchor id="DataFormats"/>
530 <section><title>Data Formats</title>
531 <source>
532 HSSFWorkbook wb = new HSSFWorkbook();
533 HSSFSheet sheet = wb.createSheet("format sheet");
534 HSSFCellStyle style;
535 HSSFDataFormat format = wb.createDataFormat();
536 HSSFRow row;
537 HSSFCell cell;
538 short rowNum = 0;
539 short colNum = 0;
541 row = sheet.createRow(rowNum++);
542 cell = row.createCell(colNum);
543 cell.setCellValue(11111.25);
544 style = wb.createCellStyle();
545 style.setDataFormat(format.getFormat("0.0"));
546 cell.setCellStyle(style);
548 row = sheet.createRow(rowNum++);
549 cell = row.createCell(colNum);
550 cell.setCellValue(11111.25);
551 style = wb.createCellStyle();
552 style.setDataFormat(format.getFormat("#,##0.0000"));
553 cell.setCellStyle(style);
555 FileOutputStream fileOut = new FileOutputStream("workbook.xls");
556 wb.write(fileOut);
557 fileOut.close();
558 </source>
559 </section>
560 <anchor id="FitTo"/>
561 <section><title>Fit Sheet to One Page</title>
562 <source>
563 HSSFWorkbook wb = new HSSFWorkbook();
564 HSSFSheet sheet = wb.createSheet("format sheet");
565 HSSFPrintSetup ps = sheet.getPrintSetup();
567 sheet.setAutobreaks(true);
569 ps.setFitHeight((short)1);
570 ps.setFitWidth((short)1);
573 // Create various cells and rows for spreadsheet.
575 FileOutputStream fileOut = new FileOutputStream("workbook.xls");
576 wb.write(fileOut);
577 fileOut.close();
578 </source>
579 </section>
580 <anchor id="PrintArea2"/>
581 <section><title>Set Print Area</title>
582 <source>
583 HSSFWorkbook wb = new HSSFWorkbook();
584 HSSFSheet sheet = wb.createSheet("Sheet1");
585 wb.setPrintArea(0, "$A$1:$C$2");
586 //sets the print area for the first sheet
587 //Alternatively:
588 //wb.setPrintArea(0, 0, 1, 0, 0) is equivalent to using the name reference (See the JavaDocs for more details)
590 // Create various cells and rows for spreadsheet.
592 FileOutputStream fileOut = new FileOutputStream("workbook.xls");
593 wb.write(fileOut);
594 fileOut.close();
597 </source>
598 </section>
600 <anchor id="FooterPageNumbers"/>
601 <section><title>Set Page Numbers on Footer</title>
602 <source>
603 HSSFWorkbook wb = new HSSFWorkbook();
604 HSSFSheet sheet = wb.createSheet("format sheet");
605 HSSFFooter footer = sheet.getFooter()
607 footer.setRight( "Page " + HSSFFooter.page() + " of " + HSSFFooter.numPages() );
611 // Create various cells and rows for spreadsheet.
613 FileOutputStream fileOut = new FileOutputStream("workbook.xls");
614 wb.write(fileOut);
615 fileOut.close();
616 </source>
617 </section>
619 <anchor id="ConvenienceFunctions"/>
620 <section><title>Using the Convenience Functions</title>
621 <p>
622 The convenience functions live in contrib and provide
623 utility features such as setting borders around merged
624 regions and changing style attributes without explicitly
625 creating new styles.
626 </p>
627 <source>
628 HSSFWorkbook wb = new HSSFWorkbook();
629 HSSFSheet sheet1 = wb.createSheet( "new sheet" );
631 // Create a merged region
632 HSSFRow row = sheet1.createRow( (short) 1 );
633 HSSFRow row2 = sheet1.createRow( (short) 2 );
634 HSSFCell cell = row.createCell( (short) 1 );
635 cell.setCellValue( "This is a test of merging" );
636 Region region = new Region( 1, (short) 1, 4, (short) 4 );
637 sheet1.addMergedRegion( region );
639 // Set the border and border colors.
640 final short borderMediumDashed = HSSFCellStyle.BORDER_MEDIUM_DASHED;
641 HSSFRegionUtil.setBorderBottom( borderMediumDashed,
642 region, sheet1, wb );
643 HSSFRegionUtil.setBorderTop( borderMediumDashed,
644 region, sheet1, wb );
645 HSSFRegionUtil.setBorderLeft( borderMediumDashed,
646 region, sheet1, wb );
647 HSSFRegionUtil.setBorderRight( borderMediumDashed,
648 region, sheet1, wb );
649 HSSFRegionUtil.setBottomBorderColor(HSSFColor.AQUA.index, region, sheet1, wb);
650 HSSFRegionUtil.setTopBorderColor(HSSFColor.AQUA.index, region, sheet1, wb);
651 HSSFRegionUtil.setLeftBorderColor(HSSFColor.AQUA.index, region, sheet1, wb);
652 HSSFRegionUtil.setRightBorderColor(HSSFColor.AQUA.index, region, sheet1, wb);
654 // Shows some usages of HSSFCellUtil
655 HSSFCellStyle style = wb.createCellStyle();
656 style.setIndention((short)4);
657 HSSFCellUtil.createCell(row, 8, "This is the value of the cell", style);
658 HSSFCell cell2 = HSSFCellUtil.createCell( row2, 8, "This is the value of the cell");
659 HSSFCellUtil.setAlignment(cell2, wb, HSSFCellStyle.ALIGN_CENTER);
661 // Write out the workbook
662 FileOutputStream fileOut = new FileOutputStream( "workbook.xls" );
663 wb.write( fileOut );
664 fileOut.close();
665 </source>
666 </section>
668 <anchor id="ShiftRows"/>
669 <section><title>Shift rows up or down on a sheet</title>
670 <source>
671 HSSFWorkbook wb = new HSSFWorkbook();
672 HSSFSheet sheet = wb.createSheet("row sheet");
674 // Create various cells and rows for spreadsheet.
676 // Shift rows 6 - 11 on the spreadsheet to the top (rows 0 - 5)
677 sheet.shiftRows(5, 10, -5);
679 FileOutputStream fileOut = new FileOutputStream("workbook.xls");
680 wb.write(fileOut);
681 fileOut.close();
682 </source>
683 </section>
685 <anchor id="SelectSheet"/>
686 <section><title>Set a sheet as selected</title>
687 <source>
688 HSSFWorkbook wb = new HSSFWorkbook();
689 HSSFSheet sheet = wb.createSheet("row sheet");
690 sheet.setSelected(true);
692 // Create various cells and rows for spreadsheet.
694 FileOutputStream fileOut = new FileOutputStream("workbook.xls");
695 wb.write(fileOut);
696 fileOut.close();
697 </source>
698 </section>
700 <anchor id="Zoom"/>
701 <section><title>Set the zoom magnification</title>
702 <p>
703 The zoom is expressed as a fraction. For example to
704 express a zoom of 75% use 3 for the numerator and
705 4 for the denominator.
706 </p>
707 <source>
708 HSSFWorkbook wb = new HSSFWorkbook();
709 HSSFSheet sheet1 = wb.createSheet("new sheet");
710 sheet1.setZoom(3,4); // 75 percent magnification
711 FileOutputStream fileOut = new FileOutputStream("workbook.xls");
712 wb.write(fileOut);
713 fileOut.close();
714 </source>
715 </section>
717 <anchor id="Splits"/>
718 <section><title>Splits and freeze panes</title>
719 <p>
720 There are two types of panes you can create; freeze panes and split panes.
721 </p>
722 <p>
723 A freeze pane is split by columns and rows. You create
724 a freeze pane using the following mechanism:
725 </p>
726 <p>
727 sheet1.createFreezePane( 3, 2, 3, 2 );
728 </p>
729 <p>
730 The first two parameters are the columns and rows you
731 wish to split by. The second two parameters indicate
732 the cells that are visible in the bottom right quadrant.
733 </p>
734 <p>
736 Split pains appear differently. The split area is
737 divided into four separate work area's. The split
738 occurs at the pixel level and the user is able to
739 adjust the split by dragging it to a new position.
740 </p>
741 <p>
743 Split panes are created with the following call:
744 </p>
745 <p>
746 sheet2.createSplitPane( 2000, 2000, 0, 0, HSSFSheet.PANE_LOWER_LEFT );
747 </p>
748 <p>
750 The first parameter is the x position of the split.
751 This is in 1/20th of a point. A point in this case
752 seems to equate to a pixel. The second parameter is
753 the y position of the split. Again in 1/20th of a point.
754 </p>
755 <p>
756 The last parameter indicates which pane currently has
757 the focus. This will be one of HSSFSheet.PANE_LOWER_LEFT,
758 PANE_LOWER_RIGHT, PANE_UPPER_RIGHT or PANE_UPPER_LEFT.
759 </p>
760 <source>
761 HSSFWorkbook wb = new HSSFWorkbook();
762 HSSFSheet sheet1 = wb.createSheet("new sheet");
763 HSSFSheet sheet2 = wb.createSheet("second sheet");
764 HSSFSheet sheet3 = wb.createSheet("third sheet");
765 HSSFSheet sheet4 = wb.createSheet("fourth sheet");
767 // Freeze just one row
768 sheet1.createFreezePane( 0, 1, 0, 1 );
769 // Freeze just one column
770 sheet2.createFreezePane( 1, 0, 1, 0 );
771 // Freeze the columns and rows (forget about scrolling position of the lower right quadrant).
772 sheet3.createFreezePane( 2, 2 );
773 // Create a split with the lower left side being the active quadrant
774 sheet4.createSplitPane( 2000, 2000, 0, 0, HSSFSheet.PANE_LOWER_LEFT );
776 FileOutputStream fileOut = new FileOutputStream("workbook.xls");
777 wb.write(fileOut);
778 fileOut.close();
779 </source>
780 </section>
782 <anchor id="Repeating"/>
783 <section><title>Repeating rows and columns</title>
784 <p>
785 It's possible to set up repeating rows and columns in
786 your printouts by using the setRepeatingRowsAndColumns()
787 function in the HSSFWorkbook class.
788 </p>
789 <p>
790 This function Contains 5 parameters.
791 The first parameter is the index to the sheet (0 = first sheet).
792 The second and third parameters specify the range for the columns to repreat.
793 To stop the columns from repeating pass in -1 as the start and end column.
794 The fourth and fifth parameters specify the range for the rows to repeat.
795 To stop the columns from repeating pass in -1 as the start and end rows.
796 </p>
797 <source>
798 HSSFWorkbook wb = new HSSFWorkbook();
799 HSSFSheet sheet1 = wb.createSheet("new sheet");
800 HSSFSheet sheet2 = wb.createSheet("second sheet");
802 // Set the columns to repeat from column 0 to 2 on the first sheet
803 wb.setRepeatingRowsAndColumns(0,0,2,-1,-1);
804 // Set the the repeating rows and columns on the second sheet.
805 wb.setRepeatingRowsAndColumns(1,4,5,1,2);
807 FileOutputStream fileOut = new FileOutputStream("workbook.xls");
808 wb.write(fileOut);
809 fileOut.close();
810 </source>
811 </section>
812 <anchor id="HeaderFooter"/>
813 <section><title>Headers and Footers</title>
814 <p>
815 Example is for headers but applies directly to footers.
816 </p>
817 <source>
818 HSSFWorkbook wb = new HSSFWorkbook();
819 HSSFSheet sheet = wb.createSheet("new sheet");
821 HSSFHeader header = sheet.getHeader();
822 header.setCenter("Center Header");
823 header.setLeft("Left Header");
824 header.setRight(HSSFHeader.font("Stencil-Normal", "Italic") +
825 HSSFHeader.fontSize((short) 16) + "Right w/ Stencil-Normal Italic font and size 16");
827 FileOutputStream fileOut = new FileOutputStream("workbook.xls");
828 wb.write(fileOut);
829 fileOut.close();
830 </source>
831 </section>
833 <anchor id="DrawingShapes"/>
834 <section><title>Drawing Shapes</title>
835 <p>
836 POI supports drawing shapes using the Microsoft Office
837 drawing tools. Shapes on a sheet are organized in a
838 hiearchy of groups and and shapes. The top-most shape
839 is the patriarch. This is not visisble on the sheet
840 at all. To start drawing you need to call <code>createPatriarch</code>
841 on the <code>HSSFSheet</code> class. This has the
842 effect erasing any other shape information stored
843 in that sheet. By default POI will leave shape
844 records alone in the sheet unless you make a call to
845 this method.
846 </p>
847 <p>
848 To create a shape you have to go through the following
849 steps:
850 </p>
851 <ol>
852 <li>Create the patriarch.</li>
853 <li>Create an anchor to position the shape on the sheet.</li>
854 <li>Ask the patriarch to create the shape.</li>
855 <li>Set the shape type (line, oval, rectangle etc...)</li>
856 <li>Set any other style details converning the shape. (eg:
857 line thickness, etc...)</li>
858 </ol>
859 <source>
860 HSSFPatriarch patriarch = sheet.createDrawingPatriarch();
861 a = new HSSFClientAnchor( 0, 0, 1023, 255, (short) 1, 0, (short) 1, 0 );
862 HSSFSimpleShape shape1 = patriarch.createSimpleShape(a1);
863 shape1.setShapeType(HSSFSimpleShape.OBJECT_TYPE_LINE);
864 </source>
865 <p>
866 Text boxes are created using a different call:
867 </p>
868 <source>
869 HSSFTextbox textbox1 = patriarch.createTextbox(
870 new HSSFClientAnchor(0,0,0,0,(short)1,1,(short)2,2));
871 textbox1.setString(new HSSFRichTextString("This is a test") );
872 </source>
873 <p>
874 It's possible to use different fonts to style parts of
875 the text in the textbox. Here's how:
876 </p>
877 <source>
878 HSSFFont font = wb.createFont();
879 font.setItalic(true);
880 font.setUnderline(HSSFFont.U_DOUBLE);
881 HSSFRichTextString string = new HSSFRichTextString("Woo!!!");
882 string.applyFont(2,5,font);
883 textbox.setString(string );
884 </source>
885 <p>
886 Just as can be done manually using Excel, it is possible
887 to group shapes together. This is done by calling
888 <code>createGroup()</code> and then creating the shapes
889 using those groups.
890 </p>
891 <p>
892 It's also possible to create groups within groups.
893 </p>
894 <warning>Any group you create should contain at least two
895 other shapes or subgroups.</warning>
896 <p>
897 Here's how to create a shape group:
898 </p>
899 <source>
900 // Create a shape group.
901 HSSFShapeGroup group = patriarch.createGroup(
902 new HSSFClientAnchor(0,0,900,200,(short)2,2,(short)2,2));
904 // Create a couple of lines in the group.
905 HSSFSimpleShape shape1 = group.createShape(new HSSFChildAnchor(3,3,500,500));
906 shape1.setShapeType(HSSFSimpleShape.OBJECT_TYPE_LINE);
907 ( (HSSFChildAnchor) shape1.getAnchor() ).setAnchor((short)3,3,500,500);
908 HSSFSimpleShape shape2 = group.createShape(new HSSFChildAnchor((short)1,200,400,600));
909 shape2.setShapeType(HSSFSimpleShape.OBJECT_TYPE_LINE);
910 </source>
911 <p>
912 If you're being observant you'll noticed that the shapes
913 that are added to the group use a new type of anchor:
914 the <code>HSSFChildAnchor</code>. What happens is that
915 the created group has it's own coordinate space for
916 shapes that are placed into it. POI defaults this to
917 (0,0,1023,255) but you are able to change it as desired.
918 Here's how:
919 </p>
920 <source>
921 myGroup.setCoordinates(10,10,20,20); // top-left, bottom-right
922 </source>
923 <p>
924 If you create a group within a group it's also going
925 to have it's own coordinate space.
926 </p>
927 </section>
929 <anchor id="StylingShapes"/>
930 <section><title>Styling Shapes</title>
931 <p>
932 By default shapes can look a little plain. It's possible
933 to apply different styles to the shapes however. The
934 sorts of things that can currently be done are:
935 </p>
936 <ul>
937 <li>Change the fill color.</li>
938 <li>Make a shape with no fill color.</li>
939 <li>Change the thickness of the lines.</li>
940 <li>Change the style of the lines. Eg: dashed, dotted.</li>
941 <li>Change the line color.</li>
942 </ul>
943 <p>
944 Here's an examples of how this is done:
945 </p>
946 <source>
947 HSSFSimpleShape s = patriarch.createSimpleShape(a);
948 s.setShapeType(HSSFSimpleShape.OBJECT_TYPE_OVAL);
949 s.setLineStyleColor(10,10,10);
950 s.setFillColor(90,10,200);
951 s.setLineWidth(HSSFShape.LINEWIDTH_ONE_PT * 3);
952 s.setLineStyle(HSSFShape.LINESTYLE_DOTSYS);
953 </source>
954 </section>
955 <anchor id="Graphics2d"/>
956 <section><title>Shapes and Graphics2d</title>
957 <p>
958 While the native POI shape drawing commands are the
959 recommended way to draw shapes in a shape it's sometimes
960 desirable to use a standard API for compatibility with
961 external libraries. With this in mind we created some
962 wrappers for <code>Graphics</code> and <code>Graphics2d</code>.
963 </p>
964 <warning>
965 It's important to not however before continuing that
966 <code>Graphics2d</code> is a poor match to the capabilities
967 of the Microsoft Office drawing commands. The older
968 <code>Graphics</code> class offers a closer match but is
969 still a square peg in a round hole.
970 </warning>
971 <p>
972 All Graphics commands are issued into an <code>HSSFShapeGroup</code>.
973 Here's how it's done:
974 </p>
975 <source>
976 a = new HSSFClientAnchor( 0, 0, 1023, 255, (short) 1, 0, (short) 1, 0 );
977 group = patriarch.createGroup( a );
978 group.setCoordinates( 0, 0, 80 * 4 , 12 * 23 );
979 float verticalPointsPerPixel = a.getAnchorHeightInPoints(sheet) / (float)Math.abs(group.getY2() - group.getY1());
980 g = new EscherGraphics( group, wb, Color.black, verticalPointsPerPixel );
981 g2d = new EscherGraphics2d( g );
982 drawChemicalStructure( g2d );
983 </source>
984 <p>
985 The first thing we do is create the group and set it's coordinates
986 to match what we plan to draw. Next we calculate a reasonable
987 fontSizeMultipler then create the EscherGraphics object.
988 Since what we really want is a <code>Graphics2d</code>
989 object we create an EscherGraphics2d object and pass in
990 the graphics object we created. Finally we call a routine
991 that draws into the EscherGraphics2d object.
992 </p>
993 <p>
994 The vertical points per pixel deserves some more explanation.
995 One of the difficulties in converting Graphics calls
996 into escher drawing calls is that Excel does not have
997 the concept of absolute pixel positions. It measures
998 it's cell widths in 'characters' and the cell heights in points.
999 Unfortunately it's not defined exactly what type of character it's
1000 measuring. Presumably this is due to the fact that the Excel will be
1001 using different fonts on different platforms or even within the same
1002 platform.
1003 </p>
1004 <p>
1005 Because of this constraint we've had to implement the concept of a
1006 verticalPointsPerPixel. This the amount the font should be scaled by when
1007 you issue commands such as drawString(). To calculate this value
1008 use the follow formula:
1009 </p>
1010 <source>
1011 multipler = groupHeightInPoints / heightOfGroup
1012 </source>
1013 <p>
1014 The height of the group is calculated fairly simply by calculating the
1015 difference between the y coordinates of the bounding box of the shape. The
1016 height of the group can be calculated by using a convenience called
1017 <code>HSSFClientAnchor.getAnchorHeightInPoints()</code>.
1018 </p>
1019 <p>
1020 Many of the functions supported by the graphics classes
1021 are not complete. Here's some of the functions that are known
1022 to work.
1023 </p>
1024 <ul>
1025 <li>fillRect()</li>
1026 <li>fillOval()</li>
1027 <li>drawString()</li>
1028 <li>drawOval()</li>
1029 <li>drawLine()</li>
1030 <li>clearRect()</li>
1031 </ul>
1032 <p>
1033 Functions that are not supported will return and log a message
1034 using the POI logging infrastructure (disabled by default).
1035 </p>
1036 </section>
1037 <anchor id="Outlining"/>
1038 <section>
1039 <title>Outlining</title>
1040 <p>
1041 Outlines are great for grouping sections of information
1042 together and can be added easily to columns and rows
1043 using the POI API. Here's how:
1044 </p>
1045 <source>
1046 HSSFWorkbook wb = new HSSFWorkbook();
1047 HSSFSheet sheet1 = wb.createSheet("new sheet");
1049 sheet1.groupRow( 5, 14 );
1050 sheet1.groupRow( 7, 14 );
1051 sheet1.groupRow( 16, 19 );
1053 sheet1.groupColumn( (short)4, (short)7 );
1054 sheet1.groupColumn( (short)9, (short)12 );
1055 sheet1.groupColumn( (short)10, (short)11 );
1057 FileOutputStream fileOut = new FileOutputStream(filename);
1058 wb.write(fileOut);
1059 fileOut.close();
1060 </source>
1061 <p>
1062 To collapse (or expand) an outline use the following calls:
1063 </p>
1064 <source>
1065 sheet1.setRowGroupCollapsed( 7, true );
1066 sheet1.setColumnGroupCollapsed( (short)4, true );
1067 </source>
1068 <p>
1069 The row/column you choose should contain an already
1070 created group. It can be anywhere within the group.
1071 </p>
1072 </section>
1073 </section>
1074 </section>
1075 <anchor id="Images"/>
1076 <section>
1077 <title>Images</title>
1078 <p>
1079 Images are part of the drawing support. To add an image just
1080 call <code>createPicture()</code> on the drawing patriarch.
1081 At the time of writing the following types are supported:
1082 </p>
1083 <ul>
1084 <li>PNG</li>
1085 <li>JPG</li>
1086 <li>DIB</li>
1087 </ul>
1088 <p>
1089 It should be noted that any existing drawings may be erased
1090 once you add a image to a sheet.
1091 </p>
1092 <source>
1093 // Create the drawing patriarch. This is the top level container for
1094 // all shapes. This will clear out any existing shapes for that sheet.
1095 HSSFPatriarch patriarch = sheet5.createDrawingPatriarch();
1097 HSSFClientAnchor anchor;
1098 anchor = new HSSFClientAnchor(0,0,0,255,(short)2,2,(short)4,7);
1099 anchor.setAnchorType( 2 );
1100 patriarch.createPicture(anchor, loadPicture( "src/resources/logos/logoKarmokar4.png", wb ));
1101 </source>
1102 <p>Creating an image and setting its anchor to the actual width and height:</p>
1103 <source>
1104 HSSFPatriarch patriarch = sheet5.createDrawingPatriarch();
1106 HSSFPicture picture = patriarch.createPicture(new HSSFClientAnchor(), loadPicture( "src/resources/logos/logoKarmokar4.png", wb ));
1107 picture.resize();
1108 </source>
1109 <p>or</p>
1110 <source>
1111 HSSFPatriarch patriarch = sheet5.createDrawingPatriarch();
1113 HSSFPicture picture = patriarch.createPicture(new HSSFClientAnchor(), loadPicture( "src/resources/logos/logoKarmokar4.png", wb ));
1114 HSSFClientAnchor preferredSize = picture.getPreferredSize();
1115 picture.setAnchor(preferredSize);
1116 </source>
1117 <warning>
1118 HSSFPicture.resize() works only for JPEG and PNG. Other formats are not yet supported.
1119 </warning>
1121 <p>Reading images from a workbook:</p>
1122 <source>
1123 HSSFWorkbook wb;
1125 List lst = wb.getAllPictures();
1126 for (Iterator it = lst.iterator(); it.hasNext(); ) {
1127 HSSFPictureData pict = (HSSFPictureData)it.next();
1128 String ext = pict.suggestFileExtension();
1129 byte[] data = pict.getData();
1130 if (ext.equals("jpeg")){
1131 FileOutputStream out = new FileOutputStream("pict.jpg");
1132 out.write(data);
1133 out.close();
1134 }
1135 }
1136 </source>
1137 </section>
1138 <anchor id="NamedRanges"/>
1139 <section>
1140 <title>Named Ranges and Named Cells</title>
1141 <p>
1142 Named Range is a way to refer to a group of cells by a name. Named Cell is a
1143 degenerate case of Named Range in that the 'group of cells' contains exactly one
1144 cell. You can create as well as refer to cells in a workbook by their named range.
1145 When working with Named Ranges, the classes: org.apache.poi.hssf.util.CellReference and
1146 & org.apache.poi.hssf.util.AreaReference are used.
1147 </p>
1148 <p>
1149 Creating Named Range / Named Cell
1150 </p>
1151 <source>
1152 // setup code
1153 String sname = "TestSheet", cname = "TestName", cvalue = "TestVal";
1154 HSSFWorkbook wb = new HSSFWorkbook();
1155 HSSFSheet sheet = wb.createSheet(sname);
1156 sheet.createRow(0).createCell((short) 0).setCellValue(cvalue);
1158 // 1. create named range for a single cell using areareference
1159 HSSFName namedCell = wb.createName();
1160 namedCell.setNameName(cname);
1161 String reference = sname+"!A1:A1"; // area reference
1162 namedCell.setReference(reference);
1164 // 2. create named range for a single cell using cellreference
1165 HSSFName namedCell = wb.createName();
1166 namedCell.setNameName(cname);
1167 String reference = sname+"!A1"; // cell reference
1168 namedCell.setReference(reference);
1170 // 3. create named range for an area using AreaReference
1171 HSSFName namedCell = wb.createName();
1172 namedCell.setNameName(cname);
1173 String reference = sname+"!A1:C5"; // area reference
1174 namedCell.setReference(reference);
1176 </source>
1177 <p>
1178 Reading from Named Range / Named Cell
1179 </p>
1180 <source>
1181 // setup code
1182 String cname = "TestName";
1183 HSSFWorkbook wb = getMyWorkbook(); // retrieve workbook
1185 // retrieve the named range
1186 int namedCellIdx = wb.getNameIndex(cellName);
1187 HSSFName aNamedCell = wb.getNameAt(namedCellIdx);
1189 // retrieve the cell at the named range and test its contents
1190 AreaReference aref = new AreaReference(aNamedCell.getReference());
1191 CellReference[] crefs = aref.getAllReferencedCells();
1192 for (int i=0; i<crefs.length; i++) {
1193 HSSFSheet s = wb.getSheet(crefs[i].getSheetName());
1194 HSSFRow r = sheet.getRow(crefs[i].getRow());
1195 HSSFCell c = r.getCell(crefs[i].getCol());
1196 // extract the cell contents based on cell type etc.
1197 }
1198 </source>
1199 <p>
1200 Reading from non-contiguous Named Ranges
1201 </p>
1202 <source>
1203 // Setup code
1204 String cname = "TestName";
1205 HSSFWorkbook wb = getMyWorkbook(); // retrieve workbook
1207 // Retrieve the named range
1208 // Will be something like "$C$10,$D$12:$D$14";
1209 int namedCellIdx = wb.getNameIndex(cellName);
1210 HSSFName aNamedCell = wb.getNameAt(namedCellIdx);
1212 // Retrieve the cell at the named range and test its contents
1213 // Will get back one AreaReference for C10, and
1214 // another for D12 to D14
1215 AreaReference[] arefs = AreaReference.generateContiguous(aNamedCell.getReference());
1216 for (int i=0; i<arefs.length; i++) {
1217 // Only get the corners of the Area
1218 // (use arefs[i].getAllReferencedCells() to get all cells)
1219 CellReference[] crefs = arefs[i].getCells();
1220 for (int j=0; j<crefs.length; j++) {
1221 // Check it turns into real stuff
1222 HSSFSheet s = wb.getSheet(crefs[j].getSheetName());
1223 HSSFRow r = s.getRow(crefs[j].getRow());
1224 HSSFCell c = r.getCell(crefs[j].getCol());
1225 // Do something with this corner cell
1226 }
1227 }
1228 </source>
1229 <p>
1230 Note, when a cell is deleted, Excel does not delete the attached named range.
1231 As result, workbook can contain named ranges that point to cells that no longer exist.
1232 You should check the validity of a reference before constructing AreaReference
1233 </p>
1234 <source>
1235 if(hssfName.isDeleted()){
1236 //named range points to a deleted cell.
1237 } else {
1238 AreaReference ref = new AreaReference(hssfName.getReference());
1239 }
1240 </source>
1241 </section>
1242 <anchor id="CellComments"/>
1243 <section><title>Cell Comments</title>
1244 <p>
1245 In Excel a comment is a kind of a text shape,
1246 so inserting a comment is very similar to placing a text box in a worksheet:
1247 </p>
1248 <source>
1249 HSSFWorkbook wb = new HSSFWorkbook();
1250 HSSFSheet sheet = wb.createSheet("Cell comments in POI HSSF");
1252 // Create the drawing patriarch. This is the top level container for all shapes including cell comments.
1253 HSSFPatriarch patr = sheet.createDrawingPatriarch();
1255 //create a cell in row 3
1256 HSSFCell cell1 = sheet.createRow(3).createCell((short)1);
1257 cell1.setCellValue(new HSSFRichTextString("Hello, World"));
1259 //anchor defines size and position of the comment in worksheet
1260 HSSFComment comment1 = patr.createComment(new HSSFClientAnchor(0, 0, 0, 0, (short)4, 2, (short) 6, 5));
1262 // set text in the comment
1263 comment1.setString(new HSSFRichTextString("We can set comments in POI"));
1265 //set comment author.
1266 //you can see it in the status bar when moving mouse over the commented cell
1267 comment1.setAuthor("Apache Software Foundation");
1269 // The first way to assign comment to a cell is via HSSFCell.setCellComment method
1270 cell1.setCellComment(comment1);
1272 //create another cell in row 6
1273 HSSFCell cell2 = sheet.createRow(6).createCell((short)1);
1274 cell2.setCellValue(36.6);
1277 HSSFComment comment2 = patr.createComment(new HSSFClientAnchor(0, 0, 0, 0, (short)4, 8, (short) 6, 11));
1278 //modify background color of the comment
1279 comment2.setFillColor(204, 236, 255);
1281 HSSFRichTextString string = new HSSFRichTextString("Normal body temperature");
1283 //apply custom font to the text in the comment
1284 HSSFFont font = wb.createFont();
1285 font.setFontName("Arial");
1286 font.setFontHeightInPoints((short)10);
1287 font.setBoldweight(HSSFFont.BOLDWEIGHT_BOLD);
1288 font.setColor(HSSFColor.RED.index);
1289 string.applyFont(font);
1291 comment2.setString(string);
1292 //by default comments are hidden. This one is always visible.
1293 comment2.setVisible(true);
1295 comment2.setAuthor("Bill Gates");
1297 /**
1298 * The second way to assign comment to a cell is to implicitly specify its row and column.
1299 * Note, it is possible to set row and column of a non-existing cell.
1300 * It works, the commnet is visible.
1301 */
1302 comment2.setRow(6);
1303 comment2.setColumn((short)1);
1305 FileOutputStream out = new FileOutputStream("poi_comment.xls");
1306 wb.write(out);
1307 out.close();
1308 </source>
1309 <p>
1310 Reading cell comments
1311 </p>
1312 <source>
1313 HSSFCell cell = sheet.get(3).getColumn((short)1);
1314 HSSFComment comment = cell.getCellComment();
1315 if (comment != null) {
1316 HSSFRichTextString str = comment.getString();
1317 String author = comment.getAuthor();
1318 }
1319 // alternatively you can retrieve cell comments by (row, column)
1320 comment = sheet.getCellComment(3, 1);
1321 </source>
1322 </section>
1323 <anchor id="Autofit"/>
1324 <section><title>Adjust column width to fit the contents</title>
1325 <source>
1326 HSSFSheet sheet = workbook.getSheetAt(0);
1327 sheet.autoSizeColumn((short)0); //adjust width of the first column
1328 sheet.autoSizeColumn((short)1); //adjust width of the second column
1329 </source>
1330 <warning>
1331 To calculate column width HSSFSheet.autoSizeColumn uses Java2D classes
1332 that throw exception if graphical environment is not available. In case if graphical environment
1333 is not available, you must tell Java that you are running in headless mode and
1334 set the following system property: <code> java.awt.headless=true </code>
1335 (either via <code>-Djava.awt.headless=true</code> startup parameter or via <code>System.setProperty("java.awt.headless", "true")</code>).
1336 </warning>
1337 </section>
1338 <anchor id="Hyperlinks"/>
1339 <section><title>How to read hyperlinks</title>
1340 <source>
1341 HSSFSheet sheet = workbook.getSheetAt(0);
1343 HSSFCell cell = sheet.getRow(0).getCell((short)0);
1344 HSSFHyperlink link = cell.getHyperlink();
1345 if(link != null){
1346 System.out.println(link.getAddress());
1347 }
1348 </source>
1349 </section>
1350 <section><title>How to create hyperlinks</title>
1351 <source>
1352 HSSFWorkbook wb = new HSSFWorkbook();
1354 //cell style for hyperlinks
1355 //by default hypelrinks are blue and underlined
1356 HSSFCellStyle hlink_style = wb.createCellStyle();
1357 HSSFFont hlink_font = wb.createFont();
1358 hlink_font.setUnderline(HSSFFont.U_SINGLE);
1359 hlink_font.setColor(HSSFColor.BLUE.index);
1360 hlink_style.setFont(hlink_font);
1362 HSSFCell cell;
1363 HSSFSheet sheet = wb.createSheet("Hyperlinks");
1365 //URL
1366 cell = sheet.createRow(0).createCell((short)0);
1367 cell.setCellValue("URL Link");
1368 HSSFHyperlink link = new HSSFHyperlink(HSSFHyperlink.LINK_URL);
1369 link.setAddress("http://poi.apache.org/");
1370 cell.setHyperlink(link);
1371 cell.setCellStyle(hlink_style);
1373 //link to a file in the current directory
1374 cell = sheet.createRow(1).createCell((short)0);
1375 cell.setCellValue("File Link");
1376 link = new HSSFHyperlink(HSSFHyperlink.LINK_FILE);
1377 link.setAddress("link1.xls");
1378 cell.setHyperlink(link);
1379 cell.setCellStyle(hlink_style);
1381 //e-mail link
1382 cell = sheet.createRow(2).createCell((short)0);
1383 cell.setCellValue("Email Link");
1384 link = new HSSFHyperlink(HSSFHyperlink.LINK_EMAIL);
1385 //note, if subject contains white spaces, make sure they are url-encoded
1386 link.setAddress("mailto:poi@apache.org?subject=Hyperlinks");
1387 cell.setHyperlink(link);
1388 cell.setCellStyle(hlink_style);
1390 //link to a place in this workbook
1392 //create a target sheet and cell
1393 HSSFSheet sheet2 = wb.createSheet("Target Sheet");
1394 sheet2.createRow(0).createCell((short)0).setCellValue("Target Cell");
1396 cell = sheet.createRow(3).createCell((short)0);
1397 cell.setCellValue("Worksheet Link");
1398 link = new HSSFHyperlink(HSSFHyperlink.LINK_DOCUMENT);
1399 link.setAddress("'Target Sheet'!A1");
1400 cell.setHyperlink(link);
1401 cell.setCellStyle(hlink_style);
1403 FileOutputStream out = new FileOutputStream("hssf-links.xls");
1404 wb.write(out);
1405 out.close();
1406 </source>
1407 </section>
1409 </body>
1410 </document>