Events

Events Model

Events are functions that are called when something happens. This is similar to UserEvents except regular Events are caused by the coder, not the user. Events notify someone when an array has been modified, when an element is collapsed, etc. The Event object keeps track of a list of functions and “delegates”. The functions are references to actual function calls. However, sometimes you need to pass in parameters and function calls alone are not enough. This is where delegates come into play.

Adding an event is just like adding an object to an array. Calling the Add function ad passing in a function reference or actual function. Examples are:

var a = [];

a.OnAdd.Add(AlertMe);
a.OnAdd.Add(function() {
    $Span("id").Text(a.length + " items");
}
 
function AlertMe(){
    alert("Something was added!");
}

An array is created and two functions are added. AlertMe is a reference to the AlertMe function and will be called first. Functions and delegates added to an event are called in the order they are added. The second function is an inline function. The function is anonymous and exists only as a parameter to the Add function for the OnAdd event. There will be no way to remove this function as there is no reference to it except to call the Clear() function on OnAdd.

 

"This" keyword

 The keyword this refers to the Owner of the Event object. Example:

$Anchor("id").OnClick.Add(test);

function test(){
    alert(this.Text());
}

Here, this refers to the Anchor with the id “id”. Delegates this keyword is defined by the delegate itself.

 

Adding and removing events

 Modifying an event involves the Add, Remove and Clear functions. For Add and Remove, passing a function reference, inline function or delegate is valid. When passing an inline function, there is no reference available that the programmer can access and thus, removing the function is impossible with a full Clear.

function func1(){
    this.OnMouseOver.Remove(func1); // once this is called, func1 is removed from the list and will no longer be called
}

function func2(){
}
 
function func3(){
}
 
$Span("id").OnMouseOver.Add(func1);
$Span("id").OnMouseOver.Add(func2);
$Span("id").OnMouseOver.Add(func3);

Calling Clear() will remove all functions and delegates from the list.

EventArgs parameter

For functions, a single parameter is passed to the function derived from EventArgs. EventArgs contains two fields, Sender and CancelEvent where as other EventArgs type objects (IterationEventArgs, KeyEventArgs, etc) may contain other information about the event. The Sender refers to the object that owns the event and originally executed the Fire function.  The information in EventArgs can be used to find the calling object.

$TextBox("name").OnBlur.Add(verifyText);
$TextBox("email").OnBlur.Add(verifyText);
$TextBox("phone").OnBlur.Add(verifyText);
 
function verifyText(e){
    if(e.Sender.Text().length == 0){  // Sender refers to $TextBox("id")
        alert("Please fill out all form fields!");
        e.Sender.Focus();
    }
}

EventArgs can also be used to cancel an event.

Page.Form.OnSubmit.Add(verifyFields);
function verifyFields(e){
    if($TextBox("id").Text().length == 0){
        e.CanceEvent = true;  // If the textbox is empty, the form will not submit
    }
}

 

UserEvents

UserEvent is a special kind of Event that represent user controlled events that are part of the normal HTML event model such as onclick, onmouseover and onblur. The UserEvent operates on the same premise of a normal Event with a few exceptions. First, any events defined in the attributes of a tag will be added to the event list first.

<a id="Anc1" onmouseover="Highlight(this)" onmouseout="Unhighlight(this)">Hi</a>
 
<script type="text/javascript">
    Page.OnLoad.Add(function() {
        $Anchor("Anc1").OnMouseOver.Add(BoldIt);
        $Anchor("Anc1").OnMouseOut.Add(UnboldIt);
    });
   
    function Highlight(e){
        e.ForegroundColor(Colors.Yellow);
    }
   
    function UnhighlightIt(e){
        e.ForegroundColor(Colors.Black);
    }
 
    function BoldIt(){
        this.Bold(true);
    }
 
    function Unboldit(){
        this.Bold(false);
    }
</script>

The Highlight and Unhighlight use traditional methods of attaching events where this does not refer to the element. BoldIt and UnboldIt use the AwesomeScript method. In the event model,  Highlight and Unhighlight will be called before BoldIt and UnboldIt

 

Awesome.Event

Awesome.Event is a global variable containing the current EventArgs for any event fired, this includes UserEvents. However, be careful about the timing of using this variable as another event may be called and override what the previous Awesome.Event contained. It's best practice to assign Awesome.Event to a local variable before using it.

Last edited Sep 19, 2011 at 12:55 PM by dahrkdaiz, version 15

Comments

No comments yet.