com.extentech.ExtenXLS
Class NameHandle

java.lang.Object
  com.extentech.ExtenXLS.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

Since:

1.3

Version:

4.1

Author:

John McMahon -- Copyright ©2011Extentech Inc.

See Also:

WorkBookHandle, WorkSheetHandle, FormulaHandle

Constructor Summary

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

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.
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

equals, 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

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 com.extentech.formats.XLS.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:

com.extentech.formats.XLS.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 com.extentech.formats.XLS.CellNotFoundException

gets the array of Cells in this Name

Returns:

Cell[] all Cells defined in this Name

Throws:

com.extentech.formats.XLS.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 com.extentech.formats.XLS.WorkSheetNotFoundException

Get WorkSheetHandles for all of the Boundsheets referenced in this NameHandle.

Returns:

an array of WorkSheetHandles referenced in this Name

Throws:

com.extentech.formats.XLS.WorkSheetNotFoundException

getCalculatedValue

public Object getCalculatedValue()
                          throws com.extentech.formats.XLS.FunctionNotSupportedException

return the calculated value of this Name if it contains a parsed Expression (Formula)

Returns:

Throws:

com.extentech.formats.XLS.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:

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