Menu
▾
▴
Spark Validators
Functional and Design Specification
Glossary
Locale data - All the data that is required by a framework/application/API in order to be able to honor various cultural conventions in a specific language and region. The data consist of month and day names, date patterns, decimal and thousand separators for number formatting, rules for language specific sorting, info on the measurement system used, and so on. The exact type of data each system chooses to store differs between systems.
Locale - In the context of this document, locale refers to the language, script, and region for which an operating system has a collection of locale data as described above. The identification of a locale can be further tailored using variants and keywords. See Locale ID below.
Locale ID - A string that identifies a locale. In the context of this specification, locale IDs use the syntax defined in Unicode Technical Standard #35, Unicode Locale Data Markup Language (LDML). In this syntax a locale ID consists of several sub-tags, that specify the language, script, region, variants, and key value pairs. E.g. the locale ID for Germany using the German language and sorting by the phonebook sort order is: de-DE@collation=phonebook. Note that not all sub-tags are required; in this case the script is inferred from the language.
Validator - A software component that ensures that an input string meets the format and criteria specified by the Validator type and set of properties. Examples include Validators for numbers, currency amounts and date time strings.
flash.globalization - A new package added to Flash player version 10.1 to access locale-specific functionality provided by the operating system on which the Flash player is running.
NumberFormatter - A class in flash.globalization that provides locale specific formatting of numbers. This class also contains properties which provide the locale specific data used in formatting numbers. For example: decimal separator, grouping separator, digits type, negative symbol, negative number format, etc. A corresponding NumberFormatter class has also been added to the flex SDK, in the spark.formatters package.
CurrencyFormatter - A class in flash.globalization that provides locale specific formatting of currency amounts. This class also contains properties which provide the locale specific data used in formatting currency amounts. For example: decimal separator, grouping separator, digit type, negative symbol, negative and positive currency format, etc. A corresponding CurrencyFormatter class has also been added to the flex SDK, in the spark.formatters package.
Summary and Background
Flex enhances rich internet application usability in several ways. One area is validating user input on the fly in the client application rather than transmitting the data to server for validation. However, some of the data entered by user can be specific to the locale he chooses in the application. Hence it is important to validate user-entered data using the locale provided. Flash Player 10.1 has the flash.globalization classes, that provide locale-specific methods and properties to format dates, numbers and currency amounts. These classes can also provide the necessary functionality to be used in Number and Currency Validators. The current mx:validators support locale-specific validation to some extent. However, those validators have following limitations:
- Locale Awareness
- The mx validators have data for only a few locales. For locales that are not supported the developer must provide the locale specific values such as the decimal separator, grouping separator for the number and currency validators.
- Use of non-European digits validation is not supported.
- Maintenance problems
- The locale data changes over time. For example, India has a introduced a new currency symbol. When the locale data is updated, the resource bundles used by the mx validators also need to be updated.
- There is a large amount of AS3 code to validate some properties. Some of this functionality can be provided with very little code by using the flash.globalization number/currency formatters.
- Validation of negative and positive formats of numbers and currency is not supported.
The new locale specific validators overcome the above problems by using the functionality and data that is available from the flash.globalization classes. The other major feature of a validator is the interaction with the UI controls such as the TextInput, TextArea, and RichTextEditor controls. The existing mx:validators provide a set of methods that allow for tight integration with the UI components. The new spark validators will provide the same level of integration with these components.
This document identifies the requirements, functionality and design of locale specific number and currency validators.
Benefits for client using Spark validators
- Extensible to any locale using the locale data supported by the operating system on which flash player is running.
- Additional control of Number and Currency validation including negative and positive number formats.
- Acceptance of non-European digits.
- Operating System updates that include new locales or changes to existing locales are automatically covered.
- Reduction in AS3 code size used for validation.
- Respecting the Internationalization preferences/customizations the user specifies for the OS (in Control Panel/System Preferences)
- Consistency with other applications running on the system
Usage Scenarios
-
Danny is a freelance Flex developer building rich internet financial applications for browsers and Android phones. He is currently building an application for a reputed global bank. One of the application features allows a client to transfer money from one account to another securely. Danny uses the Flex form and has input fields for entering the amount of money to be transferred. The amount entered by the client must be strictly validated for any errors. As it is a global bank, Danny is looking for a locale based currency amount validator. The application also requires that multiple field entries be validated upon pressing the form submit button.
-
Gouri is a web designer primarily conversant with HTML, MXML and Flex. She is not comfortable coding ActionScript but is OK with MXML syntax. She is developing a DMV (Dept of Motor Vehicles) application that needs to cater to English, Spanish, Hindi, Cantonese and Vietnamese communities per government laws. The users input the odometer reading, auto-insurance policy number, age, date and time of an accident report. The application provides accident information to multiple agencies including the insurance company and the police department. Since the server cannot deal with incorrect information, validating the user input on the client without server involvement is critical to the application.
Detailed Description
Requirements
-
The Spark validators must continue to support all existing functionality that is in in mx number/currency validators. This includes the following:
-
Validation of strings that contain currency amounts and numbers formatted based on the properties listed in the tables below.
- Triggering validation by using events
- Triggering validation programmatically
- Validating required fields
- Enabling/disabling validator
- Configuration of the validator using data binding
-
Customization of the validators
-
The validators should derive the locale in the same way as the new spark formatters.
Locale Style and Data
To get the locale specific information, each validator will use the NumberFormatter and CurrencyFormatter provided by the flash.globalization package. These classes require that a locale ID name be specified. Setting or inheriting a locale ID name for a validator will be done by using the locale style in the same fashion as the spark formatters. See the section Locale Style in http://opensource.adobe.com/wiki/display/flexsdk/Spark%20Formatters#SparkFormatters-AdditionalImplementationDetails
Note that the use of the flash.globalization classes to access the locale specific data differs from the method used by the mx:validators. The mx:validators use resource bundles for obtaining the locale specific data. This data includes the grouping separator, decimal separator, fractional digits, and so on.
NumberValidator Comparison Table
The following table provides a comparison of the properties available in the mx NumberValidator and the proposed spark NumberValidator. In some cases the names of the properties are different but the functionality is the same. In other cases the spark NumberValidator has additional properties not found in the mx NumberValidator.
mx:NumberValidator
spark:NumberValidator
Comments
allowNegative:Object Default Value:true
allowNegative:Boolean Default Value:true
This is not supported by the Flash.globalization class, therefore a small amount of code will be written to support this.
decimalSeparator:String Default Value: Locale specific value from resource bundle
decimalSeparator:String Default Value: Locale specific
Use flash.globalization.NumberFormatter.decimalSeparator if not specified by the developer.
domain:String Default Value: real
domain:String Default Value: real
Type of number: integer or real
maxValue:Object Default Value: NaN
maxValue:Number Default Value: NaN
Maximum value for the number
minValue:Object Default Value: NaN
minValue:Number Default Value: NaN
Minimum value for the number
precision:Object Default Value: Locale specific value from resource bundle
fractionalDigits:Number Default Value: Locale specific
thousandsSeparator:String Default Value: Locale specific value from resource bundle
groupingSeparator:String Default Value: Locale specific
Use flash.globalization.NumberFormatter.groupingSeparator if not specified by developer.
Additional Properties
These additional validation properties are possible with the use of the flash.globalization.NumberFormatter*
negativeNumberFormat:Number Default Value: 1
Ensure that the negative symbol is placed according to the format for negative numbers. The NumberFormatter.parseNumber method will be used to check this format.
negativeSymbol:String Default Value: Locale specific
Check to see if the negativeSymbol in the input number is used for negative numbers. This will require additional code in the validation routine. Some platforms do not support custom negative symbol, therefore this will be a read-only property.
digitsType:uint Default Value: Locale specific
The value of this property represents the Unicode value for the zero digit of a decimal digit set. This defines the set of digit characters to be used when validating numbers. The flash.globalization.NumberFormatter parse method allows the use of any valid digitTypes in the input string. The spark NumberValidator will also allow for any valid digit type.
Unsupported Properties
The following properties exist in flash.globalization.NumberFormatter but will not be provided in the spark .NumberValidator
groupingPattern:String Default Value: Locale specific
The grouping pattern defines the number of digits between the grouping separators. This type of validation is not provided by the parse method in the flash.globalization.NumberFormatter class. The flash.globalization.NumberFormatter class depends on the platform for formatting a number string. Not all platforms support the grouping pattern fully. When the platform cannot support a grouping pattern, the number formatter returns a fallback grouping of digits in the number string. Hence the output of the formatter cannot be validated correctly.
leadingZero:Boolean
The spark . NumberValidator will allow for input strings with and without the leading zero.
trailingZeroes:Boolean
The spark . NumberValidator will allow for input strings with and without the trailing zero.
useGrouping:Boolean
The spark . NumberValidator will allow for input strings with and without the grouping separators.
Public Methods
NumberValidator()
NumberValidator()
Constructor
public static validateNumber(validator:NumberValidator, value:Object, baseField:String):Array
public validateNumber(value:Object, baseField:String):Array
Convenience method for calling a validator from within a custom validation function.
Error messages
decimalPointCountError:String
decimalPointCountError:String
Error if decimal separator character occurs more than once
exceedsMaxError:String
greaterThanMaxError:String
Error message when the value exceeds maxValue property
integerError:String
notAnIntegerError:String
Error message when the number must be integer per domain property.
invalidCharError:String
invalidCharError:String
Error message if number contains invalid characters.
invalidFormatCharsError:String
invalidFormatCharsError:String
Error message if the value contains invalid format characters, which means that it contains a digit or minus sign as a separator character, or it contains tow or more consecutive separator characters.
lowerThanMinError:String
lessThanMinError:String
Error if number is less than minimum value specified.
negativeError:String
negativeError:String
Error message if number is negative and allowNegative is false.
precisionError:String
fractionalDigitsError:String
Error message when the value has more fractional digits than specified by the fractionalDigits property.
Additional Error Messages
negativeNumberFormatError:String
The negative format of the input number is incorrect.
parseError:String
The input string could not be parsed.
negativeSymbolError:String
The negative symbol is repeated or not in right place.
notANumberError:String
The input entered is not a number.
localeUndefinedError:String
Error message when the locale is undefined or not available.
CurrencyValidator Comparison Table
The following table provides a comparison of the properties available in the mx CurrencyValidator and the proposed spark CurrencyValidator. In some cases the names of the properties are different but the functionality is the same. In other cases the spark CurrencyValidator has additional properties not found in the mx CurrencyValidator.
mx:CurrencyValidator
spark:CurrencyValidator
Comments
allowNegative:Object Default Value:true
allowNegative:Boolean Default Value:true
This is not supported by the Flash.globalization class, therefore a small amount of code will be written to support this.
decimalSeparator:String Default Value: Locale specific value from resource bundle
decimalSeparator:String Default Value: Locale specific
Use flash.globalization.NumberFormatter.decimalSeparator if not specified by the developer.
domain:String Default Value:"real"
domain:String Default Value:"real"
Type of number: integer or real
maxValue:Object Default value:NaN
maxValue:Number Default value:NaN
Maximum value for the number
minValue:Object Default value:NaN
minValue:Number Default value:NaN
Minimum value for the number
precision:Object Default Value: Locale specific value from resource bundle
fractionalDigits:Number Default Value: Locale specific
Maximum number of digits allowed after the decimal point.Check against flash.globalization.NumberFormatter.fractionalDigits
thousandsSeparator:String Default Value: Locale specific value from resource bundle
groupingSeparator:String Default Value: Locale specific
Use flash.globalization.NumberFormatter.groupingSeparator if not specified by developer.
alignSymbol:String
:uint Default Value:0 negativeCurrencyFormat:uint Default Value:0
Use the positiveCurrencyFormat and negativeCurrencyFormat properties to determine the currency symbol alignment, and the format for negative currency amounts as well.
currencySymbol:String
currencySymbol:String Default Value: Locale specific
Use the CurrencyFormatter.currencySymbol for the default value. Developers can supply their own value.
Additional Properties
These additional validation properties are possible with the use of the flash.globalization.CurrencyFormatter
currencyISOCode:String Default Value: Locale specific
Use the currency ISO code from CurrencyFormatter.currencyISOCodefor the default value. Developers can supply their own value.
negativeSymbol:String Default Value: Locale specific
Check to see if the negativeSymbol in the input number is used for negative numbers. This will require additional code in the validation routine. Some platforms do not support custom negative symbol, therefore this will be a read-only property.
digitsType:uint Default Value: Locale specific
The value of this property represents the Unicode value for the zero digit of a decimal digit set.This defines the set of digit characters to be used when validating numbers. The flash.globalization.CurrencyFormatter parse method allows the use of any valid digitTypes in the input string. The spark CurrencyValidator will also allow for any valid digit type.
Unsupported Properties
The following properties exist in flash.globalization.CurrencyFormatter but will not be provided in the spark .CurrencyValidator
groupingPattern:String Default Value: Locale specific
The grouping pattern defines the number of digits between the grouping separators. This type of validation is not provided by the parse method in the flash.globalization.CurrencyFormatter class. The flash.globalization.CurrencyFormatter class depends on the platform for formatting a number string. Not all platforms support the grouping pattern fully. When the platform cannot support a grouping pattern, the formatter returns a fallback grouping of digits in the currency number string. Hence the output of the formatter cannot be validated correctly.
leadingZero:Boolean
The spark . CurrencyValidator will allow for input strings with and without the leading zero.
trailingZeroes:Boolean
The spark . CurrencyValidator will allow for input strings with and without the trailing zero.
useGrouping:Boolean
The spark . CurrencyValidator will allow for input strings with and without the grouping separators.
Public Methods
CurrencyValidator()
CurrencyValidator()
Constructor
public static validateCurrency(validator:CurrencyValidator, value:Object, baseField:String):Array
public validateCurrency(value:Object, baseField:String):Array
Convenience method for calling a validator from within a custom validation function.
Error messages
decimalPointCountError:String
decimalPointCountError:String
Error if decimal separator character occurs more than once
exceedsMaxError:String
greaterThanMaxError:String
Error message when the value exceeds maxValue property
integerError:String
notAnIntegerError:String
Error message when the number must be integer per domain property.
invalidCharError:String
invalidCharError:String
Error message if number contains invalid characters.
invalidFormatCharsError:String
invalidFormatCharsError:String
Error message if the value contains invalid format characters, which means that it contains a digit or minus sign as a separator character, or it contains tow or more consecutive separator characters
lowerThanMinError:String
lessThanMinError:String
Error if number is less than minimum value specified.
negativeError:String
negativeError:String
Error message if number is negative and allowNegative is false.
precisionError:String
fractionalDigitsError:String
Error message when the value has more fractional digits than specified by the fractionalDigits property.
currencySymbolError:String
currencyStringError:String
Currency symbol or ISO code is repeated or not correct.
Additional Error Messages
negativeCurrencyFormatError:String
The negative format of the input currency is incorrect.
positiveCurrencyFormatError:String
The positive format of the input currency is incorrect.
parseError:String
The input string could not be parsed.
negativeSymbolError
The negative symbol is repeated or not in right place.
localeUndefinedError
Error message when the locale is undefined or not available.
Interaction with UI controls
To enhance the usability of the validator classes, the validation process is tightly integrated with UI controls. The validators allow
- Data to be validated automatically upon user input.
- Highlighting of the UI control if data validation fails.
- Validation of multiple UI controls.
- Triggering validation based on other UI control events.
The new spark validator classes will also provide all of this functionality.
New classes
- spark.validators.NumberValidator
- spark.validators.CurrencyValidator
- spark.validators.supportClasses.GlobalizationValidatorBase
- spark.validators.supportClasses.NumberValidatorBase
- mx.validators.IValidator
Design Considerations
- The existing class mx.validators.Validator is re-used with some modifications and is named spark.validators.supportClasses.GlobalizationValidatorBase. mx:Validator class implements IMXMLObject interface method
initialized(). spark:GlobalizationValidatorBase class inherits from GlobalizationBase which in turn inherits from mx.styles.AdvancedStyleClient. But AdvancedStyleClient already implemented initialized() method. Hence the initialized() method override is removed from spark:GlobalizationValidatorBase.
- GlobalizationValidatorBase class implements the validation base methods/properties, UI component interaction and locale derivation from advanced style client, hence can be reused across other spark validators which need locale data like date, time, currency and number.
- spark.NumberBase class has all properties relevant for Number/Currency Validator implemented. Hence the class code is reused to create NumberValidatorBase class with only needed properties for validators.
- The inheritance looks like NumberValidator > NumberValidatorBase > GlobalizationValidatorBase > GlobalizationBase > AdvancedStyleClient
- spark:GlobalizationValidatorBase uses the other support classes ValidationResult, ValidationResultEvent, NumberValidatorDomainBase from mx package.
- New error messages are stored in the validators bundle in mx package. They need to be localized.
- flash.globalization property names are used rather than the property names in mx validators. This way developers using flash and spark globalization classes can expect consistent naming.
- A new IValidator interface has been defined to support the static method mx.Validator.validateAll(). The validateAll() method takes an array of validators from mx and spark namespaces and validates multiple text fields in a form. The problem is that spark validators inherit from GlobalizationValidatorBase, where as mx validators inherit from mx:Validator. Now both mx:validator and spark:GlobalizationValidatorBase implement IValidator interface. This way appropriate validator can be successfully called from validateAll() method.
- Internally the NumberValidator and CurrencyValidator classes use the parse() method of the underlying flash.globalization formatter. So the parse() method decides whether an input number or currency string is syntactically correct or incorrect.
- The mx:Numbervalidator and mx:CurrencyValidator objects have the methods validateNumber() and validateCurrency() defined as static methods. But in spark:NumberValidator and spark:CurrencyValidator, these methods are not static. The mx validators methods validateNumber() and validateCurrency() take actual Number/Currency Validator instance as 1st parameter. Inside the static methods, they use the passed instance and access the properties. This seemed strange. The spark versions have more modular functions doing all validations. Passing the instance as a parameter to each validating function made the code clumsy. Hence we removed the 1st parameter (instance of NumberValidator or CurrencyValidator) of validateNumber()/validateCurrency() and made the methods as non-static.
- The validateNumber() and validateCurrency() methods in spark NumberValidator and CurrencyValidator objects take the input string tobe validated as a parameter of type Object. If the Object type passed is not String type, then the code converts the object to string by passing the objet to String constructor. This string will then be validated. This is the mx NumberValidator and CurrencyValidator behaviour too.
- Error messages are not binded to the change event in mx Validators. In spark validators they are binded to the change event.
- The digitsType property represents the Unicode value for the zero digit of a decimal digit set. The digits range then is assumed to be between digitsType and digitsType + 9.
- digitsType can be set to any Unicode value. Validators donot enforce the default locale specific digit set. This way for a locale like hi_IN (Hindi, India), both devanagari and european digits can be used. All Unicode zero values specified by flash.globalization.NationalDigitsType are supported.
- Unicode minus symbols (0×2212 MINUS SIGN, 0xFE63 SMALL HYPHEN-MINUS, 0xFF0D FULLWIDTH HYPHEN-MINUS) are also accepted.
API Description
Additions to MXML Language and _ActionScript_ Object Model
Include the relevant API for this feature using the following example as a guideline. Make sure you indicate whether APIs are public or protected. You do not need to present private or mx_internal APIs here.
CurrencyValidator
package spark.validators
{
/**
* The CurrencyValidator class ensures that a String represents a valid
* currency amount according to the conventions of a locale.
*
* <p>It can ensure that a currency string falls within a given range
* (specified by <code>minValue</code> and <code>maxValue</code> properties),
* is an integer (specified by <code>domain</code> property),
* is non-negative (specified by <code>allowNegative</code> property),
* has the correct way of specifying negative numbers and postive numbers,
* has the correct currency ISO code or currency symbol,
* and does not exceed the specified <code>fractionalDigits</code>. The
* validator sets default property values from the operating system supplied
* locale data but they can be customized for specific needs.</p>
*
* <p>This class internally uses the
* <code>flash.globalization.CurrencyFormatter</code> for acquiring
* locale-specific validation data and parsing functionality.
* The CurrencyValidator class can be used in MXML declarations or can be
* used in ActionScript code.
* This class uses the locale style for specifying the Locale ID,
* and has methods and properties that are bindable.</p>
* <p>
* The flash.globalization.CurrencyFormatter class uses the underlying
* operating system to supply the locale specific data. In case the operating
* system does not provide currency formatting, this class provides fallback
* functionality.
* </p>
*
* @mxml
*
* <p>The <code><spark:CurrencyValidator></code> tag
* inherits all of the tag attributes of its superclass,
* and adds the following tag attributes:</p>
*
* <pre>
* <spark:CurrencyValidator
* allowNegative="true|false"
* currencyISOCode="(locale specified or cutomized by user)."
* currencySymbol="(locale specified or cutomized by user)."
* decimalPointCountError="The decimal separator can only occur once."
* decimalSeparator="(locale specified string or customized by user)."
* domain="real|int"
* exceedsMaxError="The number entered is too large."
* integerError="The number must be an integer."
* invalidCharError="The input contains invalid characters."
* invalidFormatCharsError="One of the formatting parameters is invalid."
* lowerThanMinError="The amount entered is too small."
* maxValue="NaN"
* minValue="NaN"
* negativeError="The amount may not be negative."
* negativeCurrencyFormat="(locale specified or cutomized by user)."
* positiveCurrencyFormat="(locale specified or cutomized by user)."
* negativeCurrencyFormatError="The negative format of the input currency is
* wrong."
* positiveCurrencyFormatError="The positive format of the input currency is
* wrong."
* negativeNumberFormatError="The negative format of the input number is
* wrong."
* negativeSymbol="(locale specified read-only string)."
* negativeSymbolError="The negative symbol is repeated or not in right
* place."
* notANumberError="The input entered is not a number."
* parseError="The input string could not be parsed."
* fractionalDigits="(locale specified number or customized by user)."
* fractionalDigitsError="The amount entered has too many digits beyond the
* decimal point."
* groupingSeparator="(locale specified string or customized by user)."
* />
* </pre>
*
* @see flash.globalization.CurrencyFormatter
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4.5
*/
/**
* Convenience method for calling a validator
* from within a custom validation function.
* Each of the standard Flex validators has a similar convenience method.
*
* @param validator The CurrencyValidator instance.
*
* @param value A currency number string to validate.
*
* @param baseField Text representation of the subfield
* specified in the <code>value</code> parameter.
* For example, if the <code>value</code> parameter specifies value.number,
* the <code>baseField</code> value is "number".
*
* @return An Array of ValidationResult objects, with one ValidationResult
* object for each field examined by the validator.
*
* @see mx.validators.ValidationResult
*
* @see flash.globalization.CurrencyFormatter
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4.5
*/
public function validateCurrency(value:Object,
baseField:String):Array
/**
* Constructs a new CurrencyValidator object to validate numbers
* representing currency amounts according to
* the conventions of a given locale.
* <p>
* The locale for this class is supplied by the locale style. The
* locale style can be set in several ways:
* </p>
* <ul>
* <li>
* Inheriting the style from a UIComponent by calling the
* UIComponent's addStyleClient method.
* </li>
* <li>
* By using the class in an mxml declaration and inheriting the
* locale from the document that contains the declaration.
* </li>
* <listing version="3.0" >
* <fx:Declarations>
* <s:CurrencyValidator id="cv" />
* </fx:Declarations>
* </listing>
* <li>
* By using an mxml declaration and specifying the locale value
* in the list of assignments.
* </li>
* <listing version="3.0" >
* <fx:Declarations>
* <s:CurrencyValidator id="cv_turkish" locale="tr-TR" />
* </fx:Declarations>
* </listing>
* <li>
* Calling the setStyle method,
* e.g. <code>cv.setStyle("locale", "tr-TR")</code>
* </li>
* </ul>
* <p>
* If the locale style is not set by one of the above techniques,
* the methods of this class that depend on the locale
* will throw an error.
* </p> *
* <p>The properties related to the currency string format are set to
* default values based on the locale.</p>
*
* <p><strong>NOTE:</strong> When a fallback locale is used, the currency
* properties are set to default values,
* and therefore may not match the currency for which the validation is
* intended. It is a good idea to
* examine the currencySymbol and currencyISOCode property values before
* validating a currency amount.
* </p>
*
* @see actualLocaleIDName
*
* @playerversion Flash 10.1
* @langversion 3.0
* @productversion Flex 4.5
* @productversion Flash CS5
*/
public function CurrencyValidator();
/**
* The three letter ISO 4217 currency code for the locale
* being used.
*
* <p>This code is used to determine the currency symbol or string when
* validating currency amounts using the <code>validate()</code> method.
* </p>
*
* <p>This property is initialized by the constructor
* based on the actual locale that is used. When a fallback
* locale is used this property reflects the preferred, default
* currency code for the fallback locale.</p>
*
* @default dependent on the actual locale and operating system
*
* @see #validate()
* @see #currencySymbol
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
*/
public function get currencyISOCode():String
public function set currencyISOCode(value:String):void
/**
* The currency symbol or string for the locale being used.
*
* <p>This property is used as the currency symbol when validating
* currency amounts using the <code>validate()</code> method. </p>
*
* <p>This property is initialized by the constructor based on
* the actual locale that is used. When a fallback
* locale is used this property reflects the preferred, default
* currency symbol for the fallback locale.</p>
*
* @default dependent on the actual locale and operating system
*
* @see #format()
* @see #setCurrency()
* @see #formattingWithCurrencySymbolIsSafe
* @see #currencyISOCode
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
*/
public function set currencySymbol(value:String):void
public function get currencySymbol():String
/**
* A numeric value that indicates a validating pattern for negative
* currency amounts. This property defines the location of the
* currency symbol and the negative symbol or parentheses in
* relation to the numeric portion of the currency
* amount. This property is used to validate whether or not the input
* currency string follows this pattern for negative amounts.
*
* <p>The value of this property must be one of the constants
* defined in the table below.
* </p>
*
* <p> The table below summarizes the possible patterns
* for negative currency amounts. </p>
*
* <ul>
* <li>The '¤' symbol represents the location of the currencyISOCode
* or the currencySymbol in the currency string.
* </li>
* <li>The '-' character represents the location of the
* negativeNumberSymbol.</li>
* <li>The 'n' character represents the currency amount.</li>
* </ul>
*
* <table class="innertable" border="0">
* <tr>
* <td>Negative currency format type</td>
* <td>Formatting pattern</td>
* </tr>
* <tr>
* <td>0</td>
* <td>(¤n)</td>
* </tr>
* <tr>
* <td>1</td>
* <td>-¤n</td>
* </tr>
* <tr>
* <td>2</td>
* <td>¤-n</td>
* </tr>
* <tr>
* <td>3</td>
* <td>¤n-</td>
* </tr>
* <tr>
* <td>4</td>
* <td>(n¤)</td>
* </tr>
* <tr>
* <td>5</td>
* <td>-n¤</td>
* </tr>
* <tr>
* <td>6</td>
* <td>n-¤</td>
* </tr>
* <tr>
* <td>7</td>
* <td>n¤-</td>
* </tr>
* <tr>
* <td>8</td>
* <td>-n ¤</td>
* </tr>
* <tr>
* <td>9</td>
* <td>-¤ n</td>
* </tr>
* <tr>
* <td>10</td>
* <td>n ¤-</td>
* </tr>
* <tr>
* <td>11</td>
* <td>¤ n-</td>
* </tr>
* <tr>
* <td>12</td>
* <td>¤ -n</td>
* </tr>
* <tr>
* <td>13</td>
* <td>n- ¤</td>
* </tr>
* <tr>
* <td>14</td>
* <td>(¤ n)</td>
* </tr>
* <tr>
* <td>15</td>
* <td>(n ¤)</td>
* </tr>
* </table>
*
* @default dependent on the actual locale and operating system
*
* @throws ArgumentError if the assigned value is not between 0 and 15.
*
* @see #format()
* @see #currencySymbol
* @see #negativeSymbol
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get negativeCurrencyFormat():uint
public function set negativeCurrencyFormat(value:uint):void
/**
* A numeric value that indicates a validating pattern for positive
* currency amounts. This property defines the location of currency symbol
* relative to the numeric portion of the currency amount. This property
* is used to validate if the input currency string
* follows this pattern for positive amounts.
*
* <p>The value of this property must be one of the constants
* defined in the table below.
* </p>
*
* <p> The table below summarizes the possible patterns
* for positive currency amounts.
* </p>
*
* <ul>
* <li>The '¤' symbol irepresents the location of the currencyISOCode
* or the currencySymbol in the currency string.</li>
* <li>The 'n' character represents the location of the currencyISOCode or
* the currencySymbol in the currency string.</li>
* </ul>
*
* <table class="innertable" border="0">
* <tr>
* <td>Positive currency format type</td>
* <td>Formatting pattern</td>
* </tr>
* <tr>
* <td>0</td>
* <td>¤n</td>
* </tr>
* <tr>
* <td>1</td>
* <td>n¤</td>
* </tr>
* <tr>
* <td>2</td>
* <td>¤ n</td>
* </tr>
* <tr>
* <td>3</td>
* <td>n ¤</td>
* </tr>
* </table>
*
* @throws ArgumentError if the assigned value is not between 0 and 3.
*
* @default dependent on the actual locale and operating system
*
* @see #currencySymbol
* @see #format()
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get positiveCurrencyFormat():uint
public function set positiveCurrencyFormat(value:uint):void
/**
* Error message when the currency symbol or currency ISO code is repeated
* or is in the incorrect location.
*
* @default "Currency symbol or ISO code is repeated or not correct."
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get currencyStringError():String
public function set currencyStringError(value:String):void
/**
* Error message when the negative number format of the input currency
* string is incorrect.
*
* @default "The negative format of the input currency is incorrect."
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get negativeCurrencyFormatError():String
public function set negativeCurrencyFormatError(value:String):void
/**
* Error message when the positive currency number format is incorrect.
*
* @default "The positive format of the input currency is incorrect."
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get positiveCurrencyFormatError():String
public function set positiveCurrencyFormatError(value:String):void
}
NumberValidator
package spark.validators
{
/**
* The NumberValidator class ensures that a String represents a valid number
* according to the conventions of a locale. It can validate <code>int</code>,
* <code>uint</code>, and <code>Number</code> objects.
*
* <p>It can ensure that the input falls within a given range
* (specified by <code>minValue</code> and <code>maxValue</code> properties),
* is an integer (specified by <code>domain</code> property),
* is non-negative (specified by <code>allowNegative</code> property),
* has the correct way of specifying negative numbers,
* and does not exceed the specified <code>fractionalDigits</code>. The
* validator sets default property values from the operating system supplied
* locale data but they can be customized for specific needs.</p>
*
* <p>This class internally uses the <code>flash.globalization.NumberFormatter
* </code> to obtain locale-specific information.
* The NumberValidator class can be used in MXML declarations or in
* ActionScript code. This class uses the locale style for specifying the
* requested Locale ID, and has methods and properties that are bindable.
* </p>
* <p>
* The flash.globalization.NumberFormatter class uses the underlying
* operating system for acquiring locale-specific data and parsing
* functionality. In case the operating system does not provide number
* formatting, this class provides fallback functionality.
* </p>
*
* @mxml
*
* <p>The <code><spark:NumberValidator></code> tag
* inherits all of the tag attributes of its superclass,
* and adds the following tag attributes:</p>
*
* <pre>
* <spark:NumberValidator
* allowNegative="true|false"
* decimalPointCountError="The decimal separator can only occur once."
* decimalSeparator="(locale specified string or customized by user)."
* domain="real|int"
* exceedsMaxError="The number entered is too large."
* integerError="The number must be an integer."
* invalidCharError="The input contains invalid characters."
* invalidFormatCharsError="One of the formatting parameters is invalid."
* lowerThanMinError="The amount entered is too small."
* maxValue="NaN"
* minValue="NaN"
* negativeError="The amount may not be negative."
* negativeNumberFormatError="The negative format of the input number is
* wrong."
* negativeSymbol="(locale specified read-only string)."
* negativeSymbolError="The negative symbol is repeated or not in right
* place."
* notANumberError="The input entered is not a number."
* parseError="The input string could not be parsed."
* fractionalDigits="(locale specified number or customized by user)."
* fractionalDigitsError="The amount entered has too many digits beyond the
* decimal point."
* groupingSeparator="(locale specified string or customized by user)."
* />
* </pre>
*
* @includeExample examples/NumberValidatorExample.mxml
*
* @see flash.globalization.NumberFormatter
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4.5
*/
/**
* Convenience method for calling a validator from within a custom
* validation function. Each of the standard Flex validators has a similar
* convenience method.
*
* @param value A number string to validate.
*
* @param baseField Text representation of the subfield specified in the
* <code>value</code> object.
* For example, if the <code>value</code> parameter specifies value.number,
* the <code>baseField</code> value is "number".
*
* @return An Array of ValidationResult objects, with one ValidationResult
* object for each field examined by the validator.
*
* @see mx.validators.ValidationResult
*
* @langversion 3.0
* @playerversion Flash 10.1
* @playerversion AIR 2.0
* @productversion Flex 4.5
*/
public function validateNumber(value:Object,
baseField:String):Array
/**
* Constructs a new NumberValidator object to validate numbers according
* to the conventions of a given locale.
* <p>
* The locale for this class is supplied by the locale style.
* The locale style can be set in several ways:
* </p>
* <ul>
* <li> *
* Inheriting the style from a UIComponent by calling the UIComponent's
* addStyleClient method.
* </li>
* <li>
* By using the class in an MXML declaration and inheriting the
* locale from the document that contains the declaration.
* <listing version="3.0" >
* <fx:Declarations>
* <s:NumberValidator id="nv" />
* </fx:Declarations>
* </listing>
* </li>
* <li>
* By using an MXML declaration and specifying the locale value in
* the list of assignments.
* <listing version="3.0" >
* <fx:Declarations>
* <s:NumberValidator id="nv_French_France" locale="fr_FR" />
* </fx:Declarations>
* </listing>
* </li>
* <li>
* Calling the setStyle method, e.g.
* <code>nv.setStyle("locale", "fr-FR")</code>
* </li>
* </ul>
* <p>
* If the locale style is not set by one of the above techniques,
* the methods of this class that depend on the locale
* will throw an error.
* </p> *
*
* @playerversion Flash 10.1
* @langversion 3.0
* @productversion Flex 4.5
* @productversion Flash CS5
*/
public function NumberValidator()
/**
* A numeric value that indicates a validating pattern for negative
* numbers.
* This pattern defines the location of the negative symbol
* or parentheses in relation to the numeric portion of the
* number to be validated.
*
* <p>The following table summarizes the possible formats for
* negative numbers. When a negative number is validated,
* the minus sign represents the value of
* the <code>negativeSymbol</code> property and the 'n' character
* represents numeric value.</p>
*
* <table class="innertable" border="0">
* <tr>
* <td>Negative number format type</td>
* <td>Format</td>
* </tr>
* <tr>
* <td>0</td>
* <td>(n)</td>
* </tr>
* <tr>
* <td>1</td>
* <td>-n</td>
* </tr>
* <tr>
* <td>2</td>
* <td>- n</td>
* </tr>
* <tr>
* <td>3</td>
* <td>n-</td>
* </tr>
* <tr>
* <td>4</td>
* <td>n -</td>
* </tr>
* </table>
*
*
* @default dependent on the locale and operating system.
*
* @throws ArgumentError if the assigned value is not a number
* between 0 and 4.
*
* @see #negativeSymbol
* @see #format()
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get negativeNumberFormat():uint
public function set negativeNumberFormat(value:uint):void
/**
* Error message when the input number's negative number format is not
* following the pattern specified by the negativeNumberFormat property.
*
* @default "The negative format of the input number is incorrect."
*
* @langversion 3.0
* @playerversion Flash 10.1
* @playerversion AIR 2.0
* @productversion Flex 4.5
*/
public function get negativeNumberFormatError():String
public function set negativeNumberFormatError(value:String):void
}
h3.NumberValidatorBase
package spark.validators.supportClasses
{
/**
* Constructor.
*
* @langversion 3.0
* @playerversion Flash 10.1
* @playerversion AIR 2.5
* @productversion Flex 4.5
*/
public function NumberValidatorBase()
/**
* The decimal separator character used for validating numbers that have
* a decimal part.
*
* <p>This property is initially set based on the locale that
* is selected when the validator object
* is constructed.</p>
*
* @throws TypeError if this property is assigned a null value.
*
* @default dependent on the locale and operating system.
*
* @see #validate()
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get decimalSeparator():String
public function set decimalSeparator(value:String):void
/**
* The maximum number of digits that can appear after the decimal
* separator.
*
* @default dependent on the locale and operating system.
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get fractionalDigits():int
public function set fractionalDigits(value:int):void
/**
* The character or string used for the grouping separator.
*
* <p>The value of this property is used as the grouping
* separator when validating numbers. This
* property is initially set based on the locale that is selected
* when the validator object is constructed.</p>
*
* @throws TypeError if this property is assigned a null value.
*
* @default dependent on the locale and operating system.
*
* @see #validate()
* @see #groupingPattern
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get groupingSeparator():String
public function set groupingSeparator(value:String):void
/**
* The negative symbol to be used when validating negative values.
*
* <p>This symbol is used when validating a negative number.
* This is read-only property as not all operating systems allow
* customizing of this property. </p>
*
* <p> This property is set to a default value specified by the locale.</p>
*
* @see #negativeNumberFormat
* @see #validate()
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get negativeSymbol():String
/**
* Specifies whether negative numbers are permitted.
* Valid values are <code>true</code> or <code>false</code>.
*
* @default true
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get allowNegative():Boolean
public function set allowNegative(value:Boolean):void
/**
* Type of number to be validated.
* Permitted values are <code>"real"</code> and <code>"int"</code>.
*
* <p>In ActionScript, you can use the following constants to set this
* property:
* <code>NumberValidatorDomainType.REAL</code> or
* <code>NumberValidatorDomainType.INT</code>.</p>
*
* @default "real"
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get domain():String
public function set domain(value:String):void
/**
* Maximum value for a valid number. A value of NaN means there is no
* maximum.
*
* @default NaN
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get maxValue():Number
public function set maxValue(value:Number):void
/**
* Minimum value for a valid number. A value of NaN means there is no
* minimum.
*
* @default NaN
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get minValue():Number
public function set minValue(value:Number):void
/**
* Error message when the decimal separator character occurs more than
* once.
*
* @default "The decimal separator can occur only once."
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get decimalPointCountError():String
public function set decimalPointCountError(value:String):void
//----------------------------------
// greaterThanMaxError
//----------------------------------
/**
* Error message when the value exceeds the <code>maxValue</code> property.
*
* @default "The number entered is too large."
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get greaterThanMaxError():String
public function set greaterThanMaxError(value:String):void
//----------------------------------
// notAnIntegerError
//----------------------------------
/**
* Error message when the number must be an integer, as defined
* by the <code>domain</code> property.
*
* @default "The number must be an integer."
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get notAnIntegerError():String
public function set notAnIntegerError(value:String):void
//----------------------------------
// invalidCharError
//----------------------------------
/**
* Error message when the value contains invalid characters.
*
* @default The input contains invalid characters."
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get invalidCharError():String
public function set invalidCharError(value:String):void
//----------------------------------
// invalidFormatCharsError
//----------------------------------
/**
* Error message when the value contains invalid format characters, which
* means that it contains a digit or minus sign (-) as a separator
* character, or it contains two or more consecutive separator characters.
*
* @default "One of the formatting parameters is invalid."
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get invalidFormatCharsError():String
public function set invalidFormatCharsError(value:String):void
//----------------------------------
// lessThanMinError
//----------------------------------
/**
* Error message when the value is less than the <code>minValue</code>.
*
* @default "The amount entered is too small."
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get lessThanMinError():String
public function set lessThanMinError(value:String):void
//----------------------------------
// negativeError
//----------------------------------
/**
* Error message when the value is negative and the
* <code>allowNegative</code> property is <code>false</code>.
*
* @default "The amount may not be negative."
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get negativeError():String
public function set negativeError(value:String):void
//----------------------------------
// negativeSymbolError
//----------------------------------
/**
* Error message when the negative symbol is repeated or is in wrong place.
*
* @default "The negative symbol is repeated or not in right place."
*
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get negativeSymbolError():String
public function set negativeSymbolError(value:String):void
//----------------------------------
// fractionalDigitsError
//----------------------------------
/**
* Error message when fraction digits exceeds the value specified
* by the fractionalDigits property.
*
* @default "The amount entered has too many digits beyond the decimal
* point."
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get fractionalDigitsError():String
public function set fractionalDigitsError(value:String):void
//----------------------------------
// groupingSeparationError
//----------------------------------
/**
* Error message when the grouping separator is in incorrect location.
*
* @default "The number digits grouping is not following the grouping
* pattern."
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get groupingSeparationError():String
public function set groupingSeparationError(value:String):void
//----------------------------------
// parseError
//----------------------------------
/**
* Error message when number could not be parsed.
*
* @default "The input string could not be parsed."
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get parseError():String
public function set parseError(value:String):void
//----------------------------------
// notANumberError
//----------------------------------
/**
* Error message when the input string is not a number.
*
* @default "The input entered is not a number."
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get notANumberError():String
public function set notANumberError(value:String):void
/**
* Error message when the locale is undefined or is not available.
*
* @default "Locale is undefined."
*
* @playerversion Flash 10.1
* @playerversion AIR 2
* @langversion 3.0
* @productversion Flex 4.5
*/
public function get localeUndefinedError():String
public function set localeUndefinedError(value:String):void
}
GlobalizationValidatorBase
package spark.validators.supportClasses
{
/**
* The GlobalizationValidatorBase class is the base class for all validators
* in the spark namespace. This class implements the ability for a validator
* to make a field required, which means that the user must enter a value in
* the field or the validation fails.
*
* @mxml
*
* <p>The GlobalizationValidatorBase class defines the following tag attributes,
* which all of its subclasses inherit:</p>
*
* <pre>
* <spark:GlobalizationValidatorBase
* enabled="true|false"
* listener="<i>Value of the source property</i>"
* property="<i>No default</i>"
* required="true|false"
* requiredFieldError="This field is required."
* source="<i>No default</i>"
* trigger="<i>Value of the source property</i>"
* triggerEvent="valueCommit"
* />
* </pre>
*
* @see mx.events.ValidationResultEvent
* @see mx.validators.ValidationResult
* @see mx.validators.RegExpValidationResult
*
* @includeExample examples/SimpleValidatorExample.mxml
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
/**
* Dispatched when validation succeeds.
*
* @eventType mx.events.ValidationResultEvent.VALID
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
<a href="Event%28name%3D%26quot%3Bvalid%26quot%3B%2C%20type%3D%26quot%3Bmx.events.ValidationResultEvent%26quot%3B%29">Event(name="valid", type="mx.events.ValidationResultEvent")</a>
/**
* Dispatched when validation fails.
*
* @eventType mx.events.ValidationResultEvent.INVALID
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
<a href="Event%28name%3D%26quot%3Binvalid%26quot%3B%2C%20type%3D%26quot%3Bmx.events.ValidationResultEvent%26quot%3B%29">Event(name="invalid", type="mx.events.ValidationResultEvent")</a>
/**
* Invokes all the validators in the <code>validators</code> Array.
* Returns an Array containing one ValidationResultEvent object
* for each validator that failed.
* Returns an empty Array if all validators succeed.
*
* @param validators An Array containing the GlobalizationValidatorBase objects to execute.
*
* @return Array of ValidationResultEvent objects, where the Array
* contains one ValidationResultEvent object for each validator
* that failed.
* The Array is empty if all validators succeed.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
public static function validateAll(validators:Array):Array
/**
* Constructor.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
public function GlobalizationValidatorBase()
/**
* Setting this value to <code>false</code> will stop the validator
* from performing validation.
* When a validator is disabled, it dispatches no events,
* and the <code>validate()</code> method returns null.
*
* @default true
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
public function get enabled():Boolean
public function set enabled(value:Boolean):void
/**
* Specifies the validation listener.
*
* <p>If you do not specify a listener,
* Flex uses the value of the <code>source</code> property.
* After Flex determines the source component,
* it changes the border color of the component,
* displays an error message for a failure,
* or hides any existing error message for a successful validation.</p>
*
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
public function get listener():Object
public function set listener(value:Object):void
/**
* A String specifying the name of the property
* of the <code>source</code> object that contains
* the value to validate.
* The property is optional, but if you specify <code>source</code>,
* you should set a value for this property as well.
*
* @default null
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
public function get property():String
public function set property(value:String):void
/**
* If <code>true</code>, specifies that a missing or empty
* value causes a validation error.
*
* @default true
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
public var required:Boolean = true;
/**
* Specifies the object containing the property to validate.
* Set this to an instance of a component or a data model.
* You use data binding syntax in MXML to specify the value.
* This property supports dot-delimited Strings
* for specifying nested properties.
*
* If you specify a value to the <code>source</code> property,
* then you should specify a value to the <code>property</code>
* property as well.
* The <code>source</code> property is optional.
*
* @default null
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
public function get source():Object
public function set source(value:Object):void
/**
* Specifies the component generating the event that triggers the
* validator.
* If omitted, by default Flex uses the value of the <code>source</code>
* property.
* When the <code>trigger</code> dispatches a <code>triggerEvent</code>,
* validation executes.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
public function get trigger():IEventDispatcher
public function set trigger(value:IEventDispatcher):void
/**
* Specifies the event that triggers the validation.
* If omitted, Flex uses the <code>valueCommit</code> event.
* Flex dispatches the <code>valueCommit</code> event
* when a user completes data entry into a control.
* Usually this is when the user removes focus from the component,
* or when a property value is changed programmatically.
* If you want a validator to ignore all events,
* set <code>triggerEvent</code> to the empty string ("").
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
public function get triggerEvent():String
public function set triggerEvent(value:String):void
/**
* Error message when a value is missing and the
* <code>required</code> property is <code>true</code>.
*
* @default "This field is required."
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
public function get requiredFieldError():String
public function set requiredFieldError(value:String):void
/**
* Performs validation and optionally notifies
* the listeners of the result.
*
* @param value Optional value to validate.
* If null, then the validator uses the <code>source</code> and
* <code>property</code> properties to determine the value.
* If you specify this argument, you should also set the
* <code>listener</code> property to specify the target component
* for any validation error messages.
*
* @param suppressEvents If <code>false</code>, then after validation,
* the validator will notify the listener of the result.
*
* @return A ValidationResultEvent object
* containing the results of the validation.
* For a successful validation, the
* <code>ValidationResultEvent.results</code> Array property is empty.
* For a validation failure, the
* <code>ValidationResultEvent.results</code> Array property contains
* one ValidationResult object for each field checked by the validator,
* both for fields that failed the validation and for fields that passed.
* Examine the <code>ValidationResult.isError</code>
* property to determine if the field passed or failed the validation.
*
* @see mx.events.ValidationResultEvent
* @see mx.validators.ValidationResult
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
public function validate(
value:Object = null,
suppressEvents:Boolean = false):ValidationResultEvent
}
IValidator
package mx.validators
{
/**
* This interface specifies the methods and properties that a Validator
* object must implement.
* <p>This interface allows to validate multiple data
* types like numbers, currency, phone numbers, zip codes etc that
* are defined in both mx and spark namespaces. The classes
* mx:Validator and spark:GlobaliationValidatorBase
* implement this interface. The validateAll() method in these classes use
* this interface type to call the validate() method on
* multiple validator objects.</p>
*
*
* @see mx.validators.Validator
* @see spark.validators.GlobalizationValidatorBase
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4.5
*/
public interface IValidator
{
//----------------------------------------------------------------------
//
// Properties
//
//----------------------------------------------------------------------
//----------------------------------
// enabled
//----------------------------------
/**
* Property to enable/disable validation process.
* <p>Setting this value to <code>false</code> will stop the validator
* from performing validation.
* When a validator is disabled, it dispatches no events,
* and the <code>validate()</code> method returns null.</p>
*
* @default true
*
* @langversion 3.0
* @playerversion Flash 10.1
* @playerversion AIR 2.0
* @productversion Flex 4.5
*/
function get enabled():Boolean;
function set enabled(value:Boolean):void;
//----------------------------------------------------------------------
//
// Methods
//
//----------------------------------------------------------------------
/**
* Performs validation and optionally notifies
* the listeners of the result.
*
* @param value Optional value to validate.
* If null, then the validator uses the <code>source</code> and
* <code>property</code> properties to determine the value.
* If you specify this argument, you should also set the
* <code>listener</code> property to specify the target component
* for any validation error messages.
*
* @param suppressEvents If <code>false</code>, then after validation,
* the validator will notify the listener of the result.
*
* @return A ValidationResultEvent object
* containing the results of the validation.
* For a successful validation, the
* <code>ValidationResultEvent.results</code> Array property is empty.
* For a validation failure, the
* <code>ValidationResultEvent.results</code> Array property contains
* one ValidationResult object for each field checked by the validator,
* both for fields that failed the validation and for fields that passed.
* Examine the <code>ValidationResult.isError</code>
* property to determine if the field passed or failed the validation.
*
* @see mx.events.ValidationResultEvent
* @see mx.validators.ValidationResult
*
* @langversion 3.0
* @playerversion Flash 10.1
* @playerversion AIR 2.0
* @productversion Flex 4.5
*/
function validate(value:Object = null,
suppressEvents:Boolean = false):ValidationResultEvent
}
B Features
Detail features here that are to be considered for B Feature time.
Examples and Usage
The following example illustrates the usage of spark validator CurrencyValidator.
CurrencyValidator cv1 validates the text field tb2 upon focus out event. It's locale is de-CH (German-Switzerland). cv1 is declared in the fx:Declarations.
CurrencyValidator cv2 is created using a constructor in the code. This is specifically added as a style client child to the application object. This way the validator cv2 gets the locale from the application. This validates the text field tb2 upon
pressing the submit1 button.
There are two side panels. One panel displays the cv2 currency validator properties. User can change these values and validate
tb1 text field accordingly. The other panel has the text boxes and the submit button.
<?xml version="1.0" encoding="utf-8"?> <s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark" xmlns:mx="library://ns.adobe.com/flex/mx" minWidth="955" minHeight="600" height="558" width="535" initialize="init()"> <s:layout> <s:VerticalLayout/> </s:layout> <fx:Declarations> <s:CurrencyValidator id="cv1" fractionalDigits="4" maxValue="100000000" minValue="2" allowNegative="false" required="false" source="{tb2}" property="text" locale="de-CH"/> </fx:Declarations> <fx:Script> <![CDATA[ import mx.collections.ArrayCollection; import mx.events.ListEvent; import spark.validators.NumberValidator; <a href="Bindable">Bindable</a> public var localeList:ArrayCollection = new ArrayCollection( [ {label:"English (US)", data:"en-US", {label:"हिंदी (भारत)", data:"hi-IN"}, {label:"English (Great Britain)", data:"en-GB"}, {label:"Deutsch (Schweiz)", data:"de-CH"}, {label:"Deutsch (Deutschland)", data:"de-DE"}, {label:"Français (France)", data:"fr-FR"}, {label:"中文(简体) (中华人民共和国)", data:"zh-CN"} ]); <a href="Bindable">Bindable</a> public var ntypeList:ArrayCollection = new ArrayCollection( [ {label:"integer number", data:"int"}, {label:"real number", data:"real"}]); private var cv2:spark.validators.CurrencyValidator; private function localeSelector_changeHandler(event:ListEvent):void { var locale:String = ComboBox(event.target).selectedItem.data; var myStyleManager: IStyleManager2 = StyleManager.getStyleManager(this.moduleFactory); myStyleManager.getStyleDeclaration("global").setStyle("locale", locale); init(); } private function setprops(v:CurrencyValidator):void { v.allowNegative = allowneg.selected; if (maxval.text != "") v.maxValue = Number(maxval.text); if (minval.text != "") v.minValue = Number(minval.text); if (ds.text != "") v.decimalSeparator = ds.text; if (gs.text != "") v.groupingSeparator = gs.text; if (iso.text != "") v.currencyISOCode = iso.text; if (sym.text != "") v.currencySymbol = sym.text; v.negativeCurrencyFormat = nf.value; v.positiveCurrencyFormat = pf.value; v.domain = ntypeList<a href="ntype.selectedIndex">ntype.selectedIndex</a>.data; v.fractionalDigits = fd.value; } public function init():void { cv2 = new spark.validators.CurrencyValidator(); this.addStyleClient(cv2); updateUI(cv2); } private function updateUI(v:CurrencyValidator):void { allowneg.selected = v.allowNegative; maxval.text = v.maxValue.toString(); minval.text = v.minValue.toString(); ds.text = v.decimalSeparator; gs.text = v.groupingSeparator; iso.text = v.currencyISOCode; sym.text = v.currencySymbol; nf.value = v.negativeCurrencyFormat; pf.value = v.positiveCurrencyFormat; fd.value = v.fractionalDigits; } private function performValidation():void { // Set the listener property to the component // used to display validation errors. setprops(cv2); this.addStyleClient(cv2); cv2.listener = tb1; cv2.validate(tb1.text); } ]]> </fx:Script> <s:Panel title="Validation example" width="531" height="500" x="0" y="0"> <s:Panel x="246" y="-33" width="283" height="500"> <s:Label x="10" y="423" text="Negative Format"/> <s:NumericStepper x="130" y="408" minimum="0" maximum="15" id="nf"/> <s:Label x="10" y="62" text="Decimal Separator"/> <s:TextInput x="129" y="48" id="ds"/> <s:Label x="10" y="99" text="Grouping Separator"/> <s:TextInput x="129" y="89" id="gs"/> <s:CheckBox x="3" y="443" id="allowneg" label="Allow Negative"/> <s:Label x="10" y="148" text="Maximum Value"/> <s:TextInput x="129" y="134" id="maxval"/> <s:Label x="10" y="189" text="Minimum Value"/> <s:TextInput x="129" y="182" id="minval"/> <s:Label x="10" y="319" text="Domain"/> <mx:ComboBox x="130" y="311" width="128" id="ntype" dataProvider="{ntypeList}"/> <s:Label x="9" y="357" text="Fractional Digits"/> <s:NumericStepper x="130" y="346" id="fd" maximum="15"/> <s:Label x="10" y="387" text="Positive Format"/> <s:NumericStepper x="130" y="380" minimum="0" maximum="4" id="pf" width="53"/> <s:Label x="10" y="231" text="Currency ISO code"/> <s:TextInput x="130" y="224" id="iso"/> <s:Label x="10" y="267" text="Currency symbol"/> <s:TextInput x="130" y="257" id="sym"/> </s:Panel> <s:Panel width="248" height="500" x="0" y="-33"> <s:Label text="textbox1_parent_locale" x="10" y="14"/> <s:TextInput id="tb1" x="10" y="34"/> <s:Label text="textbox2_de_CH" x="10" y="80"/> <s:TextInput id="tb2" x="10" y="100"/> <s:Button label="Submit1" click="performValidation();" x="10" y="267"/> <mx:ComboBox id="localeSelector" change="localeSelector_changeHandler(event)" dataProvider="{localeList}" x="10" y="217"/> </s:Panel> </s:Panel> </s:Application>
Additional Implementation Details
None
Prototype Work
A prototype has been implemented.
Compiler Work
None
Web Tier Compiler Impact
None
Flex Feature Dependencies
Dependent on several of the support classes that were created when implementing the spark validator classes.
The dependent classes are
spark.globalization.GlobalizationBase
mx.validators.ValidationResultEvent
spark.globalization.LastOperationStatus
mx.validators.NumberValidatorDomainType
mx.validators.ValidationResult
mx.validators.IValidator
Backwards Compatibility
None
Syntax changes
None
Behavior
No existing spark classes will be modified.
Warnings/Deprecation
The mx versions of the CurrencyValidator, NumberValidator will not be modified as part of this feature and will therefore continue to behave as previously implemented. However the documentation for these classes should be updated to direct developers to the new classes that are implemented as part of this feature.
The mx version of Validator is modified to implement the new IValidator interface. The documentation of this class must be updated to reflect this change.
Performance
There should not be any significant performance impacts from this feature.
Globalization
This feature is intended to provide the ability of developers to easily support locales that are available on an end users device. Thus it is a key feature for the development of world ready applications using the Flex SDK.
The feature is implemented by using the locale data provided by the spark NumberFormatter and CurrencyFormatter objects.
Localization
The following new error messages are created in the validators.bundle in the mx package. All validator error messages are stored here both for mx and spark packages. These need to be localized to other languages supported in the frameworks\projects\framework\bundles\en_US\validators.properties file.
negativeNumberFormatError=The negative format of the input number is wrong.
negativeCurrencyFormatError=The negative format of the input currency is wrong.
positiveCurrencyFormatError=The positive format of the input currency is wrong.
parseError=The input string could not be parsed.
negativeSymbolError=The negative symbol is repeated or not in right place.
fractionalDigitsError=The amount entered has too many digits beyond the decimal point.
notANumberError=The input entered is not a number.
currencyStringError=Currency symbol or ISO code is repeated or not correct.
localeUndefinedError=Locale is undefined.
Compiler Features
None
Framework Features
None
Cross-Platform Considerations
The flash globalization classes provide different results depending on the platform. Therefore this feature will require testing on different platforms, to ensure that these platform differences are handled properly. If there is a platform that does not support the flash.globalization classes, then testing should also include that platform. The testing should also include setting locales that are not supported on the specific device. This will ensure that the fall back behavior is working correctly.
All the mx:validator testcases should be tested using spark:validators.
Issues and Recommendations
None
