Triggering Scripts Using Component Events

Users can interact with components in many ways. Depending on the component, users can type text into the component, click the component, select an item, and more. As with any interactivity such as this, it's important for your application to react according to what the user is doing. For example, if the user clicks a radio button, you might want your application to react to that selection by updating a variable's value, or you may want to change the appearance of your application's interface. Fortunately, most components have several built-in events that can be used to trigger a script's execution, providing you with the flexibility to easily create highly interactive applications.

Similar to component properties, component events can be categorized into two groups: events that are common to most component instances, and events that are unique to each type of component.

Common Events

As mentioned in our discussion of properties, most components inherit from the UIObject and UIComponent classes. Not only do those classes define properties that are available to most component instances; they also specify a number of events that, as a result of inheritance, are available to all component instances. Some of these common events include (but are not limited to) the following:

move - triggered when a component instance's x or y coordinates change

focusIn - triggered when a user interacts with a component instance in any way

focusOut - triggered when a user leaves a component instance and interacts with something else

Later in this lesson, you'll see how these events are used.

Component-Specific Events

In addition to the common events just discussed, most components have events relating to their specific functionality. Let's look at a couple of simple examples.

Button and RadioButton component instances react to click events, in addition to the common events previously discussed. A click event is fired when a Button component instance is pressed and released, or when a RadioButton instance is selected. When you think about it, these are not complex components; having such a simple event associated with them makes sense.

A component such as a ComboBox is a totally different story because it's designed to be interacted with in many ways. ComboBox component instances react to the following events:

change - triggered when the user selects a new item within the combobox

close - triggered when the drop-down box within the combobox begins to close

open - triggered when the drop-down box within the combobox is opened

enter - triggered when the user presses Enter after entering a value into the combobox

scroll - triggered when the list of items within the combobox is scrolled

itemRollOver - triggered when the user rolls the mouse over a list item

itemRollOut - triggered when the user rolls the mouse away from a list item

With such a wide range of available events, component instances become powerful tools in the creation of your applications.

NOTE

There are too many component-specific events to list here. For a complete listing of the events of a component class, look up its entry in the ActionScript dictionary. Component-specific events can be found under each component listing in the Actions Toolbox section of the Actions panel.

Handling Events

There are a couple of ways to use component events in your scripts. You can use the on() handler, and you can also create Listener objects, as you learned about in Lesson 2, "Using Event Handlers." Let's first look at using the on() handler.

The on() handler allows you to script events directly on a component instance, much in the same way that you add scripts directly to button and movie clip instances. For example, if you select a ComboBox instance and open the Actions panel, you can attach the following script to that instance:

 on (open) {   trace("A ComboBox instance has been opened"); } on (scroll) {   trace("A ComboBox instance has been scrolled"); } 

If you use the term this in this type of script, it's a reference to the component instance to which the script is attached. Look at the following example:

 on (focusOut) {   this._alpha = 50; } 

Assuming that this script is attached to, say, a NumericStepper component instance, its transparency will be set to 50% when the focusOut event occurs.

The preferred way of handling component events is to use Listener objects. Let's convert our previous sample scripts to the Listener model syntax:

 var myComboBoxListener:Object = new Object(); myComboBoxListener.open = function(){   trace("A ComboBox instance has been opened"); } myComboBoxListener.scroll = function(){   trace("A ComboBox instance has been scrolled"); } 

These several lines of code create an object named myComboBoxListener and then script it to react to the open and scroll events. Now we have to register this Listener object with a particular ComboBox component instance. If we have a ComboBox instance named myCB_cb, the syntax would look similar to the following:

 myCB_cb.addEventListener("open", myComboBoxListener); myCB_cb.addEventListener("scroll", myComboBoxListener); 

When myCB_cb is opened or scrolled, the open or scroll function of our Listener object is fired.

NOTE

A single Listener object can be registered to listen to any number of component instance events.

Another way of scripting for component events involves using functions as Listeners. For example, suppose you've created the following function:

 function myFunction(eventObj:Object){   trace ("I'm a Listener too!"); } 

You could script this function to be called whenever a particular event was fired by a particular component instance:

 myCB_cb.addEventListener("open", myFunction); 

Whenever the myCB_cb component instance triggers an open event, myFunction() is called, and thus executed.

As mentioned in the discussion of the on() handler, use of the term this in either Listener object syntax or the syntax of functions that are used as Listener objects is a reference to the component instance that triggers the event.

You probably noticed within the parentheses of the myFunction Listener example the use of the syntax eventObj:Object.

When you use a Listener object or a function as a Listener, an Event object is passed to the specified handler script. This object usually contains two properties: type and target. The type property is a string reference to the event that was triggered; the target is a string reference to the target path of the component instance that fired the event. Using our previous ComboBox example, here's how an Event object is used.

Let's say we've defined a Listener function and registered it to listen for open events triggered by myCB_cb, as shown here:

 function myFunction(eventObj:Object){   trace(eventObj.target);   trace(eventObj.type); } myCB_cb.addEventListener("open", myFunction); 

If the myCB_cb instance triggers an open event, the Output panel will open and display the following:

 _level0.myCB_cb open 

Information provided by the Event object can be used in a conditional statement within the function to take appropriate action, depending on the event that has been triggered and the instance that triggered it, as the following example shows:

 function myFunction(eventObj:Object){   if(eventObj.target == "_level0.myCB_cb"){     //actions   }else if(eventObj.name == "_level0.myRadioButton_rb"){     //actions   }   if(eventObj.type == "click"){     //actions   } } 

As you can see, using the properties of the Event object allows you to set up a single function to handle several events from several different component instances.

NOTE

Some components, such as the MenuBar component, generate Event objects containing properties in addition to target and name. We'll discuss some of these properties in later lessons.

In the following exercise, we'll create several Listener objects and script them to listen to various events that are triggered by components in our project.

1. Open Components2.fla.

   This project continues from where we left off in the preceding exercise.

   We'll add all the scripts for this exercise to Frame 1 of the timeline. The focus for this exercise is to create the framework for using component events via Listener objects. The Listener objects won't actually be scripted to do anything until the next exercise.
   
   

2. With the Actions panel open and Frame 1 selected, add the following script at the end of the current script:

    var inputURL_tiListener:Object = new Object (); inputURL_tiListener.focusIn = function () { }; inputURL_ti.addEventListener ("focusIn", inputURL_tiListener); 

   
   

   The first line of this script creates an object named inputURL_tiListener. We'll use this object to listen for events generated by the TextInput component instance named inputURL_ti, which will be used in the application as an input field for new URLs.

   The next two lines of script create a handler for the focusIn event. This handler will be scripted in the next exercise.

   The last line of the script in this step registers the Listener object with the inputURL_ti instance. Anytime this instance generates the focusIn event, our Listener object will be notified and will execute its handler for that event.
   
   

3. Add the following script at the end of the current script:

    var addURL_pbListener:Object = new Object (); addURL_pbListener.click = function () { }; addURL_pb.addEventListener ("click", addURL_pbListener); 

   
   This script creates a Listener object for the addURL_pb PushButton component instance, and sets it up to listen for any click events generated by that instance. The Listener object is registered with the addURL_pb instance.
   
   

4. Add the following script at the end of the current script:

    var listURL_lbListener:Object = new Object (); listURL_lbListener.focusIn = function () { }; listURL_lb.addEventListener ("focusIn", listURL_lbListener); var openURL_pbListener:Object = new Object (); openURL_pbListener.click = function () { }; openURL_pb.addEventListener ("click", openURL_pbListener); var deleteURL_pbListener:Object = new Object (); deleteURL_pbListener.click = function () { }; deleteURL_pb.addEventListener ("click", deleteURL_pbListener); 

   
   

   

   This creates three more Listener objects, which are registered to the listURL_lb, openURL_pb, and deleteURL_pb instances, respectively. Make a note of the events the objects are set up to handle, because these are important for the next exercise.
   
   

5. Save this file as Components3.fla.

   In this exercise, we created five Listener objects and registered them to listen for events generated by various component instances in our project. At this point, the event handlers attached to our Listener objects are not scripted to do anything, but we'll take of that in the next exercise.