org.apache.poi.ss.usermodel
Interface Name

All Known Implementing Classes:
HSSFName, XSSFName

public interface Name

Represents a defined name for a range of cells.

A name is a meaningful shorthand that makes it easier to understand the purpose of a cell reference, constant or a formula.

Examples:
Sheet sheet = workbook.createSheet("Loan Calculator"); Name name; name = workbook.createName(); name.setNameName("Interest_Rate"); name.setRefersToFormula("'Loan Calculator'!$E$5"); name = wb.createName(); name.setNameName("Loan_Amount"); name.setRefersToFormula("'Loan Calculator'!$E$4"); name = wb.createName(); name.setNameName("Number_of_Payments"); name.setRefersToFormula("'Loan Calculator'!$E$10"); name = wb.createName(); name.setNameName("Monthly_Payment"); name.setRefersToFormula("-PMT(Interest_Rate/12,Number_of_Payments,Loan_Amount)"); name = wb.createName(); name.setNameName("Values_Entered"); name.setRefersToFormula("IF(Loan_Amount*Interest_Rate>0,1,0)");


Method Summary
 java.lang.String getComment()
          Returns the comment the user provided when the name was created.
 java.lang.String getNameName()
          Gets the name of the named range
 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
 boolean isDeleted()
          Checks if this name points to a cell that no longer exists
 boolean isFunctionName()
          Checks if this name is a function name
 void setComment(java.lang.String comment)
          Sets 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 setNameName(java.lang.String name)
          Sets the name of the named range
 void setRefersToFormula(java.lang.String formulaText)
          Sets the formula that the name is defined to refer to.
 void setSheetIndex(int sheetId)
          Tell Excel that this name applies to the worksheet with the specified index instead of the entire workbook.
 

Method Detail

getSheetName

java.lang.String getSheetName()
Get the sheets name which this named range is referenced to

Returns:
sheet name, which this named range refered to

getNameName

java.lang.String getNameName()
Gets the name of the named range

Returns:
named range name

setNameName

void setNameName(java.lang.String name)
Sets the name of the named range

The following is a list of syntax rules that you need to be aware of when you create and edit names.

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 Name 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)"

Parameters:
name - named range name to set
Throws:
java.lang.IllegalArgumentException - if the name is invalid or the already exists within its scope (case-insensitive)

getRefersToFormula

java.lang.String getRefersToFormula()
Returns the formula that the name is defined to refer to.

Returns:
the reference for this name, null if it has not been set yet. Never empty string
See Also:
setRefersToFormula(String)

setRefersToFormula

void setRefersToFormula(java.lang.String formulaText)
Sets the formula that the name is defined to refer to. The following are representative examples:

Parameters:
formulaText - the reference for this name
Throws:
java.lang.IllegalArgumentException - if the specified formulaText is unparsable

isFunctionName

boolean isFunctionName()
Checks if this name is a function name

Returns:
true if this name is a function name

isDeleted

boolean isDeleted()
Checks if this name points to a cell that no longer exists

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

setSheetIndex

void setSheetIndex(int sheetId)
Tell Excel that this name applies to the worksheet with the specified index instead of the entire workbook.

Parameters:
sheetId - the sheet index this name applies to, -1 unsets this property making the name workbook-global
Throws:
java.lang.IllegalArgumentException - if the sheet index is invalid.

getSheetIndex

int getSheetIndex()
Returns the sheet index this name applies to.

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

getComment

java.lang.String getComment()
Returns the comment the user provided when the name was created.

Returns:
the user comment for this named range

setComment

void setComment(java.lang.String comment)
Sets the comment the user provided when the name was created.

Parameters:
comment - the user comment for this named range

setFunction

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.

Parameters:
value - true indicates the name refers to a function.


Copyright 2012 The Apache Software Foundation or its licensors, as applicable.