////////////////////////////////////////////////////////////////////////////////
//
// Licensed to the Apache Software Foundation (ASF) under one or more
// contributor license agreements. See the NOTICE file distributed with
// this work for additional information regarding copyright ownership.
// The ASF licenses this file to You under the Apache License, Version 2.0
// (the "License"); you may not use this file except in compliance with
// the License. You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
////////////////////////////////////////////////////////////////////////////////
package mx.binding.utils
{
import mx.binding.utils.ChangeWatcher;
/**
* The BindingUtils class defines utility methods
* for performing data binding from ActionScript.
* You can use the methods defined in this class to configure data bindings.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
public class BindingUtils
{
include "../../core/Version.as";
//--------------------------------------------------------------------------
//
// Class methods
//
//--------------------------------------------------------------------------
/**
* Binds a public property, prop
on the site
* Object, to a bindable property or property chain.
* If a ChangeWatcher instance is successfully created, prop
* is initialized to the current value of chain
.
*
* @param site The Object defining the property to be bound
* to chain
.
*
* @param prop The name of the public property defined in the
* site
Object to be bound.
* The property will receive the current value of chain
,
* when the value of chain
changes.
*
* @param host The object that hosts the property or property chain
* to be watched.
* The host
maintains a list of sites
to update
* when prop
changes.
*
* @param chain A value specifying the property or chain to be watched.
* Legal values are:
*
{ name: property name, getter: function(host) { return host[property name] } }
.
* This Object must contain the name of, and a getter function for,
* a public bindable property of the host object.host.a.b.c
,
* call the method as:
* bindProperty(site, prop, host, ["a","b","c"])
.Note: The property or properties named in the chain
argument
* must be public, because the describeType()
method suppresses all information
* about non-public properties, including the bindability metadata
* that ChangeWatcher scans to find the change events that are exposed
* for a given property.
* However, the getter function supplied when using the { name, getter }
* argument form described above can be used to associate an arbitrary
* computed value with the named (public) property.
true
if the handler
* should be called only on committing change events;
* set to false
if the handler should be called
* on both committing and non-committing change events.
* Note: the presence of non-committing change events for a property
* is indicated by the [NonCommittingChangeEvent(<event-name>)]
* metadata tag.
* Typically these tags are used to indicate fine-grained value changes,
* such as modifications in a text field prior to confirmation.
*
* @param useWeakReference Determines whether the reference to site
* is strong or weak.
* A strong reference (the default) prevents site
from being garbage-collected.
* A weak reference does not.
* Added for Flex 4.
*
* @return A ChangeWatcher instance, if at least one property name has
* been specified to the chain
argument; null otherwise.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
public static function bindProperty(
site:Object, prop:String,
host:Object, chain:Object,
commitOnly:Boolean = false,
useWeakReference:Boolean = false):ChangeWatcher
{
var w:ChangeWatcher =
ChangeWatcher.watch(host, chain, null, commitOnly, useWeakReference);
if (w != null)
{
var assign:Function = function(event:*):void
{
site[prop] = w.getValue();
};
w.setHandler(assign);
assign(null);
}
return w;
}
/**
* Binds a setter function, setter
, to a bindable property
* or property chain.
* If a ChangeWatcher instance is successfully created,
* the setter function is invoked.
* The setter must have the following function signature:
*
* * function mySetterFunction(object:Object):void { * //Do whatever you want with the value of the bound property. * }* *
where object
contains the
* current value of chain
.
chain
when that value changes.
*
* @param host The host of the property.
* See the bindProperty()
method for more information.
* The host
maintains a list of setters
to update
* when prop
changes.
*
* @param name The name of the property, or property chain.
* See the bindProperty()
method for more information.
*
* @param commitOnly Set to true
if the handler should be
* called only on committing change events.
* See the bindProperty()
method for more information.
*
* @param useWeakReference Determines whether the reference to setter
* is strong or weak.
* A strong reference (the default) prevents setter
from being garbage-collected.
* A weak reference does not.
* Added for Flex 4.
*
* @return A ChangeWatcher instance, if at least one property name
* has been specified to the chain
argument; null otherwise.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
public static function bindSetter(setter:Function, host:Object,
chain:Object,
commitOnly:Boolean = false,
useWeakReference:Boolean = false):ChangeWatcher
{
var w:ChangeWatcher =
ChangeWatcher.watch(host, chain, null, commitOnly, useWeakReference);
if (w != null)
{
var invoke:Function = function(event:*):void
{
setter(w.getValue());
};
w.setHandler(invoke);
invoke(null);
}
return w;
}
}
}