Package org.apache.poi.hssf.usermodel

Class HSSFName

  • All Implemented Interfaces:
    Name
    public final class HSSFName
extends Object
implements Name
    High Level Representation of a 'defined name' which could be a 'built-in' name, 'named range' or name of a user defined function.

    • Method Detail

      • getSheetName

        public 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

      • getNameName

        public String getNameName()
        Description copied from interface: Name
        Gets the name of the named range
        Specified by:
        getNameName in interface Name
        Returns:
        text name of this defined name

      • setNameName

        public void setNameName​(String nameName)
        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.

        • Valid characters The first character of a name must be a letter, an underscore character (_), or a backslash (\). Remaining characters in the name can be letters, numbers, periods, and underscore characters.
        • Cell references disallowed Names cannot be the same as a cell reference, such as Z$100 or R1C1.
        • Spaces are not valid Spaces are not allowed as part of a name. Use the underscore character (_) and period (.) as word separators, such as, Sales_Tax or First.Quarter.
        • Name length A name can contain up to 255 characters.
        • Case sensitivity Names can contain uppercase and lowercase letters.

        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
 HSSFName 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:
        nameName - named range name to set
        Throws:
        IllegalArgumentException - if the name is invalid or the name already exists (case-insensitive)

      • setRefersToFormula

        public void setRefersToFormula​(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

      • getRefersToFormula

        public 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)

      • 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

      • isFunctionName

        public boolean isFunctionName()
        Checks if this name is a function name
        Specified by:
        isFunctionName in interface Name
        Returns:
        true if this name is a function name

      • setSheetIndex

        public void setSheetIndex​(int index)
        Specifies if the defined name is a local name, and if so, which sheet it is on.
        Specified by:
        setSheetIndex in interface Name
        Parameters:
        index - if greater than 0, the defined name is a local name and the value MUST be a 0-based index to the collection of sheets as they appear in the workbook.
        Throws:
        IllegalArgumentException - if the sheet index is invalid.

      • 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

      • getComment

        public 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​(String comment)
        Sets 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

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