The Uize.Util.Coupler class makes it easy to keep desired state synchronized between two or more instances.

Coupled instances can be widget instances (ie. instances of Uize.Widget subclasses), but they do not have to be widgets. Coupled instances do not have to be of the same class - they only need to provide the same set-get properties that are to be synchronized between them.

Using the Uize.Util.Coupler class is easy: all you have to do is create an instance of it, specifying which properties of which instances you would like to be coupled together. Consider the following example...

EXAMPLE

// create subclass of Uize.Widget.CollectionItem.Zooming, for common property values

  var CollectionItemZoomingSubclass = Uize.Widget.CollectionItem.Zooming.subclass ();
  CollectionItemZoomingSubclass.set ({
    previewZoomUrl:function () {
      return this.get ('previewUrl').replace ('100x75','400x300');
    },
    zoomPower:4
  });


// create some zooming collection item widgets

  var
    item0 = page.addChild ('item0',CollectionItemZoomingSubclass),
    item1 = page.addChild ('item1',CollectionItemZoomingSubclass),
    item2 = page.addChild ('item2',CollectionItemZoomingSubclass)
  ;


// couple the alignX, alignY, inUse properties between the collection items

  var coupler = new Uize.Util.Coupler ({
    instances:[item0,item1,item2],
    properties:['alignX','alignY','inUse']
  });

In the above example, a custom subclass of the Uize.Widget.CollectionItem.Zooming widget class is being created. This is done purely as a convenience, in order to capture some common set-get property values, and so that all instances of this subclass that are created will have those same initial values. Then, three instances of this custom subclass are added as child widgets to the page widget (which we assume in this example to already be defined).

Finally, an instance of the Uize.Util.Coupler class is created in order to couple the three instances together by keeping the values of their alignX, alignY, and inUse set-get properties synchronized across the three of them. This has the effect of making the instance that the user is currently interacting with drive the other two instances - any instance can drive the other two. When the user rests the mouse over one of the instances, the zoom in effect will be activated for all three. And when the user moves the mouse over one in order to pan horizontally and vertically around the zoomed image, the two other instances will follow the lead of the one the user is mousing over.

To see an example of how the Uize.Util.Coupler class is used, consult the Coupled Zooming Collection Items example.

A boolean, indicating whether or not the coupling is active and the instances specified by the instances set-get property are coupled together.

If this property is set to false after instances have already been coupled, then they will be uncoupled. They can be recoupled again later by setting the value of this property back to true.

NOTES

An array, specifying the instances that should be coupled together and whose properties, as specified by the properties set-get property, should be kept synchronized.

If the value of this property is changed after instances have already been coupled, then the previously coupled instances will be uncoupled and the newly specified instances will be coupled.

NOTES

An array, specifying the properties that should be kept synchronized across all instances, as specified in the instances set-get property.

If the value of this property is changed after instances have already been coupled, then the previously coupled instances will be uncoupled and the current instances will be recoupled using the newly specified properties.

NOTES