Event Listening"

From Documentation
m
Line 1: Line 1:
{{ZKComponentReferencePageHeader}}
+
{{ZKDevelopersReferencePageHeader}}
  
 
There are two ways to listen an event: an event handler and an event listener.
 
There are two ways to listen an event: an event handler and an event listener.
Line 10: Line 10:
 
An event handler can be declared in a ZUL page by specifying an event attribute<ref>An event attribute is an attribute starting with <tt>on</tt></ref>. For example,
 
An event handler can be declared in a ZUL page by specifying an event attribute<ref>An event attribute is an attribute starting with <tt>on</tt></ref>. For example,
  
<source lang="xml">
+
<syntax lang="xml">
 
<button label="hi" onClick='alert("Hello")'/>
 
<button label="hi" onClick='alert("Hello")'/>
</source>
+
</syntax>
  
 
where the content of the event handler is the code snippet in Java. The event handler will be interpreted at the run time (by use of BeanShell). If you prefer to use other language, you could specify the language name in front of it. For example, the following uses Groovy as the interpreter:
 
where the content of the event handler is the code snippet in Java. The event handler will be interpreted at the run time (by use of BeanShell). If you prefer to use other language, you could specify the language name in front of it. For example, the following uses Groovy as the interpreter:
  
<source lang="xml">
+
<syntax lang="xml">
 
<button label="hi" onClick="groovy:alert('Hi, Groovy')"/>
 
<button label="hi" onClick="groovy:alert('Hi, Groovy')"/>
</source>
+
</syntax>
  
 
Important Builtin Variables
 
Important Builtin Variables
Line 44: Line 44:
 
The other way to have an event listener is to declare it as a member of a component class. For example,
 
The other way to have an event listener is to declare it as a member of a component class. For example,
  
<source lang="Java">
+
<syntax lang="java">
 
public class MyButton extends Button {
 
public class MyButton extends Button {
 
     public void onClick() {
 
     public void onClick() {
Line 50: Line 50:
 
     }
 
     }
 
}
 
}
</source>
+
</syntax>
  
 
If the event handler needs to handle the event, it can declare the event as the argument as follows.
 
If the event handler needs to handle the event, it can declare the event as the argument as follows.
  
<source lang="Java">
+
<syntax lang="java">
 
public class MyButton extends Button {
 
public class MyButton extends Button {
 
     public void onClick(MouseEvent event) {
 
     public void onClick(MouseEvent event) {
Line 60: Line 60:
 
     }
 
     }
 
}
 
}
</source>
+
</syntax>
  
 
Suggestions:
 
Suggestions:
Line 77: Line 77:
 
An event listener is a class implementing <javadoc type="interface">org.zkoss.zk.ui.event.EventListener</javadoc>. For example,
 
An event listener is a class implementing <javadoc type="interface">org.zkoss.zk.ui.event.EventListener</javadoc>. For example,
  
<source lang="java">
+
<syntax lang="java">
 
public class MyListener implements EventListener {
 
public class MyListener implements EventListener {
 
     public void onEvent(Event event) {
 
     public void onEvent(Event event) {
Line 83: Line 83:
 
     }
 
     }
 
}
 
}
</source>
+
</syntax>
  
 
Then, you can register an event listener to the component that might receive the event by use of <javadoc method="addEventListener(java.lang.String, org.zkoss.zk.ui.event.EventListener)">org.zkoss.zk.ui.Component</javadoc>. For example,
 
Then, you can register an event listener to the component that might receive the event by use of <javadoc method="addEventListener(java.lang.String, org.zkoss.zk.ui.event.EventListener)">org.zkoss.zk.ui.Component</javadoc>. For example,
  
<source lang="java">
+
<syntax lang="java">
 
button.addEventListener("onClick", new MyListener());
 
button.addEventListener("onClick", new MyListener());
</source>
+
</syntax>
  
 
This is a typical approach to handle events. However, it is a bit tedious to register event listeners one-by-one if there are a lot of listeners. Rather, it is suggested to use a composer as described in the following section.
 
This is a typical approach to handle events. However, it is a bit tedious to register event listeners one-by-one if there are a lot of listeners. Rather, it is suggested to use a composer as described in the following section.
Line 97: Line 97:
 
If there are a lot of event listeners to register, it is suggested to use the auto-wiring feature of a composer. For example,
 
If there are a lot of event listeners to register, it is suggested to use the auto-wiring feature of a composer. For example,
  
<source lang="java">
+
<syntax lang="java">
 
public class MyComposer extends GenericForwardComposer {
 
public class MyComposer extends GenericForwardComposer {
 
     public void onClick$hi() {
 
     public void onClick$hi() {
Line 106: Line 106:
 
     }
 
     }
 
}
 
}
</source>
+
</syntax>
  
 
As shown above, the method for lsitening an event shall be named by starting with the event name, separating with <tt>$</tt>, and ending with the component's ID. The composer will search all matched methods and register the event listener automatically. Then, in the ZUL page, you can specify the <tt>apply</tt> attribute to associate the composer with a component.
 
As shown above, the method for lsitening an event shall be named by starting with the event name, separating with <tt>$</tt>, and ending with the component's ID. The composer will search all matched methods and register the event listener automatically. Then, in the ZUL page, you can specify the <tt>apply</tt> attribute to associate the composer with a component.
  
<source lang="xml">
+
<syntax lang="xml">
 
<window apply="MyComposer">
 
<window apply="MyComposer">
 
     <button id="hi"/>
 
     <button id="hi"/>
 
     <button id="bye"/>
 
     <button id="bye"/>
 
</window>
 
</window>
</source>
+
</syntax>
  
 
If the listener needs to access the event, just declare it as the argument:
 
If the listener needs to access the event, just declare it as the argument:
  
<source lang="java">
+
<syntax lang="java">
 
     public void onClick$hi(MouseEvent event) {
 
     public void onClick$hi(MouseEvent event) {
 
       Messsagebox.show("Hello, " + event.getName());
 
       Messsagebox.show("Hello, " + event.getName());
 
     }
 
     }
</source>
+
</syntax>
  
 
Though not limited, a composer is usually associated with an ID space (such as <javadoc>org.zkoss.zul.Window</javadoc>) to handle events and component within the give ID space. You could associate any component that properly represents a scope of your application to manage.
 
Though not limited, a composer is usually associated with an ID space (such as <javadoc>org.zkoss.zul.Window</javadoc>) to handle events and component within the give ID space. You could associate any component that properly represents a scope of your application to manage.
Line 137: Line 137:
 
|}
 
|}
  
{{ZKComponentReferencePageFooter}}
+
{{ZKDevelopersReferencePageFooter}}

Revision as of 07:12, 17 September 2010

There are two ways to listen an event: an event handler and an event listener.

Listen by use of an Event Handler

An event handler is a method specified as an event attribute of a ZK page or as a member of a component class.

Declare an Event Handler in a ZUL page

An event handler can be declared in a ZUL page by specifying an event attribute[1]. For example,

<syntax lang="xml"> <button label="hi" onClick='alert("Hello")'/> </syntax>

where the content of the event handler is the code snippet in Java. The event handler will be interpreted at the run time (by use of BeanShell). If you prefer to use other language, you could specify the language name in front of it. For example, the following uses Groovy as the interpreter:

<syntax lang="xml"> <button label="hi" onClick="groovy:alert('Hi, Groovy')"/> </syntax>

Important Builtin Variables

  • self - the component receiving the event. In the previous example, it is the button itself.
  • event - the event being received. In the previous example, it is an instance of MouseEvent.

Notice that the event handler declared in this way is interpreted at the run time, so it inherits all advantages and disadvantage of interpreter-based execution.

Advantange:

  • It can be changed on the fly without recompiling and reloading the application.
  • Easy to maintain if the code snippet is small.

Disadvantage:

  • Slower to run.
  • Compilation error can not be known in advance.
  • Hard to maintain if mixing business logic with user interface.

Suggestion:

  • It is generally suggested to use this approach for 1) prototyping, or 2) simple event handling.

Declare an Event Handler in Java

The other way to have an event listener is to declare it as a member of a component class. For example,

<syntax lang="java"> public class MyButton extends Button {

   public void onClick() {
       Messagebox.show("Hello");
   }

} </syntax>

If the event handler needs to handle the event, it can declare the event as the argument as follows.

<syntax lang="java"> public class MyButton extends Button {

   public void onClick(MouseEvent event) {
       Messagebox.show("Hello, "+event.getName());
   }

} </syntax>

Suggestions:

  • It is suggested to use this approach for component development, since it is subtle for application developers to notice its existence. In additions, it requires to extend the component class.

  1. An event attribute is an attribute starting with on

Listen by Use of an Event Listener

Event Listener

An event listener is a class implementing EventListener. For example,

<syntax lang="java"> public class MyListener implements EventListener {

   public void onEvent(Event event) {
       Messages.show("Hello");
   }

} </syntax>

Then, you can register an event listener to the component that might receive the event by use of Component.addEventListener(String, EventListener). For example,

<syntax lang="java"> button.addEventListener("onClick", new MyListener()); </syntax>

This is a typical approach to handle events. However, it is a bit tedious to register event listeners one-by-one if there are a lot of listeners. Rather, it is suggested to use a composer as described in the following section.

Composer and Event Listener Autowiring

If there are a lot of event listeners to register, it is suggested to use the auto-wiring feature of a composer. For example,

<syntax lang="java"> public class MyComposer extends GenericForwardComposer {

   public void onClick$hi() {
     Messsagebox.show("Hello");
   }
   public void onClick$bye() {
     Messsagebox.show("Bye");
   }

} </syntax>

As shown above, the method for lsitening an event shall be named by starting with the event name, separating with $, and ending with the component's ID. The composer will search all matched methods and register the event listener automatically. Then, in the ZUL page, you can specify the apply attribute to associate the composer with a component.

<syntax lang="xml"> <window apply="MyComposer">

   <button id="hi"/>
   <button id="bye"/>

</window> </syntax>

If the listener needs to access the event, just declare it as the argument:

<syntax lang="java">

   public void onClick$hi(MouseEvent event) {
     Messsagebox.show("Hello, " + event.getName());
   }

</syntax>

Though not limited, a composer is usually associated with an ID space (such as Window) to handle events and component within the give ID space. You could associate any component that properly represents a scope of your application to manage.

Version History

Version Date Content
     


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