UIZE JavaScript Framework

MODULES Uize.Util.Coupler

SEARCHEXAMPLESSOURCETO DODEPSTEST

1. Introduction

The Uize.Util.Coupler class implements a mechanism for coupling two or more instances of any Uize.Class subclass by synchronizing values of state properties.

DEVELOPERS: Chris van Rensburg

1.1. In a Nutshell

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

Coupled instances can be widget instances (i.e. 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 state properties that are to be synchronized between them.

1.2. An Example

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 = 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 state 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 state 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.

1.3. Examples

The following example pages are good showcases for the Uize.Util.Coupler module...

Coupled Zooming Collection Items - See how two instances of the zooming collection item widget can be coupled together to give you a side-by-side zoomed in comparison of two images.
Transferring State - UIZE makes it easy to transfer state from one widget to another. See how to copy state from one marquee to another - or even how to keep them coupled.

SEARCH FOR EXAMPLES

Use the link below to search for example pages on the UIZE Web site that reference the Uize.Util.Coupler module...

SEARCH

1.4. Implementation Info

The Uize.Util.Coupler module defines the Uize.Util.Coupler class, which is a subclass of Uize.Class.

INHERITANCE CHAIN

Uize.Class −> Uize.Util.Coupler

1.4.1. Features Introduced in This Module

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

STATE PROPERTIES

coupled | instances | properties

1.4.2. Features Overridden in This Module

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

The module that an overridden feature was initially introduced in will be noted in the IMPLEMENTATION INFO notes for the feature.

INSTANCE METHODS

valueOf

STATIC PROPERTIES

Uize.Util.Coupler.moduleName | Uize.Util.Coupler.nonInheritableStatics

1.4.3. Features Inherited From Other Modules

The features listed in this section have been inherited from other modules.

The module that an inherited feature was initially introduced in will be noted in the IMPLEMENTATION INFO notes for the feature.

INSTANCE METHODS

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

STATIC METHODS

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

STATIC PROPERTIES

Uize.Util.Coupler.pathToResources

1.4.4. Modules Directly Under This Namespace

There are no modules directly under this namespace.

1.4.5. Unit Tests

There is no dedicated unit tests module for the Uize.Util.Coupler module.

2. State Properties

2.1. coupled

A boolean, indicating whether or not the coupling is active and the instances specified by the instances state 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

the initial value is true

IMPLEMENTATION INFO

this feature was introduced in this module

2.2. instances

An array, specifying the instances that should be coupled together and whose properties, as specified by the properties state 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

see the companion properties state property
the initial value is undefined

IMPLEMENTATION INFO

this feature was introduced in this module

2.3. properties

An array, specifying the properties that should be kept synchronized across all instances, as specified in the instances state 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

see the companion instances state property
the initial value is undefined

IMPLEMENTATION INFO

this feature was introduced in this module

3. Instance Methods

3.1. fire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.2. get

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.3. is

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.4. isMet

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.5. kill

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.6. met

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.7. onChange

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.8. once

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.9. set

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.10. toggle

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.11. unmet

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.12. unwire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.13. valueOf

this is an override of an inherited feature (implementation is in this module, first introduced in Uize.Class)

IMPLEMENTATION INFO

3.14. whenever

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.15. wire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4. Static Methods

4.1. Uize.Util.Coupler.alphastructor

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.2. Uize.Util.Coupler.declare

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.3. Uize.Util.Coupler.doMy

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.4. Uize.Util.Coupler.dualContextMethods

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.5. Uize.Util.Coupler.dualContextProperties

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.6. Uize.Util.Coupler.fire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.7. Uize.Util.Coupler.get

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.8. Uize.Util.Coupler.instanceMethods

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.9. Uize.Util.Coupler.instanceProperties

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.10. Uize.Util.Coupler.mixins

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.11. Uize.Util.Coupler.omegastructor

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.12. Uize.Util.Coupler.set

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.13. Uize.Util.Coupler.singleton

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.14. Uize.Util.Coupler.stateProperties

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.15. Uize.Util.Coupler.staticMethods

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.16. Uize.Util.Coupler.staticProperties

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.17. Uize.Util.Coupler.subclass

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.18. Uize.Util.Coupler.toggle

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.19. Uize.Util.Coupler.unwire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.20. Uize.Util.Coupler.wire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5. Static Properties

5.1. Uize.Util.Coupler.moduleName

IMPLEMENTATION INFO

this is an override of an inherited feature (implementation is in this module, first introduced in Uize.Class)
this static feature is inherited by subclasses

5.2. Uize.Util.Coupler.nonInheritableStatics

IMPLEMENTATION INFO

this is an override of an inherited feature (implementation is in this module, first introduced in Uize.Class)
this static feature is not inherited by subclasses

5.3. Uize.Util.Coupler.pathToResources

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses