## 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
`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
`protected` `XSSFName(org.openxmlformats.schemas.spreadsheetml.x2006.main.CTDefinedName name, XSSFWorkbook workbook)` Creates an XSSFName object - called internally by XSSFWorkbook.

Method Summary
`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 ?
`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)`

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

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

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