attribute-base.js revision 42ca760bb9929dcdf6624637a7613f6f1ebcb4b4
/**
* The attribute module provides an augmentable Attribute implementation, which
* adds configurable attributes and attribute change events to the class being
* augmented. It also provides a State class, which is used internally by Attribute,
* store state.
*
* @module attribute
*/
/**
* The attribute-base submodule provides core attribute handling support, with everything
* aside from complex attribute handling in the provider's constructor.
*
* @module attribute
* @submodule attribute-base
*/
/**
* <p>
* Attribute provides configurable attribute support along with attribute change events. It is designed to be
* augmented on to a host class, and provides the host with the ability to configure attributes to store and retrieve state,
* along with attribute change events.
* </p>
* <p>For example, attributes added to the host can be configured:</p>
* <ul>
* <li>As read only.</li>
* <li>As write once.</li>
* <li>With a setter function, which can be used to manipulate
* values passed to Attribute's <a href="#method_set">set</a> method, before they are stored.</li>
* <li>With a getter function, which can be used to manipulate stored values,
* before they are returned by Attribute's <a href="#method_get">get</a> method.</li>
* <li>With a validator function, to validate values before they are stored.</li>
* </ul>
*
* <p>See the <a href="#method_addAttr">addAttr</a> method, for the complete set of configuration
* options available for attributes</p>.
*
* <p><strong>NOTE:</strong> Most implementations will be better off extending the <a href="Base.html">Base</a> class,
* instead of augmenting Attribute directly. Base augments Attribute and will handle the initial configuration
* of attributes for derived classes, accounting for values passed into the constructor.</p>
*
* @class Attribute
* @param attrs {Object} The attributes to add during construction (passed through to <a href="#method_addAttrs">addAttrs</a>). These can also be defined on the constructor being augmented with Attribute by defining the ATTRS property on the constructor.
* @param values {Object} The initial attribute values to apply (passed through to <a href="#method_addAttrs">addAttrs</a>). These are not merged/cloned. The caller is responsible for isolating user provided values if required.
* @param lazy {boolean} Whether or not to add attributes lazily (passed through to <a href="#method_addAttrs">addAttrs</a>).
* @uses AttributeCore
* @uses AttributeEvents
* @uses AttributeExtras
*/
var Attribute = function() {
};
// Needs to be "true", to overwrite methods from AttributeCore
/**
* <p>The value to return from an attribute setter in order to prevent the set from going through.</p>
*
* <p>You can return this value from your setter if you wish to combine validator and setter
* functionality into a single setter function, which either returns the massaged value to be stored or
* AttributeCore.INVALID_VALUE to prevent invalid values from being stored.</p>
*
* @property INVALID_VALUE
* @type Object
* @static
* @final
*/
/**
* The list of properties which can be configured for
* each attribute (e.g. setter, getter, writeOnce etc.).
*
* This property is used internally as a whitelist for faster
* Y.mix operations.
*
* @property _ATTR_CFG
* @type Array
* @static
* @protected
*/