[]
DEMOS DOCS API PRICING
FREE TRIAL
(Showing Draft Content)

Reference

Class Reference

java.lang.Object
com.grapecity.documents.excel.expressions.Reference
All Implemented Interfaces:
Cloneable
public final class Reference extends Object implements Cloneable
Represents a reference in a formula.

A Reference describes a cell, a range, a worksheet-qualified reference, a 3D worksheet reference, or a reference to an external workbook. Use its row, column, range, worksheet, and workbook properties to build or inspect formula references programmatically.

If a row or column index is relative, use the base row or base column in the parse or unparse context when converting the reference to text.


 FormulaSyntaxTree syntaxTree = FormulaSyntaxTree.Parse("SUM(Sheet1:Sheet3!D4:G10)");
 FunctionNode functionNode = (FunctionNode) syntaxTree.getRoot();
 ReferenceNode referenceNode = (ReferenceNode) functionNode.getChildren().get(0);
 Reference reference = referenceNode.getReference();
 reference.setLastWorksheetName(null);

 Reference addedReference = new Reference();
 addedReference.setRow(1);
 addedReference.setColumn(1);
 functionNode.getChildren().add(new ReferenceNode(addedReference));
 String formulaText = syntaxTree.toString();

  • Field Details

    • ErrorWorksheetName

      public static final String ErrorWorksheetName

  • Constructor Details

    • Reference

      public Reference()

  • Method Details

    • getWorkbook

      public WorkbookReference getWorkbook()
      Gets the external workbook reference.

      Use this method to retrieve the workbook component of an external reference, such as a reference that points to a worksheet in another workbook. The default value is null.

      
 Reference reference = new Reference();
 reference.setWorkbook(WorkbookReference.FromName("Book1"));
 WorkbookReference workbookReference = reference.getWorkbook();
      Returns:
      The external workbook reference, or null if this reference does not specify an external workbook.

    • setWorkbook

      public void setWorkbook(WorkbookReference value)
      Sets the external workbook reference.

      Use this method to associate this reference with an external workbook when building or modifying a formula reference. Set this property to null to clear the external workbook reference. The default value is null.

      
 Reference reference = new Reference();
 reference.setWorkbook(WorkbookReference.FromName("Book1"));
      Parameters:
      value - The external workbook reference to associate with this reference, or null to remove the external workbook reference.

    • getWorksheetName

      public String getWorksheetName()
      Gets the name of the worksheet.

      Use this method to retrieve the start worksheet name associated with this reference. For a 3D reference, use setLastWorksheetName(String) to set the end worksheet name.

      
 Reference reference = new Reference();
 reference.setWorksheetName("Sheet1");
 String worksheetName = reference.getWorksheetName();
      Returns:
      The worksheet name. Returns null if no worksheet name has been set.

    • setWorksheetName

      public void setWorksheetName(String value)
      Sets the name of the worksheet.

      Use this method to set or update the start worksheet name associated with this reference. For a 3D reference, use setLastWorksheetName(String) to set or update the end worksheet name.

      
 Reference reference = new Reference();
 reference.setWorksheetName("Sheet1");
      Parameters:
      value - The worksheet name, or null if no worksheet name should be set.

    • getLastWorksheetName

      public String getLastWorksheetName()
      Gets the name of the end worksheet of the 3D reference.

      Use this method together with setWorksheetName(String) to update the worksheet span represented by a 3D reference.

      
 Reference reference = new Reference();
 reference.setWorksheetName("Sheet1");
 reference.setLastWorksheetName("Sheet3");
 String lastWorksheetName = reference.getLastWorksheetName();
      Returns:
      The name of the end worksheet of the 3D reference, or null if no end worksheet name has been specified.

    • setLastWorksheetName

      public void setLastWorksheetName(String value)
      Sets the name of the end worksheet of the 3D reference.

      Use this method together with getWorksheetName() to inspect the worksheet span represented by a 3D reference.

      
 Reference reference = new Reference();
 reference.setWorksheetName("Sheet1");
 reference.setLastWorksheetName("Sheet3");
      Parameters:
      value - The name of the end worksheet of the 3D reference, or null if no end worksheet name has been specified.

    • getHasRow

      public boolean getHasRow()
      Gets whether the reference includes a row part.

      This property indicates whether the reference contains row information. The default value is true. If the reference is in an error state, this method returns false.

      
 Reference reference = new Reference();
 reference.setHasRow(false);
 boolean hasRow = reference.getHasRow();
      Returns:
      true if the reference includes a row part; otherwise, false. Returns false if the reference contains an error.

    • setHasRow

      public void setHasRow(boolean value)
      Sets whether the reference includes a row part.

      This property indicates whether the reference contains row information. The default value is true. If the reference is in an error state, this method sets false.

      
 Reference reference = new Reference();
 reference.setHasRow(false);
      Parameters:
      value - true if the reference includes a row part; otherwise, false. Sets false if the reference contains an error.

    • getHasColumn

      public boolean getHasColumn()
      Gets whether the reference includes a column part.

      This property indicates whether the reference contains column information. The default value is true. If the reference is in an error state, this method returns false.

      
 Reference reference = new Reference();
 reference.setHasColumn(false);
 boolean hasColumn = reference.getHasColumn();
      Returns:
      true if the reference includes a column part; otherwise, false. Returns false if the reference contains an error.

    • setHasColumn

      public void setHasColumn(boolean value)
      Sets whether the reference includes a column part.

      This property indicates whether the reference contains column information. The default value is true. If the reference is in an error state, this method sets false.

      
 Reference reference = new Reference();
 reference.setHasColumn(false);
      Parameters:
      value - true if the reference includes a column part; otherwise, false. Sets false if the reference contains an error.

    • getRow

      public int getRow()
      Gets the 0-based row index.

      The default value is 0. If this reference does not have a row, as indicated by getHasRow(), this method returns 0.

      
 Reference reference = new Reference();
 reference.setRow(3);
 int row = reference.getRow();
      Returns:
      The 0-based row index. Returns 0 if the reference does not have a row.

    • setRow

      public void setRow(int value)
      Sets the 0-based row index.

      The default value is 0. If this reference does not have a row, as indicated by getHasRow(), this method sets 0.

      
 Reference reference = new Reference();
 reference.setRow(3);
      Parameters:
      value - The 0-based row index. sets 0 if the reference does not have a row.

    • getColumn

      public int getColumn()
      Gets the 0-based column index.

      Returns the column index stored in this reference. The default value is 0. If getHasColumn() returns false, this method returns 0.

      
 Reference reference = new Reference();
 reference.setColumn(2);
 int column = reference.getColumn();
      Returns:
      The 0-based column index, or 0 if this reference does not have a column.

    • setColumn

      public void setColumn(int value)
      Sets the 0-based column index.

      sets the column index stored in this reference. The default value is 0. If getHasColumn() sets false, this method sets 0.

      
 Reference reference = new Reference();
 reference.setColumn(2);
      Parameters:
      value - The 0-based column index, or 0 if this reference does not have a column.

    • getLastRow

      public int getLastRow()
      Gets the 0-based end row index.

      For a range reference, this method returns the last row stored in the reference. If the reference is not a range, it returns the value of getRow(). If the reference is a range that does not contain row information, it returns the maximum row index.

      
 Reference reference = new Reference();
 reference.setIsRange(true);
 reference.setLastRow(5);
 int lastRow = reference.getLastRow();
      Returns:
      The 0-based end row index. Returns getRow() when the reference is not a range.

    • setLastRow

      public void setLastRow(int value)
      Sets the 0-based end row index.

      For a range reference, this method sets the last row stored in the reference. If the reference is not a range, it sets the value of getRow(). If the reference is a range that does not contain row information, it sets the maximum row index.

      
 Reference reference = new Reference();
 reference.setIsRange(true);
 reference.setLastRow(5);
      Parameters:
      value - The 0-based end row index. sets getRow() when the reference is not a range.

    • getLastColumn

      public int getLastColumn()
      Gets the 0-based end column index.

      If getIsRange() returns true, this method returns the last column index of the range when getHasColumn() is true; otherwise, it returns the last worksheet column index. If this reference does not represent a range, this method returns the same value as getColumn(). The default value is 0.

      
 Reference reference = new Reference();
 reference.setColumn(1);
 reference.setLastColumn(3);
 int lastColumn = reference.getLastColumn();
      Returns:
      The 0-based end column index. For a non-range reference, this is the same as the start column index.

    • setLastColumn

      public void setLastColumn(int value)
      Sets the 0-based end column index.

      If getIsRange() sets true, this method sets the last column index of the range when getHasColumn() is true; otherwise, it sets the last worksheet column index. If this reference does not represent a range, this method sets the same value as getColumn(). The default value is 0.

      
 Reference reference = new Reference();
 reference.setColumn(1);
 reference.setLastColumn(3);
      Parameters:
      value - The 0-based end column index. For a non-range reference, this is the same as the start column index.

    • getIsRowRelative

      public boolean getIsRowRelative()
      Gets whether the row part of this reference is relative.

      This property indicates whether the row is stored as a relative reference rather than an absolute one. The default value is true. If this reference contains an error, this method returns false.

      
 Reference reference = new Reference();
 reference.setRow(2);
 reference.setIsRowRelative(false);
 boolean isRowRelative = reference.getIsRowRelative();
      Returns:
      true if the row part of the reference is relative; false if it is absolute or if this reference contains an error.

    • setIsRowRelative

      public void setIsRowRelative(boolean value)
      Sets whether the row part of this reference is relative.

      This property indicates whether the row is stored as a relative reference rather than an absolute one. The default value is true. If this reference contains an error, this method sets false.

      
 Reference reference = new Reference();
 reference.setRow(2);
 reference.setIsRowRelative(false);
      Parameters:
      value - true if the row part of the reference is relative; false if it is absolute or if this reference contains an error.

    • getIsColumnRelative

      public boolean getIsColumnRelative()
      Gets whether the column part of this reference is relative.

      This property indicates whether the column is stored as a relative reference rather than an absolute one. The default value is true. If this reference contains an error, this method returns false.

      
 Reference reference = new Reference();
 reference.setColumn(1);
 reference.setIsColumnRelative(false);
 boolean isColumnRelative = reference.getIsColumnRelative();
      Returns:
      true if the column part of the reference is relative; false if it is absolute or if this reference contains an error.

    • setIsColumnRelative

      public void setIsColumnRelative(boolean value)
      Sets whether the column part of this reference is relative.

      This property indicates whether the column is stored as a relative reference rather than an absolute one. The default value is true. If this reference contains an error, this method sets false.

      
 Reference reference = new Reference();
 reference.setColumn(1);
 reference.setIsColumnRelative(false);
      Parameters:
      value - true if the column part of the reference is relative; false if it is absolute or if this reference contains an error.

    • getIsLastRowRelative

      public boolean getIsLastRowRelative()
      Gets whether the last row in the reference is relative.

      For a range reference, this method indicates whether the ending row is stored as a relative row reference. For a non-range reference, it returns the same value as getIsRowRelative(). If the reference contains an error, this method returns false.

      
 Reference reference = new Reference();
 reference.setLastRow(1);
 reference.setIsLastRowRelative(false);
 boolean isLastRowRelative = reference.getIsLastRowRelative();
      Returns:
      true if the last row is relative; otherwise, false. Returns false if the reference contains an error.

    • setIsLastRowRelative

      public void setIsLastRowRelative(boolean value)
      Sets whether the last row in the reference is relative.

      For a range reference, this method indicates whether the ending row is stored as a relative row reference. For a non-range reference, it sets the same value as getIsRowRelative(). If the reference contains an error, this method sets false.

      
 Reference reference = new Reference();
 reference.setLastRow(1);
 reference.setIsLastRowRelative(false);
      Parameters:
      value - true if the last row is relative; otherwise, false. sets false if the reference contains an error.

    • getIsLastColumnRelative

      public boolean getIsLastColumnRelative()
      Gets whether the last column part of this reference is relative.

      For a range reference, this method returns whether the end column is stored as a relative reference. For a non-range reference, it returns the same value as getIsColumnRelative(). The default value is true. If this reference contains an error, this method returns false.

      
 Reference reference = new Reference();
 reference.setColumn(0);
 reference.setLastColumn(1);
 reference.setIsLastColumnRelative(false);
 boolean isLastColumnRelative = reference.getIsLastColumnRelative();
      Returns:
      true if the last column part is relative; otherwise, false. Returns false if this reference contains an error.

    • setIsLastColumnRelative

      public void setIsLastColumnRelative(boolean value)
      Sets whether the last column part of this reference is relative.

      For a range reference, this method sets whether the end column is stored as a relative reference. For a non-range reference, it sets the same value as getIsColumnRelative(). The default value is true. If this reference contains an error, this method sets false.

      
 Reference reference = new Reference();
 reference.setColumn(0);
 reference.setLastColumn(1);
 reference.setIsLastColumnRelative(false);
      Parameters:
      value - true if the last column part is relative; otherwise, false. Sets false if this reference contains an error.

    • getIsRange

      public boolean getIsRange()
      Gets whether this reference represents a range.

      The default value is false. This method returns true when the reference has the range attribute set. If the reference contains an error, this method returns false.

      
 Reference reference = new Reference();
 reference.setLastColumn(1);
 boolean isRange = reference.getIsRange();
      Returns:
      true if this reference represents a range; otherwise, false.

    • setIsRange

      public void setIsRange(boolean value)
      Sets whether this reference represents a range.

      The default value is false. This method sets true when the reference has the range attribute set. If the reference contains an error, this method sets false.

      
 Reference reference = new Reference();
 reference.setLastColumn(1);
 reference.setIsRange(true);
      Parameters:
      value - true if this reference represents a range; otherwise, false.

    • getIsError

      public boolean getIsError()
      Gets whether the reference contains an error.

      The default value is false. This method returns true when the reference has the error flag, when the worksheet name is "#REF", or when the reference points to an external workbook without a worksheet name.

      
 Reference reference = new Reference();
 reference.setIsError(true);
 boolean isError = reference.getIsError();
      Returns:
      true if the reference contains an error; otherwise, false.

    • setIsError

      public void setIsError(boolean value)
      Sets whether the reference contains an error.

      The default value is false. This method sets true when the reference has the error flag, when the worksheet name is "#REF", or when the reference points to an external workbook without a worksheet name.

      
 Reference reference = new Reference();
 reference.setIsError(true);
      Parameters:
      value - true if the reference contains an error; otherwise, false.

    • toString

      public String toString()
      Converts the reference to A1 string.
      Overrides:
      toString in class Object
      Returns:
      The A1-style String representation of this reference.

    • toString

      public String toString(UnParseContext context)
      Converts the reference to text using the specified unparse context.

      Use UnParseContext to control how the reference is converted, including whether the result uses A1 or R1C1 notation and which base row and base column are applied when relative references are resolved.

      
 Reference reference = new Reference();
 reference.setRow(1);
 reference.setColumn(2);
 UnParseContext context = new UnParseContext();
 context.setIsR1C1(true);
 String text = reference.toString(context);
      Parameters:
      context - The context that specifies how the reference is converted. Must not be null.
      Returns:
      The text representation of this reference in the format specified by context.
      Throws:
      NullPointerException - if context is null.

    • equals

      public boolean equals(Object obj)
      Compares this reference with another object.

      If obj is a Reference, this method compares it by using equals(Reference). If obj is null or is not a Reference, this method returns false.

      Overrides:
      equals in class Object
      Parameters:
      obj - The object to compare with this reference. Can be null.
      Returns:
      true if obj is a Reference that is equal to this reference; otherwise, false.

    • equals

      public boolean equals(Reference other)
      Compares this reference with another Reference instance for equality.

      This method compares the reference kind and the corresponding reference attributes, such as row, column, range bounds, worksheet names, and workbook reference, when those parts are present in the reference. If both references represent an error reference, this method returns true.

      Use equals(Object) when comparing through late binding.

      Parameters:
      other - The reference to compare with. Must not be null.
      Returns:
      true if the specified reference is equal to this reference; otherwise, false.
      Throws:
      NullPointerException - if other is null.

    • hashCode

      public int hashCode()
      Returns the hash code for this reference type.

      This implementation does not derive the hash code from the current state of the reference. Because all reference fields are mutable, it always returns the hash code of Reference itself.

      Overrides:
      hashCode in class Object
      Returns:
      The hash code of the Reference class.

    • clone

      public Reference clone()
      Creates a copy of this reference.

      The returned Reference contains the same reference settings as this instance, including workbook, worksheet, row, column, and kind information. This method performs a shallow copy.

      Overrides:
      clone in class Object
      Returns:
      A new Reference instance that copies the current reference settings.