ZK Client-side Reference/Notifications/Client Activity Watches

In most cases, a widget or an application needs only to listen Event as described in the Client-side Event listening section. However, there are some activities not available as a DOM event (Event) or a ZK event (Event), such as when a widget is becoming invisible, or a window is brought to top. This kind of activity can be listened by so-called watch (zWatch)

Notice that application developers rarely need to access it. It is more for component development.

---

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

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 (that have the signature of zWatch.fire(String, Object, Map) or zWatch.fireDown(String, Object, Map)), and one field: origin. The fire and fireDown methods are used to fore the other listeners (of the same client activity) to be invoked. If your listener doesn't call any of them, the other listeners are called in the same order of registration.

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]
});

Client Activities

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

beforeSize

Called right before the browser window or the parent widget is resized.

beforeSize and onSize are fired when the browser window or a widget is resized. beforeSize is fired first, such that the listener could reset style's width or height and the the listener of onSize can change it to the correct size. Notice that it is a must for the TD/TR tag. Otherwise, the onSize's listener cannot change its width/height correctly.

Notice zWatch's fireDown must be used to fire this event, so only the listeners of descendants of the specified widget will be called.

Version History

Version	Date	Content