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.1.1. Event System Methods

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

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.2.1. Condition System Methods

The JavaScript new operator is optional when creating instances of Uize.Class subclasses, and you can make the new operator optional for your own object constructors using the newly added Uize.noNew static method.

1.1.3.1. Creating Instances of Uize Classes

// this works
var mySlider1 = new Uize.Widget.Bar.Slider ({minValue:0,maxValue:100,value:50});

// Look ma, no "new"!!!
var mySlider2 = Uize.Widget.Bar.Slider ({minValue:0,maxValue:100,value:50});

1.1.3.2. All Uize Classes Get the Benefit

// we create a widget class
var MyWidgetClass = Uize.Widget.subclass ();

// this works
var myWidgetClassInstance1 = new MyWidgetClass ();

// Look ma, no "new"!!!
var myWidgetClassInstance2 = MyWidgetClass ();

1.1.3.3. Applies for Other Uize Objects

// this works
var fuchsia = new Uize.Color ('#ff0fff');

// Look ma, no "new"!!!
var olive = Uize.Color ('#808000');

1.1.3.4. Using the Uize.noNew Method

// define the Food object
var Food = Uize.noNew (
  function (name,type) {
    this.name = name;
    this.type = type;
  }
);

// create an instance of Food using the new operator
var apple = new Food ('apple','fruit');
alert (apple.type);  // alerts the text "fruit"

// create an instance of Food without using the new operator
var rice = Food ('rice','grain');
alert (rice.type);  // alerts the text "grain"

// must always use "new" with this constructor
function Food (name,type) {
  this.name = name;
  this.type = type;
}

// "new" is optional with this constructor
var Food = Uize.noNew (
  function (name,type) {
    this.name = name;
    this.type = type;
  }
);

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

INSTANCE METHODS

fire | get | is | kill | met | once | set | toggle | unmet | unwire | wire

STATIC METHODS

Uize.Class.fire | Uize.Class.get | Uize.Class.registerProperties | Uize.Class.set | Uize.Class.singleton | Uize.Class.subclass | Uize.Class.superclass | Uize.Class.toggle | Uize.Class.unwire | Uize.Class.wire

STATIC PROPERTIES

Uize.Class.moduleName | Uize.Class.nonInheritableStatics

No features have been overridden in this module.

This module has no inherited features.

Uize.Class.Value

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.

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']);

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.

EXAMPLE 1

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

In the above example, a handler is being registered to be executed once the widget myWidget has been wired (ie. the value of its wired state property becomes true).

EXAMPLE 2

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

In the above example, code is being registered to execute once the isEmpty state property is false.

Code can be registered to be executed once all properties in a set of state properties become truthy or falsy, by specifying the state properties as an array of property names or as a comma-separated list string.

SYNTAX

wiringsOBJ = myInstance.once (propertiesConditionARRAYorSTR,handlerFUNC);

3.6.2.1. propertiesConditionARRAYorSTR

3.6.2.2. Examples

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
  }
);

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 (compoundConditionSTRorFUNC,handlerFUNC);

3.6.3.1. Condition Function

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
  }
}

3.6.3.2. Condition Expression String

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

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 condition evaluator will be executed each time any of the watched properties change value. As soon as the condition becomes met (ie. 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.

As a convenience, the once method supports condition inversion through an optional "!" (logical not) prefix that can be placed before the condition name.

EXAMPLE

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

In the above example, code is being registered to execute once the isEmpty state property is false. This is done by prefixing the "isEmpty" condition name with a "!" (bang / exclamation) character to indicate that the code should execute only once the collection is not empty (ie. the value of the isEmpty state property becomes false). The condition inversion facility is convenient in situations like this where you wish to execute code only once a property's value becomes falsy, rather than once the property's value becomes truthy (which is the standard behavior for the once method).

3.6.5.1. Condition Inversion with Multiple Property Conditions

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

The once method returns a wirings object that can be supplied to the unwire method in order to unwire the handler, in the unlikely event that one may wish to remove the handler before the condition becomes met.

This case is unlikely to arise except in exceptional situations, but the means is provided. In most cases, you will simply discard / ignore the return value of the once method. In the event that the condition is met when the once method is called, then the returned wirings object will be an empty object.

The handler code that is registered to be executed once a condition is met will be passed the values of all the state properties that affect the condition as arguments.

EXAMPLE

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
});

In the above example, code is being registered to be executed once the product of the width, height, and depth properties of the myFishTankWater instance exceeds 1000. Once the call to the set method has been executed, the volume of the fish tank's water will be 1320 and the handler will be executed.

Now, because the properties affecting the condition have been specified as "width, height, depth", the value of these state properties will be passed as arguments to the handler in the order width, height, and depth. In this case, the handler function is choosing to declare these function arguments, using the same names for the sake of clarity - you could ignore the arguments if you didn't care about the specific values at the time the condition is met, or you could use the arguments but name them differently. In this example, the alert statement will alert the text "10(W) x 11(H) x 12(D)".

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.

3.7.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']);

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.

4.4.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.

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.

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 registered 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 (ie. first in the alias list) of the property. So, for example, if a state 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.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 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.