123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205 |
- /* ====================================================================
- 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.
- * <p>
- * A name is a meaningful shorthand that makes it easier to understand the purpose of a
- * cell reference, constant or a formula.
- * </p>
- * Examples:
- * <pre>{@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)");
- *
- * }</pre>
- */
- 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
- *
- * <p>The following is a list of syntax rules that you need to be aware of when you create and edit names.</p>
- * <ul>
- * <li><strong>Valid characters</strong>
- * 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.
- * </li>
- * <li><strong>Cell references disallowed</strong>
- * Names cannot be the same as a cell reference, such as Z$100 or R1C1.</li>
- * <li><strong>Spaces are not valid</strong>
- * 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.
- * </li>
- * <li><strong>Name length</strong>
- * A name can contain up to 255 characters.
- * </li>
- * <li><strong>Case sensitivity</strong>
- * Names can contain uppercase and lowercase letters.
- * </li>
- * </ul>
- * <p>
- * 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:
- * <pre>{@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)"
- *
- * }</pre>
- *
- * @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:
- *
- * <ul>
- * <li>{@code 'My Sheet'!$A$3}</li>
- * <li>{@code 8.3}</li>
- * <li>{@code HR!$A$1:$Z$345}</li>
- * <li>{@code SUM(Sheet1!A1,Sheet2!B2)}</li>
- * <li>{@code -PMT(Interest_Rate/12,Number_of_Payments,Loan_Amount)}</li>
- * </ul>
- *
- * 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
- *
- * @param formulaText the reference for this name
- * @throws IllegalArgumentException if the specified formulaText is unparsable
- */
- void setRefersToFormula(String formulaText);
-
- /**
- * Checks if this name is a function name
- *
- * @return true if this name is a function name
- */
- boolean isFunctionName();
-
- /**
- * Checks if this name points to a cell that no longer exists
- *
- * @return {@code true} if the name refers to a deleted cell, {@code false} otherwise
- */
- boolean isDeleted();
-
- /**
- * Checks if this name is hidden, eg one of the built-in Excel
- * internal names
- *
- * @return {@code true} if the name is a hidden name, {@code false} otherwise
- */
- boolean isHidden();
-
- /**
- * Tell Excel that this name applies to the worksheet with the specified index instead of the entire workbook.
- *
- * @param sheetId the sheet index this name applies to, -1 unsets this property making the name workbook-global
- * @throws IllegalArgumentException if the sheet index is invalid.
- */
- void setSheetIndex(int sheetId);
-
- /**
- * Returns the sheet index this name applies to.
- *
- * @return the sheet index this name applies to, -1 if this name applies to the entire workbook
- */
- int getSheetIndex();
-
- /**
- * Returns the comment the user provided when the name was created.
- *
- * @return the user comment for this named range
- */
- String getComment();
-
- /**
- * Sets the comment the user provided when the name was created.
- *
- * @param comment the user comment for this named range
- */
- void setComment(String comment);
-
- /**
- * 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.
- *
- * @param value {@code true} indicates the name refers to a function.
- */
- void setFunction(boolean value);
- }
|