ZK Client-side Reference/Notifications/Client Activity Watches

In addtion to widget events (Event) and DOM events (Event), there are some special notifications called client activity watches. They are used to notify special activities, such as when a widget becomes invisible, or a window is brought to the top. This kind of activity can be listened by so-called watch (zWatch)

Listen and Unlisten

To add a watch (i.e., listen to a client activity), you could use zWatch.listen(Map) as follows:

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

As shown, the key of each entry in the given map is the name of the client activity (aka., the watch name), and the value could be one of the following:

• An object that has a method with the same name. In the above case, this must have the onSize and onSHow methods
• A two-element array, where the first element is the target, and the second is the method

The signature of the method is as follows.

function onWhatever(ctl, arg0, arg1...) {
  //ctl.origin: the object passed as the first argument to zWatch.fire or zWatch.fireDown
  //ctl.fireDown(something) and ctl.fire(something):
  //   
}

where ctl is a controller allowing you to have better control of the invocation sequence of the listeners, and arg0 and others are the arguments that passed to zWatch.fire(String, Object, Map) or zWatch.fireDown(String, Object, Map).

The controller has two methods: fire and fireDown, and one field: origin. The fire and fireDown methods are used to fore the remaining listeners (caused by the same invocation of of zWatch.fire(String, Object, Map) or zWatch.fireDown(String, Object, Map)) to be invoked. If your listener doesn't call any of them, the other listeners are called in the same order of registration.

Here is the pseudo code for the controller:

interface Controller {
  /** Usually zk.Widget (unless fire and fireDown was called with a different object) */
  Object origin;
  /** enforce the remaining listeners to be invoked immediately (change the invocation sequence) */
  void fire(Object ref, Object...);
  /** enforce the remaining listeners to be invoked immediately (change the invocation sequence) */
  void fireDown(Object ref, Object...);
}

where ref is optional. If specified, it will invoke only the listeners for the given object (and its descendants if fireDown) that are not invoked yet. If null, it will invokes all the listeners that are not invoked yet.

The origin field (ctl.origin) is the original object (usually a widget, Widget) passed as the first argument when zWatch.fire(String, Object, Map) or zWatch.fireDown(String, Object, Map) was called. In other words, it is the one causes the client activity. It is null if not available.

To unlisten, you could use zWatch.unlisten(Map) as follows:

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

Fire

The client activity is triggered (aka., fired) by either zWatch.fire(String, Object, Map) or zWatch.fireDown(String, Object, Map).

zWatch.fire(String, Object, Map) will invoke the listeners for the target object (the first argument), while zWatch.fireDown(String, Object, Map) will invokes the listeners for the target object and all of its descendants (i.e., the target object's children, grandchildren...).

For example, if a widget resizes itself, it could fire down onSize as follows.

zWatch.fireDown("onSize", wgt);

The target object could be anything as long as the listener recognizes it, but ZK's standard widgets use Widget only.

Client Activities

Here is the list of client activities that you could watch.

beforeSize

[fireDown]

It is called right before the browser window or the parent widget is resized.

beforeSize, onFitSize and onSize are fired when the browser window or a widget is resized. beforeSize is fired first, such that the listeners could reset style's width or height. Then, the listeners of onFitSize are called in the reverse order (child first) to caculate the minimal allowed size. Finally, the the listener of onSize can change it to the correct size.

Notice zWatch.fireDown(String, Object, Map) must be used to fire this event, so only the listeners of descendants of the specified widget will be called.

• Parameters
  • ctl.origin - the widget that causes the resizing. If null, it means the whole browser is resized.

onBindLevelChange

[fire]

It is called if the bind level of a widget (Widget's bindLevel) is changed due to moving from one parent to another.

Notice it won't be called if it is unbound and bound (i.e., detached and attached).

Notice zWatch.fire(String, Object, Map) is used, so all listeners are invoked.

onFitSize

[fireDown; reverse order]
[since 5.0.8]

It is called between beforeSize and onSize.

beforeSize, onFitSize and onSize are fired when the browser window or a widget is resized. beforeSize is fired first, such that the listeners could reset style's width or height. Then, the listeners of onFitSize are called in the reverse order (child first) to caculate the minimal allowed size. Finally, the the listener of onSize can change it to the correct size.

Notice that the listeners of onFitSize are called in the reverse order, i.e., the child is called before the parent. However, superclass's listener of the same widget will still be called first (like onSize and other events).

• Parameters
  • ctl.origin - the widget that causes the resizing. If null, it means the whole browser is resized.

onHide

[fireDown]

It is called before a widget is going to become invisible.

Notice zWatch.fireDown(String, Object, Map) must be used to fire this event, so only the listeners of descendants of wgt will be called.

• Parameters
  • ctl.origin - the widget is becoming invisible

• See Also
  • #onShow

onFloatUp

[fire]

It is called after a widget has gained the focus. It means the 'float' widget that is the parent of the focus widget shall become topmost.

Notice zWatch.fire(String, Object, Map) is used, so all listeners are invoked.

• Parameters
  • ctl.origin - the widget gains the focus.

onResponse

[fire]

It is called after the response of the AU request has been sent back from the server, and processed.

Notice the zWatch.fire(String, Object, Map) is used, so all listeners are invoked.

onRestore

[fireDown]

It is called when Skipper restores the DOM elements.

It is rarely required but to fix the browser's bug if any. Furthermore, if you listen to onRestore, it is likely you have to listen onVParent too.

• Parameters
  • ctl.origin - the widget has become visible

• See Also
  • #onVParent

onScroll

[fire]

It is called when the browser window or the specified widget is scrolling.

Notice the zWatch.fire(String, Object, Map) is used, so all listeners are invoked.

• Parameters
  • ctl.origin - the widget that is scrolling (i.e., causing the onScroll watch), or null if the whole browser window is scrolling

onSend

[fire]

It is called before sending the AU request to the server. The implicit argument indicates whether all AU requests being sent are implicit.

Notice zWatch.fire(String, Object, Map) is used, so all listeners are invoked.

onSize

[fireDown]

It is called when the browser window and a widget is resized.

beforeSize, onFitSize and onSize are fired when the browser window or a widget is resized. beforeSize is fired first, such that the listeners could reset style's width or height. Then, the listeners of onFitSize are called in the reverse order (child first) to caculate the minimal allowed size. Finally, the the listener of onSize can change it to the correct size.

Notice that a layout widget (such as Borderlayout and Hbox) must fire both beforeSize and onSize when it resizes.

Notice zWatch.fireDown(String, Object, Map) must be used to fire this event, so only the listeners of descendants of wgt will be called.

• Parameters
  • ctl.origin - the widget that causes the resizing. If null, it means the whole browser is resized.

onShow

[fireDown]

It is called after a widget has become visible.

Notice zWatch.fireDown(String, Object, Map) must be used to fire this event, so only the listeners of descendants of wgt will be called.

• Parameters
  • ctl.origin - the widget has become visible

• See Also
  • #onHide

onVParent

[fireDown]
[since 5.0.8]

It is called when jqzk.makeVParent() or jqzk.undoVParent() is called to move a DOM element to/from document.body.

It is rarely required but to fix the browser's bug if any. Furthermore, if you listen to onVParent, it is likely you have to listen onRestore too.

• Parameters
  • ctl.origin - the widget has become visible

• See Also
  • #onRestore

Version History

Version	Date	Content
5.0.8	August 2011	onFitSize and onVParent was introduced.