public class zWatch
extends java.lang.Object
An utility to manage watches.
A watch is a system-level event, such as onSize and beforeSize. For example, when an AU request is going to be sent to the server, the onSend watch is fired so the client application and/or the widget implementation can listen to it.
Here is a full list of Client Activity Watches.
To add a listener to a watch, use listen(_global_.Map). The listener must implement a method with the same as the action name. For example,
MyListener = zk.$extends(zk.Object, {
onSend: function() {
}
});
var ml = new MyListener();
zWatch.listen({onSend: ml})
Then, ml.onSend will be called when sending an AU request.
fireDown(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)The watch listener is added in the parent-first sequence if it has a method called getParent, or a member called parent (a typical example is Widget). Thus, the parent will be called before its children, if they are all registered to the same action.
| Modifier and Type | Method and Description |
|---|---|
static void |
fire(String name,
java.lang.Object origin,
Map opts,
java.lang.Object... vararg)
Fires an watch that invokes all listeners of the watch.
|
static void |
fireDown(String name,
java.lang.Object origin,
Map opts,
java.lang.Object... vararg)
Fires an watch but invokes only the listeners that are a descendant of the specified origin.
|
static void |
listen(Map infs)
Registers watch listener(s).
|
static void |
unlisten(Map infs)
Removes watch listener(s).
|
static void |
unlistenAll(String name)
Removes all listener of the specified watch.
|
public static void listen(Map infs)
zWatch.listen({
onSize: this,
onShow: this,
onHide: [this, this._onHide]
});
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(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)/fireDown(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...).
Note: the order is parent-first (if the watch has a method called getParent or a member called parent), so the invocation (fire(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...)) is from the parent to the child if both are registered.
infs - a map of the watch listeners. Each key of the map is the the watch name, and each value is the target or a two-element array, where the first element is the target and the second the listener function. It assumes the target implements the method with the same name as the watch name. In addition, when the method is called, this references to the target.public static void unlisten(Map infs)
infs - a map of watch listeners. Each key is the watch name, and each value is the target or or a two-element array, where the first element is the target and the second the listener function.public static void unlistenAll(String name)
name - the watch name, such as onShowpublic static void fire(String name, java.lang.Object origin, Map opts, java.lang.Object... vararg)
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(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...) 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
....
}
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
....
}
name - the watch name, such as onFloatUp.origin - [optional] the origin (optional).
It could be anything and it will become the origin member of the special controller (the first argument of the listener)opts - [optional] options:
ctl.fire in the callback.vararg - any number of arguments to pass to the listener. They will become the second, third and following arguments when the listener is called.public static void fireDown(String name, java.lang.Object origin, Map opts, java.lang.Object... vararg)
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:
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.
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.
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:
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).
name - the watch name, such as onShow.origin - [optional] the reference object used to decide what listeners to invoke (required). Notice, unlike fire(_global_.String, java.lang.Object, _global_.Map, java.lang.Object...), it cannot be null. It will become the origin member of the controller (i.e., the first argument when the listener is called).opts - [optional] options:
ctl.fireDown in the callback.vararg - any number of arguments to pass to the listener. They will become the third, forth, and following arguments when the listener is called.Copyright © 2005-2023 Potix Corporation. All Rights Reserved.