LzEvent

Events underly most of the functionality in OpenLaszlo applications. Unlike events in similar systems, OpenLaszlo's events are point-to-point, meaning that there is no general broadcast mechanism for events, and events do not trickle up or down the instance hierarchy. Instead, objects called delegates register for events, and if they try to register for an event that doesn't exist yet, the system creates the event.

You can create a delegate explicitly using the LzDelegate class, or implicitly by creating an handler.

Because of the loose type requirements in LZX, calling an event that no delegate is listening for (and which therefore hasn't been created) has no effect. This allows objects to publish many more events than they actually need to create at runtime.

There are two syntaxes with which you can specify an event handler: in the tag used to create that object, or by using the <handler> tag.

To specify an event handler in an object-creation tag, simply include it like any other attribute. For example,

<view onmouseover="doSomething()">
  <method name="doSomething">
    // code to be executed when mouse is over the view
  </method>
</view>

If you use the <handler> tag, you do not need to include the handler in the tag that creates the object.

<view>
 <handler name="onmouseover">
   // code to be executed when the mouse is over the view
 </name>
</view>

The above two examples are functionally equivalent. Using the <handler> tag, however, can often lead to more readable code because it removes clutter from the object creation tag.

Use the <event> tag to create the events; then use the sendEvent method to dispatch it. The following example illustrates how to create custom events.

Example 1. A simple example of publishing and listening for a custom event

<canvas height="40">
  <simplelayout/>
  <button name="eventSender" 
          onmouseover="this.customevent.sendEvent()"
          onmouseout="this.customevent.sendEvent()"/>
  <event name="customevent"/>
  <view bgcolor="red" width="20" height="20" oninit="this.setupDelegate()">
    <method name="setupDelegate">
      this.del = new LzDelegate( this, "respondToEvent" );
      this.del.register( eventSender , "customevent" );
    </method>
    <method name="respondToEvent">
      this.setAttribute('x', this.x + 10);
    </method>
  </view>
</canvas>

Events can be sent with a single argument, which usually conveys information about the property that changed. The default behavior of the setAttribute method is to set the named property and send the event called "on" + property. This is general mechanism that updates constraints in a OpenLaszlo programs. For instance, when a view changes its x position, it sends the event onx with the new value for its x property.

Example 2. Event sending in response to setting an attribute

<canvas height="40">
  <simplelayout/>
  <button name="eventSender" 
          onmouseover="this.setAttribute('avalue', this.avalue + 10)"
          onmouseout="this.setAttribute('avalue', this.avalue + 5)">
    <attribute name="avalue" value="0"/>
  </button>
  <view bgcolor="red" width="20" height="20" oninit="this.setupDelegate()">
    <method name="setupDelegate">
      this.del = new LzDelegate(this, "respondToEvent");
      this.del.register(eventSender, "onavalue");
    </method>
    <method name="respondToEvent" args="v">
      this.setAttribute('x' , v);
    </method>
  </view>
</canvas>