Spread Windows Forms 13.0 Product Documentation
Spread Windows Forms 13.0 Product Documentation / Developer's Guide / Managing Data on a Sheet / Validating User Input
In This Topic
    Validating User Input
    In This Topic

    You can validate the contents of the cell in a number of ways. Some validation is performed by the Spread component automatically, based on the type of cell.

    You can also use the validator classes to assign a validator to a cell. For more information, refer to Using Validation in Cells.

    Beyond this, to validate the input from a user, you can look for an event and run a validation routine based on the occurrence of that event. Another simple way to check whether the user enters data that is valid based on the cell type is by using the IsValid method, which is available in all the cell type classes.

    Cell Type Validation

    The cell validates user input and verifies that it fits the requirements of the cell type's format and settings. At run time, the component checks data either when it is entered by the user or code, when the component loses the focus, or both. The component validates data as it is provided, for example, as the user types the data, and when the component loses focus. Users can enter data by typing or pasting; data from code can come from property settings or a database. In general, all these methods of entering data are handled in the same way by the component, which checks the data to determine if it is valid.

    Values in the component that are less than the setting of the minimum value (MinimumValue or MinimumDate, or MinimumTime property) are allowed in the component. Components must allow values less than the minimum to let users provide a partial value that is later changed to a value greater than the minimum value. For example, if the MinimumValue property is set to 100, and the user tries to change the value to 124 by selecting the existing value and typing, as the user types the value changes to "1", which is less than the allowed minimum value. However, as the user types the value becomes "12" and then "124". The final value is above the allowed minimum value. The value provided by the user is checked to see if it is less than the minimum value when the control loses the focus.

    When the control is validating data as it comes into the component, if the user tries to provide invalid data, or invalid data is coming from code or a database, the UserError event occurs.

    Each cell type has some default restrictions to determine what is valid data. For example, the currency cell type regards a text string of characters such as "abcd" as an invalid value because it expects numeric data. In addition, you can set properties for each cell type that specify valid data settings.

    The following table lists the default data allowed in each of the editable cell types.

    Cell Type Default Valid Data Examples

    Currency

    Numeric data, which can include characters for the currency symbol, a separator, and a decimal symbol

    $3.45

    $1,234.56

    £45

    DateTime

    Date and time data, which can include separator characters

    8/16/2002,

    Monday, August 05, 2002 4:40 PM

    GcDateTime

    Date and time data, which can include separator characters

    8/16/2002,

    Monday, August 05, 2002 4:40 PM

    GcCharMask or GcMask

    Any character is accepted that fits the mask string criteria

     

    GcComboBox or GcTextBox

    Any character is accepted

     

    GcNumber

    Numeric data, which can include characters for a separator and a decimal symbol

    3.45

    1,234.56

    GcTimeSpan

    TimeSpan data, which can include separator characters

     

    Hyperlink

    Any character is accepted.

     

    General

    Any character is accepted.

     

    Mask

    Any character is accepted that fits the mask string criteria

     

    Number

    Numeric data, which can include characters for a separator and a decimal symbol

    3.45

    1,234.56

    Percent

    Numeric data, which can include characters for the percent symbol, a separator, and a decimal symbol

    0.5

    1,234%

    Text

    Any character is accepted.

     

    For more information about differences between these cell types, refer to the Customizing Interaction with Cell Types.

    The following table lists the additional properties you can set for each cell type that specify valid data settings.

    Cell Type Cell Type Properties for Defining Valid Data
    Currency MaximumValue, MinimumValue
    DateTime MaximumDate, MinimumDate, MaximumTime, MinimumTime
    GcCharMask FormatString
    GcCharMask or GcMask Pattern, MaxLength, MinLength
    GcComboBox MaxLength, MaxLengthUnit, FormatString
    GcDateTime MaxDate, MinDate, MaxMinBehavior
    GcNumber MaxValue, MinValue, MaxMinBehavior, ValueSign
    GcTextBox MaxLength, MaxLengthUnit, MaxLengthCodePage, FormatString
    GcTimeSpan MaxValue, MinValue, MaxMinBehavior, ValueSign
    Number MaximumValue, MinimumValue
    Mask Mask, MaskChar
    Percent MaximumValue, MinimumValue
    Text MaxLength

    The following table lists how invalid data is handled by the number and text cell types. The Column and Cell headings in the table refer to entering the data at the column or cell level.

    Action Text Cell   Number Cell  
      Column Cell Column Cell

    Input invalid cell text while cell is in edit mode

    +*

    +*

    +*

    +*

    Paste invalid cell text while cell is in edit mode

    #*

    #*

    +*

    +*

    Paste invalid cell text while cell is not in editmode

    #*

    #*

    +*

    +*

    Paste copied cell with cell type and invalid value while not in edit mode

    ##**

    ##**

    ##**

    ##**

    Paste copied cell with invalid value and cell type not set while cell is not in edit mode

    #*

    #*

    +*

    +*

    Input invalid value with cell Value property (or ISheetDataModel SetValue method)

    ++**

    ++**

    ++**

    ++**

    Input invalid string value with cell Text property (or SheetView SetText method)

    #**

    #**

    +**

    +**

    Input invalid cell value with SheetView SetValue method (validate = false)

    ++**

    ++**

    ++**

    ++**

    Input invalid cell value with SheetView SetValue method (validate = true)

    +**

    +**

    +**

    +**

    Set invalid cell type after binding

    ++**

    ++**

    ++**

    ++**

    Use the ClipboardPasteValues field to paste invalid cell value while cell is not in edit mode

    #*

    #*

    +*

    +*

    DragFillMode.Copy (the operation is canceled if the cell is locked)

    #*

    #*

    +*

    +*

    DragFillMode.Series (the operation is canceled if the cell is locked)

    #*

    #*

    +*

    +*

    The following list defines the conditions in the above table:

    Event-based Validation

    You can check for an event and run a validation routine based on the occurrence of that event. For instance, the Changed event in the SheetView class notifies your application that the user has left edit mode and the contents of the cell has changed. For more thorough validation, to handle the case where a user pastes a value from the Clipboard as opposed to typing in a value, use the Changed event on the data model (DefaultSheetDataModel class). This is a good way to evaluate the contents of a cell after it has been edited, and throw an error message or revert to original value if the data in the cell is not valid. For more information about using events, refer to Managing Events from User Actions.

    IsValid Method Validation

    The IsValid method for the cell type classes checks whether a value is valid for the cell editor. Spread uses that method internally to check values coming out of the cell editor to ensure that they are valid. In most cases, it will return True if the Format method is able to format the specified non-string value into a string to display in the editor, or whether the Parse method is able to parse the specified string value into a value of the appropriate type for the cell.

    For advanced users, you can evaluate the contents of a cell after it has been edited, and throw an error message and revert to the original value if the data in the cell is not valid. To do this requires handling the EditModeOn event and setting properties in SuperEditBase and thus GeneralEditor on the editor control each time edit mode is turned on. These properties include InvalidOption, InvalidColor, CanValidate, and UserEntry, but this requires a more involved process. At the time the EditModeOff event is raised, the value in the data model has already been changed. Handle EditModeOn and store the cell's value and then in the EditModeOff event if the current value of the cell fails your validation, reset the value to the stored value.

    See Also