The Uize.Class module provides a number of features to facilitate creation and definition of subclasses.

1.1.1.1. Subclass Creation

var MySubclass = MyClass.subclass ();

1.1.1.2. Feature Declaration Methods

The Uize.Class base class implements a novel mechanism for constructors that makes the "new" keyword optional when creating instances.

Because the Uize.Class base class utilizes the "no new" mechanism, one can create instances of any Uize.Class subclass either using the new operator or not. This means that you can use the "new" keyword or not with UIZE classes (as well as your own classes), and the end result will be the same.

THIS...

var myInstance = MyClass ();

IS EQUIVALENT TO...

var myInstance = new MyClass ();

The Uize.Class module implements a powerful and versatile event system, which can be used for application events outside the context of browser DOM events.

1.1.3.1. Event System Methods

For an in-depth discussion of events, consult the JavaScript Event System guide.

A state properties derivation is simply an expression that produces a derived value from one or more of the state properties of a class.

EXAMPLE

var CubeClass = Uize.Class.subclass ({
  stateProperties:{
    width:{value:10},
    height:{value:20},
    depth:{value:15},
    volume:{derived:'width,height,depth: width * height * depth'}
  }
});

var cubeInstance = CubeClass ();
alert (cubeInstance.get ('volume'));  // alerts the text "3000"

In the above example, the class CubeClass is being created with the state properties width, height, and depth, and with the derived property volume. The way that the value of the volume property is derived is specified using the derivation expression string 'width,height,depth: width height depth', which tells the Uize.Class module to compute the value using the width, height, and depth state properties as the determinants, and the expression width * height * depth as the computation.

Derived properties is just one way in which state properties derivations can be used. One can also use such derivations with the onChange instance method, and when specifying conditions with the isMet, once, and whenever instance methods of the condition system.

The Uize.Class module implements a condition system in the form of state properties combined with convenience methods that allow state properties to be treated semantically as conditions.

1.1.5.1. Condition System Methods

1.1.5.2. Specifying Conditions

myWidget.once (
  'wired',
  function () {
    // do something now that the widget has been wired
  }
);

myCollectionWidget.once (
  '!isEmpty',
  function () {
    // do something now that the collection is no longer empty
  }
);

myInstance.once (
  'phase1Done, phase2Done, phase3Done',
  function () {
    // execute code now that all three phases are done
  }
);

myInstance.once (
  ['phase1Done','phase2Done','phase3Done'],
  function () {
    // execute code now that all three phases are done
  }
);

myCollection.once (
  'wired, !isEmpty',
  function () {
    // execute code now that the collection widget is wired and no longer empty
  }
);

myCollection.once (
  ['wired','!isEmpty'],
  function () {
    // execute code now that the collection widget is wired and no longer empty
  }
);

myFishTankWater.once (
  function (width,height,depth) {return width * height * depth > 1000},
  function () {
    // execute code, now that the water volume of the fish tank exceeds 1000
  }
}

myFishTankWater.once (
  'width, height, depth : width * height * depth > 1000',
  function () {
    // execute code, now that the water volume of the fish tank exceeds 1000
  }
}

myCollectionWidget.once (
  '!isEmpty',
  function () {
    // do something now that the collection is no longer empty
  }
);

myCollectionWidget.once (
  ['wired','!isEmpty'],
  function () {
    // do something now that the collection is wired and no longer empty
  }
);

1.1.5.3. Wirings Object

1.1.5.4. Condition Handler

myFishTankWater.once (
  'width, height, depth : width * height * depth > 1000',
  function (width,height,depth) {
    alert (width + '(W) x ' + height + '(H) x ' + depth + '(D)');
  }
}

myFishTankWater.set ({
  width:10,
  height:11,
  depth:12
});

The features listed in this section have been introduced in this module.

INSTANCE METHODS

fire | get | is | isMet | kill | met | onChange | once | set | toggle | unmet | unwire | valueOf | whenever | wire

STATIC METHODS

Uize.Class.alphastructor | Uize.Class.declare | Uize.Class.doMy | Uize.Class.dualContextMethods | Uize.Class.dualContextProperties | Uize.Class.fire | Uize.Class.get | Uize.Class.instanceMethods | Uize.Class.instanceProperties | Uize.Class.mixins | Uize.Class.omegastructor | Uize.Class.set | Uize.Class.singleton | Uize.Class.stateProperties | Uize.Class.staticMethods | Uize.Class.staticProperties | Uize.Class.subclass | Uize.Class.superclass | Uize.Class.toggle | Uize.Class.unwire | Uize.Class.wire

STATIC PROPERTIES

Uize.Class.moduleName | Uize.Class.nonInheritableStatics | Uize.Class.pathToResources

No features have been overridden in this module.

This module has no inherited features.

Uize.Class.Test | Uize.Class.Value | Uize.Class.mChildObjectBindings | Uize.Class.mChildObjectEventBindings | Uize.Class.mDeclarativeChildObjects | Uize.Class.mModels | Uize.Class.mTreeInheritance

The Uize.Class module is unit tested by the Uize.Test.Uize.Class test module.

In the most typical usage of the get instance method, a propertyNameSTR parameter can be specified in order to get the value of a single state property.

SYNTAX

propertyValueANYTYPE = myInstance.get (propertyNameSTR);

EXAMPLE

var mySlider = Uize.Widget.Bar.Slider ({
  minValue:0,
  maxValue:100,
  value:57
});

alert (mySlider.get ('value')); // alerts the text "57

When a propertyNamesARRAY parameter is specified in place of the propertyNameSTR parameter, the values for the instance state properties specified in the array will be populated into an object and returned.

SYNTAX

propertyValuesOBJ = myInstance.get (propertyNamesARRAY);

EXAMPLE

mySlider.set ('minValue',0);
mySlider.set ('maxValue,100);
mySlider.set ('value',57);

sliderValueAndRange = mySlider.get (['minValue','maxValue','value']);

After the above code has been executed, the sliderValueAndRange variable would have the value {minValue:0,maxValue:100,value:57}.

When a propertyNamesARRAY parameter is specified in place of the propertyNameSTR parameter, the values for the instance state properties specified in the array will be populated into an object and returned.

SYNTAX

propertyValuesOBJ = myInstance.get (propertiesOBJ);

EXAMPLE

mySlider.set ('minValue',0);
mySlider.set ('maxValue,100);
mySlider.set ('value',57);

sliderValueAndRange = mySlider.get ({minValue:0,maxValue:0,value:0});

After the above code has been executed, the sliderValueAndRange variable would have the value {minValue:0,maxValue:100,value:57}. The values of the properties in the properties object, as specified by the propertiesOBJ parameter, are immaterial - for whatever properties exist in the object, the values for the corresponding state properties of the instance will be returned.

When no parameter is specified, the get instance method will return an object containing values for all the state properties of the instance.

SYNTAX

allPropertyValuesOBJ = myInstance.get ();

For one thing, this variation makes it easy to create a new instance of a class with the same state as an existing instance.

EXAMPLE

copyOfMyFade = Uize.Fade (myFade.get ());

In this example, an instance of the class Uize.Fade is being created by passing the constructor all the state property values obtained from the myFade instance using the get method. The new instance created will then have the same state as the myFade instance.

In its most basic usage, the isMet method can be used to test if a single state property becomes truthy or falsy.

SYNTAX

isMetBOOL = myInstance.isMet (propertyConditionSTR);

One can test if all properties in a set of state properties are truthy or falsy, by specifying the state properties as an array of property names or as a comma-separated list string.

SYNTAX

isMetBOOL = myInstance.isMet (propertiesConditionARRAYorSTR);

One can test if a compound condition has been met, by specifying the compound condition in the form of a condition function or condition expression string.

SYNTAX

isMetBOOL = myInstance.isMet (compoundConditionSTRorFUNC);

The concept of a condition is common to multiple instance methods of the Uize.Class module.

For more information, consult the section on the condition system. In particular, see the in-depth section on specifying conditions, which covers the common way in which conditions can be specified when using the isMet, once, and whenever instance methods.

The met method is offered as a convenience to improve the semantics of code that is using state properties to represent conditions, and is a very thin wrapper around the set instance method.

The statement myInstance.met ('myCondition') is equivalent to the statement myInstance.set ('myCondition',true). When using a state property to represent a condition, the met method is a semantically elegant way to set the value of the property to true to indicate that the condition represented by the property has been met.

EXAMPLE

MyClass.prototype.initialize = function () {
  // some code here to do the initialization
  this.met ('initialized');
};

In the above example, an initialize instance method is defined for the class MyClass. In the method's implementation, after all the initialization has been performed, the met method is being called to indicate that the initialized condition has been met, where initialized is the name of a state property provided in MyClass. Now, other code can be registered to be executed only once an instance has been initialized by using the once instance method, as follows...

myInstance.once (
  'initialized',
  function () {
    // do some stuff once the instance has been initialized
  }
);

In its most typical usage, a single condition can be set as having been met by specifying the name of the condition for the propertyNameSTR parameter.

SYNTAX

myInstance.met (propertyNameSTR);

EXAMPLE

this.met ('someSelected');

In cases where you wish to set multiple conditions as having been met, the names of those conditions can be supplied by specifying an array for the propertyNamesARRAY parameter.

SYNTAX

myInstance.met (propertyNamesARRAY);

EXAMPLE

this.met (['initialized', 'ready']);

The handler for a change event can expect to receive the following two parameters...

EXAMPLE

rectangle.onChange (
  function (width,height) {return width * height},
  function (area,determinants) {
    alert ('Area: ' + area + ' (' + determinants [0] + ' x ' + determinants [1] + ')')
  }
);

In the above example, we are registering a handler for a state properties derivation that derives an area value from the width and height state properties of a rectangle instance. In addition to declaring an area argument for the derived value, the handler function is also declaring a determinants argument that can be used to inspect the values of the derivation's determinants (the width and height state properties, respectively). Because the derivation was declared with width first and height second, this will be the order of the properties' values in the array passed via the determinants argument.

2.7.1.1. Arguments Optional

The onChange instance method returns a wirings object, which provides a means with which to unwire all the event wirings associated with registering a handler using this method.

In its most basic usage, code can be registered to be executed once a single state property becomes truthy or falsy.

SYNTAX

wiringsOBJ = myInstance.once (propertyConditionSTR,handlerFUNC);

The propertyConditionSTR parameter specifies the name of a state property, with an optional "!" (exclamation mark) prefix for indicating condition inversion. If simply the name of a state property is specified, then the handler code specified by the handlerFUNC parameter will be executed once the property is truthy. If the optional "!" prefix is specified, then the handler code will be executed once the property is falsy.

Code can be registered to be executed once a compound "and" style condition involving multiple state properties become truthy, by specifying the state properties using the propertiesConditionSTRorARRAY parameter.

SYNTAX

wiringsOBJ = myInstance.once (propertiesConditionSTRorARRAY,handlerFUNC);

The propertiesConditionSTRorARRAY parameter allows the state properties to be specified either as a comma-separated list string, or as an array of property name strings. In either form, the name of any property can be prefixed with a "!" (exclamation mark) character to achieve condition inversion for the individual property. The condition, as a whole, is truthy when all of the state property sub-parts of the condition are truthy (taking into account optional inversion for any state property).

Code can be registered to be executed once a compound condition is met, by specifying the compound condition in the form of a condition function or condition expression string.

SYNTAX

wiringsOBJ = myInstance.once (compoundConditionFUNC,handlerFUNC);
wiringsOBJ = myInstance.once (compoundConditionSTR,handlerFUNC);

If the condition specified in the call to the once method is already met at the time that the method is called, then the handler specified by the handlerFUNC parameter will be executed immediately.

Otherwise, handlers will be wired for the Changed.* (value change) events for all the state properties that affect the condition (the determinants). The condition evaluator will be executed each time any of the watched properties change value. As soon as the condition becomes met (i.e. the condition evaluator produces a truthy result), the handlers wired to watch the value change events of the properties will be unwired and the handler function registered for the condition will be executed. By design, the handler is only executed for the first time that the condition becomes met.

The concept of a condition is common to multiple instance methods of the Uize.Class module.

For more information, consult the section on the condition system. In particular, see the in-depth section on specifying conditions, which covers the common way in which conditions can be specified when using the isMet, once, and whenever instance methods. See also the section on the condition handler for information on the arguments it receives and the context on which it is called.

In the standard usage, a single propertyNamesValuesOBJ parameter can be passed to the set method in order to set values for one or more properties.

SYNTAX

myInstance.set (propertyNamesValuesOBJ);

Each key of the propertyNamesValuesOBJ object represents the name of a state property whose value should be set, and each corresponding value represents the value that a property should be set to.

EXAMPLE 1

myWidget.set ({enabled:false});

In the above example, the set method is being used to set the value of just one property - the enabled property of a widget instance.

EXAMPLE 2

mySlider.set ({
  maxValue:100,
  minValue:0,
  value:23
});

In the above example, the set method is being used to set values for multiple properties - the maxValue, minValue, and value properties of a slider widget instance.

The value of a state property can be set by providing two parameters to the set method: a string parameter specifying the name of a property, and a value parameter that can be of any type.

SYNTAX

myInstance.set (propertyNameSTR,propertyValueANYTYPE);

This variation of the set method is particularly useful in cases where you wish to use a variable or an expression to determine the state property whose value should be set. Consider the following example...

EXAMPLE

MyClass.prototype.increment = function (propertyName,amount) {
  this.set (propertyName,this.get (propertyName) + amount);
}

In the above example, a generic incrementer instance method is being implemented. It receives a propertyName parameter that specifies the state property to increment, and it passes the value of this parameter as the first parameter in the call to the set method.

2.9.2.1. Slightly Less Performant

The values for an arbitrary number of state properties can be set by providing the names and values of the properties using an arbitrary number of name-value pair arguments, where even numbered arguments are property names and odd numbered arguments are property values.

SYNTAX

myInstance.set (
  property1NameSTR,property1ValueANYTYPE,
  property2NameSTR,property2ValueANYTYPE,
  ... ... ...
  propertyNNameSTR,propertyNValueANYTYPE
);

This variation of the set method is an extension of the variation that lets you set the value for a property with name and value arguments, and has the same benefits and performance considerations.

The same value can be set for multiple state properties by specifying the names of the properties that should all be set to the same value in a propertyNamesARRAY parameter, and by specifying the value they should all be set to in a propertyValueANYTYPE parameter.

SYNTAX

myInstance.set (propertyNamesARRAY,propertyValueANYTYPE);

EXAMPLE

myWidget.set (['initialized','ready','enabled','busy'],false);

In the above example, the properties initialized, ready, enabled, and busy of a widget instance are all being set to false.

This variation of the set method can be useful in cases where you wish to set a good number of properties to the same value and where it would be more concise to use this form, or in cases where you are receiving an array of properties that should be set to some desired value. This variation can also be convenient when the value that you wish to set multiple properties to is the result of an expression and where you would otherwise need to create a local variable in order to avoid recalculating the expression for each property.

INSTEAD OF...

var initValue = env.config.hasOwnProperty ('initValue') ? env.config.initValue : false;
myInstance.set ({
  foo:initValue,
  bar:initValue,
  baz:initValue
});

USE...

myInstance.set (
  ['foo','bar','baz'],
  env.config.hasOwnProperty ('initValue') ? env.config.initValue : false
);

The unmet method is offered as a convenience to improve the semantics of code that is using state properties to represent conditions, and is a very thin wrapper around the set instance method.

The statement myInstance.unmet ('myCondition') is equivalent to the statement myInstance.set ('myCondition',false). When using a state property to represent a condition, the unmet method is a semantically elegant way to set the value of the property to false to indicate that the condition represented by the property is not met / no longer met.

EXAMPLE

MyClass.prototype.die = function () {
  // some code here to tear down the instance
  this.unmet ('initialized');
};

In the above example, a die instance method is defined for the class MyClass. In the method's implementation, after all the tear down steps have been performed, the unmet method is being called to indicate that the initialized condition is no longer met, where initialized is the name of a state property provided in MyClass. It is assumed that some other method, such as an initialize instance method for the class, is responsible for setting the condition as having been met with a statement like this.met ('initialized').

In its most typical usage, a single condition can be set as being unmet by specifying the name of the condition for the propertyNameSTR parameter.

SYNTAX

myInstance.unmet (propertyNameSTR);

EXAMPLE

this.unmet ('someSelected');

In cases where you wish to set multiple conditions as being unmet, the names of those conditions can be supplied by specifying an array for the propertyNamesARRAY parameter.

SYNTAX

myInstance.unmet (propertyNamesARRAY);

EXAMPLE

this.unmet (['initialized', 'ready']);

A handler for a specific event can be unwired by specifying the name of the event as the first argument and the previously wired handler for the event as the second argument.

SYNTAX

myInstance.unwire (eventNameSTR,eventHandlerSTRorFNorOBJ);

When no eventHandlerSTRorFNorOBJ parameter is specified, then all handlers registered for the event specified in the eventNameSTR parameter will be removed.

SYNTAX

myInstance.unwire (eventNameSTR);

When only a single eventNamesToHandlersMapOBJ parameter is specified, then event handlers for multiple events can be specified using an object hash.

SYNTAX

myInstance.unwire (eventNamesToHandlersMapOBJ);

This variation is provided as a convenience and has the effect of iteratively calling the unwire instance method for each event-name-to-handler mapping in the eventNamesToHandlersMapOBJ object.

All previously wired handlers for all events can be unwired by specifying no arguments.

SYNTAX

myInstance.unwire ();

In its most basic usage, code can be registered to be executed whenever a single state property becomes truthy or falsy.

SYNTAX

wiringsOBJ = myInstance.whenever (propertyConditionSTR,handlerFUNC);

The propertyConditionSTR parameter specifies the name of a state property, with an optional "!" (exclamation mark) prefix for indicating condition inversion. If simply the name of a state property is specified, then the handler code specified by the handlerFUNC parameter will be executed whenever the property becomes truthy. If the optional "!" prefix is specified, then the handler code will be executed whenever the property becomes falsy.

Code can be registered to be executed whenever a compound "and" style condition involving multiple state properties become truthy, by specifying the state properties using the propertiesConditionSTRorARRAY parameter.

SYNTAX

wiringsOBJ = myInstance.whenever (propertiesConditionARRAYorSTR,handlerFUNC);

The propertiesConditionSTRorARRAY parameter allows the state properties to be specified either as a comma-separated list string, or as an array of property name strings. In either form, the name of any property can be prefixed with a "!" (exclamation mark) character to achieve condition inversion for the individual property. The condition, as a whole, is truthy when all of the state property sub-parts of the condition are truthy (taking into account optional inversion for any state property).

Code can be registered to be executed whenever a compound condition becomes met, by specifying the compound condition in the form of a condition function or condition expression string.

SYNTAX

wiringsOBJ = myInstance.whenever (compoundConditionFUNC,handlerFUNC);
wiringsOBJ = myInstance.whenever (compoundConditionSTR,handlerFUNC);

If the condition specified in the call to the whenever method is already met at the time that the method is called, then the handler specified by the handlerFUNC parameter will be executed immediately.

Handlers will also be wired for the Changed.* (value change) events for all the state properties that affect the condition (the determinants). The condition evaluator will be executed each time any of the watched properties change value. Whenever the condition becomes met (i.e. the condition evaluator produces a truthy result after previously having produced a falsy result), the handler function registered for the condition will be executed.

The concept of a condition is common to multiple instance methods of the Uize.Class module.

For more information, consult the section on the condition system. In particular, see the in-depth section on specifying conditions, which covers the common way in which conditions can be specified when using the isMet, once, and whenever instance methods. See also the section on the condition handler for information on the arguments it receives and the context on which it is called.

When a class is created, the MyClass.nonInheritableStatics static property is automatically initialized on that class to a fresh object with the value {nonInheritableStatics:1}.

This initial mapping means that the MyClass.nonInheritableStatics static property is, itself, not inheritable by subclasses - subclasses get their own fresh object. So, in our example, when the MyClassSubclass subclass is created, its fresh MyClassSubclass.nonInheritableStatics property does not have an entry for the someUtilityFunction static feature, because it does not have that static feature and the contents of the MyClass.someUtilityFunction object is not inherited by the MyClassSubclass class.

The Uize.Class.doMy method is most useful when calling a superclass' version of an instance method on an instance, and produces a more concise and readable form than the typical approach.

INSTEAD OF...

_superclass.prototype.someMethod.call (this);

USE...

_superclass.doMy (this,'someMethod');

The Uize.Class.doMy method also supports calling a superclass' instance methods with arguments, as follows...

INSTEAD OF...

_superclass.prototype.someMethod.apply (this,[arg1,arg2,...,argN]);

USE...

_superclass.doMy (this,'someMethod',[arg1,arg2,...,argN]);

As you can tell from the above before-and-after examples, using the Uize.Class.doMy method produces code that is both a bit more concise as well as mentally easier to parse.

In its most simple form, a class' instance method can be called on an instance, without supplying arguments, by specifying just the instance reference and the instance method name as arguments.

SYNTAX

resultANYTYPE = MyClass.doMy (instanceOBJ,instanceMethodSTR);

EXAMPLE

return _superclass.subclass ({
  instanceMethods:{
    wireUi:function () {
      if (!this.isWired) {
        // do some wiring specific to this widget class

        _superclass.doMy (this,'wireUi');
      }
    }
  }
});

In the above example, a subclass is being created with an overrided implementation for the wireUi instance method. In this method, additional code is being executed (represented by the placeholder comment) before the superclass' version of the wireUi method is called on the instance.

When an instance method of a class needs to be called with arguments, the arguments can be specified with the optional argumentsLIST argument.

SYNTAX

resultANYTYPE = MyClass.doMy (instanceOBJ,instanceMethodSTR,argumentsLIST);

EXAMPLE

return _superclass.subclass ({
  instanceMethods:{
    someMethod:function (foo,bar,baz,qux) {
      _superclass.doMy (this,'someMethod',[foo,bar]);

      // now do extra stuff for subclass
    }
  }
});

In the above example, a subclass is being created with an overrided implementation for the superclass' someMethod instance method. Now, the superclass' version of someMethod supports foo and bar arguments, while the overrided version also supports the additional baz and qux arguments. In the overrided implementation, we first call the superclass' version of the method on the instance, passing just the foo and bar arguments that it supports, after which the additional code in the overrided version is executed (represented by the comment placeholder, and presumably making use of the additional baz and qux arguments).

In the standard usage, a single propertyNamesValuesOBJ parameter can be passed to the Uize.Class.set method in order to set initial values for one or more properties.

SYNTAX

MyClass.set (propertyNamesValuesOBJ);

Each key of the propertyNamesValuesOBJ object represents the name of a state property whose initial value should be set, and each corresponding value represents the initial value that should be set for a property.

EXAMPLE 1

MyWidgetClass.set ({enabled:false});

In the above example, the Uize.Class.set method is being used to set the initial value for just one property - the enabled property of a widget class.

EXAMPLE 2

Uize.Widget.Bar.Slider.set ({
  maxValue:100,
  minValue:0,
  value:0
});

In the above example, the Uize.Class.set method is being used to set initial values for multiple properties - the maxValue, minValue, and value properties of the Uize.Widget.Bar.Slider widget class.

The initial value for a state property can be set by providing two parameters to the Uize.Class.set method: a string parameter specifying the name of a property, and a value parameter that can be of any type.

SYNTAX

MyClass.set (propertyNameSTR,propertyValueANYTYPE);

This variation of the Uize.Class.set method is particularly useful in cases where you wish to use a variable or an expression to determine the state property whose initial value should be set. Consider the following example...

EXAMPLE

MyClass.increment = function (propertyName,amount) {
  this.set (propertyName,this.get (propertyName) + amount);
}

In the above example, a generic incrementer static method is being implemented. It receives a propertyName parameter that specifies the state property whose initial value should be incremented, and it passes the value of this parameter as the first parameter in the call to the Uize.Class.set method.

5.12.2.1. Slightly Less Performant

The initial values for an arbitrary number of state properties can be set by providing the names and values of the properties using an arbitrary number of name-value pair arguments, where even numbered arguments are property names and odd numbered arguments are property values.

SYNTAX

MyClass.set (
  property1NameSTR,property1ValueANYTYPE,
  property2NameSTR,property2ValueANYTYPE,
  ... ... ...
  propertyNNameSTR,propertyNValueANYTYPE
);

This variation of the Uize.Class.set method is an extension of the variation that lets you set the initial value for a property with name and value arguments, and has the same benefits and performance considerations.

The same initial value can be set for multiple state properties by specifying the names of the properties whose initial values should all be set to the same value in a propertyNamesARRAY parameter, and by specifying the initial value that should be set for them all in a propertyValueANYTYPE parameter.

SYNTAX

MyClass.set (propertyNamesARRAY,propertyValueANYTYPE);

EXAMPLE

MyWidgetClass.set (['initialized','ready','enabled','busy'],false);

In the above example, the initial value for the properties initialized, ready, enabled, and busy of a widget class is being set to false.

This variation of the Uize.Class.set method can be useful in cases where you wish to set the initial value for a good number of properties to the same value and where it would be more concise to use this form, or in cases where you are receiving an array of properties whose initial values should all be set to some desired value. This variation can also be convenient when the initial value that you wish to set for multiple properties is the result of an expression and where you would otherwise need to create a local variable in order to avoid recalculating the expression for each property.

INSTEAD OF...

var initValue = env.config.hasOwnProperty ('initValue') ? env.config.initValue : false;
MyClass.set ({
  foo:initValue,
  bar:initValue,
  baz:initValue
});

USE...

MyClass.set (
  ['foo','bar','baz'],
  env.config.hasOwnProperty ('initValue') ? env.config.initValue : false
);

When no parameters are specified, this method will return a singleton for the class in the default scope.

SYNTAX

singletonOBJ = MyClass.singleton ();

When the Uize.Class.singleton static method is called on a class, if a singleton instance has already been created for the default scope, then that instance will be returned. Otherwise, a singleton instance will be created for the default scope and then returned.

When the optional scopeSTR parameter is specified, this method will return a singleton for the class in the specified scope.

SYNTAX

singletonOBJ = MyClass.singleton (scopeSTR);

When the Uize.Class.singleton static method is called on a class, if a singleton instance has already been created for the specified scope, then that instance will be returned. Otherwise, a singleton instance will be created for the specified scope and then returned.

When the optional propertiesOBJ parameter is specified, then this method will return a singleton for the class in the specified scope, and with the state of its state properties set using the propertiesOBJ object.

SYNTAX

singletonOBJ = MyClass.singleton (scopeSTR,propertiesOBJ);

When the Uize.Class.singleton static method is called on a class, if a singleton instance has already been created for the specified scope, then that instance will be set to the state specified by the propertiesOBJ parameter and then returned. Otherwise, a singleton instance will be created for the specified scope, with its state initialized using the propertiesOBJ parameter, and then returned.

As a convenience, the Uize.Class.singleton static method lets you optionally specify a scope when getting singleton instances, using the scopeSTR parameter.

If no scopeSTR parameter is specified when getting a singleton for a class, then the default scope (an empty string) will be used. Therefore, the statement MyClass.singleton () is equivalent to the statement MyClass.singleton ('').

A scope provides multiple different bits of related but distributed code to get a reference to the same singleton by specifying the same scope, while still allowing other code to share references to a different singleton created using a different scope.

As a convenience, the Uize.Class.subclass method supports a variation that takes a single object parameter, as a means of declaring features by type when creating a class.

SYNTAX

MyClass = Uize.Class.subclass (featuresByTypeOBJ);

Using this variation, one or more features of various different feature types can be conveniently declared during the subclass creation. When using this variation, setting the alphastructor and/or omegastructor for the class being created must be done by specifying values for the alphastructor and/or omegastructor properties of the featuresByTypeOBJ object.

EXAMPLE

var MySubclass = MyClass.subclass ({
  alphastructor:function () {
    // implementation here
  },
  omegastructor:function () {
    // implementation here
  },
  staticMethods:{
    staticMethod1:function () {
      // implementation here
    },
    staticMethod2:function () {
      // implementation here
    }
  },
  instanceMethods:{
    instanceMethod1:function () {
      // implementation here
    },
    instanceMethod2:function () {
      // implementation here
    }
  },
  stateProperties:{
    stateProperty1:{
      // property profile
    },
    stateProperty2:{
      // property profile
    }
  }
});

A subclass can be created with just an alphastructor set, by specifying just a single alphastructorFUNC function type parameter.

SYNTAX

MyClass = Uize.Class.subclass (alphastructorFUNC);

Consider the following example...

EXAMPLE

var MyClass = Uize.Class.subclass (
  function () {
    this.foo = 'How unoriginal!';
  }
);

var MySubclass = MyClass.subclass (
  function () {
    this.bar = this.foo + ' Indeed!';
  }
);

In the above example, MySubclass is a subclass of MyClass, which is in turn a subclass of the Uize.Class base class. Now, when an instance of MySubSubclass gets created, the constructor of MyClass 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!".

A subclass can be created with both an alphastructor and an omegastructor set, by specifying the alphastructorFUNC and omegastructorFUNC function type parameters.

SYNTAX

MyClass = Uize.Class.subclass (alphastructorFUNC,omegastructorFUNC);

A subclass can be created with just an omegastructor set, by specifying the alphastructorFUNC and omegastructorFUNC parameters and specifying the value null or undefined for the alphastructorFUNC parameter.

SYNTAX

MyClass = Uize.Class.subclass (null,omegastructorFUNC);
MyClass = Uize.Class.subclass (undefined,omegastructorFUNC);

A handler for a specific event can be unwired by specifying the name of the event as the first argument and the previously wired handler for the event as the second argument.

SYNTAX

MyClass.unwire (eventNameSTR,eventHandlerSTRorFNorOBJ);

When no eventHandlerSTRorFNorOBJ parameter is specified, then all handlers registered for the event specified in the eventNameSTR parameter will be removed.

SYNTAX

MyClass.unwire (eventNameSTR);

When only a single eventNamesToHandlersMapOBJ parameter is specified, then event handlers for multiple events can be specified using an object hash.

SYNTAX

MyClass.unwire (eventNamesToHandlersMapOBJ);

This variation is provided as a convenience and has the effect of iteratively calling the Uize.Class.unwire static method for each event-name-to-handler mapping in the eventNamesToHandlersMapOBJ object.

All previously wired handlers for all events can be unwired by specifying no arguments.

SYNTAX

MyClass.unwire ();

The name of a changed event that fires is of the form Changed.[propertyName], where propertyName is the primary public name of the state property. For example, if you declared a state property named value, then a Changed.value event would fire each time this property is changed.

If a state 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 (i.e. first in the alias list) of the property. So, for example, if a state property was declared with the public names color and hexRgb, both Changed.color and Changed.hexRgb would be treated as equivalent.

EXAMPLE

function handleColorChange () {
  // do stuff
}
myColorWidget.wire ('Changed.color',handleColorChange);
myColorWidget.unwire ('Changed.hexRgb',handleColorChange);

In this example, the handleColorChange function would not be executed when the value of the color state property changes, because Changed.color and Changed.hexRgb are treated as equivalent and therefore the unwire statement effectively removes the handler registered in the previous statement.

The Changed.[propertyName] event will only fire for a particular state 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.

The Changed.[propertyName] event only fires for a particular state 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.

When a Changed.[propertyName] event fires for a particular state property that has changed value, the event object that is passed as an argument to any handlers of the event will contain a newValue property to indicate the new value of the state property.

This allows us to access the new value of the state property without having to access the instance that owns the property in order to call its get method to get the value for the property.

INSTEAD OF...

myWidget.addChild ('slider',Uize.Widget.Bar.Slider).wire (
  'Changed.value',
  function (event) {
    console.log (event.source.get ('value'));
  }
);

USE...

myWidget.addChild ('slider',Uize.Widget.Bar.Slider).wire (
  'Changed.value',
  function (event) {
    console.log (event.newValue);
  }
);

In the above example, we're adding a slider child widget to the myWidget parent widget. Because the addChild instance method returns a reference to the added child widget, we can chain a call to the child's wire method in order to wire a handler for its Changed.value event.

Now, without the newValue property of the event object, we could either access the new value by getting to the instance through the source object of the event (as in event.source.get ('value')), or we could dereference the child widget from the myWidget parent (as in myWidget.children.slider.get ('value')).

Both of these approaches are more cumbersome than simply using the newValue property that is provided as part of the event object for Changed.[propertyName] events.

By far the most common type of handler used when wiring event handlers is a function reference.

A function registered as a handler for an event should expect to receive one parameter, being a reference to the event object that is associated to the event.

When a string value is specified for the eventHandlerSTRorFNorOBJ parameter, a function object will be constructed from that string for the purpose of handling the event.

One limitation of this handler type is that, unlike function type handlers, a code string specified by the eventHandlerSTRorFNorOBJ parameter cannot reference the event object.

When a reference to a Uize.Class subclass or an instance of a Uize.Class subclass is specified for the eventHandlerSTRorFNorOBJ parameter, then the event for which the handler is registered will be fired on that instance or class.

This facility provides a means for "relaying" instance or class events to another instance or class.

EXAMPLE

myWidget.children.someButton.wire ('Click',myWidget);

In the above example, a handler is being registered for the 'Click' event of a button (an instance of the Uize.Widget.Button class) that is a child widget of myWidget. By specifying myWidget as the handler for the Click event, that event will get relayed to myWidget. This means that other code can now register handlers on the Click event for myWidget, and those handlers will handle the Click event being relayed from the button widget.

Object handlers added in this way can be removed by using the unwire instance method and the Uize.Class.unwire static method, just as with any other type of handler, as in...

myWidget.children.someButton.unwire ('Click',myWidget);

However a handler is specified when wiring an event, that is how it must be specified in order to unwire the event.

If you specified a function reference as the handler when wiring an event, then you must specify that same, identical function reference in order to unwire that event. If you specified a code string as the handler, then you must specify the exact same code string in order to unwire that event. If you specified a reference to a Uize.Class subclass or an instance of a Uize.Class subclass as the handler when wiring an event, then you must specify the exact same object reference in order to unwire the event.