ig.excel.ListDataValidationRule

Represents a data validation rule which allows a value from a list of accepted values to be applied to a cell.

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.
  • ig.excel.ListDataValidationRule
    Constructor

    new $.ig.excel.ListDataValidationRule( );

    Creates a new ListDataValidationRule instance.

  • allowNull
    Inherited

    .allowNull( );
    Return Type:
    boolean
    Return Type Description:
    True if a null value can be set on the cell; False otherwise.

    Gets the value which indicates whether a null, or blank, value is allowed to be set on a cell.

  • allowNull
    Inherited

    .allowNull( value:boolean );
    Return Type:
    boolean
    Return Type Description:
    True if a null value can be set on the cell; False otherwise.

    Sets the value which indicates whether a null, or blank, value is allowed to be set on a cell.

    • value
    • Type:boolean
  • clone
    Inherited

    .clone( );

    Creates a copy of this rule which can be applied to other worksheets.

  • errorMessageDescription
    Inherited

    .errorMessageDescription( );
    Return Type:
    string
    Return Type Description:
    The description to show the user or null to use a default error description.

    Gets the description which appears in the dialog box when an invalid value is applied to a cell in Microsoft Excel.

    Exceptions

    Exception Description
    ig.ArgumentException Occurs when the specified value is longer than 225 characters.

    Remarks

    This value is only used when DataValidationRule.showErrorMessageForInvalidValue is True.

    Note: the title cannot be more than 225 characters.

  • errorMessageDescription
    Inherited

    .errorMessageDescription( value:string );
    Return Type:
    string
    Return Type Description:
    The description to show the user or null to use a default error description.

    Sets the description which appears in the dialog box when an invalid value is applied to a cell in Microsoft Excel.

    • value
    • Type:string

    Exceptions

    Exception Description
    ig.ArgumentException Occurs when the specified value is longer than 225 characters.

    Remarks

    This value is only used when DataValidationRule.showErrorMessageForInvalidValue is True.

    Note: the title cannot be more than 225 characters.

  • errorMessageTitle
    Inherited

    .errorMessageTitle( );
    Return Type:
    string
    Return Type Description:
    The title to show the user or null to use a default error dialog title.

    Gets the title which appears in the dialog box when an invalid value is applied to a cell in Microsoft Excel.

    Exceptions

    Exception Description
    ig.ArgumentException Occurs when the specified value is longer than 32 characters.

    Remarks

    This value is only used when DataValidationRule.showErrorMessageForInvalidValue is True.

    Note: the title cannot be more than 32 characters.

  • errorMessageTitle
    Inherited

    .errorMessageTitle( value:string );
    Return Type:
    string
    Return Type Description:
    The title to show the user or null to use a default error dialog title.

    Sets the title which appears in the dialog box when an invalid value is applied to a cell in Microsoft Excel.

    • value
    • Type:string

    Exceptions

    Exception Description
    ig.ArgumentException Occurs when the specified value is longer than 32 characters.

    Remarks

    This value is only used when DataValidationRule.showErrorMessageForInvalidValue is True.

    Note: the title cannot be more than 32 characters.

  • errorStyle
    Inherited

    .errorStyle( );
    Return Type:
    ig.excel.DataValidationErrorStyle
    Return Type Description:
    Returns a DataValidationErrorStyle.

    Gets the value which indicates whether the value is allowed when it is invalid and which options are given to the user in the error dialog shown by Microsoft Excel.

    Exceptions

    Exception Description
    ig.excel.InvalidEnumArgumentException Occurs when the value is not a member of the DataValidationErrorStyle enumeration.

    Remarks

    This value is only used when DataValidationRule.showErrorMessageForInvalidValue is True.

  • errorStyle
    Inherited

    .errorStyle( value:ig.excel.DataValidationErrorStyle );
    Return Type:
    ig.excel.DataValidationErrorStyle
    Return Type Description:
    Returns a DataValidationErrorStyle.

    Sets the value which indicates whether the value is allowed when it is invalid and which options are given to the user in the error dialog shown by Microsoft Excel.

    • value
    • Type:ig.excel.DataValidationErrorStyle

    Exceptions

    Exception Description
    ig.excel.InvalidEnumArgumentException Occurs when the value is not a member of the DataValidationErrorStyle enumeration.

    Remarks

    This value is only used when DataValidationRule.showErrorMessageForInvalidValue is True.

  • getValuesFormula

    .getValuesFormula( address:string );
    Return Type:
    string
    Return Type Description:
    A formula used to validate the value applied to a cell.

    Gets the formula which specifies the accepted values.

    • address
    • Type:string
    • The address of the cell or region that serves as the basis for relative references, or null to use the top-left cell of the worksheet.

    Exceptions

    Exception Description
    ig.ArgumentException Occurs when address is not a valid cell or regions address.

    Remarks

    The is a string containing the list of accepted values or a reference to a cell or region in the same Workbook which contains the accepted values.

    If the formula equals a string, it will be a list of accepted value, such as ="A,B,C". If one of the values must contain a double quote ("), the character will be repeated in the list, like so: ="A,""B"",C". This will allow the values A, "B", and C. The separator between values will be a comma (,), unless the decimal separator for the current culture is a comma, in which case the separator will be a semicolon (;).

    If the formula equals one or more references, it will be a reference to a single cell or region in the same Workbook. Union, intersection, and range operators are not allowed. An formula might be something like =$A$1 or =Sheet2!$A$1:$A$5. In addition to a single cell or region, a named reference can also be used, but only if it refers to a single cell or region. If a region is specified, or a named reference that refers to a region, the region will consist of a single row or column. A formula that equals an error value can also be returned, but will cause the cell to not accept any values and the drop down to be empty, so it is not very useful.

    The address passed in is only needed if relative addresses are used in the the formula. For example, consider the formula applied is =B1, and the data validation rule is applied to the region A1:A5. If you get the formula for A1, the formula =B1 will be returned. If you get the formula for A2, =B2 will be returned. Similarly, for cell A5, =B5 will be returned. However, if the formula contains no references or all absolute references, the address is ignored. So in the previous example, if the original formula was =$B$1, the same formula will be returned regardless of the specified address.

    address can be any valid cell or region reference on a worksheet. If a region address is specified, the top-left cell or the region is used. The cell or region specified does not need to have the data validation rule applied to it. Any reference is allowed.

    The cell reference mode with which to parse address will be assumed to be A1, unless the data validation rule is applied to a worksheet which is in a workbook, in which case the Workbook.cellReferenceMode will be used.

  • getValuesFormula

    .getValuesFormula( address:string, format:ig.excel.WorkbookFormat, cellReferenceMode:ig.excel.CellReferenceMode, culture:string );
    Return Type:
    string
    Return Type Description:
    A formula used to validate the value applied to a cell.

    Gets the formula which specifies the accepted values.

    • address
    • Type:string
    • The address of the cell or region that serves as the basis for relative references, or null to use the top-left cell of the worksheet.
    • format
    • Type:ig.excel.WorkbookFormat
    • The workbook format with which to parse address.
    • cellReferenceMode
    • Type:ig.excel.CellReferenceMode
    • The cell reference mode with which to parse address.
    • culture
    • Type:string
    • The culture to use when generating the formula string.

    Exceptions

    Exception Description
    ig.ArgumentException Occurs when address is not a valid cell or regions address.
    ig.excel.InvalidEnumArgumentException Occurs when format is not defined in the WorkbookFormat enumeration.
    ig.excel.InvalidEnumArgumentException Occurs when cellReferenceMode is not defined in the CellReferenceMode enumeration.

    Remarks

    The is a string containing the list of accepted values or a reference to a cell or region in the same Workbook which contains the accepted values.

    If the formula equals a string, it will be a list of accepted value, such as ="A,B,C". If one of the values must contain a double quote ("), the character will be repeated in the list, like so: ="A,""B"",C". This will allow the values A, "B", and C. The separator between values will be a comma (,), unless the decimal separator for the current culture is a comma, in which case the separator will be a semicolon (;).

    If the formula equals one or more references, it will be a reference to a single cell or region in the same Workbook. Union, intersection, and range operators are not allowed. An formula might be something like =$A$1 or =Sheet2!$A$1:$A$5. In addition to a single cell or region, a named reference can also be used, but only if it refers to a single cell or region. If a region is specified, or a named reference that refers to a region, the region will consist of a single row or column. A formula that equals an error value can also be returned, but will cause the cell to not accept any values and the drop down to be empty, so it is not very useful.

    The address passed in is only needed if relative addresses are used in the the formula. For example, consider the formula applied is =B1, and the data validation rule is applied to the region A1:A5. If you get the formula for A1, the formula =B1 will be returned. If you get the formula for A2, =B2 will be returned. Similarly, for cell A5, =B5 will be returned. However, if the formula contains no references or all absolute references, the address is ignored. So in the previous example, if the original formula was =$B$1, the same formula will be returned regardless of the specified address.

    address can be any valid cell or region reference on a worksheet. If a region address is specified, the top-left cell or the region is used. The cell or region specified does not need to have the data validation rule applied to it. Any reference is allowed.

  • inputMessageDescription
    Inherited

    .inputMessageDescription( );
    Return Type:
    string
    Return Type Description:
    The description to show the user in the tooltip.

    Gets the description in the tooltip which appears when the user selects the cell in Microsoft Excel.

    Exceptions

    Exception Description
    ig.ArgumentException Occurs when the specified value is longer than 255 characters.

    Remarks

    This value is only used when DataValidationRule.showInputMessage is True.

    Note: the description cannot be more than 255 characters.

  • inputMessageDescription
    Inherited

    .inputMessageDescription( value:string );
    Return Type:
    string
    Return Type Description:
    The description to show the user in the tooltip.

    Sets the description in the tooltip which appears when the user selects the cell in Microsoft Excel.

    • value
    • Type:string

    Exceptions

    Exception Description
    ig.ArgumentException Occurs when the specified value is longer than 255 characters.

    Remarks

    This value is only used when DataValidationRule.showInputMessage is True.

    Note: the description cannot be more than 255 characters.

  • inputMessageTitle
    Inherited

    .inputMessageTitle( );
    Return Type:
    string
    Return Type Description:
    The title to show the user in the tooltip.

    Gets the title in the tooltip which appears when the user selects the cell in Microsoft Excel.

    Exceptions

    Exception Description
    ig.ArgumentException Occurs when the specified value is longer than 32 characters.

    Remarks

    This value is only used when DataValidationRule.showInputMessage is True.

    Note: the title cannot be more than 32 characters.

  • inputMessageTitle
    Inherited

    .inputMessageTitle( value:string );
    Return Type:
    string
    Return Type Description:
    The title to show the user in the tooltip.

    Sets the title in the tooltip which appears when the user selects the cell in Microsoft Excel.

    • value
    • Type:string

    Exceptions

    Exception Description
    ig.ArgumentException Occurs when the specified value is longer than 32 characters.

    Remarks

    This value is only used when DataValidationRule.showInputMessage is True.

    Note: the title cannot be more than 32 characters.

  • isEquivalentTo

    .isEquivalentTo( other:ig.excel.DataValidationRule );
    Return Type:
    boolean
    Return Type Description:
    Returns true if the specified other has the same settings as this rule.

    Indicates if this rule is structurally equivalent to another.

    • other
    • Type:ig.excel.DataValidationRule
    • The rule to compare against
  • setValues

    .setValues( values:object[] );

    Sets the list of accepted values the cell can accept.

    • values
    • Type:object[]
    • The list of accepted values.

    Exceptions

    Exception Description
    ig.ArgumentNullException Occurs when values is null and the rule is currently applied to a Worksheet.
    ig.ArgumentException Occurs when the values array is empty.

    Remarks

    If LimitedValueDataValidationRule.allowNull is True, null values are allowed in addition to the list of accepted values.

    All values will have ToString called on them to covert the accepted values list to a formula.

    Note: the formula of accepted values is created by separating each value with a function parameter separator and concatenating them into a single string. So a list of 1, 2, and 3 would have the following formula created: ="1,2,3". However, if the decimal separator of the current culture is a comma (,) then a semicolon (;) will be used to separate the values instead. Because of this, if the ToString of a value returns a string which contains one of these separators, the value will be split into two or more allowed values.

  • setValuesFormula

    .setValuesFormula( valuesFormula:string, address:string );

    Sets the formula which specifies the accepted values.

    • valuesFormula
    • Type:string
    • The formula which provides the accepted values for the rule.
    • address
    • Type:string
    • The address of the cell or region that serves as the basis for relative references, or null to use the top-left cell of the worksheet.

    Exceptions

    Exception Description
    ig.ArgumentNullException Occurs when valuesFormula is null and the rule is currently applied to a Worksheet.
    ig.excel.FormulaParseException Occurs when valuesFormula is not a valid formula.
    ig.ArgumentException Occurs when the specified value contains something other than a string or reference.
    ig.ArgumentException Occurs when the specified value contains a region reference which has more than one row and column.
    ig.ArgumentException Occurs when address is not a valid cell or regions address.

    Remarks

    The formula must be a string containing the list of accepted values or a reference to a cell or region in the same Workbook which contains the accepted values.

    If a formula equaling a string is specified, it must be a string literal and it cannot be concatenated. For example, an acceptable formula would be ="A,B,C". If one of the values must contain a double quote ("), the character should be repeated in the list, like so: ="A,""B"",C". This will allow the values A, "B", and C. The separator between values must be a comma (,), unless the decimal separator for the current culture is a comma, in which case the separator must be a semicolon (;).

    If a formula equaling one or more references is specified, it must be a reference to a single cell or region in the same Workbook. Union, intersection, and range operators are not allowed. An acceptable formula might be =$A$1 or =Sheet2!$A$1:$A$5. In addition to a single cell or region, a named reference can also be used, but only if it refers to a single cell or region. If a region is specified, or a named reference that refers to a region, the region must consist of a single row or column. A formula that equals an error value is also allowed, but will cause the cell to not accept any values and the drop down to be empty, so it is not very useful.

    The address passed in is only needed if relative addresses are used in the the formula. When the data validation rule is applied to cells or regions, the references in the formula used by each individual cell will be shifted by the offset of the cell to the passed in address. For example, consider the formula specified is =B1 and the specified address is A1. If the data validation rule is then applied to the A5 cell, the formula is will use is =B5. However, if the references in the formula are absolute, such as =$B$1, the same formula will be applied regardless of the specified address.

    address can be any valid cell or region reference on a worksheet. If a region address is specified, the top-left cell or the region is used. The cell or region specified does not need to have the data validation rule applied to it. Any reference is allowed.

    The cell reference mode with which to parse address will be assumed to be A1, unless the data validation rule is applied to a worksheet which is in a workbook, in which case the Workbook.cellReferenceMode will be used.

  • setValuesFormula

    .setValuesFormula( valuesFormula:string, address:string, format:ig.excel.WorkbookFormat, cellReferenceMode:ig.excel.CellReferenceMode, culture:string );

    Sets the formula which specifies the accepted values.

    • valuesFormula
    • Type:string
    • The formula which provides the accepted values for the rule.
    • address
    • Type:string
    • The address of the cell or region that serves as the basis for relative references, or null to use the top-left cell of the worksheet.
    • format
    • Type:ig.excel.WorkbookFormat
    • The workbook format with which to parse address.
    • cellReferenceMode
    • Type:ig.excel.CellReferenceMode
    • The cell reference mode with which to parse address.
    • culture
    • Type:string
    • The culture to use when parsing the formula string.

    Exceptions

    Exception Description
    ig.ArgumentNullException Occurs when valuesFormula is null and the rule is currently applied to a Worksheet.
    ig.excel.FormulaParseException Occurs when valuesFormula is not a valid formula.
    ig.ArgumentException Occurs when the specified value contains something other than a string or reference.
    ig.ArgumentException Occurs when the specified value contains a region reference which has more than one row and column.
    ig.ArgumentException Occurs when address is not a valid cell or regions address.
    ig.excel.InvalidEnumArgumentException Occurs when format is not defined in the WorkbookFormat enumeration.
    ig.excel.InvalidEnumArgumentException Occurs when cellReferenceMode is not defined in the CellReferenceMode enumeration.

    Remarks

    The formula must be a string containing the list of accepted values or a reference to a cell or region in the same Workbook which contains the accepted values.

    If a formula equaling a string is specified, it must be a string literal and it cannot be concatenated. For example, an acceptable formula would be ="A,B,C". If one of the values must contain a double quote ("), the character should be repeated in the list, like so: ="A,""B"",C". This will allow the values A, "B", and C. The separator between values must be a comma (,), unless the decimal separator for the current culture is a comma, in which case the separator must be a semicolon (;).

    If a formula equaling one or more references is specified, it must be a reference to a single cell or region in the same Workbook. Union, intersection, and range operators are not allowed. An acceptable formula might be =$A$1 or =Sheet2!$A$1:$A$5. In addition to a single cell or region, a named reference can also be used, but only if it refers to a single cell or region. If a region is specified, or a named reference that refers to a region, the region must consist of a single row or column. A formula that equals an error value is also allowed, but will cause the cell to not accept any values and the drop down to be empty, so it is not very useful.

    The address passed in is only needed if relative addresses are used in the the formula. When the data validation rule is applied to cells or regions, the references in the formula used by each individual cell will be shifted by the offset of the cell to the passed in address. For example, consider the formula specified is =B1 and the specified address is A1. If the data validation rule is then applied to the A5 cell, the formula is will use is =B5. However, if the references in the formula are absolute, such as =$B$1, the same formula will be applied regardless of the specified address.

    address can be any valid cell or region reference on a worksheet. If a region address is specified, the top-left cell or the region is used. The cell or region specified does not need to have the data validation rule applied to it. Any reference is allowed.

  • showDropdown

    .showDropdown( );

    Gets the value which indicates whether a drop down should be displayed in Microsoft Excel with the list of accepted values.

    Remarks

    If this is True, a drop down arrow will be displayed next to the cell when it is selected. When the user clicks the drop down arrow, a drop down will be displayed with the list of accepted values.

  • showDropdown

    .showDropdown( value:boolean );

    Sets the value which indicates whether a drop down should be displayed in Microsoft Excel with the list of accepted values.

    • value
    • Type:boolean

    Remarks

    If this is True, a drop down arrow will be displayed next to the cell when it is selected. When the user clicks the drop down arrow, a drop down will be displayed with the list of accepted values.

  • showErrorMessageForInvalidValue
    Inherited

    .showErrorMessageForInvalidValue( );
    Return Type:
    boolean
    Return Type Description:
    True to show the error dialog for invalid cell data; False otherwise.

    Gets the value which indicates whether the error dialog should appear in Microsoft Excel when invalid data is entered in the cell.

    Remarks

    When the value is False, invalid data can be entered into cells, but when the user chooses to subsequently circle invalid values in Microsoft Excel, the cell will be circled.

  • showErrorMessageForInvalidValue
    Inherited

    .showErrorMessageForInvalidValue( value:boolean );
    Return Type:
    boolean
    Return Type Description:
    True to show the error dialog for invalid cell data; False otherwise.

    Sets the value which indicates whether the error dialog should appear in Microsoft Excel when invalid data is entered in the cell.

    • value
    • Type:boolean

    Remarks

    When the value is False, invalid data can be entered into cells, but when the user chooses to subsequently circle invalid values in Microsoft Excel, the cell will be circled.

  • showInputMessage
    Inherited

    .showInputMessage( );

    Gets the value which indicates whether to show the user an input prompt tooltip when the user selects the cell in Microsoft Excel.

    Remarks

    The input prompt will only be shown if this value is True and the DataValidationRule.inputMessageDescription is not null.

  • showInputMessage
    Inherited

    .showInputMessage( value:boolean );

    Sets the value which indicates whether to show the user an input prompt tooltip when the user selects the cell in Microsoft Excel.

    • value
    • Type:boolean

    Remarks

    The input prompt will only be shown if this value is True and the DataValidationRule.inputMessageDescription is not null.

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