This chapter is from the book
This chapter is from the book
This chapter is from the book
Handling Events
Another basic idea you'll need to grasp to create many AIR applications is how to handle an event. If you've worked with JavaScript even a little, you probably already have a sense of this. In the Web browser, an event might be when the cursor moves over an item (like an image or a link) or when a form is submitted. In AIR, you can still use JavaScript events, like calling a function when a button is clicked:
<input type="button" value="Click This!" onclick="callThisFunction()">
Continuing to use this kind of event handling is fine for basic JavaScript stuff. Unfortunately, this method won't work for Flash and AIR API events (things that happen within window.runtime as opposed to document).
Handling so-called runtime events is a two-step process:
- Create a function that will handle the event
- Indicate for what event the function should be called
For the first step, define a function that does whatever should be done. The particulars will vary according to the event being handled: If the event is a window closing, the function would do X; if it's the user going offline, the function would do Y. In every case, you'll want to write this function so that it takes one argument, which will be an event object:
function someFunction(event) {
// Code.
}
For the second step, you'll use the addEventListener() method applied to a corresponding object. Its first argument is the type of event that should be monitored. The event type will be a constant: a static value associated with a name (normally written in all capital letters) that has special meaning. The addEventListener() method takes a second argument, the name of the function to be called when that event occurs
As a concrete example of this, say you write a program that should do something special when it's activated. "Activated" means that the application is already open, the user switches to another application, and then returns to—activates—this one. That particular event is represented by the constant air.Event.ACTIVATE (or written without the AIRAliases.js alias, window.runtime.flash.events.Event.ACTIVATE).
Along with knowing the event to watch for, the function to be called must be defined:
function nowActive(event) {
alert('This is now the active program.');
}
Finally, you need to call the addEvent-Listener() for the proper object. In this example, the object is the application itself, accessed via air.NativeApplication.nativeApplication. The final code is therefore:
air.NativeApplication.nativeApplication.addEventListener(air.Event.ACTIVATE, nowActive);
In this code, note that the second argument is the name of the function to be called without parentheses or quotation marks.
To hammer this point home, let's run through another example. In it, an event listener will be created that reports what file a user selected (Figure 4.8). This uses some code you haven't seen before (which will be covered in more detail in Chapter 9, "Files and Directories") but will still be easy enough to follow.
)
Figure 4.8 This AIR application simply reports back to the user which file the user selected.
To create an event handler:
Begin a new AIR project in your text editor or IDE.
Make sure that you include the AIRAliases.js file (described earlier in this chapter), because shortcuts defined in it will be used by this program.
- Within a JavaScript block, define an object of File type (Script 4.2):
var file = new air.File();
Script 4.2. In this Adobe AIR program, the File class (part of the Flash API) is used to create a prompt for the user (see Figure 4.9) in which the user can select a file on the computer. The selected file's name and location is then repeated in a JavaScript dialog.
1 <html><!-- Script 4.2 --> 2 <head> 3 <script type="text/javascript" src="AIRAliases.js"></script> 4 <script type="text/javascript"> 5 6 // Create an object of File type: 7 var file = new air.File(); 8 9 // Add the event listener: 10 file.addEventListener(air.Event. SELECT, fileWasSelected); 11 12 // Create the Open prompt: 13 file.browseForOpen('Choose a file:'); 14 15 // Define a function that will be called when 16 // the event occurs: 17 function fileWasSelected(event) { 18 19 // Use an alert to print the selected file's name. 20 alert ('You selected: ' + file.nativePath); 21 22 } // End of fileWasSelected() function. 23 24 </script> 25 </head> 26 <body> 27 <h1>Handling Events</h1> 28 </body> 29 </html>
Figure 4.9 The Open dialog window allows the user to select a file on the computer.
The File class defines all the functionality necessary for dealing with files on the user's computer. To start, create an object of this type using the new keyword and the AIR alias.
- Add an event listener to the file selection event:
file.addEventListener(air.Event.SELECT, fileWasSelected);
This line adds an event listener to the file object. The specific event being watched for is air.Event.SELECT, which occurs when a user selects a file in a Open dialog window. When such an event occurs, the fileWasSelected() function will be called. It'll be written in step 5.
- Create the browse prompt:
file.browseForOpen('Choose a file:');Again, you haven't seen any of this file-related code before, but it shouldn't be too confusing. This line generates the dialog in which the user can select a file (Figure 4.9).
-
Define the fileWasSelected() function:
function fileWasSelected(event) { alert ('You selected: ' + file.nativePath); }This function states the full path to the file that was selected by the user (see Figure 4.8). It does so by referring to the nativePath() method of the file object.
Save, test, debug, and run the application.
Notice that the application does away with normal niceties and immediately prompts the user to select a file. Later in the book you'll see examples for doing this same thing more professionally.
)