_global_
Class zWatch

java.lang.Object
  extended by _global_.zWatch

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.

Add a Watch

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.

Invocation Sequence

Sequence of 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.


Method Summary
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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

listen

public static void listen(Map infs)
Registers watch listener(s). For example,

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.

Parameters:
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.

unlisten

public static void unlisten(Map infs)
Removes watch listener(s).

Parameters:
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.

unlistenAll

public static void unlistenAll(String name)
Removes all listener of the specified watch.

Parameters:
name - the watch name, such as onShow

fire

public 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.

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
   ....
}

Parameters:
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:
  • reverse - whether to reverse the execution order. If false or omitted, the parent is called first. If true, the child is called first. Notice that there is a limitation: if reverse, you can invoke ctl.fire in the callback.
  • timeout - how many miliseconds to wait before calling the listeners. If Omitted or negative, the listeners are invoked immediately.
  • vararg - any number of arguments to pass to the listener. They will become the second, third and following arguments when the listener is called.

fireDown

public 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.

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.


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).

Parameters:
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:
  • reverse - whether to reverse the execution order. If false or omitted, the parent is called first. If true, the child is called first. Notice that there is a limitation: if reverse, you can invoke ctl.fireDown in the callback.
  • timeout - how many miliseconds to wait before calling the listeners. If Omitted or negative, the listeners are invoked immediately.
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-2011 Potix Corporation. All Rights Reserved. SourceForge.net Logo