1.1.1. The Joy of Reflection

1.1.2. Make It So

The state property mechanism provides a convenient system for managing state properties, including providing an easy way for code to...

It is not uncommon for the implementation of a class to utilize a combination of regular old properties and state properties.

Regular properties are any old properties assigned on the class or its instances. State properties are declared for a class using one of the following feature declaration approaches...

1.3.1. Properties on Steroids

State properties can be easily declared for a class, using the MyClass.stateProperties static method that is inherited from the Uize.Class base class, as follows...

var MyClass = Uize.Class.subclass ();
MyClass.stateProperties ({_propertyName:'propertyName'});

The above statement registers the state property with the public name propertyName and the private name _propertyName.

Once a state property has been declared, its value can be easily set using the set instance method that is inherited from the Uize.Class base class, as follows...

var myInstance = new MyClass;
myInstance.set ({propertyName:'propertyValue'});

Once a state property has been declared, its value can be easily queried using the get instance method that is inherited from the Uize.Class base class, as follows...

var myInstance = new MyClass;
myInstance.set ({propertyName:'propertyValue'});
alert (myInstance.get ('propertyName'));

In the above code, the alert statement will display the text propertyValue in the alert dialog.

Once a state property has been declared, its value can be easily set during construction of a new instance of your class, as follows...

var myInstance = new MyClass ({propertyName:'propertyValue'});
alert (myInstance.get ('propertyName'));

In the above code, the alert statement will display the text propertyValue in the alert dialog.

What good is a state property mechanism if it doesn't facilitate something useful?

Conforming a value is one such thing that is facilitated by the state property mechanism of the UIZE JavaScript Framework. When declaring state properties it is possible to register a conformer function to enforce valid values. Let's consider an example...

var MyClass = Uize.Class.subclass ();
MyClass.stateProperties ({
  _percentLoaded:{
    name:'percentLoaded',
    conformer:function (_value) {return Uize.constrain (_value,0,100)},
    value:0
  }
});
var myInstance = new MyClass ({percentLoaded:200});
alert (myInstance.get ('percentLoaded'));

In the above code, the alert statement will display the text 100 in the alert dialog.

This example uses the extended form for declaring a state property that lets you define the property's "profile" (but we'll get into that in more detail a bit later). In the example, a conformer function is registered for the percentLoaded state property, that conforms the property's value so that it doesn't fall outside of the range of 0 to 100. So, even though the code is trying to set the property's value to 200 during construction of an instance, the conformer conforms the value to not fall out of bounds.

Custom conformer functions are discussed in more detail in the section conformer function.

Values for state properties should always be set using the set method.

This is the only way to ensure that conformer functions and onChange handlers registered for state properties are invoked, and that handlers registered for the Changed.[propertyName] virtual event and the Changed.* wildcard event are executed.

INSTEAD OF...

this._propertyName = 'propertyValue';

USE...

this.set ({propertyName:'propertyValue'});

It is possible, within the code module that declares a particular state property, to set a value for that property using the property's private name.

For example, if a module declares a state property with the public name propertyName and the private name _propertyName, then code within that module could set a value for that property, using either the public or private name, as follows...

this.set ({propertyName:'propertyValue'});   // using the public name
this.set ({_propertyName:'propertyValue'});  // using the private name

Both of the above statements would have the same effect, provided that this code is within the implementation for some instance method within the code module that defines the class and all its state properties (and not some subclass or application code that uses the class). The benefit of using the private name is that it will be scrunched down by the Scruncher, thereby reducing the scrunched code size.

Occasionally, it becomes necessary to set the value for a state property whose name is dynamically determined by an expression, or passed as a parameter to some method.

This can be done by using the form of the set method that takes two parameters: the name of a state property, and the value it should be set to.

Consider the following example...

_class.instanceMethods ({
  increment:function (_propertyName,_amount) {
    this.set (_propertyName,this.get (_propertyName) + _amount);
  }
});

In the above example, an instance method has been defined that accepts the name of a state property as its first parameter and an increment amount as its second parameter. Once the current value for the specified property has been retrieved using the get method, it is then incremented and set using the form of the set method that takes property name and value as its two parameters. Easy.

The Uize.Class base class provides a convenient way to toggle the value of a boolean state property, in the form of the toggle instance method.

INSTEAD OF...

myInstance.set ({propertyName:!myInstance.get ('propertyName')});

USE...

myInstance.toggle ('propertyName');

The set method lets you set values for multiple state properties in a single call.

The parameter passed to the set method is an object, containing values for all the state properties you wish to set.

INSTEAD OF...

myInstance.set ({property1Name:'property1Value'});
myInstance.set ({property2Name:'property2Value'});
myInstance.set ({property3Name:'property3Value'});

USE...

myInstance.set ({
  property1Name:'property1Value',
  property2Name:'property2Value',
  property3Name:'property3Value'
});

In the above example, values for the property1Name, property2Name, and property3Name state properties are being set. There is no limit to the number of state properties that can be set in the same call to the set method.

The performance benefits from calling the set method only once include...

When accessing the value for a particular state property inside the code module that declares that property, the private name can be used.

For example, if a module declares a state property with the public name propertyName and the private name _propertyName, then code within that module could get the value for that property, using either the public or private name, as follows...

alert (this.get ('propertyName'));  // using the public name
alert (this._propertyName);         // using the private name

Both of the above statements would have the same effect, provided that this code is within the implementation for some instance method within the code module that defines the class and all its state properties (and not some subclass or application code that uses the class). The benefit of using the private name is that it will be scrunched down by the Scruncher, thereby reducing the scrunched code size.

Because the get method accepts a string parameter, specifying the name of the state property being accessed, getting values for properties that are dynamically determined by an expression (or passed as a parameter to some method) is easy.

Consider the following example...

_class.instanceMethods ({
  increment:function (_propertyName,_amount) {
    this.set (_propertyName,this.get (_propertyName) + _amount);
  }
});

In the above example, an instance method has been defined that accepts the name of a state property as its first parameter and an increment amount as its second parameter. The method then proceeds to increment the specified state property by the specified amount. Nothing special needs to be done to access the state property's value because the get method already takes a parameter for specifying the property's name.

When an array of state property names is supplied to the get method, the method obtains the values for the specified properties and returns them in an object, where the keys of the object are the property names and the values are, well, the values.

Let's consider an example...

myInstance.set ({
  property1Name:'property1Value',
  property2Name:'property2Value',
  property3Name:'property3Value',
  property4Name:'property4Value',
  property5Name:'property5Value'
});
var values = myInstance.get (['property1Name','property2Name','property3Name']);

In the above example, the values for five state properties are being set in the set method call. Then, the get method is being called with an array type value that specifies the names of just three of those properties, and its result is assigned to the values variable. After the code is executed, values will be an object with the contents...

{
  property1Name:'property1Value',
  property2Name:'property2Value',
  property3Name:'property3Value'
}

4.3.1. Transferring State

myInstance2.set ({property1Name:myInstance1.get ('property1Name')});
myInstance2.set ({property2Name:myInstance1.get ('property2Name')});
myInstance2.set ({property3Name:myInstance1.get ('property3Name')});

myInstance2.set (myInstance1.get (['property1Name','property2Name','property3Name']));

When no parameter is specified in the call to the get method, the method obtains the values for all the declared properties and returns them in an object, where the keys of the object are the property names and the values are the property values.

Let's consider an example...

var MyClass = Uize.Class.subclass ();
MyClass.stateProperties ({
  _property1Name:{name:'property1Name',value:'property1Value'},
  _property2Name:{name:'property2Name',value:'property2Value'},
  _property3Name:{name:'property3Name',value:'property3Value'}
});
var
  myInstance = new MyClass,
  values = myInstance.get ()
;

After the above code is executed, the values variable will be an object with the contents...

{
  property1Name:'property1Value',
  property2Name:'property2Value',
  property3Name:'property3Value'
}

The parameter passed to this method should be an object, whose properties' names are the private/internal names for the state properties being declared, and where the value for each property is a profile for each state property.

The profile for a state property can take two forms: the minimal profile, and the complete profile.

The minimal profile is a shorthand for declaring a state property, where the only thing being declared is a mapping between a private name and a public name.

EXAMPLE

MyClass.stateProperties ({_propertyName:'propertyName'});

In the above example, a state property is being declared, with the private name _propertyName and the public name propertyName. It can be accessed in the class' implementation in an instance method as this._propertyName, set in the class' implementation in an instance method as this.set ({_propertyName:'propertyValue'}), and set outside of the class' implementation in application code in a statement such as myInstance.set ({propertyName:'propertyValue'}) (where myInstance is an instance of the class MyClass).

IMPORTANT

When declaring state properties using the minimal profile, those properties cannot utilize the more advanced features of state properties, such as onChange handlers, conformer functions, value defaults, etc. that are available when using the complete profile. Without specifying an initial value for state properties using the value property of the complete profile, state properties will be initialized to the value undefined when creating new instances of a class.

Unlike the minimal profile, the complete profile lets you utilize the more advanced features of state properties, such as onChange handlers, conformer functions, value defaults, etc.

EXAMPLE

MyClass.stateProperties ({
  _percentLoaded:{
    name:'percentLoaded',
    conformer:function (_value) {return Uize.constrain (_value,0,100)},
    onChange:function () {
      if (this.isWired) this.setNodeValue ('percentLoaded',this._percentLoaded);
    },
    value:0
  }
});

In the above example, a state property with the public name percentLoaded and the private name _percentLoaded is being declared.

The name property in the profile specifies the property's public name. A conformer function is registered that is executed each time there is an attempt to set a new value for percentLoaded, and this function's implementation ensures that the property's value does not fall outside of the valid range of 0 to 100. An onChange handler function is registered that is executed each time the value of percentLoaded changes, and this function's implementation displays the current value in a node in the document (we're assuming this code is transplanted from a widget class' implementation). Finally, the value property in the profile specifies the initial value for percentLoaded, for all freshly minted instances of MyClass.

For any state property, you can use either the minimal profile or the complete profile.

So, when declaring multiple state properties in one call to the MyClass.stateProperties static method, you can use a combination of both profile types, as suits your needs.

EXAMPLE

MyClass.stateProperties ({
  _propertyName:'propertyName',
  _percentLoaded:{
    name:'percentLoaded',
    conformer:function (_value) {return Uize.constrain (_value,0,100)},
    onChange:function () {
      if (this.isWired) this.setNodeValue ('percentLoaded',this._percentLoaded);
    },
    value:0
  }
});

In the above example, two state properties are being declared. propertyName is being declared using the minimal profile, while percentLoaded is being declared using the complete profile.

If a public name is not specified for a state property, the public name is defaulted to be same as the private name. This offers two intriguing flavors of state properties (discussed below).

When declaring a state property, one specifies a mapping between its private name and its public name. With the the minimal profile, this is done by specifying a string value for the key that represents the property's private name. With the complete profile, this is done by specifying a value for the name property in the profile object. Now, if the public name is undefined, null, or an empty string, then the public name will be defaulted to the private name.

5.5.1. Naked State Properties

MyClass.stateProperties ({
  prop1:null,        // private & public name is prop1 - accessible as myInstance.prop1
  prop2:'',          // private & public name is prop2 - accessible as myInstance.prop2
  prop3:{value:10},  // private & public name is prop3 - accessible as myInstance.prop3
  prop4:'prop4',     // SILLY!!! don't specify public name here - let it default
  prop5:{            // SILLY!!! don't specify public name here - let it default
    name:'prop5',
    value:10
  }
});

5.5.2. Private State Properties

MyClass.stateProperties ({
  _prop1:null,         // private & public name is _prop1 - will be scrunched
  _prop2:'',           // private & public name is _prop2 - will be scrunched
  _prop3:{value:10},   // private & public name is _prop3 - will be scrunched
  _prop4:'_prop4',     // WRONG!!! string literal '_prop4' won't be scrunched
  _prop5:{             // WRONG!!! string literal '_prop5' won't be scrunched
    name:'_prop5',
    value:10
  }
});

Through a facility of the name property in the profile of a state property, multiple alternate public names can be specified for a state property.

Basically, when you specify the public name of a state property you can specify a pipe-separated list of public names, of the form...

'publicName1|publicName2|...|publicNameN'

EXAMPLE

var MyClass = Uize.Class.subclass ();
MyClass.stateProperties ({_title:'title|displayTitle'});
var myInstance = new MyClass;
myInstance.set ({displayTitle:'HELLO'});
alert (myInstance.get ('title'));

In the above example, a state property is being declared for the class MyClass, with the two public names title and displayTitle. When creating an instance of MyClass, a call to set the value for displayTitle is equivalent to setting the value for title, since both public names map to the same underlying state property. So, in the above code, the alert statement will display the text HELLO in the alert dialog.

Of course, aliases can be specified also when using the complete profile, as in...

MyClass.stateProperties ({
  _title:{
    name:'title|displayTitle',
    conformer:function (_value) {
      // coerce to a string, default to empty string for null or undefined
      return _value == undefined ? '' : _value + '';
    },
    value:'untitled'
  }
});

BENEFITS

One of the benefits of public aliases for state properties is that it eases the evolution of interfaces over time. One can officially change the name of a state property, while deprecating the old name and continuing to support it for some time for backwards compatibility.

When using the the complete profile form to declare a state property, an initial value for a property can be specified using the value property of the profile.

EXAMPLE

var MyClass = Uize.Class.subclass ();
MyClass.stateProperties ({
  _propertyName:'propertyName',
  _active:{
    name:'active',
    onChange:function () {
      // do something
    }
  },
  _percentLoaded:{
    name:'percentLoaded',
    conformer:function (_value) {return Uize.constrain (_value,0,100)},
    value:0
  }
});
var myInstance = new MyClass;
alert (myInstance.get ('propertyName'));   // will alert the value undefined
alert (myInstance.get ('active'));         // will alert the value undefined
alert (myInstance.get ('percentLoaded'));  // will alert the value 0

If a state property is declared using the minimal profile, or if it is declared using the the complete profile but no value property is specified in the profile, then the state property will be set to undefined for all freshly minted instances.

When using the the complete profile form to declare a state property, an onChange handler function can be declared to respond to changes in the property's value.

EXAMPLE

MyClass.stateProperties ({
  _percentLoaded:{
    name:'percentLoaded',
    conformer:function (_value) {return Uize.constrain (_value,0,100)},
    onChange:function () {
      if (this.isWired) this.setNodeValue ('percentLoaded',this._percentLoaded);
    },
    value:0
  }
});

In the above example, the _percentLoaded state property is being declared. An onChange handler function is registered that is executed each time the property's value changes, and this function's implementation displays the current value in a node in the document (we're assuming this code is transplanted from a widget class' implementation).

5.8.1. Executed Even on First Change

var MyClass = Uize.Class.subclass ();
function _updateArea () {
  this.set ({area:this._width * this._height});
}
MyClass.stateProperties ({
  _area:'area',
  _height:{
    name:'height',
    value:10,
    onChange:_updateArea
  },
  _width:{
    name:'width',
    value:10,
    onChange:_updateArea
  }
});
var myInstance = new MyClass;
alert (myInstance.get ('area'));  // will alert the value 100

MyClass.stateProperties ({
  _percentLoaded:{
    name:'percentLoaded',
    conformer:function (_value) {return Uize.constrain (_value,0,100)},
    onChange:function () {
      if (this.isWired) this.setNodeValue ('percentLoaded',this._percentLoaded);
    },
    value:0
  }
});

5.8.2. Only Executed on Changes

var MyClass = Uize.Class.subclass ();
MyClass.stateProperties ({
  _percentLoaded:{
    name:'percentLoaded',
    onChange:function () {alert (this._percentLoaded)},
    value:0
  }
});
var myInstance = new MyClass;         // will alert the text 0
myInstance.set ({percentLoaded:10});  // will alert the text 10
myInstance.set ({percentLoaded:10});  // does nothing (because value doesn't change)
myInstance.set ({percentLoaded:10});  // does nothing (because value doesn't change)
myInstance.set ({percentLoaded:10});  // does nothing (because value doesn't change)

var MyClass = Uize.Class.subclass ();
MyClass.stateProperties ({
  _percentLoaded:{
    name:'percentLoaded',
    conformer:function (_value) {return Uize.constrain (_value,0,100)},
    onChange:function () {alert (this._percentLoaded)},
    value:0
  }
});
var myInstance = new MyClass;          // will alert the text 0
myInstance.set ({percentLoaded:100});  // will alert the text 100
myInstance.set ({percentLoaded:200});  // does nothing (because value stays 100)
myInstance.set ({percentLoaded:300});  // does nothing (because value stays 100)
myInstance.set ({percentLoaded:400});  // does nothing (because value stays 100)

5.8.3. Called as Instance Method

var MyClass = Uize.Class.subclass ();
function _updateArea () {
  this.set ({area:this._width * this._height});
}
MyClass.stateProperties ({
  _area:'area',
  _height:{
    name:'height',
    value:10,
    onChange:_updateArea
  },
  _width:{
    name:'width',
    value:10,
    onChange:_updateArea
  }
});

When using the the complete profile form to declare a state property, a conformer function can be registered to ensure that the value for the property is always conformed to be a valid value.

Normally, whatever value is specified for a state property when calling the set method is the new value that gets set for that property. However, specifying the optional conformer allows us to register a function that should be executed before the state property's value actually changes, providing an opportunity to constrain or correct the value, or to abort the set so that the property's value remains unchanged.

EXAMPLE

var MyClass = Uize.Class.subclass ();
MyClass.stateProperties ({
  _percentLoaded:{
    name:'percentLoaded',
    conformer:function (_value) {return Uize.constrain (_value,0,100)},
    value:0
  }
});
var myInstance = new MyClass ({percentLoaded:200});
alert (myInstance.get ('percentLoaded'));

In the above code, the alert statement will display the text 100 in the alert dialog.

In the example, a conformer function is registered for the percentLoaded state property, that conforms the property's value so that it doesn't fall outside of the range of 0 to 100. So, even though the code is trying to set the property's value to 200 during construction of an instance, the conformer conforms the value to not fall out of bounds.

IN A NUTSHELL

When you register a conformer function for a state property, that function gets executed each time there is an attempt to set a value for that property. Your conformer function should expect to receive one parameter, being the new value that is being attempted to be set. Your conformer function should do what it needs to in order to conform the new value, and then return the conformed value as its result. The conformer function is called as a method on the instance to which the state property belongs, so it can access other state and methods for the instance using the this keyword, including the current value for the property being set.

5.9.1. The Conformer and onChange Handlers

var MyClass = Uize.Class.subclass ();
MyClass.stateProperties ({
  _percentLoaded:{
    name:'percentLoaded',
    conformer:function (_value) {return Uize.constrain (_value,0,100)},
    onChange:function () {alert (this._percentLoaded)},
    value:0
  }
});
var myInstance = new MyClass;          // will alert the text 0
myInstance.set ({percentLoaded:200});  // will alert the text 100
myInstance.set ({percentLoaded:200});  // does nothing (because value doesn't change)
myInstance.set ({percentLoaded:200});  // does nothing (because value doesn't change)

5.9.2. Abort a Set

var _emailRegExp =
  /^(([A-Za-z0-9])|(\w[-\w\.\+]*[\w\+]))@([-A-Za-z0-9]+\.)+[A-Za-z]{2,4}$/
;
MyClass.stateProperties ({
  _emailAddress:{
    name:'emailAddress',
    conformer:function (_value) {
      return (
        typeof _value == 'string' && (_value == '' || _emailRegExp.test (_value))
          ? _value
          : this._emailAddress
      );
    },
    value:''
  }
});

5.9.3. More Uses of Conformers

MyClass.stateProperties ({
  _percentLoaded:{
    name:'percentLoaded',
    conformer:function (_value) {return Uize.constrain (_value,0,100)},
    value:0
  }
});

MyClass.stateProperties ({
  _minWidth:{
    name:'minWidth',
    value:0
  },
  _maxWidth:{
    name:'maxWidth',
    value:Infinity
  },
  _width:{
    name:'width',
    conformer:function (_value) {
      return Uize.constrain (_value,this._minWidth,this._maxWidth);
    },
    value:0
  }
});

var _validTimeUnits =
  {ms:1,seconds:1,minutes:1,hours:1,days:1,weeks:1,months:1,years:1}
;
MyClass.stateProperties ({
  _timeUnit:{
    name:'timeUnit',
    conformer:function (_value) {
      return _validTimeUnits [_value] ? _value : this._timeUnit;
    },
    value:'hours'
  }
});

MyClass.stateProperties ({
  _fruit:{
    name:'fruit',
    conformer:function (_value) {
      return Uize.isIn (this._availableFruits,_value) ? _value : this._fruit;
    }
  },
  _availableFruits:{
    name:'availableFruits',
    value:[]
  }
});

MyClass.stateProperties ({
  _fruit:{
    name:'fruit',
    conformer:function (_value) {
      return this._availableFruits [Uize.indexIn (this._availableFruits,_value,0)];
    }
  },
  _availableFruits:{
    name:'availableFruits',
    value:[]
  }
});

MyClass.stateProperties ({
  _title:{
    name:'title',
    conformer:function (_value) {return _value + ''}
    value:''
  }
});

MyClass.stateProperties ({
  _width:{
    name:'width',
    conformer:function (_value) {return +_value}
    value:0
  }
});

MyClass.stateProperties ({
  _active:{
    name:'active',
    conformer:function (_value) {return !!_value}
    value:false
  }
});

var _trueValues = {1:1,true:1,yes:1,on:1,enabled:1,active:1};
MyClass.stateProperties ({
  _showTitle:{
    name:'showTitle',
    conformer:function (_value) {return !!_trueValues [_value + '']}
    value:false
  }
});

MyClass.stateProperties ({
  _title:{
    name:'title',
    conformer:function (_value) {
      _value += '';   // coerce to a string value, invoking valueOf
      return _value.length > 50 ? _value.slice (0,50) : _value;
    },
    value:''
  }
});

MyClass.stateProperties ({
  _filename:{
    name:'filename',
    conformer:function (_value) {return (_value + '').toLowerCase ()},
    value:''
  }
});

MyClass.stateProperties ({
  _title:{
    name:'title',
    conformer:function (_value) {
      return this._titleLocked ? this._title : _value + '';
    },
    value:''
  },
  _titleLocked:{
    name:'titleLocked',
    value:false
  }
});

The Changed.[propertyName] virtual event lets you watch on changes in value for specified state properties.

EXAMPLE

var MyClass = Uize.Class.subclass ();
MyClass.stateProperties ({
  _percentLoaded:{
    name:'percentLoaded',
    conformer:function (_value) {return Uize.constrain (_value,0,100)},
    value:0
  }
});
var myInstance = new MyClass;
myInstance.wire (
  'Changed.percentLoaded',  // name of changed event for percentLoaded stete property
  function (event) {alert (event.newValue)}
);
myInstance.set ({percentLoaded:10});   // will alert the text 10
myInstance.set ({percentLoaded:25});   // will alert the text 25
myInstance.set ({percentLoaded:66});   // will alert the text 66
myInstance.set ({percentLoaded:200});  // will alert the text 100 (because of conformer)
myInstance.set ({percentLoaded:300});  // does nothing (because value doesn't change)

In the above example, a handler is being registered for the changed event of the percentLoaded state property, which is named Changed.percentLoaded (basically, any state property has a changed virtual event that is named after that property, with "Changed." prefixed).

Now, the handler for this event alerts the current value for the property. So, the first four of the set statements in the example will result in the value of percentLoaded changing, which will fire the Changed.percentLoaded virtual event, whose handler will display the current value in an alert dialog. Important to note is that the last set statement will not cause the value of percentLoaded to change. That's because the conformer function constrains its value to the range of 0 to 100, and the previous attempt to set its value to 200 caused it to be constrained to the maximum in its range. Once constrained to 100, attempting to set its value to 300 wouldn't budge it any higher from 100. So, the last set statement doesn't cause the Changed.percentLoaded event to be fired, and no alert dialog.

6.1.1. Event Object Contains newValue Property

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

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

The Changed.* instance event is a wildcard event that is fired whenever one or more state properties change value as a result of a call to the set instance method.

This event will only be fired once for all state properties that have changed value during a call to the set method. The event object for this event will contain a properties property, which is an object indicating which state properties have changed value, being a mapping between the public names of state properties that have changed and their new values.

EXAMPLE

var
  marquee1 = page.addChild ('marquee1',Uize.Widget.Resizer.Marquee),
  marquee2 = page.addChild ('marquee2',Uize.Widget.Resizer.Marquee)
;
marquee1.wire (
  'Changed.*',
  function (eventObj) {
    var properties = eventObj.properties;
    if (
      'left' in properties || 'top' in properties ||
      'width' in properties || 'height' in properties
    )
      marquee2.set (marquee1.getCoords ())
    ;
  }
);

In the above example, two instances of the Uize.Widget.Resizer.Marquee widget class are being added as child widgets to the page widget (which we assume to already be defined). A handler is wired to the Changed.* wildcard event of the first instance, marquee1. The handler tests to see if any of the state properties left, top, width, or height have changed by checking if any of these keys are present in properties property of the event object for the Changed.* event. If any of these properties have changed value, the getCoords instance method is used to get the values for those properties, and those values are set on the second instance, instance2. This code would have the effect of making instance1 be the "driver" of instance2.

If a value state property is declared for a class, then application code can watch on changes in the value for an instance by wiring a handler for the Change.value virtual event of the instance.

EXAMPLE

var MyClass = Uize.Class.subclass ();
MyClass.stateProperties ({
  _value:{
    name:'value',
    value:0
  }
});
var myInstance = new MyClass;
myInstance.wire ('Changed.value',function () {alert (+myInstance)});
myInstance.set ({value:10});  // will alert the text 10

In the above code, a handler is wired for the Changed.value event of the instance myInstance. Setting the value state property to 10 causes its value to change from its initial value of 0 (as specified in the value property of its profile), thereby firing the Changed.value virtual event, and the handler for this event alerts the current value by prepending the plus ("+") operator to the instance reference, invoking the valueOf Intrinsic Method.

The valueOf Intrinsic Method is implemented in the Uize.Class base class, so it is inherited by all subclasses of Uize.Class, including Uize.Widget and all subclasses of Uize.Widget, and all their subclasses, etc.

To take advantage of this facility, all you need to do is declare a state property with the public name value.

By using the public aliases mechanism, it is possible to name a state property something other than value while still leveraging the valueOf Intrinsic Method provision. Simply declare two public names for the property: your desired name, and the special name value as an alias.

EXAMPLE

var MyClass = Uize.Class.subclass ();
MyClass.stateProperties ({
  _percentLoaded:{
    name:'percentLoaded|value',
    conformer:function (_value) {return Uize.constrain (_value,0,100)},
    value:0
  }
});
var myInstance = new MyClass ({percentLoaded:10});
alert (myInstance.get ('percentLoaded'));  // will alert the text 10
alert (myInstance.get ('value'));          // will alert the text 10
alert (+myInstance);                       // will alert the text 10

In the above example, the percentLoaded state property is being declared. Even though this property might represent the primary value for instances of the class, it is desirable for the property's name to be percentLoaded (rather than the more generic value) for general usability/understandability of the class' interface. However, it would be nice to still be able to get the benefit of the valueOf Intrinsic Method. Not a problem. This is accomplished by naming the state property both percentLoaded AND value. Notice how the three last statements in the example all produce the same output.

Cases can arise where it is desirable to declare a state property whose value is derived from the values of one or more other state properties, and that acts as a kind of state summary for the instance.

EXAMPLE

var MyClass = Uize.Class.subclass ();
function _updateArea () {
  this.set ({area:this._width * this._height});
}
MyClass.stateProperties ({
  _area:'area',
  _height:{
    name:'height',
    value:10,
    onChange:_updateArea
  },
  _width:{
    name:'width',
    value:10,
    onChange:_updateArea
  }
});
var myInstance = new MyClass;
alert (myInstance.get ('area'));         // will alert the value 100

myInstance.set ({width:5});
alert (myInstance.get ('area'));         // will alert the value 50

myInstance.set ({height:5});
alert (myInstance.get ('area'));         // will alert the value 25

myInstance.set ({width:20,height:20});
alert (myInstance.get ('area'));         // will alert the value 400

In the above example, the area state property is being declared. This property is not intended to be set by an application, since its value is derived in the class' implementation from the values of two other state properties declared for the class: width and height. An onChange handler function is registered in the profile for each of the width and height state properties. If the value of either (or both) of these properties changes, then the _updateArea function is called as a method on the instance, and this function sets a new value for the area state property that is the product of the width and height values.

There is no formal mechanism within the UIZE JavaScript Framework for declaring a state property as being read-only.

There might be occasions when it's desirable to expose some instance state through a state property - with all the benefits that come from using state properties - without it being intended for application code to ever set the property's value. But the Uize.Class base class cannot distinguish between a state property's value being set from within the class' implementation, or from some application code using an instance of the class.

In the event that a state property is intended only to reflect state that is maintained within a class' implementation, the property should just be documented as intended for read-only use in the documentation for the class. Incorrect setting of the property could cause code to fail, but in the rather open JavaScript language any number of other, more damaging things could be done by application code to trip up a class' implementation.

In short, read-only state properties are more of a convention / design pattern than anything else. The many classes of the UIZE JavaScript Framework are certainly replete with examples of weakly "enforced" read-only properties.