/* ==================================================================== 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.ss.usermodel; /** * 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: *{@code * 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)"); * * }*/ public interface Name { /** * Get the sheets name which this named range is referenced to * * @return sheet name, which this named range referred to */ String getSheetName(); /** * Gets the name of the named range * * @return named range name */ String getNameName(); /** * 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: *
{@code * //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)" * * }* * @param name named range name to set * @throws IllegalArgumentException if the name is invalid or the already exists within its scope (case-insensitive) */ void setNameName(String name); /** * Returns the formula that the name is defined to refer to. * * @return the reference for this name, {@code null} if it has not been set yet. Never empty string * @see #setRefersToFormula(String) */ String getRefersToFormula(); /** * Sets the formula that the name is defined to refer to. The following are representative examples: * *