An
event-handling system allows programmers to respond to user input
and system events in a convenient way. The Adobe® AIR®
event model is not only convenient, but also standards-compliant.
Based on the Document Object Model (DOM) Level 3 Events Specification,
an industry-standard event-handling architecture, the event model
provides a powerful, yet intuitive, event-handling tool for programmers.

HTMLLoader events

An HTMLLoader object dispatches the following
Adobe® ActionScript® 3.0 events:

Event

Description

htmlDOMInitialize

Dispatched when the HTML document is created,
but before any scripts are parsed or DOM nodes are added to the
page.

complete

Dispatched when the HTML DOM has been created
in response to a load operation, immediately after the
onload
event
in the HTML page.

htmlBoundsChanged

Dispatched when one or both of the
contentWidth
and
contentHeight
properties
have changed.

locationChange

Dispatched when the location property of
the HTMLLoader has changed.

locationChanging

Dispatched before the location of the HTMLLoader
changes because of user navigation, a JavaScript call, or a redirect.
The
locationChanging
event is not dispatched when
you call the
load()
,
loadString()
,
reload()
,
historyGo()
,
historyForward()
,
or
historyBack()
methods.

If a link
is opened in the system browser, a locationChanging event is not
dispatched since the HTMLLoader does not change location.

scroll

Dispatched anytime the HTML engine changes
the scroll position. Scroll events can be because of navigation
to anchor links (
#
links) in the page or because
of calls to the
window.scrollTo()
method. Entering
text in a text input or text area can also cause a scroll event.

uncaughtScriptException

Dispatched when a JavaScript exception occurs
in the HTMLLoader and the exception is not caught in JavaScript
code.

Handling DOM events with ActionScript

You
can register ActionScript functions to respond to JavaScript events.
For example, consider the following HTML content:

<html>
<body>
<a href="#" id="testLink">Click me.</a>
</html>

You
can register an ActionScript function as a handler for any event
in the page. For example, the following code adds the
clickHandler()
function
as the listener for the
onclick
event of the
testLink
element
in the HTML page:

When
a listener refers to a specific DOM element, it is good practice
to wait for the parent HTMLLoader to dispatch the
complete
event
before adding the event listeners. HTML pages often load multiple
files and the HTML DOM is not fully built until all the files are
loaded and parsed. The HTMLLoader dispatches the
complete
event
when all elements have been created.

When
a JavaScript operation encounters an illegal operation that is not
caught in the JavaScript code with a
try
/
catch
structure, the
HTMLLoader object containing the page dispatches an HTMLUncaughtScriptExceptionEvent
event. You can register a handler for this event, as in the following
code:

The
htmlErrorHandler()
event
handler cancels the default behavior of the event (which is to send
the JavaScript error message to the AIR trace output), and generates
its own output message. It outputs the value of the
exceptionValue
of
the HTMLUncaughtScriptExceptionEvent object. It outputs the properties
of each object in the
stackTrace
array:

Handling runtime events with JavaScript

The
runtime classes support adding event handlers with the
addEventListener()
method.
To add a handler function for an event, call the
addEventListener()
method
of the object that dispatches the event, providing the event type
and the handling function. For example, to listen for the
closing
event
dispatched when a user clicks the window close button on the title
bar, use the following statement:

Creating an event handler function

The following code creates a simple HTML file that displays information
about the position of the main window. A handler function named
moveHandler()
, listens
for a move event (defined by the NativeWindowBoundsEvent class)
of the main window.

When a user moves the window, the textarea elements display the
updated X and Y positions of the window:

Notice that the event object is passed as an argument to the
moveHandler()
method.
The event parameter allows your handler function to examine the
event object. In this example, you use the event object's
type
property
to report that the event is a
move
event.

Removing event listeners

You
can use the
removeEventListener()
method to remove
an event listener that you no longer need. It is a good idea to
remove any listeners that will no longer be used. Required parameters
include the
eventName
and
listener
parameters,
which are the same as the required parameters for the
addEventListener()
method.

Removing event listeners in HTML pages that navigate

When
HTML content navigates, or when HTML content is discarded because
a window that contains it is closed, the event listeners that reference
objects on the unloaded page are not automatically removed. When
an object dispatches an event to a handler that has already been
unloaded, you see the following error message: “The application
attempted to reference a JavaScript object in an HTML page that
is no longer loaded.”

To avoid this error, remove JavaScript event listeners in an
HTML page before it goes away. In the case of page navigation (within
an HTMLLoader object), remove the event listener during the
unload
event
of the
window
object.

For example, the following JavaScript code removes an event listener
for an
uncaughtScriptException
event:

To prevent the error from occurring when closing windows that
contain HTML content, call a cleanup function in response to the
closing
event
of the NativeWindow object (
window.nativeWindow
).
For example, the following JavaScript code removes an event listener
for an
uncaughtScriptException
event:

You can also prevent this error from occurring by removing an
event listener as soon as it runs (if the event only needs to be
handled once). For example, the following JavaScript code creates
an html window by calling the
createRootWindow()
method
of the HTMLLoader class and adds an event listener for the
complete
event.
When the
complete
event handler is called, it removes
its own event listener using the
removeEventListener()
function: