Widget Events

A widget event is the widget-level event (Event).

Like Event at the server side, the widget event can be anything, and can be triggered by a widget or an application to notify a widget-level or application-level event, such as that a window has been moved.

In addition, ZK Client Engine intercepts most DOM events and encapsulate them into widgets events, such that it is easier and more efficient for component developers to handle events at widget-level (rather than DOM-level, Event).

Event Listening for Component Developers

ZK Client Engine intercepts most DOM events that are targeting the DOM elements belong to widgets. It then encapsulates them into widget events, and then invokes the corresponding method of Widget. For example, when the user moves the mouse over a DOM element of a widget, Widget.doMouseOver_(Event) will be called. Similarly, when the user clicks a DOM element of a widget, Widget.doClick_(Event) will be used.

Listen by Overriding a Method

Thus, the simplest way to listen a DOM event is to override the corresponding method. For example

doMouseDown_: function (evt) {
    //do whatever you want
    this.$supers('doMouseDown_', arguments); //invoke parent.fireX() and so on
}

where evt is an instance of Event. The original DOM event can be retrieved by use of Event.domEvent, and the original DOM element can be found by use of Event.domTarget (or evt.domEvent.target).

If you want to listen and disable the default behavior, just not to call the super class:

doClick_: function (evt) {
    this.fireX(evt);
    //don't call this.$supers to avoid the event propagation
},

Note that this approach is suggested for better performance since no real DOM-level event registration is required (as described in the next section).

Event Propgation

The default implementation of the event methods (doXxxx_ in Widget) propagates the event from the target widget to its parent, grandparent and so on. To stop the propagation, you can either invoke Event.stop(Map), or not calling back the superclass's event method (the effect is the same). In other words, if the propagation is stopped, the parent's event method won't be called.

If a widget event is not stopped and required by the server, it will be sent to the server, and converted to an instance of AuRequest at the server.

In additions to the event propagation, the default implementation will invoke Widget.fireX(Event, int) to inoke the application-level listeners, if any (registered with Widget.listen(Map, int).

Notice that there are two kinds of propagation: widget-level and DOM-level. If you stop only the widget-level propagation (by calling evt.stop({propagation:true})), the DOM event will go through all DOM-level event listeners and then trigger the browser default behavior.

---

Capture the Mouse Event

Sometime you want the following Widget.doMouseOver_(Event) and Widget.doMouseUp_(Event) are called against the same widget, no matter where the mouse-up event happens. It is also known as capturing. It can be done by setting zk.mouseCapture as follows.

doMouseDown_: function () {
    zk.mouseCapture = this;
    this.$supers('doMouseDown_', arguments);
}

Notice that the mouse capture is reset automatically after Widget.doMouseUp_(Event) is called.

Capture the Input Event

Sometime you want the following Widget.onKeyPress_(Event) and Widget.onKeyUp_(Event) are called against the same widget, no matter where the key-up event happens. It is also known as capturing. It can be done by setting zk.keyCapture as follows.

doKeyDown_: function () {
    zk.keyCapture = this;
    this.$supers('doKeyDown_', arguments);
}

Notice that the key capture is reset automatically after Widget.onKeyUp_(Event) is called.

Events and Corresponding Methods

Events that can be handled by overriding a method

DOM Event Name	Method to Override
blur	Widget.doBlur_(Event) Note: unlike others, you have to register a listener with Widget.domListen_(DOMElement, String, Object) as follows. Otherwise, doBlur_ won't be called. this.domListen_(n, "onBlur");
click	Widget.doClick_(Event)
dblclick	Widget.doDoubleClick_(Event)
contextmenu (aka., the right click)	Widget.doRightClick_(Event)
focus	Widget.doFocus_(Event) Note: unlike others, you have to register a listener with Widget.domListen_(DOMElement, String, Object) as follows. Otherwise, doFocus_ won't be called. this.domListen_(n, "onFocus");
mouseover	Widget.doMouseOver_(Event)
mouseout	Widget.doMouseOut_(Event)
mousedown	Widget.doMouseDown_(Event)
mouseup	Widget.doMouseUp_(Event)
mousemove	Widget.doMouseMove_(Event)
keydown	Widget.doKeyDown_(Event)
keyup	Widget.doKeyUp_(Event)
keypress	Widget.doKeyPress_(Event)

Event Listening for Application Developers

To listen a widget event, you could invoke Widget.listen(Map, int) to listen the widget event you want. However, Widget.listen(Map, int) is designed for applications to listen events at the client. Thus, it is also called the application-level event listener.

For component development, the method overriding is suggested as described in the previous subsections.

The signature of an event listener is as follows.

function (event) { //an instance of zk.Event
}

Event Firing

To fire a widget event, you could invoke Widget.fire(String, Object, Map, int) or Widget.fireX(Event, int).

Then, the listeners registered with Widget.listen(Map, int) will be invoked one-by-one. Then, it will be sent to the server, if an event listener has been registered at the server or it is an import event.

A client-side event listener could stop the sending of a widget event to the server by invoking Event.stop(Map) with {au:true}, such as

evt.stop({au: true});

---

Version History

Version	Date	Content