/* ==================================================================== Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ==================================================================== */ package org.apache.poi.xssf.usermodel; import org.apache.poi.hssf.record.formula.Ptg; import org.apache.poi.ss.formula.FormulaParser; import org.apache.poi.ss.formula.FormulaType; import org.apache.poi.ss.usermodel.Name; import org.apache.poi.ss.util.AreaReference; import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTDefinedName; /** * 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
.
*
* * @author Nick Burch * @author Yegor Kozlov */ public final class XSSFName implements Name { /** * A built-in defined name that specifies the workbook's print area */ public final static String BUILTIN_PRINT_AREA = "_xlnm.Print_Area"; /** * A built-in defined name that specifies the row(s) or column(s) to repeat * at the top of each printed page. */ public final static String BUILTIN_PRINT_TITLE = "_xlnm.Print_Titles"; /** * 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 */ public final static String BUILTIN_CRITERIA = "_xlnm.Criteria:"; /** * this defined name refers to the range containing the filtered * output values resulting from applying an advanced filter criteria to a source * range */ public final static String BUILTIN_EXTRACT = "_xlnm.Extract:"; /** * ?an be one of the following ** 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"); * *
true
indicates the name refers to a function.
*/
public void setFunction(boolean value) {
ctName.setFunction(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.
*
* @return true
indicates the name refers to a function.
*/
public boolean getFunction() {
return ctName.getFunction();
}
/**
* 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.
*
* @param functionGroupId the function group index that defines the general category for the function
*/
public void setFunctionGroupId(int functionGroupId) {
ctName.setFunctionGroupId(functionGroupId);
}
/**
* 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.
*
* @return the function group index that defines the general category for the function
*/
public int getFunctionGroupId() {
return (int) ctName.getFunctionGroupId();
}
/**
* Get the sheets name which this named range is referenced to
*
* @return sheet name, which this named range referred to.
* Empty string if the referenced sheet name weas not found.
*/
public String getSheetName() {
if (ctName.isSetLocalSheetId()) {
// Given as explicit sheet id
int sheetId = (int)ctName.getLocalSheetId();
return workbook.getSheetName(sheetId);
} else {
String ref = getRefersToFormula();
AreaReference areaRef = new AreaReference(ref);
return areaRef.getFirstCell().getSheetName();
}
}
/**
* Is the name refers to a user-defined function ?
*
* @return true
if this name refers to a user-defined function
*/
public boolean isFunctionName() {
return getFunction();
}
/**
* Returns the comment the user provided when the name was created.
*
* @return the user comment for this named range
*/
public String getComment() {
return ctName.getComment();
}
/**
* Specifies the comment the user provided when the name was created.
*
* @param comment the user comment for this named range
*/
public void setComment(String comment) {
ctName.setComment(comment);
}
@Override
public int hashCode() {
return ctName.toString().hashCode();
}
/**
* 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
*
* @param o the object to compare this XSSFName
against.
* @return true
if the XSSFName
are equal;
* false
otherwise.
*/
@Override
public boolean equals(Object o) {
if(o == this) return true;
if (!(o instanceof XSSFName)) return false;
XSSFName cf = (XSSFName) o;
return ctName.toString().equals(cf.getCTName().toString());
}
private static void validateName(String name){
char c = name.charAt(0);
if(!(c == '_' || Character.isLetter(c)) || name.indexOf(' ') != -1) {
throw new IllegalArgumentException("Invalid name: '"+name+"'; Names must begin with a letter or underscore and not contain spaces");
}
}
}