ig.excel.NamedReference

Represents a named reference defined in the workbook.

Remarks

Named references allow for names to be used in formulas instead of complex formulas or cell references. For example, instead of using the formula =SUM(E1:E20), a named reference with a name of 'Sales' can be defined to point to the range of E1:E20 (the named reference's formula would be defined like this: =Sheet1!$E$1:$E$20). Then the original formula could be expressed as =SUM(Sales).

Each named reference has an associated scope, which can either be the NamedReference.workbook to which the named reference belongs or one of the Worksheet instances in the Workbook. The scope determines how the name must be referenced in formulas for different cells. A scope of the workbook means the named reference must be accessed by a formula in any cell of the workbook by specifying only the name. A scope of the worksheet means formulas used in other worksheets must reference the name by first specifying the worksheet scope, such as =SUM( Sheet2!Sales ). If the formula is in the same worksheet as the scope of the named reference, the formula can reference the name with or without the worksheet name.

Named references from external workbooks must always be referenced with the scope first. If the named reference's scope is the external workbook, the name is accessed by specifying the workbook file name followed by the name, such as in the following formula: ='C:\ExternalWorkbook.xls'!SalesTax. If the named reference has a scope of a worksheet in the workbook, it is referenced by specifying the file name, worksheet, and name: ='C:\[ExternalWorkbook.xls]Sheet1'!SalesTax.

Named references with different scopes can have the same names, but if two named references have the same scope, they must have case-insensitively unique names.

Dependencies

jquery-1.4.4.js
infragistics.util.js
infragistics.ext_core.js
infragistics.ext_collections.js
infragistics.ext_collectionsExtended.js
infragistics.ext_io.js
infragistics.ext_text.js
infragistics.documents.core_core.js
infragistics.ext_ui.js
The current widget has no options.
The current widget has no events.

  • comment
    Inherited

    .comment( );
    Return Type:
    string
    Return Type Description:
    The comment associated with the named reference or table.

    Gets the comment associated with the named reference or table.

    Exceptions

    Exception Description
    ig.ArgumentException The value assigned is greater than 255 characters in length.

  • comment
    Inherited

    .comment( value:string );
    Return Type:
    string
    Return Type Description:
    The comment associated with the named reference or table.

    Sets the comment associated with the named reference or table.

    • value
    • Type:string

    Exceptions

    Exception Description
    ig.ArgumentException The value assigned is greater than 255 characters in length.

  • formula

    .formula( );
    Return Type:
    string
    Return Type Description:
    The formula which defines the named reference.

    Gets the formula which defines the named reference.

    See Also

  • isSimpleReferenceFormula

    .isSimpleReferenceFormula( );

    Gets the value indicating whether the NamedReference.formula is a simple formula referring to a single cell, a single region, or multiple regions in the same workbook as the named reference.

    Remarks

    If the reference is surrounded by parentheses or whitespace or the named reference has some other complex formula this will return false.

  • name
    Inherited

    .name( );
    Return Type:
    string
    Return Type Description:
    The name of the reference.

    Gets the name of the reference.

    Exceptions

    Exception Description
    ig.ArgumentNullException The value assigned is null or empty.
    ig.ArgumentException The value assigned is longer than 255 characters.
    ig.ArgumentException The value assigned is not a valid named reference. The name must begin with a letter, underscore (_), or a backslash (\). All other characters in the name must be letters, numbers, periods, underscores (_), or backslashes (\). The name cannot be a an A1 cell reference (1 to 3 letters followed by 1 to 6 numbers). In addition, the name cannot be 'r', 'R', 'c', or 'C' or start with a row or column reference in R1C1 cell reference mode ('R' followed by 1 to 6 numbers or 'C' followed by 1 to 6 numbers).
    ig.InvalidOperationException The value assigned is the name of another named reference with the same Scope. Names are compared case-insensitively.

    Remarks

    See the overview on NamedReferenceBase.scope for details on how to access a named reference by name in formulas.

  • name
    Inherited

    .name( value:string );
    Return Type:
    string
    Return Type Description:
    The name of the reference.

    Sets the name of the reference.

    • value
    • Type:string

    Exceptions

    Exception Description
    ig.ArgumentNullException The value assigned is null or empty.
    ig.ArgumentException The value assigned is longer than 255 characters.
    ig.ArgumentException The value assigned is not a valid named reference. The name must begin with a letter, underscore (_), or a backslash (\). All other characters in the name must be letters, numbers, periods, underscores (_), or backslashes (\). The name cannot be a an A1 cell reference (1 to 3 letters followed by 1 to 6 numbers). In addition, the name cannot be 'r', 'R', 'c', or 'C' or start with a row or column reference in R1C1 cell reference mode ('R' followed by 1 to 6 numbers or 'C' followed by 1 to 6 numbers).
    ig.InvalidOperationException The value assigned is the name of another named reference with the same Scope. Names are compared case-insensitively.

    Remarks

    See the overview on NamedReferenceBase.scope for details on how to access a named reference by name in formulas.

  • referencedCell

    .referencedCell( );
    Return Type:
    ig.excel.WorksheetCell
    Return Type Description:
    Returns a WorksheetCell.

    Gets the WorksheetCell referenced by the NamedReference.formula.

    Remarks

    If named reference is a reference to one or more regions, this will return null.

    See Also

  • referencedRegion

    .referencedRegion( );
    Return Type:
    ig.excel.WorksheetRegion
    Return Type Description:
    Returns a WorksheetRegion.

    Gets the WorksheetRegion referenced by the NamedReference.formula.

    Remarks

    If the named reference is a reference to a single cell or multiple regions, this will return null.

    See Also

  • referencedRegions

    .referencedRegions( );

    Gets the array of WorksheetRegion instances referenced by the NamedReference.formula.

    Remarks

    If the named reference is a reference to a single cell or region, this will return null.

    See Also

  • scope
    Inherited

    .scope( );
    Return Type:
    object
    Return Type Description:
    The scope of the named reference.

    Gets the scope of the named reference.

    Remarks

    This can either be the workbook which the named reference belongs to or one of the worksheets in the workbook.

    The scope determines how formulas need to preface a name in order to use the named reference.

    If the scope is the workbook, formulas in any cell in the workbook can reference the named reference by specifying just the name or the workbook's file name, an exclamation point, and the name: =MyWorkbookName ='C:\MyWorkbook.xls'!MyWorkbookName When cells in other workbook's want to reference the named reference, they must use the second format by first specifying the file name when the workbook-scoped named reference exists.

    If the scope is a worksheet, formulas in cells of the worksheet can reference the named reference by specifying just the name. In addition, they can fully qualify the named reference with the worksheet name and, optionally, the workbook file name: =MyWorksheetName =Sheet1!MyWorksheetName ='C:\[MyWorkbook.xls]Sheet1'!MyWorksheetName Formulas in cells of other worksheets in the same workbook can use the named reference as well, but they must specify the worksheet name and, optionally, the workbook file name: =Sheet2!OtherWorksheetName ='C:\[MyWorkbook.xls]Sheet2'!OtherWorksheetName Formulas in cells of other workbooks can also used the named reference, but they must specify the workbook file name, worksheet name, and named reference name.

  • setFormula

    .setFormula( formula:string );

    Sets the formula for a named reference.

    • formula
    • Type:string
    • The string containing the formula value.

    Exceptions

    Exception Description
    ig.ArgumentNullException formula is null or empty.
    ig.ArgumentException formula is not a valid formula. The inner exception will contain the FormulaParseException describing the reason the formula was not valid.

    Remarks

    The formula will be parsed using the CellReferenceMode of the NamedReference.workbook to which the NamedReference is applied. If the NamedReference has been removed from its collection, the A1 reference mode will be used to parse the formula.

    See Also

  • setFormula

    .setFormula( formula:string, cellReferenceMode:ig.excel.CellReferenceMode );

    Sets the formula for a named reference.

    • formula
    • Type:string
    • The string containing the formula value.
    • cellReferenceMode
    • Type:ig.excel.CellReferenceMode
    • The mode used to interpret cell references in the formula.

    Exceptions

    Exception Description
    ig.ArgumentNullException formula is null or empty.
    ig.excel.InvalidEnumArgumentException cellReferenceMode is not defined in the CellReferenceMode enumeration.
    ig.ArgumentException formula is not a valid formula. The inner exception will contain the FormulaParseException describing the reason the formula was not valid.

    See Also

  • setFormula

    .setFormula( formula:string, cellReferenceMode:ig.excel.CellReferenceMode, culture:string );

    Sets the formula for a named reference.

    • formula
    • Type:string
    • The string containing the formula value.
    • cellReferenceMode
    • Type:ig.excel.CellReferenceMode
    • The mode used to interpret cell references in the formula.
    • culture
    • Type:string
    • The culture used to parse the formula.

    Exceptions

    Exception Description
    ig.ArgumentNullException formula is null or empty.
    ig.excel.InvalidEnumArgumentException cellReferenceMode is not defined in the CellReferenceMode enumeration.
    ig.ArgumentException formula is not a valid formula. The inner exception will contain the FormulaParseException describing the reason the formula was not valid.

    See Also

  • toString

    .toString( );
    Return Type:
    string
    Return Type Description:
    The string representation of the named reference.

    Gets the string representation of the named reference.

Copyright © 1996 - 2024 Infragistics, Inc. All rights reserved.