Wire Event Listeners"

From Documentation
m ((via JWB))
(14 intermediate revisions by 6 users not shown)
Line 2: Line 2:
  
 
=Wire Event Listeners=
 
=Wire Event Listeners=
 +
To wire an event listener, you need to declare a method with <javadoc>org.zkoss.zk.ui.select.annotation.Listen</javadoc> annotation. The method should be public, with return type void, and has either no parameter or one parameter of the specific event type (correspond to the event being listened). The parameter of @Listen should be pairs of an event name and a selector, separated by a semicolon.
  
To wire an event listener, all you need is to declare a method with the event name. The method could have an optional argument for the event received. For example,
+
ZK will look for the target component specified by the selector '''in the same [[ZK%20Developer's%20Reference/UI%20Composing/ID%20Space | ID space]]'''.
 +
 
 +
For example,
 +
 
 +
<source lang="java">
 +
@Listen("onClick = #btn0")
 +
public void submit(MouseEvent event) {
 +
// called when onClick is received on the component of id btn0.
 +
}
 +
@Listen("onSelect = #listbox0")
 +
public void select(SelectEvent event) {
 +
// called when onSelect is received on the component of id listbox0.
 +
}
 +
</source>
 +
 
 +
==Event Listener Parameter==
 +
There are three ways to declare the method signature of the event listener:
 +
#No parameter
 +
#One parameter of the corresponding event type
 +
#One parameter of a super class of the corresponding event type
 +
 
 +
For example,
 +
 
 +
<source lang="java">
 +
@Listen("onChange = textbox#input0")
 +
public void change() {
 +
// called when onChange is received on the textbox of id input0.
 +
}
 +
@Listen("onChange = textbox#input1")
 +
public void change(InputEvent event) {
 +
// called when onChange is received on the textbox of id input1.
 +
}
 +
@Listen("onChange = textbox#input2")
 +
public void change(Event event) {
 +
// called when onChange is received on the textbox of id input2.
 +
}
 +
</source>
 +
 
 +
==Multiple Targets==
 +
If the selector matches multiple components, the event listener will be wired to '''all''' matched components. In such case, if you need to know which component receives the event, you can retrieve it from <code>Event#getTarget()</code>.
 +
 
 +
For example,
  
 
<source lang="java">
 
<source lang="java">
public void onChange(InputEvent event) {
+
@Listen("onClick = grid#myGrid > rows > row")
  //it will be wired and called when onChange is received.
+
public void click(MouseEvent event) {
 +
// called when onClick is received on any Row directly under the Grid of id myGrid
 +
}
 +
@Listen("onClick = #btn0, #btn1, #btn2")
 +
public void click(MouseEvent event) {
 +
// called when onClick is received on components of id #btn0, #btn1, or #btn2
 
}
 
}
public void onMove() {
+
</source>
  //wired and called too, but no pass of the event
+
 
 +
==Multiple Event Types==
 +
By separating multiple pairs of event names and selectors by '''semicolon''', you can wire different types of event to a single method.
 +
 
 +
For example,
 +
 
 +
<source lang="java">
 +
@Listen("onClick = button#submit; onOK = textbox#password")
 +
public void submit(Event event) {
 +
// called when onClick is received on #submit, or onOK (Enter key pressed) is received on #password
 
}
 
}
 
</source>
 
</source>
  
=Wire Event Listeners Targeting Fellows=
+
==Event Listener Priority==
 +
{{versionSince| 8.0.2}}
  
=Wire Event Listeners in Nested ID Space=
+
The calling order of an event listener can be declared by specifying a number after the event name. The event listeners will be executed in the order from the largest to smallest of the declared priority number. Listeners without a priority number will be set to 0 automatically.
 +
 
 +
For example,
 +
 
 +
<source lang="java">
 +
@Listen("onClick(1) = #btn0")
 +
public void submit1(MouseEvent event) {
 +
        // called before submit2 method when onClick is received on the component of id btn0.
 +
}
 +
@Listen("onClick = #btn0")
 +
public void submit2(MouseEvent event) {
 +
        // the priority of this listener will be set to 0 by default, and will be called after submit1 and before submit2 method when onClick is received on the component of id btn0.
 +
}
 +
@Listen("onClick(-1) = #btn0")
 +
public void select3(SelectEvent event) {
 +
        // called after submit2 method when onClick is received on the component of id btn0.
 +
}
 +
</source>
  
 
=Version History=
 
=Version History=
Last Update : {{REVISIONYEAR}}/{{REVISIONMONTH}}/{{REVISIONDAY}}
+
 
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 
|-
 
|-
| &nbsp;
+
| 6.0.0
| &nbsp;
+
| February 2012
| &nbsp;
+
| @Listen was introduced.
 
|}
 
|}
  
 
{{ZKDevelopersReferencePageFooter}}
 
{{ZKDevelopersReferencePageFooter}}

Revision as of 07:34, 8 July 2022


Wire Event Listeners


Wire Event Listeners

To wire an event listener, you need to declare a method with Listen annotation. The method should be public, with return type void, and has either no parameter or one parameter of the specific event type (correspond to the event being listened). The parameter of @Listen should be pairs of an event name and a selector, separated by a semicolon.

ZK will look for the target component specified by the selector in the same ID space.

For example,

@Listen("onClick = #btn0")
public void submit(MouseEvent event) {
	// called when onClick is received on the component of id btn0.
}
@Listen("onSelect = #listbox0")
public void select(SelectEvent event) {
	// called when onSelect is received on the component of id listbox0.
}

Event Listener Parameter

There are three ways to declare the method signature of the event listener:

  1. No parameter
  2. One parameter of the corresponding event type
  3. One parameter of a super class of the corresponding event type

For example,

@Listen("onChange = textbox#input0")
public void change() {
	// called when onChange is received on the textbox of id input0.
}
@Listen("onChange = textbox#input1")
public void change(InputEvent event) { 
	// called when onChange is received on the textbox of id input1.
}
@Listen("onChange = textbox#input2")
public void change(Event event) { 
	// called when onChange is received on the textbox of id input2.
}

Multiple Targets

If the selector matches multiple components, the event listener will be wired to all matched components. In such case, if you need to know which component receives the event, you can retrieve it from Event#getTarget().

For example,

@Listen("onClick = grid#myGrid > rows > row")
public void click(MouseEvent event) {
	// called when onClick is received on any Row directly under the Grid of id myGrid
}
@Listen("onClick = #btn0, #btn1, #btn2")
public void click(MouseEvent event) {
	// called when onClick is received on components of id #btn0, #btn1, or #btn2
}

Multiple Event Types

By separating multiple pairs of event names and selectors by semicolon, you can wire different types of event to a single method.

For example,

@Listen("onClick = button#submit; onOK = textbox#password")
public void submit(Event event) {
	// called when onClick is received on #submit, or onOK (Enter key pressed) is received on #password
}

Event Listener Priority

Since 8.0.2

The calling order of an event listener can be declared by specifying a number after the event name. The event listeners will be executed in the order from the largest to smallest of the declared priority number. Listeners without a priority number will be set to 0 automatically.

For example,

@Listen("onClick(1) = #btn0")
public void submit1(MouseEvent event) {
        // called before submit2 method when onClick is received on the component of id btn0.
}
@Listen("onClick = #btn0")
public void submit2(MouseEvent event) {
        // the priority of this listener will be set to 0 by default, and will be called after submit1 and before submit2 method when onClick is received on the component of id btn0.
}
@Listen("onClick(-1) = #btn0")
public void select3(SelectEvent event) {
        // called after submit2 method when onClick is received on the component of id btn0.
}

Version History

Version Date Content
6.0.0 February 2012 @Listen was introduced.



Last Update : 2022/07/08

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