From 2f806b08d90ff69b636bcc8dbf2d7c5e07dd27ea Mon Sep 17 00:00:00 2001
From: "Amol S. Deshmukh" <amol@apache.org>
Date: Wed, 13 Jul 2005 13:15:05 +0000
Subject: [PATCH] Added quick-guide entry for how to create NamedRanges and
 NamedCells using HSSFName

git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@353749 13f79535-47bb-0310-9956-ffa450edef68
---
 .../content/xdocs/hssf/quick-guide.xml        | 65 +++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/src/documentation/content/xdocs/hssf/quick-guide.xml b/src/documentation/content/xdocs/hssf/quick-guide.xml
index d4ecc43116..59a27dc653 100644
--- a/src/documentation/content/xdocs/hssf/quick-guide.xml
+++ b/src/documentation/content/xdocs/hssf/quick-guide.xml
@@ -46,6 +46,7 @@
                     <li><link href="#Graphics2d">Shapes and Graphics2d</link></li>
                     <li><link href="#Outlining">Outlining</link></li>
                     <li><link href="#Images">Images</link></li>
+                    <li><link href="#NamedRanges">Named Ranges and Named Cells</link></li>
                 </ul>
             </section>
             <section><title>Features</title>
@@ -970,5 +971,69 @@
     patriarch.createPicture(anchor, loadPicture( "src/resources/logos/logoKarmokar4.png", wb ));
             </source>
         </section>
+        <anchor id="NamedRanges"/>
+        <section>
+            <title>Named Ranges and Named Cells</title>
+            <p>
+                Named Range is a way to refer to a group of cells by a name. Named Cell is a 
+                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 
+                &amp; org.apache.poi.hssf.util.AreaReference are used.
+            </p>
+            <p>
+            Creating Named Range / Named Cell
+            </p>
+            <source>
+    // setup code
+    String sname = "TestSheet", cname = "TestName", cvalue = "TestVal";
+    HSSFWorkbook wb = new HSSFWorkbook();
+    HSSFSheet 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();
+    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();
+    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();
+    namedCell.setNameName(cname);
+    String reference = sname+"!A1:C5"; // area reference
+    namedCell.setReference(reference);
+    
+            </source>
+            <p>
+            Reading from Named Range / Named Cell
+            </p>
+            <source>
+    // setup code
+    String cname = "TestName";
+    HSSFWorkbook wb = getMyWorkbook(); // retrieve workbook
+
+    // retrieve the named range
+    int namedCellIdx = wb.getNameIndex(cellName);
+    HSSFName aNamedCell = wb.getNameAt(namedCellIdx);
+    
+    // retrieve the cell at the named range and test its contents
+    AreaReference aref = new AreaReference(aNamedCell.getReference());
+    CellReference[] crefs = aref.getCells();
+    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());
+        // extract the cell contents based on cell type etc.
+    }
+            </source>
+            
+        </section>
+        
     </body>
 </document>
-- 
2.39.5