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

    All Methods Instance Methods Concrete Methods
    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 ?
    `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

  - #### 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 2020 The Apache Software Foundation or its licensors, as applicable.