Listen to Events with onEvent() Functions

Listen to Events with `onEvent()` Functions

The event system in ActionScript 3.0 is very powerful, but setting up simple listeners requires a lot more code (and classe names to remember) than it did in AS2. SimpleAS3 uses the native event system in AS3, but presents it in a way that is easier to use for most daily tasks.

Events can be received through a set of simple functions whose names start with on and end with the event type. For instance, any display object that allows mouse interaction now has functions like onClick(), onRollOver(), and onRollOut() (among many others). The Loader and URLLoader classes have functions like onComplete() and onIoError(). For any event, you can simply capitalize the first letter of the event type String and put "on" before it to create the event listener function name. The event type "complete" becomes "onComplete".

To set up the event listener, you only need to pass the listener function to the appropriate onEvent function. Let's look at some examples to help make it clear.

Usage Examples

The simplest thing you can do is set up a mouse click handler that loads a webpage in a new window. In this example, we've simply written the function right inside the onClick() call. That's not required, but it's a useful shortcut for events you don't ever plan to remove.

button.onClick(function()
{
	getURL( "http://www.example.com/", "_blank" );
});

That's an extremely basic task, and event handling can certainly be more complicated. You'll notice in the example above that we ignored the event parameter that gets passed to listeners in standard AS3. It's still there, but the looser syntax requirements of SimpleAS3 allow us to ignore function parameters if we don't need them. In the next example, we keep the event object intact so that we can access its properties in the listener function.

var loader = new URLLoader();
loader.onProgress(function( event )
{
	var percentage = (event.bytesLoaded / event.bytesTotal) * 100;
});

This example uses properties from the ProgressEvent object to calculate the percentage of a file that has been loaded using the URLLoader.

In the previous two examples, the event handler was placed directly into the onEvent function call. These are called anonymous functions and they can help to keep event handler code compact. However, sometimes you will want to write your handler function outside the onEvent function call. That's perfectly acceptable. The next example has the same behavior as the previous example, except the handler function is placed outside the onProgress() function call.

var loader:URLLoader = new URLLoader();
loader.onProgress( loaderProgressHandler );

function loaderProgressHandler( event:ProgressEvent ):void
{
	var percentage:Number = (event.bytesLoaded / event.bytesTotal) * 100;
}

You'll also notice that this example includes typing information for all variables, but the first version did not. Variable types are completely optional in SimpleAS3, but they can make code easier to understand.

Important Note about `onEvent` Functions

The onEvent methods are only available for events that are native to Flash Player. If the event is defined by a class in the flash.events.* package, it will be available though an onEvent function. In any other package, you'll need to initialize the event yourself.

For instance, any class that uses the "click" event type from flash.events.MouseEvent will have an onClick() function. However, if you create a custom event type "somethingHappened" on your class com.example.events.MyCustomEvent, no class will automatically define an onSomethingHappened() method.

See Create Custom onEvent() Functions for more information about how you can add a new onEvent() method with one function call.

Return to Documentation

simpleas3 documentation