moparisthebest/poi
1
0
Fork 0
Code Issues Pull Requests Releases 1 Wiki Activity

Some minor changes.

Browse Source 
git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@352327 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Glen Stampoultzis 2002-04-05 14:02:18 +00:00
parent e165f6690e
commit 5fb2ce97ec
1 changed files with 113 additions and 125 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

182
src/documentation/xdocs/hssf/how-to.xml
View File

@ -13,10 +13,9 @@
<s1 title="How to use the HSSF prototype API"> <s1 title="How to use the HSSF prototype API">
<s2 title="Capabilities"> <s2 title="Capabilities">
<p>This release of the how-to outlines functionality for 1.5. <p>This release of the how-to outlines functionality for the 1.5 release.
Those looking for information on the release edition should Those looking for information on previous releases should
look in the poi-src for the release or at a look in the documentation distributed with that release.</p>
previous edition in CVS tagged for that release.</p>
<p> <p>
This release allows numeric and string cell values to be written to This release allows numeric and string cell values to be written to
or read from an XLS file as well as reading and writing dates. Also or read from an XLS file as well as reading and writing dates. Also
@ -28,66 +27,54 @@
memory footprint. It will also serve as the basis for the HSSF memory footprint. It will also serve as the basis for the HSSF
Generator.</p> Generator.</p>
</s2> </s2>
<s2 title="Target Audience">
<p>This release is intended for developers, java-fanatics and the
just generally all around impatient. HSSF has not yet been
extensively tested in a high load multi-threaded situation. This
release is not considered to be &quot;golden&quot; as it has new
features that have not been extensively tested, and is an early 2.0
build that could be restructured significantly in the future (not
that there are necessarily plans to do so, just that you're better
off basing your code on 1.0 and sticking with it if you don't need
2.0 stuff bad enough to deal with us pulling the rug out from under
you regularly).</p>
</s2>
<s2 title="General Use"> <s2 title="General Use">
<s3 title="User API"> <s3 title="User API">
<s4 title="Writing a new one"> <s4 title="Writing a new one">
<p>The high level API (package: org.apache.poi.hssf.usermodel) <p>The high level API (package: org.apache.poi.hssf.usermodel)
is what most people should use. Usage is very simple. is what most people should use. Usage is very simple.
</p> </p>
<p>Workbooks are created by creating an instance of <p>Workbooks are created by creating an instance of
org.apache.poi.hssf.usermodel.HSSFWorkbook. org.apache.poi.hssf.usermodel.HSSFWorkbook.
</p> </p>
<p>Sheets are created by calling createSheet() from an existing <p>Sheets are created by calling createSheet() from an existing
instance of HSSFWorkbook, the created sheet is automatically added in instance of HSSFWorkbook, the created sheet is automatically added in
sequence to the workbook. Sheets do not in themselves have a sheet sequence to the workbook. Sheets do not in themselves have a sheet
name (the tab at the bottom); you set name (the tab at the bottom); you set
the name associated with a sheet by calling the name associated with a sheet by calling
HSSFWorkbook.setSheetName(sheetindex,&quot;SheetName&quot;).</p> HSSFWorkbook.setSheetName(sheetindex,&quot;SheetName&quot;).</p>
<p>Rows are created by calling createRow(rowNumber) from an existing <p>Rows are created by calling createRow(rowNumber) from an existing
instance of HSSFSheet. Only rows that have cell values should be instance of HSSFSheet. Only rows that have cell values should be
added to the sheet. To set the row's height, you just call added to the sheet. To set the row's height, you just call
setRowHeight(height) on the row object. The height must be given in setRowHeight(height) on the row object. The height must be given in
twips, or 1/20th of a point. If you prefer, there is also a twips, or 1/20th of a point. If you prefer, there is also a
setRowHeightInPoints method. setRowHeightInPoints method.
</p> </p>
<p>Cells are created by calling createCell(column, type) from an <p>Cells are created by calling createCell(column, type) from an
existing HSSFRow. Only cells that have values should be added to the existing HSSFRow. Only cells that have values should be added to the
row. Cells should have their cell type set to either row. Cells should have their cell type set to either
HSSFCell.CELL_TYPE_NUMERIC or HSSFCell.CELL_TYPE_STRING depending on HSSFCell.CELL_TYPE_NUMERIC or HSSFCell.CELL_TYPE_STRING depending on
whether they contain a numeric or textual value. Cells must also have whether they contain a numeric or textual value. Cells must also have
a value set. Set the value by calling setCellValue with either a a value set. Set the value by calling setCellValue with either a
String or double as a parameter. Individual cells do not have a String or double as a parameter. Individual cells do not have a
width; you must call setColumnWidth(colindex, width) (use units of width; you must call setColumnWidth(colindex, width) (use units of
1/256th of a character) on the HSSFSheet object. (You can't do it on 1/256th of a character) on the HSSFSheet object. (You can't do it on
an individual basis in the GUI either).</p> an individual basis in the GUI either).</p>
<p>Cells are styled with HSSFCellStyle objects which in turn contain <p>Cells are styled with HSSFCellStyle objects which in turn contain
a reference to an HSSFFont object. These are created via the a reference to an HSSFFont object. These are created via the
HSSFWorkbook object by calling createCellStyle() and createFont(). HSSFWorkbook object by calling createCellStyle() and createFont().
Once you create the object you must set its parameters (colors, Once you create the object you must set its parameters (colors,
borders, etc). To set a font for an HSSFCellStyle call borders, etc). To set a font for an HSSFCellStyle call
setFont(fontobj). setFont(fontobj).
</p> </p>
<p>Once you have generated your workbook, you can write it out by <p>Once you have generated your workbook, you can write it out by
calling write(outputStream) from your instance of Workbook, passing calling write(outputStream) from your instance of Workbook, passing
it an OutputStream (for instance, a FileOutputStream or it an OutputStream (for instance, a FileOutputStream or
ServletOutputStream). You must close the OutputStream yourself. HSSF ServletOutputStream). You must close the OutputStream yourself. HSSF
does not close it for you. does not close it for you.
</p> </p>
<p>Here is some example code (excerpted and adapted from <p>Here is some example code (excerpted and adapted from
org.apache.poi.hssf.dev.HSSF test class):</p> org.apache.poi.hssf.dev.HSSF test class):</p>
<source><![CDATA[ short rownum; <source><![CDATA[ short rownum;
// create a new file // create a new file
@ -242,45 +229,46 @@ would if creating a new xls. When you are done modifying cells just
call workbook.write(outputstream) just as you did above.</p> call workbook.write(outputstream) just as you did above.</p>
<p>An example of this can be seen in <p>An example of this can be seen in
<link href="http://cvs.apache.org/viewcvs/~checkout~/jakarta-poi/src/java/org/apache/poi/hssf/dev/HSSF.java?rev=1.1">org.apache.poi.hssf.dev.HSSF</link>.</p> <link href="http://cvs.apache.org/viewcvs/~checkout~/jakarta-poi/src/java/org/apache/poi/hssf/dev/HSSF.java?rev=1.1">org.apache.poi.hssf.dev.HSSF</link>.</p>
</s4> </s3> </s4>
</s3>
<s3 title="Event API"> <s3 title="Event API">
<p>The event API is brand new. It is intended for intermediate <p>The event API is brand new. It is intended for intermediate
developers who are willing to learn a little bit of the low level API developers who are willing to learn a little bit of the low level API
structures. Its relatively simple to use, but requires a basic structures. Its relatively simple to use, but requires a basic
understanding of the parts of an Excel file (or willingness to understanding of the parts of an Excel file (or willingness to
learn). The advantage provided is that you can read an XLS with a learn). The advantage provided is that you can read an XLS with a
relatively small memory footprint. relatively small memory footprint.
</p> </p>
<p>To use this API you construct an instance of <p>To use this API you construct an instance of
org.apache.poi.hssf.eventmodel.HSSFRequest. Register a class you org.apache.poi.hssf.eventmodel.HSSFRequest. Register a class you
create that supports the create that supports the
org.apache.poi.hssf.eventmodel.HSSFListener interface using the org.apache.poi.hssf.eventmodel.HSSFListener interface using the
HSSFRequest.addListener(yourlistener, recordsid). The recordsid HSSFRequest.addListener(yourlistener, recordsid). The recordsid
should be a static reference number (such as BOFRecord.sid) contained should be a static reference number (such as BOFRecord.sid) contained
in the classes in org.apache.poi.hssf.record. The trick is you in the classes in org.apache.poi.hssf.record. The trick is you
have to know what these records are. Alternatively you can call have to know what these records are. Alternatively you can call
HSSFRequest.addListenerForAllRecords(mylistener). In order to learn HSSFRequest.addListenerForAllRecords(mylistener). In order to learn
about these records you can either read all of the javadoc in the about these records you can either read all of the javadoc in the
org.apache.poi.hssf.record package or you can just hack up a org.apache.poi.hssf.record package or you can just hack up a
copy of org.apache.poi.hssf.dev.EFHSSF and adapt it to your copy of org.apache.poi.hssf.dev.EFHSSF and adapt it to your
needs. TODO: better documentation on records.</p> needs. TODO: better documentation on records.</p>
<p>Once you've registered your listeners in the HSSFRequest object <p>Once you've registered your listeners in the HSSFRequest object
you can construct an instance of you can construct an instance of
org.apache.poi.poifs.filesystem.FileSystem (see POIFS howto) and org.apache.poi.poifs.filesystem.FileSystem (see POIFS howto) and
pass it your XLS file inputstream. You can either pass this, along pass it your XLS file inputstream. You can either pass this, along
with the request you constructed, to an instance of HSSFEventFactory with the request you constructed, to an instance of HSSFEventFactory
via the HSSFEventFactory.processWorkbookEvents(request, Filesystem) via the HSSFEventFactory.processWorkbookEvents(request, Filesystem)
method, or you can get an instance of DocumentInputStream from method, or you can get an instance of DocumentInputStream from
Filesystem.createDocumentInputStream(&quot;Workbook&quot;) and pass Filesystem.createDocumentInputStream(&quot;Workbook&quot;) and pass
it to HSSFEventFactory.processEvents(request, inputStream). Once you it to HSSFEventFactory.processEvents(request, inputStream). Once you
make this call, the listeners that you constructed receive calls to make this call, the listeners that you constructed receive calls to
their processRecord(Record) methods with each Record they are their processRecord(Record) methods with each Record they are
registered to listen for until the file has been completely read. registered to listen for until the file has been completely read.
</p> </p>
<p>A code excerpt from org.apache.poi.hssf.dev.EFHSSF (which is <p>A code excerpt from org.apache.poi.hssf.dev.EFHSSF (which is
in CVS or the source distribution) is reprinted below with excessive in CVS or the source distribution) is reprinted below with excessive
comments:</p> comments:</p>
<source><![CDATA[ <source><![CDATA[
/** /**
* This example shows how to use the event API for reading a file. * This example shows how to use the event API for reading a file.