The purpose of a delegate is to bind an event at runtime to a particular method. Thus to "register an event with a delegate" simply means to bind that event, temporarily, to the method that is invoked by the delegate. The event stays bound to that method until you "unregister" the delegate. This means, then, that when the event happens the method is executed.

Significantly, you can use delegates even if you don't know, at compile time, the name of the event that will invoke the delegate— the name of the event can be passed as a parameter whose value is generated during the running of the application.

In LZX, delegates and events are defined in terms of each other. A delegate is a named object that calls a method, and an event is an object which stores delegates.

When the event is generated, it calls all of its delegates in turn. A delegate can be considered, then, a named method of an instance.

Delegates that you explicitly create are generally used for objects that are created in script (that is, not by tags), although delegates can be associated with tag-generated objects as well.

Delegates are necessary because sometimes you don't know, at compile time, what a particular event should do. For example, say you have a window, and you want a certain method to be called every time the window is clicked. In that case, you would use a tag such as <window onclick="clickhandler()">. However, there may exist times when the desired action for the event depends on conditions at the time the event is created. In that situation you would use delegates.

LzDelegate(object, method, sender, event)

 var del = new LzDelegate(object, method, sender, event); 

 var del = new LzDelegate(object, method); 
 del.register(sender, event);

    <handler name="eventName" reference="eventSender">
       ...what to do...
    </handler>

     <method name="methodName">
       ...what to do...
     </method>

     <method name="createDelegate>
     this.myDel = new LzDelegate(this, "methodName", eventSender, "eventName");
     </method>

onclick="do something or other"; 

 <handler name="onclick" > 
 do something or other; 
 </name> 

 // make up a unique method name 
 var uid = $m + <unique id> 
 // make a method of that name to run the onclick code 
 this.$m = function () { ; }; 
 // make a delegate for that method 
 var del = new LzDelegate(this, $m); 
 // register it to receive onclick events 
 del.register(this, 'onclick'); 

1.3.  Example: using LzDelegate to register an event at runtime

The following example is a simple memory game. When a button is clicked once, nothing special is reported. If a button is clicked a second time, the green status bar reports a message stating this fact. The game can be started over by clicking the 'start over' button.

Notice that for each button, when the onclick event is fired, the regbutton() method is invoked on the canvas. The regbutton() method creates a delegate for the buttonclickedagain() method if no such delegate already exists, and then registers the 'onclick' event of the button that has just been clicked.

1.3.1. Flow of control

If a button that hasn't been clicked before is clicked, nothing special is reported (although the delegate is created). However, when a previously clicked button is clicked, the delegate calls buttonclickedagain() which prints the message stating this fact. This is because buttons that have already been clicked have had their 'onclick' events 'registered with' (or bound to) the delegate.

Clicking on the 'start over' button unregisters all events from the delegate, and resets the message to nothing special.

Example 30.1. Registering an event at runtime

<canvas height="100"> 
    <view width="80"> 
        <button width="20" height="20" onclick="canvas.regbutton(this)" onmousedown="canvas.reset()"/>
        <button width="20" height="20" onclick="canvas.regbutton(this)" onmousedown="canvas.reset()"/>
        <button width="20" height="20" onclick="canvas.regbutton(this)" onmousedown="canvas.reset()"/>
        <button width="20" height="20" onclick="canvas.regbutton(this)" onmousedown="canvas.reset()"/>
        <button width="20" height="20" onclick="canvas.regbutton(this)" onmousedown="canvas.reset()"/>
        <button width="20" height="20" onclick="canvas.regbutton(this)" onmousedown="canvas.reset()"/>
        <button width="20" height="20" onclick="canvas.regbutton(this)" onmousedown="canvas.reset()"/>
        <button width="20" height="20" onclick="canvas.regbutton(this)" onmousedown="canvas.reset()"/>
        <button width="20" height="20" onclick="canvas.regbutton(this)" onmousedown="canvas.reset()"/>
        <wrappinglayout/>
    </view> 
    <text id="statusText" bgcolor="green" resize="true"/> 
    <button text="start over" onclick="canvas.startover()"/>
    <simplelayout axis="y"/>

    <method name="regbutton" args="b"> 
        if( typeof this.del == "undefined" )  {
            this.del = new LzDelegate( this, "buttonclickedagain" ); 
        }      

        this.del.register( b, "onclick" );
    </method> 

    <method name="startover">
        this.del.unregisterAll(); 
        this.reset();
    </method>

    <method name="reset"> 
        statusText.setAttribute("text", "Nothing special");
    </method> 

    <method name="buttonclickedagain"> 
        statusText.setAttribute("text", "That button was clicked two or more times");
    </method> 
</canvas>

When you destroy an object--for example, a view -- you free up the memory that was used to store it. However, destroying the view does not destroy the delegates associated with it. You should "clean up" the delegate manually to free up the memory used by it.

<class ...>
   <method name="doit"> ... </method>

   <method name="init">
     super.init();
     this.myDel = new LzDelegate(this, 'doit', libraryName, 'onload');
   </method>
<!--
Be sure to clean up your delegate manually, if you destroy
instances, or the application will "leak" memory:-->

   <method name="destroy">
     this.myDel.unregisterAll();  // "destroys" delegates
     super.destroy();
   </method>

</class>

In the following example, a visual timer is created which shows each passing second. When the <text> node is initialized, we call the updateTimer() method. updateTimer() first updates the text showing to indicate the number of seconds passed, and then increments the secondsPassed attribute. The first time updateTimer() is invoked, a new delegate is created which simply calls updateTimer(), and a timer is created which in turn calls the newly created delegate after 1 second. Each subsequent time updateTimer() is invoked by the delegate, instead of creating a new timer (which would be inefficient) , LzTimer.resetTimer() is invoked.

Example 30.3. Using LzTimer to created a second timer

<canvas height="20"> 
    <text oninit="updateTimer()">
        <attribute name="secondsPassed" type="number" value="0"/> 

        <method name="updateTimer">
            this.setAttribute('text', this.secondsPassed );
            this.secondsPassed++; 

            if( typeof this.del == "undefined" ) { 
                this.del = new LzDelegate( this, "updateTimer" );
                LzTimer.addTimer( this.del, 1000 );
            } else {
                LzTimer.resetTimer( this.del, 1000 );
            }
        </method>
    </text> 
</canvas>

In the following example, when the last <text> object has been replicated and initialized, we set the text in the green <text> to 'The last view has been replicated'. To accomplish this task, we first explicitly declare a datapath on the <text> to be replicated. Next, we handle the onclones event, which indicates that the new <text> nodes has been cloned, but not initialized. Inside the onclones event, we determine the last replicated clone, and register the oninit event using LzDelegate. When the last <text> node has been initialized, the delegate calls the "replicationComplete" method, where the text of the green <text> node is updated.

This technique can also be used to detect when the last view has loaded its resource by simply registering the onload event instead of the oninit event.

Example 30.4. Registering an event for when the last view is replicated

<canvas height="125"> 
    <dataset name="people">
        <people> 
            <person name="John"/> 
            <person name="Eric"/> 
            <person name="Andrew"/> 
            <person name="chrisk"/> 
            <person name="Sarah"/> 
            <person name="Pablo"/> 
            <person name="Adam"/> 
        </people>
    </dataset> 

    <view>
        <text>
            <datapath xpath="people:/people/person/@name">
                <handler name="onclones">
                    var lastclone = this.clones[ this.clones.length - 1 ];

                    if( typeof this.del == "undefined" ) {
                        this.del = new LzDelegate( this, "replicationComplete") 
                    } else {
                        this.del.ungregisterAll();
                    }

                    this.del.register( lastclone, "oninit"); 
                </handler>

                <method name="replicationComplete">
                    lastRepText.setText("The last view has been replicated"); 
                </method>
            </datapath>
        </text>
        <simplelayout axis="y"/>
    </view>

    <text id="lastRepText" bgcolor="green" resize="true"> 
        Replication incomplete
    </text>
   
    <simplelayout axis="y"/> 
</canvas> 

A delegate is an object, and as such it can be an attribute of another object. For example, consider:

<button text="clickme">
    <attribute name="mydel" type="expression"
               value="$once{new LzDelegate(this, 'handler')}"

The above code creates the delegate mydel when the button is instantiated. This technique of declaring a delegate has the advantage of being easy to read, and it ensures that only one delegate is created.

For an example that uses this technique, see the "Using delegates as attributes"example in Chapter 44, OpenLaszlo RPC.

Here is a brief discussion of delegates in relation to other programming languages with which you may be familiar. You don't need to follow this discussion in order to use delegates in LZX.

A delegate is a 'method pointer'. It's a way of saying: "give me a thing that when I call it will call method m on object o." (As opposed to a function pointer, which doesn't capture the object.) In Java, you use an 'anonymous inner class' to get this effect (i.e., Java creates an instance with a function). In Lisp, you use a closure (i.e., Lisp creates a function with a context). [The Java and Lisp ways are just two sides of the same coin.]

Basically:

 // constructor 
 LzDelegate = function(o, m) { this.o = o; this.m = m; } 
 LzDelegate.prototype.execute = function () { with (this) { return o[m](); } }; 

 var del = new LzDelegate(object, 'method'); 
 del.execute(); 

is the same as:

 // constructor 
 function makeDelegate (o, m) { return function () { return o[m](); }; }; 

 var del = makeDelegate(object, 'method'); 
 del(); 

Here you can see the parallel between allocating an instance that captures the context 'o' and 'm' and has a function (method) to invoke it, and a function that you can invoke that captures the context 'o' and 'm' by being a closure.