NameHandle (OpenXLS Java Spreadsheet SDK 11.0.4 API)

java.lang.Object
- io.starter.OpenXLS.NameHandle

```
public class NameHandle
extends Object
```
The NameHandle provides access to a Named Range and its Cells.

Use the NameHandle to work with individual Named Ranges in an XLS file.

With a NameHandle you can:

get a handle to the Cells in a Name
set the default formatting for a Name

See Also:

WorkBookHandle, WorkSheetHandle, FormulaHandle

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`NameHandle(Name c, WorkBookHandle myb)` Create a NameHandle from an internal Name record
	`NameHandle(String namestr, CellRange cr)` Creates a new Named Range from a CellRange
	`NameHandle(String name, String location, WorkBookHandle book)` Create a new named range in the workbook
	`NameHandle(String namestr, WorkBookHandle myb)` Deprecated.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addCell(CellHandle cx)` add a cell to this named range
`void`	`addRow(Object[] objarr)` add a row of cells to this named range
`void`	`deleteRow(int idxcol)` deletes a row of cells in this named range, shifts subsequent rows up.
`String`	`get2DSheetName()` return the sheetname for a 2D named range NOTE: Does not work for 3D ranges
`Object`	`getCalculatedValue()` return the calculated value of this Name if it contains a parsed Expression (Formula)
`CellRange[]`	`getCellRanges()` Get an Array of CellRanges, one per referenced WorkSheet.
`String`	`getCellRangeXML()` gets the array of Cells in this Name
`String`	`getCellRangeXML(boolean fragment)` gets the array of Cells in this Name NOTE: this method variation also returns the Sheetname for the name record if not null.
`CellHandle[]`	`getCells()` gets the array of Cells in this Name
`String`	`getExpandedXML()`
`String`	`getExpressionString()` returns the name's formula String for the range definition
`String`	`getJSON()` Return a JSON object representing this name Handle.
`String`	`getJSON(boolean celldata)` Return a JSON object representing this name Handle.
`org.json.JSONObject`	`getJSONCellRange()` Returns a JSON object in the same format as `CellRange.getJSON()`.
`String`	`getLocation()` get the referenced named cell range as string in standard excel syntax including sheetname, for instance "Sheet1!A1:Z255"
`String`	`getName()` returns the name String for the range definition
`WorkSheetHandle[]`	`getReferencedSheets()` Get WorkSheetHandles for all of the Boundsheets referenced in this NameHandle.
`Handle`	`getScope()` Returns a handle to the object (either workbook or sheet) that is scoped to the name record Default scope is a WorkBookHandle, else the WorkSheetHandle is returned.
`String`	`getXML()` Return an XML representation of this name record
`boolean`	`remove()` removes this Named Range from the WorkBook.
`void`	`setCreateBlanks(boolean b)` set whether the CellRanges referenced by the NameHandle will add blank records to the WorkBook for any missing Cells contained within the range.
`void`	`setFormatId(int i)` sets the default format id for the Name's Cells
`void`	`setLocation(String strloc)` set the referenced cells for the named range this reference should be in the standard excel syntax including sheetname, for instance "Sheet1!A1:Z255"
`boolean`	`setLocationLocked(String loc, boolean l)` Sets the location lock on the Cell Reference at the specified location Used to prevent updating of the Cell Reference when Cells are moved.
`void`	`setName(String newname)` set the name String for the range definition
`void`	`setScope(Handle scope)` Set the scope of this name to that of the handle passed in.
`String`	`toString()`
`void`	`updateRow(Object[] objarr, int idxcol)` update a row of cells in this named range

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - NameHandle
```
public NameHandle(String namestr,
                  CellRange cr)
```
    Creates a new Named Range from a CellRange
    
    Parameters:
    
    Name - of the Range, the CellRange referenced by the Name
  - NameHandle
```
protected NameHandle(Name c,
                     WorkBookHandle myb)
```
    Create a NameHandle from an internal Name record
    
    Parameters:
    
    c -
    
    myb -
  - NameHandle
```
public NameHandle(String namestr,
                  WorkBookHandle myb)
```
    Deprecated.
    
    Create a new named range in the workbook note that this does not set the actual range, just the workbook and name, follow up with setLocation
    
    Parameters:
    
    namestr -
    
    myb -
  - NameHandle
```
public NameHandle(String name,
                  String location,
                  WorkBookHandle book)
```
    Create a new named range in the workbook
    
    Parameters:
    
    name - name that should be used to reference this named range
    
    location - rangeDef Range of the cells for this named range, in excel syntax including sheet name, ie "Sheet1!A1:D1"
    
    book - WorkBookHandle to insert this named range into
- Method Detail
  - getScope
```
public Handle getScope()
                throws WorkSheetNotFoundException
```
    Returns a handle to the object (either workbook or sheet) that is scoped to the name record Default scope is a WorkBookHandle, else the WorkSheetHandle is returned.
    
    Returns:
    
    the scope of the name
    
    Throws:
    
    WorkSheetNotFoundException
  - setScope
```
public void setScope(Handle scope)
```
    Set the scope of this name to that of the handle passed in. This can either be a WorkbookHandle or a WorksheetHandle note: this will only be functional for the workbook that the name is contained in, you cannot change the scope to a different Document with this method.
    
    Parameters:
    
    scope - Workbookhandle or WorksheetHandle
  - getXML
```
public String getXML()
```
    Return an XML representation of this name record
  - getExpandedXML
```
public String getExpandedXML()
```
    Returns:
    
    String XML rep of all the cells referenced by this range
  - setFormatId
```
public void setFormatId(int i)
```
    sets the default format id for the Name's Cells
    
    Parameters:
    
    int - Format Id for all Cells in Name
  - deleteRow
```
public void deleteRow(int idxcol)
               throws Exception
```
    deletes a row of cells in this named range, shifts subsequent rows up.
    
    Parameters:
    
    the - column to use as unique index
    
    Throws:
    
    Exception
  - updateRow
```
public void updateRow(Object[] objarr,
                      int idxcol)
               throws Exception
```
    update a row of cells in this named range
    
    Parameters:
    
    an - array of Objects to update existing
    
    the - column to use as unique index
    
    Throws:
    
    Exception
  - addRow
```
public void addRow(Object[] objarr)
            throws Exception
```
    add a row of cells to this named range
    
    Parameters:
    
    an - array of Objects to insert at last rown
    
    Throws:
    
    Exception
  - addCell
```
public void addCell(CellHandle cx)
             throws Exception
```
    add a cell to this named range
    
    Parameters:
    
    cx -
    
    Throws:
    
    Exception
  - setLocation
```
public void setLocation(String strloc)
```
    set the referenced cells for the named range this reference should be in the standard excel syntax including sheetname, for instance "Sheet1!A1:Z255"
  - getLocation
```
public String getLocation()
```
    get the referenced named cell range as string in standard excel syntax including sheetname, for instance "Sheet1!A1:Z255"
  - setName
```
public void setName(String newname)
```
    set the name String for the range definition
    
    Parameters:
    
    String - definition name
  - getName
```
public String getName()
```
    returns the name String for the range definition
    
    Returns:
    
    String definition name
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - getExpressionString
```
public String getExpressionString()
```
    returns the name's formula String for the range definition
    
    Returns:
    
    String the expression string
  - remove
```
public boolean remove()
```
    removes this Named Range from the WorkBook.
    
    Returns:
    
    whether the removal was a success
  - setCreateBlanks
```
public void setCreateBlanks(boolean b)
```
    set whether the CellRanges referenced by the NameHandle will add blank records to the WorkBook for any missing Cells contained within the range.
    
    Parameters:
    
    b - set whether to create blank records for missing Cells
  - getCellRangeXML
```
public String getCellRangeXML(boolean fragment)
```
    gets the array of Cells in this Name NOTE: this method variation also returns the Sheetname for the name record if not null. Thus this method is limited to use with 2D ranges.
    
    Parameters:
    
    fragment - whether to enclose result in NameHandle tag
    
    Returns:
    
    Cell[] all Cells defined in this Name
  - getCellRangeXML
```
public String getCellRangeXML()
```
    gets the array of Cells in this Name
    
    Returns:
    
    Cell[] all Cells defined in this Name
  - getCells
```
public CellHandle[] getCells()
                      throws CellNotFoundException
```
    gets the array of Cells in this Name
    
    Returns:
    
    Cell[] all Cells defined in this Name
    
    Throws:
    
    CellNotFoundException
  - getCellRanges
```
public CellRange[] getCellRanges()
                          throws Exception
```
    Get an Array of CellRanges, one per referenced WorkSheet. If this method throws CellNotFoundExceptions, then you are addressing a sparsely populated CellRange. Use 'setCreateBlanks(true)' to populate these Cells and avoid this error.
    
    Returns:
    
    Throws:
    
    Exception
  - getReferencedSheets
```
public WorkSheetHandle[] getReferencedSheets()
                                      throws WorkSheetNotFoundException
```
    Get WorkSheetHandles for all of the Boundsheets referenced in this NameHandle.
    
    Returns:
    
    an array of WorkSheetHandles referenced in this Name
    
    Throws:
    
    WorkSheetNotFoundException
  - getCalculatedValue
```
public Object getCalculatedValue()
                          throws FunctionNotSupportedException
```
    return the calculated value of this Name if it contains a parsed Expression (Formula)
    
    Returns:
    
    Throws:
    
    FunctionNotSupportedException
  - setLocationLocked
```
public boolean setLocationLocked(String loc,
                                 boolean l)
```
    Sets the location lock on the Cell Reference at the specified location Used to prevent updating of the Cell Reference when Cells are moved.
    
    Parameters:
    
    location - of the Cell Reference to be locked/unlocked
    
    lock - status setting
    
    Returns:
    
    boolean whether the Cell Reference was found and modified
  - getJSON
```
public String getJSON()
```
    Return a JSON object representing this name Handle. name:'nameOfRange' cellrange:'Sheet1!A1:B1'
    
    Returns:
  - getJSON
```
public String getJSON(boolean celldata)
```
    Return a JSON object representing this name Handle. name:'nameOfRange' cellrange:'Sheet1!A1:B1' cells:celldata
    
    Parameters:
    
    whether - to return cell data
    
    Returns:
  - getJSONCellRange
```
public org.json.JSONObject getJSONCellRange()
```
    Returns a JSON object in the same format as CellRange.getJSON().
  - get2DSheetName
```
public String get2DSheetName()
```
    return the sheetname for a 2D named range NOTE: Does not work for 3D ranges
    
    Returns:
    
    the Sheet name if this is a 2d range

Class NameHandle

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

NameHandle

NameHandle

NameHandle

NameHandle

Method Detail

getScope

setScope

getXML

getExpandedXML

setFormatId

deleteRow

updateRow

addRow

addCell

setLocation

getLocation

setName

getName

toString

getExpressionString

remove

setCreateBlanks

getCellRangeXML

getCellRangeXML

getCells

getCellRanges

getReferencedSheets

getCalculatedValue

setLocationLocked

getJSON

getJSON

getJSONCellRange

get2DSheetName