org.apache.poi.xssf.usermodel

Class XSSFName

java.lang.Object

org.apache.poi.xssf.usermodel.XSSFName

All Implemented Interfaces:

Name

public final class XSSFName
extends java.lang.Object
implements Name

Represents a defined named range in a SpreadsheetML workbook.

Defined names are descriptive text that is used to represents a cell, range of cells, formula, or constant value. Use easy-to-understand names, such as Products, to refer to hard to understand ranges, such as Sales!C20:C30.

Example:

   XSSFWorkbook wb = new XSSFWorkbook();
   XSSFSheet sh = wb.createSheet("Sheet1");

   //applies to the entire workbook
   XSSFName name1 = wb.createName();
   name1.setNameName("FMLA");
   name1.setRefersToFormula("Sheet1!$B$3");

   //applies to Sheet1
   XSSFName name2 = wb.createName();
   name2.setNameName("SheetLevelName");
   name2.setComment("This name is scoped to Sheet1");
   name2.setLocalSheetId(0);
   name2.setRefersToFormula("Sheet1!$B$3");

 

Author:

Nick Burch, Yegor Kozlov

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	BUILTIN_CONSOLIDATE_AREA A built-in defined name that refers to a consolidation area
static java.lang.String	BUILTIN_CRITERIA A built-in defined name that refers to a range containing the criteria values to be used in applying an advanced filter to a range of data
static java.lang.String	BUILTIN_DATABASE A built-in defined name that specified that the range specified is from a database data source
static java.lang.String	BUILTIN_EXTRACT this defined name refers to the range containing the filtered output values resulting from applying an advanced filter criteria to a source range
static java.lang.String	BUILTIN_FILTER_DB ?an be one of the following this defined name refers to a range to which an advanced filter has been applied.
static java.lang.String	BUILTIN_PRINT_AREA A built-in defined name that specifies the workbook's print area
static java.lang.String	BUILTIN_PRINT_TITLE A built-in defined name that specifies the row(s) or column(s) to repeat at the top of each printed page.
static java.lang.String	BUILTIN_SHEET_TITLE A built-in defined name that refers to a sheet title.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	XSSFName(org.openxmlformats.schemas.spreadsheetml.x2006.main.CTDefinedName name, XSSFWorkbook workbook) Creates an XSSFName object - called internally by XSSFWorkbook.

Method Summary

Modifier and Type	Method and Description
boolean	equals(java.lang.Object o) Compares this name to the specified object.
java.lang.String	getComment() Returns the comment the user provided when the name was created.
protected org.openxmlformats.schemas.spreadsheetml.x2006.main.CTDefinedName	getCTName() Returns the underlying named range object
boolean	getFunction() Indicates that the defined name refers to a user-defined function.
int	getFunctionGroupId() Returns the function group index if the defined name refers to a function.
java.lang.String	getNameName() Returns the name that will appear in the user interface for the defined name.
java.lang.String	getRefersToFormula() Returns the formula that the name is defined to refer to.
int	getSheetIndex() Returns the sheet index this name applies to.
java.lang.String	getSheetName() Get the sheets name which this named range is referenced to
int	hashCode()
boolean	isDeleted() Checks if this name points to a cell that no longer exists
boolean	isFunctionName() Is the name refers to a user-defined function ?
boolean	isHidden() Checks if this name is hidden, eg one of the built-in Excel internal names
void	setComment(java.lang.String comment) Specifies the comment the user provided when the name was created.
void	setFunction(boolean value) Indicates that the defined name refers to a user-defined function.
void	setFunctionGroupId(int functionGroupId) Specifies the function group index if the defined name refers to a function.
void	setNameName(java.lang.String name) Sets the name that will appear in the user interface for the defined name.
void	setRefersToFormula(java.lang.String formulaText) Sets the formula that the name is defined to refer to.
void	setSheetIndex(int index) Tell Excel that this name applies to the worksheet with the specified index instead of the entire workbook.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

BUILTIN_PRINT_AREA

public static final java.lang.String BUILTIN_PRINT_AREA

A built-in defined name that specifies the workbook's print area

See Also:

Constant Field Values

BUILTIN_PRINT_TITLE

public static final java.lang.String BUILTIN_PRINT_TITLE

A built-in defined name that specifies the row(s) or column(s) to repeat at the top of each printed page.

See Also:

Constant Field Values

BUILTIN_CRITERIA

public static final java.lang.String BUILTIN_CRITERIA

A built-in defined name that refers to a range containing the criteria values to be used in applying an advanced filter to a range of data

See Also:

Constant Field Values

BUILTIN_EXTRACT

public static final java.lang.String BUILTIN_EXTRACT

this defined name refers to the range containing the filtered output values resulting from applying an advanced filter criteria to a source range

See Also:

Constant Field Values

BUILTIN_FILTER_DB

public static final java.lang.String BUILTIN_FILTER_DB

?an be one of the following

this defined name refers to a range to which an advanced filter has been applied. This represents the source data range, unfiltered. This defined name refers to a range to which an AutoFilter has been applied

See Also:

Constant Field Values

BUILTIN_CONSOLIDATE_AREA

public static final java.lang.String BUILTIN_CONSOLIDATE_AREA

A built-in defined name that refers to a consolidation area

See Also:

Constant Field Values

BUILTIN_DATABASE

public static final java.lang.String BUILTIN_DATABASE

A built-in defined name that specified that the range specified is from a database data source

See Also:

Constant Field Values

BUILTIN_SHEET_TITLE

public static final java.lang.String BUILTIN_SHEET_TITLE

A built-in defined name that refers to a sheet title.

See Also:

Constant Field Values

Constructor Detail

XSSFName

protected XSSFName(org.openxmlformats.schemas.spreadsheetml.x2006.main.CTDefinedName name,
                   XSSFWorkbook workbook)

Creates an XSSFName object - called internally by XSSFWorkbook.

Parameters:

name - - the xml bean that holds data represenring this defined name.

workbook - - the workbook object associated with the name

See Also:

XSSFWorkbook.createName()

Method Detail

getCTName

protected org.openxmlformats.schemas.spreadsheetml.x2006.main.CTDefinedName getCTName()

Returns the underlying named range object

getNameName

public java.lang.String getNameName()

Returns the name that will appear in the user interface for the defined name.

Specified by:

getNameName in interface Name

Returns:

text name of this defined name

setNameName

public void setNameName(java.lang.String name)

Sets the name that will appear in the user interface for the defined name. Names must begin with a letter or underscore, not contain spaces and be unique across the workbook.

A name must always be unique within its scope. POI prevents you from defining a name that is not unique within its scope. However you can use the same name in different scopes. Example:

 //by default names are workbook-global
 XSSFName name;
 name = workbook.createName();
 name.setNameName("sales_08");

 name = workbook.createName();
 name.setNameName("sales_08"); //will throw an exception: "The workbook already contains this name (case-insensitive)"

 //create sheet-level name
 name = workbook.createName();
 name.setSheetIndex(0); //the scope of the name is the first sheet
 name.setNameName("sales_08");  //ok

 name = workbook.createName();
 name.setSheetIndex(0);
 name.setNameName("sales_08");  //will throw an exception: "The sheet already contains this name (case-insensitive)"

 

Specified by:

setNameName in interface Name

Parameters:

name - name of this defined name

Throws:

java.lang.IllegalArgumentException - if the name is invalid or the workbook already contains this name (case-insensitive)

getRefersToFormula

public java.lang.String getRefersToFormula()

Description copied from interface: Name

Returns the formula that the name is defined to refer to.

Specified by:

getRefersToFormula in interface Name

Returns:

the reference for this name, null if it has not been set yet. Never empty string

See Also:

Name.setRefersToFormula(String)

setRefersToFormula

public void setRefersToFormula(java.lang.String formulaText)

Description copied from interface: Name

Sets the formula that the name is defined to refer to. The following are representative examples:

• 'My Sheet'!$A$3
• 8.3
• HR!$A$1:$Z$345
• SUM(Sheet1!A1,Sheet2!B2)
• -PMT(Interest_Rate/12,Number_of_Payments,Loan_Amount)

Note: Using relative values like 'A1:B1' can lead to unexpected moving of the cell that the name points to when working with the workbook in Microsoft Excel, usually using absolute references like '$A$1:$B$1' avoids this, see also https://superuser.com/a/1031047/126954

Specified by:

setRefersToFormula in interface Name

Parameters:

formulaText - the reference for this name

isDeleted

public boolean isDeleted()

Description copied from interface: Name

Checks if this name points to a cell that no longer exists

Specified by:

isDeleted in interface Name

Returns:

true if the name refers to a deleted cell, false otherwise

setSheetIndex

public void setSheetIndex(int index)

Tell Excel that this name applies to the worksheet with the specified index instead of the entire workbook.

Specified by:

setSheetIndex in interface Name

Parameters:

index - the sheet index this name applies to, -1 unsets this property making the name workbook-global

getSheetIndex

public int getSheetIndex()

Returns the sheet index this name applies to.

Specified by:

getSheetIndex in interface Name

Returns:

the sheet index this name applies to, -1 if this name applies to the entire workbook

setFunction

public void setFunction(boolean value)

Indicates that the defined name refers to a user-defined function. This attribute is used when there is an add-in or other code project associated with the file.

Specified by:

setFunction in interface Name

Parameters:

value - true indicates the name refers to a function.

getFunction

public boolean getFunction()

Indicates that the defined name refers to a user-defined function. This attribute is used when there is an add-in or other code project associated with the file.

Returns:

true indicates the name refers to a function.

setFunctionGroupId

public void setFunctionGroupId(int functionGroupId)

Specifies the function group index if the defined name refers to a function. The function group defines the general category for the function. This attribute is used when there is an add-in or other code project associated with the file.

Parameters:

functionGroupId - the function group index that defines the general category for the function

getFunctionGroupId

public int getFunctionGroupId()

Returns the function group index if the defined name refers to a function. The function group defines the general category for the function. This attribute is used when there is an add-in or other code project associated with the file.

Returns:

the function group index that defines the general category for the function

getSheetName

public java.lang.String getSheetName()

Get the sheets name which this named range is referenced to

Specified by:

getSheetName in interface Name

Returns:

sheet name, which this named range referred to. Empty string if the referenced sheet name was not found.

isFunctionName

public boolean isFunctionName()

Is the name refers to a user-defined function ?

Specified by:

isFunctionName in interface Name

Returns:

true if this name refers to a user-defined function

isHidden

public boolean isHidden()

Checks if this name is hidden, eg one of the built-in Excel internal names

Specified by:

isHidden in interface Name

Returns:

true if this name is a hidden one

getComment

public java.lang.String getComment()

Returns the comment the user provided when the name was created.

Specified by:

getComment in interface Name

Returns:

the user comment for this named range

setComment

public void setComment(java.lang.String comment)

Specifies the comment the user provided when the name was created.

Specified by:

setComment in interface Name

Parameters:

comment - the user comment for this named range

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object o)

Compares this name to the specified object. The result is true if the argument is XSSFName and the underlying CTDefinedName bean equals to the CTDefinedName representing this name

Overrides:

equals in class java.lang.Object

Parameters:

o - the object to compare this XSSFName against.

Returns:

true if the XSSFName are equal; false otherwise.