/*______________ | ______ | U I Z E J A V A S C R I P T A P I | / / | ----------------------------------------- | / O / | MODULE : Uize Foundation Class (version 1.2.1) | / / / | AUTHOR : Chris van Rensburg (http://www.tomkidding.com) | / / / /| | ONLINE : http://www.tomkidding.com/uize/uize-js-api | /____/ /__/_| | COPYRIGHT : (c)2003-2006 Chris van Rensburg | /___ | LICENSE : Distributed under the terms of the GNU General Public License |_______________| http://www.gnu.org/licenses/gpl.txt */ /* TO DO - handle recursion in Uize.clone (how to generate properties that are references to other parts of structure in same relationship as the equivalent property in the cloning source???) - rethink alphasubber and omegasubber mechanism, since omegasubber is never used, and alphasubber is only used in the Uize baseclass and in a very specific way - improvements to property mechanism - support for read-only properties - fix the substitution code... - allow for arbitrary substitution map (ie. not just limited token syntax) - fix problem of substitution into substituted content from previous items in substitution map (ie. use insertion objects) - optimize for successive substitution on the same source using the same form of map (but different values, of course) */ /*? Introduction The =Uize= class is the base class from which many of the classes in the UIZE JavaScript API inherit. Key Features The =Uize= base class provides the following key features that provide the foundation for the subclasses... Beyond Prototype-based Inheritance Prototype-based inheritance only takes you so far. One major disadvantage is that subclasses don't inherit the instance methods and properties that are assigned in the constructor of the class that is being subclassed, nor any initialization that takes place in this constructor. Additionally, subclasses don't inherit static methods and properties of the base class. The inheritance system that is implemented in the =Uize= base class overcomes these weaknesses. Event Infrastructure The =Uize= base class provides a convenient infrastructure for supporting both static and instance events. Events can conveniently be fired for a class or an instance of a class, and methods are provided to every class that subclasses the =Uize= class to allow code to manage the registering and unregistering of event handlers for static and instance events. This provides all =Uize= subclasses with a consistent event model. Property Infrastructure Along with an event infrastructure, the =Uize= base class also provides a convenient system for managing instance properties, including providing an easy way for code to set defaults for a class's instance properties. Generated Instance Names When designing JavaScript classes, it is often necessary in the class's implementation to set intervals, timeouts, or the event handlers of HTML nodes that make up an instance's user interface, so that they execute methods of the instance. Often this must be done by generating JavaScript code that is to be interpreted. This generated code must, therefore, be able to reference its instance using a global identifier, because the code will be executed in a global context. The =Uize= base class provides every subclass with a convenient way of addressing this need. A global identifier name is automatically generated for every instance of a =Uize= subclass and is assigned to the instance's =objectName= property. Then, the global identifier by that name is assigned a reference to the instance. The global identifier is guaranteed to be unique for all instances of all =Uize= subclasses in a document. Other Utility Services As part of the foundation for developing =Uize= subclasses, the =Uize= class provides all its subclasses with a set of useful static and instance utility methods and properties. Static Methods Uize.subclass Lets you subclass the =Uize= class or any subclass of the =Uize= class. SYNTAX ................................................... MySubclass = Uize.subclass (subclassConstructorFN); ................................................... Consider the following example... ..................................... MySubclass = Uize.subclass ( function () { this.foo = 'How unoriginal!'; } ); MySubSubclass = MySubclass.subclass ( function () { this.bar = this.foo + ' Indeed!'; } ); ..................................... In the above example, =MySubSubclass= is a subclass of =MySubclass=, which is in turn a subclass of =Uize=. Now, when an instance of =MySubSubclass= gets created, the constructor of =MySubclass= and then the constructor of =MySubSubclass= will be executed in the initialization of the instance, and the instance will have both =foo= and =bar= properties, where the =bar= property will have a value of "How unoriginal! Indeed!". Instance Properties objectClass A reference to the class's constructor You can use this to interrogate an object instance to see if it is of a certain class, as illustrated in the following example... EXAMPLE ............................................................ if (myInstance.objectClass == Uize.Widget.Bar.Slider) { // do something for sliders } else if (myInstance.objectClass == Uize.Widget.TreeMenu) { // do something for tree menus } else if (myInstance.objectClass == Uize.Widget.ImageWipe) { // do something for wipes } ............................................................ The above example is admittedly a little abstract. It is hard to imagine the exact scenario that may come up where some code is handed object instances where their class will not be known. But, when such a case comes up, the =objectClass= property has got your back. */ /*___________ | _____ | R O O T C L A S S | | \ | ----------------------------------------- | | / | MODULE : RootClass (version 1.2.0) | |____/ | AUTHOR : Chris van Rensburg (http://www.tomkidding.com) | | \ | ONLINE : http://www.tomkidding.com/uize/uize-js-api | | \ | COPYRIGHT : (c)2003-2006 Chris van Rensburg | | \ | LICENSE : Distributed under the terms of the GNU General Public License |____________| http://www.gnu.org/licenses/gpl.txt */ /* DESCRIPTION Implements a JavaScript foundation class to facilitate unlimited levels of inheritance TO DO - consider a facility to support multiple inheritance (may involve creating a merge service for merging data from one object into another, since it should be possible to merge additional features of a different class into an already created class, and perhaps that merge feature would also be used in the _subclass function's implementation) */ /*ScruncherSettings Mappings="" LineCompacting="TRUE"*/ (function () { /*** Variables for Scruncher Optimization ***/ var _class = RootClass = function () {}; /*** Global Variables ***/ _emptyArray = []; /*** Public Static Methods ***/ var _clone = _class.clone = function (_object) { var _result; if (typeof _object == 'object' && _object && !(_object instanceof RegExp)) { if (_isArray (_object)) { _result = []; _result.length = _object.length; } else { _result = {}; } for (var _property in _object) _result [_property] = _clone (_object [_property]) ; } else { _result = _object; } return _result; /*? Static Methods Uize.clone Returns an identical clone of the specified source object. SYNTAX ................................................. var clonedObject = Uize.clone (objectToCloneOBJ); ................................................. An object that is cloned from a source object using this method will not be conjoined to the source object. Spawning an exact copy of an object is not as simple as copying that object's properties over to a new object. That simple approach works fine if the source object is simple and only contains properties with simple string or number types. But, if the source object contains properties that are references to other objects, then the simple approach will give rise to a clone that is not 100% discrete from its source. So, subsequent manipulations within the depths of the clone's structure may be reflected in the source object. The =Uize.clone= method makes sure to recurse the structure of the source object and create identical new data objects within the clone that match those in the source. NOTES - The one exception to the conjoined rule is function references, which will be shared according to the current implementation. */ }; var _isArray = _class.isArray = function (_object) { return _object instanceof Array || (_object && typeof _object.splice == 'function'); /*? Static Methods Uize.isArray Returns a boolean, indicating whether or not the specified value is an instance of the JavaScript Array class. SYNTAX .................................... Uize.isArray (possibleArrayANYTYPE); .................................... This method is a useful abstraction to deal with the fact that the =instanceof Array= test fails on arrays that are passed across frames/windows. The method returns =true= if the =instanceof Array= test passes, or if the specified value is an object and has a property named =splice= that is a function (the =splice= method is unique to arrays and its name is unique enough that the likelihood of an object having this property and it being a function is quite low). NOTES - an object having a property named =splice= whose value is of type =function= will be regarded as an array by this method */ }; _class.isNumber = function (_value) { return typeof _value == 'number' && !isNaN (_value); /*? Static Methods Uize.isNumber Returns a boolean, indicating whether or not the specified value is a number. SYNTAX ...................................... Uize.isNumber (possibleNumberANYTYPE); ...................................... This method is a useful abstraction to deal with the fact that the division of zero by zero in JavaScript yields a special kind of value know as =NaN=. Unfortunately, in the implementation of this special value, the result chosen for when the =typeof= operator is applied to it is ='number' (ie. =typeof NaN == 'number'= yields =true=). Go figure. This method checks that both the type of the parameter is ='number'= and also that the parameter is not =NaN=. */ }; _class.capFirstChar = function (_sourceStr) { return _sourceStr.charAt (0).toUpperCase () + _sourceStr.substr (1); }; /*** Inheritance Mechanism ***/ function _subclass (_Class,_alphastructor,_omegastructor,_alphasubber,_omegasubber) { var _Subclass = function () { _callAlongInheritanceChain (this,'alphastructor',arguments); _callAlongInheritanceChain (this,'omegastructor',arguments); return this; }; function _callAlongInheritanceChain (_context,_type,_arguments) { for (var _classNo = 0; _classNo < _classInheritanceChain.length; _classNo++) { var _function = _classInheritanceChain [_classNo] [_type]; if (_function) _function.apply (_context,_arguments || _emptyArray) ; } } /*** Inherit static properties (excluding prototype) and methods from base class ***/ for (var _property in _Class) { if (_property != 'prototype') _Subclass [_property] = _clone (_Class [_property]) ; } /*** Prepare instance properties and methods ***/ var _classPrototype = _Class.prototype, _subclassPrototype = _Subclass.prototype ; /*** Inherit instance properties and methods from base class (from prototype) ***/ for (var _property in _classPrototype) _subclassPrototype [_property] = _classPrototype [_property]; /*** Non-inherited Public Instance Properties ***/ _subclassPrototype.objectClass = _Subclass; /*** Initialize class inheritance chain ***/ var _classInheritanceChain = _Subclass._classInheritanceChain = (_Class._classInheritanceChain ? _Class._classInheritanceChain : _emptyArray).concat ({ alphastructor:_alphastructor, omegastructor:_omegastructor, alphasubber:_alphasubber, omegasubber:_omegasubber }) ; /*** Call subclassers along inheritance chain ***/ _callAlongInheritanceChain (_Subclass,'alphasubber'); _callAlongInheritanceChain (_Subclass,'omegasubber'); /*** Class Context Specific Public Static Methods ***/ _Subclass.callSuper = function (_this,_methodName,_params) { /* NOTE: This method must be defined here as a closure in order to access the _classPrototype variable, so that the super static method of every class can "know" its superclass. */ return _classPrototype [_methodName].apply (_this,_params || _emptyArray); }; return _Subclass; }; /*** Public Static Methods ***/ _class.subclass = function (_alphastructor,_omegastructor,_alphasubber,_omegasubber) { return _subclass (this,_alphastructor,_omegastructor,_alphasubber,_omegasubber); }; /* _class.use = function (_instance,_methodName,_params) { return this.prototype [_methodName].apply (_this,_params || _emptyArray); }; */ }) (); /*ScruncherSettings Mappings="=a" LineCompacting="TRUE"*/ (function () { /*** Variables for Scruncher Optimization ***/ var _undefined, _typeString = 'string', _typeObject = 'object', _typeFunction = 'function', _false = false, _true = true, _null = null ; /*** Global Variables ***/ var _UIZE_GUIDs = 0; /*** Object Constructor ***/ var _class = Uize = RootClass.subclass ( /*** alphastructor ***/ function () { var _this = this; /*** Public Instance Properties ***/ _this.objectName = _getGuid (); /*? Instance Properties objectName An automatically generated name of a global identifier that is assigned a reference to the instance. To illustrate this, consider the following example... ..................................................... if (myInstance == window [myInstance.objectName]) { alert ("Congratulations! It's an instance!!!"); } ..................................................... The above code will pop up the alert, because the property of the window object (ie. a global identifier) of the name stored in the =myInstance.objectName= property will refer to the same instance as the =myInstance= identifier. The =objectName= property can be used when generating JavaScript code that is to execute methods of the instance. Consider the following example... .................................................................. MySubclass.prototype.click = function () { // do something when the button is clicked }; MySubclass.prototype.insertButton = function () { document.writeln ( '' ); }; .................................................................. In the above example, we see a segment of the implementation for a =Uize= subclass named =MySubclass=. The =insertButton= instance method is writing HTML into the document, and the =input= tag that is created has an onClick event handler that will execute the =click= method of that instance when clicked. That's because the global identifier by the name stored in the =objectName= property is also a reference to the instance. NOTES - the =objectName= property's value is guaranteed to be unique for all instances of all =Uize= subclasses in a document */ /*** Private Instance Properties ***/ _this._eventsFired = {}; }, /*** omegastructor ***/ function (_properties) { var _this = this, _class = _this.objectClass ; /*** Setup Properties ***/ /* This section initializes the set-get instance properties using the values for the class's static set-get properties as the defaults. Additionally, the properties passed through to the constructor are "merged in" to override the initial values. */ var _propertiesInit = {}, _propertyProfilesByPublicNames = _class._propertyProfilesByPublicNames, _propertiesAdded = {} /* NOTES: - mapped by private name - this mechanism ensures that there is only one property in the _propertiesInit object for each actual set-get property, otherwise you can end up in situations where there are multiple properties for set-get properties that have aliases, and if that happens then the subsequent copyInto before the set call can put the constructor specified value for a property in an order before a static default value mapped to one of the aliases. */ ; for (var _propertyPublicName in _propertyProfilesByPublicNames) { var _propertyPrivateName = _propertyProfilesByPublicNames [_propertyPublicName]._privateName; if (!_propertiesAdded [_propertyPrivateName]) { _propertiesAdded [_propertyPrivateName] = 1; _propertiesInit [_propertyPublicName] = _class [_propertyPrivateName]; } } _this.set (_copyInto (_propertiesInit,_properties)); }, /*** alphasubber ***/ function () { var _class = this; if (!_class._uizeAlphaSubberDone) { _class._uizeAlphaSubberDone = _true; _class._propertyProfilesByPrivateNames = {}; _class._propertyProfilesByPublicNames = {}; _class._eventsFired = {}; } } ), _classPrototype = _class.prototype ; /*** Utility Functions ***/ function _getClass (_instanceOrClass) {return _instanceOrClass.objectClass || _instanceOrClass} /*** Property System Support Code ***/ function _getPropertyProfile (_this,_propertyPublicOrPrivateName) { var _class = _getClass (_this); return ( _class._propertyProfilesByPublicNames [_propertyPublicOrPrivateName] || _class._propertyProfilesByPrivateNames [_propertyPublicOrPrivateName] ); } function _getPropertyPrivateName (_this,_propertyPublicOrPrivateName) { var _propertyProfile = _getPropertyProfile (_this,_propertyPublicOrPrivateName); return _propertyProfile ? _propertyProfile._privateName : _propertyPublicOrPrivateName; } /*** Event System Support Code ***/ function _execEventHandler (_handler,_eventObject) { if (typeof _handler == _typeFunction) _handler (_eventObject); else if (typeof _handler == _typeString) eval (_handler); } /*** Private Instance-Static Methods ***/ /*** Event System Methods ***/ _class._abstractEventName = _classPrototype._abstractEventName = function (_eventName,_managementFunction) { var _this = this; if (_eventName.indexOf ('Changed.') == 0) { var _propertyPublicName = _eventName.substr (8), _propertyProfile = _getPropertyProfile (_this,_propertyPublicName) ; if (_propertyProfile) { _propertyPublicName = _propertyProfile._publicName; _eventName = 'Changed.' + _propertyPublicName; } if (_managementFunction) { _managementFunction (_eventName); (_this._hasChangedHandlers || (_this._hasChangedHandlers = {})) [_propertyPublicName] = _this._eventHandlers && _this._eventHandlers [_eventName] ; } } else { if (_managementFunction) _managementFunction (_eventName); } return _eventName; }; /*** Public Instance-Static Methods ***/ /*** Event System Methods ***/ _class.addEventHandler = _classPrototype.addEventHandler = function (_eventName,_handler) { var _this = this; _this._abstractEventName ( _eventName, function (_eventName) { var _eventHandlers = _this._eventHandlers || (_this._eventHandlers = _this.eventHandlers = {}); (_eventHandlers [_eventName] || (_eventHandlers [_eventName] = [])).push ( {_eventName:_eventName,_handler:_handler} ); } ); /*? Instance Methods addEventHandler Lets you register an event handler for a specific instance event. SYNTAX .............................................................. myInstance.addEventHandler (eventNameSTR,eventHandlerSTRorFN); .............................................................. Event handlers registered using this method will handle events fired for the instance using the =fireEvent= instance method, and not those events fired using the =Uize.fireEvent= static method. A =Uize= subclass may not provide any instance events, so you should consult the reference documentation for a class to learn more about its suite of events. EXAMPLE ........................................................................... mySlider.addEventHandler ( 'Changed.value', function () { document.getElementById ('valueField').value = mySlider.get ('value'); } ); ........................................................................... SPECIAL VALUES - the string value ="*"= acts as a wildcard when specified for the =eventNameSTR= parameter, meaning that the specified handler should be executed for all events of the instance NOTES - see also the =removeEventHandler= instance method - see also the =Uize.addEventHandler= and =Uize.removeEventHandler= static methods - compare to the =addEventHandlers= instance method Static Methods Uize.addEventHandler Lets you register an event handler for a static event of the class. SYNTAX .............................................................. MySubclass.addEventHandler (eventNameSTR,eventHandlerSTRorFN); .............................................................. Event handlers registered using this method will handle events fired for the class using the =Uize.fireEvent= static method, and not those events fired using the =fireEvent= instance method. A =Uize= subclass may not provide any static events, so you should consult the reference documentation for a class to learn more about its suite of events. SPECIAL VALUES - the string value ="*"= acts as a wildcard when specified for the =eventNameSTR= parameter, meaning that the specified handler should be executed for all events of the class NOTES - see also the =Uize.removeEventHandler= static method - see also the =addEventHandler= and =removeEventHandler= instance methods - compare to the =Uize.addEventHandlers= static method */ }; _class.addEventHandlers = _classPrototype.addEventHandlers = function (_eventsToHandlers) { for (var _event in _eventsToHandlers) this.addEventHandler (_event,_eventsToHandlers [_event]) ; /*? Instance Methods addEventHandlers Lets you conveniently register handlers for multiple instance events in a single method call. SYNTAX ......................................................... myInstance.addEventHandlers (eventNamesToHandlersMapOBJ); ......................................................... This method has the effect of iteratively calling the =addEventHandler= instance method for each event-name-to-handler mapping in the =eventNamesToHandlersMapOBJ= object, where the contents of this object are of the form... ................................... { event1Name:event1HandlerSTRorFN, event2Name:event2HandlerSTRorFN, ... eventNName:eventNHandlerSTRorFN } ................................... NOTES - compare to the =addEventHandler= instance method Static Methods Uize.addEventHandlers Lets you conveniently register handlers for multiple static events in a single method call. SYNTAX ......................................................... MySubclass.addEventHandlers (eventNamesToHandlersMapOBJ); ......................................................... This method has the effect of iteratively calling the =Uize.addEventHandler= instance method for each event-name-to-handler mapping in the =eventNamesToHandlersMapOBJ= object, where the contents of this object are of the form... ................................... { event1Name:event1HandlerSTRorFN, event2Name:event2HandlerSTRorFN, ... eventNName:eventNHandlerSTRorFN } ................................... NOTES - compare to the =Uize.addEventHandler= static method */ }; _class.hasEventFired = _classPrototype.hasEventFired = function (_eventName) { var _eventsFired = this._eventsFired; return _eventsFired && _eventsFired [this._abstractEventName (_eventName)]; /*? Instance Methods hasEventFired Returns a boolean, indicating whether or not the specified instance event has been fired at least once. SYNTAX ........................................ myInstance.hasEventFired (eventNameSTR); ........................................ NOTES - see also the =Uize.hasEventFired= static method Static Methods Uize.hasEventFired Returns a boolean, indicating whether or not the specified static event has been fired at least once. SYNTAX ........................................ MySubclass.hasEventFired (eventNameSTR); ........................................ NOTES - see also the =hasEventFired= instance method */ }; _class.doOnceEvent = _classPrototype.doOnceEvent = function (_eventName,_handler) { var _this = this; if (_this.hasEventFired (_eventName)) { _execEventHandler (_handler); } else { _this.addEventHandler (_eventName,function () {_execEventHandler (_handler); _handler = _null}); } /*? Instance Methods doOnceEvent Provides a convenient way to perform code only once the specified instance event has been fired at least once. SYNTAX ..................................................... myInstance.doOnceEvent (eventNameSTR,handlerSTRorFN); ..................................................... If the event specified by the =eventNameSTR= parameter has already been fired at least once, then the handler will be executed at the time this method is called. Otherwise, the handler will be remembered so that it can be executed for just the first time that the event is fired. This method can be useful when you wish to execute some code once some kind of initialization or setup for an instance is complete and the instance fires an event to indicate its ready state. Using this method ensures that the handler will not be executed before the instance is ready. NOTES - see also the =Uize.doOnceEvent= static method Static Methods Uize.doOnceEvent Provides a convenient way to perform code only once the specified static event has been fired at least once. SYNTAX ..................................................... MySubclass.doOnceEvent (eventNameSTR,handlerSTRorFN); ..................................................... If the event specified by the =handlerSTRorFN= parameter has already been fired at least once, then the handler will be executed at the time this method is called. Otherwise, the handler will be remembered so that it can be executed for just the first time that the event is fired. This method can be useful when you wish to execute some code once some kind of initialization or setup for a class is complete and the class fires a static event to indicate its ready state. Using this method ensures that the handler will not be executed before the class is ready. NOTES - see also the =doOnceEvent= instance method */ }; _class.fireEvent = _classPrototype.fireEvent = function (_event) { /* NOTES - this code is deliberately optimized for performance and not code size, since event firing is a mechanism that is heavily utilized. This will explain some patterns here that may seem slightly out of character, with seemingly redundant code or a lack of typical factoring out. */ if (typeof _event != _typeObject) _event = {name:_event}; var _this = this, _eventHandlers = _this._eventHandlers ; _this._eventsFired [_event.name] = _true; if (_eventHandlers) { var _handlersForThisEvent = _eventHandlers [_event.name], _handlersForAnyEvent = _eventHandlers ['*'] ; if (_handlersForThisEvent || _handlersForAnyEvent) { if (!_event.source) _event.source = _this; function _execEventHandlers (_handlers) { var _totalHandlers = _handlers.length; if (_totalHandlers == 1) { _execEventHandler (_handlers [0]._handler,_event); } else { for (var _handlerNo = 0; _handlerNo < _totalHandlers; _handlerNo++) _execEventHandler (_handlers [_handlerNo]._handler,_event) ; } } if (_handlersForAnyEvent) _execEventHandlers (_handlersForAnyEvent); if (_handlersForThisEvent) _execEventHandlers (_handlersForThisEvent); } } if (_event.bubble && _this.objectClass && _this.parent) { if (!_event.source) _event.source = _this; _this.parent.fireEvent (_event); } return _event; /*? Instance Methods fireEvent Lets you fire an event for an instance of the class. SYNTAX .................................... MyInstance.fireEvent (eventNameSTR); .................................... VARIATIONS ................................ MyInstance.fireEvent (eventOBJ); ................................ When an object is specified instead of a string value, then extra event properties can be bundled with the event and will then be available to all handlers that are executed. When using this form, the =eventOBJ= object must have a =name= property that specifies the name of the event being fired. NOTES - see also the =Uize.fireEvent= static method Static Methods Uize.fireEvent Lets you fire a static event for the class. SYNTAX .................................... MySubclass.fireEvent (eventNameSTR); .................................... VARIATIONS ................................ MySubclass.fireEvent (eventOBJ); ................................ When an object is specified instead of a string value, then extra event properties can be bundled with the event and will then be available to all handlers that are executed. When using this form, the =eventOBJ= object must have a =name= property that specifies the name of the event being fired. NOTES - see also the =fireEvent= instance method */ }; _class.removeEventHandler = _classPrototype.removeEventHandler = function (_eventName,_handler) { var _this = this; _this._abstractEventName ( _eventName, function (_eventName) { var _eventHandlers = _this._eventHandlers; if (_eventHandlers) { var _handlersForEventName = _eventHandlers [_eventName]; if (_handlersForEventName) { if (_handler) { /* TO DO: this is a candidate for factoring out as a generally useful array manipulation method: removeAllOfValue */ var _handlerNo = 0; while (_handlerNo < _handlersForEventName.length) { if (_handlersForEventName [_handlerNo]._handler == _handler) { _handlersForEventName.splice (_handlerNo,1); } else { _handlerNo++; } } } if (!_handler || !_handlersForEventName.length) delete _eventHandlers [_eventName] ; } } } ); /*? Instance Methods removeEventHandler Lets you remove an event handler previously registered using the =addEventHandler= method. SYNTAX ................................................................. myInstance.removeEventHandler (eventNameSTR,eventHandlerSTRorFN); ................................................................. Static Methods Uize.removeEventHandler Lets you remove an event handler for a static event of the class. SYNTAX ................................................................. MySubclass.removeEventHandler (eventNameSTR,eventHandlerSTRorFN); ................................................................. VARIATIONS ............................................. MySubclass.removeEventHandler (eventNameSTR); MySubclass.removeEventHandler (); ............................................. When no =eventHandlerSTRorFN= parameter is specified, then all handlers registered for the event specified in the =eventNameSTR= parameter will be removed. When no parameters at all are specified, then all handlers for all events will be removed. NOTES - see also the =Uize.addEventHandler= static method - see also the =addEventHandler= instance method - see also the =removeEventHandler= instance method */ }; /*** Set-get Property System Methods ***/ _class.get = _classPrototype.get = function (_property) { var _this = this, _result ; if (typeof _property == _typeString) { _result = _this [_getPropertyPrivateName (_this,_property)]; } else if (_class.isArray (_property)) { _result = {}; var _totalSubProperties = _property.length; for (var _subPropertyNo = 0; _subPropertyNo < _totalSubProperties; _subPropertyNo++) { var _subProperty = _property [_subPropertyNo]; _result [_subProperty] = _this.get (_subProperty); } } return _result; /*? Instance Methods get Lets you query the value of one of an instance's set-get properties. SYNTAX ................................. myInstance.get (propertyNameSTR); ................................. NOTES - see also the =set= instance method - see also the =Uize.get= static method - see also the =Uize.set= static method Static Methods Uize.get Lets you query the initial value for one of the class's set-get properties. SYNTAX ........................... Uize.get (propertyNameSTR); ........................... NOTES - see also the =Uize.set= static method - see also the =get= instance method - see also the =set= instance method */ }; _class.registerProperties = function (_propertyProfiles) { var _this = this, _class = _getClass (_this) ; if (_propertyProfiles) { var _propertyProfilesByPrivateNames = _class._propertyProfilesByPrivateNames, _propertyProfilesByPublicNames = _class._propertyProfilesByPublicNames ; for (var _propertyPrivateName in _propertyProfiles) { var _propertyData = _propertyProfiles [_propertyPrivateName], _propertyDataIsObject = typeof _propertyData == _typeObject, _propertyPublicName = _propertyDataIsObject ? _propertyData.name : _propertyData, _propertyPrimaryPublicName = _propertyPublicName, _propertyProfile = _propertyProfilesByPrivateNames [_propertyPrivateName] = {_privateName:_propertyPrivateName} ; if (_propertyPublicName.indexOf ('|') > -1) { var _pseudonyms = _propertyPublicName.split ('|'); _propertyPrimaryPublicName = _pseudonyms [0]; for (var _pseudonymNo = 0; _pseudonymNo < _pseudonyms.length; _pseudonymNo++) _propertyProfilesByPublicNames [_pseudonyms [_pseudonymNo]] = _propertyProfile ; } else { _propertyProfilesByPublicNames [_propertyPublicName] = _propertyProfile; } _propertyProfile._publicName = _propertyPrimaryPublicName; if (_propertyDataIsObject) { if (_propertyData.onChange) _propertyProfile._onChange = _propertyData.onChange; if (_propertyData.conformer) _propertyProfile._conformer = _propertyData.conformer; _class [_propertyPrivateName] = _propertyData.value; } } } /*? Static Methods Uize.registerProperties Lets you register properties for the class. SYNTAX ........................................................ MySubclass.registerProperties (propertiesDefinitionOBJ); ........................................................ The object specified in =propertiesDefinitionOBJ= parameter must conform to a specific structure. Each property of this object represents a property to be registered for the class, where the property name specifies the internal name to be used for the class property and the property's string value specifies the class property's public name. As an alternative to a string value, the property's value can be an object whose =name= property specifies the class property's public name and where an optional =onChange= property specifies a handler function that should be executed every time the value of the class property changes. This is all best illustrated with an example... EXAMPLE ........................................................................... MySubclass.registerProperties ( { _propertylName:'property1Name', _property2Name:'property2Name', _property3Name:{ name:'property3Name', onChange:function () { // code to be performed when the value of this property changes } } } ); ........................................................................... NOTES - calls to this method are cumulative, so it is possible to register properties in multiple separate batches */ }; _class.set = _classPrototype.set = function (_properties) { /* NOTE: Yes, there are functions _isInstance, _getClass, and _getPropertyPrivateName that could be used (and were at one point), but this code needs to be tuned for performance since set is a touch point in so many places. */ var _this = this, _isInstance = _this.objectClass ? _true : _false, _class = _this.objectClass || _this, _propertyProfilesByPublicNames = _class._propertyProfilesByPublicNames, _propertyProfilesByPrivateNames = _class._propertyProfilesByPrivateNames, _propertyProfile, _onChangeHandlers, _onChangeHandlerAddedFlagName, _onChangeHandler, _changedEventsToFire, _propertyPrivateName, _propertyPublicName, _propertiesToRegister, _propertyValue, _propertyValuesBeingSet = {} ; for (var _propertyPublicOrPrivateName in _properties) { _propertyValue = _properties [_propertyPublicOrPrivateName]; if (_propertyValue !== _undefined) { _propertyProfile = _propertyProfilesByPublicNames [_propertyPublicOrPrivateName] || _propertyProfilesByPrivateNames [_propertyPublicOrPrivateName] ; if (_propertyProfile) { _propertyPrivateName = _propertyProfile._privateName; _propertyPublicName = _propertyProfile._publicName; /*** if there's a registered conformer, execute it and adjust the value ***/ if (_isInstance && _propertyProfile._conformer) _propertyValue = _propertyProfile._conformer.call (_this,_propertyValue, _this [_propertyPrivateName]) ; _propertyValuesBeingSet [_propertyPublicName] = _propertyValue; if (_propertyValue !== _this [_propertyPrivateName]) { if (_isInstance) { /*** build up list of events to fire for 'Changed.' event handlers ***/ if (_this._hasChangedHandlers) { if (_this._hasChangedHandlers [_propertyPublicName]) (_changedEventsToFire || (_changedEventsToFire = [])).push (_propertyPublicName) ; } /*** build up list of onChange handlers to execute ***/ _onChangeHandler = _propertyProfile._onChange; if (_onChangeHandler) { if (typeof _onChangeHandler != _typeFunction) _onChangeHandler = _this [_onChangeHandler] ; if (!_onChangeHandlers) { _onChangeHandlers = []; _onChangeHandlerAddedFlagName = _this.objectName + '_handlerAlreadyAdded'; } if (!_onChangeHandler [_onChangeHandlerAddedFlagName]) { _onChangeHandler [_onChangeHandlerAddedFlagName] = 1; _onChangeHandlers.push (_onChangeHandler); } } } _this [_propertyPrivateName] = _propertyValue; } } else { _this [_propertyPublicOrPrivateName] = _propertyValue; (_propertiesToRegister || (_propertiesToRegister = {})) [_propertyPublicOrPrivateName] = _propertyPublicOrPrivateName ; } } } if (_propertiesToRegister) _class.registerProperties (_propertiesToRegister) ; if (_onChangeHandlers) { for (var _handlerNo = 0; _handlerNo < _onChangeHandlers.length; _handlerNo++) { var _onChangeHandler = _onChangeHandlers [_handlerNo]; delete _onChangeHandler [_onChangeHandlerAddedFlagName]; _onChangeHandler.call (_this,_propertyValuesBeingSet); } } if (_changedEventsToFire) { for ( var _changedEventNo = 0, _changedEventsToFireLength = _changedEventsToFire.length; _changedEventNo < _changedEventsToFireLength; _changedEventNo++ ) _this.fireEvent ('Changed.' + _changedEventsToFire [_changedEventNo]) ; /*? Instance Events Changed.[propertyName] The =Uize= base class implements a generalized mechanism for firing events when the values of set-get properties are changed. This means that for any set-get property that is registered through the =Uize.registerProperties= static method, a handler can be registered for a change in the value of that property without having to write any additional code to fire an event. Event Naming The name of a changed event that fires is of the form =Changed.[propertyName]=, where =propertyName= is the primary public name of the set-get property. For example, if you registered a set-get property named =value=, then a =Changed.value= event would fire each time this property is changed. Property Aliases If a set-get property has aliases, handlers can be registered for the property's changed event using any of the aliases. However, the name of the event when it fires will always be derived from the primary public name (ie. first in the alias list) of the property. So, for example, if a set-get property was registered with the public names =color= and =hexRgb=, both =Changed.color= and =Changed.hexRgb= would be treated as equivalent. EXAMPLE ...................................................................... function handleColorChange () { // do stuff } myColorWidget.addEventHandler ('Changed.color',handleColorChange); myColorWidget.removeEventHandler ('Changed.hexRgb',handleColorChange); ...................................................................... In this example, the =handleColorChange= function would not be executed when the value of the =color= set-get property changes, because =Changed.color= and =Changed.hexRgb= are treated as equivalent and therefore the =removeEventHandler= statement effectively removes the handler registered in the previous statement. Must Use the set Method The =Changed.[propertyName]= event will only fire for a particular set-get property if the value for that property is set using the =set= method, since it is within the =set= method that change detection occurs and the event is fired. If you simply assign a value by directly accessing the private name of the property, then the event will not fire. Only On Change, Not Every Set The =Changed.[propertyName]= event only fires for a particular set-get property when the value for that property is *changed* by using the =set= method. So, if the =set= method is called but the value that is specified is already the value of the property, then there will be no change and no event will be fired. Additionally, if a =conformer= is registered for the property and the action of the conformer results in the property value not being changed, then no event will be fired - even if the value specified in the =set= call is different to the current value of the property. This can be the case if the value is at an edge of its valid range, an attempt is made to set the value outside of its valid range, and the conformer has the action of constraining the value so that it remains at the same edge of its valid range. */ } /*? Instance Methods set Lets you set one or more of an instance's set-get properties. SYNTAX ............................. myInstance.set (propertiesOBJ); ............................. EXAMPLE ................................... myInstance.set ( { property1Name:'property1Value', property2Name:'property2Value', property3Name:'property4Value' } ); ................................... NOTES - see also the =get= instance method - see also the =Uize.get= static method - see also the =Uize.set= static method Static Methods Uize.set Lets you set the initial value for one of the class's set-get properties. SYNTAX ......................... Uize.set (propertiesOBJ); ......................... EXAMPLE ................................... Uize.set ( { property1Name:'property1Value', property2Name:'property2Value', property3Name:'property4Value' } ); ................................... NOTES - see also the =Uize.get= static method - see also the =get= instance method - see also the =set= instance method */ }; /*** Public Instance Methods ***/ _classPrototype.kill = function () { if (window [this.objectName]) window [this.objectName] = _null ; /*? Instance Methods kill Nulls out the property of the =window= object of the name =objectName=. This method may be useful if global window level references are made to instances of a class, usually for the purpose of group management, or the implementation of certain kinds of state exclusivity amongst instances of a class. This method is also intended to be overrided by subclasses where additional destructor style code may be desired. */ }; /*** Public Static Methods ***/ var _copyInto = _class.copyInto = function (_targetObject) { var _arguments = arguments, _argumentsLength = _arguments.length ; for (var _sourceObjectNo = 1; _sourceObjectNo < _argumentsLength; _sourceObjectNo++) { var _sourceObject = _arguments [_sourceObjectNo]; if (typeof _sourceObject == _typeObject) { for (var _propertyName in _sourceObject) _targetObject [_propertyName] = _sourceObject [_propertyName]; } } return _targetObject; /*? Static Methods Uize.copyInto Lets you copy properties into a target object from a source object. SYNTAX .......................................... MySubclass.copyInto (targetOBJ,sourceOBJ); .......................................... EXAMPLE ................................................ var targetObject = { foo:'How unoriginal!' }, sourceObject = { bar:'Indeed!' } ; MySubclass.copyInto (targetObject,sourceObject); ................................................ In the above example, after the code has been executed, =targetObject= will have both =foo= and =bar= properties while =sourceObject= will remain unchanged. Of course, the JavaScript language allows in-place creation of anonymous objects using what's termed the "literal syntax", so you could also add properties to an object as shown in the example below... ................................................... var targetObject = { foo:'How unoriginal!' }; MySubclass.copyInto (targetObject,{bar:'Indeed!'}); ................................................... */ }; _class.callOn = function (_object,_method,_arguments) { if (!_arguments) _arguments = []; var _methodIsString = typeof _method == _typeString, _methodIsFunction = typeof _method == _typeFunction ; function _callOn (_object) { if (typeof _object == _typeObject) { if (_class.isArray (_object)) { var _totalSubObjects = _object.length; for (var _subObjectNo = 0; _subObjectNo < _totalSubObjects; _subObjectNo++) _callOn (_object [_subObjectNo]) ; } else { var _methodIsStringAndIsInObject = _methodIsString && typeof _object [_method] == _typeFunction; if (_isInstance (_object) || _methodIsStringAndIsInObject) { if (_methodIsFunction || _methodIsStringAndIsInObject) (_methodIsFunction ? _method : _object [_method]).apply (_object,_arguments) ; } else { for (var _subObjectName in _object) _callOn (_object [_subObjectName]) ; } } } } _callOn (_object); /*? Static Methods Uize.callOn Recurses through the arbitrarily complex object specified, calling the specified method on all values that are instances of =Uize= subclasses, or that are objects that have a property whose name matches the method name specified and whose value is a function. This sounds like a mouthfull, but in a nutshell it allows the following kinds of things... - specifying a function that should be called as a method on a specified set of instances - specifying the name of a method that should be called on a specified set of instances SYNTAX ................................................ Uize.callOn (objectSetARRAYorOBJ,methodSTRorFN); ................................................ VARIATIONS ............................................................... Uize.callOn (objectSetARRAYorOBJ,methodSTRorFN,argumentsARRAY); ............................................................... When the optional =argumentsARRAY= parameter is specified, this set of arguments will be passed when calling the specified method on each of the objects in the set. EXAMPLE 1 .................................................................................................... Uize.callOn ([instance1,instance2,instance3,instance4,instance5,instance6],'set',[{enabled:false}]); .................................................................................................... The above statement would be equivalent to... ................................ instance1.set ({enabled:false}); instance2.set ({enabled:false}); instance3.set ({enabled:false}); instance4.set ({enabled:false}); instance5.set ({enabled:false}); instance6.set ({enabled:false}); ................................ EXAMPLE 2 ............................................................................................ function myPhantomMethod () { // do stuff } Uize.callOn ([instance1,instance2,instance3,instance4,instance5,instance6],myPhantomMethod); ............................................................................................ The above statement would be equivalent to... ................................. function myPhantomMethod () { // do stuff } myPhantomMethod.call (instance1); myPhantomMethod.call (instance2); myPhantomMethod.call (instance3); myPhantomMethod.call (instance4); myPhantomMethod.call (instance5); myPhantomMethod.call (instance6); ................................. This method is most compelling when an object or array contains a dynamic set of instances on which a specific method needs to be called, or on which a specified function needs to be called as a method. */ }; _class.findRecordNo = function (_records,_match,_defaultNoIfNoMatch) { var _result = _class.isNumber (_defaultNoIfNoMatch) ? _defaultNoIfNoMatch : -1; if (_records) { var _recordsLength = _records.length; for (var _recordNo = 0; _recordNo < _recordsLength; _recordNo++) { var _record = _records [_recordNo], _isMatch = true ; for (var _propertyName in _match) { _isMatch = _record [_propertyName] === _match [_propertyName]; if (!_isMatch) break; } if (_isMatch) { _result = _recordNo; break; } } } return _result; /*? Static Methods Uize.findRecordNo Returns an integer, indicating the index in the specified records array of the first record whose contents is a superset of the contents of the specified match object. If no matching record can be found, then this method will return the value =-1=. SYNTAX .......................................... Uize.findRecordNo (recordsARRAY,matchOBJ); .......................................... EXAMPLE ........................................................................................ var fruits = [ { type:'Apple', variety:'Braeburn', color:'red' }, { type:'Orange', variety:'Navel', color:'orange' }, { type:'Apple', variety:'Granny Smith', color:'green' }, { type:'Apple', variety:'Red Delicious', color:'red' } ], greenAppleRecordNo = Uize.findRecordNo (fruits,{type:'Apple',variety:'Granny Smith'}) ; ........................................................................................ In the above example, the variable =greenAppleRecordNo= will have the value =2=. NOTES - This method uses strict matching, so the statement =Uize.findRecordNo ([{index:'0'},{index:'1'}],{index:1})= will return =-1=. - see also the related =Uize.findRecord= static method */ }; _class.findRecord = function (_records,_match,_defaultNoIfNoMatch) { var _recordNo = _class.findRecordNo (_records,_match,_defaultNoIfNoMatch); return _recordNo > -1 ? _records [_recordNo] : null; /*? Static Methods Uize.findRecord Returns the first record in the specified records array whose contents is a superset of the contents of the specified match object. If no matching record can be found, then this method will return the value =null=. SYNTAX ........................................ Uize.findRecord (recordsARRAY,matchOBJ); ........................................ This method uses the =Uize.findRecordNo= static method in its implementation, so consult the reference for that method for further details and for an example. NOTES - This method uses strict matching, so the statement =Uize.findRecord ([{index:'0'},{index:'1'}],{index:1})= will return =null=. */ }; _class.getBlankImageUrl = function () { return Uize.pathToResources + 'Uize/blank.gif'; /*? Static Methods Uize.getBlankImageUrl Returns a string, representing the relative path from the current document to the "blank.gif" image resource that is available to all =Uize= subclasses that may need it in generating HTML markup, or in building or manipulating DOM nodes. SYNTAX ......................... Uize.getBlankImageUrl (); ......................... */ }; var _getGuid = _class.getGuid = function () { return '_UIZE_GUID_' + _UIZE_GUIDs++; /*? Static Methods Uize.getGuid Returns a string value, being an ID that is globally unique in the current window context. When an instance of a =Uize= subclass is created, its =objectName= instance property is set to a value returned by this method. This method may also be useful in the implementations of subclasses, in situations where it is necessary to stash something in a context shared by different modules of code that need to be able to interoperate without conflicts. */ }; var _getPathToLibrary = _class.getPathToLibrary = function (_libraryFilename) { var _result = '', _scriptBlocks = document.getElementsByTagName ('SCRIPT') ; for (var _scriptBlockNo = 0; _scriptBlockNo < _scriptBlocks.length; _scriptBlockNo++) { var _scriptSrc = _scriptBlocks [_scriptBlockNo].src, _libraryFilenamePos = _scriptSrc.indexOf (_libraryFilename) ; if (_libraryFilenamePos > -1) { _result = _scriptSrc.substr (0,_scriptSrc.lastIndexOf ('/',_libraryFilenamePos) + 1); break; } } return _result; /*? Static Methods Uize.getPathToLibrary Returns a string, representing the relative path from the current document to the folder containing the specified JavaScript library. SYNTAX ................................................. MySubclass.getPathToLibrary (libraryFilenameSTR); ................................................. Whereas the =Uize.pathToResources= static property specifies the relative path to the folder containing the "Uize.js" JavaScript library, this method can be used to find the relative path to a different JavaScript library that is being sourced into the document. This can be useful when the JavaScript library implementing a =Uize= subclass does not reside in the same folder alongside the "Uize.js" file. This method is useful in the implementation of =Uize= subclasses that may wish to, in their implementation, make use of image and other support resources located inside the folder that contains the class's JavaScript library. By using this method, a subclass's implementation does not need to know whether or not the document using it is being loaded through HTTP or from the local file system and does not need to impose extra requirements on developers regarding where its JavaScript library is located in relation to documents using it. NOTES - see also the =Uize.pathToResources= static property */ }; var _isInstance = _class.isInstance = function (_object) { return _object.objectClass ? _true : _false; /*? Static Methods Uize.isInstance Returns a boolean, indicating whether or not the parameter passed is a reference to an object instance or to a class. SYNTAX ........................................... MySubclass.isInstance (instanceOrClassOBJ); ........................................... This method can be useful when implementing methods that may be called on a class as well as on an instance of a class. */ }; var _substituteInto = _class.substituteInto = function (_sourceStr,_properties) { var _result = _sourceStr; if (typeof _result == _typeString) { for (var _propertyName in _properties) _result = _result.replace (new RegExp ('\\[#' + _propertyName + '\\]','gi'),_properties [_propertyName]) ; } return _result; /*? Static Methods Uize.substituteInto Lets you substitute the specified set of properties into the specified string. SYNTAX .................................................... MySubclass.substituteInto (sourceSTR,propertiesOBJ); .................................................... The string specified by the =sourceSTR= parameter should contain token markup so that the properties of the object specified in the =propertiesOBJ= parameter can be correctly substituted into the string. For each of the properties to substitute, the string should contain a token of the form =[#propertyName]=. Each substitution token for a property will be replaced with the property's value. EXAMPLE ........................................ MySubclass.substituteInto ( '[#foo] [#bar]', {foo:'How unoriginal!',bar:'Indeed!'} ); ........................................ In the above example, the method will return the value ="How unoriginal! Indeed!"=. EXAMPLE ........................................ MySubclass.substituteInto ( 'An [#fruit]. Oh, an [#fruit]!! Please, give me an [#fruit].', {fruit:'apple'} ); ........................................ If there are multiple tokens for the same property, then that property will be substituted multiple times. So, in the above example, the method will return the value ="An apple. Oh, an apple!! Please, give me an apple."=. EXAMPLE ........................................ MySubclass.substituteInto ( 'An orange. Oh, an orange!! Please, give me an orange.', {fruit:'apple'} ); ........................................ If there are no substitution tokens for a property, then that property will not be substituted. So, in the above example, the method will return the value ="An orange. Oh, an orange!! Please, give me an orange."=. EXAMPLE ........................................ MySubclass.substituteInto ( 'An [#fruit]. Oh, an [#fruit]!! Please, give me an [#fruit].', {vegetable:'artichoke'} ); ........................................ Substitution tokens for which there are no properties will be left in the string (they will not be blanked out). So, in the above example, the method will return the value ="An [#fruit]. Oh, an [#fruit]!! Please, give me an [#fruit]."=. */ }; /*** Public Static Properties ***/ _class.pathToResources = _getPathToLibrary ('Uize.js'); /*? Static Properties Uize.pathToResources A string, representing the relative path from the current document to the folder containing the =Uize= class's JavaScript library. This property is useful in the implementation of =Uize= subclasses that are to reside in the same folder alongside the =Uize= class's JavaScript file and that may wish to, in their implementation, make use of image and other support resources located inside that folder. By using this property, a subclass's implementation does not need to know whether or not the document using it is being loaded through HTTP or from the local file system and does not need to impose extra requirements on developers regarding where its JavaScript library is located in relation to documents using it. */ }) ();