Class zWatch

Fires an watch that invokes all listeners of the watch.

For example, zWatch.fire('onX', null, 'a', 123) will cause ml.onX(ctl, 'a', 123) being called -- assuming ml is a listener of onX.

Notice that the first argument (ctl in the above example) is a special controller. The first two argument of fire become part of the control (as the name and origin fields). In additions, the control can be used to control the invocation sequence. For example, the invocation sequence is, by default, evaluated in the order of fist-listen-first-call, and you can use the controller to force the listeners of a certain target to be called first as follows.

onX: function (ctl) {
  ctl.fire(specialTarget); //enforce the listeners of specialTarget to execute first
  ...
}
Copy

If you want the listeners of descendants to execute too, use fireDown instead as follows:

onX: function (ctl) {
ctl.fireDown(specialTarget); //enforce the listeners of specialTarget and descendants to execute first
....
}
Copy

Fires an watch but invokes only the listeners that are a descendant of the specified origin.

By descendant we mean the watch listener is the same or an descendant of the specified origin. In other words, if the specified origin is not the ancestor of a watch listener, the listener won't be called.

Notice that it assumes:

1. The watch listener's parent can be retrieved by either a method called getParent, or a property called parent.
2. It has a data member called bindLevel indicating which level the object in the parent-child tree.

Widget is a typical example (Widget#parent and Widget#bindLevel).

For example, zWatch.fireDown('onX', wgt, opts, 'a', 123) will cause ml.onX(ctl, opts, 'a', 123) being called -- assuming ml is a listener of onX and zUtl.isAncestor(wgt, ml) is true (zUtl#isAncestor).

Notice that the first argument (ctl in the above example) is a special controller that a listen can use to do further control. For example, origin (of fire()) can be retrieved by accessing the member of the controller called origin. ```ts onSize: function (ctl) { if (ctl.origin) //retrieve the origin ... } ```

Notice that the second argument (opts in the above example) is also a special argument used to pass optional control info to the zWatch engine.

The invocation sequence is, by default, evaluated in the order of parent-first, and you can use the controller to change it. For example, the following will cause the listener of specialTarget, if any, to execute first. ```ts onX: function (ctl) { ctl.fire(specialTarget); //enfore the listeners of specialTarget to execute first ... } ```

If you want the listeners of descendants to execute too, use fireDown instead as follows: ```ts onX: function (ctl) { ctl.fireDown(specialTarget); //enfore the listeners of specialTarget and descendants to execute first ... } ```

It is useful if a listener depends some of its children's listeners to complete (notice that the parent's listener is, by default, called first). For example, when onSize of a widget is called, it might want some of its children's onSiz to be called first (so he can have their updated size).

zWatch.listen({
  onSize: this,
  onShow: this,
  onHide: [this, this._onHide]
});
Copy

Registers watch listener(s). For example,

zWatch.listen({
  onSize: this,
  onShow: this,
  onHide: [this, this._onHide]
});
Copy

As shown above, each key of the infs map is the watch name, and each value is the target against which the watch listener will be called, or a two-element array, where the first element is the target and the second the listener function. For example, `zWatch({onSize: foo})` will cause foo.onSize to be called when onSize is fired. The arguments passed are the same as fire/fireDown.

Note: the order is parent-first (if the watch has a method called getParent or a member called parent), so the invocation (fire) is from the parent to the child if both are registered.

Removes watch listener(s).

Removes all listener of the specified watch.