Choose method names carefully. Names should be descriptive, to help you and other readers of your code understand what they do. You need also to keep in mind that when you extend a class, your new class inherits the methods of the class from which it was extended. If you give a new method the name of already existing method, the original method will be overridden. To avoid such "naming collisions" you should consult the LZX Reference, which lists all methods for all Laszlo Foundation Classes (LFC).

The method attribute 'args' is used to pass arguments to a method. The value of the 'args' attribute is a string containing variable names separated by commas. In the following example, two arguments 'a' and 'b' are declared in the args attribute of the method named 'add'. To call this method in script to add the number 1 to the number 2, you would write myNode.add(1, 2);

Example 29.2. Defining a method with arguments

<canvas debug="true">
  <debug y="10"/>
  <node id="myNode">
    <method name="add" args="a,b">
      var sum = a + b;
      Debug.write('a + b = ' + sum);          
    </method>
  </node>
  <script>
     myNode.add(4,9)
   </script>
</canvas> 

Sometimes when you write a method, you want the result to be returned to the calling script for further processing. In the following example, returnsum() method uses the 'return' keyword. In the script block, this value is used in turn to compute another.

Example 29.3. Returning data from a method

<canvas debug="true">
  <debug y="10"/>
  <node id="myNode">
    <method name="returnsum" args="a,b">
      var sum = 3 + 4;
      Debug.write('a + b = ' + sum);          
      return sum;
    </method>
  </node>
  <script>
      var x = 5;
      var y = myNode.returnsum();
      var z = x + y;
      Debug.write('z equals ' +  z)
  </script>
</canvas> 

Any defined attribute has an associated event called "on" plus the name of the attribute. Whenever the value of any attribute is updated using the setAttribute(), its associated "on" event is generated. For example, the "height" attribute of a view has an associated "onheight" event that is generated whenever the view's height changes. These events are implicit in the sense that they are built into the system — you don't have to declare them or send them.

Said another way, the default behavior of the setAttribute() method is to set the named property and send the event. For instance, when a view changes its x position, it sends the event onx with the new value for its x property.

In addition to the implicit event associated with each named attribute, LFC classes have a variety of additional events associated with them. For example, the <view> tag has an onclick event that is generated whenever the user clicks the mouse while the cursor is positioned over the view— even though there is no attribute named "click". See the LZX Reference Manual for a complete list of events associated with LFC classes.

In addition to built-in and implicit events, you can explicitly declare events with the <event> tag.

Note that in 3.n and earlier releases, you can send events that have not been explicitly declared. However, this is not a good practice, and applications that rely on this will break with release 4.0. Therefore, it's good to get in the habit of declaring any events that you know you will send by calling sendEvent().

When you create an event using the <event>, you are creating an instance of the class called LzEvent. You can then call the sendEvent() on this class to explicitly cause the event to be sent.

<button name="framitzbutton" onclick="sendframitz()">
     Send framitz event
     <event name="framitz"/>
     <method name="sendframitz">
      framitz.sendEvent()
     </method>
 </button>

You shouldn't send an event for which no handler has been defined. That is to say, it is fine to define an event (using the <event> tag) for which no handler exists. This is often useful to to in prototyping. But don't send it unless you know that there is a handler for it.

Note that there is virtually never any reason to create an event in script by creating a new LzEvent. Likewise, there is virtually never any reason for you to use any method on this event other than sendEvent. Other methods are used internally within the Laszlo Foundation Classes; they are not intended for user code.

The "onevent" syntax is available for attributes that correspond to the CSS event model—onclick, onmouseover, and so forth. For such events, the simplest way to declare an event handler is simply to include it in the definition tag of the node that contains the attribute. This syntax does not work for other events generated by class attributes; for those you must use the < handler> syntax.

In the example below, the event handler for the event generated by the user mouse click changes the views's color from red to blue.

Example 29.5. Event handler defined in opening tag

<canvas height="50">
   <view height="30" width="30" bgcolor="red" onclick="setAttribute('bgcolor', blue)"/>
</canvas>

The <handler> tag defines how an instance responds to an event. A handler can either specify the code to handle an event or it can specify a method that should be invoked to handle the event. Any event can have an unlimited number of handlers associated with it.

4.2.1. Handler tag "name" attribute

The <handler> tag defines code that is executed when an event that has the name of the handler is fired. The name of the handler is the same as the name of the event with which it is associated. For example, the "onclick" event is handled by a handler also named "onclick". Event handlers defined in this way are executed whenever their associated event occurs.

The following example shows how you might handle a button click:

Example 29.6. A simple handler

<canvas height="40">
  <button text="not clicked">
    <handler name="onclick">
      this.setAttribute('text', 'clicked'); 
    </handler>
  </button>
</canvas>  

An event can have associated with it any number of handlers. When that event is sent, all handlers associated with it are executed.

Example 29.7. Multiple handlers for one event

<canvas debug="true">
  <debug y=" 20"/>
  <button>
   Howdy!
   <handler name="onclick">
      Debug.write("handler one")
   </handler>
     <handler name="onclick">
      Debug.write("handler two")
   </handler>
  <handler name="onclick">
      Debug.write("handler three")
   </handler>
   </button>
</canvas>

A handler may include javascript code to be executed when the associated event occurs, or it may reference a method that contains the code to be executed. To reference another method, use the method attribute of the <handler> tag.

Example 29.8. Calling a method from a handler

<canvas debug="true">
   <debug y="50"/>
 <simplelayout/>
 <view name="myview" height="30" width="30" bgcolor="blue"/>
 <button>
   Make red the blue box!
  <handler name="onclick" method="redify"/>
  <method name="redify">
     parent.myview.setAttribute("bgcolor", red)
  </method>
  </button>
</canvas>

A handler is not overridable in a subclass, so you can add as many handlers as you like to an event and they will all fire.

If you want a subclass to be able to override the handling of an event in a superclass, the superclass would associate a method with the event by:

<handler name="eventName" method="methodName" />

And the subclass would overrride methodName.

Recall that a method is an 'action' you can perform on an instance, and that you can call it from any script. You could call it from a handler. For example, the usage above can be written longhand as:

<handler name="eventName">
  this.methodName();
</handler>

If you want the superclass to define a handler that the subclass can override, you would have the handler point to a method, and in the subclass you just override the method. Let's repeat that to make it clear: when you want the subclass to have a different behavior than the superclass, don't attempt to override the handler in the subclass, and don't create a new handler in the subclass. Instead, have the handler in the superclass call a method, and then in the subclass, override that method. Try this example, which hopefully makes all clear:

Example 29.9. Overriding event-handler method in subclass

<canvas debug="true">
  <class name="base" extends="button">
    <handler name="onclick" method="handleonclick" />
    <method name="handleonclick">
      Debug.write("base click");
    </method>
  </class>

  <class name="subaccumulate" extends="base">
    <handler name="onclick">
      Debug.write("subaccumulate click");
    </handler>
  </class>

  <class name="suboverride" extends="base">
    <method name="handleonclick">
      Debug.write("suboverride click");
    </method>
  </class>

  <subaccumulate>accumulate</subaccumulate>
  <suboverride>override</suboverride>
  <simplelayout />
</canvas>

Here is the same example with instances:

Example 29.10. Overriding event-handling method in an intance

<canvas debug="true">
  <class name="base" extends="button">
    <handler name="onclick" method="handleonclick" />
    <method name="handleonclick">
      Debug.write("base click");
    </method>
  </class>

  <base text="Accumulate">
    <handler name="onclick">
      Debug.write("subaccumulate click");
    </handler>
  </base>

  <base text="Override">
    <method name="handleonclick">
      Debug.write("suboverride click");
    </method>
  </base>

  <simplelayout />
</canvas>

Suppose you want to handle, in one class, an event from some other object? In that case, you would use the reference attribute:

<handler name="onclick" reference="yours">
  Debug.write("Someone is pushing your button");
</handler>

Here's an example:

Example 29.11. Referencing an event in another object

<canvas debug="true">
  <class name="base" extends="button">
    <handler name="onclick" method="handleonclick" />
    <method name="handleonclick">
      Debug.write("base click");
    </method>
  </class>

  <base id="yours" text="Yours">
    <handler name="onclick">
      Debug.write("Your click");
    </handler>
  </base>

  <base text="Mine">
    <method name="handleonclick">
      Debug.write("My click");
    </method>
    <handler name="onclick" reference="yours">
      Debug.write("Someone is pushing your buttons.");
    </handler>
  </base>

  <simplelayout />
</canvas>

Note that Mine handles a click on Yours. Even though the handler is in Mine, it only runs when you click Yours.

As has been discussed above, you can cause an event to be sent explicitly, by defining the event and then calling the sendEvent() on it. Or, you can use the setAttribute() method to implicitly define and send an event. A third way of defining events, using delegates, is explained in Chapter 30, Delegates.

<canvas debug="true">
     <debug />

    <class name="myclass_with_handler">
        <event name="myevent"/>
        <handler name="myevent" args="myargs">
            Debug.write(this, 'handling myevent, myargs=', myargs);
        </handler>

        <attribute name="season" type="string" value="spring" />
        <event name="onseason" />
        <handler name="onseason" args="s">
            Debug.write("got season of ", s, ", season is ", season);
        </handler>
    </class>

  <myclass_with_handler id="foo" />


  <button onclick="foo.myevent.sendEvent(12)" text="send the event" />
  <button onclick="foo.setAttribute('season', 'fall')" text="autumn" />

  <!-- Don't do this! Setting an attribute directly with '=' shortcuts around
       the event system. This is not right; use setAttribute instead -->
  <button onclick="foo.season='winter'" text="evil" />

  <simplelayout axis="x" spacing="5" />

</canvas>

As is explained in Chapter 30, Delegates, an event doesn't really exist unless and until there is a delegate registered to recieve it. In code that was written before the <event> tag became part of the language, before sending an event it was necessary to test whether the receiving delegate existed; otherwise an error resulted. In order to create your own event, you needed to create an attribute like this:

<attribute name="onsomeevent" value="null"/>

Then, you had to check to see if it was a valid LzEvent before calling sendEvent()() on it. Ways of making that test look like this:

    if ( onsomeevent instanceof LzEvent) {
       onsomeevent.sendEvent();
    }

or like this:

    if (classroot.onactivate) {
       classroot.onactivate.sendEvent();
    }

If you use the <event> and <handler> syntax, you do not have to worry about such tests. (The delegates are handled for you by the runtime.)

Attributes can be placed into five categories according to how they are set, read, and modified.

These are described briefly in the following sections.

5.1.1. Attributes (with setter)

These are built-in attributes which have setters that may be modified at runtime and used in constraint expressions. When setAttribute() is called, the appropriate setter is called automatically. The value of an attribute can be retrieved through script using dot syntax, for example, myView.opacity.

For example:

Example 29.17. Using setAttribute to update a constraint

<canvas height="20">
  <view id="myView" onclick="setAttribute('opacity', 1.5 - this.opacity)" bgcolor="red">
    <text text="${'My opacity is ' + myView.opacity + 'x  Click to change it.'}"/>
  </view>
</canvas>

5.1.2. Attributes (without setter)

Some attributes are usable in a tag, but do not have a predefined setter method. Instead they use the default setter method (setAttribute()) to set their values at run-time. Typically they are custom attributes that have been declared in components using the <attribute> tag. Therefore they can be declared and set in tags too.

Example 29.18. An attribute without a setter method

<canvas height="200" width="600" >
    <window height="50" width="200" title="My Window" onclick="this.setAttribute('title', 'Hello World');"/>
</canvas>

Attributes can be constrained to the value of other attributes. See the Chapter 27, Constraints for details.

By default, attributes are of the JavaScript expression type, but in some cases the default declaration doesn't give enough instruction to achieve the desired result. In this example, no labels are displayed in the boxes:

Example 29.21. Incorrect: attribute has no effect

<canvas height="300">
    <simplelayout spacing="5"/>
    <class name="box" height="100" width="100" bgcolor="red">
       <attribute name="label" value="Label"/>
       <text text="${parent.label}" />
    </class>

    <box label="Box1"/>
    <box/>
</canvas>

To make sure attributes do what you want them to do, assign a type to your attributes when you declare them:

Example 29.22. Declaring attribute type

<canvas height="300">
    <simplelayout spacing="5"/>
    <class name="box" height="100" width="100" bgcolor="red">
       <attribute name="label" value="Label"  type="string"/>
       <text text="${parent.label}" />
    </class>

    <box label="Box1"/>
    <box/>
</canvas>

The value of an attribute, whether set in an attribute element or start tag, is evaluated according to the attribute when option. when can be one of the following:

The declared evaluation time of an attribute can be overridden when assigning a value by using value="$when{expression}" (or in a start tag by <tag attribute="$when{expression}">), where when is one of the possible when options. If omitted, when defaults to always.

when is a declaration and applies to any setting of the tag, not just the initial one. For example, the width and height attributes of view are declared when="always": any time you set width or height, it creates a constraint, even if you don't say ${expression}. (The compiler is optimized to evaluate constant constraints only once).

${expression} can be used to override the declaration at any site where you are setting the value of an attribute. For example, the title attribute of view is declared when="once", so if you want to have a dynamically updating title, you need to say title=${some.reference} to constrain it to follow some.reference.

Note that an attribute that is not given an initial value will not be created in the element by default: it should either be initialized in the init method using this.attrName=expression or made a required attribute using the required="true" option.

Attributes can normally be referred to in class methods and expressions by their name except when being initialized as above, in which case they must be referred to using this., in order to create the attribute in the element.

For example:

<class name="myclass">
  <!-- 'foo' has an initial value of 1 -->
  <attribute name="foo" value="1"/>
  <!-- 'thing' is always four more than 'foo' -->
  <attribute name="thing" value="foo + 4" when="always"/>
  <!-- 'bar' is only declared, initialized below -->
  <attribute name="bar"/>

  <handler name="oninit">
    <!--
      the attribute 'bar' will be created in the instance
      sets its value to true
      is appropriate for internal script flags
    -->
    this.bar= true; 
    <!-- 
      probably a mistake...
      sets the value of attribute 'foo' to 4,
      but does not update the constraint on 'thing'
      use setAttribute, as below
    -->
    this.foo = 4;            
  </handler>

  <method name="dothis">
    if (bar) {
      <!--
        sets the value of 'foo' to 6             
        sends the event 'onfoo'
        (which causes dependent constraints to be evaluated)
        as a result 'thing' will equal 10
      -->
      this.setAttribute("foo", 6);
    }                
  </method>
</class>

In many cases, specific code operations need to take place when an attribute is set. For example, when the width attribute of a <view> is set, the view needs to update the width of the parent view if clipping is set to false. Though it is very convenient to simply handle the onwidth event to execute the required code, there is no guarantee as to order events will be called. This task is instead accomplished best using the setAttribute() method of <view>, to set the width attribute.

In the following example, the time between clicks is shown on a button. For every click, the current time in milliseconds is stored in the time attribute. The custom setter, setTime(), has been defined for the time attribute.

Normally, when an attribute is set by invoking setAttribute(), setAttribute() handles the tasks of setting the value of the attribute, and sending the onattribute event. You can change this behavior by using the setter attribute on the <attribute> tag. You would then define a method that has the name of the setter.

When defining a custom setter for an attribute, you are responsible for setting the value and sending the onattribute event, as shown in the example below. If the onattribute event isn't sent in the custom defined settter, registered onattribute events will not fire, and constraints tied to the attribute will not be updated when the value of the attribute is changed.

Example 29.24. Defining an explicit setter method

<canvas height="40"> 
  <button text="click me">
    <attribute name="time" setter="setTime(time)"/> 
    <attribute name="ontime" value="null"/> 

    <handler name="onclick"> 
      Debug.write('inited:' + this.isinited); 
      var now = (new Date()).getTime();
      this.setAttribute("time", now); 
    </handler> 

    <method name="setTime" args="t"> 
      if (!this.isinited) {                                          //catch the case where this.time is being 
        this.time = t;                                               //initialized during object instantiation
        return;
      } 

      if (typeof this.time == "undefined" || this.time == null) {    //handle first set of time
        this.setAttribute("text", "first click registered");
      } 
      else {
        var diff = t - this.time;                                    //handle any additional setting of time
        this.setAttribute("text", diff + " milliseconds between clicks");             
      } 
      this.time = t;                                                 //as this is the declared setter for 
                                                                     //this.time, we have to set it

      if (ontime)                                                    //required to update constraints and 
        this.ontime.sendEvent();                                     //fire ontime event 
    </method> 
  </button> 
</canvas> 

Instances and subclasses of LzNode, including LzView and classes defined using <class> , have both an init() method and an oninit event. Since you do not have control over the order that events are fired, you should put all initialization code in the init() method (and not, for example, in a handler for oninit).

If you declare an init() method in a view or class, you are effectively overriding the init() method in that object's super class. The <view> tag and all its subclasses have important initialization code in the init method, and it is essential that this code is executed when overriding init(). This is accomplished by using the super keyword, which is a reference to the superclass. In the example below, we override the init method in the button class. Notice the call to super.init(), which executes initialization code for the button. The init() method for button subsequently invokes super.init on basebutton, and so on up to the execution of LzNode.init().

Example 29.25. init() method vs oninit event

<canvas height="40">
  <button>
    <method name="init">
      super.init(); //best practice to always call super.init() when declaring 
                    //an init method
      //do some init code here
    </method>
    
    <handler name="oninit">
      //this isn't fired in any particular order 
      //use the init method instead
    </handler>
  </button>
</canvas> 

When setting variables local to the current class, node, or view, always refer to those variables using the keyword this.

Example 29.26. Using "this" keyword

<canvas height="50">
   <view x=" 10" height="30" width="30" bgcolor="red"
   onclick="this.bringToFront()"/>
   <view  height="30" width="30" bgcolor="blue"
   onclick="this.bringToFront()"/> 
</canvas>

Not using this can result in unpredictable results.

There are four ways of getting and setting attributes in LZX, each with benefits and drawbacks:

<node>
  <attribute name="foo"/>
  
  <method name="doSomething">
    this.setWidth(10); 
    Debug.write('width' + this.getWidth());        
  </method> 
</node>

<node>
  <attribute name="foo"/>
  
  <method name="doSomething">
    this.width = 10;
    Debug.write('width' + this.width);
  </method>
</node>