|
|
Because of the differences of the security models between content running within the browser, and content running within Adobe AIR, most JavaScript frameworks must explicitly add support for Adobe AIR in order for them to running correctly within an Adobe AIR application.
At the time that the book was authored, all major JavaScript frameworks have added (or are adding) support for Adobe AIR.
Dojo Toolkit 1.1.0 Beta
Ext JS 2.0.2 with Adobe AIR Adapter
jQuery 1.2.3
YUI 2.5.1
MooTools 1.11
FCKeditor 2.6.0 Beta
MochiKit 1.3.1
Spry Prerelease 1.6.1
For a complete and up to date list of frameworks that support Adobe AIR please check the AIR product page http://www.adobe.com/products/air/ or the AIR Developer Center for Ajax: http://www.adobe.com/devnet/air/ajax/.
In addition to the standard JavaScript and HTML DOM APIs, JavaScript code running within the application sandbox in an AIR application can also take advantage of APIs provided by the runtime, as well as Flash Player APIs and even ActionScript 3 libraries. This greatly extends the capabilities of JavaScript over the APIs available in the browser, and includes functionality such as:
Playing sounds
Manipulating images and bitmaps
Access to a relational local database
Creating, controlling and manipulating native windows
Creating and working with native menus
Making direct socket connections (both binary and text based)
Network detection
Accessing the clipboard
Dragging data between AIR applications and OS or another application
This section discusses how to leverage AIR and Flash Player APIs from JavaScript, as well as how to load and leverage compiled ActionScript libraries from within JavaScript.
The following diagram shows the relationship between the two environments.
Only a single native window is shown but an AIR application can contain multiple windows. Also, a single window can contain multiple HTMLLoader objects.
The JavaScript environment has its own document and window objects. JavaScript code can interact with the AIR runtime environment through the runtime, nativeWindow, and htmlLoader properties of window.
The runtime property provides access to AIR API classes; it allows you to create new AIR objects as well as access static members.
The nativeWindow gives you access to the current instance of the NativeWindow that controls the current application window.
The htmlLoader gives you access to the current instance of the HTMLLoader that controls how content is loaded and rendered.
ActionScript code can interact with the JavaScript environment through the window property of an HTMLLoader object, which is a reference to the JavaScript window object.
In addition, both ActionScript and JavaScript objects can listen for events dispatched by both AIR and JavaScript objects.
There is also another important object instance available in any AIR application that is not shown in the diagram. The NativeApplication object provides information about the application state, dispatches several important application-level events, and provides useful functions for controlling application behavior. A single instance of the NativeApplication object is created automatically and can be accessed through the class-defined NativeApplication.nativeApplication property.
To access the object from JavaScript code you could use:
var app = window.runtime.flash.desktop.NativeApplication. nativeApplication;
Most AIR and Flash Player APIs are contained within packages (similar to how many Ajax frameworks leverage namespaces and packages). This helps organize the APIs, and also reduces the possibility of naming conflicts. When accessing AIR and Flash Player APIs directly from JavaScript, you must do so via their complete package path and name.
As discussed earlier, all AIR and Flash Player APIs are made available via the window.runtime property. The runtime property is at the root of the runtime environment, and all APIs are relative to this root.
For example, to access an API which is not contained within a package, such as trace you reference it directly from the runtime property, like so:
window.runtime.trace("foo");
However, if you want to access an API that is contained within a package, you must prepend the package path to the API. For example, to access the amount of memory currently used by the application, you can call the totalMemory Flash Player property that is in the flash.system.System class. To call this API from JavaScript:
var mem = window.runtime.flash.system.System.totalMemory;
This also applies when creating new instances of an API class from within JavaScript:
var file = new window.runtime.flash.filesystem.File();
This code creates a new File instance that can be used to work with the file system.
Here is a complete example that shows how to write a file named output.txt to the user's desktop:
//call a static property
var desktop = window.runtime.flash.filesystem.File.desktop
Directory;
//call a function on an instance of a class
var file = desktop.resolvePath("output.txt");
//create a new instance of a class using new
var fileStream = new window.runtime.flash.filesystem.
FileStream();
//call a function, passing arguments
fileStream.open(file, window.runtime.flash.filesystem.
FileMode.WRITE);
fileStream.writeUTFBytes("Hello World");
fileStream.close();
Don't worry too much about what the code is doing in this example, but rather focus on how the AIR APIs are called from JavaScript.
This allows you to leverage virtually any AIR or Flash Player API from within JavaScript.
By remembering how to use the package structure to call APIs, you can leverage all AIR, Flash Player and ActionScript APIs even if JavaScript-specific documentation is not provided.
Many of the AIR and Flash Player APIs make extensive use of events. Event handling in ActionScript-based APIs is based on the W3C DOM Level 3 event model. This is similar to the W3C DOM Level 2 event model available within JavaScript, but is very different from the callback mechanism often deployed in JavaScript.
In order to be notified when an event from an AIR or Flash Player API occurs, you must register to listen for it. The best way to understand this is to look at an example. The following example registers for a NETWORK_CHANGE event that is broadcast by the NativeApplication instance:
function onNetworkChange(event)
{
runtime.trace("Network status changed");
}
function onAppLoad()
{
window.runtime.flash.desktop.NativeApplication.
nativeApplication.addEventListener(
window.runtime.flash.events.Event.
NETWORK_CHANGE,
onNetworkChange);
}
As you can see from the example, you register for events broadcast by a class instance by calling the addEventListener function on the class instance. This API requires two arguments.
The first argument is the event name of the event being broadcast. For all AIR and Flash Player APIs, there will be a constant for the event name, which you can find in the documentation.
The second argument is a reference to the function that will handle the event. In this case, the function is named onNetworkChange. Looking at the function, you can see that it is passed an argument with information about the event. Again, all AIR and Flash Player APIs will pass an object to the event handler function, which provides information about the event. You can find the exact type of event object passed to the handler, and the information it provides, by referencing the API documentation.
As the previous examples show, being able to leverage AIR and Flash Player APIs from directly within JavaScript can be very powerful. However, because you must reference the APIs via the runtime property and the complete API package path, it can lead to very verbose code.
In order to make it easier to use some of the more common AIR and Flash Player APIs from within JavaScript, Adobe has created a JavaScript include file, named AIRAliases.js. This file, which can be found in the frameworks directory of the SDK, provides aliases for commonly used APIs to make them more convenient to use from within JavaScript.
To use the aliases file, copy it from the SDK to your application directory (make sure to also package it in your AIR file). You then include it within your application using the script tag in each HTML document that you want to leverage the aliases in.
For example, let's look at the earlier example that writes a file to the desktop, but uses the JavaScript aliases provided in the AIRAliases.js file instead of typing out the complete package paths:
<script src="airaliases.js" type="text/javascript"></script>
<script type="text/javascript">
function writeFile()
{
var desktop = air.File.desktopDirectory;
var file = desktop.resolvePath("output.txt");
var fileStream = new air.FileStream();
fileStream.open(file, air.FileMode.WRITE);
fileStream.writeUTFBytes("Hello World");
fileStream.close();
}
</script>
First, notice that the code is much less verbose. This is because instead of having to reference APIs via window.runtime and then the complete package path, we can use the aliases within the include file.
For example, this reduces:
var desktop = window.runtime.flash.filesystem.File. desktopDirectory;
to:
var desktop = air.File.desktopDirectory;
Second, the AIR and Flash Player APIs are placed in a namespace called air. If you open the AIRAliases.js file, you can see how the aliases actually work. For example, here is the code that sets up the File API aliases:
var air; if (!air) air = {};
// file
air.File = window.runtime.flash.filesystem.File;
air.FileStream = window.runtime.flash.filesystem.FileStream;
air.FileMode = window.runtime.flash.filesystem.FileMode;
To see a complete list of APIs included, open up the AIRAliases.js file with a text editor. While not all APIs are included, you can easily add additional APIs by following the existing examples in the file.
Not only can AIR applications leverage Flash Player APIs directly from JavaScript, they can also access compiled ActionScript 3 libraries from within JavaScript.
In addition to loading external JavaScript files, the HTML script tag within an AIR application also has support for loading compiled ActionScript 3 libraries and providing access to the ActionScript classes included within the file. Once the SWF is loaded, the APIs can be referenced in the same manner as the AIR and Flash Player APIs are referenced via the API package path and API name.
NOTE
This technique works only with ActionScript 3 libraries.
Let's look at an example. Included in the Adobe AIR SDK is a SWF that contains the ActionScript 3 Adobe AIR service connectivity API. While this example won't show how to use that API, it will show how to access those APIs from within JavaScript.
In order for the example to work, you must copy the frameworks/servicemonitor.swf file from the AIR SDK to your application directory.
Any classes and APIs available within the compiled SWF will be made available via the window.runtime property. The API we want to reference is in a class named ServiceMonitor in the air.net package.
Here's the code:
<script src="servicemonitor.swf" type="application/x-
shockwave-flash"></script>
<script type="text/javascript">
function onAppLoad()
{
var monitor = new runtime.air.net.ServiceMonitor();
}
</script>
If AIRAliases.js is included in the page you can use the short version:
var monitor = new air.ServiceMonitor();
This is a very simple example that shows how to load compiled ActionScript libraries, and then access them from JavaScript. In this case, we include the servicemonitor.swf file via the HTML script tag using the special type "application/x-shockwave-flash". This file contains the compiled ActionScript 3 APIs for the air.net.ServiceMonitor class.
Using this technique allows you to leverage third party ActionScript APIs from within AIR applications via JavaScript.
NOTE
Most ActionScript 3 libraries are distributed as zip-based SWC files. In order to use the libraries within JavaScript, change the extension of the library from SWC to ZIP, unzip them using a zip program, and then remove the library's SWF file contained within the SWC.
You can then include the SWF within your application in the same manner as demonstrated earlier.
|
|