ComponentMixins

Kind of class:class
Inherits from:none
Classpath:mx.data.binding.ComponentMixins
File last modified:Tuesday, 18 December 2007, 15:44:38
Defines component functionality related to DataBinding, These are properties
and functions that are automatically added to any object that is the source
or destination of a Binding (this is usually a UIComponent, but is not required to be).
These functions do not affect normal component functionality,
rather, they add functionality that is useful in conjunction with DataBinding.

These functions are only available on components that have already been included
in a Binding, either as a source, a destination, or an index.

Summary


Instance properties
Class methods
Instance methods

Instance properties

__bindings

private __bindings:Array
(read)

__fieldCache

private __fieldCache
(read)

__highPrioEvents

__highPrioEvents:Object
(read)

__refreshing

private __refreshing
(read)

__schema

__schema:Object
(read)

The Data schema for this component. This is automatically set for any components whose
schema is known by Flash at author-time. You may also set this property directly in
your actionscript code.

A Schema is an ActionScript object, whose properties are a description of a
particular data type. The description contains information that is needed
for type validation, type conversion, and other databinding-related operations.
A Schema object contains more-or-less the same information as is found
in the schema pane of the Component Inspector. See the documentation for
the Component Inspector for more information.
A Schema object has the following fields - *all* fields are optional:


name: String
the name of this type. This is ignored by databinding, except for one case:
the name "XML" indicates that the data is an XML object, rather than an ActionScript data structure. In
this case, the category (below) must be "complex"

category: String
This can be
  • "array" - the data is an array. The "elements" array (below) must contain exactly one item, which
    says what this is an array of.
  • "attribute" - the data is an attribute that is attached to an XML node. This category can only appear
    if the type is describing a field inside an XML structure.
  • "simple" - the data is a string, boolean, date, or number
  • "complex" - the data is an object (either actionscript or XML). The "elements" array (below)
    describes the fields of the object.
If category is omitted, it is assumed to be "simple" if elements is null, and "complex" otherwise.

elements: Array of Element
if category = "complex", this is a list of all the fields
of the object. if category = "array", this contains a single item. The schema for a component
contains one element for each property. "Element" is described below.

validation: ObjectSpec
describes a class of objects that will be created at runtime,
to validate data, and do type conversion. The class must
be a subclass of mx.data.binding.DataType.

required: Boolean
if true, then null values are not valid

readonly: Boolean
if true, then databinding will never write to this data

format: ObjectSpec
describes a class of objects that will be created at runtime,
to format data. The class must
be a subclass of mx.data.binding.Formatter.

value: Object
for use by the DataSet (Firefly) component

label: String
for use by the DataSet (Firefly) component

uicontrol: String
for use by the DataSet (Firefly) component

Here are the fields of the Element object:


name: String
the name of this field.

type: Schema
the name of this field.

The ObjectSpec object specifies how to create certain "helper" objects, as described above. The properties of this object are:


cls : class
an actionscript class.

className : String
a string containing the name of an actionscript class

settings : Object
an object whose properties are option settings for the created object

cls and className contain the same information, and you can give one or the other
of these, but not both.
The difference is that cls is an actual reference to a class, whereas className is the name of
the class as a string. If you choose to give the class name as a string, you must also reference that class directly somewhere
in actionscript code - this reminds Flash to include a copy of the class in your SWF.

Example:
  • {elements: [{name: "dataProvider", type: {category: "array"}}, 
        {name: "selectedIndex", type: {validation: {className: "mx.data.types.Num", settings: {int: 0}}}}, 
        {name: "selectedIndices", type: {category: "array"}}, 
        {name: "selectedItem", type: {readonly: true}}, 
        {name: "selectedItems", type: {category: "array", readonly: true}}]}
    For more examples, I recommend you take a look at the schema of any component in any Flash movie,
    for example with the following code: 
    trace(mx.data.binding.ObjectDumper.toString(myComponent.__schema));
    @property __schema

_databinding_original_dispatchEvent

_databinding_original_dispatchEvent:Function
(read)

_eventDispatcher

_eventDispatcher:Object
(read)

dispatchEvent

dispatchEvent:Function
(read)

Class methods

deepEqual

static function deepEqual (
a, b) : Boolean

initComponent

static function initComponent (
component)

Instance methods

__addHighPrioEventListener

function __addHighPrioEventListener (
event:String, handler) : Void

__setReadOnly

function __setReadOnly (
setting)

addBinding

function addBinding (
binding:mx = .data.binding.Binding)

createField

function createField (
property:String, location:Object) : mx.data.binding.DataType

createFieldAccessor

function createFieldAccessor (
property:String, location:Object, mustExist:Boolean) : mx.data.binding.FieldAccessor

findSchema

function findSchema (
property:String, location:Object)

getBindingMetaData

function getBindingMetaData (
name)

getField

function getField (
property:String, location:Object) : mx.data.binding.DataType

getFieldFromCache

private function getFieldFromCache (
property:String, location:Object) : mx.data.binding.DataType

refreshAndValidate

function refreshAndValidate (
property:String) : Boolean

refreshDestinations

function refreshDestinations (
)

Executes all the Bindings that have this object as the source EndPoint.
This is a handy way to execute Bindings whose sources do not emit
a 'data changed' event.

refreshFromSources

function refreshFromSources (
)

Executes all the Bindings that have this component as the destination EndPoint.
This causes the data to be completely up to date. This is a handy way to
execute Bindings that have constant sources, or sources that do not emit
any 'data changed' event.

validateProperty

function validateProperty (
property:String, initialMessages:Array) : Array

Checks to see if the data in the indicated property is valid. The validation is
based on the information in this component's __schema property.
For each field within the data, this function dispatches valid/invalid events as follows:
  • If the value is null, and the field is not required,
    we return null and don't dispatch any events.
  • If the value is null, and the field is required,
    we return some errors, and dispatch an "invalid" event.
  • If the value is non-null and the field's type does not have a validator defined for it,
    we return null and don't dispatch any events
  • If the value s non-null and a validator does exist, then we run the validator,
    dispatch either a "valid" or "invalid" event,
    and return null (for valid) or an array of messages (for invalid).
Validation only applies to fields which have type information available.
Fields that are objects with child elements will try to validate each child field
(and so on, recursively). Each individual field will dispatch a "valid" or "invalid" event if necessary.
Parameters:
property:
The name of a property of this component
Returns:
  • null, if the data is valid. Otherwise this is a array of descriptions of
    all the errors that were detected, including errors detected in fields of nested objects.
    Each element of the array is an object containing these fields:


    message : String
    an error message

    field : String
    [optional] name of the field or sub-field causing the error

Example:
  • // Web service calls don't normally validate the data they receive,
// but we want to do it anyway. The webservicecall object will then
// emit a 'valid' or 'invalid' event, which we can then
// handle in any way we like.
_root.myWebServiceCall.addEventListener("result", function ()
{
    _root.myWebServiceCall.validateProperty("results");
});