Detecting events in ActionScript 3

Actionscript Course

Events are actions carried out in the Flash presentation by the user or by other elements from that prezentation.
For example, clicking or positioning the mouse over a Flash element, writing in a Text Input field, are events carried out by the user; and reaching a certain frame of an animation or finalizing an action are events carried out by elements in the presentation.
ActionScript 3 contains special objects and methods used to detect and recognise events, depending on these certain commands, different actions can be executed when those events occur.
Like most things in ActionScript 3, an event is considered an object, it has special properties and methods for working with events.
• In brief, an event works like this: the action tied to an element (called "event target") occurs (a pressed button, an animation, etc.) and transmits data to the script, in the form of an object (called "event object"). The script must contain a special function known as "event listener" , which detects the event and takes it's data and transmit it to a function that can perform different commands.
The function /method used in in ActionScript 3 to detect and capture events is "addEventListener()". It's a method from the "EventDispatcher" class, and it records in the script to detect the action on the element indicated by it.
The general syntax to use this method is:

event_target.addEventListener(EventObject.TYPE, aFunction);
function aFunction(ins_EventObject:EventObject):void
{
  // The code to execute

}

- "event_target" is the object at which the event occurs (it's instance name. For example, the instance name of a button that will be pressed).
- "EventObject" reprezente the cathegory of events that must be detected. It's also the object where information about the event that occured is stored (Ex., MouseEvent, TextEvent).
- "TYPE" is a constant that reprezents the type of event (such as: CLICK, MOUSE_OVER, COMPLETE) from the specified cathegory.
            - The "event_object.TYPE" specifies exactly the event that must be recognized. Ex., "MouseEvent:CLICK" is detected when somebody click's on the "event_target", or, "Event.COMPLETE" detects when an action is completed.
- "aFunction" is a function that is invoked when the event has occured, and the code in it will be executed.
- "ins_EventObject" is the instance of the "EventObject" object through which the data transmited in that object can be processed.

ActionScript 3 has a multitude of events that can be recognized, such as: MouseEvent (for mouse), KeyboardEvent (for keyboard), TextEvent (for text fields), ScrollEvent (for Scroll), IOErrorEvent (for cases when errors appear), and others. The list with all types of events, properties, methods and their constants can be found at AS3 Events.

Here's a practical example of using event detection. A content taken from an external TXT file will be displayed in a text field in the Flash presentation.

// Creating "event target"
// An instance of the  URLLoader object (used for loading data from a URL address
var urlLoader:URLLoader = new URLLoader();

// Applies the "load()" method (for loading) at the URLLoader instance
// creates a URLRequest instance used to specify the files address
urlLoader.load(new URLRequest("somefile.txt"));

// Set an "event listener", applied at "urlLoader", recognizes when the loading of the file has been completed
urlLoader.addEventListener(Event.COMPLETE, campTxt);

// Function that will be called by the event that was set-up
function campTxt(evt:Event):void
{
  // defines a TextField object instance to create a text field
  var camp_txt:TextField = new TextField();
  camp_txt.x = 78;                  // Distance from the left edge
  camp_txt.y = 75;                  // Distance from the top edge
  camp_txt.width = 145;             // Lenght of the text field
  camp_txt.height = 50;             // Height
  camp_txt.border = true;           // Activates to display the border

  // Adds data from the loaded file to the text field, stored in "evt"
  camp_txt.text = evt.target.data;

  addChild(camp_txt);        // Adds the text field in the flash presentation.
}

- First, an instance must be created using the "URLLoader" object, it is used to load the content from an external file. The URL loading adress must be added to this instance with the "URLRequest" object. Then the "addEventListener()" method is applied to the same instance and it's defined to recognize the "Event.COMPLETE" type of event (activated when a specific action is completed, here the loading).
- When the loading is completed, the event registered in that instance is activated, which detects completion of the loading process. Then it takes the data and transmits them at the "campText" function, this function retains the data in the "evt" parameter, creates a text field and with the "evt.target.data" expression it adds the data in the field and displays it in the Flash prezentation.
- See the explanations in the code.
Add this code in a new Flash document, make the SWF presentation (with Export) and in the same folder create a file with the name "somefile.txt" with some text in it. The result will be a flash presentation like this:

The file's URL address, added at "URLRequest("URL_fisier")", must be complete or relative to the Flash presentation, depending in which folder it's located.

Deleting event detection

To stop an "event listener" set up with "addEventListener()" from receiving notifications about the registered event, that record must be deleted, with the method "removeEventListener()" (belongs to the "EventDispatcher" class).
The general formula used for this method is:

event_target.removeEventListener(EventObject.TIP, aFunction);

- "event_target" represents the instance to which the event listener "addEventListener()" was applied, that must be deleted.
- "EventObject.TYPE" is the type of event.
- "aFunction" is a function that was set up to be called.

It is recommended to delete the record of an event's detection, when it is not needed in the program anymore, because it help freeing up used memory.
The event is permanently active and tied to the function that it calls (stored in memory) until it is deleted with "removeEventListener()".

Here's how the method must be applied to the previous example

// Creating "event target"
// An instance of the URLLoader object (for loading data from a URL address)
var urlLoader:URLLoader = new URLLoader( );

// Apply the "load()" method to the URLLoader instance
// create a URLRequest instance used to specify file address 
urlLoader.load(new URLRequest("somefile.txt"));

// Setting "event listener", to detect when the loading of a file has finished
urlLoader.addEventListener(Event.COMPLETE, campTxt);

// Function that will be called by the set event
function campTxt(evt:Event):void
{
  // defines a TextField object instance to create a text field
  var camp_txt:TextField = new TextField();
  camp_txt.x = 78;                 // Distance from the left edge
  camp_txt.y = 75;                  // Distance from the top edge
  camp_txt.width = 145;             // Lenght of the text field
  camp_txt.height = 50;             // Height
  camp_txt.border = true;           // Activates the display of a border

  // Adds data from the loaded file to the text field, stored in "evt"
  camp_txt.text = evt.target.data;

  addChild(camp_txt);        // Adds the text field in the flash presentation.

  // After the field is added to the presentation
  // Delete the record of the event's detection, to free up memory
  urlLoader.removeEventListener(Event.COMPLETE, campTxt);
}

- "urlLoader.removeEventListener(Event.COMPLETE, campTxt);" is added in the function "campTxt()" after the command which displays the text field with content loaded from the external file. This way, this command is executed after the event's role to take and display the loaded data ends, therefore it is no longer necessary to store it in memory.
- If this instruction would have been written outside the "campText()" function, it would have as effect the deletion of the event's detection before the function would have been called and would no longer be carried out because the event would not be detected.

The FLA file with this example can be downloaded from: Detecting events.

Priority of event capture

Normally if there are multiple event listeners registered at the same object (with equal or different types), the order of capture and triggering is the one in which they are written in the script. But this order can be changed, using a "priority parameter" in the "addEventListener()" method:

event_target.addEventListener(EventObject.TIP, oFunctie, useCapture, prioritate);

- for "useCapture" you put false
- "priority" is an integer number that is equal to or greater than zero, through which the execution priority is determined (default is 0). The event listener with greater priority is triggered before others.
For example, for the following 2 registered events:

urlLoader.addEventListener(Event.COMPLETE, aFunction, false, 0);
urlLoader.addEventListener(Event.COMPLETE, bFunction, false, 1);

- The event with priority 1 is executed first, which calls the "bFunction" function, and then it is executed the event with priority 0.

<ul>
 <li>http://coursesweb.net/html/</li>
 <li>http://coursesweb.net/css/</li>
</ul>

.some_class {
  display: list-item;
}

var obj = {
 "courses": ["php", "javascript", "ajax"]
};
var jsonstr = JSON.stringify(obj);
alert(jsonstr);    // {"courses":["php","javascript","ajax"]}

$strhtml = '<body><div id="dv1">CoursesWeb.net</div></body>';
$dochtml = new DOMDocument();
$dochtml->loadHTML($strhtml);
$elm = $dochtml->getElementById("dv1");
echo $elm->nodeValue;    // CoursesWeb.net