CreateEvent"

From Documentation
 
(7 intermediate revisions by 3 users not shown)
Line 9: Line 9:
 
= Employment/Purpose =
 
= Employment/Purpose =
  
Used to notify a window that all its children are created and initialized. <tt>UiEngine</tt> post this event to components that declares the <tt>onCreate</tt> handler (either as a method or as in instance definition).
+
<code>UiEngine</code> posts this event to notify a component that all its children are created and initialized when creating components upon a zul page. So devs can listen to this event to do your application-specific initialization logic.
  
= Example =
+
But if you create components on your new statement (e.g. <code>new Label()</code>), not through a zul, ZK doesn't post such an event.
 
 
N/A
 
  
 
= Notes =
 
= Notes =
Line 29: Line 27:
 
where the execution sequence is as follows.
 
where the execution sequence is as follows.
  
# ZK Loader creates a listbox and a listitem, and posts <tt>onCreate</tt> to the listitem (since it has a listener).
+
# ZK Loader creates a listbox and a listitem, and posts <code>onCreate</code> to the listitem (since it has a listener).
# The data binder processes all annotations, after all components are created.
+
# The data binder processes all annotations, after all the components are created.
## When handling <tt>each</tt>, the data binder detaches the listitem, invokes <javadoc method="clone()">org.zkoss.zk.ui.Component</javadoc> to make a clone for each item (person.interests), and attach the clone to the listbox.
+
## When handling <code>each</code>, the data binder detaches the listitem, invokes <javadoc method="clone()">org.zkoss.zk.ui.Component</javadoc> to make a clone for each item (person.interests), and attach the clone to the listbox.
# The listitem created by ZK Loader receives <tt>onCreate</tt>.
+
# The listitem created by ZK Loader receives <code>onCreate</code>.
  
 
The detail behavior of step 3 is a bit different since 5.0.4. We will discuss it more detailed in the following sections.
 
The detail behavior of step 3 is a bit different since 5.0.4. We will discuss it more detailed in the following sections.
Line 38: Line 36:
 
=== 5.0.3 and earlier ===
 
=== 5.0.3 and earlier ===
  
With 5.0.3 and earlier, only the original listitem (the listitem used as template to be cloned) will receive <tt>onCreate</tt>.
+
With 5.0.3 and earlier, only the original listitem (the listitem used as template to be cloned) will receive <code>onCreate</code>.
 
Thus, whatever change the listener made won't affect the cloned listitems.
 
Thus, whatever change the listener made won't affect the cloned listitems.
  
Line 44: Line 42:
  
 
=== 5.0.4 ===
 
=== 5.0.4 ===
Since 5.0.4, the data binder will fire <tt>onCreate</tt> to each cloned component, so it is safe to use <tt>onCreate</tt> with the data binder.
+
Since 5.0.4, the data binder will fire <code>onCreate</code> to each cloned component, so it is safe to use <code>onCreate</code> with the data binder.
  
However, there is one more thing to be noticed: how the event listener is cloned when a component is cloned. By default, the new component will share the same listener with the original component. Sometimes, it might not be correct (for example, the listener might be an inner class that assumes <tt>this</tt> to be the original component), the event listener shall implement <javadoc>org.zkoss.zk.ui.util.ComponentCloneListener</javadoc> to clone the listener by itself. For example,
+
However, there is one more thing to be noticed: how the event listener is cloned when a component is cloned. By default, the new component will share the same listener with the original component. Sometimes, it might not be correct (for example, the listener might be an inner class that assumes <code>this</code> to be the original component), the event listener shall implement <javadoc>org.zkoss.zk.ui.util.ComponentCloneListener</javadoc> to clone the listener by itself. For example,
  
 
<source lang="java">
 
<source lang="java">
Line 63: Line 61:
 
</source>
 
</source>
  
Instead of implementing <javadoc>org.zkoss.zk.ui.util.ComponentCloneListener</javadoc>, using <javadoc method="getTarget()">org.zkoss.zk.ui.event.Event</java> could be easier way to make a listener safe to clone.
+
Instead of implementing <javadoc>org.zkoss.zk.ui.util.ComponentCloneListener</javadoc>, using <javadoc method="getTarget()">org.zkoss.zk.ui.event.Event</javadoc> could be easier to make a listener safe to clone.
  
  
Line 77: Line 75:
 
=Supported events=
 
=Supported events=
  
{| border="1" | width="100%"
+
{| class='wikitable' | width="100%"
 
! <center>Name</center>
 
! <center>Name</center>
 
! <center>Event Type</center>
 
! <center>Event Type</center>
Line 91: Line 89:
 
=Use cases=
 
=Use cases=
  
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Description !! Example Location
 
! Version !! Description !! Example Location
 
|-
 
|-
Line 101: Line 99:
 
=Version History=
 
=Version History=
  
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 
|-
 
|-

Latest revision as of 02:40, 24 November 2023

CreateEvent

  • Demonstration: N/A
  • Java API: CreateEvent
  • JavaScript API: N/A

Employment/Purpose

UiEngine posts this event to notify a component that all its children are created and initialized when creating components upon a zul page. So devs can listen to this event to do your application-specific initialization logic.

But if you create components on your new statement (e.g. new Label()), not through a zul, ZK doesn't post such an event.

Notes

Use with data binding

When the data binder processed a collection of data in, say, a grid or a listbox, it will detach the original one, and then clone it to represent each item of the data. For example,

<listbox model="@{person.interests}">
	<listitem self="@{each=obj}" value="@{obj}" onCreate="foo()"/>
</listbox>

where the execution sequence is as follows.

  1. ZK Loader creates a listbox and a listitem, and posts onCreate to the listitem (since it has a listener).
  2. The data binder processes all annotations, after all the components are created.
    1. When handling each, the data binder detaches the listitem, invokes Component.clone() to make a clone for each item (person.interests), and attach the clone to the listbox.
  3. The listitem created by ZK Loader receives onCreate.

The detail behavior of step 3 is a bit different since 5.0.4. We will discuss it more detailed in the following sections.

5.0.3 and earlier

With 5.0.3 and earlier, only the original listitem (the listitem used as template to be cloned) will receive onCreate. Thus, whatever change the listener made won't affect the cloned listitems.

In summary, when using data binding with 5.0.3 or earlier, don't use onCreate.

5.0.4

Since 5.0.4, the data binder will fire onCreate to each cloned component, so it is safe to use onCreate with the data binder.

However, there is one more thing to be noticed: how the event listener is cloned when a component is cloned. By default, the new component will share the same listener with the original component. Sometimes, it might not be correct (for example, the listener might be an inner class that assumes this to be the original component), the event listener shall implement ComponentCloneListener to clone the listener by itself. For example,

public FooCreateListener implements EventListener, ComponentCloneListener {
  private Listitem _item;
  public FooListener(Listitem item) {
    _item = item;
  }
  public Object willClone(Component comp) {
    return new FooListener((Listitem)comp);
  }
  public void onEvent(Event evt) {
   //handle _item
  }
}

Instead of implementing ComponentCloneListener, using Event.getTarget() could be easier to make a listener safe to clone.


public FooCreateListener implements EventListener, ComponentCloneListener {
  public void onEvent(Event evt) {
    Listitem item = (Listitem)evt.getTarget();
    //then, handle item
  }
}

Supported events

Name
Event Type
None None

Supported Children

*NONE

Use cases

Version Description Example Location
     

Version History

Version Date Content
     



Last Update : 2023/11/24

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