Widget Events"

From Documentation
m
Line 8: Line 8:
  
 
In additions, 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, <javadoc directory="jsdoc">jq.Event</javadoc>).
 
In additions, 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, <javadoc directory="jsdoc">jq.Event</javadoc>).
 +
 +
=Event Listening for Component Developers=
 +
 +
ZK Client Engine intercepts most DOM events applied to the DOM elements of widgets. It then encapsulates them into widget events, and then invokes the corresponding method of <javadoc directory="jsdoc">zk.Widget</javadoc>. For example, when the user moves the mouse over a DOM element of a widget, <javadoc method="doMouseOver_(zk.Event)" directory="jsdoc">zk.Widget</javadoc> will be called.
 +
 +
==Event Propgation ==
 +
A widget event will be ''propagated'' to the parent widget, parent's parent and so on, until stopped (<javadoc method="stop(_global_.Map)" directory="jsdoc">zk.Event</javadoc>). Then, if the event is required by the server, it will be sent to the server, and converted to an instance of <javadoc type="interface">org.zkoss.zk.au.AuRequest</javadoc> at the server<ref>For more information, please refer to the [[ZK Client-side Reference/Communication/AU Requests|AU Requests]] section.</ref>.
 +
 +
<blockquote>
 +
----
 +
<references/>
 +
</blockquote>
  
 
=Event Listening for Application Developers=
 
=Event Listening for Application Developers=
  
To listen a widget event, you could invoke <javadoc method="listen(_global_.Map, int)" directory="jsdoc">zk.Widget</javadoc> to listen the widget event you want. However, <javadoc method="listen(_global_.Map, int)" directory="jsdoc">zk.Widget</javadoc> is designed for applications to listen events at the client. For component development, the method overriding is suggested as described in the following subsections.
+
To listen a widget event, you could invoke <javadoc method="listen(_global_.Map, int)" directory="jsdoc">zk.Widget</javadoc> to listen the widget event you want. However, <javadoc method="listen(_global_.Map, int)" directory="jsdoc">zk.Widget</javadoc> is designed for applications to listen events at the client. For component development, the method overriding is suggested as described in the previous subsections.
  
 
The signature of an event listener is as follows.
 
The signature of an event listener is as follows.
Line 19: Line 31:
 
}
 
}
 
</source>
 
</source>
 
=Event Listening for Component Developers=
 
 
==Event Propgation ==
 
A widget event will be ''propagated'' to the parent widget, parent's parent and so on, until stopped (<javadoc method="stop(_global_.Map)" directory="jsdoc">zk.Event</javadoc>). Then, if the event is required by the server, it will be sent to the server, and converted to an instance of <javadoc type="interface">org.zkoss.zk.au.AuRequest</javadoc> at the server<ref>For more information, please refer to the [[ZK Client-side Reference/Communication/AU Requests|AU Requests]] section.</ref>.
 
 
<blockquote>
 
----
 
<references/>
 
</blockquote>
 
  
 
=Event Firing=
 
=Event Firing=

Revision as of 08:53, 20 December 2010


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 a window has been moved.

In additions, 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 applied to the DOM elements of 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.

Event Propgation

A widget event will be propagated to the parent widget, parent's parent and so on, until stopped (Event.stop(Map)). Then, if the event is required by the server, it will be sent to the server, and converted to an instance of AuRequest at the server[1].


  1. For more information, please refer to the AU Requests section.

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. 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[1].

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

  1. For more information, please refer to the AU Requests section.

Version History

Last Update : 2010/12/20


Version Date Content
     



Last Update : 2010/12/20

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.