";
The regular expression matches the entire string:
Paragraph 1
Paragraph 2
Suppose, however, that you want to match only one
...
grouping. You can do this with the following:
Paragraph 1
Add a question mark (?) after any quantifier to change it to what is known as a lazy quantifier. For example, the
following regular expression, which uses the lazy *? quantifier, matches
followed by the minimum number of
characters possible (lazy), followed by
:
/
.*?<\/p>/
Keep in mind the following points about quantifiers:
• The quantifiers {0} and {0,0} do not exclude an item from a match.
• Do not combine multiple quantifiers, as in /abc+*/.
• The dot (.) does not span lines unless the s (dotall) flag is set, even if it is followed by a * quantifier. For example,
consider the following code:
var str:String = "
Test\n";
str += "Multiline
";
var re:RegExp = /
.*<\/p>/;
trace(str.match(re)); // null;
re = /
.*<\/p>/s;
trace(str.match(re));
// output:
Test
//
Multiline
For more information, see “Flags and properties” on page 87.
Alternation
Flash Player 9 and later, Adobe AIR 1.0 and later
Use the | (pipe) character in a regular expression to have the regular expression engine consider alternatives for a
match. For example, the following regular expression matches any one of the words cat, dog, pig, rat:
Last updated 3/21/2011
84
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Using regular expressions
var pattern:RegExp = /cat|dog|pig|rat/;
You can use parentheses to define groups to restrict the scope of the | alternator. The following regular expression
matches cat followed by nap or nip:
var pattern:RegExp = /cat(nap|nip)/;
For more information, see “Groups” on page 84.
The following two regular expressions, one using the | alternator, the other using a character class (defined with [ and
] ), are equivalent:
/1|3|5|7|9/
/[13579]/
For more information, see “Character classes” on page 81.
Groups
Flash Player 9 and later, Adobe AIR 1.0 and later
You can specify a group in a regular expression by using parentheses, as follows:
/class-(\d*)/
A group is a subsection of a pattern. You can use groups to do the following things:
• Apply a quantifier to more than one character.
• Delineate subpatterns to be applied with alternation (by using the | character).
• Capture substring matches (for example, by using \1 in a regular expression to match a previously matched group,
or by using $1 similarly in the replace() method of the String class).
The following sections provide details on these uses of groups.
Using groups with quantifiers
If you do not use a group, a quantifier applies to the character or character class that precedes it, as the following shows:
var pattern:RegExp = /ab*/ ;
// matches the character a followed by
// zero or more occurrences of the character b
pattern = /a\d+/;
// matches the character a followed by
// one or more digits
pattern = /a[123]{1,3}/;
// matches the character a followed by
// one to three occurrences of either 1, 2, or 3
However, you can use a group to apply a quantifier to more than one character or character class:
Last updated 3/21/2011
85
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Using regular expressions
var pattern:RegExp = /(ab)*/;
// matches zero or more occurrences of the character a
// followed by the character b, such as ababab
pattern = /(a\d)+/;
// matches one or more occurrences of the character a followed by
// a digit, such as a1a5a8a3
pattern = /(spam ){1,3}/;
// matches 1 to 3 occurrences of the word spam followed by a space
For more information on quantifiers, see “Quantifiers” on page 82.
Using groups with the alternator (|) character
You can use groups to define the group of characters to which you want to apply an alternator (|) character, as follows:
var pattern:RegExp = /cat|dog/;
// matches cat or dog
pattern = /ca(t|d)og/;
// matches catog or cadog
Using groups to capture substring matches
When you define a standard parenthetical group in a pattern, you can later refer to it in the regular expression. This is
known as a backreference, and these sorts of groups are known as capturing groups. For example, in the following
regular expression, the sequence \1 matches whatever substring matched the capturing parenthetical group:
var pattern:RegExp = /(\d+)-by-\1/;
// matches the following: 48-by-48
You can specify up to 99 of these backreferences in a regular expression by typing \1, \2, ... , \99.
Similarly, in the replace() method of the String class, you can use $1$99– to insert captured group substring matches
in the replacement string:
var pattern:RegExp = /Hi, (\w+)\./;
var str:String = "Hi, Bob.";
trace(str.replace(pattern, "$1, hello."));
// output: Bob, hello.
Also, if you use capturing groups, the exec() method of the RegExp class and the match() method of the String class
return substrings that match the capturing groups:
var pattern:RegExp = /(\w+)@(\w+).(\w+)/;
var str:String = "bob@example.com";
trace(pattern.exec(str));
// bob@example.com,bob,example,com
Using noncapturing groups and lookahead groups
A noncapturing group is one that is used for grouping only; it is not “collected,” and it does not match numbered
backreferences. Use (?: and ) to define noncapturing groups, as follows:
var pattern = /(?:com|org|net);
For example, note the difference between putting (com|org) in a capturing versus a noncapturing group (the exec()
method lists capturing groups after the complete match):
Last updated 3/21/2011
86
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Using regular expressions
var pattern:RegExp = /(\w+)@(\w+).(com|org)/;
var str:String = "bob@example.com";
trace(pattern.exec(str));
// bob@example.com,bob,example,com
//noncapturing:
var pattern:RegExp = /(\w+)@(\w+).(?:com|org)/;
var str:String = "bob@example.com";
trace(pattern.exec(str));
// bob@example.com,bob,example
A special type of noncapturing group is the lookahead group, of which there are two types: the positive lookahead group
and the negative lookahead group.
Use (?= and ) to define a positive lookahead group, which specifies that the subpattern in the group must match at the
position. However, the portion of the string that matches the positive lookahead group can match remaining patterns
in the regular expression. For example, because (?=e) is a positive lookahead group in the following code, the
character e that it matches can be matched by a subsequent part of the regular expression—in this case, the capturing
group, \w*):
var pattern:RegExp = /sh(?=e)(\w*)/i;
var str:String = "Shelly sells seashells by the seashore";
trace(pattern.exec(str));
// Shelly,elly
Use (?! and ) to define a negative lookahead group that specifies that the subpattern in the group must not match at
the position. For example:
var pattern:RegExp = /sh(?!e)(\w*)/i;
var str:String = "She sells seashells by the seashore";
trace(pattern.exec(str));
// shore,ore
Using named groups
A named group is a type of group in a regular expression that is given a named identifier. Use (?P and ) to
define the named group. For example, the following regular expression includes a named group with the identifier
named digits:
var pattern = /[a-z]+(?P\d+)[a-z]+/;
When you use the exec() method, a matching named group is added as a property of the result array:
var myPattern:RegExp = /([a-z]+)(?P\d+)[a-z]+/;
var str:String = "a123bcd";
var result:Array = myPattern.exec(str);
trace(result.digits); // 123
Here is another example, which uses two named groups, with the identifiers name and dom:
var emailPattern:RegExp =
/(?P(\w|[_.\-])+)@(?P((\w|-)+))+\.\w{2,4}+/;
var address:String = "bob@example.com";
var result:Array = emailPattern.exec(address);
trace(result.name); // bob
trace(result.dom); // example
Note: Named groups are not part of the ECMAScript language specification. They are an added feature in ActionScript 3.0.
Last updated 3/21/2011
87
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Using regular expressions
Flags and properties
Flash Player 9 and later, Adobe AIR 1.0 and later
The following table lists the five flags that you can set for regular expressions. Each flag can be accessed as a property
of the regular expression object.
Flag
Property
Description
g
global
Matches more than one match.
i
ignoreCase
Case-insensitive matching. Applies to the A—Z and a—z characters, but not to extended characters
such as É and é .
m
multiline
With this flag set, $ and ^ can match the beginning of a line and end of a line, respectively.
s
dotall
With this flag set, . (dot) can match the newline character (\n).
x
extended
Allows extended regular expressions. You can type spaces in the regular expression, which are ignored
as part of the pattern. This lets you type regular expression code more legibly.
Note that these properties are read-only. You can set the flags (g, i, m, s, x) when you set a regular expression variable,
as follows:
var re:RegExp = /abc/gimsx;
However, you cannot directly set the named properties. For instance, the following code results in an error:
var re:RegExp = /abc/;
re.global = true; // This generates an error.
By default, unless you specify them in the regular expression declaration, the flags are not set, and the corresponding
properties are also set to false.
Additionally, there are two other properties of a regular expression:
• The lastIndex property specifies the index position in the string to use for the next call to the exec() or test()
method of a regular expression.
• The source property specifies the string that defines the pattern portion of the regular expression.
The g (global) flag
When the g (global) flag is not included, a regular expression matches no more than one match. For example, with
the g flag not included in the regular expression, the String.match() method returns only one matching substring:
var str:String = "she sells seashells by the seashore.";
var pattern:RegExp = /sh\w*/;
trace(str.match(pattern)) // output: she
When the g flag is set, the Sting.match() method returns multiple matches, as follows:
var str:String = "she sells seashells by the seashore.";
var pattern:RegExp = /sh\w*/g;
// The same pattern, but this time the g flag IS set.
trace(str.match(pattern)); // output: she,shells,shore
The i (ignoreCase) flag
By default, regular expression matches are case-sensitive. When you set the i (ignoreCase) flag, case sensitivity is
ignored. For example, the lowercase s in the regular expression does not match the uppercase letter S, the first
character of the string:
Last updated 3/21/2011
88
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Using regular expressions
var str:String = "She sells seashells by the seashore.";
trace(str.search(/sh/)); // output: 13 -- Not the first character
With the i flag set, however, the regular expression does match the capital letter S:
var str:String = "She sells seashells by the seashore.";
trace(str.search(/sh/i)); // output: 0
The i flag ignores case sensitivity only for the A–Z and a–z characters, but not for extended characters such as É and é .
The m (multiline) flag
If the m (multiline) flag is not set, the ^ matches the beginning of the string and the $ matches the end of the string.
If the m flag is set, these characters match the beginning of a line and end of a line, respectively. Consider the following
string, which includes a newline character:
var str:String = "Test\n";
str += "Multiline";
trace(str.match(/^\w*/g)); // Match a word at the beginning of the string.
Even though the g (global) flag is set in the regular expression, the match() method matches only one substring, since
there is only one match for the ^—the beginning of the string. The output is:
Test
Here is the same code with the m flag set:
var str:String = "Test\n";
str += "Multiline";
trace(str.match(/^\w*/gm)); // Match a word at the beginning of lines.
This time, the output includes the words at the beginning of both lines:
Test,Multiline
Note that only the \n character signals the end of a line. The following characters do not:
• Return (\r) character
• Unicode line-separator (\u2028) character
• Unicode paragraph-separator (\u2029) character
The s (dotall) flag
If the s (dotall or “dot all”) flag is not set, a dot (.) in a regular expression pattern does not match a newline character
(\n). So for the following example, there is no match:
var str:String = "
Test\n";
str += "Multiline
";
var re:RegExp = /
.*?<\/p>/;
trace(str.match(re));
However, if the s flag is set, the dot matches the newline character:
var str:String = "
Test\n";
str += "Multiline
";
var re:RegExp = /
.*?<\/p>/s;
trace(str.match(re));
In this case, the match is the entire substring within the
tags, including the newline character:
Test
Multiline
Last updated 3/21/2011
89
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Using regular expressions
The x (extended) flag
Regular expressions can be difficult to read, especially when they include a lot of metasymbols and metasequences. For
example:
/|(\s*[^>]*>)).*?<\/p>/gi
When you use the x (extended) flag in a regular expression, any blank spaces that you type in the pattern are ignored.
For example, the following regular expression is identical to the previous example:
/
)
As the following example shows, you can also use curly brace operators ( { and } ) to pass data by reference (from other
variables) when constructing XML objects:
var ids:Array = [121, 122, 123];
var names:Array = [["Murphy","Pat"], ["Thibaut","Jean"], ["Smith","Vijay"]]
var x:XML = new XML("");
for (var i:int = 0; i < 3; i++)
{
var newnode:XML = new XML();
newnode =
{names[i][0]}{names[i][1]};
x = x.appendChild(newnode)
}
You can assign properties and attributes to an XML object by using the = operator, as in the following:
var x:XML =
Smith
x.firstname = "Jean";
x.@id = "239";
This sets the XML object x to the following:
SmithJean
You can use the + and += operators to concatenate XMLList objects:
var x1:XML = test1
var x2:XML = test2
var xList:XMLList = x1 + x2;
xList += test3
This sets the XMLList object xList to the following:
test1test2test3
Last updated 3/21/2011
106
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with XML
Traversing XML structures
Flash Player 9 and later, Adobe AIR 1.0 and later
One of the powerful features of XML is its ability to provide complex, nested data via a linear string of text characters.
When you load data into an XML object, ActionScript parses the data and loads its hierarchical structure into memory
(or it sends a run-time error if the XML data is not well formed).
The operators and methods of the XML and XMLList objects make it easy to traverse the structure of XML data.
Use the dot (.) operator and the descendent accessor (..) operator to access child properties of an XML object. Consider
the following XML object:
var myXML:XML =
Baking Extravagant Pastries with KumquatsContinoChuck238Emu Care and BreedingCaseJustin115
The object myXML.book is an XMLList object containing child properties of the myXML object that have the name book.
These are two XML objects, matching the two book properties of the myXML object.
The object myXML..lastName is an XMLList object containing any descendent properties with the name lastName.
These are two XML objects, matching the two lastName of the myXML object.
The object myXML.book.editor.lastName is an XMLList object containing any children with the name lastName
of children with the name editor of children with the name book of the myXML object: in this case, an XMLList object
containing only one XML object (the lastName property with the value "Case").
Accessing parent and child nodes
Flash Player 9 and later, Adobe AIR 1.0 and later
The parent() method returns the parent of an XML object.
You can use the ordinal index values of a child list to access specific child objects. For example, consider an XML object
myXML that has two child properties named book. Each child property named book has an index number associated
with it:
myXML.book[0]
myXML.book[1]
Last updated 3/21/2011
107
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with XML
To access a specific grandchild, you can specify index numbers for both the child and grandchild names:
myXML.book[0].title[0]
However, if there is only one child of x.book[0] that has the name title, you can omit the index reference, as follows:
myXML.book[0].title
Similarly, if there is only one book child of the object x, and if that child object has only one title object, you can omit
both index references, like this:
myXML.book.title
You can use the child() method to navigate to children with names based on a variable or expression, as the following
example shows:
var myXML:XML =
Dictionary;
var childName:String = "book";
trace(myXML.child(childName).title) // output: Dictionary
Accessing attributes
Flash Player 9 and later, Adobe AIR 1.0 and later
Use the @ symbol (the attribute identifier operator) to access attributes in an XML or XMLList object, as shown in the
following code:
var employee:XML =
WuErin;
trace(employee.@id); // 6401
You can use the * wildcard symbol with the @ symbol to access all attributes of an XML or XMLList object, as in the
following code:
var employee:XML =
WuErin;
trace(employee.@*.toXMLString());
// 6401
// 233
You can use the attribute() or attributes() method to access a specific attribute or all attributes of an XML or
XMLList object, as in the following code:
Last updated 3/21/2011
108
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with XML
var employee:XML =
WuErin;
trace(employee.attribute("id")); // 6401
trace(employee.attribute("*").toXMLString());
// 6401
// 233
trace(employee.attributes().toXMLString());
// 6401
// 233
Note that you can also use the following syntax to access attributes, as the following example shows:
employee.attribute("id")
employee["@id"]
employee.@["id"]
These are each equivalent to employee.@id. However, the syntax employee.@id is the preferred approach.
Filtering by attribute or element value
Flash Player 9 and later, Adobe AIR 1.0 and later
You can use the parentheses operators— ( and ) —to filter elements with a specific element name or attribute value.
Consider the following XML object:
var x:XML =
ZmedSueData analystMcGeeChuckJr. data analyst
The following expressions are all valid:
•
x.employee.(lastName == "McGee")—This is the second employee node.
•
x.employee.(lastName == "McGee").firstName—This is the firstName property of the second employee node.
•
x.employee.(lastName == "McGee").@id—This is the value of the id attribute of the second employee node.
•
x.employee.(@id == 347)—The first employee node.
•
x.employee.(@id == 347).lastName—This is the lastName property of the first employee node.
•
x.employee.(@id > 300)—This is an XMLList with both employee properties.
•
x.employee.(position.toString().search("analyst") > -1)—This is an XMLList with both position
properties.
If you try to filter on attributes or elements that do not exist, an exception is thrown. For example, the final line of the
following code generates an error, because there is no id attribute in the second p element:
Last updated 3/21/2011
109
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with XML
var doc:XML =
Hello, Bob.
Hello.
;
trace(doc.p.(@id == '123'));
Similarly, the final line of following code generates an error because there is no b property of the second p element:
var doc:XML =
Hello, Bob.
Hello.
;
trace(doc.p.(b == 'Bob'));
To avoid these errors, you can identify the properties that have the matching attributes or elements by using the
attribute() and elements() methods, as in the following code:
var doc:XML =
Hello, Bob.
Hello.
;
trace(doc.p.(attribute('id') == '123'));
trace(doc.p.(elements('b') == 'Bob'));
You can also use the hasOwnProperty() method, as in the following code:
var doc:XML =
The first lines of the method clear the default xml namespace:
default xml namespace = new Namespace();
The default xml namespace directive has function block-level scope. This means that the scope of this declaration
is the buildItemHTML() method.
The lines that follow assemble the XMLList, based on the string arguments passed to the function:
Last updated 3/21/2011
116
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with XML
var body:XMLList = new XMLList();
body += new XML("" + itemTitle + "");
var p:XML = new XML("
" + itemDescription + "
");
var link:XML = ;
link.@href = itemLink; //
link.font.@color = "#008000";
//
// 0x008000 = green
link.font = "More...";
p.appendChild( );
p.appendChild(link);
body += p;
This XMLList object represents string data suitable for an ActionScript HTML text field.
The xmlLoaded() method uses the return value of the buildItemHTML() method and converts it to a string:
XML.prettyPrinting = false;
rssOutput = outXML.toXMLString();
Extracting the title of the RSS feed and sending a custom event
Flash Player 9 and later, Adobe AIR 1.0 and later
The xmlLoaded() method sets a rssTitle string variable, based on information in the source RSS XML data:
rssTitle = rssXML.channel.title.toString();
Finally, the xmlLoaded() method generates an event, which notifies the application that the data is parsed and
available:
dataWritten = new Event("dataWritten", true);
Last updated 3/21/2011
117
Chapter 7: Handling events
Flash Player 9 and later, Adobe AIR 1.0 and later
An event-handling system allows programmers to respond to user input and system events in a convenient way. The
ActionScript 3.0 event model is not only convenient, but also standards-compliant, and well integrated with the
display list. Based on the Document Object Model (DOM) Level 3 Events Specification, an industry-standard eventhandling architecture, the new event model provides a powerful yet intuitive event-handling tool for ActionScript
programmers.
The ActionScript 3.0 event-handling system interacts closely with the display list. To gain a basic understanding of the
display list, read “Display programming” on page 143.
More Help topics
flash.events package
Document Object Model (DOM) Level 3 Events Specification
Basics of handling events
Flash Player 9 and later, Adobe AIR 1.0 and later
You can think of events as occurrences of any kind in your SWF file that are of interest to you as a programmer. For
example, most SWF files support user interaction of some sort—whether it's something as simple as responding to a
mouse click or something more complex, such as accepting and processing data entered into a form. Any such user
interaction with your SWF file is considered an event. Events can also occur without any direct user interaction, such
as when data has finished loading from a server or when an attached camera has become active.
In ActionScript 3.0, each event is represented by an event object, which is an instance of the Event class or one of its
subclasses. An event object not only stores information about a specific event, but also contains methods that facilitate
manipulation of the event object. For example, when Flash Player or AIR detects a mouse click, it creates an event
object (an instance of the MouseEvent class) to represent that particular mouse click event.
After creating an event object, Flash Player or AIR dispatches it, which means that the event object is passed to the
object that is the target of the event. An object that serves as the destination for a dispatched event object is called an
event target. For example, when an attached camera becomes active, Flash Player dispatches an event object directly to
the event target, which in this case is the object that represents the camera. If the event target is on the display list,
however, the event object is passed down through the display list hierarchy until it reaches the event target. In some
cases, the event object then “bubbles” back up the display list hierarchy along the same route. This traversal of the
display list hierarchy is called the event flow.
You can “listen” for event objects in your code using event listeners. Event listeners are the functions or methods that
you write to respond to specific events. To ensure that your program responds to events, you must add event listeners
either to the event target or to any display list object that is part of an event object’s event flow.
Any time you write event listener code, it follows this basic structure (elements in bold are placeholders you’d fill in
for your specific case):
Last updated 3/21/2011
118
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Handling events
function eventResponse(eventObject:EventType):void
{
// Actions performed in response to the event go here.
}
eventTarget.addEventListener(EventType.EVENT_NAME, eventResponse);
This code does two things. First, it defines a function, which is the way to specify the actions that will be performed in
response to the event. Next, it calls the addEventListener() method of the source object, in essence “subscribing”
the function to the specified event so that when the event happens, the function’s actions are carried out. When the
event actually happens, the event target checks its list of all the functions and methods that are registered as event
listeners. It then calls each one in turn, passing the event object as a parameter.
You need to alter four things in this code to create your own event listener. First, you must change the name of the
function to the name you want to use (this must be changed in two places, where the code says eventResponse).
Second, you must specify the appropriate class name of the event object that is dispatched by the event you want to
listen for (EventType in the code), and you must specify the appropriate constant for the specific event
(EVENT_NAME in the listing). Third, you must call the addEventListener() method on the object that will
dispatch the event (eventTarget in this code). Optionally, you can change the name of the variable used as the
function’s parameter (eventObject in this code).
Important concepts and terms
The following reference list contains important terms that you will encounter when writing event-handling routines:
Bubbling Bubbling occurs for some events so that a parent display object can respond to events dispatched by its
children.
Bubbling phase The part of the event flow in which an event propagates up to parent display objects. The bubbling
phase occurs after the capture and target phases.
Capture phase The part of the event flow in which an event propagates down from the most general target to the most
specific target object. The capture phase occurs before the target and bubbling phases.
Default behavior Some events include a behavior that normally happens along with the event, known as the default
behavior. For example, when a user types text in a text field, a text input event is raised. The default behavior for that
event is to actually display the character that was typed into the text field—but you can override that default behavior
(if for some reason you don’t want the typed character to be displayed).
Dispatch To notify event listeners that an event has occurred.
Event Something that happens to an object that the object can tell other objects about.
Event flow When events happen to an object on the display list (an object displayed on the screen), all the objects that
contain the object are notified of the event and notify their event listeners in turn. This process starts with the Stage
and proceeds through the display list to the actual object where the event occurred, and then proceeds back to the Stage
again. This process is known as the event flow.
Event object An object that contains information about a particular event’s occurrence, which is sent to all listeners
when an event is dispatched.
Event target The object that actually dispatches an event. For example, if the user clicks a button that is inside a Sprite
that is in turn inside the Stage, all those objects dispatch events, but the event target is the one where the event actually
happened—in this case, the clicked button.
Listener An object or function that has registered itself with an object, to indicate that it should be notified when a
specific event takes place.
Last updated 3/21/2011
119
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Handling events
Target phase The point of the event flow at which an event has reached the most specific possible target. The target
phase occurs between the capture and the bubbling phases.
How ActionScript 3.0 event handling differs from earlier
versions
Flash Player 9 and later, Adobe AIR 1.0 and later
The most noticeable difference between event handling in ActionScript 3.0 and event handling in previous versions of
ActionScript is that in ActionScript 3.0 there is only one system for event handling, whereas in previous versions of
ActionScript there are several different event-handling systems. This section begins with an overview of how event
handling worked in previous versions of ActionScript, and then discusses how event handling has changed for
ActionScript 3.0.
Event handling in previous versions of ActionScript
Flash Player 9 and later, Adobe AIR 1.0 and later
Versions of ActionScript before ActionScript 3.0 provided a number of different ways to handle events:
•
on() event handlers that can be placed directly on Button and MovieClip instances
•
onClipEvent() handlers that can be placed directly on MovieClip instances
• Callback function properties, such as XML.onload and Camera.onActivity
• Event listeners that you register using the addListener() method
• The UIEventDispatcher class that partially implemented the DOM event model.
Each of these mechanisms presents its own set of advantages and limitations. The on() and onClipEvent() handlers
are easy to use, but make subsequent maintenance of projects more difficult because code placed directly on buttons
and movie clips can be difficult to find. Callback functions are also simple to implement, but limit you to only one
callback function for any given event. Event listeners are more difficult to implement—they require not only the
creation of a listener object and function, but also the registration of the listener with the object that generates the
event. This increased overhead, however, enables you to create several listener objects and register them all for the
same event.
The development of components for ActionScript 2.0 engendered yet another event model. This new model,
embodied in the UIEventDispatcher class, was based on a subset of the DOM Events Specification. Developers who
are familiar with component event handling will find the transition to the new ActionScript 3.0 event model relatively
painless.
Unfortunately, the syntax used by the various event models overlap in various ways, and differ in others. For example,
in ActionScript 2.0, some properties, such as TextField.onChanged, can be used as either a callback function or an
event listener. However, the syntax for registering listener objects differs depending on whether you are using one of
the six classes that support listeners or the UIEventDispatcher class. For the Key, Mouse, MovieClipLoader, Selection,
Stage, and TextField classes, you use the addListener() method, but for components event handling, you use a
method called addEventListener().
Another complexity introduced by the different event-handling models was that the scope of the event handler
function varied widely depending on the mechanism used. In other words, the meaning of the this keyword was not
consistent among the event-handling systems.
Last updated 3/21/2011
120
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Handling events
Event handling in ActionScript 3.0
Flash Player 9 and later, Adobe AIR 1.0 and later
ActionScript 3.0 introduces a single event-handling model that replaces the many different event-handling
mechanisms that existed in previous versions of the language. The new event model is based on the Document Object
Model (DOM) Level 3 Events Specification. Although the SWF file format does not adhere specifically to the
Document Object Model standard, there are sufficient similarities between the display list and the structure of the
DOM to make implementation of the DOM event model possible. An object on the display list is analogous to a node
in the DOM hierarchical structure, and the terms display list object and node are used interchangeably throughout this
discussion.
The Flash Player and AIR implementation of the DOM event model includes a concept named default behaviors. A
default behavior is an action that Flash Player or AIR executes as the normal consequence of certain events.
Default behaviors
Developers are usually responsible for writing code that responds to events. In some cases, however, a behavior is so
commonly associated with an event that Flash Player or AIR automatically executes the behavior unless the developer
adds code to cancel it. Because Flash Player or AIR automatically exhibits the behavior, such behaviors are called
default behaviors.
For example, when a user enters text into a TextField object, the expectation that the text will be displayed in that
TextField object is so common that the behavior is built into Flash Player and AIR. If you do not want this default
behavior to occur, you can cancel it using the new event-handling system. When a user inputs text into a TextField
object, Flash Player or AIR creates an instance of the TextEvent class to represent that user input. To prevent Flash
Player or AIR from displaying the text in the TextField object, you must access that specific TextEvent instance and
call that instance’s preventDefault() method.
Not all default behaviors can be prevented. For example, Flash Player and AIR generate a MouseEvent object when a
user double-clicks a word in a TextField object. The default behavior, which cannot be prevented, is that the word
under the cursor is highlighted.
Many types of event objects do not have associated default behaviors. For example, Flash Player dispatches a connect
event object when a network connection is established, but there is no default behavior associated with it. The API
documentation for the Event class and its subclasses lists each type of event and describes any associated default
behavior, and whether that behavior can be prevented.
It is important to understand that default behaviors are associated only with event objects dispatched by Flash Player
or AIR, and do not exist for event objects dispatched programmatically through ActionScript. For example, you can
use the methods of the EventDispatcher class to dispatch an event object of type textInput, but that event object will
not have a default behavior associated with it. In other words, Flash Player and AIR will not display a character in a
TextField object as a result of a textInput event that you dispatched programmatically.
What’s new for event listeners in ActionScript 3.0
For developers with experience using the ActionScript 2.0 addListener() method, it may be helpful to point out the
differences between the ActionScript 2.0 event listener model and the ActionScript 3.0 event model. The following list
describes a few major differences between the two event models:
• To add event listeners in ActionScript 2.0, you use addListener() in some cases and addEventListener() in
others, whereas in ActionScript 3.0, you use addEventListener() in all situations.
• There is no event flow in ActionScript 2.0, which means that the addListener() method can be called only on the
object that broadcasts the event, whereas in ActionScript 3.0, the addEventListener() method can be called on
any object that is part of the event flow.
Last updated 3/21/2011
121
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Handling events
• In ActionScript 2.0, event listeners can be either functions, methods, or objects, whereas in ActionScript 3.0, only
functions or methods can be event listeners.
The event flow
Flash Player 9 and later, Adobe AIR 1.0 and later
Flash Player or AIR dispatches event objects whenever an event occurs. If the event target is not on the display list,
Flash Player or AIR dispatches the event object directly to the event target. For example, Flash Player dispatches the
progress event object directly to a URLStream object. If the event target is on the display list, however, Flash Player
dispatches the event object into the display list, and the event object travels through the display list to the event target.
The event flow describes how an event object moves through the display list. The display list is organized in a hierarchy
that can be described as a tree. At the top of the display list hierarchy is the Stage, which is a special display object
container that serves as the root of the display list. The Stage is represented by the flash.display.Stage class and can only
be accessed through a display object. Every display object has a property named stage that refers to the Stage for that
application.
When Flash Player or AIR dispatches an event object for a display list-related event, that event object makes a roundtrip journey from the Stage to the target node. The DOM Events Specification defines the target node as the node
representing the event target. In other words, the target node is the display list object where the event occurred. For
example, if a user clicks on a display list object named child1, Flash Player or AIR will dispatch an event object using
child1 as the target node.
The event flow is conceptually divided into three parts. The first part is called the capture phase; this phase comprises
all of the nodes from the Stage to the parent of the target node. The second part is called the target phase, which consists
solely of the target node. The third part is called the bubbling phase. The bubbling phase comprises the nodes
encountered on the return trip from the parent of the target node back to the Stage.
The names of the phases make more sense if you conceive of the display list as a vertical hierarchy with the Stage at the
top, as shown in the following diagram:
Stage
Parent Node
Child1 Node
Child2 Node
Last updated 3/21/2011
122
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Handling events
If a user clicks on Child1 Node, Flash Player or AIR dispatches an event object into the event flow. As the following
image shows, the object’s journey starts at Stage, moves down to Parent Node, then moves to Child1 Node, and
then “bubbles” back up to Stage, moving through Parent Node again on its journey back to Stage.
Stage
Capture
Phase
Bubbling
Phase
Parent Node
Child1 Node
Child2 Node
Target Phase
In this example, the capture phase comprises Stage and Parent Node during the initial downward journey. The target
phase comprises the time spent at Child1 Node. The bubbling phase comprises Parent Node and Stage as they are
encountered during the upward journey back to the root node.
The event flow contributes to a more powerful event-handling system than that previously available to ActionScript
programmers. In previous versions of ActionScript, the event flow does not exist, which means that event listeners can
be added only to the object that generates the event. In ActionScript 3.0, you can add event listeners not only to a target
node, but also to any node along the event flow.
The ability to add event listeners along the event flow is useful when a user interface component comprises more than
one object. For example, a button object often contains a text object that serves as the button’s label. Without the ability
to add a listener to the event flow, you would have to add a listener to both the button object and the text object to
ensure that you receive notification about click events that occur anywhere on the button. The existence of the event
flow, however, allows you to place a single event listener on the button object that handles click events that occur either
on the text object or on the areas of the button object that are not obscured by the text object.
Not every event object, however, participates in all three phases of the event flow. Some types of events, such as the
enterFrame and init event types, are dispatched directly to the target node and participate in neither the capture
phase nor the bubbling phase. Other events may target objects that are not on the display list, such as events dispatched
to an instance of the Socket class. These event objects will also flow directly to the target object, without participating
in the capture and bubbling phases.
To find out how a particular event type behaves, you can either check the API documentation or examine the event
object's properties. Examining the event object’s properties is described in the following section.
Event objects
Flash Player 9 and later, Adobe AIR 1.0 and later
Event objects serve two main purposes in the new event-handling system. First, event objects represent actual events
by storing information about specific events in a set of properties. Second, event objects contain a set of methods that
allow you to manipulate event objects and affect the behavior of the event-handling system.
To facilitate access to these properties and methods, the Flash Player API defines an Event class that serves as the base
class for all event objects. The Event class defines a fundamental set of properties and methods that are common to all
event objects.
Last updated 3/21/2011
123
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Handling events
This section begins with a discussion of the Event class properties, continues with a description of the Event class
methods, and concludes with an explanation of why subclasses of the Event class exist.
Understanding Event class properties
Flash Player 9 and later, Adobe AIR 1.0 and later
The Event class defines a number of read-only properties and constants that provide important information about an
event object.The following are especially important:
• Event object types are represented by constants and stored in the Event.type property.
• Whether an event’s default behavior can be prevented is represented by a Boolean value and stored in the
Event.cancelable property.
• Event flow information is contained in the remaining properties.
Event object types
Every event object has an associated event type. Event types are stored in the Event.type property as string values. It
is useful to know the type of an event object so that your code can distinguish objects of different types from one
another. For example, the following code specifies that the clickHandler() listener function should respond to any
mouse click event objects that are passed to myDisplayObject:
myDisplayObject.addEventListener(MouseEvent.CLICK, clickHandler);
Some two dozen event types are associated with the Event class itself and are represented by Event class constants,
some of which are shown in the following excerpt from the Event class definition:
package flash.events
{
public class Event
{
// class constants
public static const ACTIVATE:String = "activate";
public static const ADDED:String= "added";
// remaining constants omitted for brevity
}
}
These constants provide an easy way to refer to specific event types. You should use these constants instead of the
strings they represent. If you misspell a constant name in your code, the compiler will catch the mistake, but if you
instead use strings, a typographical error may not manifest at compile time and could lead to unexpected behavior that
could be difficult to debug. For example, when adding an event listener, use the following code:
myDisplayObject.addEventListener(MouseEvent.CLICK, clickHandler);
rather than:
myDisplayObject.addEventListener("click", clickHandler);
Default behavior information
Your code can check whether the default behavior for any given event object can be prevented by accessing the
cancelable property. The cancelable property holds a Boolean value that indicates whether or not a default
behavior can be prevented. You can prevent, or cancel, the default behavior associated with a small number of events
using the preventDefault() method. For more information, see Cancelling default event behavior under
“Understanding Event class methods” on page 125.
Last updated 3/21/2011
124
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Handling events
Event flow information
The remaining Event class properties contain important information about an event object and its relationship to the
event flow, as described in the following list:
• The bubbles property contains information about the parts of the event flow in which the event object participates.
• The eventPhase property indicates the current phase in the event flow.
• The target property stores a reference to the event target.
• The currentTarget property stores a reference to the display list object that is currently processing the event
object.
The bubbles property
An event is said to bubble if its event object participates in the bubbling phase of the event flow, which means that the
event object is passed from the target node back through its ancestors until it reaches the Stage. The Event.bubbles
property stores a Boolean value that indicates whether the event object participates in the bubbling phase. Because all
events that bubble also participate in the capture and target phases, any event that bubbles participates in all three of
the event flow phases. If the value is true, the event object participates in all three phases. If the value is false, the
event object does not participate in the bubbling phase.
The eventPhase property
You can determine the event phase for any event object by investigating its eventPhase property. The eventPhase
property contains an unsigned integer value that represents one of the three phases of the event flow. The Flash Player
API defines a separate EventPhase class that contains three constants that correspond to the three unsigned integer
values, as shown in the following code excerpt:
package flash.events
{
public final class EventPhase
{
public static const CAPTURING_PHASE:uint = 1;
public static const AT_TARGET:uint = 2;
public static const BUBBLING_PHASE:uint= 3;
}
}
These constants correspond to the three valid values of the eventPhase property. You can use these constants to make
your code more readable. For example, if you want to ensure that a function named myFunc() is called only if the event
target is in the target stage, you can use the following code to test for this condition:
if (event.eventPhase == EventPhase.AT_TARGET)
{
myFunc();
}
The target property
The target property holds a reference to the object that is the target of the event. In some cases, this is straightforward,
such as when a microphone becomes active, the target of the event object is the Microphone object. If the target is on
the display list, however, the display list hierarchy must be taken into account. For example, if a user inputs a mouse
click on a point that includes overlapping display list objects, Flash Player and AIR always choose the object that is
farthest away from the Stage as the event target.
Last updated 3/21/2011
125
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Handling events
For complex SWF files, especially those in which buttons are routinely decorated with smaller child objects, the
target property may not be used frequently because it will often point to a button’s child object instead of the button.
In these situations, the common practice is to add event listeners to the button and use the currentTarget property
because it points to the button, whereas the target property may point to a child of the button.
The currentTarget property
The currentTarget property contains a reference to the object that is currently processing the event object. Although
it may seem odd not to know which node is currently processing the event object that you are examining, keep in mind
that you can add a listener function to any display object in that event object's event flow, and the listener function can
be placed in any location. Moreover, the same listener function can be added to different display objects. As a project
increases in size and complexity, the currentTarget property becomes more and more useful.
Understanding Event class methods
Flash Player 9 and later, Adobe AIR 1.0 and later
There are three categories of Event class methods:
• Utility methods, which can create copies of an event object or convert it to a string
• Event flow methods, which remove event objects from the event flow
• Default behavior methods, which prevent default behavior or check whether it has been prevented
Event class utility methods
There are two utility methods in the Event class. The clone() method allows you to create copies of an event object.
The toString() method allows you to generate a string representation of the properties of an event object along with
their values. Both of these methods are used internally by the event model system, but are exposed to developers for
general use.
For advanced developers creating subclasses of the Event class, you must override and implement versions of both
utility methods to ensure that the event subclass will work properly.
Stopping event flow
You can call either the Event.stopPropagation() method or the Event.stopImmediatePropagation() method
to prevent an event object from continuing on its way through the event flow. The two methods are nearly identical
and differ only in whether the current node’s other event listeners are allowed to execute:
• The Event.stopPropagation() method prevents the event object from moving on to the next node, but only after
any other event listeners on the current node are allowed to execute.
• The Event.stopImmediatePropagation() method also prevents the event object from moving on to the next
node, but does not allow any other event listeners on the current node to execute.
Calling either of these methods has no effect on whether the default behavior associated with an event occurs. Use the
default behavior methods of the Event class to prevent default behavior.
Cancelling default event behavior
The two methods that pertain to cancelling default behavior are the preventDefault() method and the
isDefaultPrevented() method. Call the preventDefault() method to cancel the default behavior associated with
an event. To check whether preventDefault() has already been called on an event object, call the
isDefaultPrevented() method, which returns a value of true if the method has already been called and false
otherwise.
Last updated 3/21/2011
126
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Handling events
The preventDefault() method will work only if the event’s default behavior can be cancelled. You can check
whether this is the case by referring to the API documentation for that event type, or by using ActionScript to examine
the cancelable property of the event object.
Cancelling the default behavior has no effect on the progress of an event object through the event flow. Use the event
flow methods of the Event class to remove an event object from the event flow.
Subclasses of the Event class
Flash Player 9 and later, Adobe AIR 1.0 and later
For many events, the common set of properties defined in the Event class is sufficient. Other events, however, have
unique characteristics that cannot be captured by the properties available in the Event class. For these events,
ActionScript 3.0 defines several subclasses of the Event class.
Each subclass provides additional properties and event types that are unique to that category of events. For example,
events related to mouse input have several unique characteristics that cannot be captured by the properties defined in
the Event class. The MouseEvent class extends the Event class by adding ten properties that contain information such
as the location of the mouse event and whether specific keys were pressed during the mouse event.
An Event subclass also contains constants that represent the event types that are associated with the subclass. For
example, the MouseEvent class defines constants for several mouse event types, include the click, doubleClick,
mouseDown, and mouseUp event types.
As described in the section on Event class utility methods under “Event objects” on page 122, when creating an Event
subclass you must override the clone() and toString() methods to provide functionality specific to the subclass.
Event listeners
Flash Player 9 and later, Adobe AIR 1.0 and later
Event listeners, which are also called event handlers, are functions that Flash Player and AIR execute in response to
specific events. Adding an event listener is a two-step process. First, you create a function or class method for Flash
Player or AIR to execute in response to the event. This is sometimes called the listener function or the event handler
function. Second, you use the addEventListener() method to register your listener function with the target of the
event or any display list object that lies along the appropriate event flow.
Creating a listener function
Flash Player 9 and later, Adobe AIR 1.0 and later
The creation of listener functions is one area where the ActionScript 3.0 event model deviates from the DOM event
model. In the DOM event model, there is a clear distinction between an event listener and a listener function: an event
listener is an instance of a class that implements the EventListener interface, whereas a listener function is a method
of that class named handleEvent(). In the DOM event model, you register the class instance that contains the listener
function rather than the actual listener function.
In the ActionScript 3.0 event model, there is no distinction between an event listener and a listener function.
ActionScript 3.0 does not have an EventListener interface, and listener functions can be defined outside a class or as
part of a class. Moreover, listener functions do not have to be named handleEvent()—they can be named with any
valid identifier. In ActionScript 3.0, you register the name of the actual listener function.
Last updated 3/21/2011
127
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Handling events
Listener function defined outside of a class
The following code creates a simple SWF file that displays a red square shape. A listener function named
clickHandler(), which is not part of a class, listens for mouse click events on the red square.
package
{
import flash.display.Sprite;
public class ClickExample extends Sprite
{
public function ClickExample()
{
var child:ChildSprite = new ChildSprite();
addChild(child);
}
}
}
import flash.display.Sprite;
import flash.events.MouseEvent;
class ChildSprite extends Sprite
{
public function ChildSprite()
{
graphics.beginFill(0xFF0000);
graphics.drawRect(0,0,100,100);
graphics.endFill();
addEventListener(MouseEvent.CLICK, clickHandler);
}
}
function clickHandler(event:MouseEvent):void
{
trace("clickHandler detected an event of type: " + event.type);
trace("the this keyword refers to: " + this);
}
When a user interacts with the resulting SWF file by clicking on the square, Flash Player or AIR generates the following
trace output:
clickHandler detected an event of type: click
the this keyword refers to: [object global]
Notice that the event object is passed as an argument to clickHandler(). This allows your listener function to
examine the event object. In this example, you use the event object's type property to ascertain that the event is a click
event.
The example also checks the value of the this keyword. In this case, this represents the global object, which makes
sense because the function is defined outside of any custom class or object.
Listener function defined as a class method
The following example is identical to the previous example that defines the ClickExample class except that the
clickHandler() function is defined as a method of the ChildSprite class:
Last updated 3/21/2011
128
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Handling events
package
{
import flash.display.Sprite;
public class ClickExample extends Sprite
{
public function ClickExample()
{
var child:ChildSprite = new ChildSprite();
addChild(child);
}
}
}
import flash.display.Sprite;
import flash.events.MouseEvent;
class ChildSprite extends Sprite
{
public function ChildSprite()
{
graphics.beginFill(0xFF0000);
graphics.drawRect(0,0,100,100);
graphics.endFill();
addEventListener(MouseEvent.CLICK, clickHandler);
}
private function clickHandler(event:MouseEvent):void
{
trace("clickHandler detected an event of type: " + event.type);
trace("the this keyword refers to: " + this);
}
}
When a user interacts with the resulting SWF file by clicking on the red square, Flash Player or AIR generates the
following trace output:
clickHandler detected an event of type: click
the this keyword refers to: [object ChildSprite]
Note that the this keyword refers to the ChildSprite instance named child. This is a change in behavior from
ActionScript 2.0. If you used components in ActionScript 2.0, you may remember that when a class method was passed
in to UIEventDispatcher.addEventListener(), the scope of the method was bound to the component that
broadcast the event instead of the class in which the listener method was defined. In other words, if you used this
technique in ActionScript 2.0, the this keyword would refer to the component broadcasting the event instead of the
ChildSprite instance.
This was a significant issue for some programmers because it meant that they could not access other methods and
properties of the class containing the listener method. As a workaround, ActionScript 2.0 programmers could use the
mx.util.Delegate class to change the scope of the listener method. This is no longer necessary, however, because
ActionScript 3.0 creates a bound method when addEventListener() is called. As a result, the this keyword refers
to the ChildSprite instance named child, and the programmer has access to the other methods and properties of the
ChildSprite class.
Last updated 3/21/2011
129
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Handling events
Event listener that should not be used
There is a third technique in which you create a generic object with a property that points to a dynamically assigned
listener function, but it is not recommended. It is discussed here because it was commonly used in ActionScript 2.0,
but should not be used in ActionScript 3.0. This technique is not recommended because the this keyword will refer
to the global object instead of your listener object.
The following example is identical to the previous ClickExample class example, except that the listener function is
defined as part of a generic object named myListenerObj:
package
{
import flash.display.Sprite;
public class ClickExample extends Sprite
{
public function ClickExample()
{
var child:ChildSprite = new ChildSprite();
addChild(child);
}
}
}
import flash.display.Sprite;
import flash.events.MouseEvent;
class ChildSprite extends Sprite
{
public function ChildSprite()
{
graphics.beginFill(0xFF0000);
graphics.drawRect(0,0,100,100);
graphics.endFill();
addEventListener(MouseEvent.CLICK, myListenerObj.clickHandler);
}
}
var myListenerObj:Object = new Object();
myListenerObj.clickHandler = function (event:MouseEvent):void
{
trace("clickHandler detected an event of type: " + event.type);
trace("the this keyword refers to: " + this);
}
The results of the trace will look like this:
clickHandler detected an event of type: click
the this keyword refers to: [object global]
You would expect that this would refer to myListenerObj and that the trace output would be [object Object],
but instead it refers to the global object. When you pass in a dynamic property name as an argument to
addEventListener(), Flash Player or AIR is unable to create a bound method. This is because what you are passing
as the listener parameter is nothing more than the memory address of your listener function, and Flash Player and
AIR have no way to link that memory address with the myListenerObj instance.
Last updated 3/21/2011
130
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Handling events
Managing event listeners
Flash Player 9 and later, Adobe AIR 1.0 and later
You can manage your listener functions using the methods of the IEventDispatcher interface. The IEventDispatcher
interface is the ActionScript 3.0 version of the EventTarget interface of the DOM event model. Although the name
IEventDispatcher may seem to imply that its main purpose is to send (or dispatch) event objects, the methods of this
class are actually used much more frequently to register event listeners, check for event listeners, and remove event
listeners. The IEventDispatcher interface defines five methods, as shown in the following code:
package flash.events
{
public interface IEventDispatcher
{
function addEventListener(eventName:String,
listener:Object,
useCapture:Boolean=false,
priority:Integer=0,
useWeakReference:Boolean=false):Boolean;
function removeEventListener(eventName:String,
listener:Object,
useCapture:Boolean=false):Boolean;
function dispatchEvent(eventObject:Event):Boolean;
function hasEventListener(eventName:String):Boolean;
function willTrigger(eventName:String):Boolean;
}
}
The Flash Player API implements the IEventDispatcher interface with the EventDispatcher class, which serves as a
base class for all classes that can be event targets or part of an event flow. For example, the DisplayObject class inherits
from the EventDispatcher class. This means that any object on the display list has access to the methods of the
IEventDispatcher interface.
Adding event listeners
The addEventListener() method is the workhorse of the IEventDispatcher interface. You use it to register your
listener functions. The two required parameters are type and listener. You use the type parameter to specify the
type of event. You use the listener parameter to specify the listener function that will execute when the event occurs.
The listener parameter can be a reference to either a function or a class method.
Do not use parentheses when you specify the listener parameter. For example, the clickHandler() function is
specified without parentheses in the following call to the addEventListener() method:
addEventListener(MouseEvent.CLICK, clickHandler)
The useCapture parameter of the addEventListener() method allows you to control the event flow phase on which
your listener will be active. If useCapture is set to true, your listener will be active during the capture phase of the
event flow. If useCapture is set to false, your listener will be active during the target and bubbling phases of the event
flow. To listen for an event during all phases of the event flow, you must call addEventListener() twice, once with
useCapture set to true, and then again with useCapture set to false.
Last updated 3/21/2011
131
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Handling events
The priority parameter of the addEventListener() method is not an official part of the DOM Level 3 event model.
It is included in ActionScript 3.0 to provide you with more flexibility in organizing your event listeners. When you call
addEventListener(), you can set the priority for that event listener by passing an integer value as the priority
parameter. The default value is 0, but you can set it to negative or positive integer values. The higher the number, the
sooner that event listener will be executed. Event listeners with the same priority are executed in the order that they
were added, so the earlier a listener is added, the sooner it will be executed.
The useWeakReference parameter allows you to specify whether the reference to the listener function is weak or
normal. Setting this parameter to true allows you to avoid situations in which listener functions persist in memory
even though they are no longer needed. Flash Player and AIR use a technique called garbage collection to clear objects
from memory that are no longer in use. An object is considered no longer in use if no references to it exist. The garbage
collector disregards weak references, which means that a listener function that has only a weak reference pointing to
it is eligible for garbage collection.
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. Recall that you can
listen for events during all event phases by calling addEventListener() twice, once with useCapture set to true,
and then again with it set to false. To remove both event listeners, you would need to call removeEventListener()
twice, once with useCapture set to true, and then again with it set to false.
Dispatching events
The dispatchEvent() method can be used by advanced programmers to dispatch a custom event object into the
event flow. The only parameter accepted by this method is a reference to an event object, which must be an instance
of the Event class or a subclass of the Event class. Once dispatched, the target property of the event object is set to
the object on which dispatchEvent() was called.
Checking for existing event listeners
The final two methods of the IEventDispatcher interface provide useful information about the existence of event
listeners. The hasEventListener() method returns true if an event listener is found for a specific event type on a
particular display list object. The willTrigger() method also returns true if a listener is found for a particular
display list object, but willTrigger() checks for listeners not only on that display object, but also on all of that display
list object’s ancestors for all phases of the event flow.
Last updated 3/21/2011
132
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Handling events
Error events without listeners
Flash Player 9 and later, Adobe AIR 1.0 and later
Exceptions, rather than events, are the primary mechanism for error handling in ActionScript 3.0, but exception
handling does not work for asynchronous operations such as loading files. If an error occurs during such an
asynchronous operation, Flash Player and AIR dispatch an error event object. If you do not create a listener for the
error event, the debugger versions of Flash Player and AIR will bring up a dialog box with information about the error.
For example, the debugger version of Flash Player produces the following dialog box describing the error when the
application attempts to load a file from an invalid URL:
Most error events are based on the ErrorEvent class, and as such will have a property named text that is used to store
the error message that Flash Player or AIR displays. The two exceptions are the StatusEvent and NetStatusEvent
classes. Both of these classes have a level property (StatusEvent.level and NetStatusEvent.info.level).
When the value of the level property is "error", these event types are considered to be error events.
An error event will not cause a SWF file to stop running. It will manifest only as a dialog box on the debugger versions
of the browser plug-ins and stand-alone players, as a message in the output panel in the authoring player, and as an
entry in the log file for Adobe Flash Builder. It will not manifest at all in the release versions of Flash Player or AIR.
Event handling example: Alarm Clock
Flash Player 9 and later, Adobe AIR 1.0 and later
The Alarm Clock example consists of a clock that allows the user to specify a time at which an alarm will go off, as well
as a message to be displayed at that time. The Alarm Clock example builds on the SimpleClock application from
“Working with dates and times” on page 1 Alarm Clock illustrates several aspects of working with events in
ActionScript 3.0, including:
• Listening and responding to an event
• Notifying listeners of an event
• Creating a custom event type
To get the Flash Professional application files for this sample, see
http://www.adobe.com/go/learn_programmingAS3samples_flash. To get the Flex application files for this sample, see
http://www.adobe.com/go/as3examples. The Alarm Clock application files can be found in the Samples/AlarmClock
folder. The application includes these files:
Last updated 3/21/2011
133
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Handling events
File
Description
AlarmClockApp.mxml
The main application file in Flash (FLA) or Flex (MXML).
or
AlarmClockApp.fla
com/example/programmingas3/clock/AlarmClock.as
A class which extends the SimpleClock class, adding alarm clock
functionality.
com/example/programmingas3/clock/AlarmEvent.as
A custom event class (a subclass of flash.events.Event) which serves as
the event object for the AlarmClock class’s alarm event.
com/example/programmingas3/clock/AnalogClockFace.as
Draws a round clock face and hour, minute, and seconds hands based
on the time (described in the SimpleClock example).
com/example/programmingas3/clock/SimpleClock.as
A clock interface component with simple timekeeping functionality
(described in the SimpleClock example).
Alarm Clock overview
Flash Player 9 and later, Adobe AIR 1.0 and later
The primary functionality of the clock in this example, including tracking the time and displaying the clock face, reuses
the SimpleClock application code, which is described in “Date and time example: Simple analog clock” on page 6. The
AlarmClock class extends the SimpleClock class from that example by adding the functionality required for an alarm
clock, including setting the alarm time and providing notification when the alarm “goes off.”
Providing notification when something happens is the job that events are made for. The AlarmClock class exposes the
Alarm event, which other objects can listen for in order to perform desired actions. In addition, the AlarmClock class
uses an instance of the Timer class to determine when to trigger its alarm. Like the AlarmClock class, the Timer class
provides an event to notify other objects (an AlarmClock instance, in this case) when a certain amount of time has
passed. As with most ActionScript applications, events form an important part of the functionality of the Alarm Clock
sample application.
Triggering the alarm
Flash Player 9 and later, Adobe AIR 1.0 and later
As mentioned previously, the only functionality that the AlarmClock class actually provides relates to setting and
triggering the alarm. The built-in Timer class (flash.utils.Timer) provides a way for a developer to define code that will
be executed after a specified amount of time. The AlarmClock class uses a Timer instance to determine when to set off
the alarm.
Last updated 3/21/2011
134
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Handling events
import flash.events.TimerEvent;
import flash.utils.Timer;
/**
* The Timer that will be used for the alarm.
*/
public var alarmTimer:Timer;
...
/**
* Instantiates a new AlarmClock of a given size.
*/
public override function initClock(faceSize:Number = 200):void
{
super.initClock(faceSize);
alarmTimer = new Timer(0, 1);
alarmTimer.addEventListener(TimerEvent.TIMER, onAlarm);
}
The Timer instance defined in the AlarmClock class is named alarmTimer. The initClock() method, which
performs necessary setup operations for the AlarmClock instance, does two things with the alarmTimer variable.
First, the variable is instantiated with parameters instructing the Timer instance to wait 0 milliseconds and only trigger
its timer event one time. After instantiating alarmTimer, the code calls that variable’s addEventListener() method
to indicate that it wants to listen to that variable’s timer event. A Timer instance works by dispatching its timer event
after a specified amount of time has passed. The AlarmClock class will need to know when the timer event is
dispatched in order to set off its own alarm. By calling addEventListener(), the AlarmClock code registers itself as
a listener with alarmTimer. The two parameters indicate that the AlarmClock class wants to listen for the timer event
(indicated by the constant TimerEvent.TIMER), and that when the event happens, the AlarmClock class’s onAlarm()
method should be called in response to the event.
In order to actually set the alarm, the AlarmClock class’s setAlarm() method is called, as follows:
Last updated 3/21/2011
135
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Handling events
/**
* Sets the time at which the alarm should go off.
* @param hour The hour portion of the alarm time.
* @param minutes The minutes portion of the alarm time.
* @param message The message to display when the alarm goes off.
* @return The time at which the alarm will go off.
*/
public function setAlarm(hour:Number = 0, minutes:Number = 0, message:String = "Alarm!"):Date
{
this.alarmMessage = message;
var now:Date = new Date();
// Create this time on today's date.
alarmTime = new Date(now.fullYear, now.month, now.date, hour, minutes);
// Determine if the specified time has already passed today.
if (alarmTime <= now)
{
alarmTime.setTime(alarmTime.time + MILLISECONDS_PER_DAY);
}
// Stop the alarm timer if it's currently set.
alarmTimer.reset();
// Calculate how many milliseconds should pass before the alarm should
// go off (the difference between the alarm time and now) and set that
// value as the delay for the alarm timer.
alarmTimer.delay = Math.max(1000, alarmTime.time - now.time);
alarmTimer.start();
return alarmTime;
}
This method does several things, including storing the alarm message and creating a Date object (alarmTime)
representing the actual moment in time when the alarm is to go off. Of most relevance to the current discussion, in the
final several lines of the method, the alarmTimer variable’s timer is set and activated. First, its reset() method is
called, stopping the timer and resetting it in case it is already running. Next, the current time (represented by the now
variable) is subtracted from the alarmTime variable’s value to determine how many milliseconds need to pass before
the alarm goes off. The Timer class doesn’t trigger its timer event at an absolute time, so it is this relative time
difference that is assigned to the delay property of alarmTimer. Finally, the start() method is called to actually start
the timer.
Once the specified amount of time has passed, alarmTimer dispatches the timer event. Because the AlarmClock class
registered its onAlarm() method as a listener for that event, when the timer event happens, onAlarm() is called.
/**
* Called when the timer event is dispatched.
*/
public function onAlarm(event:TimerEvent):void
{
trace("Alarm!");
var alarm:AlarmEvent = new AlarmEvent(this.alarmMessage);
this.dispatchEvent(alarm);
}
Last updated 3/21/2011
136
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Handling events
A method that is registered as an event listener must be defined with the appropriate signature (that is, the set of
parameters and return type of the method). To be a listener for the Timer class’s timer event, a method must define
one parameter whose data type is TimerEvent (flash.events.TimerEvent), a subclass of the Event class. When the Timer
instance calls its event listeners, it passes a TimerEvent instance as the event object.
Notifying others of the alarm
Flash Player 9 and later, Adobe AIR 1.0 and later
Like the Timer class, the AlarmClock class provides an event that allows other code to receive notifications when the
alarm goes off. For a class to use the event-handling framework built into ActionScript, that class must implement the
flash.events.IEventDispatcher interface. Most commonly, this is done by extending the flash.events.EventDispatcher
class, which provides a standard implementation of IEventDispatcher (or by extending one of EventDispatcher’s
subclasses). As described previously, the AlarmClock class extends the SimpleClock class, which (through a chain of
inheritance) extends the EventDispatcher class. All of this means that the AlarmClock class already has built-in
functionality to provide its own events.
Other code can register to be notified of the AlarmClock class’s alarm event by calling the addEventListener()
method that AlarmClock inherits from EventDispatcher. When an AlarmClock instance is ready to notify other code
that its alarm event has been raised, it does so by calling the dispatchEvent() method, which is also inherited from
EventDispatcher.
var alarm:AlarmEvent = new AlarmEvent(this.alarmMessage);
this.dispatchEvent(alarm);
These lines of code are taken from the AlarmClock class’s onAlarm() method (shown in its entirety previously). The
AlarmClock instance’s dispatchEvent() method is called, which in turn notifies all the registered listeners that the
AlarmClock instance’s alarm event has been triggered. The parameter that is passed to dispatchEvent() is the event
object that will be passed along to the listener methods. In this case, it is an instance of the AlarmEvent class, an Event
subclass created specifically for this example.
Providing a custom alarm event
Flash Player 9 and later, Adobe AIR 1.0 and later
All event listeners receive an event object parameter with information about the particular event being triggered. In
many cases, the event object is an instance of the Event class. However, in some cases it is useful to provide additional
information to event listeners. A common way to accomplish this is to define a new class, a subclass of the Event class,
and use an instance of that class as the event object. In this example, an AlarmEvent instance is used as the event object
when the AlarmClock class’s alarm event is dispatched. The AlarmEvent class, shown here, provides additional
information about the alarm event, specifically the alarm message:
Last updated 3/21/2011
137
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Handling events
import flash.events.Event;
/**
* This custom Event class adds a message property to a basic Event.
*/
public class AlarmEvent extends Event
{
/**
* The name of the new AlarmEvent type.
*/
public static const ALARM:String = "alarm";
/**
* A text message that can be passed to an event handler
* with this event object.
*/
public var message:String;
/**
*Constructor.
*@param message The text to display when the alarm goes off.
*/
public function AlarmEvent(message:String = "ALARM!")
{
super(ALARM);
this.message = message;
}
...
}
The best way to create a custom event object class is to define a class that extends the Event class, as shown in the
preceding example. To supplement the inherited functionality, the AlarmEvent class defines a property message that
contains the text of the alarm message associated with the event; the message value is passed in as a parameter in the
AlarmEvent constructor. The AlarmEvent class also defines the constant ALARM, which can be used to refer to the
specific event (alarm) when calling the AlarmClock class’s addEventListener() method.
In addition to adding custom functionality, every Event subclass must override the inherited clone() method as part
of the ActionScript event-handling framework. Event subclasses can also optionally override the inherited
toString() method to include the custom event’s properties in the value returned when the toString() method is
called.
Last updated 3/21/2011
138
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Handling events
/**
* Creates and returns a copy of the current instance.
* @return A copy of the current instance.
*/
public override function clone():Event
{
return new AlarmEvent(message);
}
/**
* Returns a String containing all the properties of the current
* instance.
* @return A string representation of the current instance.
*/
public override function toString():String
{
return formatToString("AlarmEvent", "type", "bubbles", "cancelable", "eventPhase",
"message");
}
The overridden clone() method needs to return a new instance of the custom Event subclass, with all the custom
properties set to match the current instance. In the overridden toString() method, the utility method
formatToString() (inherited from Event) is used to provide a string with the name of the custom type, as well as the
names and values of all its properties.
Last updated 3/21/2011
139
Chapter 8: Working with application
domains
Flash Player 9 and later, Adobe AIR 1.0 and later
The purpose of the ApplicationDomain class is to store a table of ActionScript 3.0 definitions. All code in a SWF file
is defined to exist in an application domain. You use application domains to partition classes that are in the same
security domain. This allows multiple definitions of the same class to exist and also lets children reuse parent
definitions.
You can use application domains when loading an external SWF file written in ActionScript 3.0 using the Loader class
API. (Note that you cannot use application domains when loading an image or SWF file written in ActionScript 1.0 or
ActionScript 2.0.) All ActionScript 3.0 definitions contained in the loaded class are stored in the application domain.
When loading the SWF file, you can specify that the file be included in the same application domain as that of the
Loader object, by setting the applicationDomain parameter of the LoaderContext object to
ApplicationDomain.currentDomain. By putting the loaded SWF file in the same application domain, you can
access its classes directly. This can be useful if you are loading a SWF file that contains embedded media, which you
can access via their associated class names, or if you want to access the loaded SWF file’s methods.
The following example assumes it has access to a separate Greeter.swf file that defines a public method named
welcome():
Last updated 3/21/2011
140
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with application domains
package
{
import
import
import
import
import
import
flash.display.Loader;
flash.display.Sprite;
flash.events.*;
flash.net.URLRequest;
flash.system.ApplicationDomain;
flash.system.LoaderContext;
public class ApplicationDomainExample extends Sprite
{
private var ldr:Loader;
public function ApplicationDomainExample()
{
ldr = new Loader();
var req:URLRequest = new URLRequest("Greeter.swf");
var ldrContext:LoaderContext = new LoaderContext(false,
ApplicationDomain.currentDomain);
ldr.contentLoaderInfo.addEventListener(Event.COMPLETE, completeHandler);
ldr.load(req, ldrContext);
}
private function completeHandler(event:Event):void
{
var myGreeter:Class = ApplicationDomain.currentDomain.getDefinition("Greeter") as
Class;
var myGreeter:Greeter = Greeter(event.target.content);
var message:String = myGreeter.welcome("Tommy");
trace(message); // Hello, Tommy
}
}
}
Also see the ApplicationDomain class example of the ActionScript 3.0 Reference for the Adobe Flash Platform.
Other things to keep in mind when you work with application domains include the following:
• All code in a SWF file is defined to exist in an application domain. The current domain is where your main
application runs. The system domain contains all application domains, including the current domain, which means
that it contains all Flash Player classes.
• All application domains, except the system domain, have an associated parent domain. The parent domain for your
main application's application domain is the system domain. Loaded classes are defined only when their parent
doesn't already define them. You cannot override a loaded class definition with a newer definition.
The following diagram shows an application that loads content from various SWF files within a single domain,
domain1.com. Depending on the content you load, different application domains can be used. The text that follows
describes the logic used to set the appropriate application domain for each SWF file in the application.
Last updated 3/21/2011
141
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with application domains
Security domain: domain1.com
Stage
Application domain 1
mx.core.Application
application1.swf
module1.swf
Loader
Application
Loader
Loader
Loader
Module
B
Application domain 3
module3.swf
C
Module
Application domain 2
mx.core.Application
A
application2.swf
Module
A. Usage A B. Usage B C. Usage C
The main application file is application1.swf. It contains Loader objects that load content from other SWF files. In this
scenario, the current domain is Application domain 1. Usage A, usage B, and usage C illustrate different techniques
for setting the appropriate application domain for each SWF file in an application.
Usage A Partition the child SWF file by creating a child of the system domain. In the diagram, Application domain 2
is created as a child of the system domain.The application2.swf file is loaded in Application domain 2, and its class
definitions are thus partitioned from the classes defined in application1.swf.
One use of this technique is to have an old application dynamically loading a newer version of the same application
without conflict. There is no conflict because although the same class names are used, they are partitioned into
different application domains.
The following code creates an application domain that is a child of the system domain, and starts loading a SWF using
that application domain:
var appDomainA:ApplicationDomain = new ApplicationDomain();
var contextA:LoaderContext = new LoaderContext(false, appDomainA);
var loaderA:Loader = new Loader();
loaderA.load(new URLRequest("application2.swf"), contextA);
Usage B: Add new class definitions to current class definitions. The application domain of module1.swf is set to the
current domain (Application domain 1). This lets you add to the application’s current set of class definitions with new
class definitions. This could be used for a run-time shared library of the main application. The loaded SWF is treated
as a remote shared library (RSL). Use this technique to load RSLs by a preloader before the application starts.
The following code loads a SWF, setting its application domain to the current domain:
Last updated 3/21/2011
142
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with application domains
var appDomainB:ApplicationDomain = ApplicationDomain.currentDomain;
var contextB:LoaderContext = new LoaderContext(false, appDomainB);
var loaderB:Loader = new Loader();
loaderB.load(new URLRequest("module1.swf"), contextB);
Usage C: Use the parent’s class definitions by creating a new child domain of the current domain. The application
domain of module3.swf is a child of the current domain, and the child uses the parent's versions of all classes. One use
of this technique might be a module of a multiple-screen rich Internet application (RIA), loaded as a child of the main
application, that uses the main application's types. If you can ensure that all classes are always updated to be backward
compatible, and that the loading application is always newer than the things it loads, the children will use the parent
versions. Having a new application domain also allows you to unload all the class definitions for garbage collection, if
you can ensure that you do not continue to have references to the child SWF.
This technique lets loaded modules share the loader's singleton objects and static class members.
The following code creates a new child domain of the current domain, and starts loading a SWF using that application
domain:
var appDomainC:ApplicationDomain = new ApplicationDomain(ApplicationDomain.currentDomain);
var contextC:LoaderContext = new LoaderContext(false, appDomainC);
var loaderC:Loader = new Loader();
loaderC.load(new URLRequest("module3.swf"), contextC);
Last updated 3/21/2011
143
Chapter 9: Display programming
Flash Player 9 and later, Adobe AIR 1.0 and later
Visual elements are programmed in Adobe® ActionScript® 3.0 by working with display objects on the display stage. For
example, you can add, move, remove, and order display objects, apply filters and masks, draw vector and bitmap
graphics, and perform three-dimensional transformations using the ActionScript display programming API. The
primary classes used for display programming are part of the flash.display package.
Note: Adobe® AIR™ provides the HTMLoader object for rendering and displaying HTML content. The HTMLLoader
renders the visual elements of the HTML DOM as a single display object. You cannot access the individual elements of
the DOM directly through the ActionScript display list hierarchy. Instead, you access these DOM elements using the
separate DOM API provided by the HTMLLoader.
Basics of display programming
Flash Player 9 and later, Adobe AIR 1.0 and later
Each application built with ActionScript 3.0 has a hierarchy of displayed objects known as the display list, illustrated
below. The display list contains all the visible elements in the application.
Stage
Instance of
the main class of
the SWF file
Display Object
Container
Display Object
Display Object
Container
Display Object
Display Object
Container
Display Object
Display Object
Container
Last updated 3/21/2011
144
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Display programming
As the illustration shows, display elements fall into one or more of the following groups:
• The Stage
The Stage is the base container of display objects. Each application has one Stage object, which contains all onscreen display objects. The Stage is the top-level container and is at the top of the display list hierarchy:
Each SWF file has an associated ActionScript class, known as the main class of the SWF file. When a SWF file opens
in Flash Player or Adobe AIR, Flash Player or AIR calls the constructor function for that class and the instance that
is created (which is always a type of display object) is added as a child of the Stage object. The main class of a SWF
file always extends the Sprite class (for more information, see “Advantages of the display list approach” on
page 148).
You can access the Stage through the stage property of any DisplayObject instance. For more information, see
“Setting Stage properties” on page 156.
• Display objects
In ActionScript 3.0, all elements that appear on screen in an application are types of display objects. The
flash.display package includes a DisplayObject class, which is a base class extended by a number of other classes.
These different classes represent different types of display objects, such as vector shapes, movie clips, and text fields,
to name a few. For an overview of these classes, see “Advantages of the display list approach” on page 148.
• Display object containers
Display object containers are special types of display objects that, in addition to having their own visual
representation, can also contain child objects that are also display objects.
The DisplayObjectContainer class is a subclass of the DisplayObject class. A DisplayObjectContainer object can
contain multiple display objects in its childlist. For example, the following illustration shows a type of
DisplayObjectContainer object known as a Sprite that contains various display objects:
A
B
C
D
A. A SimpleButton object. This type of display object has different “up,” “down,” and “over” states. B. A Bitmap object. In this case, the
Bitmap object was loaded from an external JPEG through a Loader object. C. A Shape object. The “picture frame” contains a rounded
rectangle that is drawn in ActionScript. This Shape object has a Drop Shadow filter applied to it. D. A TextField object.
In the context of discussing display objects, DisplayObjectContainer objects are also known as display object
containers or simply containers. As noted earlier, the Stage is a display object container.
Last updated 3/21/2011
145
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Display programming
Although all visible display objects inherit from the DisplayObject class, the type of each is of a specific subclass of
DisplayObject class. For example, there is a constructor function for the Shape class or the Video class, but there is
no constructor function for the DisplayObject class.
Important concepts and terms
The following reference list contains important terms that you will encounter when programming ActionScript
graphics:
Alpha The color value representing the amount of transparency (or more correctly, the amount of opacity) in a color.
For example, a color with an alpha channel value of 60% only shows 60% of its full strength, and is 40% transparent.
Bitmap graphic A graphic that is defined in the computer as a grid (rows and columns) of colored pixels. Commonly
bitmap graphics include digital photos and similar images.
Blending mode A specification of how the contents of two overlapping images should interact. Commonly an opaque
image on top of another image simply blocks the image underneath so that it isn’t visible at all; however, different
blending modes cause the colors of the images to blend together in different ways so the resulting content is some
combination of the two images.
Display list The hierarchy of display objects that will be rendered as visible screen content by Flash Player and AIR.
The Stage is the root of the display list, and all the display objects that are attached to the Stage or one of its children
form the display list (even if the object isn’t actually rendered, for example if it’s outside the boundaries of the Stage).
Display object An object which represents some type of visual content in Flash Player or AIR. Only display objects can
be included in the display list, and all display object classes are subclasses of the DisplayObject class.
Display object container A special type of display object which can contain child display objects in addition to
(generally) having its own visual representation.
Main class of the SWF file The class that defines the behavior for the outermost display object in a SWF file, which
conceptually is the class for the SWF file itself. For instance, in a SWF created in Flash authoring, the main class is the
document class. It has a “main timeline” which contains all other timelines; the main class of the SWF file is the class
of which the main timeline is an instance.
Masking A technique of hiding from view certain parts of an image (or conversely, only allowing certain parts of an
image to display). The portions of the mask image become transparent, so content underneath shows through. The
term is related to painter’s masking tape that is used to prevent paint from being applied to certain areas.
Stage The visual container that is the base or background of all visual content in a SWF.
Transformation An adjustment to a visual characteristic of a graphic, such as rotating the object, altering its scale,
skewing or distorting its shape, or altering its color.
Vector graphic A graphic that is defined in the computer as lines and shapes drawn with particular characteristics
(such as thickness, length, size, angle, and position).
Last updated 3/21/2011
146
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Display programming
Core display classes
Flash Player 9 and later, Adobe AIR 1.0 and later
The ActionScript 3.0 flash.display package includes classes for visual objects that can appear in Flash Player or AIR.
The following illustration shows the subclass relationships of these core display object classes.
DisplayObject
AVM1Movie
Bitmap
InteractiveObject
DisplayObjectContainer SimpleButton
Loader
Sprite
MorphShape
Shape
StaticText
Video
TextField
Stage
MovieClip
The illustration shows the class inheritance of display object classes. Note that some of these classes, specifically
StaticText, TextField, and Video, are not in the flash.display package, but they still inherit from the DisplayObject class.
All classes that extend the DisplayObject class inherit its methods and properties. For more information, see
“Properties and methods of the DisplayObject class” on page 150.
You can instantiate objects of the following classes contained in the flash.display package:
• Bitmap—You use the Bitmap class to define bitmap objects, either loaded from external files or rendered through
ActionScript. You can load bitmaps from external files through the Loader class. You can load GIF, JPG, or PNG
files. You can also create a BitmapData object with custom data and then create a Bitmap object that uses that data.
You can use the methods of the BitmapData class to alter bitmaps, whether they are loaded or created in
ActionScript. For more information, see “Loading display objects” on page 189 and “Working with bitmaps” on
page 232.
• Loader—You use the Loader class to load external assets (either SWF files or graphics). For more information, see
“Loading display content dynamically” on page 189.
• Shape—You use the Shape class to create vector graphics, such as rectangles, lines, circles, and so on. For more
information, see “Using the drawing API” on page 211.
• SimpleButton—A SimpleButton object is the ActionScript representation of a button symbol created in the Flash
authoring tool. A SimpleButton instance has four button states: up, down, over, and hit test (the area that responds
to mouse and keyboard events).
• Sprite—A Sprite object can contain graphics of its own, and it can contain child display objects. (The Sprite class
extends the DisplayObjectContainer class). For more information, see “Working with display object containers” on
page 151 and “Using the drawing API” on page 211.
Last updated 3/21/2011
147
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Display programming
• MovieClip—A MovieClip object is the ActionScript form of a movie clip symbol created in the Flash authoring
tool. In practice, a MovieClip is similar to a Sprite object, except that it also has a timeline. For more information,
see “Working with movie clips” on page 310.
The following classes, which are not in the flash.display package, are subclasses of the DisplayObject class:
• The TextField class, included in the flash.text package, is a display object for text display and input. For more
information, see “Basics of Working with text” on page 349.
• The TextLine class, included in the flash.text.engine package, is the display object used to display lines of text
composed by the Flash Text Engine and the Text Layout Framework. For more information, see “Using the Flash
Text Engine” on page 375 and “Using the Text Layout Framework” on page 404.
• The Video class, included in the flash.media package, is the display object used for displaying video files. For more
information, see “Working with video” on page 452.
The following classes in the flash.display package extend the DisplayObject class, but you cannot create instances of
them. Instead, they serve as parent classes for other display objects, combining common functionality into a single
class.
• AVM1Movie—The AVM1Movie class is used to represent loaded SWF files that are authored in ActionScript 1.0
and 2.0.
• DisplayObjectContainer—The Loader, Stage, Sprite, and MovieClip classes each extend the
DisplayObjectContainer class. For more information, see “Working with display object containers” on page 151.
• InteractiveObject—InteractiveObject is the base class for all objects used to interact with the mouse and keyboard.
SimpleButton, TextField, Loader, Sprite, Stage, and MovieClip objects are all subclasses of the InteractiveObject
class. For more information on creating mouse and keyboard interaction, see “Basics of user interaction” on
page 523.
• MorphShape—These objects are created when you create a shape tween in the Flash authoring tool. You cannot
instantiate them using ActionScript, but they can be accessed from the display list.
• Stage—The Stage class extends the DisplayObjectContainer class. There is one Stage instance for an application,
and it is at the top of the display list hierarchy. To access the Stage, use the stage property of any DisplayObject
instance. For more information, see “Setting Stage properties” on page 156.
Also, the StaticText class, in the flash.text package, extends the DisplayObject class, but you cannot create an instance
of it in code. Static text fields are created only in Flash.
The following classes are not display objects or display object containers, and do not appear in the display list, but do
display graphics on the stage. These classes draw into a rectangle, called a viewport, positioned relative to the stage.
• StageVideo—The StageVideo class displays video content, using hardware acceleration, when possible. This class
is available starting in Flash Player 10.2 and AIR 2.5 (in the AIR for TV profiles). For more information, see “Using
the StageVideo class for hardware-accelerated rendering” on page 486.
• StageWebView—The StageWebView class displays HTML content. This class is available starting in AIR 2.5. For
more infromation, see “StageWebView objects” on page 997.
Last updated 3/21/2011
148
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Display programming
Advantages of the display list approach
Flash Player 9 and later, Adobe AIR 1.0 and later
In ActionScript 3.0, there are separate classes for different types of display objects. In ActionScript 1.0 and 2.0, many
of the same types of objects are all included in one class: the MovieClip class.
This individualization of classes and the hierarchical structure of display lists have the following benefits:
• More efficient rendering and reduced memory usage
• Improved depth management
• Full traversal of the display list
• Off-list display objects
• Easier subclassing of display objects
More efficient rendering and smaller file sizes
Flash Player 9 and later, Adobe AIR 1.0 and later
In ActionScript 1.0 and 2.0, you could draw shapes only in a MovieClip object. In ActionScript 3.0, there are simpler
display object classes in which you can draw shapes. Because these ActionScript 3.0 display object classes do not
include the full set of methods and properties that a MovieClip object includes, they are less taxing on memory and
processor resources.
For example, each MovieClip object includes properties for the timeline of the movie clip, whereas a Shape object does
not. The properties for managing the timeline can use a lot of memory and processor resources. In ActionScript 3.0,
using the Shape object results in better performance. The Shape object has less overhead than the more complex
MovieClip object. Flash Player and AIR do not need to manage unused MovieClip properties, which improves speed
and reduces the memory footprint the object uses.
Improved depth management
Flash Player 9 and later, Adobe AIR 1.0 and later
In ActionScript 1.0 and 2.0, depth was managed through a linear depth management scheme and methods such as
getNextHighestDepth().
ActionScript 3.0 includes the DisplayObjectContainer class, which has more convenient methods and properties for
managing the depth of display objects.
In ActionScript 3.0, when you move a display object to a new position in the child list of a DisplayObjectContainer
instance, the other children in the display object container are repositioned automatically and assigned appropriate
child index positions in the display object container.
Also, in ActionScript 3.0 it is always possible to discover all of the child objects of any display object container. Every
DisplayObjectContainer instance has a numChildren property, which lists the number of children in the display object
container. And since the child list of a display object container is always an indexed list, you can examine every object
in the list from index position 0 through the last index position (numChildren - 1). This was not possible with the
methods and properties of a MovieClip object in ActionScript 1.0 and 2.0.
Last updated 3/21/2011
149
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Display programming
In ActionScript 3.0, you can easily traverse the display list sequentially; there are no gaps in the index numbers of a
child list of a display object container. Traversing the display list and managing the depth of objects is much easier than
was possible in ActionScript 1.0 and 2.0. In ActionScript 1.0 and 2.0, a movie clip could contain objects with
intermittent gaps in the depth order, which could make it difficult to traverse the list of object. In ActionScript 3.0,
each child list of a display object container is cached internally as an array, resulting in very fast lookups (by index).
Looping through all children of a display object container is also very fast.
In ActionScript 3.0, you can also access children in a display object container by using the getChildByName() method
of the DisplayObjectContainer class.
Full traversal of the display list
Flash Player 9 and later, Adobe AIR 1.0 and later
In ActionScript 1.0 and 2.0, you could not access some objects, such as vector shapes, that were drawn in the Flash
authoring tool. In ActionScript 3.0, you can access all objects on the display list—both those created using ActionScript
and all display objects created in the Flash authoring tool. For details, see “Traversing the display list” on page 155.
Off-list display objects
Flash Player 9 and later, Adobe AIR 1.0 and later
In ActionScript 3.0, you can create display objects that are not on the visible display list. These are known as off-list
display objects. A display object is added to the visible display list only when you call the addChild() or
addChildAt() method of a DisplayObjectContainer instance that has already been added to the display list.
You can use off-list display objects to assemble complex display objects, such as those that have multiple display object
containers containing multiple display objects. By keeping display objects off-list, you can assemble complicated
objects without using the processing time to render these display objects. You can then add an off-list display object
to the display list when it is needed. Also, you can move a child of a display object container on and off the display list
and to any desired position in the display list at will.
Easier subclassing of display objects
Flash Player 9 and later, Adobe AIR 1.0 and later
In ActionScript 1.0 and 2.0, you would often have to add new MovieClip objects to a SWF file to create basic shapes
or to display bitmaps. In ActionScript 3.0, the DisplayObject class includes many built-in subclasses, including Shape
and Bitmap. Because the classes in ActionScript 3.0 are more specialized for specific types of objects, it is easier to
create basic subclasses of the built-in classes.
For example, in order to draw a circle in ActionScript 2.0, you could create a CustomCircle class that extends the
MovieClip class when an object of the custom class is instantiated. However, that class would also include a number
of properties and methods from the MovieClip class (such as totalFrames) that do not apply to the class. In
ActionScript 3.0, however, you can create a CustomCircle class that extends the Shape object, and as such does not
include the unrelated properties and methods that are contained in the MovieClip class. The following code shows an
example of a CustomCircle class:
Last updated 3/21/2011
150
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Display programming
import flash.display.*;
public class CustomCircle extends Shape
{
var xPos:Number;
var yPos:Number;
var radius:Number;
var color:uint;
public function CustomCircle(xInput:Number,
yInput:Number,
rInput:Number,
colorInput:uint)
{
xPos = xInput;
yPos = yInput;
radius = rInput;
color = colorInput;
this.graphics.beginFill(color);
this.graphics.drawCircle(xPos, yPos, radius);
}
}
Working with display objects
Flash Player 9 and later, Adobe AIR 1.0 and later
Now that you understand the basic concepts of the Stage, display objects, display object containers, and the display list,
this section provides you with some more specific information about working with display objects in ActionScript 3.0.
Properties and methods of the DisplayObject class
Flash Player 9 and later, Adobe AIR 1.0 and later
All display objects are subclasses of the DisplayObject class, and as such they inherit the properties and methods of the
DisplayObject class. The properties inherited are basic properties that apply to all display objects. For example, each
display object has an x property and a y property that specifies the object’s position in its display object container.
You cannot create a DisplayObject instance using the DisplayObject class constructor. You must create another type
of object (an object that is a subclass of the DisplayObject class), such as a Sprite, to instantiate an object with the new
operator. Also, if you want to create a custom display object class, you must create a subclass of one of the display object
subclasses that has a usable constructor function (such as the Shape class or the Sprite class). For more information,
see the DisplayObject class description in the ActionScript 3.0 Reference for the Adobe Flash Platform.
Adding display objects to the display list
Flash Player 9 and later, Adobe AIR 1.0 and later
When you instantiate a display object, it will not appear on-screen (on the Stage) until you add the display object
instance to a display object container that is on the display list. For example, in the following code, the myText
TextField object would not be visible if you omitted the last line of code. In the last line of code, the this keyword must
refer to a display object container that is already added to the display list.
Last updated 3/21/2011
151
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Display programming
import flash.display.*;
import flash.text.TextField;
var myText:TextField = new TextField();
myText.text = "Buenos dias.";
this.addChild(myText);
When you add any visual element to the Stage, that element becomes a child of the Stage object. The first SWF file
loaded in an application (for example, the one that you embed in an HTML page) is automatically added as a child of
the Stage. It can be an object of any type that extends the Sprite class.
Any display objects that you create without using ActionScript—for example, by adding an MXML tag in a Flex MXML
file or by placing an item on the Stage in Flash Professional—are added to the display list. Although you do not add
these display objects through ActionScript, you can access them through ActionScript. For example, the following
code adjusts the width of an object named button1 that was added in the authoring tool (not through ActionScript):
button1.width = 200;
Working with display object containers
Flash Player 9 and later, Adobe AIR 1.0 and later
If a DisplayObjectContainer object is deleted from the display list, or if it is moved or transformed in some other way,
each display object in the DisplayObjectContainer is also deleted, moved, or transformed.
A display object container is itself a type of display object—it can be added to another display object container. For
example, the following image shows a display object container, pictureScreen, that contains one outline shape and
four other display object containers (of type PictureFrame):
Last updated 3/21/2011
152
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Display programming
A
B
A. A shape defining the border of the pictureScreen display object container B. Four display object containers that are children of the
pictureScreen object
In order to have a display object appear in the display list, you must add it to a display object container that is on the
display list. You do this by using the addChild() method or the addChildAt() method of the container object. For
example, without the final line of the following code, the myTextField object would not be displayed:
var myTextField:TextField = new TextField();
myTextField.text = "hello";
this.root.addChild(myTextField);
In this code sample, this.root points to the MovieClip display object container that contains the code. In your actual
code, you may specify a different container.
Use the addChildAt() method to add the child to a specific position in the child list of the display object container.
These zero-based index positions in the child list relate to the layering (the front-to-back order) of the display objects.
For example, consider the following three display objects. Each object was created from a custom class called Ball.
Last updated 3/21/2011
153
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Display programming
The layering of these display objects in their container can be adjusted using the addChildAt() method. For example,
consider the following code:
ball_A = new Ball(0xFFCC00, "a");
ball_A.name = "ball_A";
ball_A.x = 20;
ball_A.y = 20;
container.addChild(ball_A);
ball_B = new Ball(0xFFCC00, "b");
ball_B.name = "ball_B";
ball_B.x = 70;
ball_B.y = 20;
container.addChild(ball_B);
ball_C = new Ball(0xFFCC00, "c");
ball_C.name = "ball_C";
ball_C.x = 40;
ball_C.y = 60;
container.addChildAt(ball_C, 1);
After executing this code, the display objects are positioned as follows in the container DisplayObjectContainer
object. Notice the layering of the objects.
To reposition an object to the top of the display list, simply re-add it to the list. For example, after the previous code,
to move ball_A to the top of the stack, use this line of code:
container.addChild(ball_A);
This code effectively removes ball_A from its location in container’s display list, and re-adds it to the top of the list—
which has the end result of moving it to the top of the stack.
You can use the getChildAt() method to verify the layer order of the display objects. The getChildAt() method
returns child objects of a container based on the index number you pass it. For example, the following code reveals
names of display objects at different positions in the child list of the container DisplayObjectContainer object:
trace(container.getChildAt(0).name); // ball_A
trace(container.getChildAt(1).name); // ball_C
trace(container.getChildAt(2).name); // ball_B
If you remove a display object from the parent container’s child list, the higher elements on the list each move down a
position in the child index. For example, continuing with the previous code, the following code shows how the display
object that was at position 2 in the container DisplayObjectContainer moves to position 1 if a display object that is
lower in the child list is removed:
Last updated 3/21/2011
154
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Display programming
container.removeChild(ball_C);
trace(container.getChildAt(0).name); // ball_A
trace(container.getChildAt(1).name); // ball_B
The removeChild() and removeChildAt() methods do not delete a display object instance entirely. They simply
remove it from the child list of the container. The instance can still be referenced by another variable. (Use the delete
operator to completely remove an object.)
Because a display object has only one parent container, you can add an instance of a display object to only one display
object container. For example, the following code shows that the display object tf1 can exist in only one container (in
this case, a Sprite, which extends the DisplayObjectContainer class):
tf1:TextField = new TextField();
tf2:TextField = new TextField();
tf1.name = "text 1";
tf2.name = "text 2";
container1:Sprite = new Sprite();
container2:Sprite = new Sprite();
container1.addChild(tf1);
container1.addChild(tf2);
container2.addChild(tf1);
trace(container1.numChildren); // 1
trace(container1.getChildAt(0).name); // text 2
trace(container2.numChildren); // 1
trace(container2.getChildAt(0).name); // text 1
If you add a display object that is contained in one display object container to another display object container, it is
removed from the first display object container’s child list.
In addition to the methods described above, the DisplayObjectContainer class defines several methods for working
with child display objects, including the following:
•
contains(): Determines whether a display object is a child of a DisplayObjectContainer.
•
getChildByName(): Retrieves a display object by name.
•
getChildIndex(): Returns the index position of a display object.
•
setChildIndex(): Changes the position of a child display object.
•
swapChildren(): Swaps the front-to-back order of two display objects.
•
swapChildrenAt(): Swaps the front-to-back order of two display objects, specified by their index values.
For more information, see the relevant entries in the ActionScript 3.0 Reference for the Adobe Flash Platform.
Recall that a display object that is off the display list—one that is not included in a display object container that is a
child of the Stage—is known as an off-list display object.
Last updated 3/21/2011
155
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Display programming
Traversing the display list
Flash Player 9 and later, Adobe AIR 1.0 and later
As you’ve seen, the display list is a tree structure. At the top of the tree is the Stage, which can contain multiple display
objects. Those display objects that are themselves display object containers can contain other display objects, or display
object containers.
Stage
Instance of
the main class of
the SWF file
Display Object
Container
Display Object
Display Object
Container
Display Object
Display Object
Container
Display Object
Display Object
Container
The DisplayObjectContainer class includes properties and methods for traversing the display list, by means of the child
lists of display object containers. For example, consider the following code, which adds two display objects, title and
pict, to the container object (which is a Sprite, and the Sprite class extends the DisplayObjectContainer class):
var container:Sprite = new Sprite();
var title:TextField = new TextField();
title.text = "Hello";
var pict:Loader = new Loader();
var url:URLRequest = new URLRequest("banana.jpg");
pict.load(url);
pict.name = "banana loader";
container.addChild(title);
container.addChild(pict);
The getChildAt() method returns the child of the display list at a specific index position:
trace(container.getChildAt(0) is TextField); // true
You can also access child objects by name. Each display object has a name property, and if you don’t assign it, Flash
Player or AIR assigns a default value, such as "instance1". For example, the following code shows how to use the
getChildByName() method to access a child display object with the name "banana loader":
Last updated 3/21/2011
156
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Display programming
trace(container.getChildByName("banana loader") is Loader); // true
Using the getChildByName() method can result in slower performance than using the getChildAt() method.
Since a display object container can contain other display object containers as child objects in its display list, you can
traverse the full display list of the application as a tree. For example, in the code excerpt shown earlier, once the load
operation for the pict Loader object is complete, the pict object will have one child display object, which is the
bitmap, loaded. To access this bitmap display object, you can write pict.getChildAt(0). You can also write
container.getChildAt(0).getChildAt(0) (since container.getChildAt(0) == pict).
The following function provides an indented trace() output of the display list from a display object container:
function traceDisplayList(container:DisplayObjectContainer,indentString:String = ""):void
{
var child:DisplayObject;
for (var i:uint=0; i < container.numChildren; i++)
{
child = container.getChildAt(i);
trace(indentString, child, child.name);
if (container.getChildAt(i) is DisplayObjectContainer)
{
traceDisplayList(DisplayObjectContainer(child), indentString + "")
}
}
}
Adobe Flex
If you use Flex, you should know that Flex defines many component display object classes, and these classes override
the display list access methods of the DisplayObjectContainer class. For example, the Container class of the mx.core
package overrides the addChild() method and other methods of the DisplayObjectContainer class (which the
Container class extends). In the case of the addChild() method, the class overrides the method in such a way that you
cannot add all types of display objects to a Container instance in Flex. The overridden method, in this case, requires
that the child object that you are adding be a type of mx.core.UIComponent object.
Setting Stage properties
Flash Player 9 and later, Adobe AIR 1.0 and later
The Stage class overrides most properties and methods of the DisplayObject class. If you call one of these overridden
properties or methods, Flash Player and AIR throw an exception. For example, the Stage object does not have x or y
properties, since its position is fixed as the main container for the application. The x and y properties refer to the
position of a display object relative to its container, and since the Stage is not contained in another display object
container, these properties do not apply.
Note: Some properties and methods of the Stage class are only available to display objects that are in the same security
sandbox as the first SWF file loaded. For details, see “Stage security” on page 1029.
Controlling the playback frame rate
Flash Player 9 and later, Adobe AIR 1.0 and later
The frameRate property of the Stage class is used to set the frame rate for all SWF files loaded into the application.
For more information, see the ActionScript 3.0 Reference for the Adobe Flash Platform.
Last updated 3/21/2011
157
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Display programming
Controlling Stage scaling
Flash Player 9 and later, Adobe AIR 1.0 and later
When the portion of the screen representing Flash Player or AIR is resized, the runtime automatically adjusts the Stage
contents to compensate. The Stage class’s scaleMode property determines how the Stage contents are adjusted. This
property can be set to four different values, defined as constants in the flash.display.StageScaleMode class:
•
StageScaleMode.EXACT_FIT scales the SWF to fill the new stage dimensions without regard for the original
content aspect ratio. The scale factors might not be the same for width and height, so the content can appear
squeezed or stretched if the aspect ratio of the stage is changed.
•
StageScaleMode.SHOW_ALL scales the SWF to fit entirely within the new stage dimensions without changing the
content aspect ratio. This scale mode displays all of the content, but can result in “letterbox” borders, like the black
bars that appear when viewing a wide-screen movie on a standard television.
•
StageScaleMode.NO_BORDER scales the SWF to entirely fill the new stage dimensions without changing the aspect
ratio of the content. This scale mode makes full use of the stage display area, but can result in cropping.
•
StageScaleMode.NO_SCALE — does not scale the SWF. If the new stage dimensions are smaller, the content is
cropped; if larger, the added space is blank.
In the StageScaleMode.NO_SCALE scale mode only, the stageWidth and stageHeight properties of the Stage class
can be used to determine the actual pixel dimensions of the resized stage. (In the other scale modes, the stageWidth
and stageHeight properties always reflect the original width and height of the SWF.) In addition, when
scaleMode is set to StageScaleMode.NO_SCALE and the SWF file is resized, the Stage class’s resize event is
dispatched, allowing you to make adjustments accordingly.
Consequently, having scaleMode set to StageScaleMode.NO_SCALE allows you to have greater control over how
the screen contents adjust to the window resizing if you desire. For example, in a SWF containing a video and a
control bar, you might want to make the control bar stay the same size when the Stage is resized, and only change
the size of the video window to accommodate the Stage size change. This is demonstrated in the following example:
Last updated 3/21/2011
158
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Display programming
// videoScreen is a display object (e.g. a Video instance) containing a
// video; it is positioned at the top-left corner of the Stage, and
// it should resize when the SWF resizes.
//
//
//
//
controlBar is a display object (e.g. a Sprite) containing several
buttons; it should stay positioned at the bottom-left corner of the
Stage (below videoScreen) and it should not resize when the SWF
resizes.
import
import
import
import
flash.display.Stage;
flash.display.StageAlign;
flash.display.StageScaleMode;
flash.events.Event;
var swfStage:Stage = videoScreen.stage;
swfStage.scaleMode = StageScaleMode.NO_SCALE;
swfStage.align = StageAlign.TOP_LEFT;
function resizeDisplay(event:Event):void
{
var swfWidth:int = swfStage.stageWidth;
var swfHeight:int = swfStage.stageHeight;
// Resize the video window.
var newVideoHeight:Number = swfHeight - controlBar.height;
videoScreen.height = newVideoHeight;
videoScreen.scaleX = videoScreen.scaleY;
// Reposition the control bar.
controlBar.y = newVideoHeight;
}
swfStage.addEventListener(Event.RESIZE, resizeDisplay);
Setting the stage scale mode for AIR windows
The stage scaleMode property determines how the stage scales and clips child display objects when a window is
resized. Only the noScale mode should be used in AIR. In this mode, the stage is not scaled. Instead, the size of the
stage changes directly with the bounds of the window. Objects may be clipped if the window is resized smaller.
The stage scale modes are designed for use in a environments such as a web browser where you don't always have
control over the size or aspect ratio of the stage. The modes let you choose the least bad compromise when the stage
does not match the ideal size or aspect ratio of your application. In AIR, you always have control of the stage, so in
most cases re-laying out your content or adjusting the dimensions of your window will give you better results than
enabling stage scaling.
In the browser and for the initial AIR window, the relationship between the window size and the initial scale factor is
read from the loaded SWF file. However, when you create a NativeWindow object, AIR chooses an arbitrary
relationship between the window size and the scale factor of 72:1. Thus, if your window is 72x72 pixels, a 10x10
rectangle added to the window is drawn the correct size of 10x10 pixels. However, if the window is 144x144 pixels, then
a 10x10 pixel rectangle is scaled to 20x20 pixels. If you insist on using a scaleMode other than noScale for a window
stage, you can compensate by setting the scale factor of any display objects in the window to the ratio of 72 pixels to
the current width and height of the stage. For example, the following code calculates the required scale factor for a
display object named client:
Last updated 3/21/2011
159
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Display programming
if(newWindow.stage.scaleMode != StageScaleMode.NO_SCALE){
client.scaleX = 72/newWindow.stage.stageWidth;
client.scaleY = 72/newWindow.stage.stageHeight;
}
Note: Flex and HTML windows automatically set the stage scaleMode to noScale. Changing the scaleMode disturbs
the automatic layout mechanisms used in these types of windows.
Working with full-screen mode
Flash Player 9 and later, Adobe AIR 1.0 and later
Full-screen mode allows you to set a movie’s stage to fill a viewer’s entire monitor without any container borders or
menus. The Stage class’s displayState property is used to toggle full-screen mode on and off for a SWF. The
displayState property can be set to one of the values defined by the constants in the flash.display.StageDisplayState
class. To turn on full-screen mode, set the displayState property to StageDisplayState.FULL_SCREEN:
stage.displayState = StageDisplayState.FULL_SCREEN;
In Flash Player, full-screen mode can only be initiated through ActionScript in response to a mouse click (including
right-click) or keypress. AIR content running in the application security sandbox does not require that full-screen
mode be entered in response to a user gesture.
To exit full-screen mode, set the displayState property to StageDisplayState.NORMAL.
stage.displayState = StageDisplayState.NORMAL;
In addition, a user can choose to leave full-screen mode by switching focus to a different window or by using one of
several key combinations: the Esc key (all platforms), Control-W (Windows), Command-W (Mac), or Alt-F4
(Windows).
Enabling full-screen mode in Flash Player
To enable full-screen mode for a SWF file embedded in an HTML page, the HTML code to embed Flash Player must
include a param tag and embed attribute with the name allowFullScreen and value true, like this:
In the Flash authoring tool, select File -> Publish Settings and in the Publish Settings dialog box, on the HTML tab,
select the Flash Only - Allow Full Screen template.
In Flex, ensure that the HTML template includes
Handling file drops in non-application HTML sandboxes
Adobe AIR 1.0 and later
Non-application content cannot access the File objects that result when files are dragged into an AIR application. Nor
is it possible to pass one of these File objects to application content through a sandbox bridge. (The object properties
must be accessed during serialization.) However, you can still drop files in your application by listening for the AIR
nativeDragDrop events on the HTMLLoader object.
Normally, if a user drops a file into a frame that hosts non-application content, the drop event does not propagate from
the child to the parent. However, since the events dispatched by the HTMLLoader (which is the container for all
HTML content in an AIR application) are not part of the HTML event flow, you can still receive the drop event in
application content.
To receive the event for a file drop, the parent document adds an event listener to the HTMLLoader object using the
reference provided by window.htmlLoader:
window.htmlLoader.addEventListener("nativeDragDrop",function(event){
var filelist = event.clipboard.getData(air.ClipboardFormats.FILE_LIST_FORMAT);
air.trace(filelist[0].url);
});
The following example uses a parent document that loads a child page into a remote sandbox (http://localhost/). The
parent listens for the nativeDragDrop event on the HTMLLoader object and traces out the file url.
Last updated 3/21/2011
590
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Drag and drop in AIR
Drag-and-drop in a remote sandbox
The child document must present a valid drop target by calling the Event object preventDefault() method in the
HTML dragenter and dragover event handlers. Otherwise, the drop event can never occur.
Drag and drop target
Drop Files Here
Dropping file promises
Adobe AIR 2 and later
A file promise is a drag-and-drop clipboard format that allows a user to drag a file that does not yet exist out of an AIR
application. For example, using file promises, your application could allow a user to drag a proxy icon to a desktop
folder. The proxy icon represents a file or some data known to be available at a URL. After the user drops the icon, the
runtime downloads the data and writes the file to the drop location.
You can use the URLFilePromise class in an AIR application to drag-and-drop files accessible at a URL. The
URLFilePromise implementation is provided in the aircore library as part of the AIR 2 SDK. Use either the aircore.swc
or aircore.swf file found in the SDK frameworks/libs/air directory.
Alternately, you can implement your own file promise logic using the IFilePromise interface (which is defined in the
runtime flash.desktop package).
Last updated 3/21/2011
591
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Drag and drop in AIR
File promises are similar in concept to deferred rendering using a data handler function on the clipboard. Use file
promises instead of deferred rendering when dragging and dropping files. The deferred rendering technique can lead
to undesirable pauses in the drag gesture as the data is generated or downloaded. Use deferred rendering for copy and
paste operations (for which file promises are not supported).
Limitations when using file promises
File promises have the following limitations compared to other data formats that you can put in a drag-and-drop
clipboard:
• File promises can only be dragged out of an AIR application; they cannot be dropped into an AIR application.
• File promises are not supported on all operating systems. Use the Clipboard.supportsFilePromise property to
test whether file promises are supported on the host system. On systems that do not support file promises, you
should provide an alternative mechanism for downloading or generating the file data.
• File promises cannot be used with the copy-and-paste clipboard (Clipboard.generalClipboard).
More Help topics
flash.desktop.IFilePromise
air.desktop.URLFilePromise
Dropping remote files
Adobe AIR 2 and later
Use the URLFilePromise class to create file promise objects representing files or data available at a URL. Add one or
more file promise objects to the clipboard using the FILE_PROMISE_LIST clipboard format. In the following example,
a single file, available at http://www.example.com/foo.txt, is downloaded and saved to the drop location as bar.txt. (The
remote and the local file names do not have to match.)
if( Clipboard.supportsFilePromise )
{
var filePromise:URLFilePromise = new URLFilePromise();
filePromise.request = new URLRequest("http://example.com/foo.txt");
filePromise.relativePath = "bar.txt";
var fileList:Array = new Array( filePromise );
var clipboard:Clipboard = new Clipboard();
clipboard.setData( ClipboardFormats.FILE_PROMISE_LIST_FORMAT, fileList );
NativeDragManager.doDrag( dragSource, clipboard );
}
You can allow the user to drag more than one file at a time by adding more file promise objects to the array assigned
to the clipboard. You can also specify subdirectories in the relativePath property so that some or all of the files
included in the operation are placed in a subfolder relative to the drop location.
The following example illustrates how to initiate a drag operation that includes multiple file promises. In this example,
an html page, article.html, is put on the clipboard as a file promise, along with its two linked image files. The images
are copied into an images subfolder so that the relative links are maintained.
Last updated 3/21/2011
592
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Drag and drop in AIR
if( Clipboard.supportsFilePromise )
{
//Create the promise objects
var filePromise:URLFilePromise = new URLFilePromise();
filePromise.request = new URLRequest("http://example.com/article.html");
filePromise.relativePath = "article.html";
var image1Promise:URLFilePromise = new URLFilePromise();
image1Promise.request = new URLRequest("http://example.com/images/img_1.jpg");
image1Promise.relativePath = "images/img_1.html";
var image2Promise:URLFilePromise = new URLFilePromise();
image2Promise.request = new URLRequest("http://example.com/images/img_2.jpg");
image2Promise.relativePath = "images/img_2.jpg";
//Put the promise objects onto the clipboard inside an array
var fileList:Array = new Array( filePromise, image1Promise, image2Promise );
var clipboard:Clipboard = new Clipboard();
clipboard.setData( ClipboardFormats.FILE_PROMISE_LIST_FORMAT, fileList );
//Start the drag operation
NativeDragManager.doDrag( dragSource, clipboard );
}
Implementing the IFilePromise interface
Adobe AIR 2 and later
To provide file promises for resources that cannot be accessed using a URLFilePromise object, you can implement the
IFilePromise interface in a custom class. The IFilePromise interface defines the methods and properties used by the
AIR runtime to access the data to be written to a file once the file promise is dropped.
An IFilePromise implementation passes another object to the AIR runtime that provides the data for the file promise.
This object must implement the IDataInput interface, which the AIR runtime uses to read the data. For example, the
URLFilePromise class, which implements IFilePromise, uses a URLStream object as the data provider.
AIR can read the data synchronously or asynchronously. The IFilePromise implementation reports which mode of
access is supported by returning the appropriate value in the isAsync property. If asynchronous data access is
provided, the data provider object must implement the IEventDispatcher interface and dispatch the necessary events,
such as open, progress and complete.
You can use a custom class, or one of the following built-in classes, as a data provider for a file promise:
• ByteArray (synchronous)
• FileStream (synchronous or asynchronous)
• Socket (asynchronous)
• URLStream (asynchronous)
To implement the IFilePromise interface, you must provide code for the following functions and properties:
•
open():IDataInput — Returns the data provider object from which the data for the promised file is read. The
object must implement the IDataInput interface. If the data is provided asynchronously, the object must also
implement the IEventDispatcher interface and dispatch the necessary events (see “Using an asynchronous data
provider in a file promise” on page 594).
Last updated 3/21/2011
593
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Drag and drop in AIR
•
get relativePath():String — Provides the path, including file name, for the created file. The path is resolved
relative to the drop location chosen by the user in the drag-and-drop operation. To make sure that the path uses
the proper separator character for the host operating system, use the File.separator constant when specifying
paths containing directories. You can add a setter function or use a constructor parameter to allow the path to be
set at runtime.
•
get isAsync():Boolean — Informs the AIR runtime whether the data provider object provides it’s data
asynchronously or synchronously.
•
close():void — Called by the runtime when the data is fully read (or an error prevents further reading). You can
use this function to cleanup resources.
•
reportError( e:ErrorEvent ):void — Called by the runtime when an error reading the data occurs.
All of the IFilePromise methods are called by the runtime during a drag-and-drop operation involving the file promise.
Typically, your application logic should not call any of these methods directly.
Using a synchronous data provider in a file promise
Adobe AIR 2 and later
The simplest way to implement the IFilePromise interface is to use a synchronous data provider object, such as a
ByteArray or a synchronous FileStream. In the following example, a ByteArray object is created, filled with data, and
returned when the open() method is called.
package
{
import
import
import
import
flash.desktop.IFilePromise;
flash.events.ErrorEvent;
flash.utils.ByteArray;
flash.utils.IDataInput;
public class SynchronousFilePromise implements IFilePromise
{
private const fileSize:int = 5000; //size of file data
private var filePath:String = "SynchronousFile.txt";
public function get relativePath():String
{
return filePath;
}
public function get isAsync():Boolean
{
return false;
}
public function open():IDataInput
{
var fileContents:ByteArray = new ByteArray();
//Create some arbitrary data for the file
for( var i:int = 0; i < fileSize; i++ )
Last updated 3/21/2011
594
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Drag and drop in AIR
{
fileContents.writeUTFBytes( 'S' );
}
//Important: the ByteArray is read from the current position
fileContents.position = 0;
return fileContents;
}
public function close():void
{
//Nothing needs to be closed in this case.
}
public function reportError(e:ErrorEvent):void
{
trace("Something went wrong: " + e.errorID + " - " + e.type + ", " + e.text );
}
}
}
In practice, synchronous file promises have limited utility. If the amount of data is small, you could just as easily create
a file in a temporary directory and add a normal file list array to the drag-and-drop clipboard. On the other hand, if
the amount of data is large or generating the data is computationally expensive, a long synchronous process is
necessary. Long synchronous processes can block UI updates for a noticeable amount of time and make your
application seem unresponsive. To avoid this problem, you can create an asynchronous data provider driven by a
timer.
Using an asynchronous data provider in a file promise
Adobe AIR 2 and later
When you use an asynchronous data provider object, the IFilePromise isAsync property must be true and the object
returned by the open() method must implement the IEventDispatcher interface. The runtime listens for several
alternative events so that different built-in objects can be used as a data provider. For example, progress events are
dispatched by FileStream and URLStream objects, whereas socketData events are dispatched by Socket objects. The
runtime listens for the appropriate events from all of these objects.
The following events drive the process of reading the data from the data provider object:
• Event.OPEN — Informs the runtime that the data source is ready.
• ProgressEvent.PROGRESS — Informs the runtime that data is available. The runtime will read the amount of
available data from the data provider object.
• ProgressEvent.SOCKET_DATA — Informs the runtime that data is available. The socketData event is dispatched
by socket-based objects. For other object types, you should dispatch a progress event. (The runtime listens for
both events to detect when data can be read.)
• Event.COMPLETE — Informs the runtime that the data has all been read.
• Event.CLOSE — Informs the runtime that the data has all been read. (The runtime listens for both close and
complete for this purpose.)
• IOErrorEvent.IOERROR — Informs the runtime that an error reading the data has occurred. The runtime aborts
file creation and calls the IFilePromise close() method.
Last updated 3/21/2011
595
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Drag and drop in AIR
• SecurityErrorEvent.SECURITY_ERROR — Informs the runtime that a security error has occurred. The runtime
aborts file creation and calls the IFilePromise close() method.
• HTTPStatusEvent.HTTP_STATUS — Used, along with httpResponseStatus, by the runtime to make sure that
the data available represents the desired content, rather than an error message (such as a 404 page). Objects based
on the HTTP protocol should dispatch this event.
• HTTPStatusEvent.HTTP_RESPONSE_STATUS — Used, along with httpStatus, by the runtime to make sure
that the data available represents the desired content. Objects based on the HTTP protocol should dispatch this
event.
The data provider should dispatch these events in the following sequence:
1 open event
2 progress or socketData events
3 complete or close event
Note: The built-in objects, FileStream, Socket, and URLStream, dispatch the appropriate events automatically.
The following example creates a file promise using a custom, asynchronous data provider. The data provider class
extends ByteArray (for the IDataInput support) and implements the IEventDispatcher interface. At each timer event,
the object generates a chunk of data and dispatches a progress event to inform the runtime that the data is available.
When enough data has been produced, the object dispatches a complete event.
package
{
import flash.events.Event;
import flash.events.EventDispatcher;
import flash.events.IEventDispatcher;
import flash.events.ProgressEvent;
import flash.events.TimerEvent;
import flash.utils.ByteArray;
import flash.utils.Timer;
[Event(name="open", type="flash.events.Event.OPEN")]
[Event(name="complete", type="flash.events.Event.COMPLETE")]
[Event(name="progress", type="flash.events.ProgressEvent")]
[Event(name="ioError", type="flash.events.IOErrorEvent")]
[Event(name="securityError", type="flash.events.SecurityErrorEvent")]
public class AsyncDataProvider extends ByteArray implements IEventDispatcher
{
private var dispatcher:EventDispatcher = new EventDispatcher();
public var fileSize:int = 0; //The number of characters in the file
private const chunkSize:int = 1000; //Amount of data written per event
private var dispatchDataTimer:Timer = new Timer( 100 );
private var opened:Boolean = false;
public function AsyncDataProvider()
{
super();
dispatchDataTimer.addEventListener( TimerEvent.TIMER, generateData );
}
public function begin():void{
dispatchDataTimer.start();
}
Last updated 3/21/2011
596
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Drag and drop in AIR
public function end():void
{
dispatchDataTimer.stop();
}
private function generateData( event:Event ):void
{
if( !opened )
{
var open:Event = new Event( Event.OPEN );
dispatchEvent( open );
opened = true;
}
else if( position + chunkSize < fileSize )
{
for( var i:int = 0; i <= chunkSize; i++ )
{
writeUTFBytes( 'A' );
}
//Set position back to the start of the new data
this.position -= chunkSize;
var progress:ProgressEvent =
new ProgressEvent( ProgressEvent.PROGRESS, false, false, bytesAvailable,
bytesAvailable + chunkSize);
dispatchEvent( progress )
}
else
{
var complete:Event = new Event( Event.COMPLETE );
dispatchEvent( complete );
}
}
//IEventDispatcher implementation
public function addEventListener(type:String, listener:Function,
useCapture:Boolean=false, priority:int=0, useWeakReference:Boolean=false):void
{
dispatcher.addEventListener( type, listener, useCapture, priority, useWeakReference );
}
public function removeEventListener(type:String, listener:Function,
useCapture:Boolean=false):void
Last updated 3/21/2011
597
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Drag and drop in AIR
{
dispatcher.removeEventListener( type, listener, useCapture );
}
public function dispatchEvent(event:Event):Boolean
{
return dispatcher.dispatchEvent( event );
}
public function hasEventListener(type:String):Boolean
{
return dispatcher.hasEventListener( type );
}
public function willTrigger(type:String):Boolean
{
return dispatcher.willTrigger( type );
}
}
}
Note: Because the AsyncDataProvider class in the example extends ByteArray, it cannot also extend EventDispatcher. To
implement the IEventDispatcher interface, the class uses an internal EventDispatcher object and forwards the
IEventDispatcher method calls to that internal object. You could also extend EventDispatcher and implement IDataInput
(or implement both interfaces).
The asynchronous IFilePromise implementation is almost identical to the synchronous implementation. The main
differences are that isAsync returns true and that the open() method returns an asynchronous data object:
package
{
import
import
import
import
flash.desktop.IFilePromise;
flash.events.ErrorEvent;
flash.events.EventDispatcher;
flash.utils.IDataInput;
public class AsynchronousFilePromise extends EventDispatcher implements IFilePromise
{
private var fileGenerator:AsyncDataProvider;
private const fileSize:int = 5000; //size of file data
private var filePath:String = "AsynchronousFile.txt";
public function get relativePath():String
{
return filePath;
}
public function get isAsync():Boolean
{
return true;
}
Last updated 3/21/2011
598
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Drag and drop in AIR
public function open():IDataInput
{
fileGenerator = new AsyncDataProvider();
fileGenerator.fileSize = fileSize;
fileGenerator.begin();
return fileGenerator;
}
public function close():void
{
fileGenerator.end();
}
public function reportError(e:ErrorEvent):void
{
trace("Something went wrong: " + e.errorID + " - " + e.type + ", " + e.text );
}
}
}
Last updated 3/21/2011
599
Chapter 34: Working with menus
Flash Player 9 and later, Adobe AIR 1.0 and later
Use the classes in the context menu API to modify the context menu in web-based Flex and Flash Player applications.
Use the classes in the native menu API to define application, window, context, and pop-up menus in Adobe® AIR®.
Menu basics
Flash Player 9 and later, Adobe AIR 1.0 and later
For a quick explanation and code examples of creating native menus in AIR applications, see the following quick start
articles on the Adobe Developer Connection:
• Adding native menus to an AIR application (Flex)
• Adding native menus to an AIR application (Flash)
The native menu classes allow you to access the native menu features of the operating system on which your
application is running. NativeMenu objects can be used for application menus (available on Mac OS X), window
menus (available on Windows and Linux), context menus, and pop-up menus.
Outside of AIR, you can use the context menu classes to modify the context menu that Flash Player automatically
displays when a user right-clicks or cmd-clicks on an object in your application. (An automatic context menu is not
displayed for AIR applications.)
Menu classes
Flash Player 9 and later, Adobe AIR 1.0 and later
The menu classes include:
Package
Classes
flash.display
•
NativeMenu
•
NativeMenuItem
•
ContextMenu
•
ContextMenuItem
•
Event
•
ContextMenuEvent
flash.ui
flash.events
Last updated 3/21/2011
600
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with menus
Menu varieties
Flash Player 9 and later, Adobe AIR 1.0 and later
AIR supports the following types of menus:
Context menus Context menus open in response to a right-click or command-click on an interactive object in SWF
content or a document element in HTML content.
In the Flash Player runtime, a context menu is automatically displayed. You can use the ContextMenu and
ContextMenuItem classes to add your own commands to the menu. You can also remove some, but not all, of the
built-in commands.
In the AIR runtime, you can create a context menu using either the NativeMenu or the ContextMenu class. In HTML
content in AIR, you can use the Webkit HTML and JavaScript APIs to add context menus to HTML elements.
Application menus (AIR only) An application menu is a global menu that applies to the entire application. Application
menus are supported on Mac OS X, but not on Windows or Linux. On Mac OS X, the operating system automatically
creates an application menu. You can use the AIR menu API to add items and submenus to the standard menus. You
can add listeners for handling the existing menu commands. Or you can remove existing items.
Window menus (AIR only) A window menu is associated with a single window and is displayed below the title bar.
Menus can be added to a window by creating a NativeMenu object and assigning it to the menu property of the
NativeWindow object. Window menus are supported on the Windows and Linux operating systems, but not on Mac
OS X. Native window menus can only be used with windows that have system chrome.
Dock and system tray icon menus (AIR only) These icon menus are similar to context menus and are assigned to an
application icon in the Mac OS X dock or the Windows and Linux notification areas on the taskbar. Dock and system
tray icon menus use the NativeMenu class. On Mac OS X, the items in the menu are added above the standard
operating system items. On Windows or Linux, there is no standard menu.
Pop-up menus (AIR only) An AIR pop-up menu is like a context menu, but is not necessarily associated with a
particular application object or component. Pop-up menus can be displayed anywhere in a window by calling the
display() method of any NativeMenu object.
Custom menus Native menus are drawn entirely by the operating system and, as such, exist outside the Flash and
HTML rendering models. Instead of using native menus, you can always create your own custom, non-native menus
using MXML, ActionScript, or JavaScript (in AIR). Such menus must be fully rendered inside application content.
Flex menus The Adobe® Flex™ framework provides a set of Flex menu components. The Flex menus are drawn by the
runtime rather than the operating system and are not native menus. A Flex menu component can be used for Flex
windows that do not have system chrome. Another benefit of using the Flex menu component is that you can specify
menus declaratively in MXML format. If you are using the Flex Framework, use the Flex menu classes for window
menus instead of the native classes.
Default menus (AIR only)
The following default menus are provided by the operating system or a built-in AIR class:
• Application menu on Mac OS X
• Dock icon menu on Mac OS X
• Context menu for selected text and images in HTML content
• Context menu for selected text in a TextField object (or an object that extends TextField)
Last updated 3/21/2011
601
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with menus
About context menus
Flash Player 9 and later, Adobe AIR 1.0 and later
In SWF content, any object that inherits from InteractiveObject can be given a context menu by assigning a menu
object to its contextMenu property. Several commands are included by default, including Forward, Back, Print,
Quality, and Zoom. In the AIR runtime, the menu object assigned to contextMenu can either be of type NativeMenu
or of type ContextMenu. In the Flash Player runtime, only the ContextMenu class is available.
You can listen for either native menu events or context menus events when using the ContextMenu and
ContextMenuItem classes; both are dispatched. One benefit provided by the ContextMenuEvent object properties is
that contextMenuOwner identifies the object to which the menu is attached and mouseTarget identifies the object
that was clicked to open the menu. This information is not available from the NativeMenuEvent object.
The following example creates a Sprite and adds a simple edit context menu:
var sprite:Sprite = new Sprite();
sprite.contextMenu = createContextMenu()
private function createContextMenu():ContextMenu{
var editContextMenu:ContextMenu = new ContextMenu();
var cutItem:ContextMenuItem = new ContextMenuItem("Cut")
cutItem.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT, doCutCommand);
editContextMenu.customItems.push(cutItem);
var copyItem:ContextMenuItem = new ContextMenuItem("Copy")
copyItem.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT, doCopyCommand);
editContextMenu.customItems.push(copyItem);
var pasteItem:ContextMenuItem = new ContextMenuItem("Paste")
pasteItem.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT, doPasteCommand);
editContextMenu.customItems.push(pasteItem);
return editContextMenu
}
private function doCutCommand(event:ContextMenuEvent):void{trace("cut");}
private function doCopyCommand(event:ContextMenuEvent):void{trace("copy");}
private function doPasteCommand(event:ContextMenuEvent):void{trace("paste");}
Note: In contrast to SWF content displayed in a browser environment, context menus in AIR do not have any built-in
commands.
Customizing a Flash Player context menu
In a browser or a projector, context menus in SWF content always have built-in items. You can remove all of these
default commands from the menu, except for the Settings and About commands. Setting the Stage property
showDefaultContextMenu to false removes these commands from the context menu.
To create a customized context menu for a specific display object, create a new instance of the ContextMenu class, call
the hideBuiltInItems() method, and assign that instance to the contextMenu property of that DisplayObject
instance. The following example provides a dynamically drawn square with a context menu command to change it to
a random color:
Last updated 3/21/2011
602
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with menus
var square:Sprite = new Sprite();
square.graphics.beginFill(0x000000);
square.graphics.drawRect(0,0,100,100);
square.graphics.endFill();
square.x =
square.y = 10;
addChild(square);
var menuItem:ContextMenuItem = new ContextMenuItem("Change Color");
menuItem.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT,changeColor);
var customContextMenu:ContextMenu = new ContextMenu();
customContextMenu.hideBuiltInItems();
customContextMenu.customItems.push(menuItem);
square.contextMenu = customContextMenu;
function changeColor(event:ContextMenuEvent):void
{
square.transform.colorTransform = getRandomColor();
}
function getRandomColor():ColorTransform
{
return new ColorTransform(Math.random(), Math.random(), Math.random(),1,(Math.random() *
512) - 255, (Math.random() * 512) -255, (Math.random() * 512) - 255, 0);
}
Native menu structure (AIR)
Adobe AIR 1.0 and later
Native menus are hierarchical in nature. NativeMenu objects contain child NativeMenuItem objects.
NativeMenuItem objects that represent submenus, in turn, can contain NativeMenu objects. The top- or root-level
menu object in the structure represents the menu bar for application and window menus. (Context, icon, and pop-up
menus don’t have a menu bar).
Last updated 3/21/2011
603
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with menus
The following diagram illustrates the structure of a typical menu. The root menu represents the menu bar and contains
two menu items referencing a File submenu and an Edit submenu. The File submenu in this structure contains two
command items and an item that references an Open Recent Menu submenu, which, itself, contains three items. The
Edit submenu contains three commands and a separator.
NativeMenu
Root Menu
NativeMenuItem
“File”
NativeMenu
File Menu
NativeMenuItem
“New”
NativeMenuItem
“Save”
NativeMenuItem
“Open Recent”
NativeMenu
NativeMenuItem
NativeMenu
Open Recent Menu
NativeMenuItem
“GreatGatsby.pdf”
NativeMenuItem
“WarAndPeace.pdf”
NativeMenuItem
“Iliad.pdf”
“Edit”
Edit Menu
NativeMenuItem
“Copy”
NativeMenuItem
“Paste”
NativeMenuItem
Separator
NativeMenuItem
“Preferences”
Defining a submenu requires both a NativeMenu and a NativeMenuItem object. The NativeMenuItem object defines
the label displayed in the parent menu and allows the user to open the submenu. The NativeMenu object serves as a
container for items in the submenu. The NativeMenuItem object references the NativeMenu object through the
NativeMenuItem submenu property.
To view a code example that creates this menu see “Native menu example: Window and application menu (AIR)” on
page 611.
Menu events
Adobe AIR 1.0 and later
NativeMenu and NativeMenuItem objects both dispatch preparing, displaying, and select events:
Preparing: Whenever the object is about to begin a user interaction, the menu and its menu items dispatch a
preparing event to any registered listeners. Interaction includes opening the menu or selecting an item with a
keyboard shortcut.
Last updated 3/21/2011
604
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with menus
Note: The preparing event is available only for Adobe AIR 2.6 and later.
Displaying: Immediately before a menu is displayed, the menu and its menu items dispatch a displaying event to
any registered listeners.
The preparing and displaying events give you an opportunity to update the menu contents or item appearance
before it is shown to the user. For example, in the listener for the displaying event of an “Open Recent” menu, you
could change the menu items to reflect the current list of recently viewed documents.
If you remove the menu item whose keyboard shortcut triggered a preparing event, the menu interaction is effectively
canceled and a select event is not dispatched.
The target and currentTarget properties of the event are both the object on which the listener is registered: either
the menu itself, or one of its items.
The preparing event is dispatched before the displaying event. You typically listen for one event or the other, not both.
Select: When a command item is chosen by the user, the item dispatches a select event to any registered listeners.
Submenu and separator items cannot be selected and so never dispatch a select event.
A select event bubbles up from a menu item to its containing menu, on up to the root menu. You can listen for
select events directly on an item and you can listen higher up in the menu structure. When you listen for the select
event on a menu, you can identify the selected item using the event target property. As the event bubbles up through
the menu hierarchy, the currentTarget property of the event object identifies the current menu object.
Note: ContextMenu and ContextMenuItem objects dispatch menuItemSelect and menuSelect events as well as
select, preparing, and displaying events.
Key equivalents for native menu commands (AIR)
Adobe AIR 1.0 and later
You can assign a key equivalent (sometimes called an accelerator) to a menu command. The menu item dispatches a
select event to any registered listeners when the key, or key combination is pressed. The menu containing the item
must be part of the menu of the application or the active window for the command to be invoked.
Key equivalents have two parts, a string representing the primary key and an array of modifier keys that must also be
pressed. To assign the primary key, set the menu item keyEquivalent property to the single character string for that
key. If you use an uppercase letter, the shift key is added to the modifier array automatically.
On Mac OS X, the default modifier is the command key (Keyboard.COMMAND). On Windows and Linux, it is the
control key (Keyboard.CONTROL). These default keys are automatically added to the modifier array. To assign
different modifier keys, assign a new array containing the desired key codes to the keyEquivalentModifiers
property. The default array is overwritten. Whether you use the default modifiers or assign your own modifier array,
the shift key is added if the string you assign to the keyEquivalent property is an uppercase letter. Constants for the
key codes to use for the modifier keys are defined in the Keyboard class.
The assigned key equivalent string is automatically displayed beside the menu item name. The format depends on the
user’s operating system and system preferences.
Note: If you assign the Keyboard.COMMAND value to a key modifier array on the Windows operating system, no key
equivalent is displayed in the menu. However, the control key must be used to activate the menu command.
The following example assigns Ctrl+Shift+G as the key equivalent for a menu item:
var item:NativeMenuItem = new NativeMenuItem("Ungroup");
item.keyEquivalent = "G";
Last updated 3/21/2011
605
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with menus
This example assigns Ctrl+Shift+G as the key equivalent by setting the modifier array directly:
var item:NativeMenuItem = new NativeMenuItem("Ungroup");
item.keyEquivalent = "G";
item.keyEquivalentModifiers = [Keyboard.CONTROL];
Note: Key equivalents are only triggered for application and window menus. If you add a key equivalent to a context or
pop-up menu, the key equivalent is displayed in the menu label, but the associated menu command is never invoked.
Mnemonics (AIR)
Adobe AIR 1.0 and later
Mnemonics are part of the operating system keyboard interface to menus. Linux, Mac OS X, and Windows allow users
to open menus and select commands with the keyboard, but there are subtle differences.
On Mac OS X, the user types the first letter or two of the menu or command and then presses the return key. The
mnemonicIndex property is ignored.
On Windows, only a single letter is significant. By default, the significant letter is the first character in the label, but if
you assign a mnemonic to the menu item, then the significant character becomes the designated letter. If two items in
a menu have the same significant character (whether or not a mnemonic has been assigned), then the user’s keyboard
interaction with the menu changes slightly. Instead of pressing a single letter to select the menu or command, the user
must press the letter as many times as necessary to highlight the desired item and then press the enter key to complete
the selection. To maintain a consistent behavior, you should assign a unique mnemonic to each item in a menu for
window menus.
On Linux, no default mnemonic is provided. You must specify a value for the mnemonicIndex property of a menu item
to provide a mnemonic.
Specify the mnemonic character as an index into the label string. The index of the first character in a label is 0. Thus,
to use “r” as the mnemonic for a menu item labeled, “Format,” you would set the mnemonicIndex property equal to 2.
var item:NativeMenuItem = new NativeMenuItem("Format");
item.mnemonicIndex = 2;
Menu item state
Adobe AIR 1.0 and later
Menu items have the two state properties, checked and enabled:
checked Set to true to display a check mark next to the item label.
var item:NativeMenuItem = new NativeMenuItem("Format");
item.checked = true;
enabled Toggle the value between true and false to control whether the command is enabled. Disabled items are
visually “grayed-out” and do not dispatch select events.
var item:NativeMenuItem = new NativeMenuItem("Format");
item.enabled = false;
Last updated 3/21/2011
606
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with menus
Attaching an object to a menu item
Adobe AIR 1.0 and later
The data property of the NativeMenuItem class allows you to reference an arbitrary object in each item. For example,
in an “Open Recent” menu, you could assign the File object for each document to each menu item.
var file:File = File.applicationStorageDirectory.resolvePath("GreatGatsby.pdf")
var menuItem:NativeMenuItem = docMenu.addItem(new NativeMenuItem(file.name));
menuItem.data = file;
Creating native menus (AIR)
Adobe AIR 1.0 and later
This topic describes how to create the various types of native menu supported by AIR.
Creating a root menu object
Adobe AIR 1.0 and later
To create a NativeMenu object to serve as the root of the menu, use the NativeMenu constructor:
var root:NativeMenu = new NativeMenu();
For application and window menus, the root menu represents the menu bar and should only contain items that open
submenus. Context menu and pop-up menus do not have a menu bar, so the root menu can contain commands and
separator lines as well as submenus.
After the menu is created, you can add menu items. Items appear in the menu in the order in which they are added,
unless you add the items at a specific index using the addItemAt() method of a menu object.
Assign the menu as an application, window, icon, or context menu, or display it as a pop-up menu as shown in the
following sections:
Setting the application menu or window menu
It’s important that your code accommodate both application menus (supported on Mac OS) and window menus
(supported on other operating systems)
var root:NativeMenu = new NativeMenu();
if (NativeApplication.supportsMenu)
{
NativeApplication.nativeApplication.menu = root;
}
else if (NativeWindow.supportsMenu)
{
nativeWindow.menu = root;
}
Note: Mac OS defines a menu containing standard items for every application. Assigning a new NativeMenu object to
the menu property of the NativeApplication object replaces the standard menu. You can also use the standard menu
instead of replacing it.
Last updated 3/21/2011
607
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with menus
The Adobe Flex provides a FlexNativeMenu class for easily creating menus that work across platforms. If you are using
the Flex Framework, use the FlexNativeMenu classes instead of the NativeMenu class.
Setting a context menu on an interactive object
interactiveObject.contextMenu = root;
Setting a dock icon menu or system tray icon menu
It’s important that your code accommodate both application menus (supported on Mac OS) and window menus
(supported on other operating systems)
if (NativeApplication.supportsSystemTrayIcon)
{
SystemTrayIcon(NativeApplication.nativeApplication.icon).menu = root;
}
else if (NativeApplication.supportsDockIcon)
{
DockIcon(NativeApplication.nativeApplication.icon).menu = root;
}
Note: Mac OS X defines a standard menu for the application dock icon. When you assign a new NativeMenu to the menu
property of the DockIcon object, the items in that menu are displayed above the standard items. You cannot remove,
access, or modify the standard menu items.
Displaying a menu as a pop-up
root.display(stage, x, y);
More Help topics
Developing cross-platform AIR applications
Creating a submenu
Adobe AIR 1.0 and later
To create a submenu, you add a NativeMenuItem object to the parent menu and then assign the NativeMenu object
defining the submenu to the item’s submenu property. AIR provides two ways to create submenu items and their
associated menu object:
You can create a menu item and its related menu object in one step with the addSubmenu() method:
var editMenuItem:NativeMenuItem = root.addSubmenu(new NativeMenu(), "Edit");
You can also create the menu item and assign the menu object to its submenu property separately:
var editMenuItem:NativeMenuItem = root.addItem("Edit", false);
editMenuItem.submenu = new NativeMenu();
Creating a menu command
Adobe AIR 1.0 and later
To create a menu command, add a NativeMenuItem object to a menu and add an event listener referencing the
function implementing the menu command:
Last updated 3/21/2011
608
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with menus
var copy:NativeMenuItem = new NativeMenuItem("Copy", false);
copy.addEventListener(Event.SELECT, onCopyCommand);
editMenu.addItem(copy);
You can listen for the select event on the command item itself (as shown in the example), or you can listen for the
select event on a parent menu object.
Note: Menu items that represent submenus and separator lines do not dispatch select events and so cannot be used as
commands.
Creating a menu separator line
Adobe AIR 1.0 and later
To create a separator line, create a NativeMenuItem, setting the isSeparator parameter to true in the constructor.
Then add the separator item to the menu in the correct location:
var separatorA:NativeMenuItem = new NativeMenuItem("A", true);
editMenu.addItem(separatorA);
The label specified for the separator, if any, is not displayed.
About context menus in HTML (AIR)
Adobe AIR 1.0 and later
In HTML content displayed using the HTMLLoader object, the contextmenu event can be used to display a context
menu. By default, a context menu is displayed automatically when the user invokes the context menu event on selected
text (by right-clicking or command-clicking the text). To prevent the default menu from opening, listen for the
contextmenu event and call the event object’s preventDefault() method:
function showContextMenu(event){
event.preventDefault();
}
You can then display a custom context menu using DHTML techniques or by displaying an AIR native context menu.
The following example displays a native context menu by calling the menu display() method in response to the
HTML contextmenu event:
Last updated 3/21/2011
609
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with menus
Custom context
menu.
Displaying pop-up native menus (AIR)
Adobe AIR 1.0 and later
You can display any NativeMenu object at an arbitrary time and location above a window, by calling the menu
display() method. The method requires a reference to the stage; thus, only content in the application sandbox can
display a menu as a pop-up.
The following method displays the menu defined by a NativeMenu object named popupMenu in response to a mouse
click:
private function onMouseClick(event:MouseEvent):void {
popupMenu.display(event.target.stage, event.stageX, event.stageY);
}
Note: The menu does not need to be displayed in direct response to an event. Any method can call the display()
function.
Last updated 3/21/2011
610
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with menus
Handling menu events
Flash Player 9 and later, Adobe AIR 1.0 and later
A menu dispatches events when the user selects the menu or when the user selects a menu item.
Events summary for menu classes
Flash Player 9 and later, Adobe AIR 1.0 and later
Add event listeners to menus or individual items to handle menu events.
Object
Events dispatched
NativeMenu (AIR)
Event.PREPARING (Adobe AIR 2.6 and later)
Event.DISPLAYING
Event.SELECT (propagated from child items and submenus)
NativeMenuItem (AIR)
Event.PREPARING (Adobe AIR 2.6 and later)
Event.SELECT
Event.DISPLAYING (propagated from parent menu)
ContextMenu
ContextMenuEvent.MENU_SELECT
ContextMenuItem
ContextMenuEvent.MENU_ITEM_SELECT
Event.SELECT (AIR)
Select menu events
Adobe AIR 1.0 and later
To handle a click on a menu item, add an event listener for the select event to the NativeMenuItem object:
var menuCommandX:NativeMenuItem = new NativeMenuItem("Command X");
menuCommandX.addEventListener(Event.SELECT, doCommandX)
Because select events bubble up to the containing menus, you can also listen for select events on a parent menu.
When listening at the menu level, you can use the event object target property to determine which menu command
was selected. The following example traces the label of the selected command:
Last updated 3/21/2011
611
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with menus
var colorMenuItem:NativeMenuItem = new NativeMenuItem("Choose a color");
var colorMenu:NativeMenu = new NativeMenu();
colorMenuItem.submenu = colorMenu;
var red:NativeMenuItem = new NativeMenuItem("Red");
var green:NativeMenuItem = new NativeMenuItem("Green");
var blue:NativeMenuItem = new NativeMenuItem("Blue");
colorMenu.addItem(red);
colorMenu.addItem(green);
colorMenu.addItem(blue);
if(NativeApplication.supportsMenu){
NativeApplication.nativeApplication.menu.addItem(colorMenuItem);
NativeApplication.nativeApplication.menu.addEventListener(Event.SELECT, colorChoice);
} else if (NativeWindow.supportsMenu){
var windowMenu:NativeMenu = new NativeMenu();
this.stage.nativeWindow.menu = windowMenu;
windowMenu.addItem(colorMenuItem);
windowMenu.addEventListener(Event.SELECT, colorChoice);
}
function colorChoice(event:Event):void {
var menuItem:NativeMenuItem = event.target as NativeMenuItem;
trace(menuItem.label + " has been selected");
}
If you are using the ContextMenuItem class, you can listen for either the select event or the menuItemSelect event.
The menuItemSelect event gives you additional information about the object owning the context menu, but does not
bubble up to the containing menus.
Displaying menu events
Adobe AIR 1.0 and later
To handle the opening of a menu, you can add a listener for the displaying event, which is dispatched before a menu
is displayed. You can use the displaying event to update the menu, for example by adding or removing items, or by
updating the enabled or checked states of individual items. You can also listen for the menuSelect event from a
ContextMenu object.
In AIR 2.6 and later, you can use the preparing event to update a menu in response to either displaying a menu or
selecting an item with a keyboard shortcut.
Native menu example: Window and application menu
(AIR)
Adobe AIR 1.0 and later
The following example creates the menu shown in “Native menu structure (AIR)” on page 602.
Last updated 3/21/2011
612
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with menus
The menu is designed to work both on Windows, for which only window menus are supported, and on Mac OS X, for
which only application menus are supported. To make the distinction, the MenuExample class constructor checks the
static supportsMenu properties of the NativeWindow and NativeApplication classes. If
NativeWindow.supportsMenu is true, then the constructor creates a NativeMenu object for the window and then
creates and adds the File and Edit submenus. If NativeApplication.supportsMenu is true, then the constructor
creates and adds the File and Edit menus to the existing menu provided by the Mac OS X operating system.
The example also illustrates menu event handling. The select event is handled at the item level and also at the menu
level. Each menu in the chain from the menu containing the selected item to the root menu responds to the select
event. The displaying event is used with the “Open Recent” menu. Just before the menu is opened, the items in the
menu are refreshed from the recent Documents array (which doesn’t actually change in this example). Although not
shown in this example, you can also listen for displaying events on individual items.
package {
import
import
import
import
import
import
import
flash.display.NativeMenu;
flash.display.NativeMenuItem;
flash.display.NativeWindow;
flash.display.Sprite;
flash.events.Event;
flash.filesystem.File;
flash.desktop.NativeApplication;
public class MenuExample extends Sprite
{
private var recentDocuments:Array =
new Array(new File("app-storage:/GreatGatsby.pdf"),
new File("app-storage:/WarAndPeace.pdf"),
new File("app-storage:/Iliad.pdf"));
public function MenuExample()
{
var fileMenu:NativeMenuItem;
var editMenu:NativeMenuItem;
if (NativeWindow.supportsMenu){
stage.nativeWindow.menu = new NativeMenu();
stage.nativeWindow.menu.addEventListener(Event.SELECT, selectCommandMenu);
fileMenu = stage.nativeWindow.menu.addItem(new NativeMenuItem("File"));
fileMenu.submenu = createFileMenu();
editMenu = stage.nativeWindow.menu.addItem(new NativeMenuItem("Edit"));
editMenu.submenu = createEditMenu();
}
if (NativeApplication.supportsMenu){
NativeApplication.nativeApplication.menu.addEventListener(Event.SELECT,
selectCommandMenu);
fileMenu = NativeApplication.nativeApplication.menu.addItem(new
NativeMenuItem("File"));
fileMenu.submenu = createFileMenu();
editMenu = NativeApplication.nativeApplication.menu.addItem(new
NativeMenuItem("Edit"));
editMenu.submenu = createEditMenu();
}
}
public function createFileMenu():NativeMenu {
Last updated 3/21/2011
613
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with menus
var fileMenu:NativeMenu = new NativeMenu();
fileMenu.addEventListener(Event.SELECT, selectCommandMenu);
var newCommand:NativeMenuItem = fileMenu.addItem(new NativeMenuItem("New"));
newCommand.addEventListener(Event.SELECT, selectCommand);
var saveCommand:NativeMenuItem = fileMenu.addItem(new NativeMenuItem("Save"));
saveCommand.addEventListener(Event.SELECT, selectCommand);
var openRecentMenu:NativeMenuItem =
fileMenu.addItem(new NativeMenuItem("Open Recent"));
openRecentMenu.submenu = new NativeMenu();
openRecentMenu.submenu.addEventListener(Event.DISPLAYING,
updateRecentDocumentMenu);
openRecentMenu.submenu.addEventListener(Event.SELECT, selectCommandMenu);
return fileMenu;
}
public function createEditMenu():NativeMenu {
var editMenu:NativeMenu = new NativeMenu();
editMenu.addEventListener(Event.SELECT, selectCommandMenu);
var copyCommand:NativeMenuItem = editMenu.addItem(new NativeMenuItem("Copy"));
copyCommand.addEventListener(Event.SELECT, selectCommand);
copyCommand.keyEquivalent = "c";
var pasteCommand:NativeMenuItem =
editMenu.addItem(new NativeMenuItem("Paste"));
pasteCommand.addEventListener(Event.SELECT, selectCommand);
pasteCommand.keyEquivalent = "v";
editMenu.addItem(new NativeMenuItem("", true));
var preferencesCommand:NativeMenuItem =
editMenu.addItem(new NativeMenuItem("Preferences"));
preferencesCommand.addEventListener(Event.SELECT, selectCommand);
return editMenu;
}
private function updateRecentDocumentMenu(event:Event):void {
trace("Updating recent document menu.");
var docMenu:NativeMenu = NativeMenu(event.target);
for each (var item:NativeMenuItem in docMenu.items) {
docMenu.removeItem(item);
}
for each (var file:File in recentDocuments) {
var menuItem:NativeMenuItem =
docMenu.addItem(new NativeMenuItem(file.name));
menuItem.data = file;
menuItem.addEventListener(Event.SELECT, selectRecentDocument);
}
}
private function selectRecentDocument(event:Event):void {
trace("Selected recent document: " + event.target.data.name);
}
private function selectCommand(event:Event):void {
Last updated 3/21/2011
614
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with menus
trace("Selected command: " + event.target.label);
}
private function selectCommandMenu(event:Event):void {
if (event.currentTarget.parent != null) {
var menuItem:NativeMenuItem =
findItemForMenu(NativeMenu(event.currentTarget));
if (menuItem != null) {
trace("Select event for \"" +
event.target.label +
"\" command handled by menu: " +
menuItem.label);
}
} else {
trace("Select event for \"" +
event.target.label +
"\" command handled by root menu.");
}
}
private function findItemForMenu(menu:NativeMenu):NativeMenuItem {
for each (var item:NativeMenuItem in menu.parent.items) {
if (item != null) {
if (item.submenu == menu) {
return item;
}
}
}
return null;
}
}
}
Last updated 3/21/2011
615
Chapter 35: Taskbar icons in AIR
Adobe AIR 1.0 and later
Many operating systems provide a taskbar, such as the Mac OS X dock, that can contain an icon to represent an
application. Adobe® AIR® provides an interface for interacting with the application task bar icon through the
NativeApplication.nativeApplication.icon property.
• Using the system tray and dock icons (Flex)
• Using the system tray and dock icons (Flash)
More Help topics
flash.desktop.NativeApplication
flash.desktop.DockIcon
flash.desktop.SystemTrayIcon
About taskbar icons
Adobe AIR 1.0 and later
AIR creates the NativeApplication.nativeApplication.icon object automatically. The object type is either
DockIcon or SystemTrayIcon, depending on the operating system. You can determine which of these InteractiveIcon
subclasses that AIR supports on the current operating system using the NativeApplication.supportsDockIcon
and NativeApplication.supportsSystemTrayIcon properties. The InteractiveIcon base class provides the
properties width, height, and bitmaps, which you can use to change the image used for the icon. However, accessing
properties specific to DockIcon or SystemTrayIcon on the wrong operating system generates a runtime error.
To set or change the image used for an icon, create an array containing one or more images and assign it to the
NativeApplication.nativeApplication.icon.bitmaps property. The size of taskbar icons can be different on
different operating systems. To avoid image degradation due to scaling, you can add multiple sizes of images to the
bitmaps array. If you provide more than one image, AIR selects the size closest to the current display size of the taskbar
icon, scaling it only if necessary. The following example sets the image for a taskbar icon using two images:
NativeApplication.nativeApplication.icon.bitmaps =
[bmp16x16.bitmapData, bmp128x128.bitmapData];
To change the icon image, assign an array containing the new image or images to the bitmaps property. You can
animate the icon by changing the image in response to an enterFrame or timer event.
To remove the icon from the notification area on Windows and Linux, or to restore the default icon appearance on
Mac OS X, set bitmaps to an empty array:
NativeApplication.nativeApplication.icon.bitmaps = [];
Last updated 3/21/2011
616
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Taskbar icons in AIR
Dock icons
Adobe AIR 1.0 and later
AIR supports dock icons when NativeApplication.supportsDockIcon is true. The
NativeApplication.nativeApplication.icon property represents the application icon on the dock (not a
window dock icon).
Note: AIR does not support changing window icons on the dock under Mac OS X. Also, changes to the application dock
icon only apply while an application is running — the icon reverts to its normal appearance when the application
terminates.
Dock icon menus
Adobe AIR 1.0 and later
You can add commands to the standard dock menu by creating a NativeMenu object containing the commands and
assigning it to the NativeApplication.nativeApplication.icon.menu property. The items in the menu are
displayed above the standard dock icon menu items.
Bouncing the dock
Adobe AIR 1.0 and later
You can bounce the dock icon by calling the NativeApplication.nativeApplication.icon.bounce() method. If
you set the bounce() priority parameter to informational, then the icon bounces once. If you set it to critical, then
the icon bounces until the user activates the application. Constants for the priority parameter are defined in the
NotificationType class.
Note: The icon does not bounce if the application is already active.
Dock icon events
Adobe AIR 1.0 and later
When the dock icon is clicked, the NativeApplication object dispatches an invoke event. If the application is not
running, the system launches it. Otherwise, the invoke event is delivered to the running application instance.
System Tray icons
Adobe AIR 1.0 and later
AIR supports system tray icons when NativeApplication.supportsSystemTrayIcon is true, which is currently
the case only on Windows and most Linux distributions. On Windows and Linux, system tray icons are displayed in
the notification area of the taskbar. No icon is displayed by default. To show an icon, assign an array containing
BitmapData objects to the icon bitmaps property. To change the icon image, assign an array containing the new
images to bitmaps. To remove the icon, set bitmaps to null.
Last updated 3/21/2011
617
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Taskbar icons in AIR
System tray icon menus
Adobe AIR 1.0 and later
You can add a menu to the system tray icon by creating a NativeMenu object and assigning it to the
NativeApplication.nativeApplication.icon.menu property (no default menu is provided by the operating
system). Access the system tray icon menu by right-clicking the icon.
System tray icon tooltips
Adobe AIR 1.0 and later
Add a tooltip to an icon by setting the tooltip property:
NativeApplication.nativeApplication.icon.tooltip = "Application name";
System tray icon events
Adobe AIR 1.0 and later
The SystemTrayIcon object referenced by the NativeApplication.nativeApplication.icon property dispatches a
ScreenMouseEvent for click, mouseDown, mouseUp, rightClick, rightMouseDown, and rightMouseUp events. You
can use these events, along with an icon menu, to allow users to interact with your application when it has no visible
windows.
Example: Creating an application with no windows
Adobe AIR 1.0 and later
The following example creates an AIR application which has a system tray icon, but no visible windows. (The visible
property of the application must not be set to true in the application descriptor, or the window will be visible when
the application starts up.)
package
{
import
import
import
import
import
import
import
import
import
import
flash.display.Loader;
flash.display.NativeMenu;
flash.display.NativeMenuItem;
flash.display.NativeWindow;
flash.display.Sprite;
flash.desktop.DockIcon;
flash.desktop.SystemTrayIcon;
flash.events.Event;
flash.net.URLRequest;
flash.desktop.NativeApplication;
public class SysTrayApp extends Sprite
{
public function SysTrayApp():void{
NativeApplication.nativeApplication.autoExit = false;
var icon:Loader = new Loader();
var iconMenu:NativeMenu = new NativeMenu();
var exitCommand:NativeMenuItem = iconMenu.addItem(new NativeMenuItem("Exit"));
exitCommand.addEventListener(Event.SELECT, function(event:Event):void {
Last updated 3/21/2011
618
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Taskbar icons in AIR
NativeApplication.nativeApplication.icon.bitmaps = [];
NativeApplication.nativeApplication.exit();
});
if (NativeApplication.supportsSystemTrayIcon) {
NativeApplication.nativeApplication.autoExit = false;
icon.contentLoaderInfo.addEventListener(Event.COMPLETE, iconLoadComplete);
icon.load(new URLRequest("icons/AIRApp_16.png"));
var systray:SystemTrayIcon =
NativeApplication.nativeApplication.icon as SystemTrayIcon;
systray.tooltip = "AIR application";
systray.menu = iconMenu;
}
if (NativeApplication.supportsDockIcon){
icon.contentLoaderInfo.addEventListener(Event.COMPLETE,iconLoadComplete);
icon.load(new URLRequest("icons/AIRApp_128.png"));
var dock:DockIcon = NativeApplication.nativeApplication.icon as DockIcon;
dock.menu = iconMenu;
}
}
private function iconLoadComplete(event:Event):void
{
NativeApplication.nativeApplication.icon.bitmaps =
[event.target.content.bitmapData];
}
}
}
Note: When using the Flex WindowedApplication component, you must set the visible attribute of the
WindowedApplication tag to false. This attribute supercedes the setting in the application descriptor.
Note: The example assumes that there are image files named AIRApp_16.png and AIRApp_128.png in an icons
subdirectory of the application. (Sample icon files, which you can copy to your project folder, are included in the AIR SDK.)
Window taskbar icons and buttons
Adobe AIR 1.0 and later
Iconified representations of windows are typically displayed in the window area of a taskbar or dock to allow users to
easily access background or minimized windows. The Mac OS X dock displays an icon for your application as well as
an icon for each minimized window. The Microsoft Windows and Linux taskbars display a button containing the
progam icon and title for each normal-type window in your application.
Last updated 3/21/2011
619
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Taskbar icons in AIR
Highlighting the taskbar window button
Adobe AIR 1.0 and later
When a window is in the background, you can notify the user that an event of interest related to the window has
occurred. On Mac OS X, you can notify the user by bouncing the application dock icon (as described in “Bouncing the
dock” on page 616). On Windows and Linux, you can highlight the window taskbar button by calling the
notifyUser() method of the NativeWindow instance. The type parameter passed to the method determines the
urgency of the notification:
•
NotificationType.CRITICAL: the window icon flashes until the user brings the window to the foreground.
•
NotificationType.INFORMATIONAL: the window icon highlights by changing color.
Note: On Linux, only the informational type of notification is supported. Passing either type value to the
notifyUser() function will create the same effect.
The following statement highlights the taskbar button of a window:
stage.nativeWindow.notifyUser(NotificationType.CRITICAL);
Calling the NativeWindow.notifyUser() method on an operating system that does not support window-level
notification has no effect. Use the NativeWindow.supportsNotification property to determine if window
notification is supported.
Creating windows without taskbar buttons or icons
Adobe AIR 1.0 and later
On the Windows operating system, windows created with the types utility or lightweight do not appear on the taskbar.
Invisible windows do not appear on the taskbar, either.
Because the initial window is necessarily of type, normal, in order to create an application without any windows
appearing in the taskbar, you must either close the initial window or leave it invisible. To close all windows in your
application without terminating the application, set the autoExit property of the NativeApplication object to false
before closing the last window. To simply prevent the initial window from ever becoming visible, add
false to the element of the application descriptor file (and do not set the
visible property to true or call the activate() method of the window).
In new windows opened by the application, set the type property of the NativeWindowInitOption object passed to
the window constructor to NativeWindowType.UTILITY or NativeWindowType.LIGHTWEIGHT.
On Mac OS X, windows that are minimized are displayed on the dock taskbar. You can prevent the minimized icon
from being displayed by hiding the window instead of minimizing it. The following example listens for a
nativeWindowDisplayState change event and cancels it if the window is being minimized. Instead the handler sets
the window visible property to false:
private function preventMinimize(event:NativeWindowDisplayStateEvent):void{
if(event.afterDisplayState == NativeWindowDisplayState.MINIMIZED){
event.preventDefault();
event.target.visible = false;
}
}
If a window is minimized on the Mac OS X dock when you set the visible property to false, the dock icon is not
removed. A user can still click the icon to make the window reappear.
Last updated 3/21/2011
620
Chapter 36: Working with the file system
Flash Player 9 and later, Adobe AIR 1.0 and later
Flash® Player provides basic file reading and writing capabilities, via the FileReference class. For security reasons, when
running in Flash Player, the user must always grant permission before you can read or write a file.
Adobe® AIR® provides more complete access to the file system of the host computer than is available in Flash Player.
Using the AIR file system API, you can access and manage directories and files, create directories and files, write data
to files, and so on.
More Help topics
flash.net.FileReference
flash.net.FileReferenceList
flash.filesystem.File
flash.filesystem.FileStream
Using the FileReference class
Flash Player 9 and later, Adobe AIR 1.0 and later
A FileReference object represents a data file on a client or server machine. The methods of the FileReference class let
your application load and save data files locally, and transfer file data to and from remote servers.
The FileReference class offers two different approaches to loading, transferring, and saving data files. Since its
introduction, the FileReference class has includedthe browse() method, the upload() method, and the download()
method. Use the browse() method to let the user select a file. Use the upload() method to transfer the file data to a
remote server. Use the download() method to retrieve that data from the server and save it in a local file. Starting with
Flash Player 10 and Adobe AIR 1.5, the FileReference class includes the load() and save() methods. The load() and
save() methods allow you to access and save local files directly as well. The use of those methods is similar to the
equivalent-named methods in the URLLoader and Loader classes.
Note: The File class, which extends the FileReference class, and the FileStream class provide additional functions for
working with files and the local file system. The File and FileStream classes are only supported in AIR and not in the Flash
Player.
FileReference class
Flash Player 9 and later, Adobe AIR 1.0 and later
Each FileReference object represents a single data file on the local machine. The properties of the FileReference class
contain information about the file’s size, type, name, filename extension, creator, creation date, and modification date.
Note: The creator property is supported on Mac OS only. All other platforms return null.
Note: The extension property is only supported in Adobe AIR.
Last updated 3/21/2011
621
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
You can create an instance of the FileReference class one of two ways:
• Use the new operator, as shown in the following code:
import flash.net.FileReference;
var fileRef:FileReference = new FileReference();
• Call the FileReferenceList.browse() method, which opens a dialog box and prompts the user to select one or
more files to upload. It then creates an array of FileReference objects if the user successfully selects one or more files.
Once you have created a FileReference object, you can do the following:
• Call the FileReference.browse() method, which opens a dialog box and prompts the user to select a single file
from the local file system. This is usually done before a subsequent call to the FileReference.upload() method
or FileReference.load() method. Call the FileReference.upload() method to upload the file to a remote
server. Call to the FileReference.load() method to open a local file.
• Call the FileReference.download() method. The download() method opens a dialog box to let the user select
a location for saving a new file. Then it downloads data from the server and stores it in the new file.
• Call the FileReference.load() method. This method begins loading data from a file selected previously using
the browse() method. The load() method can’t be called until the browse() operation completes (the user selects
a file).
• Call the FileReference.save() method. This method opens a dialog box and prompts the user to choose a single
file location on the local file system. It then saves data to the specified location.
Note: You can only perform one browse(), download(), or save() action at a time, because only one dialog box can
be open at any point.
The FileReference object properties such as name, size, or modificationDate are not defined until one of the
following happens:
• The FileReference.browse() method or FileReferenceList.browse() method has been called, and the user
has selected a file using the dialog box.
• The FileReference.download() method has been called, and the user has specified a new file location using the
dialog box.
Note: When performing a download, only the FileReference.name property is populated before the download is
complete. After the file has been downloaded, all properties are available.
While calls to the FileReference.browse(), FileReferenceList.browse(), FileReference.download(),
FileReference.load(), or FileReference.save() methods are executing, most players continue SWF file
playback including dispatching events and executing code.
For uploading and downloading operations, a SWF file can access files only within its own domain, including any
domains specified by a policy file. You need to put a policy file on the server containing the file if that server is not in
the same domain as the SWF file initiating the upload or download.
See FileReference.
Loading data from files
Flash Player 9 and later, Adobe AIR 1.0 and later
The FileReference.load() method lets you load data from a local file into memory.
Note: Your code must first call the FileReference.browse() method to let the user select a file to load. This restriction
does not apply to content running in Adobe AIR in the application security sandbox
Last updated 3/21/2011
622
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
The FileReference.load() method returns immediately after being called, but the data being loaded isn’t available
immediately. The FileReference object dispatches events to invoke listener methods at each step of the loading process.
The FileReference object dispatches the following events during the loading process.
•
open event (Event.OPEN): Dispatched when the load operation starts.
•
progress event (ProgressEvent.PROGRESS): Dispatched periodically as bytes of data are read from the file.
•
complete event (Event.COMPLETE): Dispatched when the load operation completes successfully.
•
ioError event (IOErrorEvent.IO_ERROR): Dispatched if the load process fails because an input/output error
occurs while opening or reading data from the file.
Once the FileReference object dispatches the complete event, the loaded data can be accessed as a ByteArray in the
FileReference object’s data property.
The following example shows how to prompt the user to select a file and then load the data from that file into memory:
package
{
import
import
import
import
import
import
flash.display.Sprite;
flash.events.*;
flash.net.FileFilter;
flash.net.FileReference;
flash.net.URLRequest;
flash.utils.ByteArray;
public class FileReferenceExample1 extends Sprite
{
private var fileRef:FileReference;
public function FileReferenceExample1()
{
fileRef = new FileReference();
fileRef.addEventListener(Event.SELECT, onFileSelected);
fileRef.addEventListener(Event.CANCEL, onCancel);
fileRef.addEventListener(IOErrorEvent.IO_ERROR, onIOError);
fileRef.addEventListener(SecurityErrorEvent.SECURITY_ERROR,
onSecurityError);
var textTypeFilter:FileFilter = new FileFilter("Text Files (*.txt, *.rtf)",
"*.txt;*.rtf");
fileRef.browse([textTypeFilter]);
}
public function onFileSelected(evt:Event):void
{
fileRef.addEventListener(ProgressEvent.PROGRESS, onProgress);
fileRef.addEventListener(Event.COMPLETE, onComplete);
fileRef.load();
}
public function onProgress(evt:ProgressEvent):void
{
trace("Loaded " + evt.bytesLoaded + " of " + evt.bytesTotal + " bytes.");
}
public function onComplete(evt:Event):void
Last updated 3/21/2011
623
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
{
trace("File was successfully loaded.");
trace(fileRef.data);
}
public function onCancel(evt:Event):void
{
trace("The browse request was canceled by the user.");
}
public function onIOError(evt:IOErrorEvent):void
{
trace("There was an IO Error.");
}
public function onSecurityError(evt:Event):void
{
trace("There was a security error.");
}
}
}
The example code first creates the FileReference object named fileRef and then calls its browse() method. The
browse() method opens a dialog box that prompts the user to select a file. When a file is selected, the code invokes the
onFileSelected() method. This method adds listeners for the progress and complete events and then calls the
FileReference object’s load() method. The other handler methods in the example simply output messages to report
on the progress of the load operation. When the loading completes, the application displays the contents of the loaded
file using the trace() method.
In Adobe AIR, the FileStream class provides additional functionality for reading data from a local file. See “Reading
and writing files” on page 655.
Saving data to local files
Flash Player 9 and later, Adobe AIR 1.0 and later
The FileReference.save() method lets you save data to a local file. It starts by opening a dialog box to let the user
enter a new filename and location to which to save a file. After the user selects the filename and location, the data is
written to the new file. When the file is saved successfully, the properties of the FileReference object are populated with
the properties of the local file.
Note: Your code can only call the FileReference.save() method in response to a user-initiated event such as a mouse
click or a keypress event. Otherwise an error is thrown. This restriction does not apply to content running in Adobe AIR
in the application security sandbox.
The FileReference.save() method returns immediately after being called. The FileReference object then
dispatches events to call listener methods at each step of the file saving process.
The FileReference object dispatches the following events during the file saving process:
•
select event (Event.SELECT): Dispatched when the user specifies the location and file name for the new file to be
saved.
•
cancel event (Event.CANCEL): Dispatched when the user click the Cancel button in the dialog box.
•
open event (Event.OPEN): Dispatched when the save operation starts.
•
progress event (ProgressEvent.PROGRESS): Dispatched periodically as bytes of data are saved to the file.
Last updated 3/21/2011
624
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
•
complete event (Event.COMPLETE): Dispatched when the save operation completes successfully.
•
ioError event (IOErrorEvent.IO_ERROR): Dispatched if the saving process fails because an input/output error
occurs while attempting to save data to the file.
The type of object passed in the data parameter of the FileReference.save() method determines how the data is
written to the file:
• If it is a String value, then it is saved as a text file using UTF-8 encoding.
• If it is an XML object, then it is written to a file in XML format with all formatting preserved.
• If it is a ByteArray object, then its contents are written directly to the file with no conversion.
• If it is some other object, then the FileReference.save() method calls the object’s toString() method and then
saves the resulting String value to a UTF-8 text file. If the object’s toString() method can’t be called, then an error
is thrown.
If the value of the data parameter is null, then an error is thrown.
The following code extends the previous example for the FileReference.load() method. After reading the data
from the file, this example prompts the user for a filename and then saves the data in a new file:
package
{
import
import
import
import
import
import
flash.display.Sprite;
flash.events.*;
flash.net.FileFilter;
flash.net.FileReference;
flash.net.URLRequest;
flash.utils.ByteArray;
public class FileReferenceExample2 extends Sprite
{
private var fileRef:FileReference;
public function FileReferenceExample2()
{
fileRef = new FileReference();
fileRef.addEventListener(Event.SELECT, onFileSelected);
fileRef.addEventListener(Event.CANCEL, onCancel);
fileRef.addEventListener(IOErrorEvent.IO_ERROR, onIOError);
fileRef.addEventListener(SecurityErrorEvent.SECURITY_ERROR,
onSecurityError);
var textTypeFilter:FileFilter = new FileFilter("Text Files (*.txt, *.rtf)",
"*.txt;*.rtf");
fileRef.browse([textTypeFilter]);
}
public function onFileSelected(evt:Event):void
{
fileRef.addEventListener(ProgressEvent.PROGRESS, onProgress);
fileRef.addEventListener(Event.COMPLETE, onComplete);
fileRef.load();
}
public function onProgress(evt:ProgressEvent):void
{
trace("Loaded " + evt.bytesLoaded + " of " + evt.bytesTotal + " bytes.");
}
public function onCancel(evt:Event):void
{
Last updated 3/21/2011
625
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
trace("The browse request was canceled by the user.");
}
public function onComplete(evt:Event):void
{
trace("File was successfully loaded.");
fileRef.removeEventListener(Event.SELECT, onFileSelected);
fileRef.removeEventListener(ProgressEvent.PROGRESS, onProgress);
fileRef.removeEventListener(Event.COMPLETE, onComplete);
fileRef.removeEventListener(Event.CANCEL, onCancel);
saveFile();
}
public function saveFile():void
{
fileRef.addEventListener(Event.SELECT, onSaveFileSelected);
fileRef.save(fileRef.data,"NewFileName.txt");
}
public function onSaveFileSelected(evt:Event):void
{
fileRef.addEventListener(ProgressEvent.PROGRESS, onSaveProgress);
fileRef.addEventListener(Event.COMPLETE, onSaveComplete);
fileRef.addEventListener(Event.CANCEL, onSaveCancel);
}
public function onSaveProgress(evt:ProgressEvent):void
{
trace("Saved " + evt.bytesLoaded + " of " + evt.bytesTotal + " bytes.");
}
public function onSaveComplete(evt:Event):void
{
trace("File saved.");
fileRef.removeEventListener(Event.SELECT, onSaveFileSelected);
fileRef.removeEventListener(ProgressEvent.PROGRESS, onSaveProgress);
fileRef.removeEventListener(Event.COMPLETE, onSaveComplete);
fileRef.removeEventListener(Event.CANCEL, onSaveCancel);
}
public function onSaveCancel(evt:Event):void
{
trace("The save request was canceled by the user.");
}
public function onIOError(evt:IOErrorEvent):void
{
trace("There was an IO Error.");
}
public function onSecurityError(evt:Event):void
{
trace("There was a security error.");
}
}
}
Last updated 3/21/2011
626
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
When all of the data loads from the file, the code calls the onComplete() method. The onComplete() method
removes the listeners for the loading events and then calls the saveFile() method. The saveFile() method calls the
FileReference.save() method. The FileReference.save() method opens a new dialog box to let the user enter
a new filename and location to save the file. The remaining event listener methods trace the progress of the file saving
process until it is complete.
In Adobe AIR, the FileStream class provides additional functionality for writing data to a local file. See “Reading and
writing files” on page 655.
Uploading files to a server
Flash Player 9 and later, Adobe AIR 1.0 and later
To upload files to a server, first call the browse() method to allow a user to select one or more files. Next, when the
FileReference.upload() method is called, the selected file is transferred to the server. If the user selects multiple
files using the FileReferenceList.browse() method, Flash Player creates an array of selected files called
FileReferenceList.fileList. You can then use the FileReference.upload() method to upload each file
individually.
Note: Using the FileReference.browse() method allows you to upload single files only. To allow a user to upload
multiple files, use the FileReferenceList.browse() method.
By default, the system file picker dialog box allows users to pick any file type from the local computer. Developers can
specify one or more custom file type filters by using the FileFilter class and passing an array of file filter instances to
the browse() method:
var imageTypes:FileFilter = new FileFilter("Images (*.jpg, *.jpeg, *.gif, *.png)", "*.jpg;
*.jpeg; *.gif; *.png");
var textTypes:FileFilter = new FileFilter("Text Files (*.txt, *.rtf)", "*.txt; *.rtf");
var allTypes:Array = new Array(imageTypes, textTypes);
var fileRef:FileReference = new FileReference();
fileRef.browse(allTypes);
When the user has selected the files and clicked the Open button in the system file picker, the Event.SELECT event is
dispatched. If the FileReference.browse() method is used to select a file to upload, the following code sends the
file to a web server:
Last updated 3/21/2011
627
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
var fileRef:FileReference = new FileReference();
fileRef.addEventListener(Event.SELECT, selectHandler);
fileRef.addEventListener(Event.COMPLETE, completeHandler);
try
{
var success:Boolean = fileRef.browse();
}
catch (error:Error)
{
trace("Unable to browse for files.");
}
function selectHandler(event:Event):void
{
var request:URLRequest = new URLRequest("http://www.[yourdomain].com/fileUploadScript.cfm")
try
{
fileRef.upload(request);
}
catch (error:Error)
{
trace("Unable to upload file.");
}
}
function completeHandler(event:Event):void
{
trace("uploaded");
}
You can send data to the server with the FileReference.upload() method by using the URLRequest.method and
URLRequest.data properties to send variables using the POST or GET methods.
When you attempt to upload a file using the FileReference.upload() method, the following events are dispatched:
•
open event (Event.OPEN): Dispatched when the upload operation starts.
•
progress event (ProgressEvent.PROGRESS): Dispatched periodically as bytes of data from the file are uploaded.
•
complete event (Event.COMPLETE): Dispatched when the upload operation completes successfully.
•
httpStatus event (HTTPStatusEvent.HTTP_STATUS): Dispatched when the upload process fails because of an
HTTP error.
•
httpResponseStatus event (HTTPStatusEvent.HTTP_RESPONSE_STATUS): Dispatched if a call to the upload()
or uploadUnencoded() method attempts to access data over HTTP and Adobe AIR is able to detect and return the
status code for the request.
•
securityError event (SecurityErrorEvent.SECURITY_ERROR): Dispatched when an upload operation fails
because of a security violation.
•
uploadCompleteData event (DataEvent.UPLOAD_COMPLETE_DATA): Dispatched after data is received from the
server after a successful upload.
•
ioError event (IOErrorEvent.IO_ERROR): Dispatched if the upload process fails for any of the following reasons:
• An input/output error occurred while Flash Player is reading, writing, or transmitting the file.
• The SWF tried to upload a file to a server that requires authentication (such as a user name and password).
During upload, Flash Player does not provide a means for users to enter passwords.
• The url parameter contains an invalid protocol. The FileReference.upload() method must use either
HTTP or HTTPS.
Last updated 3/21/2011
628
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
Flash Player does not offer complete support for servers that require authentication. Only SWF files that are running
in a browser using the browser plug-in or Microsoft ActiveX® control can provide a dialog box to prompt the user to
enter a user name and password for authentication, and then only for downloads. For uploads using the plug-in or
ActiveX control or upload/download using either the stand-alone or external player, the file transfer fails.
To create a server script in ColdFusion to accept a file upload from Flash Player, you can use code similar to the
following:
This ColdFusion code uploads the file sent by Flash Player and saves it to the same directory as the ColdFusion
template, overwriting any file with the same name. The previous code shows the bare minimum amount of code
necessary to accept a file upload; this script should not be used in a production environment. Ideally, add data
validation to ensure that users upload only accepted file types, such as an image instead of a potentially dangerous
server-side script.
The following code demonstrates file uploads using PHP, and it includes data validation. The script limits the number
of uploaded files in the upload directory to 10, ensures that the file is less than 200 KB, and permits only JPEG, GIF, or
PNG files to be uploaded and saved to the file system.
$MAXIMUM_FILE_COUNT)
{
$files_to_delete = array_splice($files, 0, count($files) - $MAXIMUM_FILE_COUNT);
Last updated 3/21/2011
629
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
for ($i = 0; $i < count($files_to_delete); $i++)
{
unlink($files_to_delete[$i][0]);
}
}
print_r($files);
closedir($directory);
function sorter($a, $b)
{
if ($a[1] == $b[1])
{
return 0;
}
else
{
return ($a[1] < $b[1]) ? -1 : 1;
}
}
?>
You can pass additional variables to the upload script using either the POST or GET request method. To send additional
POST variables to your upload script, you can use the following code:
var fileRef:FileReference = new FileReference();
fileRef.addEventListener(Event.SELECT, selectHandler);
fileRef.addEventListener(Event.COMPLETE, completeHandler);
fileRef.browse();
function selectHandler(event:Event):void
{
var params:URLVariables = new URLVariables();
params.date = new Date();
params.ssid = "94103-1394-2345";
var request:URLRequest = new
URLRequest("http://www.yourdomain.com/FileReferenceUpload/fileupload.cfm");
request.method = URLRequestMethod.POST;
request.data = params;
fileRef.upload(request, "Custom1");
}
function completeHandler(event:Event):void
{
trace("uploaded");
}
The previous example creates a URLVariables object that you pass to the remote server- side script. In previous
versions of ActionScript, you could pass variables to the server upload script by passing values in the query string.
ActionScript 3.0 allows you to pass variables to the remote script using a URLRequest object, which allows you to pass
data using either the POST or GET method; this, in turn, makes passing larger sets of data easier and cleaner. In order
to specify whether the variables are passed using the GET or POST request method, you can set the URLRequest.method
property to either URLRequestMethod.GET or URLRequestMethod.POST, respectively.
ActionScript 3.0 also lets you override the default Filedata upload file field name by providing a second parameter
to the upload() method, as demonstrated in the previous example (which replaced the default value Filedata with
Custom1).
Last updated 3/21/2011
630
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
By default, Flash Player does not attempt to send a test upload, although you can override this default by passing a value
of true as the third parameter to the upload() method. The purpose of the test upload is to check whether the actual
file upload will be successful and that server authentication, if required, will succeed.
Note: A test upload occurs only on Windows-based Flash Players at this time.
The server script that handles the file upload should expect an HTTP POST request with the following elements:
•
Content-Type with a value of multipart/form-data.
•
Content-Disposition with a name attribute set to “Filedata” and a filename attribute set to the name of the
original file. You can specify a custom name attribute by passing a value for the uploadDataFieldName parameter
in the FileReference.upload() method.
• The binary contents of the file.
Here is a sample HTTP POST request:
POST /handler.asp HTTP/1.1
Accept: text/*
Content-Type: multipart/form-data;
boundary=----------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6
User-Agent: Shockwave Flash
Host: www.mydomain.com
Content-Length: 421
Connection: Keep-Alive
Cache-Control: no-cache
------------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6
Content-Disposition: form-data; name="Filename"
sushi.jpg
------------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6
Content-Disposition: form-data; name="Filedata"; filename="sushi.jpg"
Content-Type: application/octet-stream
Test File
------------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6
Content-Disposition: form-data; name="Upload"
Submit Query
------------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6
(actual file data,,,)
The following sample HTTP POST request sends three POST variables: api_sig, api_key, and auth_token, and uses
a custom upload data field name value of "photo":
Last updated 3/21/2011
631
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
POST /handler.asp HTTP/1.1
Accept: text/*
Content-Type: multipart/form-data;
boundary=----------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6
User-Agent: Shockwave Flash
Host: www.mydomain.com
Content-Length: 421
Connection: Keep-Alive
Cache-Control: no-cache
------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7
Content-Disposition: form-data; name="Filename"
sushi.jpg
------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7
Content-Disposition: form-data; name="api_sig"
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7
Content-Disposition: form-data; name="api_key"
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7
Content-Disposition: form-data; name="auth_token"
XXXXXXXXXXXXXXXXXXXXXXX
------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7
Content-Disposition: form-data; name="photo"; filename="sushi.jpg"
Content-Type: application/octet-stream
(actual file data,,,)
------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7
Content-Disposition: form-data; name="Upload"
Submit Query
------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7--
Downloading files from a server
Flash Player 9 and later, Adobe AIR 1.0 and later
You can let users download files from a server using the FileReference.download() method, which takes two
parameters: request and defaultFileName. The first parameter is the URLRequest object that contains the URL of
the file to download. The second parameter is optional—it lets you specify a default filename that appears in the
download file dialog box. If you omit the second parameter, defaultFileName, the filename from the specified URL
is used.
The following code downloads a file named index.xml from the same directory as the SWF file:
var request:URLRequest = new URLRequest("index.xml");
var fileRef:FileReference = new FileReference();
fileRef.download(request);
To set the default name to currentnews.xml instead of index.xml, specify the defaultFileName parameter, as the
following snippet shows:
Last updated 3/21/2011
632
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
var request:URLRequest = new URLRequest("index.xml");
var fileToDownload:FileReference = new FileReference();
fileToDownload.download(request, "currentnews.xml");
Renaming a file can be useful if the server filename was not intuitive or was server-generated. It’s also good to explicitly
specify the defaultFileName parameter when you download a file using a server-side script, instead of downloading
the file directly. For example, you need to specify the defaultFileName parameter if you have a server-side script that
downloads specific files based on URL variables passed to it. Otherwise, the default name of the downloaded file is the
name of your server-side script.
Data can be sent to the server using the download() method by appending parameters to the URL for the server script
to parse. The following ActionScript 3.0 snippet downloads a document based on which parameters are passed to a
ColdFusion script:
package
{
import
import
import
import
import
flash.display.Sprite;
flash.net.FileReference;
flash.net.URLRequest;
flash.net.URLRequestMethod;
flash.net.URLVariables;
public class DownloadFileExample extends Sprite
{
private var fileToDownload:FileReference;
public function DownloadFileExample()
{
var request:URLRequest = new URLRequest();
request.url = "http://www.[yourdomain].com/downloadfile.cfm";
request.method = URLRequestMethod.GET;
request.data = new URLVariables("id=2");
fileToDownload = new FileReference();
try
{
fileToDownload.download(request, "file2.txt");
}
catch (error:Error)
{
trace("Unable to download file.");
}
}
}
}
The following code demonstrates the ColdFusion script, download.cfm, that downloads one of two files from the
server, depending on the value of a URL variable:
Last updated 3/21/2011
633
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
FileReferenceList class
Flash Player 9 and later, Adobe AIR 1.0 and later
The FileReferenceList class lets the user select one or more files to upload to a server-side script. The file upload is
handled by the FileReference.upload() method, which must be called on each file that the user selects.
The following code creates two FileFilter objects (imageFilter and textFilter) and passes them in an array to the
FileReferenceList.browse() method. This causes the operating system file dialog box to display two possible
filters for file types.
var imageFilter:FileFilter = new FileFilter("Image Files (*.jpg, *.jpeg, *.gif, *.png)",
"*.jpg; *.jpeg; *.gif; *.png");
var textFilter:FileFilter = new FileFilter("Text Files (*.txt, *.rtf)", "*.txt; *.rtf");
var fileRefList:FileReferenceList = new FileReferenceList();
try
{
var success:Boolean = fileRefList.browse(new Array(imageFilter, textFilter));
}
catch (error:Error)
{
trace("Unable to browse for files.");
}
Allowing the user to select and upload one or more files by using the FileReferenceList class is the same as using
FileReference.browse() to select files, although the FileReferenceList allows you to select more than one file.
Uploading multiple files requires you to upload each of the selected files by using FileReference.upload(), as the
following code shows:
var fileRefList:FileReferenceList = new FileReferenceList();
fileRefList.addEventListener(Event.SELECT, selectHandler);
fileRefList.browse();
function selectHandler(event:Event):void
{
var request:URLRequest = new URLRequest("http://www.[yourdomain].com/fileUploadScript.cfm");
var file:FileReference;
var files:FileReferenceList = FileReferenceList(event.target);
var selectedFileArray:Array = files.fileList;
for (var i:uint = 0; i < selectedFileArray.length; i++)
{
file = FileReference(selectedFileArray[i]);
file.addEventListener(Event.COMPLETE, completeHandler);
try
{
file.upload(request);
}
catch (error:Error)
{
trace("Unable to upload files.");
}
}
}
function completeHandler(event:Event):void
{
trace("uploaded");
}
Last updated 3/21/2011
634
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
Because the Event.COMPLETE event is added to each individual FileReference object in the array, Flash Player calls the
completeHandler() method when each individual file finishes uploading.
Using the AIR file system API
Adobe AIR 1.0 and later
The Adobe AIR file system API includes the following classes:
• File
• FileMode
• FileStream
The file system API lets you do the following (and more):
• Copy, create, delete, and move files and directories
• Get in from at ion about files and directories
• Read and write files
AIR file basics
Adobe AIR 1.0 and later
For a quick explanation and code examples of working with the file system in AIR, see the following quick start articles
on the Adobe Developer Connection:
• Building a text-file editor (Flash)
• Building a text-file editor (Flex)
• Building a directory search application (Flex)
• Reading and writing from an XML preferences file (Flex)
• Compressing files and data (Flex)
Adobe AIR provides classes that you can use to access, create, and manage both files and folders. These classes,
contained in the flash.filesystem package, are used as follows:
File classes
Description
File
File object represents a path to a file or directory. You use a file object to create a pointer to a file or
folder, initiating interaction with the file or folder.
FileMode
The FileMode class defines string constants used in the fileMode parameter of the open() and
openAsync() methods of the FileStream class. The fileMode parameter of these methods determines
the capabilities available to the FileStream object once the file is opened, which include writing, reading,
appending, and updating.
FileStream
FileStream object is used to open files for reading and writing. Once you’ve created a File object that
points to a new or existing file, you pass that pointer to the FileStream object so that you can open it and
read or write data.
Some methods in the File class have both synchronous and asynchronous versions:
•
File.copyTo() and File.copyToAsync()
Last updated 3/21/2011
635
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
•
File.deleteDirectory() and File.deleteDirectoryAsync()
•
File.deleteFile() and File.deleteFileAsync()
•
File.getDirectoryListing() and File.getDirectoryListingAsync()
•
File.moveTo() and File.moveToAsync()
•
File.moveToTrash() and File.moveToTrashAsync()
Also, FileStream operations work synchronously or asynchronously depending on how the FileStream object opens
the file: by calling the open() method or by calling the openAsync() method.
The asynchronous versions let you initiate processes that run in the background and dispatch events when complete
(or when error events occur). Other code can execute while these asynchronous background processes are taking place.
With asynchronous versions of the operations, you must set up event listener functions, using the
addEventListener() method of the File or FileStream object that calls the function.
The synchronous versions let you write simpler code that does not rely on setting up event listeners. However, since
other code cannot execute while a synchronous method is executing, important processes such as display object
rendering and animation can be delayed.
Working with File objects in AIR
Adobe AIR 1.0 and later
A File object is a pointer to a file or directory in the file system.
The File class extends the FileReference class. The FileReference class, which is available in Adobe® Flash® Player as well
as AIR, represents a pointer to a file. The File class adds properties and methods that are not exposed in Flash Player
(in a SWF file running in a browser), due to security considerations.
About the File class
Adobe AIR 1.0 and later
You can use the File class for the following:
• Getting the path to special directories, including the user directory, the user's documents directory, the directory
from which the application was launched, and the application directory
• Coping files and directories
• Moving files and directories
• Deleting files and directories (or moving them to the trash)
• Listing files and directories contained in a directory
• Creating temporary files and folders
Once a File object points to a file path, you can use it to read and write file data, using the FileStream class.
A File object can point to the path of a file or directory that does not yet exist. You can use such a File object in creating
a file or directory.
Paths of File objects
Adobe AIR 1.0 and later
Each File object has two properties that each define its path:
Last updated 3/21/2011
636
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
Property
Description
nativePath
Specifies the platform-specific path to a file. For example, on Windows a path might be "c:\Sample
directory\test.txt" whereas on Mac OS it could be "/Sample directory/test.txt". A nativePath
property uses the backslash (\) character as the directory separator character on Windows, and it uses
the forward slash (/) character on Mac OS and Linux.
url
This may use the file URL scheme to point to a file. For example, on Windows a path might be
"file:///c:/Sample%20directory/test.txt" whereas on Mac OS it could be
"file:///Sample%20directory/test.txt". The runtime includes other special URL schemes besides file
and are described in “Supported AIR URL schemes” on page 644
The File class includes static properties for pointing to standard directories on Mac OS, Windows, and Linux. These
properties include:
•
File.applicationStorageDirectory—a storage directory unique to each installed AIR application. This
directory is an appropriate place to store dynamic application assets and user preferences. Consider storing large
amounts of data elsewhere.
On Android and iOS, the application storage directory is removed when the application is uninstalled or the user
chooses to clear application data, but this is not the case on other platforms.
•
File.applicationDirectory—the directory where the application is installed (along with any installed assets).
On some operating systems, the application is stored in a single package file rather than a physical directory. In this
case, the contents may not be accessible using the native path. The application directory is read-only.
•
File.desktopDirectory—the user’s desktop directory. If a platform does not define a desktop directory, another
location on the file system is used.
•
File.documentsDirectory—the user’s documents directory. If a platform does not define a documents
directory, another location on the file system is used.
•
File.userDirectory—the user directory. If a platform does not define a user directory, another location on the
file system is used.
Note: When a platform does not define standard locations for desktop, documents, or user directories,
File.documentsDirectory, File.desktopDirectory, and File.userDirectory can reference the same directory.
These properties have different values on different operating systems. For example, Mac and Windows each have a
different native path to the user’s desktop directory. However, the File.desktopDirectory property points to an
appropriate directory path on every platform. To write applications that work well across platforms, use these
properties as the basis for referencing other directories and files used by the application. Then use the resolvePath()
method to refine the path. For example, this code points to the preferences.xml file in the application storage directory:
var prefsFile:File = File.applicationStorageDirectory;
prefsFile = prefsFile.resolvePath("preferences.xml");
Although the File class lets you point to a specific file path, doing so can lead to applications that do not work across
platforms. For example, the path C:\Documents and Settings\joe\ only works on Windows. For these reasons, it is best
to use the static properties of the File class, such as File.documentsDirectory.
Last updated 3/21/2011
637
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
Common directory locations
Platform
Directory type
Typical file system location
Android
Application
/data/data/
Application-storage
/data/data/air.applicationID/filename/Local Store
Desktop
/mnt/sdcard
Documents
/mnt/sdcard
Temporary
/data/data/applicationID/cache/FlashTmp.randomString
User
/mnt/sdcard
Application
/var/mobile/Applications/uid/filename.app
Application-storage
/var/mobile/Applications/uid/Library/Application
Support/applicationID/Local Store
Desktop
not accessible
Documents
not accessible
Temporary
/private/var/mobile/Applications/uid/tmp/FlashTmpNNN
User
not accessible
Application
/opt/filename/share
Application-storage
/home/userName/.appdata/applicationID/Local Store
Desktop
/home/userName/Desktop
Documents
/home/userName/Documents
Temporary
/tmp/FlashTmp.randomString
User
/home/userName
Application
/Applications/filename.app/Contents/Resources
Application-storage
/Users/userName/Library/Preferences/applicationID/Local Store
Desktop
/Users/userName/Desktop
Documents
/Users/userName/Documents
Temporary
/private/var/folders/JY/randomString/TemporaryItems/FlashTmp
User
/Users/userName
Application
C:\Program Files\filename
Application-storage
C:\Documents and
settings\userName\ApplicationData\applicationID\Local Store
Desktop
C:\Documents and settings\userName\Desktop
Documents
C:\Documents and settings\userName\My Documents
Temporary
C:\Documents and settings\userName\Local
Settings\Temp\randomString.tmp
User
C:\Documents and settings\userName
iOS
Linux
Mac
Windows
The actual native paths for these directories vary based on the operating system and computer configuration. The
paths shown in this table are typical examples. You should always use the appropriate static File class properties to refer
Last updated 3/21/2011
638
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
to these directories so that your application works correctly on any platform. In an actual AIR application, the values
for applicationID and filename shown in the table are taken from the application descriptor. If you specify a
publisher ID in the application descriptor, then the publisher ID is appended to the application ID in these paths. The
value for userName is the account name of the installing user.
Directory view for AIR for TV applications
To provide security to the system files on AIR for TV devices, an AIR application can access only a limited set of
directories. AIR for TV prohibits the application from accessing any other directories. Furthermore, AIR for TV
isolates each user’s user-specific data for each AIR application.
The AIR application uses directory names that are only for ActionScript 3.0 use. These names do not represent actual
directories on the device. AIR for TV maps these ActionScript 3.0 directory names to actual device directories. This mapping
protects AIR for TV applications from maliciously or inadvertently accessing local files that do not belong to them.
The ActionScript 3.0 directory names are:
/app/ The read-only application directory for the running AIR application.
/app-storage/ The read-write application storage directory for the running AIR application.
/home/ The read-write user directory.
/tmp/ The read-write temporary directory for the running AIR application.
/volumes/ The read-only directory containing zero or more read-write subdirectories that represent mounted
volumes.
If an application tries to access a prohibited directory, the runtime throws an exception that ActionScript code can
catch.
The following table shows the File.nativePath value for various File properties and methods. The values reflect the
application’s limited view of the device’s file system.
File property or method
File.nativePat
h value
Mapping information
applicationDirectory
/app/
Maps to an application-specific directory.
applicationStorageDirectory
/app-storage/
Maps to an application-specific directory within a userspecific directory.
desktopDirectory
/home/
Maps to an application-specific directory within a userspecific directory. The same directory as userDirectory
and documentsDirectory.
userDirectory
/home/
Maps to an application-specific directory within a userspecific directory. The same directory as
desktopDirectory and documentsDirectory.
documentsDirectory
/home/
Maps to an application-specific directory within a userspecific directory. The same directory as userDirectory
and desktopDirectory.
createTempDirectory()
/tmp/
Maps to a temporary directory. AIR for TV deletes this
directory and its contents when the AIR application exits.
Also consider the behavior of the following methods on AIR for TV devices:
•
File.createTempFile() creates a file in the /tmp/ directory.
Last updated 3/21/2011
639
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
•
File.getRootDirectories()returns an array with one File object. The File object’s nativePath property has the
value /. This root directory contains the directories app, app-storage, home and tmp.
•
StorageVolumeInfo.storageVolumeInfo.getStorageVolumes() returns a Vector of StorageVolume objects.
Each StorageVolume object’s rootDirectory property is a File object. The File object’s nativePath value begins
with /volumes/. All applications and users have access to the /volumes/ directory.
Pointing a File object to a directory
Adobe AIR 1.0 and later
There are different ways to set a File object to point to a directory.
Pointing to the user’s home directory
Adobe AIR 1.0 and later
You can point a File object to the user’s home directory. The following code sets a File object to point to an AIR Test
subdirectory of the home directory:
var file:File = File.userDirectory.resolvePath("AIR Test");
Pointing to the user’s documents directory
Adobe AIR 1.0 and later
You can point a File object to the user's documents directory. The following code sets a File object to point to an AIR
Test subdirectory of the documents directory:
var file:File = File.documentsDirectory.resolvePath("AIR Test");
Pointing to the desktop directory
Adobe AIR 1.0 and later
You can point a File object to the desktop. The following code sets a File object to point to an AIR Test subdirectory
of the desktop:
var file:File = File.desktopDirectory.resolvePath("AIR Test");
Pointing to the application storage directory
Adobe AIR 1.0 and later
You can point a File object to the application storage directory. For every AIR application, there is a unique associated
path that defines the application storage directory. This directory is unique to each application and user. You can use
this directory to store user-specific, application-specific data (such as user data or preferences files). For example, the
following code points a File object to a preferences file, prefs.xml, contained in the application storage directory:
var file:File = File.applicationStorageDirectory;
file = file.resolvePath("prefs.xml");
Last updated 3/21/2011
640
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
The application storage directory location is typically based on the user name and the application ID. The following
file system locations are given here to help you debug your application. You should always use the
File.applicationStorage property or app-storage: URI scheme to resolve files in this directory:
• On Mac OS—In:
/Users/user name/Library/Preferences/applicationID/Local Store/
For example:
/Users/babbage/Library/Preferences/com.example.TestApp/Local Store
• On Windows—In the documents and Settings directory, in:
C:\Documents and Settings\user name\Application Data\applicationID\Local Store\
For example:
C:\Documents and Settings\babbage\Application Data\com.example.TestApp\Local Store
• On Linux—In:
/home/user name/.appdata/applicationID/Local Store/
For example:
/home/babbage/.appdata/com.example.TestApp/Local Store
• On Android—In:
/data/data/androidPackageID/applicationID/Local Store
For example:
/data/data/air.com.example.TestApp/com.example.TestApp/Local Store
• On AIR for TV devices, the location is described in “Directory view for AIR for TV applications” on page 638.
Note: If an application has a publisher ID, then the publisher ID is also used as part of the path to the application storage
directory.
The URL (and url property) for a File object created with File.applicationStorageDirectory uses the appstorage URL scheme (see “Supported AIR URL schemes” on page 644), as in the following:
var dir:File = File.applicationStorageDirectory;
dir = dir.resolvePath("preferences");
trace(dir.url); // app-storage:/preferences
Pointing to the application directory
Adobe AIR 1.0 and later
You can point a File object to the directory in which the application was installed, known as the application directory.
You can reference this directory using the File.applicationDirectory property. You can use this directory to
examine the application descriptor file or other resources installed with the application. For example, the following
code points a File object to a directory named images in the application directory:
var dir:File = File.applicationDirectory;
dir = dir.resolvePath("images");
The URL (and url property) for a File object created with File.applicationDirectory uses the app URL scheme
(see “Supported AIR URL schemes” on page 644), as in the following:
Last updated 3/21/2011
641
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
var dir:File = File.applicationDirectory;
dir = dir.resolvePath("images");
trace(dir.url); // app:/images
Note: On Android, the files in the application package are not accessible via the nativePath. The nativePath property
is an empty string. Always use the URL to access files in the application directory rather than a native path.
Pointing to the file system root
Adobe AIR 1.0 and later
The File.getRootDirectories() method lists all root volumes, such as C: and mounted volumes, on a Windows
computer. On Mac OS and Linux, this method always returns the unique root directory for the machine (the "/"
directory). The StorageVolumeInfo.getStorageVolumes() method provides more detailed information on
mounted storage volumes (see “Working with storage volumes” on page 654).
Note: The root of the file system is not readable on Android. A File object referencing the directory with the native path,
“/”, is returned, but the properties of that object do not have accurate values. For example, spaceAvailable is always 0.
Pointing to an explicit directory
Adobe AIR 1.0 and later
You can point the File object to an explicit directory by setting the nativePath property of the File object, as in the
following example (on Windows):
var file:File = new File();
file.nativePath = "C:\\AIR Test";
Important: Pointing to an explicit path this way can lead to code that does not work across platforms. For example,
the previous example only works on Windows. You can use the static properties of the File object, such as
File.applicationStorageDirectory, to locate a directory that works cross-platform. Then use the
resolvePath() method (see the next section) to navigate to a relative path.
Navigating to relative paths
Adobe AIR 1.0 and later
You can use the resolvePath() method to obtain a path relative to another given path. For example, the following
code sets a File object to point to an "AIR Test" subdirectory of the user's home directory:
var file:File = File.userDirectory;
file = file.resolvePath("AIR Test");
You can also use the url property of a File object to point it to a directory based on a URL string, as in the following:
var urlStr:String = "file:///C:/AIR Test/";
var file:File = new File()
file.url = urlStr;
For more information, see “Modifying File paths” on page 644.
Last updated 3/21/2011
642
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
Letting the user browse to select a directory
Adobe AIR 1.0 and later
The File class includes the browseForDirectory() method, which presents a system dialog box in which the user can
select a directory to assign to the object. The browseForDirectory() method is asynchronous. The File object
dispatches a select event if the user selects a directory and clicks the Open button, or it dispatches a cancel event if
the user clicks the Cancel button.
For example, the following code lets the user select a directory and outputs the directory path upon selection:
var file:File = new File();
file.addEventListener(Event.SELECT, dirSelected);
file.browseForDirectory("Select a directory");
function dirSelected(e:Event):void {
trace(file.nativePath);
}
Note: On Android, the browseForDirectory() method is not supported. Calling this method has no effect; a cancel
event is dispatched immediately. To allow users to select a directory, use a custom, application-defined dialog, instead.
Pointing to the directory from which the application was invoked
Adobe AIR 1.0 and later
You can get the directory location from which an application is invoked, by checking the currentDirectory property
of the InvokeEvent object dispatched when the application is invoked. For details, see “Capturing command line
arguments” on page 852.
Pointing a File object to a file
Adobe AIR 1.0 and later
There are different ways to set the file to which a File object points.
Pointing to an explicit file path
Adobe AIR 1.0 and later
Important: Pointing to an explicit path can lead to code that does not work across platforms. For example, the path
C:/foo.txt only works on Windows. You can use the static properties of the File object, such as
File.applicationStorageDirectory, to locate a directory that works cross-platform. Then use the
resolvePath() method (see “Modifying File paths” on page 644) to navigate to a relative path.
You can use the url property of a File object to point it to a file or directory based on a URL string, as in the following:
var urlStr:String = "file:///C:/AIR Test/test.txt";
var file:File = new File()
file.url = urlStr;
You can also pass the URL to the File() constructor function, as in the following:
var urlStr:String = "file:///C:/AIR Test/test.txt";
var file:File = new File(urlStr);
The url property always returns the URI-encoded version of the URL (for example, blank spaces are replaced with
"%20):
Last updated 3/21/2011
643
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
file.url = "file:///c:/AIR Test";
trace(file.url); // file:///c:/AIR%20Test
You can also use the nativePath property of a File object to set an explicit path. For example, the following code, when
run on a Windows computer, sets a File object to the test.txt file in the AIR Test subdirectory of the C: drive:
var file:File = new File();
file.nativePath = "C:/AIR Test/test.txt";
You can also pass this path to the File() constructor function, as in the following:
var file:File = new File("C:/AIR Test/test.txt");
Use the forward slash (/) character as the path delimiter for the nativePath property. On Windows, you can also use
the backslash (\) character, but doing so leads to applications that do not work across platforms.
For more information, see “Modifying File paths” on page 644.
Enumerating files in a directory
Adobe AIR 1.0 and later
You can use the getDirectoryListing() method of a File object to get an array of File objects pointing to files and
subdirectories at the root level of a directory. For more information, see “Enumerating directories” on page 650.
Letting the user browse to select a file
Adobe AIR 1.0 and later
The File class includes the following methods that present a system dialog box in which the user can select a file to
assign to the object:
•
browseForOpen()
•
browseForSave()
•
browseForOpenMultiple()
These methods are each asynchronous. The browseForOpen() and browseForSave() methods dispatch the select
event when the user selects a file (or a target path, in the case of browseForSave()). With the browseForOpen() and
browseForSave() methods, upon selection the target File object points to the selected files. The
browseForOpenMultiple() method dispatches a selectMultiple event when the user selects files. The
selectMultiple event is of type FileListEvent, which has a files property that is an array of File objects (pointing
to the selected files).
For example, the following code presents the user with an “Open” dialog box in which the user can select a file:
Last updated 3/21/2011
644
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
var fileToOpen:File = File.documentsDirectory;
selectTextFile(fileToOpen);
function selectTextFile(root:File):void
{
var txtFilter:FileFilter = new FileFilter("Text", "*.as;*.css;*.html;*.txt;*.xml");
root.browseForOpen("Open", [txtFilter]);
root.addEventListener(Event.SELECT, fileSelected);
}
function fileSelected(event:Event):void
{
trace(fileToOpen.nativePath);
}
If the application has another browser dialog box open when you call a browse method, the runtime throws an Error
exception.
Note: On Android, only image, video, and audio files can be selected with the browseForOpen() and
browseForOpenMultiple() methods. The browseForSave() dialog also displays only media files even though the user
can enter an arbitrary filename. For opening and saving non-media files, you should consider using custom dialogs
instead of these methods.
Modifying File paths
Adobe AIR 1.0 and later
You can also modify the path of an existing File object by calling the resolvePath() method or by modifying the
nativePath or url property of the object, as in the following examples (on Windows):
var file1:File = File.documentsDirectory;
file1 = file1.resolvePath("AIR Test");
trace(file1.nativePath); // C:\Documents and Settings\userName\My Documents\AIR Test
var file2:File = File.documentsDirectory;
file2 = file2.resolvePath("..");
trace(file2.nativePath); // C:\Documents and Settings\userName
var file3:File = File.documentsDirectory;
file3.nativePath += "/subdirectory";
trace(file3.nativePath); // C:\Documents and Settings\userName\My Documents\subdirectory
var file4:File = new File();
file4.url = "file:///c:/AIR Test/test.txt";
trace(file4.nativePath); // C:\AIR Test\test.txt
When using the nativePath property, use the forward slash (/) character as the directory separator character. On
Windows, you can use the backslash (\) character as well, but you should not do so, as it leads to code that does not
work cross-platform.
Supported AIR URL schemes
Adobe AIR 1.0 and later
In AIR, you can use any of the following URL schemes in defining the url property of a File object:
Last updated 3/21/2011
645
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
URL scheme
Description
file
Use to specify a path relative to the root of the file system. For example:
file:///c:/AIR Test/test.txt
The URL standard specifies that a file URL takes the form file:///. As a special
case, can be the empty string, which is interpreted as "the machine from which the URL is being
interpreted." For this reason, file URLs often have three slashes (///).
app
Use to specify a path relative to the root directory of the installed application (the directory that contains
the application.xml file for the installed application). For example, the following path points to an images
subdirectory of the directory of the installed application:
app:/images
app-storage
Use to specify a path relative to the application store directory. For each installed application, AIR defines
a unique application store directory, which is a useful place to store data specific to that application. For
example, the following path points to a prefs.xml file in a settings subdirectory of the application store
directory:
app-storage:/settings/prefs.xml
Finding the relative path between two files
Adobe AIR 1.0 and later
You can use the getRelativePath() method to find the relative path between two files:
var file1:File = File.documentsDirectory.resolvePath("AIR Test");
var file2:File = File.documentsDirectory
file2 = file2.resolvePath("AIR Test/bob/test.txt");
trace(file1.getRelativePath(file2)); // bob/test.txt
The second parameter of the getRelativePath() method, the useDotDot parameter, allows for .. syntax to be
returned in results, to indicate parent directories:
var file1:File = File.documentsDirectory;
file1 = file1.resolvePath("AIR Test");
var file2:File = File.documentsDirectory;
file2 = file2.resolvePath("AIR Test/bob/test.txt");
var file3:File = File.documentsDirectory;
file3 = file3.resolvePath("AIR Test/susan/test.txt");
trace(file2.getRelativePath(file1, true)); // ../..
trace(file3.getRelativePath(file2, true)); // ../../bob/test.txt
Obtaining canonical versions of file names
Adobe AIR 1.0 and later
File and path names are not case sensitive on Windows and Mac OS. In the following, two File objects point to the
same file:
File.documentsDirectory.resolvePath("test.txt");
File.documentsDirectory.resolvePath("TeSt.TxT");
However, documents and directory names do include capitalization. For example, the following assumes that there is
a folder named AIR Test in the documents directory, as in the following examples:
Last updated 3/21/2011
646
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
var file:File = File.documentsDirectory.resolvePath("AIR test");
trace(file.nativePath); // ... AIR test
file.canonicalize();
trace(file.nativePath); // ... AIR Test
The canonicalize() method converts the nativePath object to use the correct capitalization for the file or directory
name. On case sensitive file systems (such as Linux), when multiple files exists with names differing only in case, the
canonicalize() method adjusts the path to match the first file found (in an order determined by the file system).
You can also use the canonicalize() method to convert short file names ("8.3" names) to long file names on
Windows, as in the following examples:
var path:File = new File();
path.nativePath = "C:\\AIR~1";
path.canonicalize();
trace(path.nativePath); // C:\AIR Test
Working with packages and symbolic links
Adobe AIR 1.0 and later
Various operating systems support package files and symbolic link files:
Packages—On Mac OS, directories can be designated as packages and show up in the Mac OS Finder as a single file
rather than as a directory.
Symbolic links—Mac OS, Linux, and Windows Vista support symbolic links. Symbolic links allow a file to point to
another file or directory on disk. Although similar, symbolic links are not the same as aliases. An alias is always
reported as a file (rather than a directory), and reading or writing to an alias or shortcut never affects the original file
or directory that it points to. On the other hand, a symbolic link behaves exactly like the file or directory it points to.
It can be reported as a file or a directory, and reading or writing to a symbolic link affects the file or directory that it
points to, not the symbolic link itself. Additionally, on Windows the isSymbolicLink property for a File object
referencing a junction point (used in the NTFS file system) is set to true.
The File class includes the isPackage and isSymbolicLink properties for checking if a File object references a
package or symbolic link.
The following code iterates through the user’s desktop directory, listing subdirectories that are not packages:
var desktopNodes:Array = File.desktopDirectory.getDirectoryListing();
for (var i:uint = 0; i < desktopNodes.length; i++)
{
if (desktopNodes[i].isDirectory && !!desktopNodes[i].isPackage)
{
trace(desktopNodes[i].name);
}
}
The following code iterates through the user’s desktop directory, listing files and directories that are not symbolic links:
Last updated 3/21/2011
647
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
var desktopNodes:Array = File.desktopDirectory.getDirectoryListing();
for (var i:uint = 0; i < desktopNodes.length; i++)
{
if (!desktopNodes[i].isSymbolicLink)
{
trace(desktopNodes[i].name);
}
}
The canonicalize() method changes the path of a symbolic link to point to the file or directory to which the link
refers. The following code iterates through the user’s desktop directory, and reports the paths referenced by files that
are symbolic links:
var desktopNodes:Array = File.desktopDirectory.getDirectoryListing();
for (var i:uint = 0; i < desktopNodes.length; i++)
{
if (desktopNodes[i].isSymbolicLink)
{
var linkNode:File = desktopNodes[i] as File;
linkNode.canonicalize();
trace(linkNode.nativePath);
}
}
Determining space available on a volume
Adobe AIR 1.0 and later
The spaceAvailable property of a File object is the space available for use at the File location, in bytes. For example,
the following code checks the space available in the application storage directory:
trace(File.applicationStorageDirectory.spaceAvailable);
If the File object references a directory, the spaceAvailable property indicates the space in the directory that files can
use. If the File object references a file, the spaceAvailable property indicates the space into which the file could grow.
If the file location does not exist, the spaceAvailable property is set to 0. If the File object references a symbolic link,
the spaceAvailable property is set to space available at the location the symbolic link points to.
Typically the space available for a directory or file is the same as the space available on the volume containing the
directory or file. However, space available can take into account quotas and per-directory limits.
Adding a file or directory to a volume generally requires more space than the actual size of the file or the size of the
contents of the directory. For example, the operating system may require more space to store index information. Or
the disk sectors required may use additional space. Also, available space changes dynamically. So, you cannot expect
to allocate all of the reported space for file storage. For information on writing to the file system, see “Reading and
writing files” on page 655.
The StorageVolumeInfo.getStorageVolumes() method provides more detailed information on mounted storage
volumes (see “Working with storage volumes” on page 654).
Last updated 3/21/2011
648
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
Opening files with the default system application
Adobe AIR 2 and later
In AIR 2, you can open a file using the application registered by the operating system to open it. For example, an AIR
application can open a DOC file with the application registered to open it. Use the openWithDefaultApplication()
method of a File object to open the file. For example, the following code opens a file named test.doc on the user’s
desktop and opens it with the default application for DOC files:
var file:File = File.deskopDirectory;
file = file.resolvePath("test.doc");
file.openWithDefaultApplication();
Note: On Linux, the file’s MIME type, not the filename extension, determines the default application for a file.
The following code lets the user navigate to an mp3 file and open it in the default application for playing mp3 files:
var file:File = File.documentsDirectory;
var mp3Filter:FileFilter = new FileFilter("MP3 Files", "*.mp3");
file.browseForOpen("Open", [mp3Filter]);
file.addEventListener(Event.SELECT, fileSelected);
function fileSelected(e:Event):void
{
file.openWithDefaultApplication();
}
You cannot use the openWithDefaultApplication() method with files located in the application directory.
AIR prevents you from using the openWithDefaultApplication() method to open certain files. On Windows, AIR
prevents you from opening files that have certain filetypes, such as EXE or BAT. On Mac OS and Linux, AIR prevents
you from opening files that will launch in certain application. (These include Terminal and AppletLauncher on Mac
OS; and csh, bash, or ruby on Linux.) Attempting to open one of these files using the
openWithDefaultApplication() method results in an exception. For a complete list of prevented filetypes, see the
language reference entry for the File.openWithDefaultApplication() method.
Note: This limitation does not exist for an AIR application installed using a native installer (an extended desktop
application).
Getting file system information
Adobe AIR 1.0 and later
The File class includes the following static properties that provide some useful information about the file system:
Property
Description
File.lineEnding
The line-ending character sequence used by the host operating system. On Mac OS and Linux, this is
the line-feed character. On Windows, this is the carriage return character followed by the line-feed
character.
File.separator
The host operating system's path component separator character. On Mac OS and Linux, this is the
forward slash (/) character. On Windows, it is the backslash (\) character.
File.systemCharset
The default encoding used for files by the host operating system. This pertains to the character set
used by the operating system, corresponding to its language.
The Capabilities class also includes useful system information that can be useful when working with files:
Last updated 3/21/2011
649
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
Property
Description
Capabilities.hasIME
Specifies whether the player is running on a system that does (true) or does not (false) have an
input method editor (IME) installed.
Capabilities.language
Specifies the language code of the system on which the player is running.
Capabilities.os
Specifies the current operating system.
Note: Be careful when using Capabilities.os to determine system characteristics. If a more specific property exists to
determine a system characteristic, use it. Otherwise, you run the risk of writing code that does not work correctly on all
platforms. For example, consider the following code:
var separator:String;
if (Capablities.os.indexOf("Mac") > -1)
{
separator = "/";
}
else
{
separator = "\\";
}
This code leads to problems on Linux. It is better to simply use the File.separator property.
Working with directories
Adobe AIR 1.0 and later
The runtime provides you with capabilities to work with directories on the local file system.
For details on creating File objects that point to directories, see “Pointing a File object to a directory” on page 639.
Creating directories
Adobe AIR 1.0 and later
The File.createDirectory() method lets you create a directory. For example, the following code creates a directory
named AIR Test as a subdirectory of the user's home directory:
var dir:File = File.userDirectory.resolvePath("AIR Test");
dir.createDirectory();
If the directory exists, the createDirectory() method does nothing.
Also, in some modes, a FileStream object creates directories when opening files. Missing directories are created when
you instantiate a FileStream instance with the fileMode parameter of the FileStream() constructor set to
FileMode.APPEND or FileMode.WRITE. For more information, see “Workflow for reading and writing files” on
page 656.
Creating a temporary directory
Adobe AIR 1.0 and later
The File class includes a createTempDirectory() method, which creates a directory in the temporary directory
folder for the System, as in the following example:
Last updated 3/21/2011
650
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
var temp:File = File.createTempDirectory();
The createTempDirectory() method automatically creates a unique temporary directory (saving you the work of
determining a new unique location).
You can use a temporary directory to temporarily store temporary files used for a session of the application. Note that
there is a createTempFile() method for creating new, unique temporary files in the System temporary directory.
You may want to delete the temporary directory before closing the application, as it is not automatically deleted on all
devices.
Enumerating directories
Adobe AIR 1.0 and later
You can use the getDirectoryListing() method or the getDirectoryListingAsync() method of a File object to
get an array of File objects pointing to files and subfolders in a directory.
For example, the following code lists the contents of the user's documents directory (without examining
subdirectories):
var directory:File = File.documentsDirectory;
var contents:Array = directory.getDirectoryListing();
for (var i:uint = 0; i < contents.length; i++)
{
trace(contents[i].name, contents[i].size);
}
When using the asynchronous version of the method, the directoryListing event object has a files property that
is the array of File objects pertaining to the directories:
var directory:File = File.documentsDirectory;
directory.getDirectoryListingAsync();
directory.addEventListener(FileListEvent.DIRECTORY_LISTING, dirListHandler);
function dirListHandler(event:FileListEvent):void
{
var contents:Array = event.files;
for (var i:uint = 0; i < contents.length; i++)
{
trace(contents[i].name, contents[i].size);
}
}
Copying and moving directories
Adobe AIR 1.0 and later
You can copy or move a directory, using the same methods as you would to copy or move a file. For example, the
following code copies a directory synchronously:
var sourceDir:File = File.documentsDirectory.resolvePath("AIR Test");
var resultDir:File = File.documentsDirectory.resolvePath("AIR Test Copy");
sourceDir.copyTo(resultDir);
Last updated 3/21/2011
651
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
When you specify true for the overwrite parameter of the copyTo() method, all files and folders in an existing target
directory are deleted and replaced with the files and folders in the source directory (even if the target file does not exist
in the source directory).
The directory that you specify as the newLocation parameter of the copyTo() method specifies the path to the
resulting directory; it does not specify the parent directory that will contain the resulting directory.
For details, see “Copying and moving files” on page 652.
Deleting directory contents
Adobe AIR 1.0 and later
The File class includes a deleteDirectory() method and a deleteDirectoryAsync() method. These methods
delete directories, the first working synchronously, the second working asynchronously (see “AIR file basics” on
page 634). Both methods include a deleteDirectoryContents parameter (which takes a Boolean value); when this
parameter is set to true (the default value is false) the call to the method deletes non-empty directories; otherwise,
only empty directories are deleted.
For example, the following code synchronously deletes the AIR Test subdirectory of the user's documents directory:
var directory:File = File.documentsDirectory.resolvePath("AIR Test");
directory.deleteDirectory(true);
The following code asynchronously deletes the AIR Test subdirectory of the user's documents directory:
var directory:File = File.documentsDirectory.resolvePath("AIR Test");
directory.addEventListener(Event.COMPLETE, completeHandler)
directory.deleteDirectoryAsync(true);
function completeHandler(event:Event):void {
trace("Deleted.")
}
Also included are the moveToTrash() and moveToTrashAsync() methods, which you can use to move a directory to
the System trash. For details, see “Moving a file to the trash” on page 653.
Working with files
Adobe AIR 1.0 and later
Using the AIR file API, you can add basic file interaction capabilities to your applications. For example, you can read
and write files, copy and delete files, and so on. Since your applications can access the local file system, refer to “AIR
security” on page 1041, if you haven't already done so.
Note: You can associate a file type with an AIR application (so that double-clicking it opens the application). For details,
see “Managing file associations” on page 860.
Getting file information
Adobe AIR 1.0 and later
The File class includes the following properties that provide information about a file or directory to which a File object
points:
Last updated 3/21/2011
652
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
File property
Description
creationDate
The creation date of the file on the local disk.
creator
Obsolete—use the extension property. (This property reports the Macintosh creator type of the file,
which is only used in Mac OS versions prior to Mac OS X.)
downloaded
(AIR 2 and later) Indicates whether the referenced file or directory was downloaded (from the internet)
or not. property is only meaningful on operating systems in which files can be flagged as downloaded:
•
Windows XP service pack 2 and later, and on Windows Vista
•
Mac OS 10.5 and later
exists
Whether the referenced file or directory exists.
extension
The file extension, which is the part of the name following (and not including) the final dot ("."). If there
is no dot in the filename, the extension is null.
icon
An Icon object containing the icons defined for the file.
isDirectory
Whether the File object reference is to a directory.
modificationDate
The date that the file or directory on the local disk was last modified.
name
The name of the file or directory (including the file extension, if there is one) on the local disk.
nativePath
The full path in the host operating system representation. See “Paths of File objects” on page 635.
parent
The folder that contains the folder or file represented by the File object. This property is null if the File
object references a file or directory in the root of the file system.
size
The size of the file on the local disk in bytes.
type
Obsolete—use the extension property. (On the Macintosh, this property is the four-character file type,
which is only used in Mac OS versions prior to Mac OS X.)
url
The URL for the file or directory. See “Paths of File objects” on page 635.
For details on these properties, see the File class entry in the ActionScript 3.0 Reference for the Adobe Flash Platform.
Copying and moving files
Adobe AIR 1.0 and later
The File class includes two methods for copying files or directories: copyTo() and copyToAsync(). The File class
includes two methods for moving files or directories: moveTo() and moveToAsync(). The copyTo() and moveTo()
methods work synchronously, and the copyToAsync() and moveToAsync() methods work asynchronously (see “AIR
file basics” on page 634).
To copy or move a file, you set up two File objects. One points to the file to copy or move, and it is the object that calls
the copy or move method; the other points to the destination (result) path.
The following copies a test.txt file from the AIR Test subdirectory of the user's documents directory to a file named
copy.txt in the same directory:
var original:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var newFile:File = File.resolvePath("AIR Test/copy.txt");
original.copyTo(newFile, true);
In this example, the value of overwrite parameter of the copyTo() method (the second parameter) is set to true. By
setting overwrite to true, an existing target file is overwritten. This parameter is optional. If you set it to false (the
default value), the operation dispatches an IOErrorEvent event if the target file exists (and the file is not copied).
Last updated 3/21/2011
653
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
The “Async” versions of the copy and move methods work asynchronously. Use the addEventListener() method to
monitor completion of the task or error conditions, as in the following code:
var original = File.documentsDirectory;
original = original.resolvePath("AIR Test/test.txt");
var destination:File = File.documentsDirectory;
destination = destination.resolvePath("AIR Test 2/copy.txt");
original.addEventListener(Event.COMPLETE, fileMoveCompleteHandler);
original.addEventListener(IOErrorEvent.IO_ERROR, fileMoveIOErrorEventHandler);
original.moveToAsync(destination);
function fileMoveCompleteHandler(event:Event):void {
trace(event.target); // [object File]
}
function fileMoveIOErrorEventHandler(event:IOErrorEvent):void {
trace("I/O Error.");
}
The File class also includes the File.moveToTrash() and File.moveToTrashAsync() methods, which move a file
or directory to the system trash.
Deleting a file
Adobe AIR 1.0 and later
The File class includes a deleteFile() method and a deleteFileAsync() method. These methods delete files, the
first working synchronously, the second working asynchronously (see “AIR file basics” on page 634).
For example, the following code synchronously deletes the test.txt file in the user's documents directory:
var file:File = File.documentsDirectory.resolvePath("test.txt");
file.deleteFile();
The following code asynchronously deletes the test.txt file of the user's documents directory:
var file:File = File.documentsDirectory.resolvePath("test.txt");
file.addEventListener(Event.COMPLETE, completeHandler)
file.deleteFileAsync();
function completeHandler(event:Event):void {
trace("Deleted.")
}
Also included are the moveToTrash() and moveToTrashAsync methods, which you can use to move a file or directory
to the System trash. For details, see “Moving a file to the trash” on page 653.
Moving a file to the trash
Adobe AIR 1.0 and later
The File class includes a moveToTrash() method and a moveToTrashAsync() method. These methods send a file or
directory to the System trash, the first working synchronously, the second working asynchronously (see “AIR file
basics” on page 634).
Last updated 3/21/2011
654
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
For example, the following code synchronously moves the test.txt file in the user's documents directory to the System
trash:
var file:File = File.documentsDirectory.resolvePath("test.txt");
file.moveToTrash();
Note: On operating systems that do not support the concept of a recoverable trash folder, the files are removed
immediately.
Creating a temporary file
Adobe AIR 1.0 and later
The File class includes a createTempFile() method, which creates a file in the temporary directory folder for the
System, as in the following example:
var temp:File = File.createTempFile();
The createTempFile() method automatically creates a unique temporary file (saving you the work of determining a
new unique location).
You can use a temporary file to temporarily store information used in a session of the application. Note that there is
also a createTempDirectory() method, for creating a unique temporary directory in the System temporary
directory.
You may want to delete the temporary file before closing the application, as it is not automatically deleted on all
devices.
Working with storage volumes
Adobe AIR 2 and later
In AIR 2, you can detect when mass storage volumes are mounted or unmounted. The StorageVolumeInfo class
defines a singleton storageVolumeInfo object. The StorageVolumeInfo.storageVolumeInfo object dispatches a
storageVolumeMount event when a storage volume is mounted. And it dispatches a storageVolumeUnmount event
when a volume is unmounted. The StorageVolumeChangeEvent class defines these events.
Note: On modern Linux distributions, the StorageVolumeInfo object only dispatches storageVolumeMount and
storageVolumeUnmount events for physical devices and network drives mounted at particular locations.
The storageVolume property of the StorageVolumeChangeEvent class is a StorageVolume object. The
StorageVolume class defines basic properties of the storage volume:
•
drive—The volume drive letter on Windows (null on other operating systems)
•
fileSystemType—The type of file system on the storage volume (such as "FAT", "NTFS", "HFS", or "UFS")
•
isRemoveable—Whether a volume is removable (true) or not (false)
•
isWritable—Whether a volume is writable (true) or not (false)
•
name—The name of the volume
•
rootDirectory—A File object corresponding to the root directory of the volume
The StorageVolumeChangeEvent class also includes a rootDirectory property. The rootDirectory property is a
File object referencing the root directory of the storage volume that has been mounted or unmounted.
Last updated 3/21/2011
655
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
The storageVolume property of the StorageVolumeChangeEvent object is undefined (null) for an unmounted
volume. However you can access the rootDirectory property of the event.
The following code outputs the name and file path of a storage volume when it is mounted:
StorageVolumeInfo.storageVolumeInfo.addEventListener(StorageVolumeChangeEvent.STORAGE_VOLUME
_MOUNT, onVolumeMount);
function onVolumeMount(event:StorageVolumeChangeEvent):void
{
trace(event.storageVolume.name, event.rootDirectory.nativePath);
}
The following code outputs the file path of a storage volume when it is unmounted:
StorageVolumeInfo.storageVolumeInfo.addEventListener(StorageVolumeChangeEvent.STORAGE_VOLUME
_UNMOUNT, onVolumeUnmount);
function onVolumeUnmount(event:StorageVolumeChangeEvent):void
{
trace(event.rootDirectory.nativePath);
}
The StorageVolumeInfo.storageVolumeInfo object includes a getStorageVolumes() method. This method
returns a vector of StorageVolume objects corresponding to the currently mounted storage volumes. The following
code shows how to list the names and root directories of all mounted storage volumes:
var volumes:Vector. = new Vector.;
volumes = StorageVolumeInfo.storageVolumeInfo.getStorageVolumes();
for (var i:int = 0; i < volumes.length; i++)
{
trace(volumes[i].name, volumes[i].rootDirectory.nativePath);
}
Note: On modern Linux distributions, the getStorageVolumes() method returns objects corresponding to physical
devices and network drives mounted at particular locations.
The File.getRootDirectories() method lists the root directories (see “Pointing to the file system root” on
page 641. However, the StorageVolume objects (enumerated by the StorageVolumeInfo.getStorageVolumes()
method) provides more information about the storage volumes.
You can use the spaceAvailable property of the rootDirectory property of a StorageVolume object to get the space
available on a storage volume. (See “Determining space available on a volume” on page 647.)
For information about storage volumes on AIR for TV devices, see “Directory view for AIR for TV applications” on
page 638.
More Help topics
StorageVolume
StorageVolumeInfo
Reading and writing files
Adobe AIR 1.0 and later
The FileStream class lets AIR applications read and write to the file system.
Last updated 3/21/2011
656
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
Workflow for reading and writing files
Adobe AIR 1.0 and later
The workflow for reading and writing files is as follows.
Initialize a File object that points to the path.
The File object represents the path of the file that you want to work with (or a file that you will later create).
var file:File = File.documentsDirectory;
file = file.resolvePath("AIR Test/testFile.txt");
This example uses the File.documentsDirectory property and the resolvePath() method of a File object to
initialize the File object. However, there are many other ways to point a File object to a file. For more information, see
“Pointing a File object to a file” on page 642.
Initialize a FileStream object.
Call the open() method or the openAsync() method of the FileStream object.
The method you call depends on whether you want to open the file for synchronous or asynchronous operations. Use
the File object as the file parameter of the open method. For the fileMode parameter, specify a constant from the
FileMode class that specifies the way in which you will use the file.
For example, the following code initializes a FileStream object that is used to create a file and overwrite any existing data:
var fileStream:FileStream = new FileStream();
fileStream.open(file, FileMode.WRITE);
For more information, see “Initializing a FileStream object, and opening and closing files” on page 657 and
“FileStream open modes” on page 657.
If you opened the file asynchronously (using the openAsync() method), add and set up event listeners for the
FileStream object.
These event listener methods respond to events dispatched by the FileStream object in various situations. These
situations include when data is read in from the file, when I/O errors are encountered, or when the complete amount
of data to be written has been written.
For details, see “Asynchronous programming and the events generated by a FileStream object opened asynchronously”
on page 661.
Include code for reading and writing data, as needed.
There are many methods of the FileStream class related to reading and writing. (They each begin with "read" or
"write".) The method you choose to use to read or write data depends on the format of the data in the target file.
For example, if the data in the target file is UTF-encoded text, you may use the readUTFBytes() and
writeUTFBytes() methods. If you want to deal with the data as byte arrays, you may use the readByte(),
readBytes(), writeByte(), and writeBytes() methods. For details, see “Data formats, and choosing the read and
write methods to use” on page 662.
If you opened the file asynchronously, then be sure that enough data is available before calling a read method. For
details, see “The read buffer and the bytesAvailable property of a FileStream object” on page 660.
Before writing to a file, if you want to check the amount of disk space available, you can check the spaceAvailable
property of the File object. For more information, see “Determining space available on a volume” on page 647.
Last updated 3/21/2011
657
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
Call the close() method of the FileStream object when you are done working with the file.
Calling the close() method makes the file available to other applications.
For details, see “Initializing a FileStream object, and opening and closing files” on page 657.
To see a sample application that uses the FileStream class to read and write files, see the following articles at the Adobe
AIR Developer Center:
• Building a text-file editor
• Building a text-file editor
• Reading and writing from an XML preferences file
Working with FileStream objects
Adobe AIR 1.0 and later
The FileStream class defines methods for opening, reading, and writing files.
FileStream open modes
Adobe AIR 1.0 and later
The open() and openAsync() methods of a FileStream object each include a fileMode parameter, which defines
some properties for a file stream, including the following:
• The ability to read from the file
• The ability to write to the file
• Whether data will always be appended past the end of the file (when writing)
• What to do when the file does not exist (and when its parent directories do not exist)
The following are the various file modes (which you can specify as the fileMode parameter of the open() and
openAsync() methods):
File mode
Description
FileMode.READ
Specifies that the file is open for reading only.
FileMode.WRITE
Specifies that the file is open for writing. If the file does not exist, it is created when the FileStream object
is opened. If the file does exist, any existing data is deleted.
FileMode.APPEND
Specifies that the file is open for appending. The file is created if it does not exist. If the file exists, existing
data is not overwritten, and all writing begins at the end of the file.
FileMode.UPDATE
Specifies that the file is open for reading and writing. If the file does not exist, it is created. Specify this
mode for random read/write access to the file. You can read from any position in the file. When writing
to the file, only the bytes written overwrite existing bytes (all other bytes remain unchanged).
Initializing a FileStream object, and opening and closing files
Adobe AIR 1.0 and later
When you open a FileStream object, you make it available to read and write data to a file. You open a FileStream object
by passing a File object to the open() or openAsync() method of the FileStream object:
Last updated 3/21/2011
658
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.open(myFile, FileMode.READ);
The fileMode parameter (the second parameter of the open() and openAsync() methods), specifies the mode in
which to open the file: for read, write, append, or update. For details, see the previous section, “FileStream open
modes” on page 657.
If you use the openAsync() method to open the file for asynchronous file operations, set up event listeners to handle
the asynchronous events:
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.addEventListener(Event.COMPLETE, completeHandler);
myFileStream.addEventListener(ProgressEvent.PROGRESS, progressHandler);
myFileStream.addEventListener(IOErrorEvent.IOError, errorHandler);
myFileStream.open(myFile, FileMode.READ);
function completeHandler(event:Event):void {
// ...
}
function progressHandler(event:ProgressEvent):void {
// ...
}
function errorHandler(event:IOErrorEvent):void {
// ...
}
The file is opened for synchronous or asynchronous operations, depending upon whether you use the open() or
openAsync() method. For details, see “AIR file basics” on page 634.
If you set the fileMode parameter to FileMode.READ or FileMode.UPDATE in the open method of the FileStream
object, data is read into the read buffer as soon as you open the FileStream object. For details, see “The read buffer and
the bytesAvailable property of a FileStream object” on page 660.
You can call the close() method of a FileStream object to close the associated file, making it available for use by other
applications.
The position property of a FileStream object
Adobe AIR 1.0 and later
The position property of a FileStream object determines where data is read or written on the next read or write
method.
Before a read or write operation, set the position property to any valid position in the file.
For example, the following code writes the string "hello" (in UTF encoding) at position 8 in the file:
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.open(myFile, FileMode.UPDATE);
myFileStream.position = 8;
myFileStream.writeUTFBytes("hello");
Last updated 3/21/2011
659
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
When you first open a FileStream object, the position property is set to 0.
Before a read operation, the value of position must be at least 0 and less than the number of bytes in the file (which
are existing positions in the file).
The value of the position property is modified only in the following conditions:
• When you explicitly set the position property.
• When you call a read method.
• When you call a write method.
When you call a read or write method of a FileStream object, the position property is immediately incremented by
the number of bytes that you read or write. Depending on the read method you use, the position property is either
incremented by the number of bytes you specify to read or by the number of bytes available. When you call a read or
write method subsequently, it reads or writes starting at the new position.
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.open(myFile, FileMode.UPDATE);
myFileStream.position = 4000;
trace(myFileStream.position); // 4000
myFileStream.writeBytes(myByteArray, 0, 200);
trace(myFileStream.position); // 4200
There is, however, one exception: for a FileStream opened in append mode, the position property is not changed after
a call to a write method. (In append mode, data is always written to the end of the file, independent of the value of the
position property.)
For a file opened for asynchronous operations, the write operation does not complete before the next line of code is
executed. However, you can call multiple asynchronous methods sequentially, and the runtime executes them in order:
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.openAsync(myFile, FileMode.WRITE);
myFileStream.writeUTFBytes("hello");
myFileStream.writeUTFBytes("world");
myFileStream.addEventListener(Event.CLOSE, closeHandler);
myFileStream.close();
trace("started.");
closeHandler(event:Event):void
{
trace("finished.");
}
The trace output for this code is the following:
started.
finished.
You can specify the position value immediately after you call a read or write method (or at any time), and the next
read or write operation will take place starting at that position. For example, note that the following code sets the
position property right after a call to the writeBytes() operation, and the position is set to that value (300) even
after the write operation completes:
Last updated 3/21/2011
660
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.openAsync(myFile, FileMode.UPDATE);
myFileStream.position = 4000;
trace(myFileStream.position); // 4000
myFileStream.writeBytes(myByteArray, 0, 200);
myFileStream.position = 300;
trace(myFileStream.position); // 300
The read buffer and the bytesAvailable property of a FileStream object
Adobe AIR 1.0 and later
When a FileStream object with read capabilities (one in which the fileMode parameter of the open() or openAsync()
method was set to READ or UPDATE) is opened, the runtime stores the data in an internal buffer. The FileStream object
begins reading data into the buffer as soon as you open the file (by calling the open() or openAsync() method of the
FileStream object).
For a file opened for synchronous operations (using the open() method), you can always set the position pointer to
any valid position (within the bounds of the file) and begin reading any amount of data (within the bounds of the file),
as shown in the following code (which assumes that the file contains at least 100 bytes):
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.open(myFile, FileMode.READ);
myFileStream.position = 10;
myFileStream.readBytes(myByteArray, 0, 20);
myFileStream.position = 89;
myFileStream.readBytes(myByteArray, 0, 10);
Whether a file is opened for synchronous or asynchronous operations, the read methods always read from the
"available" bytes, represented by the bytesAvalable property. When reading synchronously, all of the bytes of the file
are available all of the time. When reading asynchronously, the bytes become available starting at the position specified
by the position property, in a series of asynchronous buffer fills signaled by progress events.
For files opened for synchronous operations, the bytesAvailable property is always set to represent the number of
bytes from the position property to the end of the file (all bytes in the file are always available for reading).
For files opened for asynchronous operations, you need to ensure that the read buffer has consumed enough data
before calling a read method. For a file opened asynchronously, as the read operation progresses, the data from the file,
starting at the position specified when the read operation started, is added to the buffer, and the bytesAvailable
property increments with each byte read. The bytesAvailable property indicates the number of bytes available
starting with the byte at the position specified by the position property to the end of the buffer. Periodically, the
FileStream object sends a progress event.
For a file opened asynchronously, as data becomes available in the read buffer, the FileStream object periodically
dispatches the progress event. For example, the following code reads data into a ByteArray object, bytes, as it is read
into the buffer:
Last updated 3/21/2011
661
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
var bytes:ByteArray = new ByteArray();
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.addEventListener(ProgressEvent.PROGRESS, progressHandler);
myFileStream.openAsync(myFile, FileMode.READ);
function progressHandler(event:ProgressEvent):void
{
myFileStream.readBytes(bytes, myFileStream.position, myFileStream.bytesAvailable);
}
For a file opened asynchronously, only the data in the read buffer can be read. Furthermore, as you read the data, it is
removed from the read buffer. For read operations, you need to ensure that the data exists in the read buffer before
calling the read operation. For example, the following code reads 8000 bytes of data starting from position 4000 in the
file:
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.addEventListener(ProgressEvent.PROGRESS, progressHandler);
myFileStream.addEventListener(Event.COMPLETE, completed);
myFileStream.openAsync(myFile, FileMode.READ);
myFileStream.position = 4000;
var str:String = "";
function progressHandler(event:Event):void
{
if (myFileStream.bytesAvailable > 8000 )
{
str += myFileStream.readMultiByte(8000, "iso-8859-1");
}
}
During a write operation, the FileStream object does not read data into the read buffer. When a write operation
completes (all data in the write buffer is written to the file), the FileStream object starts a new read buffer (assuming
that the associated FileStream object was opened with read capabilities), and starts reading data into the read buffer,
starting from the position specified by the position property. The position property may be the position of the last
byte written, or it may be a different position, if the user specifies a different value for the position object after the
write operation.
Asynchronous programming and the events generated by a FileStream object opened asynchronously
Adobe AIR 1.0 and later
When a file is opened asynchronously (using the openAsync() method), reading and writing files are done
asynchronously. As data is read into the read buffer and as output data is being written, other ActionScript code can
execute.
This means that you need to register for events generated by the FileStream object opened asynchronously.
By registering for the progress event, you can be notified as new data becomes available for reading, as in the
following code:
Last updated 3/21/2011
662
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.addEventListener(ProgressEvent.PROGRESS, progressHandler);
myFileStream.openAsync(myFile, FileMode.READ);
var str:String = "";
function progressHandler(event:ProgressEvent):void
{
str += myFileStream.readMultiByte(myFileStream.bytesAvailable, "iso-8859-1");
}
You can read the entire data by registering for the complete event, as in the following code:
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.addEventListener(Event.COMPLETE, completed);
myFileStream.openAsync(myFile, FileMode.READ);
var str:String = "";
function completeHandler(event:Event):void
{
str = myFileStream.readMultiByte(myFileStream.bytesAvailable, "iso-8859-1");
}
In much the same way that input data is buffered to enable asynchronous reading, data that you write on an
asynchronous stream is buffered and written to the file asynchronously. As data is written to a file, the FileStream
object periodically dispatches an OutputProgressEvent object. An OutputProgressEvent object includes a
bytesPending property that is set to the number of bytes remaining to be written. You can register for the
outputProgress event to be notified as this buffer is actually written to the file, perhaps in order to display a progress
dialog. However, in general, it is not necessary to do so. In particular, you may call the close() method without
concern for the unwritten bytes. The FileStream object will continue writing data and the close event will be delivered
after the final byte is written to the file and the underlying file is closed.
Data formats, and choosing the read and write methods to use
Adobe AIR 1.0 and later
Every file is a set of bytes on a disk. In ActionScript, the data from a file can always be represented as a ByteArray. For
example, the following code reads the data from a file into a ByteArray object named bytes:
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.addEventListener(Event.COMPLETE, completeHandler);
myFileStream.openAsync(myFile, FileMode.READ);
var bytes:ByteArray = new ByteArray();
function completeHandler(event:Event):void
{
myFileStream.readBytes(bytes, 0, myFileStream.bytesAvailable);
}
Similarly, the following code writes data from a ByteArray named bytes to a file:
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.open(myFile, FileMode.WRITE);
myFileStream.writeBytes(bytes, 0, bytes.length);
Last updated 3/21/2011
663
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
However, often you do not want to store the data in an ActionScript ByteArray object. And often the data file is in a
specified file format.
For example, the data in the file may be in a text file format, and you may want to represent such data in a String object.
For this reason, the FileStream class includes read and write methods for reading and writing data to and from types
other than ByteArray objects. For example, the readMultiByte() method lets you read data from a file and store it to
a string, as in the following code:
var myFile:File = File.documentsDirectory.resolvePath("AIR Test/test.txt");
var myFileStream:FileStream = new FileStream();
myFileStream.addEventListener(Event.COMPLETE, completed);
myFileStream.openAsync(myFile, FileMode.READ);
var str:String = "";
function completeHandler(event:Event):void
{
str = myFileStream.readMultiByte(myFileStream.bytesAvailable, "iso-8859-1");
}
The second parameter of the readMultiByte() method specifies the text format that ActionScript uses to interpret
the data ("iso-8859-1" in the example). Adobe AIR supports common character set encodings (see Supported character
sets).
The FileStream class also includes the readUTFBytes() method, which reads data from the read buffer into a string
using the UTF-8 character set. Since characters in the UTF-8 character set are of variable length, do not use
readUTFBytes() in a method that responds to the progress event, since the data at the end of the read buffer may
represent an incomplete character. (This is also true when using the readMultiByte() method with a variable-length
character encoding.) For this reason, read the entire set of data when the FileStream object dispatches the complete
event.
There are also similar write methods, writeMultiByte() and writeUTFBytes(), for working with String objects and
text files.
The readUTF() and the writeUTF() methods (not to be confused with readUTFBytes() and writeUTFBytes())
also read and write the text data to a file, but they assume that the text data is preceded by data specifying the length of
the text data, which is not a common practice in standard text files.
Some UTF-encoded text files begin with a "UTF-BOM" (byte order mark) character that defines the endianness as well
as the encoding format (such as UTF-16 or UTF-32).
For an example of reading and writing to a text file, see “Example: Reading an XML file into an XML object” on
page 665.
The readObject() and writeObject() are convenient ways to store and retrieve data for complex ActionScript
objects. The data is encoded in AMF (ActionScript Message Format). Adobe AIR, Flash Player, Flash Media Server,
and Flex Data Services include APIs for working with data in this format.
There are some other read and write methods (such as readDouble() and writeDouble()). However, if you use
these, make sure that the file format matches the formats of the data defined by these methods.
File formats are often more complex than simple text formats. For example, an MP3 file includes compressed data that
can only be interpreted with the decompression and decoding algorithms specific to MP3 files. MP3 files also may
include ID3 tags that contain meta tag information about the file (such as the title and artist for a song). There are
multiple versions of the ID3 format, but the simplest (ID3 version 1) is discussed in the “Example: Reading and writing
data with random access” on page 666 section.
Last updated 3/21/2011
664
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
Other files formats (for images, databases, application documents, and so on) have different structures, and to work
with their data in ActionScript, you must understand how the data is structured.
Using the load() and save() methods
Flash Player 10 and later, Adobe AIR 1.5 and later
Flash Player 10 added the load() and save() methods to the FileReference class. These methods are also in AIR 1.5,
and the File class inherits the methods from the FileReference class. These methods were designed to provide a secure
means for users to load and save file data in Flash Player. However, AIR applications can also use these methods as an
easy way to load and save files asynchronously.
For example, the following code saves a string to a text file:
var file:File = File.applicationStorageDirectory.resolvePath("test.txt");
var str:String = "Hello.";
file.addEventListener(Event.COMPLETE, fileSaved);
file.save(str);
function fileSaved(event:Event):void
{
trace("Done.");
}
The data parameter of the save() method can take a String, XML, or ByteArray value. When the argument is a String
or XML value, the method saves the file as a UTF-8–encoded text file.
When this code sample executes, the application displays a dialog box in which the user selects the saved file
destination.
The following code loads a string from a UTF-8–encoded text file:
var file:File = File.applicationStorageDirectory.resolvePath("test.txt");
file.addEventListener(Event.COMPLETE, loaded);
file.load();
var str:String;
function loaded(event:Event):void
{
var bytes:ByteArray = file.data;
str = bytes.readUTFBytes(bytes.length);
trace(str);
}
The FileStream class provides more functionality than that provided by the load() and save() methods:
• Using the FileStream class, you can read and write data both synchronously and asynchronously.
• Using the FileStream class lets you write incrementally to a file.
• Using the FileStream class lets you open a file for random access (both reading from and writing to any section of
the file).
• The FileStream class lets you specify the type of file access you have to the file, by setting the fileMode parameter
of the open() or openAsync() method.
• The FileStream class lets you save data to files without presenting the user with an Open or Save dialog box.
• You can directly use types other than byte arrays when reading data with the FileStream class.
Last updated 3/21/2011
665
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
Example: Reading an XML file into an XML object
Adobe AIR 1.0 and later
The following examples demonstrate how to read and write to a text file that contains XML data.
To read from the file, initialize the File and FileStream objects, call the readUTFBytes() method of the FileStream and
convert the string to an XML object:
var file:File = File.documentsDirectory.resolvePath("AIR Test/preferences.xml");
var fileStream:FileStream = new FileStream();
fileStream.open(file, FileMode.READ);
var prefsXML:XML = XML(fileStream.readUTFBytes(fileStream.bytesAvailable));
fileStream.close();
Similarly, writing the data to the file is as easy as setting up appropriate File and FileStream objects, and then calling a
write method of the FileStream object. Pass the string version of the XML data to the write method as in the following
code:
var prefsXML:XML = true;
var file:File = File.documentsDirectory.resolvePath("AIR Test/preferences.xml");
fileStream = new FileStream();
fileStream.open(file, FileMode.WRITE);
var outputString:String = '\n';
outputString += prefsXML.toXMLString();
fileStream.writeUTFBytes(outputString);
fileStream.close();
These examples use the readUTFBytes() and writeUTFBytes() methods, because they assume that the files are in
UTF-8 format. If not, you may need to use a different method (see “Data formats, and choosing the read and write
methods to use” on page 662).
The previous examples use FileStream objects opened for synchronous operation. You can also open files for
asynchronous operations (which rely on event listener functions to respond to events). For example, the following
code shows how to read an XML file asynchronously:
var file:File = File.documentsDirectory.resolvePath("AIR Test/preferences.xml");
var fileStream:FileStream = new FileStream();
fileStream.addEventListener(Event.COMPLETE, processXMLData);
fileStream.openAsync(file, FileMode.READ);
var prefsXML:XML;
function processXMLData(event:Event):void
{
prefsXML = XML(fileStream.readUTFBytes(fileStream.bytesAvailable));
fileStream.close();
}
The processXMLData() method is invoked when the entire file is read into the read buffer (when the FileStream
object dispatches the complete event). It calls the readUTFBytes() method to get a string version of the read data,
and it creates an XML object, prefsXML, based on that string.
To see a sample application that shows these capabilities, see Reading and writing from an XML preferences file.
Last updated 3/21/2011
666
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
Example: Reading and writing data with random access
Adobe AIR 1.0 and later
MP3 files can include ID3 tags, which are sections at the beginning or end of the file that contain meta data identifying
the recording. The ID3 tag format itself has different revisions. This example describes how to read and write from an
MP3 file that contains the simplest ID3 format (ID3 version 1.0) using "random access to file data", which means that
it reads from and writes to arbitrary locations in the file.
An MP3 file that contains an ID3 version 1 tag includes the ID3 data at the end of the file, in the final 128 bytes.
When accessing a file for random read/write access, it is important to specify FileMode.UPDATE as the fileMode
parameter for the open() or openAsync() method:
var file:File = File.documentsDirectory.resolvePath("My Music/Sample ID3 v1.mp3");
var fileStr:FileStream = new FileStream();
fileStr.open(file, FileMode.UPDATE);
This lets you both read and write to the file.
Upon opening the file, you can set the position pointer to the position 128 bytes before the end of the file:
fileStr.position = file.size - 128;
This code sets the position property to this location in the file because the ID3 v1.0 format specifies that the ID3 tag
data is stored in the last 128 bytes of the file. The specification also says the following:
• The first 3 bytes of the tag contain the string "TAG".
• The next 30 characters contain the title for the MP3 track, as a string.
• The next 30 characters contain the name of the artist, as a string.
• The next 30 characters contain the name of the album, as a string.
• The next 4 characters contain the year, as a string.
• The next 30 characters contain the comment, as a string.
• The next byte contains a code indicating the track's genre.
• All text data is in ISO 8859-1 format.
The id3TagRead() method checks the data after it is read in (upon the complete event):
function id3TagRead():void
{
if (fileStr.readMultiByte(3, "iso-8859-1").match(/tag/i))
{
var id3Title:String = fileStr.readMultiByte(30, "iso-8859-1");
var id3Artist:String = fileStr.readMultiByte(30, "iso-8859-1");
var id3Album:String = fileStr.readMultiByte(30, "iso-8859-1");
var id3Year:String = fileStr.readMultiByte(4, "iso-8859-1");
var id3Comment:String = fileStr.readMultiByte(30, "iso-8859-1");
var id3GenreCode:String = fileStr.readByte().toString(10);
}
}
Last updated 3/21/2011
667
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with the file system
You can also perform a random-access write to the file. For example, you could parse the id3Title variable to ensure
that it is correctly capitalized (using methods of the String class), and then write a modified string, called newTitle,
to the file, as in the following:
fileStr.position = file.length - 125;
// 128 - 3
fileStr.writeMultiByte(newTitle, "iso-8859-1");
To conform with the ID3 version 1 standard, the length of the newTitle string should be 30 characters, padded at the
end with the character code 0 (String.fromCharCode(0)).
Last updated 3/21/2011
668
Chapter 37: Storing local data
Flash Player 9 and later, Adobe AIR 1.0 and later
You use the SharedObject class to store small amounts of data on the client computer. In Adobe AIR, you can also use
the EncryptedLocalStore class to store small amounts of privacy-sensitive user data on the local computer in an AIR
application.
You can also read and write files on the file system and (in Adobe AIR) access local database files. For more
information, see “Working with the file system” on page 620 and “Working with local SQL databases in AIR” on
page 681.
There are a number of security factors that relate to shared objects. For more information, see “Shared objects” on
page 1039 in “Security” on page 1008.
Shared objects
Flash Player 9 and later, Adobe AIR 1.0 and later
A shared object, sometimes referred to as a “Flash cookie,” is a data file that can be created on your computer by the
sites that you visit. Shared objects are most often used to enhance your web-browsing experience—for example, by
allowing you to personalize the look and feel of a website that you frequently visit.
About shared objects
Flash Player 9 and later, Adobe AIR 1.0 and later
Shared objects function like browser cookies. You use the SharedObject class to store data on the user’s local hard disk
and call that data during the same session or in a later session. Applications can access only their own SharedObject
data, and only if they are running on the same domain. The data is not sent to the server and is not accessible by other
applications running on other domains, but can be made accessible by applications from the same domain.
Shared objects compared with cookies
Flash Player 9 and later, Adobe AIR 1.0 and later
Cookies and shared objects are very similar. Because most web programmers are familiar with how cookies work, it
might be useful to compare cookies and local SharedObjects.
Cookies that adhere to the RFC 2109 standard generally have the following properties:
• They can expire, and often do at the end of a session by default.
• They can be disabled by the client on a site-specific basis.
• There is a limit of 300 cookies total, and 20 cookies maximum per site.
• They are usually limited to a size of 4 KB each.
• They are sometimes perceived to be a security threat, and as a result, they are sometimes disabled on the client.
• They are stored in a location specified by the client browser.
Last updated 3/21/2011
669
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Storing local data
• They are transmitted from client to server through HTTP.
In contrast, shared objects have the following properties:
• They do not expire by default.
• By default, they are limited to a size of 100 KB each.
• They can store simple data types (such as String, Array, and Date).
• They are stored in a location specified by the application (within the user’s home directory).
• They are never transmitted between the client and server.
About the SharedObject class
Flash Player 9 and later, Adobe AIR 1.0 and later
Using the SharedObject class, you can create and delete shared objects, as well as detect the current size of a
SharedObject object that you are using. The SharedObject class consists of the following methods.
Method
Description
clear()
Purges all of the data from the SharedObject object, and deletes the SharedObject file from the
disk.
flush()
Immediately writes the SharedObject file to a file on the client.
getLocal()
Returns a reference to the client’s domain-specific, local SharedObject object. If none exists, this
method creates a new shared object on the client.
getSize()
Gets the size of the SharedObject file, in bytes. The default size limit is 100 KB, although it can
be larger if the client allows it.
In addition to these methods, SharedObject objects have the following properties:
Property
Description
data
Read-only property that represents the collection of attributes the shared object stores.
onStatus
The shared object’s event handler that is invoked for every warning, error, or informational
note.
Creating a shared object
Flash Player 9 and later, Adobe AIR 1.0 and later
To create a SharedObject object, use the SharedObject.getLocal() method, which has the following syntax:
SharedObject.getLocal("objectName" [, pathname]): SharedObject
The following example creates a shared object called mySO:
public var mySO:SharedObject;
mySO = SharedObject.getLocal("preferences");
This creates a file on the client’s machine called preferences.sol.
The term local refers to the location of the shared object. In this case, Adobe® Flash® Player stores the SharedObject file
locally in the client’s home directory.
Last updated 3/21/2011
670
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Storing local data
When you create a shared object, Flash Player creates a new directory for the application and domain inside its
sandbox. It also creates a *.sol file that stores the SharedObject data. The default location of this file is a subdirectory
of the user’s home directory. The following table shows the default locations of this directory:
Operating System
Location
Windows
95/98/ME/2000/XP
c:/Documents and Settings/username/Application
Data/Macromedia/Flash Player/#SharedObjects
Windows Vista
c:/Users/username/AppData/Roaming/Macromedia/Flash
Player/#SharedObjects
Macintosh OS X
/Users/username/Library/Preferences/Macromedia/Flash
Player/#SharedObjects/web_domain/path_to_application/applicatio
n_name/object_name.sol
Linux/Unix
/home/username/.macromedia/Flash_Player/#SharedObjects/web_doma
in/path_to_application/application_name/object_name.sol
Below the #SharedObjects directory is a randomly-named directory. Below that is a directory that matches the
hostname, then the path to the application, and finally the *.sol file.
For example, if you request an application named MyApp.swf on the local host, and within a subdirectory named /sos,
Flash Player stores the *.sol file in the following location on Windows XP:
c:/Documents and Settings/fred/Application Data/Macromedia/Flash
Player/#SharedObjects/KROKWXRK/#localhost/sos/MyApp.swf/data.sol
Note: If you do not provide a name in the SharedObject.getLocal() method, Flash Player names the file
undefined.sol.
By default, Flash can save locally persistent SharedObject objects of up to 100 KB per domain. This value is userconfigurable. When the application tries to save data to a shared object that would make it bigger than 100 KB, Flash
Player displays the Local Storage dialog box, which lets the user allow or deny more local storage for the domain that
is requesting access.
Specifying a path
Flash Player 9 and later, Adobe AIR 1.0 and later
You can use the optional pathname parameter to specify a location for the SharedObject file. This file must be a
subdirectory of that domain’s SharedObject directory. For example, if you request an application on the localhost and
specify the following:
mySO = SharedObject.getLocal("myObjectFile","/");
Flash Player writes the SharedObject file in the /#localhost directory (or /localhost if the application is offline). This is
useful if you want more than one application on the client to be able to access the same shared object. In this case, the
client could run two Flex applications, both of which specify a path to the shared object that is the root of the domain;
the client could then access the same shared object from both applications. To share data between more than
application without persistence, you can use the LocalConnection object.
If you specify a directory that does not exist, Flash Player does not create a SharedObject file.
Last updated 3/21/2011
671
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Storing local data
Adding data to a shared object
Flash Player 9 and later, Adobe AIR 1.0 and later
You add data to a SharedObject’s *.sol file using the data property of the SharedObject object. To add new data to the
shared object, use the following syntax:
sharedObject_name.data.variable = value;
The following example adds the userName, itemNumbers, and adminPrivileges properties and their values to a
SharedObject:
public var currentUserName:String = "Reiner";
public var itemsArray:Array = new Array(101,346,483);
public var currentUserIsAdmin:Boolean = true;
mySO.data.userName = currentUserName;
mySO.data.itemNumbers = itemsArray;
mySO.data.adminPrivileges = currentUserIsAdmin;
After you assign values to the data property, you must instruct Flash Player to write those values to the SharedObject’s
file. To force Flash Player to write the values to the SharedObject’s file, use the SharedObject.flush() method, as
follows:
mySO.flush();
If you do not call the SharedObject.flush() method, Flash Player writes the values to the file when the application
quits. However, this does not provide the user with an opportunity to increase the available space that Flash Player has
to store the data if that data exceeds the default settings. Therefore, it is a good practice to call
SharedObject.flush().
When using the flush() method to write shared objects to a user’s hard drive, you should be careful to check whether
the user has explicitly disabled local storage using the Flash Player Settings Manager
(www.macromedia.com/support/documentation/en/flashplayer/help/settings_manager07.html), as shown in the
following example:
var so:SharedObject = SharedObject.getLocal("test");
trace("Current SharedObject size is " + so.size + " bytes.");
so.flush();
Storing objects in shared objects
You can store simple objects such as Arrays or Strings in a SharedObject’s data property.
The following example is an ActionScript class that defines methods that control the interaction with the shared object.
These methods let the user add and remove objects from the shared object. This class stores an ArrayCollection that
contains simple objects.
Last updated 3/21/2011
672
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Storing local data
package {
import mx.collections.ArrayCollection;
import flash.net.SharedObject;
public class LSOHandler {
private var mySO:SharedObject;
private var ac:ArrayCollection;
private var lsoType:String;
// The parameter is "feeds" or "sites".
public function LSOHandler(s:String) {
init(s);
}
private function init(s:String):void {
ac = new ArrayCollection();
lsoType = s;
mySO = SharedObject.getLocal(lsoType);
if (getObjects()) {
ac = getObjects();
}
}
public function getObjects():ArrayCollection {
return mySO.data[lsoType];
}
public function addObject(o:Object):void {
ac.addItem(o);
updateSharedObjects();
}
private function updateSharedObjects():void {
mySO.data[lsoType] = ac;
mySO.flush();
}
}
}
The following Flex application creates an instance of the ActionScript class for each of the types of shared objects it
needs. It then calls methods on that class when the user adds or removes blogs or site URLs.
Last updated 3/21/2011
673
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Storing local data
-1) {
localFeeds.removeItemAt(myFeedsGrid.selectedIndex);
}
}
private function addSite():void {
var o:Object = {name:ti3.text, date:new Date()};
lsosites.addObject(o);
localSites = lsosites.getObjects();
ti3.text = '';
}
private function removeSite():void {
if (mySitesGrid.selectedIndex > -1) {
localSites.removeItemAt(mySitesGrid.selectedIndex);
}
}
]]>
Last updated 3/21/2011
675
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Storing local data
Storing typed objects in shared objects
You can store typed ActionScript instances in shared objects. You do this by calling the
flash.net.registerClassAlias() method to register the class. If you create an instance of your class and store it
in the data member of your shared object and later read the object out, you will get a typed instance. By default, the
SharedObject objectEncoding property supports AMF3 encoding, and unpacks your stored instance from the
SharedObject object; the stored instance retains the same type you specified when you called the
registerClassAlias() method.
Creating multiple shared objects
Flash Player 9 and later, Adobe AIR 1.0 and later
You can create multiple shared objects for the same Flex application. To do this, you assign each of them a different
instance name, as the following example shows:
public var mySO:SharedObject = SharedObject.getLocal("preferences");
public var mySO2:SharedObject = SharedObject.getLocal("history");
This creates a preferences.sol file and a history.sol file in the Flex application’s local directory.
Creating a secure SharedObject
Flash Player 9 and later, Adobe AIR 1.0 and later
When you create either a local or remote SharedObject using getLocal() or getRemote(), there is an optional
parameter named secure that determines whether access to this shared object is restricted to SWF files that are
delivered over an HTTPS connection. If this parameter is set to true and your SWF file is delivered over HTTPS, Flash
Player creates a new secure shared object or gets a reference to an existing secure shared object. This secure shared
object can be read from or written to only by SWF files delivered over HTTPS that call SharedObject.getLocal()
with the secure parameter set to true. If this parameter is set to false and your SWF file is delivered over HTTPS,
Flash Player creates a new shared object or gets a reference to an existing shared object.
Last updated 3/21/2011
676
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Storing local data
This shared object can be read from or written to by SWF files delivered over non-HTTPS connections. If your SWF
file is delivered over a non-HTTPS connection and you try to set this parameter to true, the creation of a new shared
object (or the access of a previously created secure shared object) fails, an error is thrown, and the shared object is set
to null. If you attempt to run the following snippet from a non-HTTPS connection, the SharedObject.getLocal()
method will throw an error:
try
{
var so:SharedObject = SharedObject.getLocal("contactManager", null, true);
}
catch (error:Error)
{
trace("Unable to create SharedObject.");
}
Regardless of the value of this parameter, the created shared objects count toward the total amount of disk space
allowed for a domain.
Displaying contents of a shared object
Flash Player 9 and later, Adobe AIR 1.0 and later
Values are stored in shared objects within the data property. You can loop over each value within a shared object
instance by using a for..in loop, as the following example shows:
var so:SharedObject = SharedObject.getLocal("test");
so.data.hello = "world";
so.data.foo = "bar";
so.data.timezone = new Date().timezoneOffset;
for (var i:String in so.data)
{
trace(i + ":\t" + so.data[i]);
}
Destroying shared objects
Flash Player 9 and later, Adobe AIR 1.0 and later
To destroy a SharedObject on the client, use the SharedObject.clear() method. This does not destroy directories
in the default path for the application’s shared objects.
The following example deletes the SharedObject file from the client:
public function destroySharedObject():void {
mySO.clear();
}
SharedObject example
Flash Player 9 and later, Adobe AIR 1.0 and later
The following example shows that you can store simple objects, such as a Date object, in a SharedObject object without
having to manually serialize and deserialize those objects.
Last updated 3/21/2011
677
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Storing local data
The following example begins by welcoming you as a first-time visitor. When you click Log Out, the application stores
the current date in a shared object. The next time you launch this application or refresh the page, the application
welcomes you back with a reminder of the time you logged out.
To see the application in action, launch the application, click Log Out, and then refresh the page. The application
displays the date and time that you clicked the Log Out button on your previous visit. At any time, you can delete the
stored information by clicking the Delete LSO button.
Encrypted local storage
The Adobe® AIR® runtime provides a persistent encrypted local store (ELS) for each AIR application installed on a
user's computer. This lets you save and retrieve data that is stored on the user’s local hard drive in an encrypted format
that cannot easily be deciphered by other users. A separate encrypted local store is used for each AIR application, and
each AIR application uses a separate encrypted local store for each user.
Last updated 3/21/2011
678
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Storing local data
Note: In addition to the encrypted local store, AIR also provides encryption for content stored in SQL databases. For
details, see “Using encryption with SQL databases” on page 725.
You may want to use the encrypted local store to cache information that must be secured, such as login credentials for
web services. The ELS is appropriate for storing information that must be kept private from other users. It does not,
however, protect the data from other processes run under the same user account. It is thus not appropriate for
protecting secret application data, such as DRM or encryption keys.
AIR uses DPAPI on Windows, KeyChain on Mac OS, and KeyRing or KWallet on Linux to associate the encrypted
local store to each application and user. The encrypted local store uses AES-CBC 128-bit encryption.
Information in the encrypted local store is only available to AIR application content in the application security
sandbox.
If you update an AIR application, the updated version retains access to any existing data in the encrypted local store
unless:
• The items were added with the stronglyBound parameter set to true
• The existing and update versions are both published prior to AIR 1.5.3 and the update is signed with a migration
signature.
Limitations of the encrypted local store
The data in the encrypted local store is protected by the user’s operating system account credentials. Other entities
cannot access the data in the store unless they can login as that user. However, the data is not secure against access by
other applications run by an authenticated user.
Because the user must be authenticated for these attacks to work, the user’s private data is still protected (unless the
user account itself is compromised). However, data that your application may want to keep secret from users, such as
keys used for licensing or digital rights management, is not secure. Thus the ELS is not an appropriate location for
storing such information. It is only an appropriate place for storing a user’s private data, such as passwords.
Data in the ELS can be lost for a variety of reasons. For example, the user could uninstall the application and delete the
encrypted file. Or, the publisher ID could be changed as a result of an update. Thus the ELS should be treated as a
private cache, not a permanent data storage.
The stronglyBound parameter is deprecated and should not be set to true. Setting the parameter to true does not
provide any additional protection for data. At the same time, access to the data is lost whenever the application is
updated — even if the publisher ID stays the same.
The encrypted local store may perform more slowly if the stored data exceeds 10MB.
When you uninstall an AIR application, the uninstaller does not delete data stored in the encrypted local store.
The best practices for using the ELS include:
• Use the ELS to store sensitive user data such as passwords (setting stronglyBound to false)
• Do not use the ELS to store applications secrets such as DRM keys or licensing tokens.
• Provide a way for your application to recreate the data stored in the ELS if the ELS data is lost. For example, by
prompting the user to re-enter their account credentials when necessary.
• Do not use the stronglyBound parameter.
• If you do set stronglyBound to true, do not migrate stored items during an update. Recreate the data after the
update instead.
• Only store relatively small amounts of data. For larger amounts of data, use an AIR SQL database with encryption.
Last updated 3/21/2011
679
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Storing local data
More Help topics
flash.data.EncryptedLocalStore
Adding data to the encrypted local store
Use the setItem() static method of the EncryptedLocalStore class to store data in the local store. The data is stored
in a hash table, using strings as keys, with the data stored as byte arrays.
For example, the following code stores a string in the encrypted local store:
var str:String = "Bob";
var bytes:ByteArray = new ByteArray();
bytes.writeUTFBytes(str);
EncryptedLocalStore.setItem("firstName", bytes);
The third parameter of the setItem() method, the stronglyBound parameter, is optional. When this parameter is
set to true, the encrypted local store binds the stored item to the storing AIR application’s digital signature and bits:
var str:String = "Bob";
var bytes:ByteArray = new ByteArray();
bytes.writeUTFBytes(str);
EncryptedLocalStore.setItem("firstName", bytes, false);
For an item that is stored with stronglyBound set to true, subsequent calls to getItem() only succeed if the calling
AIR application is identical to the storing application (if no data in files in the application directory have changed). If
the calling AIR application is different from the storing application, the application throws an Error exception when
you call getItem() for a strongly bound item. If you update your application, it will not be able to read strongly bound
data previously written to the encrypted local store.
If the stronglyBound parameter is set to false (the default), only the publisher ID needs to stay the same for the
application to read the data. The bits of the application may change (and they need to be signed by the same publisher),
but they do not need to be the exact same bits as were in application that stored the data. Updated applications with
the same publisher ID as the original can continue to access the data.
Note: In practice, setting stronglyBound to true does not add any additional data protection. A “malicious” user could
still alter an application to gain access to items stored in the ELS. Furthermore, data is protected from external, non-user
threats just as strongly whether stronglyBound is set to true or false. For these reasons, setting stronglyBound to
true is discouraged.
Accessing data in the encrypted local store
Adobe AIR 1.0 and later
You can retrieve a value from the encrypted local store by using the EncryptedLocalStore.getItem() method, as
in the following example:
var storedValue:ByteArray = EncryptedLocalStore.getItem("firstName");
trace(storedValue.readUTFBytes(storedValue.length)); // "Bob"
Last updated 3/21/2011
680
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Storing local data
Removing data from the encrypted local store
Adobe AIR 1.0 and later
You can delete a value from the encrypted local store by using the EncryptedLocalStore.removeItem() method,
as in the following example:
EncryptedLocalStore.removeItem("firstName");
You can clear all data from the encrypted local store by calling the EncryptedLocalStore.reset() method, as in the
following example:
EncryptedLocalStore.reset();
Last updated 3/21/2011
681
Chapter 38: Working with local SQL
databases in AIR
Adobe AIR 1.0 and later
Adobe® AIR® includes the capability of creating and working with local SQL databases. The runtime includes a SQL
database engine with support for many standard SQL features, using the open source SQLite database system. A local
SQL database can be used for storing local, persistent data. For example, it can be used for application data, application
user settings, documents, or any other type of data that you want your application to save locally.
About local SQL databases
Adobe AIR 1.0 and later
For a quick explanation and code examples of using SQL databases, see the following quick start articles on the Adobe
Developer Connection:
• Working asynchronously with a local SQL database (Flex)
• Working synchronously with a local SQL database (Flex)
• Using an encrypted database (Flex)
• Working asynchronously with a local SQL database (Flash)
• Working synchronously with a local SQL database (Flash)
• Using an encrypted database (Flash)
Adobe AIR includes a SQL-based relational database engine that runs within the runtime, with data stored locally in
database files on the computer on which the AIR application runs (for example, on the computer’s hard drive). Because
the database runs and data files are stored locally, a database can be used by an AIR application regardless of whether
a network connection is available. Thus, the runtime’s local SQL database engine provides a convenient mechanism
for storing persistent, local application data, particularly if you have experience with SQL and relational databases.
Uses for local SQL databases
Adobe AIR 1.0 and later
The AIR local SQL database functionality can be used for any purpose for which you might want to store application
data on a user’s local computer. Adobe AIR includes several mechanisms for storing data locally, each of which has
different advantages. The following are some possible uses for a local SQL database in your AIR application:
• For a data-oriented application (for example an address book), a database can be used to store the main application data.
• For a document-oriented application, where users create documents to save and possibly share, each document
could be saved as a database file, in a user-designated location. (Note, however, that unless the database is encrypted
any AIR application would be able to open the database file. Encryption is recommended for potentially sensitive
documents.)
Last updated 3/21/2011
682
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
• For a network-aware application, a database can be used to store a local cache of application data, or to store data
temporarily when a network connection isn’t available. You could create a mechanism for synchronizing the local
database with the network data store.
• For any application, a database can be used to store individual users’ application settings, such as user options or
application information like window size and position.
More Help topics
Christophe Coenraets: Employee Directory on AIR for Android
Raymond Camden: jQuery and AIR - Moving from web page to application
About AIR databases and database files
Adobe AIR 1.0 and later
An individual Adobe AIR local SQL database is stored as a single file in the computer’s file system. The runtime
includes the SQL database engine that manages creation and structuring of database files and manipulation and
retrieval of data from a database file. The runtime does not specify how or where database data is stored on the file
system; rather, each database is stored completely within a single file. You specify the location in the file system where
the database file is stored. A single AIR application can access one or many separate databases (that is, separate
database files). Because the runtime stores each database as a single file on the file system, you can locate your database
as needed by the design of your application and file access constraints of the operating system. Each user can have a
separate database file for their specific data, or a database file can be accessed by all application users on a single
computer for shared data. Because the data is local to a single computer, data is not automatically shared among users
on different computers. The local SQL database engine doesn’t provide any capability to execute SQL statements
against a remote or server-based database.
About relational databases
Adobe AIR 1.0 and later
A relational database is a mechanism for storing (and retrieving) data on a computer. Data is organized into tables:
rows represent records or items, and columns (sometimes called “fields”) divide each record into individual values.
For example, an address book application could contain a “friends” table. Each row in the table would represent a
single friend stored in the database. The table’s columns would represent data such as first name, last name, birth date,
and so forth. For each friend row in the table, the database stores a separate value for each column.
Relational databases are designed to store complex data, where one item is associated with or related to items of
another type. In a relational database, any data that has a one-to-many relationship—where a single record can be
related to multiple records of a different type—should be divided among different tables. For example, suppose you
want your address book application to store multiple phone numbers for each friend; this is a one-to-many
relationship. The “friends” table would contain all the personal information for each friend. A separate “phone
numbers” table would contain all the phone numbers for all the friends.
In addition to storing the data about friends and phone numbers, each table would need a piece of data to keep track
of the relationship between the two tables—to match individual friend records with their phone numbers. This data is
known as a primary key—a unique identifier that distinguishes each row in a table from other rows in that table. The
primary key can be a “natural key,” meaning it’s one of the items of data that naturally distinguishes each record in a
table. In the “friends” table, if you knew that none of your friends share a birth date, you could use the birth date
column as the primary key (a natural key) of the “friends” table. If there isn’t a natural key, you would create a separate
primary key column such as a “friend id” —an artificial value that the application uses to distinguish between rows.
Last updated 3/21/2011
683
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
Using a primary key, you can set up relationships between multiple tables. For example, suppose the “friends” table
has a column “friend id” that contains a unique number for each row (each friend). The related “phone numbers” table
can be structured with two columns: one with the “friend id” of the friend to whom the phone number belongs, and
one with the actual phone number. That way, no matter how many phone numbers a single friend has, they can all be
stored in the “phone numbers” table and can be linked to the related friend using the “friend id” primary key. When a
primary key from one table is used in a related table to specify the connection between the records, the value in the
related table is known as a foreign key. Unlike many databases, the AIR local database engine does not allow you to
create foreign key constraints, which are constraints that automatically check that an inserted or updated foreign key
value has a corresponding row in the primary key table. Nevertheless, foreign key relationships are an important part
of the structure of a relational database, and foreign keys should be used when creating relationships between tables in
your database.
About SQL
Adobe AIR 1.0 and later
Structured Query Language (SQL) is used with relational databases to manipulate and retrieve data. SQL is a descriptive
language rather than a procedural language. Instead of giving the computer instructions on how it should retrieve data,
a SQL statement describes the set of data you want. The database engine determines how to retrieve that data.
The SQL language has been standardized by the American National Standards Institute (ANSI). The Adobe AIR local
SQL database supports most of the SQL-92 standard.
For specific descriptions of the SQL language supported in Adobe AIR, see “SQL support in local databases” on
page 1068.
About SQL database classes
Adobe AIR 1.0 and later
To work with local SQL databases in ActionScript 3.0, you use instances of these classes in the flash.data package:
Class
Description
flash.data.SQLConnection
Provides the means to create and open databases (database files), as well as methods for performing
database-level operations and for controlling database transactions.
flash.data.SQLStatement
Represents a single SQL statement (a single query or command) that is executed on a database, including
defining the statement text and setting parameter values.
flash.data.SQLResult
Provides a way to get information about or results from executing a statement, such as the result rows from
a SELECT statement, the number of rows affected by an UPDATE or DELETE statement, and so forth.
To obtain schema information describing the structure of a database, you use these classes in the flash.data package:
Class
Description
flash.data.SQLSchemaResult
Serves as a container for database schema results generated by calling the
SQLConnection.loadSchema() method.
flash.data.SQLTableSchema
Provides information describing a single table in a database.
Last updated 3/21/2011
684
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
Class
Description
flash.data.SQLViewSchema
Provides information describing a single view in a database.
flash.data.SQLIndexSchema
Provides information describing a single column of a table or view in a database.
flash.data.SQLTriggerSchem
a
Provides information describing a single trigger in a database.
Other classes in the flash.data package provide constants that are used with the SQLConnection class and the
SQLColumnSchema class:
Class
Description
flash.data.SQLMode
Defines a set of constants representing the possible values for the openMode parameter of the
SQLConnection.open() and SQLConnection.openAsync() methods.
flash.data.SQLColumnNameStyle
Defines a set of constants representing the possible values for the SQLConnection.columnNameStyle
property.
flash.data.SQLTransactionLockType Defines a set of constants representing the possible values for the option parameter of the
SQLConnection.begin() method.
flash.data.SQLCollationType
Defines a set of constants representing the possible values for the
SQLColumnSchema.defaultCollationType property and the defaultCollationType parameter
of the SQLColumnSchema() constructor.
In addition, the following classes in the flash.events package represent the events (and supporting constants) that you use:
Class
Description
flash.events.SQLEvent
Defines the events that a SQLConnection or SQLStatement instance dispatches when any of its operations
execute successfully. Each operation has an associated event type constant defined in the SQLEvent class.
flash.events.SQLErrorEvent
Defines the event that a SQLConnection or SQLStatement instance dispatches when any of its operations
results in an error.
flash.events.SQLUpdateEven Defines the event that a SQLConnection instances dispatches when table data in one of its connected
t
databases changes as a result of an INSERT, UPDATE, or DELETE SQL statement being executed.
Finally, the following classes in the flash.errors package provide information about database operation errors:
Class
Description
flash.errors.SQLError
Provides information about a database operation error, including the operation that was being attempted
and the cause of the failure.
flash.errors.SQLErrorOperati
on
Defines a set of constants representing the possible values for the SQLError class’s operation property,
which indicates the database operation that resulted in an error.
About synchronous and asynchronous execution modes
Adobe AIR 1.0 and later
When you’re writing code to work with a local SQL database, you specify that database operations execution in one of
two execution modes: asynchronous or synchronous execution mode. In general, the code examples show how to
perform each operation in both ways, so that you can use the example that’s most appropriate for your needs.
Last updated 3/21/2011
685
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
In asynchronous execution mode, you give the runtime an instruction and the runtime dispatches an event when your
requested operation completes or fails. First you tell the database engine to perform an operation. The database engine
does its work in the background while the application continues running. Finally, when the operation is completed (or
when it fails) the database engine dispatches an event. Your code, triggered by the event, carries out subsequent
operations. This approach has a significant benefit: the runtime performs the database operations in the background
while the main application code continues executing. If the database operation takes a notable amount of time, the
application continues to run. Most importantly, the user can continue to interact with it without the screen freezing.
Nevertheless, asynchronous operation code can be more complex to write than other code. This complexity is usually
in cases where multiple dependent operations must be divided up among various event listener methods.
Conceptually, it is simpler to code operations as a single sequence of steps—a set of synchronous operations—rather
than a set of operations split into several event listener methods. In addition to asynchronous database operations,
Adobe AIR also allows you to execute database operations synchronously. In synchronous execution mode, operations
don’t run in the background. Instead they run in the same execution sequence as all other application code. You tell
the database engine to perform an operation. The code then pauses at that point while the database engine does its
work. When the operation completes, execution continues with the next line of your code.
Whether operations execute asynchronously or synchronously is set at the SQLConnection level. Using a single
database connection, you can’t execute some operations or statements synchronously and others asynchronously. You
specify whether a SQLConnection operates in synchronous or asynchronous execution mode by calling a
SQLConnection method to open the database. If you call SQLConnection.open() the connection operates in
synchronous execution mode, and if you call SQLConnection.openAsync() the connection operates in
asynchronous execution mode. Once a SQLConnection instance is connected to a database using open() or
openAsync(), it is fixed to synchronous or asynchronous execution mode unless you close and reopen the connection
to the database.
Each execution mode has benefits. While most aspects of each mode are similar, there are some differences you’ll want
to keep in mind when working in each mode. For more information on these topics, and suggestions for working in
each mode, see “Using synchronous and asynchronous database operations” on page 720.
Creating and modifying a database
Adobe AIR 1.0 and later
Before your application can add or retrieve data, there must be a database with tables defined in it that your application
can access. Described here are the tasks of creating a database and creating the data structure within a database. While
these tasks are less frequently used than data insertion and retrieval, they are necessary for most applications.
More Help topics
Mind the Flex: Updating an existing AIR database
Last updated 3/21/2011
686
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
Creating a database
Adobe AIR 1.0 and later
To create a database file, you first create a SQLConnection instance. You call its open() method to open it in
synchronous execution mode, or its openAsync() method to open it in asynchronous execution mode. The open()
and openAsync() methods are used to open a connection to a database. If you pass a File instance that refers to a nonexistent file location for the reference parameter (the first parameter), the open() or openAsync() method creates
a database file at that file location and open a connection to the newly created database.
Whether you call the open() method or the openAsync() method to create a database, the database file’s name can
be any valid filename, with any filename extension. If you call the open() or openAsync() method with null for the
reference parameter, a new in-memory database is created rather than a database file on disk.
The following code listing shows the process of creating a database file (a new database) using asynchronous execution
mode. In this case, the database file is saved in the “Pointing to the application storage directory” on page 639, with the
filename “DBSample.db”:
import
import
import
import
flash.data.SQLConnection;
flash.events.SQLErrorEvent;
flash.events.SQLEvent;
flash.filesystem.File;
var conn:SQLConnection = new SQLConnection();
conn.addEventListener(SQLEvent.OPEN, openHandler);
conn.addEventListener(SQLErrorEvent.ERROR, errorHandler);
// The database file is in the application storage directory
var folder:File = File.applicationStorageDirectory;
var dbFile:File = folder.resolvePath("DBSample.db");
conn.openAsync(dbFile);
function openHandler(event:SQLEvent):void
{
trace("the database was created successfully");
}
function errorHandler(event:SQLErrorEvent):void
{
trace("Error message:", event.error.message);
trace("Details:", event.error.details);
}
Last updated 3/21/2011
687
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
Note: Although the File class lets you point to a specific native file path, doing so can lead to applications that will not
work across platforms. For example, the path C:\Documents and Settings\joe\test.db only works on Windows. For these
reasons, it is best to use the static properties of the File class such as File.applicationStorageDirectory, as well as
the resolvePath() method (as shown in the previous example). For more information, see “Paths of File objects” on
page 635.
To execute operations synchronously, when you open a database connection with the SQLConnection instance, call
the open() method. The following example shows how to create and open a SQLConnection instance that executes its
operations synchronously:
Last updated 3/21/2011
688
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
import flash.data.SQLConnection;
import flash.errors.SQLError;
import flash.filesystem.File;
var conn:SQLConnection = new SQLConnection();
// The database file is in the application storage directory
var folder:File = File.applicationStorageDirectory;
var dbFile:File = folder.resolvePath("DBSample.db");
try
{
conn.open(dbFile);
trace("the database was created successfully");
}
catch (error:SQLError)
{
trace("Error message:", error.message);
trace("Details:", error.details);
}
Last updated 3/21/2011
689
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
Creating database tables
Adobe AIR 1.0 and later
Creating a table in a database involves executing a SQL statement on that database, using the same process that you
use to execute a SQL statement such as SELECT, INSERT, and so forth. To create a table, you use a CREATE TABLE
statement, which includes definitions of columns and constraints for the new table. For more information about
executing SQL statements, see “Working with SQL statements” on page 696.
The following example demonstrates creating a table named “employees” in an existing database file, using
asynchronous execution mode. Note that this code assumes there is a SQLConnection instance named conn that is
already instantiated and is already connected to a database.
import
import
import
import
flash.data.SQLConnection;
flash.data.SQLStatement;
flash.events.SQLErrorEvent;
flash.events.SQLEvent;
// ... create and open the SQLConnection instance named conn ...
var createStmt:SQLStatement = new SQLStatement();
createStmt.sqlConnection = conn;
var sql:String =
"CREATE TABLE IF NOT EXISTS employees (" +
"
empId INTEGER PRIMARY KEY AUTOINCREMENT, " +
"
firstName TEXT, " +
"
lastName TEXT, " +
"
salary NUMERIC CHECK (salary > 0)" +
")";
createStmt.text = sql;
createStmt.addEventListener(SQLEvent.RESULT, createResult);
createStmt.addEventListener(SQLErrorEvent.ERROR, createError);
createStmt.execute();
function createResult(event:SQLEvent):void
{
trace("Table created");
}
function createError(event:SQLErrorEvent):void
{
trace("Error message:", event.error.message);
trace("Details:", event.error.details);
}
Last updated 3/21/2011
690
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
0)" +
")";
createStmt.text = sql;
createStmt.addEventListener(SQLEvent.RESULT, createResult);
createStmt.addEventListener(SQLErrorEvent.ERROR, createError);
createStmt.execute();
}
private function createResult(event:SQLEvent):void
{
trace("Table created");
}
private function createError(event:SQLErrorEvent):void
{
trace("Error message:", event.error.message);
trace("Details:", event.error.details);
}
]]>
The following example demonstrates how to create a table named “employees” in an existing database file, using
synchronous execution mode. Note that this code assumes there is a SQLConnection instance named conn that is
already instantiated and is already connected to a database.
Last updated 3/21/2011
691
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
import flash.data.SQLConnection;
import flash.data.SQLStatement;
import flash.errors.SQLError;
// ... create and open the SQLConnection instance named conn ...
var createStmt:SQLStatement = new SQLStatement();
createStmt.sqlConnection = conn;
var sql:String =
"CREATE TABLE IF NOT EXISTS employees (" +
"
empId INTEGER PRIMARY KEY AUTOINCREMENT, " +
"
firstName TEXT, " +
"
lastName TEXT, " +
"
salary NUMERIC CHECK (salary > 0)" +
")";
createStmt.text = sql;
try
{
createStmt.execute();
trace("Table created");
}
catch (error:SQLError)
{
trace("Error message:", error.message);
trace("Details:", error.details);
}
Last updated 3/21/2011
692
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
0)" +
")";
createStmt.text = sql;
try
{
createStmt.execute();
trace("Table created");
}
catch (error:SQLError)
{
trace("Error message:", error.message);
trace("Details:", error.details);
}
}
]]>
Manipulating SQL database data
Adobe AIR 1.0 and later
There are some common tasks that you perform when you’re working with local SQL databases. These tasks include
connecting to a database, adding data to tables, and retrieving data from tables in a database. There are also several
issues you’ll want to keep in mind while performing these tasks, such as working with data types and handling errors.
Note that there are also several database tasks that are things you’ll deal with less frequently, but will often need to do
before you can perform these more common tasks. For example, before you can connect to a database and retrieve data
from a table, you’ll need to create the database and create the table structure in the database. Those less-frequent initial
setup tasks are discussed in “Creating and modifying a database” on page 685.
Last updated 3/21/2011
693
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
You can choose to perform database operations asynchronously, meaning the database engine runs in the background
and notifies you when the operation succeeds or fails by dispatching an event. You can also perform these operations
synchronously. In that case the database operations are performed one after another and the entire application
(including updates to the screen) waits for the operations to complete before executing other code. For more
information on working in asynchronous or synchronous execution mode, see “Using synchronous and asynchronous
database operations” on page 720.
Connecting to a database
Adobe AIR 1.0 and later
Before you can perform any database operations, first open a connection to the database file. A SQLConnection
instance is used to represent a connection to one or more databases. The first database that is connected using a
SQLConnection instance is known as the “main” database. This database is connected using the open() method (for
synchronous execution mode) or the openAsync() method (for asynchronous execution mode).
If you open a database using the asynchronous openAsync() operation, register for the SQLConnection instance’s
open event in order to know when the openAsync() operation completes. Register for the SQLConnection instance’s
error event to determine if the operation fails.
The following example shows how to open an existing database file for asynchronous execution. The database file is
named “DBSample.db” and is located in the user’s “Pointing to the application storage directory” on page 639.
import
import
import
import
import
flash.data.SQLConnection;
flash.data.SQLMode;
flash.events.SQLErrorEvent;
flash.events.SQLEvent;
flash.filesystem.File;
var conn:SQLConnection = new SQLConnection();
conn.addEventListener(SQLEvent.OPEN, openHandler);
conn.addEventListener(SQLErrorEvent.ERROR, errorHandler);
// The database file is in the application storage directory
var folder:File = File.applicationStorageDirectory;
var dbFile:File = folder.resolvePath("DBSample.db");
conn.openAsync(dbFile, SQLMode.UPDATE);
function openHandler(event:SQLEvent):void
{
trace("the database opened successfully");
}
function errorHandler(event:SQLErrorEvent):void
{
trace("Error message:", event.error.message);
trace("Details:", event.error.details);
}
Last updated 3/21/2011
694
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
The following example shows how to open an existing database file for synchronous execution. The database file is
named “DBSample.db” and is located in the user’s “Pointing to the application storage directory” on page 639.
Last updated 3/21/2011
695
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
import
import
import
import
flash.data.SQLConnection;
flash.data.SQLMode;
flash.errors.SQLError;
flash.filesystem.File;
var conn:SQLConnection = new SQLConnection();
// The database file is in the application storage directory
var folder:File = File.applicationStorageDirectory;
var dbFile:File = folder.resolvePath("DBSample.db");
try
{
conn.open(dbFile, SQLMode.UPDATE);
trace("the database opened successfully");
}
catch (error:SQLError)
{
trace("Error message:", error.message);
trace("Details:", error.details);
}
Last updated 3/21/2011
696
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
Notice that in the openAsync() method call in the asynchronous example, and the open() method call in the
synchronous example, the second argument is the constant SQLMode.UPDATE. Specifying SQLMode.UPDATE for the
second parameter (openMode) causes the runtime to dispatch an error if the specified file doesn’t exist. If you pass
SQLMode.CREATE for the openMode parameter (or if you leave the openMode parameter off), the runtime attempts to
create a database file if the specified file doesn’t exist. However, if the file exists it is opened, which is the same as if you
use SQLMode.Update. You can also specify SQLMode.READ for the openMode parameter to open an existing database
in a read-only mode. In that case data can be retrieved from the database but no data can be added, deleted, or changed.
Working with SQL statements
Adobe AIR 1.0 and later
An individual SQL statement (a query or command) is represented in the runtime as a SQLStatement object. Follow
these steps to create and execute a SQL statement:
Create a SQLStatement instance.
The SQLStatement object represents the SQL statement in your application.
var selectData:SQLStatement = new SQLStatement();
Specify which database the query runs against.
To do this, set the SQLStatement object’s sqlConnection property to the SQLConnection instance that’s connected
with the desired database.
// A SQLConnection named "conn" has been created previously
selectData.sqlConnection = conn;
Specify the actual SQL statement.
Create the statement text as a String and assign it to the SQLStatement instance’s text property.
selectData.text = "SELECT col1, col2 FROM my_table WHERE col1 = :param1";
Define functions to handle the result of the execute operation (asynchronous execution mode only).
Use the addEventListener() method to register functions as listeners for the SQLStatement instance’s result and
error events.
// using listener methods and addEventListener()
selectData.addEventListener(SQLEvent.RESULT, resultHandler);
selectData.addEventListener(SQLErrorEvent.ERROR, errorHandler);
function resultHandler(event:SQLEvent):void
{
// do something after the statement execution succeeds
}
function errorHandler(event:SQLErrorEvent):void
{
// do something after the statement execution fails
}
Alternatively, you can specify listener methods using a Responder object. In that case you create the Responder
instance and link the listener methods to it.
Last updated 3/21/2011
697
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
// using a Responder (flash.net.Responder)
var selectResponder = new Responder(onResult, onError);
function onResult(result:SQLResult):void
{
// do something after the statement execution succeeds
}
function onError(error:SQLError):void
{
// do something after the statement execution fails
}
If the statement text includes parameter definitions, assign values for those parameters.
To assign parameter values, use the SQLStatement instance’s parameters associative array property.
selectData.parameters[":param1"] = 25;
Execute the SQL statement.
Call the SQLStatement instance’s execute() method.
// using synchronous execution mode
// or listener methods in asynchronous execution mode
selectData.execute();
Additionally, if you’re using a Responder instead of event listeners in asynchronous execution mode, pass the
Responder instance to the execute() method.
// using a Responder in asynchronous execution mode
selectData.execute(-1, selectResponder);
For specific examples that demonstrate these steps, see the following topics:
“Retrieving data from a database” on page 700
“Inserting data” on page 710
“Changing or deleting data” on page 716
Using parameters in statements
Adobe AIR 1.0 and later
Using SQL statement parameters allows you to create a reusable SQL statement. When you use statement parameters,
values within the statement can change (such as values being added in an INSERT statement) but the basic statement
text remains unchanged. Consequently, using parameters provides performance benefits and makes it easier to code
an application.
Last updated 3/21/2011
698
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
Understanding statement parameters
Adobe AIR 1.0 and later
Frequently an application uses a single SQL statement multiple times in an application, with slight variation. For
example, consider an inventory-tracking application where a user can add new inventory items to the database. The
application code that adds an inventory item to the database executes a SQL INSERT statement that actually adds the
data to the database. However, each time the statement is executed there is a slight variation. Specifically, the actual
values that are inserted in the table are different because they are specific to the inventory item being added.
In cases where you have a SQL statement that’s used multiple times with different values in the statement, the best
approach is to use a SQL statement that includes parameters rather than literal values in the SQL text. A parameter is
a placeholder in the statement text that is replaced with an actual value each time the statement is executed. To use
parameters in a SQL statement, you create the SQLStatement instance as usual. For the actual SQL statement assigned
to the text property, use parameter placeholders rather than literal values. You then define the value for each
parameter by setting the value of an element in the SQLStatement instance’s parameters property. The parameters
property is an associative array, so you set a particular value using the following syntax:
statement.parameters[parameter_identifier] = value;
The parameter_identifier is a string if you’re using a named parameter, or an integer index if you’re using an unnamed
parameter.
Using named parameters
Adobe AIR 1.0 and later
A parameter can be a named parameter. A named parameter has a specific name that the database uses to match the
parameter value to its placeholder location in the statement text. A parameter name consists of the “:” or “@” character
followed by a name, as in the following examples:
:itemName
@firstName
The following code listing demonstrates the use of named parameters:
var sql:String =
"INSERT INTO inventoryItems (name, productCode)" +
"VALUES (:name, :productCode)";
var addItemStmt:SQLStatement = new SQLStatement();
addItemStmt.sqlConnection = conn;
addItemStmt.text = sql;
// set parameter values
addItemStmt.parameters[":name"] = "Item name";
addItemStmt.parameters[":productCode"] = "12345";
addItemStmt.execute();
Last updated 3/21/2011
699
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
Using unnamed parameters
Adobe AIR 1.0 and later
As an alternative to using named parameters, you can also use unnamed parameters. To use an unnamed parameter
you denote a parameter in a SQL statement using a “?” character. Each parameter is assigned a numeric index,
according to the order of the parameters in the statement, starting with index 0 for the first parameter. The following
example demonstrates a version of the previous example, using unnamed parameters:
var sql:String =
"INSERT INTO inventoryItems (name, productCode)" +
"VALUES (?, ?)";
var addItemStmt:SQLStatement = new SQLStatement();
addItemStmt.sqlConnection = conn;
addItemStmt.text = sql;
// set parameter values
addItemStmt.parameters[0] = "Item name";
addItemStmt.parameters[1] = "12345";
addItemStmt.execute();
Benefits of using parameters
Adobe AIR 1.0 and later
Using parameters in a SQL statement provides several benefits:
Better performance A SQLStatement instance that uses parameters can execute more efficiently compared to one that
dynamically creates the SQL text each time it executes. The performance improvement is because the statement is
prepared a single time and can then be executed multiple times using different parameter values, without needing to
recompile the SQL statement.
Explicit data typing Parameters are used to allow for typed substitution of values that are unknown at the time the SQL
statement is constructed. The use of parameters is the only way to guarantee the storage class for a value passed in to
the database. When parameters are not used, the runtime attempts to convert all values from their text representation
to a storage class based on the associated column's type affinity.
For more information on storage classes and column affinity, see “Data type support” on page 1089.
Greater security The use of parameters helps prevent a malicious technique known as a SQL injection attack. In a SQL
injection attack, a user enters SQL code in a user-accessible location (for example, a data entry field). If application
code constructs a SQL statement by directly concatenating user input into the SQL text, the user-entered SQL code is
executed against the database. The following listing shows an example of concatenating user input into SQL text. Do
not use this technique:
Last updated 3/21/2011
700
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
// assume the variables "username" and "password"
// contain user-entered data
var sql:String =
"SELECT userId " +
"FROM users " +
"WHERE username = '" + username + "' " +
"
AND password = '" + password + "'";
var statement:SQLStatement = new SQLStatement();
statement.text = sql;
Using statement parameters instead of concatenating user-entered values into a statement's text prevents a SQL
injection attack. SQL injection can’t happen because the parameter values are treated explicitly as substituted values,
rather than becoming part of the literal statement text. The following is the recommended alternative to the previous
listing:
// assume the variables "username" and "password"
// contain user-entered data
var sql:String =
"SELECT userId " +
"FROM users " +
"WHERE username = :username " +
"
AND password = :password";
var statement:SQLStatement = new SQLStatement();
statement.text = sql;
// set parameter values
statement.parameters[":username"] = username;
statement.parameters[":password"] = password;
Retrieving data from a database
Adobe AIR 1.0 and later
Retrieving data from a database involves two steps. First, you execute a SQL SELECT statement, describing the set of
data you want from the database. Next, you access the retrieved data and display or manipulate it as needed by your
application.
Executing a SELECT statement
Adobe AIR 1.0 and later
To retrieve existing data from a database, you use a SQLStatement instance. Assign the appropriate SQL SELECT
statement to the instance’s text property, then call its execute() method.
For details on the syntax of the SELECT statement, see “SQL support in local databases” on page 1068.
The following example demonstrates executing a SELECT statement to retrieve data from a table named “products,”
using asynchronous execution mode:
Last updated 3/21/2011
701
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
var selectStmt:SQLStatement = new SQLStatement();
// A SQLConnection named "conn" has been created previously
selectStmt.sqlConnection = conn;
selectStmt.text = "SELECT itemId, itemName, price FROM products";
selectStmt.addEventListener(SQLEvent.RESULT, resultHandler);
selectStmt.addEventListener(SQLErrorEvent.ERROR, errorHandler);
selectStmt.execute();
function resultHandler(event:SQLEvent):void
{
var result:SQLResult = selectStmt.getResult();
var numResults:int = result.data.length;
for (var i:int = 0; i < numResults; i++)
{
var row:Object = result.data[i];
var output:String = "itemId: " + row.itemId;
output += "; itemName: " + row.itemName;
output += "; price: " + row.price;
trace(output);
}
}
function errorHandler(event:SQLErrorEvent):void
{
// Information about the error is available in the
// event.error property, which is an instance of
// the SQLError class.
}
The following example demonstrates executing a SELECT statement to retrieve data from a table named “products,”
using synchronous execution mode:
Last updated 3/21/2011
703
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
var selectStmt:SQLStatement = new SQLStatement();
// A SQLConnection named "conn" has been created previously
selectStmt.sqlConnection = conn;
selectStmt.text = "SELECT itemId, itemName, price FROM products";
try
{
selectStmt.execute();
var result:SQLResult = selectStmt.getResult();
var numResults:int = result.data.length;
for (var i:int = 0; i < numResults; i++)
{
var row:Object = result.data[i];
var output:String = "itemId: " + row.itemId;
output += "; itemName: " + row.itemName;
output += "; price: " + row.price;
trace(output);
}
}
catch (error:SQLError)
{
// Information about the error is available in the
// error variable, which is an instance of
// the SQLError class.
}
In asynchronous execution mode, when the statement finishes executing, the SQLStatement instance dispatches a
result event (SQLEvent.RESULT) indicating that the statement was run successfully. Alternatively, if a Responder
object is passed as an argument to the execute() method, the Responder object’s result handler function is called. In
synchronous execution mode, execution pauses until the execute() operation completes, then continues on the next
line of code.
Accessing SELECT statement result data
Adobe AIR 1.0 and later
Once the SELECT statement has finished executing, the next step is to access the data that was retrieved. You retrieve
the result data from executing a SELECT statement by calling the SQLStatement object’s getResult() method:
var result:SQLResult = selectStatement.getResult();
The getResult() method returns a SQLResult object. The SQLResult object’s data property is an Array containing
the results of the SELECT statement:
var numResults:int = result.data.length;
for (var i:int = 0; i < numResults; i++)
{
// row is an Object representing one row of result data
var row:Object = result.data[i];
}
Each row of data in the SELECT result set becomes an Object instance contained in the data Array. That object has
properties whose names match the result set’s column names. The properties contain the values from the result set’s
columns. For example, suppose a SELECT statement specifies a result set with three columns named “itemId,”
“itemName,” and “price.” For each row in the result set, an Object instance is created with properties named itemId,
itemName, and price. Those properties contain the values from their respective columns.
Last updated 3/21/2011
705
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
The following code listing defines a SQLStatement instance whose text is a SELECT statement. The statement retrieves
rows containing the firstName and lastName column values of all the rows of a table named employees. This
example uses asynchronous execution mode. When the execution completes, the selectResult() method is called,
and the resulting rows of data are accessed using SQLStatement.getResult() and displayed using the trace()
method. Note that this listing assumes there is a SQLConnection instance named conn that has already been
instantiated and is already connected to the database. It also assumes that the “employees” table has already been
created and populated with data.
import
import
import
import
import
flash.data.SQLConnection;
flash.data.SQLResult;
flash.data.SQLStatement;
flash.events.SQLErrorEvent;
flash.events.SQLEvent;
// ... create and open the SQLConnection instance named conn ...
// create the SQL statement
var selectStmt:SQLStatement = new SQLStatement();
selectStmt.sqlConnection = conn;
// define the SQL text
var sql:String =
"SELECT firstName, lastName " +
"FROM employees";
selectStmt.text = sql;
// register listeners for the result and error events
selectStmt.addEventListener(SQLEvent.RESULT, selectResult);
selectStmt.addEventListener(SQLErrorEvent.ERROR, selectError);
// execute the statement
selectStmt.execute();
function selectResult(event:SQLEvent):void
{
// access the result data
var result:SQLResult = selectStmt.getResult();
var numRows:int = result.data.length;
for (var i:int = 0; i < numRows; i++)
{
var output:String = "";
for (var columnName:String in result.data[i])
{
output += columnName + ": " + result.data[i][columnName] + "; ";
}
trace("row[" + i.toString() + "]\t", output);
}
}
function selectError(event:SQLErrorEvent):void
{
trace("Error message:", event.error.message);
trace("Details:", event.error.details);
}
Last updated 3/21/2011
706
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
Last updated 3/21/2011
707
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
The following code listing demonstrates the same techniques as the preceding one, but uses synchronous execution
mode. The example defines a SQLStatement instance whose text is a SELECT statement. The statement retrieves rows
containing the firstName and lastName column values of all the rows of a table named employees. The resulting
rows of data are accessed using SQLStatement.getResult() and displayed using the trace() method. Note that this
listing assumes there is a SQLConnection instance named conn that has already been instantiated and is already
connected to the database. It also assumes that the “employees” table has already been created and populated with data.
import
import
import
import
flash.data.SQLConnection;
flash.data.SQLResult;
flash.data.SQLStatement;
flash.errors.SQLError;
// ... create and open the SQLConnection instance named conn ...
// create the SQL statement
var selectStmt:SQLStatement = new SQLStatement();
selectStmt.sqlConnection = conn;
// define the SQL text
var sql:String =
"SELECT firstName, lastName " +
"FROM employees";
selectStmt.text = sql;
try
{
// execute the statement
selectStmt.execute();
// access the result data
var result:SQLResult = selectStmt.getResult();
var numRows:int = result.data.length;
for (var i:int = 0; i < numRows; i++)
{
var output:String = "";
for (var columnName:String in result.data[i])
{
output += columnName + ": " + result.data[i][columnName] + "; ";
}
trace("row[" + i.toString() + "]\t", output);
}
}
catch (error:SQLError)
{
trace("Error message:", error.message);
trace("Details:", error.details);
}
Last updated 3/21/2011
708
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
Last updated 3/21/2011
709
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
Defining the data type of SELECT result data
Adobe AIR 1.0 and later
By default, each row returned by a SELECT statement is created as an Object instance with properties named for the
result set's column names and with the value of each column as the value of its associated property. However, before
executing a SQL SELECT statement, you can set the itemClass property of the SQLStatement instance to a class. By
setting the itemClass property, each row returned by the SELECT statement is created as an instance of the designated
class. The runtime assigns result column values to property values by matching the column names in the SELECT result
set to the names of the properties in the itemClass class.
Any class assigned as an itemClass property value must have a constructor that does not require any parameters. In
addition, the class must have a single property for each column returned by the SELECT statement. It is considered an
error if a column in the SELECT list does not have a matching property name in the itemClass class.
Retrieving SELECT results in parts
Adobe AIR 1.0 and later
By default, a SELECT statement execution retrieves all the rows of the result set at one time. Once the statement
completes, you usually process the retrieved data in some way, such as creating objects or displaying the data on the
screen. If the statement returns a large number of rows, processing all the data at once can be demanding for the
computer, which in turn will cause the user interface to not redraw itself.
You can improve the perceived performance of your application by instructing the runtime to return a specific number
of result rows at a time. Doing so causes the initial result data to return more quickly. It also allows you to divide the
result rows into sets, so that the user interface is updated after each set of rows is processed. Note that it’s only practical
to use this technique in asynchronous execution mode.
To retrieve SELECT results in parts, specify a value for the SQLStatement.execute() method’s first parameter (the
prefetch parameter). The prefetch parameter indicates the number of rows to retrieve the first time the statement
executes. When you call a SQLStatement instance’s execute() method, specify a prefetch parameter value and only
that many rows are retrieved:
var stmt:SQLStatement = new SQLStatement();
stmt.sqlConnection = conn;
stmt.text = "SELECT ...";
stmt.addEventListener(SQLEvent.RESULT, selectResult);
stmt.execute(20); // only the first 20 rows (or fewer) are returned
The statement dispatches the result event, indicating that the first set of result rows is available. The resulting
SQLResult instance’s data property contains the rows of data, and its complete property indicates whether there are
additional result rows to retrieve. To retrieve additional result rows, call the SQLStatement instance’s next() method.
Like the execute() method, the next() method’s first parameter is used to indicate how many rows to retrieve the
next time the result event is dispatched.
Last updated 3/21/2011
710
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
function selectResult(event:SQLEvent):void
{
var result:SQLResult = stmt.getResult();
if (result.data != null)
{
// ... loop through the rows or perform other processing ...
if (!result.complete)
{
stmt.next(20); // retrieve the next 20 rows
}
else
{
stmt.removeEventListener(SQLEvent.RESULT, selectResult);
}
}
}
The SQLStatement dispatches a result event each time the next() method returns a subsequent set of result rows.
Consequently, the same listener function can be used to continue processing results (from next() calls) until all the
rows are retrieved.
For more information, see the descriptions for the SQLStatement.execute() method (the prefetch parameter
description) and the SQLStatement.next() method.
Inserting data
Adobe AIR 1.0 and later
Adding data to a database involves executing a SQL INSERT statement. Once the statement has finished executing, you
can access the primary key for the newly inserted row if the key was generated by the database.
Executing an INSERT statement
Adobe AIR 1.0 and later
To add data to a table in a database, you create and execute a SQLStatement instance whose text is a SQL INSERT
statement.
The following example uses a SQLStatement instance to add a row of data to the already-existing employees table. This
example demonstrates inserting data using asynchronous execution mode. Note that this listing assumes that there is
a SQLConnection instance named conn that has already been instantiated and is already connected to a database. It
also assumes that the “employees” table has already been created.
Last updated 3/21/2011
711
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
import
import
import
import
import
flash.data.SQLConnection;
flash.data.SQLResult;
flash.data.SQLStatement;
flash.events.SQLErrorEvent;
flash.events.SQLEvent;
// ... create and open the SQLConnection instance named conn ...
// create the SQL statement
var insertStmt:SQLStatement = new SQLStatement();
insertStmt.sqlConnection = conn;
// define the SQL text
var sql:String =
"INSERT INTO employees (firstName, lastName, salary) " +
"VALUES ('Bob', 'Smith', 8000)";
insertStmt.text = sql;
// register listeners for the result and failure (status) events
insertStmt.addEventListener(SQLEvent.RESULT, insertResult);
insertStmt.addEventListener(SQLErrorEvent.ERROR, insertError);
// execute the statement
insertStmt.execute();
function insertResult(event:SQLEvent):void
{
trace("INSERT statement succeeded");
}
function insertError(event:SQLErrorEvent):void
{
trace("Error message:", event.error.message);
trace("Details:", event.error.details);
}
The following example adds a row of data to the already-existing employees table, using synchronous execution mode.
Note that this listing assumes that there is a SQLConnection instance named conn that has already been instantiated
and is already connected to a database. It also assumes that the “employees” table has already been created.
Last updated 3/21/2011
713
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
import
import
import
import
flash.data.SQLConnection;
flash.data.SQLResult;
flash.data.SQLStatement;
flash.errors.SQLError;
// ... create and open the SQLConnection instance named conn ...
// create the SQL statement
var insertStmt:SQLStatement = new SQLStatement();
insertStmt.sqlConnection = conn;
// define the SQL text
var sql:String =
"INSERT INTO employees (firstName, lastName, salary) " +
"VALUES ('Bob', 'Smith', 8000)";
insertStmt.text = sql;
try
{
// execute the statement
insertStmt.execute();
trace("INSERT statement succeeded");
}
catch (error:SQLError)
{
trace("Error message:", error.message);
trace("Details:", error.details);
}
Last updated 3/21/2011
714
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
Retrieving a database-generated primary key of an inserted row
Adobe AIR 1.0 and later
Often after inserting a row of data into a table, your code needs to know a database-generated primary key or row
identifier value for the newly inserted row. For example, once you insert a row in one table, you might want to add
rows in a related table. In that case you would want to insert the primary key value as a foreign key in the related table.
The primary key of a newly inserted row can be retrieved using the SQLResult object associated with the statement
execution. This is the same object that’s used to access result data after a SELECT statement is executed. As with any
SQL statement, when the execution of an INSERT statement completes the runtime creates a SQLResult instance. You
access the SQLResult instance by calling the SQLStatement object’s getResult() method if you’re using an event
listener or if you’re using synchronous execution mode. Alternatively, if you’re using asynchronous execution mode
and you pass a Responder instance to the execute() call, the SQLResult instance is passed as an argument to the result
handler function. In any case, the SQLResult instance has a property, lastInsertRowID, that contains the row
identifier of the most-recently inserted row if the executed SQL statement is an INSERT statement.
Last updated 3/21/2011
715
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
The following example demonstrates accessing the primary key of an inserted row in asynchronous execution mode:
insertStmt.text = "INSERT INTO ...";
insertStmt.addEventListener(SQLEvent.RESULT, resultHandler);
insertStmt.execute();
function resultHandler(event:SQLEvent):void
{
// get the primary key
var result:SQLResult = insertStmt.getResult();
var primaryKey:Number = result.lastInsertRowID;
// do something with the primary key
}
The following example demonstrates accessing the primary key of an inserted row in synchronous execution mode:
insertStmt.text = "INSERT INTO ...";
try
{
insertStmt.execute();
// get the primary key
var result:SQLResult = insertStmt.getResult();
var primaryKey:Number = result.lastInsertRowID;
// do something with the primary key
}
catch (error:SQLError)
{
// respond to the error
}
Note that the row identifier may or may not be the value of the column that is designated as the primary key column
in the table definition, according to the following rules:
• If the table is defined with a primary key column whose affinity (column data type) is INTEGER, the
lastInsertRowID property contains the value that was inserted into that row (or the value generated by the
runtime if it’s an AUTOINCREMENT column).
• If the table is defined with multiple primary key columns (a composite key) or with a single primary key column
whose affinity is not INTEGER, behind the scenes the database generates an integer row identifier value for the row.
That generated value is the value of the lastInsertRowID property.
• The value is always the row identifier of the most-recently inserted row. If an INSERT statement causes a trigger to
fire which in turn inserts a row, the lastInsertRowID property contains the row identifier of the last row inserted
by the trigger rather than the row created by the INSERT statement.
As a consequence of these rules, if you want to have an explicitly defined primary key column whose value is available
after an INSERT command through the SQLResult.lastInsertRowID property, the column must be defined as an
INTEGER PRIMARY KEY column. Even if your table does not include an explicit INTEGER PRIMARY KEY column, it is
equally acceptable to use the database-generated row identifier as a primary key for your table in the sense of defining
relationships with related tables. The row identifier column value is available in any SQL statement by using one of the
special column names ROWID, _ROWID_, or OID. You can create a foreign key column in a related table and use the row
Last updated 3/21/2011
716
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
identifier value as the foreign key column value just as you would with an explicitly declared INTEGER PRIMARY KEY
column. In that sense, if you are using an arbitrary primary key rather than a natural key, and as long as you don’t mind
the runtime generating the primary key value for you, it makes little difference whether you use an INTEGER PRIMARY
KEY column or the system-generated row identifier as a table’s primary key for defining a foreign key relationship with
between two tables.
For more information about primary keys and generated row identifiers, see “SQL support in local databases” on
page 1068.
Changing or deleting data
Adobe AIR 1.0 and later
The process for executing other data manipulation operations is identical to the process used to execute a SQL SELECT
or INSERT statement, as described in “Working with SQL statements” on page 696. Simply substitute a different SQL
statement in the SQLStatement instance’s text property:
• To change existing data in a table, use an UPDATE statement.
• To delete one or more rows of data from a table, use a DELETE statement.
For descriptions of these statements, see “SQL support in local databases” on page 1068.
Working with multiple databases
Adobe AIR 1.0 and later
Use the SQLConnection.attach() method to open a connection to an additional database on a SQLConnection
instance that already has an open database. You give the attached database a name using the name parameter in the
attach() method call. When writing statements to manipulate that database, you can then use that name in a prefix
(using the form database-name.table-name) to qualify any table names in your SQL statements, indicating to the
runtime that the table can be found in the named database.
You can execute a single SQL statement that includes tables from multiple databases that are connected to the same
SQLConnection instance. If a transaction is created on the SQLConnection instance, that transaction applies to all SQL
statements that are executed using the SQLConnection instance. This is true regardless of which attached database the
statement runs on.
Alternatively, you can also create multiple SQLConnection instances in an application, each of which is connected to
one or multiple databases. However, if you do use multiple connections to the same database keep in mind that a
database transaction isn’t shared across SQLConnection instances. Consequently, if you connect to the same database
file using multiple SQLConnection instances, you can’t rely on both connections’ data changes being applied in the
expected manner. For example, if two UPDATE or DELETE statements are run against the same database through
different SQLConnection instances, and an application error occurs after one operation takes place, the database data
could be left in an intermediate state that would not be reversible and might affect the integrity of the database (and
consequently the application).
Last updated 3/21/2011
717
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
Handling database errors
Adobe AIR 1.0 and later
In general, database error handling is like other runtime error handling. You should write code that is prepared for
errors that may occur, and respond to the errors rather than leave it up to the runtime to do so. In a general sense, the
possible database errors can be divided into three categories: connection errors, SQL syntax errors, and constraint
errors.
Connection errors
Adobe AIR 1.0 and later
Most database errors are connection errors, and they can occur during any operation. Although there are strategies for
preventing connection errors, there is rarely a simple way to gracefully recover from a connection error if the database
is a critical part of your application.
Most connection errors have to do with how the runtime interacts with the operating system, the file system, and the
database file. For example, a connection error occurs if the user doesn’t have permission to create a database file in a
particular location on the file system. The following strategies help to prevent connection errors:
Use user-specific database files Rather than using a single database file for all users who use the application on a single
computer, give each user their own database file. The file should be located in a directory that’s associated with the
user’s account. For example, it could be in the application’s storage directory, the user’s documents folder, the user’s
desktop, and so forth.
Consider different user types Test your application with different types of user accounts, on different operating
systems. Don’t assume that the user has administrator permission on the computer. Also, don’t assume that the
individual who installed the application is the user who’s running the application.
Consider various file locations If you allow a user to specify where to save a database file or select a file to open,
consider the possible file locations that the users might use. In addition, consider defining limits on where users can
store (or from where they can open) database files. For example, you might only allow users to open files that are within
their user account’s storage location.
If a connection error occurs, it most likely happens on the first attempt to create or open the database. This means that
the user is unable to do any database-related operations in the application. For certain types of errors, such as readonly or permission errors, one possible recovery technique is to copy the database file to a different location. The
application can copy the database file to a different location where the user does have permission to create and write
to files, and use that location instead.
Syntax errors
Adobe AIR 1.0 and later
A syntax error occurs when a SQL statement is incorrectly formed, and the application attempts to execute the
statement. Because local database SQL statements are created as strings, compile-time SQL syntax checking is not
possible. All SQL statements must be executed to check their syntax. Use the following strategies to prevent SQL syntax
errors:
Test all SQL statements thoroughly If possible, while developing your application test your SQL statements separately
before encoding them as statement text in the application code. In addition, use a code-testing approach such as unit
testing to create a set of tests that exercise every possible option and variation in the code.
Last updated 3/21/2011
718
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
Use statement parameters and avoid concatenating (dynamically generating) SQL Using parameters, and avoiding
dynamically built SQL statements, means that the same SQL statement text is used each time a statement is executed.
Consequently, it’s much easier to test your statements and limit the possible variation. If you must dynamically
generate a SQL statement, keep the dynamic parts of the statement to a minimum. Also, carefully validate any user
input to make sure it won’t cause syntax errors.
To recover from a syntax error, an application would need complex logic to be able to examine a SQL statement and
correct its syntax. By following the previous guidelines for preventing syntax errors, your code can identify any
potential run-time sources of SQL syntax errors (such as user input used in a statement). To recover from a syntax
error, provide guidance to the user. Indicate what to correct to make the statement execute properly.
Constraint errors
Adobe AIR 1.0 and later
Constraint errors occur when an INSERT or UPDATE statement attempts to add data to a column. The error happens if
the new data violates one of the defined constraints for the table or column. The set of possible constraints includes:
Unique constraint Indicates that across all the rows in a table, there cannot be duplicate values in one column.
Alternatively, when multiple columns are combined in a unique constraint, the combination of values in those
columns must not be duplicated. In other words, in terms of the specified unique column or columns, each row must
be distinct.
Primary key constraint In terms of the data that a constraint allows and doesn’t allow, a primary key constraint is
identical to a unique constraint.
Not null constraint Specifies that a single column cannot store a NULL value and consequently that in every row, that
column must have a value.
Check constraint Allows you to specify an arbitrary constraint on one or more tables. A common check constraint is
a rule that define that a column’s value must be within certain bounds (for example, that a numeric column’s value
must be larger than 0). Another common type of check constraint specifies relationships between column values (for
example, that a column’s value must be different from the value of another column in the same row).
Data type (column affinity) constraint The runtime enforces the data type of columns’ values, and an error occurs if
an attempt is made to store a value of the incorrect type in a column. However, in many conditions values are
converted to match the column’s declared data type. See “Working with database data types” on page 719 for more
information.
The runtime does not enforce constraints on foreign key values. In other words, foreign key values aren’t required to
match an existing primary key value.
In addition to the predefined constraint types, the runtime SQL engine supports the use of triggers. A trigger is like an
event handler. It is a predefined set of instructions that are carried out when a certain action happens. For example, a
trigger could be defined that runs when data is inserted into or deleted from a particular table. One possible use of a
trigger is to examine data changes and cause an error to occur if specified conditions aren’t met. Consequently, a
trigger can serve the same purpose as a constraint, and the strategies for preventing and recovering from constraint
errors also apply to trigger-generated errors. However, the error id for trigger-generated errors is different from the
error id for constraint errors.
The set of constraints that apply to a particular table is determined while you’re designing an application. Consciously
designing constraints makes it easier to design your application to prevent and recover from constraint errors.
However, constraint errors are difficult to systematically predict and prevent. Prediction is difficult because constraint
errors don’t appear until application data is added. Constraint errors occur with data that is added to a database after
Last updated 3/21/2011
719
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
it’s created. These errors are often a result of the relationship between new data and data that already exists in the
database. The following strategies can help you avoid many constraint errors:
Carefully plan database structure and constraints The purpose of constraints is to enforce application rules and help
protect the integrity of the database’s data. When you’re planning your application, consider how to structure your
database to support your application. As part of that process, identify rules for your data, such as whether certain
values are required, whether a value has a default, whether duplicate values are allowed, and so forth. Those rules guide
you in defining database constraints.
Explicitly specify column names An INSERT statement can be written without explicitly specifying the columns into
which values are to be inserted, but doing so is an unnecessary risk. By explicitly naming the columns into which values
are to be inserted, you can allow for automatically generated values, columns with default values, and columns that
allow NULL values. In addition, by doing so you can ensure that all NOT NULL columns have an explicit value inserted.
Use default values Whenever you specify a NOT NULL constraint for a column, if at all possible specify a default value
in the column definition. Application code can also provide default values. For example, your code can check if a String
variable is null and assign it a value before using it to set a statement parameter value.
Validate user-entered data Check user-entered data ahead of time to make sure that it obeys limits specified by
constraints, especially in the case of NOT NULL and CHECK constraints. Naturally, a UNIQUE constraint is more difficult
to check for because doing so would require executing a SELECT query to determine whether the data is unique.
Use triggers You can write a trigger that validates (and possibly replaces) inserted data or takes other actions to correct
invalid data. This validation and correction can prevent a constraint error from occurring.
In many ways constraint errors are more difficult to prevent than other types of errors. Fortunately, there are several
strategies to recover from constraint errors in ways that don’t make the application unstable or unusable:
Use conflict algorithms When you define a constraint on a column, and when you create an INSERT or UPDATE
statement, you have the option of specifying a conflict algorithm. A conflict algorithm defines the action the database
takes when a constraint violation occurs. There are several possible actions the database engine can take. The database
engine can end a single statement or a whole transaction. It can ignore the error. It can even remove old data and
replace it with the data that the code is attempting to store.
For more information see the section “ON CONFLICT (conflict algorithms)” in the “SQL support in local databases”
on page 1068.
Provide corrective feedback The set of constraints that can affect a particular SQL command can be identified ahead
of time. Consequently, you can anticipate constraint errors that a statement could cause. With that knowledge, you
can build application logic to respond to a constraint error. For example, suppose an application includes a data entry
form for entering new products. If the product name column in the database is defined with a UNIQUE constraint, the
action of inserting a new product row in the database could cause a constraint error. Consequently, the application is
designed to anticipate a constraint error. When the error happens, the application alerts the user, indicating that the
specified product name is already in use and asking the user to choose a different name. Another possible response is
to allow the user to view information about the other product with the same name.
Working with database data types
Adobe AIR 1.0 and later
When a table is created in a database, the SQL statement for creating the table defines the affinity, or data type, for each
column in the table. Although affinity declarations can be omitted, it’s a good idea to explicitly declare column affinity
in your CREATE TABLE SQL statements.
Last updated 3/21/2011
720
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
As a general rule, any object that you store in a database using an INSERT statement is returned as an instance of the
same data type when you execute a SELECT statement. However, the data type of the retrieved value can be different
depending on the affinity of the database column in which the value is stored. When a value is stored in a column, if
its data type doesn’t match the column’s affinity, the database attempts to convert the value to match the column’s
affinity. For example, if a database column is declared with NUMERIC affinity, the database attempts to convert inserted
data into a numeric storage class (INTEGER or REAL) before storing the data. The database throws an error if the data
can’t be converted. According to this rule, if the String “12345” is inserted into a NUMERIC column, the database
automatically converts it to the integer value 12345 before storing it in the database. When it’s retrieved with a SELECT
statement, the value is returned as an instance of a numeric data type (such as Number) rather than as a String instance.
The best way to avoid undesirable data type conversion is to follow two rules. First, define each column with the affinity
that matches the type of data that it is intended to store. Next, only insert values whose data type matches the defined
affinity. Following these rules provides two benefits. When you insert the data it isn’t converted unexpectedly (possibly
losing its intended meaning as a result). In addition, when you retrieve the data it is returned with its original data type.
For more information about the available column affinity types and using data types in SQL statements, see the “Data
type support” on page 1089.
Using synchronous and asynchronous database
operations
Adobe AIR 1.0 and later
Previous sections have described common database operations such as retrieving, inserting, updating, and deleting
data, as well as creating a database file and tables and other objects within a database. The examples have demonstrated
how to perform these operations both asynchronously and synchronously.
As a reminder, in asynchronous execution mode, you instruct the database engine to perform an operation. The
database engine then works in the background while the application keeps running. When the operation finishes the
database engine dispatches an event to alert you to that fact. The key benefit of asynchronous execution is that the
runtime performs the database operations in the background while the main application code continues executing.
This is especially valuable when the operation takes a notable amount of time to run.
On the other hand, in synchronous execution mode operations don’t run in the background. You tell the database
engine to perform an operation. The code pauses at that point while the database engine does its work. When the
operation completes, execution continues with the next line of your code.
A single database connection can’t execute some operations or statements synchronously and others asynchronously.
You specify whether a SQLConnection operates in synchronous or asynchronous when you open the connection to
the database. If you call SQLConnection.open() the connection operates in synchronous execution mode, and if you
call SQLConnection.openAsync() the connection operates in asynchronous execution mode. Once a
SQLConnection instance is connected to a database using open() or openAsync(), it is fixed to synchronous or
asynchronous execution.
Last updated 3/21/2011
721
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
Using synchronous database operations
Adobe AIR 1.0 and later
There is little difference in the actual code that you use to execute and respond to operations when using synchronous
execution, compared to the code for asynchronous execution mode. The key differences between the two approaches
fall into two areas. The first is executing an operation that depends on another operation (such as SELECT result rows
or the primary key of the row added by an INSERT statement). The second area of difference is in handling errors.
Writing code for synchronous operations
Adobe AIR 1.0 and later
The key difference between synchronous and asynchronous execution is that in synchronous mode you write the code
as a single series of steps. In contrast, in asynchronous code you register event listeners and often divide operations
among listener methods. When a database is connected in synchronous execution mode, you can execute a series of
database operations in succession within a single code block. The following example demonstrates this technique:
var conn:SQLConnection = new SQLConnection();
// The database file is in the application storage directory
var folder:File = File.applicationStorageDirectory;
var dbFile:File = folder.resolvePath("DBSample.db");
// open the database
conn.open(dbFile, OpenMode.UPDATE);
// start a transaction
conn.begin();
// add the customer record to the database
var insertCustomer:SQLStatement = new SQLStatement();
insertCustomer.sqlConnection = conn;
insertCustomer.text =
"INSERT INTO customers (firstName, lastName) " +
"VALUES ('Bob', 'Jones')";
insertCustomer.execute();
var customerId:Number = insertCustomer.getResult().lastInsertRowID;
// add a related phone number record for the customer
var insertPhoneNumber:SQLStatement = new SQLStatement();
insertPhoneNumber.sqlConnection = conn;
insertPhoneNumber.text =
"INSERT INTO customerPhoneNumbers (customerId, number) " +
"VALUES (:customerId, '800-555-1234')";
insertPhoneNumber.parameters[":customerId"] = customerId;
insertPhoneNumber.execute();
// commit the transaction
conn.commit();
As you can see, you call the same methods to perform database operations whether you’re using synchronous or
asynchronous execution. The key differences between the two approaches are executing an operation that depends on
another operation and handling errors.
Last updated 3/21/2011
722
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
Executing an operation that depends on another operation
Adobe AIR 1.0 and later
When you’re using synchronous execution mode, you don’t need to write code that listens for an event to determine
when an operation completes. Instead, you can assume that if an operation in one line of code completes successfully,
execution continues with the next line of code. Consequently, to perform an operation that depends on the success of
another operation, simply write the dependent code immediately following the operation on which it depends. For
instance, to code an application to begin a transaction, execute an INSERT statement, retrieve the primary key of the
inserted row, insert that primary key into another row of a different table, and finally commit the transaction, the code
can all be written as a series of statements. The following example demonstrates these operations:
var conn:SQLConnection = new SQLConnection();
// The database file is in the application storage directory
var folder:File = File.applicationStorageDirectory;
var dbFile:File = folder.resolvePath("DBSample.db");
// open the database
conn.open(dbFile, SQLMode.UPDATE);
// start a transaction
conn.begin();
// add the customer record to the database
var insertCustomer:SQLStatement = new SQLStatement();
insertCustomer.sqlConnection = conn;
insertCustomer.text =
"INSERT INTO customers (firstName, lastName) " +
"VALUES ('Bob', 'Jones')";
insertCustomer.execute();
var customerId:Number = insertCustomer.getResult().lastInsertRowID;
// add a related phone number record for the customer
var insertPhoneNumber:SQLStatement = new SQLStatement();
insertPhoneNumber.sqlConnection = conn;
insertPhoneNumber.text =
"INSERT INTO customerPhoneNumbers (customerId, number) " +
"VALUES (:customerId, '800-555-1234')";
insertPhoneNumber.parameters[":customerId"] = customerId;
insertPhoneNumber.execute();
// commit the transaction
conn.commit();
Last updated 3/21/2011
723
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
Handling errors with synchronous execution
Adobe AIR 1.0 and later
In synchronous execution mode, you don’t listen for an error event to determine that an operation has failed. Instead,
you surround any code that could trigger errors in a set of try..catch..finally code blocks. You wrap the errorthrowing code in the try block. Write the actions to perform in response to each type of error in separate catch blocks.
Place any code that you want to always execute regardless of success or failure (for example, closing a database
connection that’s no longer needed) in a finally block. The following example demonstrates using
try..catch..finally blocks for error handling. It builds on the previous example by adding error handling code:
var conn:SQLConnection = new SQLConnection();
// The database file is in the application storage directory
var folder:File = File.applicationStorageDirectory;
var dbFile:File = folder.resolvePath("DBSample.db");
// open the database
conn.open(dbFile, SQLMode.UPDATE);
// start a transaction
conn.begin();
try
{
// add the customer record to the database
var insertCustomer:SQLStatement = new SQLStatement();
insertCustomer.sqlConnection = conn;
insertCustomer.text =
"INSERT INTO customers (firstName, lastName)" +
"VALUES ('Bob', 'Jones')";
insertCustomer.execute();
var customerId:Number = insertCustomer.getResult().lastInsertRowID;
// add a related phone number record for the customer
var insertPhoneNumber:SQLStatement = new SQLStatement();
insertPhoneNumber.sqlConnection = conn;
insertPhoneNumber.text =
"INSERT INTO customerPhoneNumbers (customerId, number)" +
"VALUES (:customerId, '800-555-1234')";
insertPhoneNumber.parameters[":customerId"] = customerId;
insertPhoneNumber.execute();
// if we've gotten to this point without errors, commit the transaction
conn.commit();
}
catch (error:SQLError)
{
// rollback the transaction
conn.rollback();
}
Last updated 3/21/2011
724
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
Understanding the asynchronous execution model
Adobe AIR 1.0 and later
One common concern about using asynchronous execution mode is the assumption that you can’t start executing a
SQLStatement instance if another SQLStatement is currently executing against the same database connection. In fact,
this assumption isn’t correct. While a SQLStatement instance is executing you can’t change the text property of the
statement. However, if you use a separate SQLStatement instance for each different SQL statement that you want to
execute, you can call the execute() method of a SQLStatement while another SQLStatement instance is still
executing, without causing an error.
Internally, when you’re executing database operations using asynchronous execution mode, each database connection
(each SQLConnection instance) has its own queue or list of operations that it is instructed to perform. The runtime
executes each operation in sequence, in the order they are added to the queue. When you create a SQLStatement
instance and call its execute() method, that statement execution operation is added to the queue for the connection.
If no operation is currently executing on that SQLConnection instance, the statement begins executing in the
background. Suppose that within the same block of code you create another SQLStatement instance and also call that
method’s execute() method. That second statement execution operation is added to the queue behind the first
statement. As soon as the first statement finishes executing, the runtime moves to the next operation in the queue. The
processing of subsequent operations in the queue happens in the background, even while the result event for the first
operation is being dispatched in the main application code. The following code demonstrates this technique:
// Using asynchronous execution mode
var stmt1:SQLStatement = new SQLStatement();
stmt1.sqlConnection = conn;
// ... Set statement text and parameters, and register event listeners ...
stmt1.execute();
// At this point stmt1's execute() operation is added to conn's execution queue.
var stmt2:SQLStatement = new SQLStatement();
stmt2.sqlConnection = conn;
// ... Set statement text and parameters, and register event listeners ...
stmt2.execute();
// At this point stmt2's execute() operation is added to conn's execution queue.
// When stmt1 finishes executing, stmt2 will immediately begin executing
// in the background.
There is an important side effect of the database automatically executing subsequent queued statements. If a statement
depends on the outcome of another operation, you can’t add the statement to the queue (in other words, you can’t call
its execute() method) until the first operation completes. This is because once you’ve called the second statement’s
execute() method, you can’t change the statement’s text or parameters properties. In that case you must wait for
the event indicating that the first operation completes before starting the next operation. For example, if you want to
execute a statement in the context of a transaction, the statement execution depends on the operation of opening the
transaction. After calling the SQLConnection.begin() method to open the transaction, you need to wait for the
SQLConnection instance to dispatch its begin event. Only then can you call the SQLStatement instance’s execute()
method. In this example the simplest way to organize the application to ensure that the operations are executed
properly is to create a method that’s registered as a listener for the begin event. The code to call the
SQLStatement.execute() method is placed within that listener method.
Last updated 3/21/2011
725
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
Using encryption with SQL databases
Adobe AIR 1.5 and later
All Adobe AIR applications share the same local database engine. Consequently, any AIR application can connect to,
read from, and write to an unencrypted database file. Starting with Adobe AIR 1.5, AIR includes the capability of
creating and connecting to encrypted database files. When you use an encrypted database, in order to connect to the
database an application must provide the correct encryption key. If the incorrect encryption key (or no key) is
provided, the application is not able to connect to the database. Consequently, the application can’t read data from the
database or write to or change data in the database.
To use an encrypted database, you must create the database as an encrypted database. With an existing encrypted
database, you can open a connection to the database. You can also change the encryption key of an encrypted database.
Other than creating and connecting to encrypted databases, the techniques for working with an encrypted database
are the same as for working with an unencrypted one. In particular, executing SQL statements is the same regardless
of whether a database is encrypted or not.
Uses for an encrypted database
Adobe AIR 1.5 and later
Encryption is useful any time you want to restrict access to the information stored in a database. The database
encryption functionality of Adobe AIR can be used for several purposes. The following are some examples of cases
where you would want to use an encrypted database:
• A read-only cache of private application data downloaded from a server
• A local application store for private data that is synchronized with a server (data is sent to and loaded from the
server)
• Encrypted files used as the file format for documents created and edited by the application. The files could be
private to one user, or could be designed to be shared among all users of the application.
• Any other use of a local data store, such as the ones described in “Uses for local SQL databases” on page 681, where
the data must be kept private from people who have access to the machine or the database files.
Understanding the reason why you want to use an encrypted database helps you decide how to architect your
application. In particular, it can affect how your application creates, obtains, and stores the encryption key for the
database. For more information about these considerations, see “Considerations for using encryption with a database”
on page 729.
Other than an encrypted database, an alternative mechanism for keeping sensitive data private is the encrypted local
store. With the encrypted local store, you store a single ByteArray value using a String key. Only the AIR application
that stores the value can access it, and only on the computer on which it is stored. With the encrypted local store, it
isn’t necessary to create your own encryption key. For these reasons, the encrypted local store is most suitable for easily
storing a single value or set of values that can easily be encoded in a ByteArray. An encrypted database is most suitable
for larger data sets where structured data storage and querying are desirable. For more information about using the
encrypted local store, see “Encrypted local storage” on page 677.
Last updated 3/21/2011
726
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
Creating an encrypted database
Adobe AIR 1.5 and later
To use an encrypted database, the database file must be encrypted when it is created. Once a database is created as
unencrypted, it can’t be encrypted later. Likewise, an encrypted database can’t be unencrypted later. If needed you can
change the encryption key of an encrypted database. For details, see “Changing the encryption key of a database” on
page 728. If you have an existing database that’s not encrypted and you want to use database encryption, you can create
a new encrypted database and copy the existing table structure and data to the new database.
Creating an encrypted database is nearly identical to creating an unencrypted database, as described in “Creating a
database” on page 686. You first create a SQLConnection instance that represents the connection to the database. You
create the database by calling the SQLConnection object’s open() method or openAsync() method, specifying for the
database location a file that doesn’t exist yet. The only difference when creating an encrypted database is that you
provide a value for the encryptionKey parameter (the open() method’s fifth parameter and the openAsync()
method’s sixth parameter).
A valid encryptionKey parameter value is a ByteArray object containing exactly 16 bytes.
The following examples demonstrate creating an encrypted database. For simplicity, in these examples the encryption
key is hard-coded in the application code. However, this technique is strongly discouraged because it is not secure.
var conn:SQLConnection = new SQLConnection();
var encryptionKey:ByteArray = new ByteArray();
encryptionKey.writeUTFBytes("Some16ByteString"); // This technique is not secure!
// Create an encrypted database in asynchronous mode
conn.openAsync(dbFile, SQLMode.CREATE, null, false, 1024, encryptionKey);
// Create an encrypted database in synchronous mode
conn.open(dbFile, SQLMode.CREATE, false, 1024, encryptionKey);
For an example demonstrating a recommended way to generate an encryption key, see “Example: Generating and
using an encryption key” on page 730.
Connecting to an encrypted database
Adobe AIR 1.5 and later
Like creating an encrypted database, the procedure for opening a connection to an encrypted database is like
connecting to an unencrypted database. That procedure is described in greater detail in “Connecting to a database” on
page 693. You use the open() method to open a connection in synchronous execution mode, or the openAsync()
method to open a connection in asynchronous execution mode. The only difference is that to open an encrypted
database, you specify the correct value for the encryptionKey parameter (the open() method’s fifth parameter and
the openAsync() method’s sixth parameter).
If the encryption key that’s provided is not correct, an error occurs. For the open() method, a SQLError exception is
thrown. For the openAsync() method, the SQLConnection object dispatches a SQLErrorEvent, whose error
property contains a SQLError object. In either case, the SQLError object generated by the exception has the errorID
property value 3138. That error ID corresponds to the error message “File opened is not a database file.”
The following example demonstrates opening an encrypted database in asynchronous execution mode. For simplicity,
in this example the encryption key is hard-coded in the application code. However, this technique is strongly
discouraged because it is not secure.
Last updated 3/21/2011
727
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
import
import
import
import
import
flash.data.SQLConnection;
flash.data.SQLMode;
flash.events.SQLErrorEvent;
flash.events.SQLEvent;
flash.filesystem.File;
var conn:SQLConnection = new SQLConnection();
conn.addEventListener(SQLEvent.OPEN, openHandler);
conn.addEventListener(SQLErrorEvent.ERROR, errorHandler);
var dbFile:File = File.applicationStorageDirectory.resolvePath("DBSample.db");
var encryptionKey:ByteArray = new ByteArray();
encryptionKey.writeUTFBytes("Some16ByteString"); // This technique is not secure!
conn.openAsync(dbFile, SQLMode.UPDATE, null, false, 1024, encryptionKey);
function openHandler(event:SQLEvent):void
{
trace("the database opened successfully");
}
function errorHandler(event:SQLErrorEvent):void
{
if (event.error.errorID == 3138)
{
trace("Incorrect encryption key");
}
else
{
trace("Error message:", event.error.message);
trace("Details:", event.error.details);
}
}
The following example demonstrates opening an encrypted database in synchronous execution mode. For simplicity,
in this example the encryption key is hard-coded in the application code. However, this technique is strongly
discouraged because it is not secure.
Last updated 3/21/2011
728
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
import flash.data.SQLConnection;
import flash.data.SQLMode;
import flash.filesystem.File;
var conn:SQLConnection = new SQLConnection();
var dbFile:File = File.applicationStorageDirectory.resolvePath("DBSample.db");
var encryptionKey:ByteArray = new ByteArray();
encryptionKey.writeUTFBytes("Some16ByteString"); // This technique is not secure!
try
{
conn.open(dbFile, SQLMode.UPDATE, false, 1024, encryptionKey);
trace("the database was created successfully");
}
catch (error:SQLError)
{
if (error.errorID == 3138)
{
trace("Incorrect encryption key");
}
else
{
trace("Error message:", error.message);
trace("Details:", error.details);
}
}
For an example demonstrating a recommended way to generate an encryption key, see “Example: Generating and
using an encryption key” on page 730.
Changing the encryption key of a database
Adobe AIR 1.5 and later
When a database is encrypted, you can change the encryption key for the database at a later time. To change a
database’s encryption key, first open a connection to the database by creating a SQLConnection instance and calling
its open() or openAsync() method. Once the database is connected, call the reencrypt() method, passing the new
encryption key as an argument.
Like most database operations, the reencrypt() method’s behavior varies depending on whether the database
connection uses synchronous or asynchronous execution mode. If you use the open() method to connect to the
database, the reencrypt() operation runs synchronously. When the operation finishes, execution continues with the
next line of code:
var newKey:ByteArray = new ByteArray();
// ... generate the new key and store it in newKey
conn.reencrypt(newKey);
On the other hand, if the database connection is opened using the openAsync() method, the reencrypt() operation
is asynchronous. Calling reencrypt() begins the reencryption process. When the operation completes, the
SQLConnection object dispatches a reencrypt event. You use an event listener to determine when the reencryption
finishes:
Last updated 3/21/2011
729
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
var newKey:ByteArray = new ByteArray();
// ... generate the new key and store it in newKey
conn.addEventListener(SQLEvent.REENCRYPT, reencryptHandler);
conn.reencrypt(newKey);
function reencryptHandler(event:SQLEvent):void
{
// save the fact that the key changed
}
The reencrypt() operation runs in its own transaction. If the operation is interrupted or fails (for example, if the
application is closed before the operation finishes) the transaction is rolled back. In that case, the original encryption
key is still the encryption key for the database.
The reencrypt() method can’t be used to remove encryption from a database. Passing a null value or encryption
key that’s not a 16-byte ByteArray to the reencrypt() method results in an error.
Considerations for using encryption with a database
Adobe AIR 1.5 and later
The section “Uses for an encrypted database” on page 725 presents several cases in which you would want to use an
encrypted database. It’s obvious that the usage scenarios of different applications (including these and other scenarios)
have different privacy requirements. The way you architect the use of encryption in your application plays an
important part in controlling how private a database’s data is. For example, if you are using an encrypted database to
keep personal data private, even from other users of the same machine, then each user’s database needs its own
encryption key. For the greatest security, your application can generate the key from a user-entered password. Basing
the encryption key on a password ensures that even if another person is able to impersonate the user’s account on the
machine, the data still can’t be accessed. On the other end of the privacy spectrum, suppose you want a database file to
be readable by any user of your application but not to other applications. In that case every installed copy of the
application needs access to a shared encryption key.
You can design your application, and in particular the technique used to generate the encryption key, according to the
level of privacy that you want for your application data. The following list provides design suggestions for various levels
of data privacy:
• To make a database accessible to any user who has access to the application on any machine, use a single key that’s
available to all instances of the application. For example, the first time an application runs it can download the
shared encryption key from a server using a secure protocol such as SSL. It can then save the key in the encrypted
local store for future use. As an alternative, encrypt the data per-user on the machine, and synchronize the data with
a remote data store such as a server to make the data portable.
• To make a database accessible to a single user on any machine, generate the encryption key from a user secret (such
as a password). In particular, do not use any value that’s tied to a particular computer (such as a value stored in the
encrypted local store) to generate the key. As an alternative, encrypt the data per-user on the machine, and
synchronize the data with a remote data store such as a server to make the data portable.
• To make a database accessible only to a single individual on a single machine, generate the key from a password
and a generated salt. For an example of this technique, see “Example: Generating and using an encryption key” on
page 730.
Last updated 3/21/2011
730
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
The following are additional security considerations that are important to keep in mind when designing an application
to use an encrypted database:
• A system is only as secure as its weakest link. If you are using a user-entered password to generate an encryption
key, consider imposing minimum length and complexity restrictions on passwords. A short password that uses
only basic characters can be guessed quickly.
• The source code of an AIR application is stored on a user’s machine in plain text (for HTML content) or an easily
decompilable binary format (for SWF content). Because the source code is accessible, two points to remember are:
• Never hard-code an encryption key in your source code
• Always assume that the technique used to generate an encryption key (such as random character generator or a
particular hashing algorithm) can be easily worked out by an attacker
• AIR database encryption uses the Advanced Encryption Standard (AES) with Counter with CBC-MAC (CCM)
mode. This encryption cipher requires a user-entered key to be combined with a salt value to be secure. For an
example of this, see “Example: Generating and using an encryption key” on page 730.
• When you elect to encrypt a database, all disk files used by the database engine in conjunction with that database
are encrypted. However, the database engine holds some data temporarily in an in-memory cache to improve readand write-time performance in transactions. Any memory-resident data is unencrypted. If an attacker is able to
access the memory used by an AIR application, for example by using a debugger, the data in a database that is
currently open and unencrypted would be available.
Example: Generating and using an encryption key
Adobe AIR 1.5 and later
This example application demonstrates one technique for generating an encryption key. This application is designed
to provide the highest level of privacy and security for users’ data. One important aspect of securing private data is to
require the user to enter a password each time the application connects to the database. Consequently, as shown in this
example, an application that requires this level of privacy should never directly store the database encryption key.
The application consists of two parts: an ActionScript class that generates an encryption key (the
EncryptionKeyGenerator class), and a basic user interface that demonstrates how to use that class. For the complete
source code, see “Complete example code for generating and using an encryption key” on page 732.
Using the EncryptionKeyGenerator class to obtain a secure encryption key
Adobe AIR 1.5 and later
It isn’t necessary to understand the details of how the EncryptionKeyGenerator class works to use it in your
application. If you are interested in the details of how the class generates an encryption key for a database, see
“Understanding the EncryptionKeyGenerator class” on page 737.
Follow these steps to use the EncryptionKeyGenerator class in your application:
1 Download the EncryptionKeyGenerator class as source code or a compiled SWC. The EncryptionKeyGenerator
class is included in the open-source ActionScript 3.0 core library (as3corelib) project. You can download the
as3corelib package including source code and documentation. You can also download the SWC or source code files
from the project page.
2 Place the source code for the EncryptionKeyGenerator class (or the as3corelib SWC) in a location where your
application source code can find it.
3 In your application source code, add an import statement for the EncryptionKeyGenerator class.
Last updated 3/21/2011
731
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
import com.adobe.air.crypto.EncryptionKeyGenerator;
4 Before the point where the code creates the database or opens a connection to it, add code to create an
EncryptionKeyGenerator instance by calling the EncryptionKeyGenerator() constructor.
var keyGenerator:EncryptionKeyGenerator = new EncryptionKeyGenerator();
5 Obtain a password from the user:
var password:String = passwordInput.text;
if (!keyGenerator.validateStrongPassword(password))
{
// display an error message
return;
}
The EncryptionKeyGenerator instance uses this password as the basis for the encryption key (shown in the next
step). The EncryptionKeyGenerator instance tests the password against certain strong password validation
requirements. If the validation fails, an error occurs. As the example code shows, you can check the password ahead
of time by calling the EncryptionKeyGenerator object’s validateStrongPassword() method. That way you can
determine whether the password meets the minimum requirements for a strong password and avoid an error.
6 Generate the encryption key from the password:
var encryptionKey:ByteArray = keyGenerator.getEncryptionKey(password);
The getEncryptionKey() method generates and returns the encryption key (a 16-byte ByteArray). You can then
use the encryption key to create your new encrypted database or open your existing one.
The getEncryptionKey() method has one required parameter, which is the password obtained in step 5.
Note: To maintain the highest level of security and privacy for data, an application must require the user to enter a
password each time the application connects to the database. Do not store the user’s password or the database
encryption key directly. Doing so exposes security risks. Instead, as demonstrated in this example, an application
should use the same technique to derive the encryption key from the password both when creating the encrypted
database and when connecting to it later.
The getEncryptionKey() method also accepts a second (optional) parameter, the overrideSaltELSKey
parameter. The EncryptionKeyGenerator creates a random value (known as a salt) that is used as part of the
encryption key. In order to be able to re-create the encryption key, the salt value is stored in the Encrypted Local
Store (ELS) of your AIR application. By default, the EncryptionKeyGenerator class uses a particular String as the
ELS key. Although unlikely, it’s possible that the key can conflict with another key your application uses. Instead of
using the default key, you might want to specify your own ELS key. In that case, specify a custom key by passing it
as the second getEncryptionKey() parameter, as shown here:
var customKey:String = "My custom ELS salt key";
var encryptionKey:ByteArray = keyGenerator.getEncryptionKey(password, customKey);
7 Create or open the database
With an encryption key returned by the getEncryptionKey() method, your code can create a new encrypted
database or attempt to open the existing encrypted database. In either case you use the SQLConnection class’s
open() or openAsync() method, as described in “Creating an encrypted database” on page 726 and “Connecting
to an encrypted database” on page 726.
In this example, the application is designed to open the database in asynchronous execution mode. The code sets
up the appropriate event listeners and calls the openAsync() method, passing the encryption key as the final
argument:
Last updated 3/21/2011
732
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
conn.addEventListener(SQLEvent.OPEN, openHandler);
conn.addEventListener(SQLErrorEvent.ERROR, openError);
conn.openAsync(dbFile, SQLMode.CREATE, null, false, 1024, encryptionKey);
In the listener methods, the code removes the event listener registrations. It then displays a status message
indicating whether the database was created, opened, or whether an error occurred. The most noteworthy part of
these event handlers is in the openError() method. In that method an if statement checks if the database exists
(meaning that the code is attempting to connect to an existing database) and if the error ID matches the constant
EncryptionKeyGenerator.ENCRYPTED_DB_PASSWORD_ERROR_ID. If both of these conditions are true, it probably
means that the password the user entered is incorrect. (It could also mean that the specified file isn’t a database file
at all.) The following is the code that checks the error ID:
if (!createNewDB && event.error.errorID ==
EncryptionKeyGenerator.ENCRYPTED_DB_PASSWORD_ERROR_ID)
{
statusMsg.text = "Incorrect password!";
}
else
{
statusMsg.text = "Error creating or opening database.";
}
For the complete code for the example event listeners, see “Complete example code for generating and using an
encryption key” on page 732.
Complete example code for generating and using an encryption key
Adobe AIR 1.5 and later
The following is the complete code for the example application “Generating and using an encryption key.” The code
consists of two parts.
The example uses the EncryptionKeyGenerator class to create an encryption key from a password. The
EncryptionKeyGenerator class is included in the open-source ActionScript 3.0 core library (as3corelib) project. You
can download the as3corelib package including source code and documentation. You can also download the SWC or
source code files from the project page.
Flex example
The application MXML file contains the source code for a simple application that creates or opens a connection to an
encrypted database:
Last updated 3/21/2011
733
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
Flash Professional example
The application FLA file contains the source code for a simple application that creates or opens a connection to an
encrypted database. The FLA file has four components placed on the stage:
Last updated 3/21/2011
735
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
Instance name
Component type
Description
instructions
Label
Contains the instructions given to the user
passwordInput
TextInput
Input field where the user enters the password
openButton
Button
Button the user clicks after entering the password
statusMsg
Label
Displays status (success or failure) messages
The code for the application is defined on a keyframe on frame 1 of the main timeline. The following is the code for
the application:
import com.adobe.air.crypto.EncryptionKeyGenerator;
const dbFileName:String = "encryptedDatabase.db";
var dbFile:File;
var createNewDB:Boolean = true;
var conn:SQLConnection;
init();
// ------- Event handling ------function init():void
{
passwordInput.displayAsPassword = true;
openButton.addEventListener(MouseEvent.CLICK, openConnection);
statusMsg.setStyle("textFormat", new TextFormat(null, null, 0x990000));
conn = new SQLConnection();
dbFile = File.applicationStorageDirectory.resolvePath(dbFileName);
if (dbFile.exists)
{
createNewDB = false;
instructions.text = "Enter your database password to open the encrypted database.";
openButton.label = "Open Database";
}
else
{
instructions.text = "Enter a password to create an encrypted database. The next time
you open the application, you will need to re-enter the password to open the database again.";
openButton.label = "Create Database";
}
}
function openConnection(event:MouseEvent):void
{
var keyGenerator:EncryptionKeyGenerator = new EncryptionKeyGenerator();
var password:String = passwordInput.text;
if (password == null || password.length <= 0)
{
statusMsg.text = "Please specify a password.";
return;
Last updated 3/21/2011
736
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
}
if (!keyGenerator.validateStrongPassword(password))
{
statusMsg.text = "The password must be 8-32 characters long. It must contain at least
one lowercase letter, at least one uppercase letter, and at least one number or symbol.";
return;
}
passwordInput.text = "";
passwordInput.enabled = false;
openButton.enabled = false;
var encryptionKey:ByteArray = keyGenerator.getEncryptionKey(password);
conn.addEventListener(SQLEvent.OPEN, openHandler);
conn.addEventListener(SQLErrorEvent.ERROR, openError);
conn.openAsync(dbFile, SQLMode.CREATE, null, false, 1024, encryptionKey);
}
function openHandler(event:SQLEvent):void
{
conn.removeEventListener(SQLEvent.OPEN, openHandler);
conn.removeEventListener(SQLErrorEvent.ERROR, openError);
statusMsg.setStyle("textFormat", new TextFormat(null, null, 0x009900));
if (createNewDB)
{
statusMsg.text = "The encrypted database was created successfully.";
}
else
{
statusMsg.text = "The encrypted database was opened successfully.";
}
}
function openError(event:SQLErrorEvent):void
{
conn.removeEventListener(SQLEvent.OPEN, openHandler);
conn.removeEventListener(SQLErrorEvent.ERROR, openError);
if (!createNewDB && event.error.errorID ==
EncryptionKeyGenerator.ENCRYPTED_DB_PASSWORD_ERROR_ID)
{
statusMsg.text = "Incorrect password!";
}
else
{
statusMsg.text = "Error creating or opening database.";
}
}
Last updated 3/21/2011
737
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
Understanding the EncryptionKeyGenerator class
Adobe AIR 1.5 and later
It isn’t necessary to understand the inner workings of the EncryptionKeyGenerator class to use it to create a secure
encryption key for your application database. The process for using the class is explained in “Using the
EncryptionKeyGenerator class to obtain a secure encryption key” on page 730. However, you might find it valuable to
understand the techniques that the class uses. For example, you might want to adapt the class or incorporate some of
its techniques for situations where a different level of data privacy is desired.
The EncryptionKeyGenerator class is included in the open-source ActionScript 3.0 core library (as3corelib) project.
You can download the as3corelib package including source code and documentation.You can also view the source
code on the project site or download it to follow along with the explanations.
When code creates an EncryptionKeyGenerator instance and calls its getEncryptionKey() method, several steps are
taken to ensure that only the rightful user can access the data. The process is the same to generate an encryption key
from a user-entered password before the database is created as well as to re-create the encryption key to open the
database.
Obtain and validate a strong password
Adobe AIR 1.5 and later
When code calls the getEncryptionKey() method, it passes in a password as a parameter. The password is used as
the basis for the encryption key. By using a piece of information that only the user knows, this design ensures that only
the user who knows the password can access the data in the database. Even if an attacker accesses the user’s account
on the computer, the attacker can’t get into the database without knowing the password. For maximum security, the
application never stores the password.
An application’s code creates an EncryptionKeyGenerator instance and calls its getEncryptionKey() method,
passing a user-entered password as an argument (the variable password in this example):
var keyGenerator:EncryptionKeyGenerator = new EncryptionKeyGenerator();
var encryptionKey:ByteArray = keyGenerator.getEncryptionKey(password);
The first step the EncryptionKeyGenerator class takes when the getEncryptionKey() method is called is to check the
user-entered password to ensure that it meets the password strength requirements. The EncryptionKeyGenerator class
requires a password to be 8 - 32 characters long. The password must contain a mix of uppercase and lowercase letters
and at least one number or symbol character.
The regular expression that checks this pattern is defined as a constant named STRONG_PASSWORD_PATTERN:
private static const STRONG_PASSWORD_PATTERN:RegExp =
/(?=^.{8,32}$)((?=.*\d)|(?=.*\W+))(?![.\n])(?=.*[A-Z])(?=.*[a-z]).*$/;
The code that checks the password is in the EncryptionKeyGenerator class’s validateStrongPassword() method.
The code is as follows:
public function vaidateStrongPassword(password:String):Boolean
{
if (password == null || password.length <= 0)
{
return false;
}
return STRONG_PASSWORD_PATTERN.test(password))
}
Last updated 3/21/2011
738
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
Internally the getEncryptionKey() method calls the EncryptionKeyGenerator class’s validateStrongPassword()
method and, if the password isn’t valid, throws an exception. The validateStrongPassword() method is a public
method so that application code can check a password without calling the getEncryptionKey() method to avoid
causing an error.
Expand the password to 256 bits
Adobe AIR 1.5 and later
Later in the process, the password is required to be 256 bits long. Rather than require each user to enter a password
that’s exactly 256 bits (32 characters) long, the code creates a longer password by repeating the password characters.
The getEncryptionKey() method calls the concatenatePassword() method to perform the task of creating the
long password.
var concatenatedPassword:String = concatenatePassword(password);
The following is the code for the concatenatePassword() method:
private function concatenatePassword(pwd:String):String
{
var len:int = pwd.length;
var targetLength:int = 32;
if (len == targetLength)
{
return pwd;
}
var repetitions:int = Math.floor(targetLength / len);
var excess:int = targetLength % len;
var result:String = "";
for (var i:uint = 0; i < repetitions; i++)
{
result += pwd;
}
result += pwd.substr(0, excess);
return result;
}
If the password is less than 256 bits, the code concatenates the password with itself to make it 256 bits. If the length
doesn’t work out exactly, the last repetition is shortened to get exactly 256 bits.
Generate or retrieve a 256-bit salt value
Adobe AIR 1.5 and later
The next step is to get a 256-bit salt value that in a later step is combined with the password. A salt is a random value
that is added to or combined with a user-entered value to form a password. Using a salt with a password ensures that
even if a user chooses a real word or common term as a password, the password-plus-salt combination that the system
uses is a random value. This randomness helps guard against a dictionary attack, where an attacker uses a list of words
to attempt to guess a password. In addition, by generating the salt value and storing it in the encrypted local store, it is
tied to the user’s account on the machine on which the database file is located.
Last updated 3/21/2011
739
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
If the application is calling the getEncryptionKey() method for the first time, the code creates a random 256-bit salt
value. Otherwise, the code loads the salt value from the encrypted local store.
The salt is stored in a variable named salt. The code determines if it has already created a salt by attempting to load
the salt from the encrypted local store:
var salt:ByteArray = EncryptedLocalStore.getItem(saltKey);
if (salt == null)
{
salt = makeSalt();
EncryptedLocalStore.setItem(saltKey, salt);
}
If the code is creating a new salt value, the makeSalt() method generates a 256-bit random value. Because the value
is eventually stored in the encrypted local store, it is generated as a ByteArray object. The makeSalt() method uses
the Math.random() method to randomly generate the value. The Math.random() method can’t generate 256 bits at
one time. Instead, the code uses a loop to call Math.random() eight times. Each time, a random uint value between 0
and 4294967295 (the maximum uint value) is generated. A uint value is used for convenience, because a uint uses
exactly 32 bits. By writing eight uint values into the ByteArray, a 256-bit value is generated. The following is the code
for the makeSalt() method:
private function makeSalt():ByteArray
{
var result:ByteArray = new ByteArray;
for (var i:uint = 0; i < 8; i++)
{
result.writeUnsignedInt(Math.round(Math.random() * uint.MAX_VALUE));
}
return result;
}
When the code is saving the salt to the Encrypted Local Store (ELS) or retrieving the salt from the ELS, it needs a String
key under which the salt is saved. Without knowing the key, the salt value can’t be retrieved. In that case, the
encryption key can’t be re-created each time to reopen the database. By default, the EncryptionKeyGenerator uses a
predefined ELS key that is defined in the constant SALT_ELS_KEY. Instead of using the default key, application code
can also specify an ELS key to use in the call to the getEncryptionKey() method. Either the default or the applicationspecified salt ELS key is stored in a variable named saltKey. That variable is used in the calls to
EncryptedLocalStore.setItem() and EncryptedLocalStore.getItem(), as shown previously.
Combine the 256-bit password and salt using the XOR operator
Adobe AIR 1.5 and later
The code now has a 256-bit password and a 256-bit salt value. It next uses a bitwise XOR operation to combine the salt
and the concatenated password into a single value. In effect, this technique creates a 256-bit password consisting of
characters from the entire range of possible characters. This principle is true even though most likely the actual
password input consists of primarily alphanumeric characters. This increased randomness provides the benefit of
making the set of possible passwords large without requiring the user to enter a long complex password.
The result of the XOR operation is stored in the variable unhashedKey. The actual process of performing a bitwise
XOR on the two values happens in the xorBytes() method:
var unhashedKey:ByteArray = xorBytes(concatenatedPassword, salt);
Last updated 3/21/2011
740
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
The bitwise XOR operator (^) takes two uint values and returns a uint value. (A uint value contains 32 bits.) The input
values passed as arguments to the xorBytes() method are a String (the password) and a ByteArray (the salt).
Consequently, the code uses a loop to extract 32 bits at a time from each input to combine using the XOR operator.
private function xorBytes(passwordString:String, salt:ByteArray):ByteArray
{
var result:ByteArray = new ByteArray();
for (var i:uint = 0; i < 32; i += 4)
{
// ...
}
return result;
}
Within the loop, first 32 bits (4 bytes) are extracted from the passwordString parameter. Those bits are extracted and
converted into a uint (o1) in a two-part process. First, the charCodeAt() method gets each character’s numeric value.
Next, that value is shifted to the appropriate position in the uint using the bitwise left shift operator (<<) and the shifted
value is added to o1. For example, the first character (i) becomes the first 8 bits by using the bitwise left shift operator
(<<) to shift the bits left by 24 bits and assigning that value to o1. The second character (i + 1) becomes the second
8 bits by shifting its value left 16 bits and adding the result to o1. The third and fourth characters’ values are added the
same way.
// ...
// Extract 4 bytes from the password string and convert to a uint
var o1:uint = passwordString.charCodeAt(i) << 24;
o1 += passwordString.charCodeAt(i + 1) << 16;
o1 += passwordString.charCodeAt(i + 2) << 8;
o1 += passwordString.charCodeAt(i + 3);
// ...
The variable o1 now contains 32 bits from the passwordString parameter. Next, 32 bits are extracted from the salt
parameter by calling its readUnsignedInt() method. The 32 bits are stored in the uint variable o2.
// ...
salt.position = i;
var o2:uint = salt.readUnsignedInt();
// ...
Finally, the two 32-bit (uint) values are combined using the XOR operator and the result is written into a ByteArray
named result.
// ...
var xor:uint = o1 ^ o2;
result.writeUnsignedInt(xor);
// ...
Once the loop completes, the ByteArray containing the XOR result is returned.
Last updated 3/21/2011
741
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
// ...
}
return result;
}
Hash the key
Adobe AIR 1.5 and later
Once the concatenated password and the salt have been combined, the next step is to further secure this value by
hashing it using the SHA-256 hashing algorithm. Hashing the value makes it more difficult for an attacker to reverseengineer it.
At this point the code has a ByteArray named unhashedKey containing the concatenated password combined with the
salt. The ActionScript 3.0 core library (as3corelib) project includes a SHA256 class in the com.adobe.crypto package.
The SHA256.hashBytes() method that performs a SHA-256 hash on a ByteArray and returns a String containing the
256-bit hash result as a hexadecimal number. The EncryptionKeyGenerator class uses the SHA256 class to hash the key:
var hashedKey:String = SHA256.hashBytes(unhashedKey);
Extract the encryption key from the hash
Adobe AIR 1.5 and later
The encryption key must be a ByteArray that is exactly 16 bytes (128 bits) long. The result of the SHA-256 hashing
algorithm is always 256 bits long. Consequently, the final step is to select 128 bits from the hashed result to use as the
actual encryption key.
In the EncryptionKeyGenerator class, the code reduces the key to 128 bits by calling the generateEncryptionKey()
method. It then returns that method’s result as the result of the getEncryptionKey() method:
var encryptionKey:ByteArray = generateEncryptionKey(hashedKey);
return encryptionKey;
It isn’t necessary to use the first 128 bits as the encryption key. You could select a range of bits starting at some arbitrary
point, you could select every other bit, or use some other way of selecting bits. The important thing is that the code
selects 128 distinct bits, and that the same 128 bits are used each time.
In this case, the generateEncryptionKey() method uses the range of bits starting at the 18th byte as the encryption
key. As mentioned previously, the SHA256 class returns a String containing a 256-bit hash as a hexadecimal number.
A single block of 128 bits has too many bytes to add to a ByteArray at one time. Consequently, the code uses a for loop
to extract characters from the hexadecimal String, convert them to actual numeric values, and add them to the
ByteArray. The SHA-256 result String is 64 characters long. A range of 128 bits equals 32 characters in the String, and
each character represents 4 bits. The smallest increment of data you can add to a ByteArray is one byte (8 bits), which
is equivalent to two characters in the hash String. Consequently, the loop counts from 0 to 31 (32 characters) in
increments of 2 characters.
Within the loop, the code first determines the starting position for the current pair of characters. Since the desired
range starts at the character at index position 17 (the 18th byte), the position variable is assigned the current iterator
value (i) plus 17. The code uses the String object’s substr() method to extract the two characters at the current
position. Those characters are stored in the variable hex. Next, the code uses the parseInt() method to convert the
hex String to a decimal integer value. It stores that value in the int variable byte. Finally, the code adds the value in
byte to the result ByteArray using its writeByte() method. When the loop finishes, the result ByteArray contains
16 bytes and is ready to use as a database encryption key.
Last updated 3/21/2011
742
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
private function generateEncryptionKey(hash:String):ByteArray
{
var result:ByteArray = new ByteArray();
for (var i:uint = 0; i < 32; i += 2)
{
var position:uint = i + 17;
var hex:String = hash.substr(position, 2);
var byte:int = parseInt(hex, 16);
result.writeByte(byte);
}
return result;
}
Strategies for working with SQL databases
Adobe AIR 1.0 and later
There are various ways that an application can access and work with a local SQL database. The application design can
vary in terms of how the application code is organized, the sequence and timing of how operations are performed, and
so on. The techniques you choose can have an impact on how easy it is to develop your application. They can affect
how easy it is to modify the application in future updates. They can also affect how well the application performs from
the users’ perspective.
Distributing a pre-populated database
Adobe AIR 1.0 and later
When you use an AIR local SQL database in your application, the application expects a database with a certain
structure of tables, columns, and so forth. Some applications also expect certain data to be pre-populated in the
database file. One way to ensure that the database has the proper structure is to create the database within the
application code. When the application loads it checks for the existence of its database file in a particular location. If
the file doesn’t exist, the application executes a set of commands to create the database file, create the database
structure, and populate the tables with the initial data.
The code that creates the database and its tables is frequently complex. It is often only used once in the installed lifetime
of the application, but still adds to the size and complexity of the application. As an alternative to creating the database,
structure, and data programmatically, you can distribute a pre-populated database with your application. To distribute
a predefined database, include the database file in the application’s AIR package.
Like all files that are included in an AIR package, a bundled database file is installed in the application directory (the
directory represented by the File.applicationDirectory property). However, files in that directory are read only.
Use the file from the AIR package as a “template” database. The first time a user runs the application, copy the original
database file into the user’s “Pointing to the application storage directory” on page 639 (or another location), and use
that database within the application.
Last updated 3/21/2011
743
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
Best practices for working with local SQL databases
Adobe AIR 1.0 and later
The following list is a set of suggested techniques you can use to improve the performance, security, and ease of
maintenance of your applications when working with local SQL databases.
Pre-create database connections
Adobe AIR 1.0 and later
Even if your application doesn’t execute any statements when it first loads, instantiate a SQLConnection object and
call its open() or openAsync() method ahead of time (such as after the initial application startup) to avoid delays
when running statements. See “Connecting to a database” on page 693.
Reuse database connections
Adobe AIR 1.0 and later
If you access a certain database throughout the execution time of your application, keep a reference to the
SQLConnection instance, and reuse it throughout the application, rather than closing and reopening the connection.
See “Connecting to a database” on page 693.
Favor asynchronous execution mode
Adobe AIR 1.0 and later
When writing data-access code, it can be tempting to execute operations synchronously rather than asynchronously,
because using synchronous operations frequently requires shorter and less complex code. However, as described in
“Using synchronous and asynchronous database operations” on page 720, synchronous operations can have a
performance impact that is obvious to users and detrimental to their experience with an application. The amount of
time a single operation takes varies according to the operation and particularly the amount of data it involves. For
instance, a SQL INSERT statement that only adds a single row to the database takes less time than a SELECT statement
that retrieves thousands of rows of data. However, when you’re using synchronous execution to perform multiple
operations, the operations are usually strung together. Even if the time each single operation takes is very short, the
application is frozen until all the synchronous operations finish. As a result, the cumulative time of multiple operations
strung together may be enough to stall your application.
Use asynchronous operations as a standard approach, especially with operations that involve large numbers of rows.
There is a technique for dividing up the processing of large sets of SELECT statement results, described in “Retrieving
SELECT results in parts” on page 709. However, this technique can only be used in asynchronous execution mode.
Only use synchronous operations when you can’t achieve certain functionality using asynchronous programming,
when you’ve considered the performance trade-off that your application’s users will face, and when you’ve tested your
application so that you know how your application’s performance is affected. Using asynchronous execution can
involve more complex coding. However, remember that you only have to write the code once, but the application’s
users have to use it repeatedly, fast or slow.
In many cases, by using a separate SQLStatement instance for each SQL statement to be executed, multiple SQL
operations can be queued up at one time, which makes asynchronous code like synchronous code in terms of how the
code is written. For more information, see “Understanding the asynchronous execution model” on page 724.
Last updated 3/21/2011
744
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with local SQL databases in AIR
Use separate SQL statements and don’t change the SQLStatement’s text property
Adobe AIR 1.0 and later
For any SQL statement that is executed more than once in an application, create a separate SQLStatement instance for
each SQL statement. Use that SQLStatement instance each time that SQL command executes. For example, suppose
you are building an application that includes four different SQL operations that are performed multiple times. In that
case, create four separate SQLStatement instances and call each statement’s execute() method to run it. Avoid the
alternative of using a single SQLStatement instance for all SQL statements, redefining its text property each time
before executing the statement.
Use statement parameters
Adobe AIR 1.0 and later
Use SQLStatement parameters—never concatenate user input into statement text. Using parameters makes your
application more secure because it prevents the possibility of SQL injection attacks. It makes it possible to use objects
in queries (rather than only SQL literal values). It also makes statements run more efficiently because they can be
reused without needing to be recompiled each time they’re executed. See “Using parameters in statements” on
page 697 for more information.
Last updated 3/21/2011
745
Chapter 39: Working with byte arrays
Flash Player 9 and later, Adobe AIR 1.0 and later
The ByteArray class allows you to read from and write to a binary stream of data, which is essentially an array of bytes.
This class provides a way to access data at the most elemental level. Because computer data consists of bytes, or groups
of 8 bits, the ability to read data in bytes means that you can access data for which classes and access methods do not
exist. The ByteArray class allows you to parse any stream of data, from a bitmap to a stream of data traveling over the
network, at the byte level.
The writeObject() method allows you to write an object in serialized Action Message Format (AMF) to a ByteArray,
while the readObject() method allows you to read a serialized object from a ByteArray to a variable of the original
data type. You can serialize any object except for display objects, which are those objects that can be placed on the
display list. You can also assign serialized objects back to custom class instances if the custom class is available to the
runtime. After converting an object to AMF, you can efficiently transfer it over a network connection or save it to a file.
The sample Adobe® AIR® application described here reads a .zip file as an example of processing a byte stream,
extracting a list of the files that the .zip file contains and writing them to the desktop.
More Help topics
flash.utils.ByteArray
flash.utils.IExternalizable
Action Message Format specification
Reading and writing a ByteArray
Flash Player 9 and later, Adobe AIR 1.0 and later
The ByteArray class is part of the flash.utils package. To create a ByteArray object in ActionScript 3.0, import the
ByteArray class and invoke the constructor, as shown in the following example:
import flash.utils.ByteArray;
var stream:ByteArray = new ByteArray();
ByteArray methods
Flash Player 9 and later, Adobe AIR 1.0 and later
Any meaningful data stream is organized into a format that you can analyze to find the information that you want. A
record in a simple employee file, for example, would probably include an ID number, a name, an address, a phone
number, and so on. An MP3 audio file contains an ID3 tag that identifies the title, author, album, publishing date, and
genre of the file that’s being downloaded. The format allows you to know the order in which to expect the data on the
data stream. It allows you to read the byte stream intelligently.
Last updated 3/21/2011
746
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with byte arrays
The ByteArray class includes several methods that make it easier to read from and write to a data stream. Some of these
methods include readBytes() and writeBytes(), readInt() and writeInt(), readFloat() and writeFloat(),
readObject() and writeObject(), and readUTFBytes() and writeUTFBytes(). These methods enable you to
read data from the data stream into variables of specific data types and write from specific data types directly to the
binary data stream.
For example, the following code reads a simple array of strings and floating-point numbers and writes each element
to a ByteArray. The organization of the array allows the code to call the appropriate ByteArray methods
(writeUTFBytes() and writeFloat()) to write the data. The repeating data pattern makes it possible to read the
array with a loop.
// The following example reads a simple Array (groceries), made up of strings
// and floating-point numbers, and writes it to a ByteArray.
import flash.utils.ByteArray;
// define the grocery list Array
var groceries:Array = ["milk", 4.50, "soup", 1.79, "eggs", 3.19, "bread" , 2.35]
// define the ByteArray
var bytes:ByteArray = new ByteArray();
// for each item in the array
for (var i:int = 0; i < groceries.length; i++) {
bytes.writeUTFBytes(groceries[i++]); //write the string and position to the next item
bytes.writeFloat(groceries[i]);// write the float
trace("bytes.position is: " + bytes.position);//display the position in ByteArray
}
trace("bytes length is: " + bytes.length);// display the length
The position property
Flash Player 9 and later, Adobe AIR 1.0 and later
The position property stores the current position of the pointer that indexes the ByteArray during reading or writing.
The initial value of the position property is 0 (zero) as shown in the following code:
var bytes:ByteArray = new ByteArray();
trace("bytes.position is initially: " + bytes.position); // 0
When you read from or write to a ByteArray, the method that you use updates the position property to point to the
location immediately following the last byte that was read or written. For example, the following code writes a string
to a ByteArray and afterward the position property points to the byte immediately following the string in the
ByteArray:
var bytes:ByteArray = new ByteArray();
trace("bytes.position is initially: " + bytes.position); // 0
bytes.writeUTFBytes("Hello World!");
trace("bytes.position is now: " + bytes.position);// 12
Likewise, a read operation increments the position property by the number of bytes read.
Last updated 3/21/2011
747
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with byte arrays
var bytes:ByteArray = new ByteArray();
trace("bytes.position is initially: " + bytes.position); // 0
bytes.writeUTFBytes("Hello World!");
trace("bytes.position is now: " + bytes.position);// 12
bytes.position = 0;
trace("The first 6 bytes are: " + (bytes.readUTFBytes(6)));//Hello
trace("And the next 6 bytes are: " + (bytes.readUTFBytes(6)));// World!
Notice that you can set the position property to a specific location in the ByteArray to read or write at that offset.
The bytesAvailable and length properties
Flash Player 9 and later, Adobe AIR 1.0 and later
The length and bytesAvailable properties tell you how long a ByteArray is and how many bytes remain in it from
the current position to the end. The following example illustrates how you can use these properties. The example writes
a String of text to the ByteArray and then reads the ByteArray one byte at a time until it encounters either the character
“a” or the end (bytesAvailable <= 0).
var bytes:ByteArray = new ByteArray();
var text:String = "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Vivamus etc.";
bytes.writeUTFBytes(text); // write the text to the ByteArray
trace("The length of the ByteArray is: " + bytes.length);// 70
bytes.position = 0; // reset position
while (bytes.bytesAvailable > 0 && (bytes.readUTFBytes(1) != 'a')) {
//read to letter a or end of bytes
}
if (bytes.position < bytes.bytesAvailable) {
trace("Found the letter a; position is: " + bytes.position); // 23
trace("and the number of bytes available is: " + bytes.bytesAvailable);// 47
}
The endian property
Flash Player 9 and later, Adobe AIR 1.0 and later
Computers can differ in how they store multibyte numbers, that is, numbers that require more than 1 byte of memory
to store them. An integer, for example, can take 4 bytes, or 32 bits, of memory. Some computers store the most
significant byte of the number first, in the lowest memory address, and others store the least significant byte first. This
attribute of a computer, or of byte ordering, is referred to as being either big endian (most significant byte first) or little
endian (least significant byte first). For example, the number 0x31323334 would be stored as follows for big endian and
little endian byte ordering, where a0 represents the lowest memory address of the 4 bytes and a3 represents the highest:
Big
Endian
Big
Endian
Big
Endian
Big
Endian
a0
a1
a2
a3
31
32
33
34
Last updated 3/21/2011
748
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with byte arrays
Little
Endian
Little
Endian
Little
Endian
Little
Endian
a0
a1
a2
a3
34
33
32
31
The endian property of the ByteArray class allows you to denote this byte order for multibyte numbers that you are
processing. The acceptable values for this property are either "bigEndian" or "littleEndian" and the Endian class
defines the constants BIG_ENDIAN and LITTLE_ENDIAN for setting the endian property with these strings.
The compress() and uncompress() methods
Flash Player 9 and later, Adobe AIR 1.0 and later
The compress() method allows you to compress a ByteArray in accordance with a compression algorithm that you
specify as a parameter. The uncompress() method allows you to uncompress a compressed ByteArray in accordance
with a compression algorithm. After calling compress() and uncompress(), the length of the byte array is set to the
new length and the position property is set to the end.
The CompressionAlgorithm class (AIR) defines constants that you can use to specify the compression algorithm. The
ByteArray class supports both the deflate (AIR-only) and zlib algorithms. The deflate compression algorithm is used
in several compression formats, such as zlib, gzip, and some zip implementations. The zlib compressed data format is
described at http://www.ietf.org/rfc/rfc1950.txt and the deflate compression algorithm is described at
http://www.ietf.org/rfc/rfc1951.txt.
The following example compresses a ByteArray called bytes using the deflate algorithm:
bytes.compress(CompressionAlgorithm.DEFLATE);
The following example uncompresses a compressed ByteArray using the deflate algorithm:
bytes.uncompress(CompressionAlgorithm.DEFLATE);
Reading and writing objects
Flash Player 9 and later, Adobe AIR 1.0 and later
The readObject() and writeObject() methods read an object from and write an object to a ByteArray, encoded in
serialized Action Message Format (AMF). AMF is a proprietary message protocol created by Adobe and used by
various ActionScript 3.0 classes, including Netstream, NetConnection, NetStream, LocalConnection, and Shared
Objects.
A one-byte type marker describes the type of the encoded data that follows. AMF uses the following 13 data types:
value-type = undefined-marker | null-marker | false-marker | true-marker | integer-type |
double-type | string-type | xml-doc-type | date-type | array-type | object-type |
xml-type | byte-array-type
The encoded data follows the type marker unless the marker represents a single possible value, such as null or true or
false, in which case nothing else is encoded.
Last updated 3/21/2011
749
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with byte arrays
There are two versions of AMF: AMF0 and AMF3. AMF 0 supports sending complex objects by reference and allows
endpoints to restore object relationships. AMF 3 improves AMF 0 by sending object traits and strings by reference, in
addition to object references, and by supporting new data types that were introduced in ActionScript 3.0. The
ByteArray.objectEcoding property specifies the version of AMF that is used to encode the object data. The
flash.net.ObjectEncoding class defines constants for specifying the AMF version: ObjectEncoding.AMF0 and
ObjectEncoding.AMF3.
The following example calls writeObject() to write an XML object to a ByteArray, which it then compresses using
the Deflate algorithm and writes to the order file on the desktop. The example uses a label to display the message
“Wrote order file to desktop!” in the AIR window when it is finished.
/* The following lines, minus comment characters
, are for Flex version:
*
*
*
*
burger3.95fries1.45
// Write XML object to ByteArray
bytes.writeObject(myXML);
Last updated 3/21/2011
750
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with byte arrays
bytes.position = 0;//reset position to beginning
bytes.compress(CompressionAlgorithm.DEFLATE);// compress ByteArray
outFile("order", bytes);
myLabel.text = "Wrote order file to desktop!";
// for Flex: } // end of init()function outFile(fileName:String, data:ByteArray):void {
var outFile:File = File.desktopDirectory; // dest folder is desktop
outFile = outFile.resolvePath(fileName); // name of file to write
var outStream:FileStream = new FileStream();
// open output file stream in WRITE mode
outStream.open(outFile, FileMode.WRITE);
// write out the file
outStream.writeBytes(data, 0, data.length);
// close it
outStream.close();
}
/* Add the following lines for Flex, minus comment characters:
*
]]>
*
*
*/
The readObject() method reads an object in serialized AMF from a ByteArray and stores it in an object of the
specified type. The following example reads the order file from the desktop into a ByteArray (inBytes),
uncompresses it, and calls readObject() to store it in the XML object orderXML. The example uses a for each()
loop construct to add each node to a text area for display. The example also displays the value of the objectEncoding
property along with a header for the contents of the order file.
/* The following lines, minus comment characters, are for Flex version:
*
*
*
*
*
*
*
*/
ByteArray example: Reading a .zip file
Adobe AIR 1.0 and later
This example demonstrates how to read a simple .zip file containing several files of different types. It does so by
extracting relevant data from the metadata for each file, uncompressing each file into a ByteArray and writing the file
to the desktop.
The general structure of a .zip file is based on the specification by PKWARE Inc., which is maintained at
http://www.pkware.com/documents/casestudies/APPNOTE.TXT. First is a file header and file data for the first file in
the .zip archive, followed by a file header and file data pair for each additional file. (The structure of the file header is
described later.) Next, the .zip file optionally includes a data descriptor record (usually when the output zip file was
created in memory rather than saved to a disk). Next are several additional optional elements: archive decryption
header, archive extra data record, central directory structure, Zip64 end of central directory record, Zip64 end of
central directory locator, and end of central directory record.
The code in this example is written to only parse zip files that do not contain folders and it does not expect data
descriptor records. It ignores all information following the last file data.
The format of the file header for each file is as follows:
file header signature
4 bytes
required version
2 bytes
general-purpose bit flag
2 bytes
compression method
2 bytes (8=DEFLATE; 0=UNCOMPRESSED)
last modified file time
2 bytes
last modified file date
2 bytes
crc-32
4 bytes
Last updated 3/21/2011
752
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with byte arrays
compressed size
4 bytes
uncompressed size
4 bytes
file name length
2 bytes
extra field length
2 bytes
file name
variable
extra field
variable
Following the file header is the actual file data, which can be either compressed or uncompressed, depending on the
compression method flag. The flag is 0 (zero) if the file data is uncompressed, 8 if the data is compressed using the
DEFLATE algorithm, or another value for other compression algorithms.
The user interface for this example consists of a label and a text area (taFiles). The application writes the following
information to the text area for each file it encounters in the .zip file: the file name, the compressed size, and the
uncompressed size. The following MXML document defines the user interface for the Flex version of the application:
The beginning of the program performs the following tasks:
• Imports the required classes
import flash.filesystem.*;
import flash.utils.ByteArray;
import flash.events.Event;
• Defines the user interface for Flash
import fl.controls.*;
//requires TextArea and Label components in the Library
var taFiles = new TextArea();
var output = new Label();
taFiles.setSize(320, 150);
taFiles.move(10, 30);
output.move(10, 10);
output.width = 150;
output.text = "Contents of HelloAir.zip";
addChild(taFiles);
addChild(output);
• Defines the bytes ByteArray
var bytes:ByteArray = new ByteArray();
Last updated 3/21/2011
753
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with byte arrays
• Defines variables to store metadata from the file header
//
var
var
var
var
var
var
var
var
variables for reading fixed portion of file header
fileName:String = new String();
flNameLength:uint;
xfldLength:uint;
offset:uint;
compSize:uint;
uncompSize:uint;
compMethod:int;
signature:int;
• Defines File (zfile) and FileStream (zStream) objects to represent the .zip file, and specifies the location of the
.zip file from which the files are extracted—a file named “HelloAIR.zip” in the desktop directory.
// File variables for accessing .zip file
var zfile:File = File.desktopDirectory.resolvePath("HelloAIR.zip");
var zStream:FileStream = new FileStream();
In Flex, the program code starts in the init() method, which is called as the creationComplete handler for the root
mx:WindowedApplication tag.
// for Flex
private function init():void
{
The program begins by opening the .zip file in READ mode.
zStream.open(zfile, FileMode.READ);
It then sets the endian property of bytes to LITTLE_ENDIAN to indicate that the byte order of numeric fields has the
least significant byte first.
bytes.endian = Endian.LITTLE_ENDIAN;
Next, a while() statement begins a loop that continues until the current position in the file stream is greater than or
equal to the size of the file.
while (zStream.position < zfile.size)
{
The first statement inside the loop reads the first 30 bytes of the file stream into the ByteArray bytes. The first 30 bytes
make up the fixed-size part of the first file header.
// read fixed metadata portion of local file header
zStream.readBytes(bytes, 0, 30);
Next, the code reads an integer (signature) from the first bytes of the 30-byte header. The ZIP format definition
specifies that the signature for every file header is the hexadecimal value 0x04034b50; if the signature is different it
means that the code has moved beyond the file portion of the .zip file and there are no more files to extract. In that case
the code exits the while loop immediately rather than waiting for the end of the byte array.
bytes.position = 0;
signature = bytes.readInt();
// if no longer reading data files, quit
if (signature != 0x04034b50)
{
break;
}
Last updated 3/21/2011
754
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with byte arrays
The next part of the code reads the header byte at offset position 8 and stores the value in the variable compMethod.
This byte contains a value indicating the compression method that was used to compress this file. Several compression
methods are allowed, but in practice nearly all .zip files use the DEFLATE compression algorithm. If the current file is
compressed with DEFLATE compression, compMethod is 8; if the file is uncompressed, compMethod is 0.
bytes.position = 8;
compMethod = bytes.readByte();
// store compression method (8 == Deflate)
Following the first 30 bytes is a variable-length portion of the header that contains the file name and, possibly, an extra
field. The variable offset stores the size of this portion. The size is calculated by adding the file name length and extra
field length, read from the header at offsets 26 and 28.
offset = 0;// stores length of variable portion of metadata
bytes.position = 26; // offset to file name length
flNameLength = bytes.readShort();// store file name
offset += flNameLength; // add length of file name
bytes.position = 28;// offset to extra field length
xfldLength = bytes.readShort();
offset += xfldLength;// add length of extra field
Next the program reads the variable-length portion of the file header for the number of bytes stored in the offset
variable.
// read variable length bytes between fixed-length header and compressed file data
zStream.readBytes(bytes, 30, offset);
The program reads the file name from the variable length portion of the header and displays it in the text area along
with the compressed (zipped) and uncompressed (original) sizes of the file.
// Flash version
bytes.position = 30;
fileName = bytes.readUTFBytes(flNameLength); // read file name
taFiles.appendText(fileName + "\n"); // write file name to text area
bytes.position = 18;
compSize = bytes.readUnsignedInt(); // store size of compressed portion
taFiles.appendText("\tCompressed size is: " + compSize + '\n');
bytes.position = 22; // offset to uncompressed size
uncompSize = bytes.readUnsignedInt(); // store uncompressed size
taFiles.appendText("\tUncompressed size is: " + uncompSize + '\n');
// Flex version
bytes.position = 30;
fileName = bytes.readUTFBytes(flNameLength); // read file name
taFiles.text += fileName + "\n"; // write file name to text area
bytes.position = 18;
compSize = bytes.readUnsignedInt(); // store size of compressed portion
taFiles.text += "\tCompressed size is: " + compSize + '\n';
bytes.position = 22; // offset to uncompressed size
uncompSize = bytes.readUnsignedInt(); // store uncompressed size
taFiles.text += "\tUncompressed size is: " + uncompSize + '\n';
The example reads the rest of the file from the file stream into bytes for the length specified by the compressed size,
overwriting the file header in the first 30 bytes. The compressed size is accurate even if the file is not compressed
because in that case the compressed size is equal to the uncompressed size of the file.
// read compressed file to offset 0 of bytes; for uncompressed files
// the compressed and uncompressed size is the same
zStream.readBytes(bytes, 0, compSize);
Last updated 3/21/2011
755
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with byte arrays
Next, the example uncompresses the compressed file and calls the outfile() function to write it to the output file
stream. It passes outfile() the file name and the byte array containing the file data.
if (compMethod == 8) // if file is compressed, uncompress
{
bytes.uncompress(CompressionAlgorithm.DEFLATE);
}
outFile(fileName, bytes);
// call outFile() to write out the file
The closing braces indicate the end of the while loop, and of the init() method and the Flex application code, except
for the outFile() method. Execution loops back to the beginning of the while loop and continues processing the next
bytes in the .zip file—either extracting another file or ending processing of the .zip file if the last file has been processed.
} // end of while loop
} // for Flex version, end of init() method and application
The outfile() function opens an output file in WRITE mode on the desktop, giving it the name supplied by the
filename parameter. It then writes the file data from the data parameter to the output file stream (outStream) and
closes the file.
// Flash version
function outFile(fileName:String, data:ByteArray):void
{
var outFile:File = File.desktopDirectory; // destination folder is desktop
outFile = outFile.resolvePath(fileName); // name of file to write
var outStream:FileStream = new FileStream();
// open output file stream in WRITE mode
outStream.open(outFile, FileMode.WRITE);
// write out the file
outStream.writeBytes(data, 0, data.length);
// close it
outStream.close();
}
private function outFile(fileName:String, data:ByteArray):void
{
var outFile:File = File.desktopDirectory; // dest folder is desktop
outFile = outFile.resolvePath(fileName); // name of file to write
var outStream:FileStream = new FileStream();
// open output file stream in WRITE mode
outStream.open(outFile, FileMode.WRITE);
// write out the file
outStream.writeBytes(data, 0, data.length);
// close it
outStream.close();
}
Last updated 3/21/2011
756
Chapter 40: Basics of networking and
communication
Flash Player 9 and later, Adobe AIR 1.0 and later
When you build applications in Flash Player or AIR, you often need to access resources outside your application. For
example, you might send a request for an image to an Internet web server and get the image data in return. Or, you
might send serialized objects back and forth over a socket connection with an application server. The Flash Player and
AIR APIs provide several classes that allow your applications to participate in this exchange. These APIs support IPbased networking for protocols like UDP, TCP, HTTP, RTMP, and RTMFP.
The following classes can be used to send and receive data across a network:
Class
Loader
Supported data formats
SWF, PNG, JPEG, GIF
Protocols
HTTP, HTTPS
Description
Loads supported data types and converts the
data into a display object.
See “Loading display content dynamically” on
page 189.
Loads arbitrary formats of data. Your
application is responsible for interpreting the
data.
URLLoader
Any (text, XML, binary,
etc.)
HTTP, HTTPS
FileReference
Any
HTTP
See “Using the URLLoader class” on page 782
Upload and download files.
NetConnection
Video, audio, ActionScript
Message Format (AMF)
HTTP, HTTPS,
RTMP, RTMFP
See “Using the FileReference class” on
page 620
Connects to video, audio and remote object
streams.
Sound
Audio
HTTP
See “Working with video” on page 452.
Loads and plays supported audio formats.
See “Loading external sound files” on
page 421.
Exchanges XML messages with an XMLSocket
server.
XMLSocket
XML
TCP
Socket
Any
TCP
See “XML sockets” on page 769.
Connects to a TCP socket server.
SecureSocket (AIR)
Any
TCP with SSLv3
or TLSv1
See “Binary client sockets” on page 765.
Connects to a TCP socket server that requires
SSL or TLS security.
ServerSocket (AIR)
Any
TCP
DatagramSocket (AIR)
Any
UDP
See “Secure client sockets (AIR)” on page 765.
Acts as a server for incoming TCP socket
connections.
See “Server sockets” on page 773.
Sends and receives UDP packets.
See “UDP sockets (AIR)” on page 775
Often, when creating a web application it is helpful to store persistent information about the user’s application state.
HTML pages and applications typically use cookies for this purpose. In Flash Player, you can use the SharedObject
class for the same purpose. See “Shared objects” on page 668. (The SharedObject class can be used in AIR applications,
but there are fewer restrictions when just saving the data to a regular file.)
Last updated 3/21/2011
757
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Basics of networking and communication
When your Flash Player or AIR application needs to communicate with another Flash Player or AIR application on
the same computer, you can use the LocalConnection class. For example, two (or more) SWFs on the same web page
can communicate with each other. Likewise, a SWF running on a web page can communicate with an AIR application.
See “Communicating with other Flash Player and AIR instances” on page 797.
When you need to communicate with other, non-SWF processes on the local computer, you can use the NativeProcess
class added in AIR 2. The NativeProcess class allows your AIR application to launch and communicate with other
applications. See “Communicating with native processes in AIR” on page 804.
When you need information about the network environment of the computer on which an AIR application is running,
you can use the following classes:
• NetworkInfo—Provides information about the available network interfaces, such as the computer’s IP address. See
“Network interfaces” on page 758.
• DNSResolver—Allows you to look up DNS records. See “Domain Name System (DNS) records” on page 761.
• ServiceMonitor—Allows you to monitor the availability of a server. See “Service monitoring” on page 759.
• URLMonitor—Allows you to monitor the availability of a resource at a particular URL. See “HTTP monitoring”
on page 760.
• SocketMonitor and SecureSocketMonitor—Allows you to monitor the availability of a resource at a socket. See
“Socket monitoring” on page 761.
Important concepts and terms
The following reference list contains important terms that you will encounter when programming networking and
communications code:
External data Data that is stored in some form outside of the application, and loaded into the application when
needed. This data could be stored in a file that’s loaded directly, or stored in a database or other form that is retrieved
by calling scripts or programs running on a server.
URL-encoded variables The URL-encoded format provides a way to represent several variables (pairs of variable
names and values) in a single string of text. Individual variables are written in the format name=value. Each variable
(that is, each name-value pair) is separated by ampersand characters, like this: variable1=value1&variable2=value2. In
this way, an indefinite number of variables can be sent as a single message.
MIME type A standard code used to identify the type of a given file in Internet communication. Any given file type has
a specific code that is used to identify it. When sending a file or message, a computer (such as a web server or a user’s
Flash Player or AIR instance) will specify the type of file being sent.
HTTP Hypertext Transfer Protocol—a standard format for delivering web pages and various other types of content
that are sent over the Internet.
Request method When an application (such as an AIR application or a web browser) sends a message (called an
HTTP request) to a web server, any data being sent can be embedded in the request in one of two ways; these are the
two request methods GET and POST. On the server end, the program receiving the request will need to look in the
appropriate portion of the request to find the data, so the request method used to send data from your application
should match the request method used to read that data on the server.
Socket connection A persistent connection for communication between two computers.
Upload To send a file to another computer.
Download To retrieve a file from another computer.
Last updated 3/21/2011
758
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Basics of networking and communication
Network interfaces
Adobe AIR 2 and later
You can use the NetworkInfo object to discover the hardware and software network interfaces available to your
application. The NetworkInfo object is a singleton object, you do not need to create one. Instead, use the static class
property, networkInfo, to access the single NetworkInfo object. The NetworkInfo object also dispatches a
networkChange event when one of the available interfaces change.
Call the findInterfaces() method to get a list of NetworkInterface objects. Each NetworkInterface object in the list
describes one of the available interfaces. The NetworkInterface object provides such information as the IP address,
hardware address, maximum transmission unit, and whether the interface is active.
The following code example traces the NetworkInterface properties of each interface on the client computer:
package {
import flash.display.Sprite;
import flash.net.InterfaceAddress;
import flash.net.NetworkInfo;
import flash.net.NetworkInterface;
public class NetworkInformationExample extends Sprite
{
public function NetworkInformationExample()
{
var networkInfo:NetworkInfo = NetworkInfo.networkInfo;
var interfaces:Vector. = networkInfo.findInterfaces();
if( interfaces != null )
{
trace( "Interface count: " + interfaces.length );
for each ( var interfaceObj:NetworkInterface in interfaces )
{
trace( "\nname: " + interfaceObj.name );
trace( "display name: " + interfaceObj.displayName );
trace( "mtu: " + interfaceObj.mtu );
trace( "active?: " + interfaceObj.active );
trace( "parent interface: " + interfaceObj.parent );
trace( "hardware address: " + interfaceObj.hardwareAddress );
if( interfaceObj.subInterfaces != null )
{
trace( "# subinterfaces: " + interfaceObj.subInterfaces.length );
}
trace("# addresses: " + interfaceObj.addresses.length );
for each ( var address:InterfaceAddress in interfaceObj.addresses )
{
trace( " type: "
+ address.ipVersion );
trace( " address: " + address.address );
trace( " broadcast: " + address.broadcast );
trace( " prefix length: " + address.prefixLength );
}
}
}
}
}
}
Last updated 3/21/2011
759
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Basics of networking and communication
For more information, see:
• NetworkInfo
• NetworkInterface
• InterfaceAddress
Network connectivity changes
Adobe AIR 1.0 and later
Your AIR application can run in environments with uncertain and changing network connectivity. To help an
application manage connections to online resources, Adobe AIR sends a network change event whenever a network
connection becomes available or unavailable. Both the NetworkInfo object and the application’s NativeApplication
object dispatch the networkChange event. To react to this event, add a listener:
NetworkInfo.networkInfo.addEventListener(Event.NETWORK_CHANGE, onNetworkChange);
And define an event handler function:
function onNetworkChange(event:Event)
{
//Check resource availability
}
The networkChange event does not indicate a change in all network activity, only that an individual network
connection has changed. AIR does not attempt to interpret the meaning of the network change. A networked
computer can have many real and virtual connections, so losing a connection does not necessarily mean losing a
resource. On the other hand, new connections do not guarantee improved resource availability, either. Sometimes a
new connection can even block access to resources previously available (for example, when connecting to a VPN).
In general, the only way for an application to determine whether it can connect to a remote resource is to try it. The
service monitoring framework provides an event-based means of responding to changes in network connectivity to a
specified host.
Note: The service monitoring framework detects whether a server responds acceptably to a request. A successful check does
not guarantee full connectivity. Scalable web services often use caching and load-balancing appliances to redirect traffic
to a cluster of web servers. In this situation, service providers only provide a partial diagnosis of network connectivity.
Service monitoring
Adobe AIR 1.0 and later
The service monitor framework, separate from the AIR framework, resides in the file aircore.swc. To use the
framework, the aircore.swc file must be included in your build process.
Adobe® Flash® Builder includes this library automatically.
Last updated 3/21/2011
760
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Basics of networking and communication
The ServiceMonitor class implements the framework for monitoring network services and provides a base
functionality for service monitors. By default, an instance of the ServiceMonitor class dispatches events regarding
network connectivity. The ServiceMonitor object dispatches these events when the instance is created and whenever
the runtime detects a network change. Additionally, you can set the pollInterval property of a ServiceMonitor
instance to check connectivity at a specified interval in milliseconds, regardless of general network connectivity events.
A ServiceMonitor object does not check network connectivity until the start() method is called.
The URLMonitor class, a subclass of the ServiceMonitor class, detects changes in HTTP connectivity for a specified
URLRequest.
The SocketMonitor class, also a subclass of the ServiceMonitor class, detects changes in connectivity to a specified host
at a specified port.
Note: Prior to AIR 2, the service monitor framework was published in the servicemonitor.swc library. This library is now
deprecated. Use the aircore.swc library instead.
Flash CS4 and CS5 Professional
To use these classes in Adobe® Flash® CS4 or CS5 Professional:
1 Select the File > Publish Settings command.
2 Click the Settings button for ActionScript 3.0. Select Library Path.
3 Click the Browse to SWC button and browse to the AIK folder in your Flash Professional installation folder.
4 Within this folder, find the /frameworks/libs/air/aircore.swc (for AIR 2) or
/frameworks/libs/air/servicemonitor.swc (for AIR 1.5).
5 Click the OK button.
6 Add the following import statement to your ActionScript 3.0 code:
import air.net.*;
Flash CS3 Professional
To use these classes in Adobe® Flash® CS3 Professional, drag the ServiceMonitorShim component from the
Components panel to the Library. Then, add the following importstatement to your ActionScript 3.0 code:
import air.net.*;
HTTP monitoring
Adobe AIR 1.0 and later
The URLMonitor class determines if HTTP requests can be made to a specified address at port 80 (the typical port for
HTTP communication). The following code uses an instance of the URLMonitor class to detect connectivity changes
to the Adobe website:
Last updated 3/21/2011
761
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Basics of networking and communication
import air.net.URLMonitor;
import flash.net.URLRequest;
import flash.events.StatusEvent;
var monitor:URLMonitor;
monitor = new URLMonitor(new URLRequest('http://www.example.com'));
monitor.addEventListener(StatusEvent.STATUS, announceStatus);
monitor.start();
function announceStatus(e:StatusEvent):void {
trace("Status change. Current status: " + monitor.available);
}
Socket monitoring
Adobe AIR 1.0 and later
AIR applications can also use socket connections for push-model connectivity. Firewalls and network routers typically
restrict network communication on unauthorized ports for security reasons. For this reason, developers must consider
that users do not always have the capability to make socket connections.
The following code uses an instance of the SocketMonitor class to detect connectivity changes to a socket connection.
The port monitored is 6667, a common port for IRC:
import air.net.ServiceMonitor;
import flash.events.StatusEvent;
socketMonitor = new SocketMonitor('www.example.com',6667);
socketMonitor.addEventListener(StatusEvent.STATUS, socketStatusChange);
socketMonitor.start();
function announceStatus(e:StatusEvent):void {
trace("Status change. Current status: " + socketMonitor.available);
}
If the socket server requires a secure connection, you can use the SecureSocketMonitor class instead of SocketMonitor.
Domain Name System (DNS) records
Adobe AIR 2.0 and later
You can look up DNS resource records using the DNSResolver class. DNS resource records provide information like
the IP address of a domain name and the domain name of an IP address. You can look up the following types of DNS
resource records:
• ARecord—IPv4 address for a host.
• AAAARecord—IPv6 address for a host.
• MXRecord—mail exchange record for a host.
• PTRRecord—host name for an IP address.
• SRVRecord—service record for a service.
To look up a record, you pass a query string and the class object representing the record type to the lookup() method
of the DNSResolver object. The query string to use depends on the record type:
Last updated 3/21/2011
762
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Basics of networking and communication
Record class
Query string
Example query string
ARecord
host name
“example.com”
AAAARecord
host name
“example.com”
MXRecord
host name
“example.com”
PTRRecord
IP address
“208.77.188.166”
SRVRecord
Service identifier: _service._protocol.host
“_sip._tcp.example.com”
The following code example looks up the IP address of the host “example.com”.
package
{
import
import
import
import
import
flash.display.Sprite;
flash.events.DNSResolverEvent;
flash.events.ErrorEvent;
flash.net.dns.ARecord;
flash.net.dns.DNSResolver;
public class DNSResolverExample extends Sprite
{
public function DNSResolverExample()
{
var resolver:DNSResolver = new DNSResolver();
resolver.addEventListener( DNSResolverEvent.LOOKUP, lookupComplete );
resolver.addEventListener( ErrorEvent.ERROR, lookupError );
resolver.lookup( "example.com.", ARecord );
}
private function lookupComplete( event:DNSResolverEvent ):void
{
trace( "Query string: " + event.host );
trace( "Record count: " + event.resourceRecords.length );
for each( var record:* in event.resourceRecords )
{
if( record is ARecord ) trace( record.address );
}
}
private function lookupError( error:ErrorEvent ):void
{
trace("Error: " + error.text );
}
}
}
For more information, see:
• DNSResolver
• DNSResolverEvent
• ARecord
Last updated 3/21/2011
763
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Basics of networking and communication
• AAAARecord
• MXRecord
• PTRRecord
• SRVRecord
Last updated 3/21/2011
764
Chapter 41: Sockets
Flash Player 9 and later, Adobe AIR 1.0 and later
A socket is a type of network connection established between two computer processes. Typically, the processes are
running on two different computers attached to the same Internet Protocol (IP) network. However, the connected
processes can be running on the same computer using the special “local host” IP address.
Adobe Flash Player supports client-side Transport Control Protocol (TCP) sockets. A Flash Player application can
connect to another process acting as a socket server, but cannot accept incoming connection requests from other
processes. In other words, a Flash Player application can connect to a TCP server, but cannot serve as one.
The Flash Player API also includes the XMLSocket class. The XMLSocket class uses a Flash Player-specific protocol
that allows you to exchange XML messages with a server that understands that protocol. The XMLSocket class was
introduced in ActionScript 1 and is still supported to provide backward compatibility. In general, the Socket class
should be used for new applications unless you are connecting to a server specifically created to communicate with
Flash XMLSockets.
Adobe AIR adds several additional classes for socket-based network programming. AIR applications can act as TCP
socket servers with the ServerSocket class and can connect to socket servers requiring SSL or TLS security with the
SecureSocket class. AIR applications can also send and receive Universal Datagram Protocol (UDP) messages with the
DatagramSocket class.
More Help topics
flash.net package
“Connecting to sockets” on page 1033
TCP sockets
Flash Player 9 and later, Adobe AIR 1.0 and later
The Transmission Control Protocol (TCP) provides a way to exchange messages over a persistent network connection.
TCP guarantees that any messages sent arrive in the correct order (barring major network problems). TCP
connections require a “client” and a “server.” Flash Player can create client sockets. Adobe AIR can, additionally, create
server sockets.
The following ActionScript APIs provide TCP connections:
• Socket — allows a client application to connect to a server. The Socket class cannot listen for incoming connections.
• SecureSocket (AIR) — allows a client application to connect to a trusted server and engage in encrypted
communications.
• ServerSocket (AIR) — allows an application to listen for incoming connections and act as a server.
• XMLSocket — allows a client application to connect to an XMLSocket server.
Last updated 3/21/2011
765
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Sockets
Binary client sockets
Flash Player 9 and later, Adobe AIR 1.0 and later
A binary socket connection is similar to an XML socket except that the client and server are not limited to exchanging
XML messages. Instead, the connection can transfer data as binary information. Thus, you can connect to a wider
range of services, including mail servers (POP3, SMTP, and IMAP), and news servers (NNTP).
Socket class
Flash Player 9 and later, Adobe AIR 1.0 and later
The Socket class enables you to make socket connections and to read and write raw binary data. The Socket class is
useful for interoperating with servers that use binary protocols. By using binary socket connections, you can write code
that interacts with several different Internet protocols, such as POP3, SMTP, IMAP, and NNTP. This interaction, in
turn, enables your applications to connect to mail and news servers.
Flash Player can interface with a server by using the binary protocol of that server directly. Some servers use the bigendian byte order, and some use the little-endian byte order. Most servers on the Internet use the big-endian byte order
because “network byte order” is big-endian. The little-endian byte order is popular because the Intel® x86 architecture
uses it. You should use the endian byte order that matches the byte order of the server that is sending or receiving data.
All operations that are performed by the IDataInput and IDataOutput interfaces, and the classes that implement those
interfaces (ByteArray, Socket, and URLStream), are encoded by default in big-endian format; that is, with the most
significant byte first. This default byte order was chosen to match Java and the official network byte order. To change
whether big-endian or little-endian byte order is used, you can set the endian property to Endian.BIG_ENDIAN or
Endian.LITTLE_ENDIAN.
The Socket class inherits all the methods defined by the IDataInput and IDataOutput interfaces (located in the
flash.utils package). Those methods must be used to write to and read from the Socket.
For more information, see:
• Socket
• IDataInput
• IDataOutput
• socketData event
Secure client sockets (AIR)
Adobe AIR 2 and later
You can use the SecureSocket class to connect to socket servers that use Secure Sockets Layer version 4 (SSLv4) or
Transport Layer Security version 1 (TLSv1). A secure socket provides three benefits: server authentication, data
integrity, and message confidentiality. The runtime authenticates a server using the server certificate and its
relationship to the root or intermediate certificate authority certificates in the user’s trust store. The runtime relies on
the cryptography algorithms used by the SSL and TLS protocol implementations to provide data integrity and message
confidentiality.
When you connect to a server using the SecureSocket object, the runtime validates the server certificate using the
certificate trust store. On Windows and Mac, the operating system provides the trust store. On Linux, the runtime
provides its own trust store.
Last updated 3/21/2011
766
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Sockets
If the server certificate is not valid or not trusted, the runtime dispatches an ioError event. You can check the
serverCertificateStatus property of the SecureSocket object to determine why validation failed. No provision is
provided for communicating with a server that does not have a valid and trusted certificate.
The CertificateStatus class defines string constants that represent the possible validation results:
• Expired—the certificate expiration date has passed.
• Invalid—there are a number of reasons that a certificate can be invalid. For example, the certificate could have been
altered, corrupted, or it could be the wrong type of certificate.
• Invalid chain—one or more of the certificates in the server’s chain of certificates are invalid.
• Principal mismatch—the host name of the server and the certificate common name do not match. In other words,
the server is using the wrong certificate.
• Revoked—the issuing certificate authority has revoked the certificate.
• Trusted—the certificate is valid and trusted. A SecureSocket object can only connect to a server that uses a valid,
trusted certificate.
• Unknown—the SecureSocket object has not validated the certificate yet. The serverCertificateStatus
property has this status value before you call connect() and before either a connect or an ioError event is
dispatched.
• Untrusted signers—the certificate does not “chain” to a trusted root certificate in the trust store of the client
computer.
Communicating with a SecureSocket object requires a server that uses a secure protocol and has a valid, trusted
certificate. In other respects, using a SecureSocket object is the same as using a Socket object.
The SecureSocket object is not supported on all platforms. Use the SecureSocket class isSupported property to test
whether the runtime supports use of the SecureSocket object on the current client computer.
For more information, see:
• SecureSocket
• CertificateStatus
• IDataInput
• IDataOutput
• socketData event
TCP socket example: Building a Telnet client
Flash Player 9 and later, Adobe AIR 1.0 and later
The Telnet example demonstrates techniques for connecting with a remote server and transmitting data using the
Socket class. The example demonstrates the following techniques:
• Creating a custom telnet client using the Socket class
• Sending text to the remote server using a ByteArray object
• Handling received data from a remote server
To get the application files for this sample, see www.adobe.com/go/learn_programmingAS3samples_flash. The Telnet
application files can be found in the Samples/Telnet folder. The application consists of the following files:
Last updated 3/21/2011
767
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Sockets
File
Description
TelnetSocket.fla
The main application file consisting of the user interface for Flex (MXML) or Flash
(FLA).
or
TelnetSocket.mxml
TelnetSocket.as
Document class providing the user interface logic (Flash only).
com/example/programmingas3/Telnet/Telnet.as
Provides the Telnet client functionality for the application, such as connecting to a
remote server, and sending, receiving, and displaying data.
Telnet socket application overview
Flash Player 9 and later, Adobe AIR 1.0 and later
The main TelnetSocket.mxml file is responsible for creating the user interface (UI) for the entire application.
In addition to the UI, this file also defines two methods, login() and sendCommand(), to connect the user to the
specified server.
The following code lists the ActionScript in the main application file:
import com.example.programmingas3.socket.Telnet;
private var telnetClient:Telnet;
private function connect():void
{
telnetClient = new Telnet(serverName.text, int(portNumber.text), output);
console.title = "Connecting to " + serverName.text + ":" + portNumber.text;
console.enabled = true;
}
private function sendCommand():void
{
var ba:ByteArray = new ByteArray();
ba.writeMultiByte(command.text + "\n", "UTF-8");
telnetClient.writeBytesToSocket(ba);
command.text = "";
}
The first line of code imports the Telnet class from the custom com.example.programmingas.socket package. The
second line of code declares an instance of the Telnet class, telnetClient, that is initialized later by the connect()
method. Next, the connect() method is declared and initializes the telnetClient variable declared earlier. This
method passes the user-specified telnet server name, telnet server port, and a reference to a TextArea component on
the display list, which is used to display the text responses from the socket server. The final two lines of the connect()
method set the title property for the Panel and enable the Panel component, which allows the user to send data to
the remote server. The final method in the main application file, sendCommand(), is used to send the user's commands
to the remote server as a ByteArray object.
Telnet class overview
Flash Player 9 and later, Adobe AIR 1.0 and later
The Telnet class is responsible for connecting to the remote Telnet server and sending/receiving data.
The Telnet class declares the following private variables:
Last updated 3/21/2011
768
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Sockets
private
private
private
private
private
var
var
var
var
var
serverURL:String;
portNumber:int;
socket:Socket;
ta:TextArea;
state:int = 0;
The first variable, serverURL, contains the user-specified server address to connect to.
The second variable, portNumber, is the port number that the Telnet server is currently running on. By default, the
Telnet service runs on port 23.
The third variable, socket, is a Socket instance that attempts to connect to the server defined by the serverURL and
portNumber variables.
The fourth variable, ta, is a reference to a TextArea component instance on the Stage. This component is used to
display responses from the remote Telnet server, or any possible error messages.
The final variable, state, is a numeric value that is used to determine which options your Telnet client supports.
As you saw before, the Telnet class's constructor function is called by the connect() method in the main application file.
The Telnet constructor takes three parameters: server, port, and output. The server and port parameters specify
the server name and port number where the Telnet server is running. The final parameter, output, is a reference to a
TextArea component instance on the Stage where server output is displayed to users.
public function Telnet(server:String, port:int, output:TextArea)
{
serverURL = server;
portNumber = port;
ta = output;
socket = new Socket();
socket.addEventListener(Event.CONNECT, connectHandler);
socket.addEventListener(Event.CLOSE, closeHandler);
socket.addEventListener(ErrorEvent.ERROR, errorHandler);
socket.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
socket.addEventListener(ProgressEvent.SOCKET_DATA, dataHandler);
Security.loadPolicyFile("http://" + serverURL + "/crossdomain.xml");
try
{
msg("Trying to connect to " + serverURL + ":" + portNumber + "\n");
socket.connect(serverURL, portNumber);
}
catch (error:Error)
{
msg(error.message + "\n");
socket.close();
}
}
Writing data to a socket
Flash Player 9 and later, Adobe AIR 1.0 and later
To write data to a socket connection, you call any of the write methods in the Socket class. These write methods include
writeBoolean(), writeByte(), writeBytes(), writeDouble(), and others. Then, flush the data in the output
buffer using the flush() method. In the Telnet server, data is written to the socket connection using the
writeBytes() method which takes the byte array as a parameter and sends it to the output buffer. The
writeBytesToSocket() method is as follows:
Last updated 3/21/2011
769
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Sockets
public function writeBytesToSocket(ba:ByteArray):void
{
socket.writeBytes(ba);
socket.flush();
}
This method gets called by the sendCommand() method of the main application file.
Displaying messages from the socket server
Flash Player 9 and later, Adobe AIR 1.0 and later
Whenever a message is received from the socket server, or an event occurs, the custom msg() method is called. This
method appends a string to the TextArea on the Stage and calls a custom setScroll() method, which causes the
TextArea component to scroll to the bottom. The msg() method is as follows:
private function msg(value:String):void
{
ta.text += value;
setScroll();
}
If you didn’t automatically scroll the contents of the TextArea component, users would need to manually drag the
scroll bars on the text area to see the latest response from the server.
Scrolling a TextArea component
Flash Player 9 and later, Adobe AIR 1.0 and later
The setScroll() method contains a single line of ActionScript that scrolls the TextArea component’s contents
vertically so the user can see the last line of the returned text. The following snippet shows the setScroll() method:
public function setScroll():void
{
ta.verticalScrollPosition = ta.maxVerticalScrollPosition;
}
This method sets the verticalScrollPosition property, which is the line number of the top row of characters that
is currently displayed, and sets it to the value of the maxVerticalScrollPosition property.
XML sockets
Flash Player 9 and later, Adobe AIR 1.0 and later
An XML socket lets you create a connection to a remote server that remains open until explicitly closed. You can
exchange string data, such as XML, between the server and client. A benefit of using an XML socket server is that the
client does not need to explicitly request data. The server can send data without waiting for a request and can send data
to every connected client connected.
In Flash Player, and in Adobe AIR content outside the application sandbox, XML socket connections require the
presence of a socket policy file on the target server. For more information, see “Website controls (policy files)” on
page 1017 and “Connecting to sockets” on page 1033.
The XMLSocket class cannot tunnel through firewalls automatically because, unlike the Real-Time Messaging
Protocol (RTMP), XMLSocket has no HTTP tunneling capability. If you need to use HTTP tunneling, consider using
Flash Remoting or Flash Media Server (which supports RTMP) instead.
Last updated 3/21/2011
770
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Sockets
The following restrictions apply to how and where content in Flash Player or in an AIR application outside of the
application security sandbox can use an XMLSocket object to connect to the server:
• For content outside of the application security sandbox, the XMLSocket.connect() method can connect only to
TCP port numbers greater than or equal to 1024. One consequence of this restriction is that the server daemons
that communicate with the XMLSocket object must also be assigned to port numbers greater than or equal to 1024.
Port numbers below 1024 are often used by system services such as FTP (21), Telnet (23), SMTP (25), HTTP (80),
and POP3 (110), so XMLSocket objects are barred from these ports for security reasons. The port number
restriction limits the possibility that these resources will be inappropriately accessed and abused.
• For content outside of the application security sandbox, the XMLSocket.connect() method can connect only to
computers in the same domain where the content resides. (This restriction is identical to the security rules for
URLLoader.load().) To connect to a server daemon running in a domain other than the one where the content
resides, you can create a cross-domain policy file on the server that allows access from specific domains. For details
on cross-domain policy files, see “AIR security” on page 1041.
Note: Setting up a server to communicate with the XMLSocket object can be challenging. If your application does not
require real-time interactivity, use the URLLoader class instead of the XMLSocket class.
You can use the XMLSocket.connect() and XMLSocket.send() methods of the XMLSocket class to transfer XML to
and from a server over a socket connection. The XMLSocket.connect() method establishes a socket connection with
a web server port. The XMLSocket.send() method passes an XML object to the server specified in the socket
connection.
When you invoke the XMLSocket.connect() method, the application opens a TCP/IP connection to the server and
keeps that connection open until one of the following occurs:
• The XMLSocket.close() method of the XMLSocket class is called.
• No more references to the XMLSocket object exist.
• Flash Player exits.
• The connection is broken (for example, the modem disconnects).
Connecting to a server with the XMLSocket class
Flash Player 9 and later, Adobe AIR 1.0 and later
To create a socket connection, you must create a server-side application to wait for the socket connection request and
send a response to the Flash Player or AIR application. This type of server-side application can be written in AIR or in
another programming language such as Java, Python, or Perl. To use the XMLSocket class, the server computer must
run a daemon that understands the simple protocol used by the XMLSocket class:
• XML messages are sent over a full-duplex TCP/IP stream socket connection.
• Each XML message is a complete XML document, terminated by a zero (0) byte.
• An unlimited number of XML messages can be sent and received over a single XMLSocket connection.
Creating and connecting to a Java XML socket server
Flash Player 9 and later, Adobe AIR 1.0 and later
The following code demonstrates a simple XMLSocket server written in Java that accepts incoming connections and
displays the received messages in the command prompt window. By default, a new server is created on port 8080 of
your local machine, although you can specify a different port number when starting your server from the command
line.
Last updated 3/21/2011
771
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Sockets
Create a new text document and add the following code:
import java.io.*;
import java.net.*;
class SimpleServer
{
private static SimpleServer server;
ServerSocket socket;
Socket incoming;
BufferedReader readerIn;
PrintStream printOut;
public static void main(String[] args)
{
int port = 8080;
try
{
port = Integer.parseInt(args[0]);
}
catch (ArrayIndexOutOfBoundsException e)
{
// Catch exception and keep going.
}
server = new SimpleServer(port);
}
private SimpleServer(int port)
{
System.out.println(">> Starting SimpleServer");
try
{
socket = new ServerSocket(port);
incoming = socket.accept();
readerIn = new BufferedReader(new InputStreamReader(incoming.getInputStream()));
printOut = new PrintStream(incoming.getOutputStream());
printOut.println("Enter EXIT to exit.\r");
out("Enter EXIT to exit.\r");
boolean done = false;
while (!done)
{
String str = readerIn.readLine();
if (str == null)
{
done = true;
}
else
{
out("Echo: " + str + "\r");
Last updated 3/21/2011
772
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Sockets
if(str.trim().equals("EXIT"))
{
done = true;
}
}
incoming.close();
}
}
catch (Exception e)
{
System.out.println(e);
}
}
private void out(String str)
{
printOut.println(str);
System.out.println(str);
}
}
Save the document to your hard disk as SimpleServer.java and compile it using a Java compiler, which creates a Java
class file named SimpleServer.class.
You can start the XMLSocket server by opening a command prompt and typing java SimpleServer. The
SimpleServer.class file can be located anywhere on your local computer or network; it doesn’t need to be placed in the
root directory of your web server.
If you’re unable to start the server because the files are not located within the Java classpath, try starting the server
with java -classpath . SimpleServer.
To connect to the XMLSocket from your application, you need to create a new instance of the XMLSocket class, and
call the XMLSocket.connect() method while passing a host name and port number, as follows:
var xmlsock:XMLSocket = new XMLSocket();
xmlsock.connect("127.0.0.1", 8080);
Whenever you receive data from the server, the data event (flash.events.DataEvent.DATA) is dispatched:
xmlsock.addEventListener(DataEvent.DATA, onData);
private function onData(event:DataEvent):void
{
trace("[" + event.type + "] " + event.data);
}
To send data to the XMLSocket server, you use the XMLSocket.send() method and pass an XML object or string.
Flash Player converts the supplied parameter to a String object and sends the content to the XMLSocket server
followed by a zero (0) byte:
xmlsock.send(xmlFormattedData);
The XMLSocket.send() method does not return a value that indicates whether the data was successfully transmitted.
If an error occurred while trying to send data, an IOError error is thrown.
Each message you send to the XML socket server must be terminated by a newline (\n) character.
For more information, see XMLSocket.
Last updated 3/21/2011
773
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Sockets
Server sockets
Adobe AIR 2 and later
Use the ServerSocket class to allow other processes to connect to your application using a Transport Control Protocol
(TCP) socket. The connecting process can be running on the local computer or on another network-connected
computer. When a ServerSocket object receives a connection request, it dispatches a connect event. The
ServerSocketConnectEvent object dispatched with the event contains a Socket object. You can use this Socket object
for subsequent communication with the other process.
To listen for incoming socket connections:
1 Create a ServerSocket object and bind it to a local port
2 Add event listeners for the connect event
3 Call the listen() method
4 Respond to the connect event, which provides a Socket object for each incoming connection
The ServerSocket object continues to listen for new connections until you call the close() method.
The following code example illustrates how to create a socket server application. The example listens for incoming
connections on port 8087. When a connection is received, the example sends a message (the string “Connected.”) to
the client socket. Thereafter, the server echoes any messages received back to the client.
package
{
import
import
import
import
import
import
import
flash.display.Sprite;
flash.events.Event;
flash.events.IOErrorEvent;
flash.events.ProgressEvent;
flash.events.ServerSocketConnectEvent;
flash.net.ServerSocket;
flash.net.Socket;
public class ServerSocketExample extends Sprite
{
private var serverSocket:ServerSocket;
private var clientSockets:Array = new Array();
public function ServerSocketExample()
{
try
{
// Create the server socket
serverSocket = new ServerSocket();
// Add the event listener
serverSocket.addEventListener( Event.CONNECT, connectHandler );
serverSocket.addEventListener( Event.CLOSE, onClose );
// Bind to local port 8087
serverSocket.bind( 8087, "127.0.0.1" );
// Listen for connections
serverSocket.listen();
trace( "Listening on " + serverSocket.localPort );
Last updated 3/21/2011
774
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Sockets
}
catch(e:SecurityError)
{
trace(e);
}
}
public function connectHandler(event:ServerSocketConnectEvent):void
{
//The socket is provided by the event object
var socket:Socket = event.socket as Socket;
clientSockets.push( socket );
socket.addEventListener( ProgressEvent.SOCKET_DATA, socketDataHandler);
socket.addEventListener( Event.CLOSE, onClientClose );
socket.addEventListener( IOErrorEvent.IO_ERROR, onIOError );
//Send a connect message
socket.writeUTFBytes("Connected.");
socket.flush();
trace( "Sending connect message" );
}
public function socketDataHandler(event:ProgressEvent):void
{
var socket:Socket = event.target as Socket
//Read the message from the socket
var message:String = socket.readUTFBytes( socket.bytesAvailable );
trace( "Received: " + message);
// Echo the received message back to the sender
message = "Echo -- " + message;
socket.writeUTFBytes( message );
socket.flush();
trace( "Sending: " + message );
}
private function onClientClose( event:Event ):void
{
trace( "Connection to client closed." );
//Should also remove from clientSockets array...
}
private function onIOError( errorEvent:IOErrorEvent ):void
{
trace( "IOError: " + errorEvent.text );
}
private function onClose( event:Event ):void
{
trace( "Server socket closed by OS." );
}
}}
Last updated 3/21/2011
775
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Sockets
For more information, see:
• ServerSocket
• ServerSocketConnectEvent
• Socket
UDP sockets (AIR)
Adobe AIR 2 and later
The Universal Datagram Protocol (UDP) provides a way to exchange messages over a stateless network connection.
UDP provides no guarantees that messages are delivered in order or even that messages are delivered at all. With UDP,
the operating system’s network code usually spends less time marshaling, tracking, and acknowledging messages.
Thus, UDP messages typically arrive at the destination application with a shorter delay than do TCP messages.
UDP socket communication is helpful when you must send real-time information such as position updates in a game,
or sound packets in an audio chat application. In such applications, some data loss is acceptable, and low transmission
latency is more important than guaranteed arrival. For almost all other purposes, TCP sockets are a better choice.
Your AIR application can send and receive UDP messages with the DatagramSocket and DatagramSocketDataEvent
classes. To send or receive a UDP message:
1 Create a DatagramSocket object
2 Add an event listener for the data event
3 Bind the socket to a local IP address and port using the bind() method
4 Send messages by calling the send() method, passing in the IP address and port of the target computer
5 Receive messages by responding to the data event. The DatagramSocketDataEvent object dispatched for this event
contains a ByteArray object containing the message data.
The following code example illustrates how an application can send and receive UDP messages. The example sends a
single message containing the string, “Hello.”, to the target computer. It also traces the contents of any messages
received.
Last updated 3/21/2011
776
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Sockets
package
{
import flash.display.Sprite;
import flash.events.DatagramSocketDataEvent;
import flash.events.Event;
import flash.net.DatagramSocket;
import flash.utils.ByteArray;
public class DatagramSocketExample extends Sprite
{
private var datagramSocket:DatagramSocket;
//The IP and port for this computer
private var localIP:String = "192.168.0.1";
private var localPort:int = 55555;
//The IP and port for the target computer
private var targetIP:String = "192.168.0.2";
private var targetPort:int = 55555;
public function DatagramSocketExample()
{
//Create the socket
datagramSocket = new DatagramSocket();
datagramSocket.addEventListener( DatagramSocketDataEvent.DATA, dataReceived );
//Bind the socket to the local network interface and port
datagramSocket.bind( localPort, localIP );
//Listen for incoming datagrams
datagramSocket.receive();
//Create a message in a ByteArray
var data:ByteArray = new ByteArray();
data.writeUTFBytes("Hello.");
//Send the datagram message
datagramSocket.send( data, 0, 0, targetIP, targetPort);
}
private function dataReceived( event:DatagramSocketDataEvent ):void
{
//Read the data from the datagram
trace("Received from " + event.srcAddress + ":" + event.srcPort + "> " +
event.data.readUTFBytes( event.data.bytesAvailable ) );
}
}}
Keep in mind the following considerations when using UDP sockets:
• A single packet of data cannot be larger than the smallest maximum transmission unit (MTU) of the network
interface or any network nodes between the sender and the recipient. All of the data in the ByteArray object passed
to the send() method is sent as a single packet. (In TCP, large messages are broken up into separate packets.)
• There is no handshaking between the sender and the target. Messages are discarded without error if the target does
not exist or does not have an active listener at the specified port.
Last updated 3/21/2011
777
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Sockets
• When you use the connect() method, messages sent from other sources are ignored. A UDP connection provides
convenient packet filtering only. It does not mean that there is necessarily a valid, listening process at the target
address and port.
• UDP traffic can swamp a network. Network administrators might need to implement quality-of-service controls if
network congestion occurs. (TCP has built-in traffic control to reduce the impact of network congestion.)
For more information, see:
• DatagramSocket
• DatagramSocketDataEvent
• ByteArray
IPv6 addresses
Flash Player 9 and later, Adobe AIR 1.0 and later
Flash Player 9.0.115.0 and later support IPv6 (Internet Protocol version 6). IPv6 is a version of Internet Protocol that
supports 128-bit addresses (an improvement on the earlier IPv4 protocol that supports 32-bit addresses). You might
need to activate IPv6 on your networking interfaces. For more information, see the Help for the operating system
hosting the data.
If IPv6 is supported on the hosting system, you can specify numeric IPv6 literal addresses in URLs enclosed in brackets
([]), as in the following:
[2001:db8:ccc3:ffff:0:444d:555e:666f]
Flash Player returns literal IPv6 values, according to the following rules:
• Flash Player returns the long form of the string for IPv6 addresses.
• The IP value has no double-colon abbreviations.
• Hexadecimal digits are lowercase only.
• IPv6 addresses are enclosed in square brackets ([]).
• Each address quartet is output as 0 to 4 hexadecimal digits, with the leading zeros omitted.
• An address quartet of all zeros is output as a single zero (not a double colon) except as noted in the following list of
exceptions.
The IPv6 values that Flash Player returns have the following exceptions:
• An unspecified IPv6 address (all zeros) is output as [::].
• The loopback or localhost IPv6 address is output as [::1].
• IPv4 mapped (converted to IPv6) addresses are output as [::ffff:a.b.c.d], where a.b.c.d is a typical IPv4 dotteddecimal value.
• IPv4 compatible addresses are output as [::a.b.c.d], where a.b.c.d is a typical IPv4 dotted-decimal value.
Last updated 3/21/2011
778
Chapter 42: HTTP communications
Flash Player 9 and later, Adobe AIR 1.0 and later
Adobe® AIR® and Adobe® Flash® Player applications can communicate with HTTP-based servers to load data, images,
video and to exchange messages.
More Help topics
flash.net.URLLoader
flash.net.URLStream
flash.net.URLRequest
flash.net.URLRequestDefaults
flash.net.URLRequestHeader
flash.net.URLRequestMethod
flash.net.URLVariables
Loading external data
Flash Player 9 and later, Adobe AIR 1.0 and later
ActionScript 3.0 includes mechanisms for loading data from external sources. Those sources can provide static content
such as text files, or dynamic content generated by a web script. The data can be formatted in various ways, and
ActionScript provides functionality for decoding and accessing the data. You can also send data to the external server
as part of the process of retrieving data.
Using the URLRequest class
Flash Player 9 and later, Adobe AIR 1.0 and later
Many APIs that load external data use the URLRequest class to define the properties of necessary network request.
URLRequest properties
Flash Player 9 and later, Adobe AIR 1.0 and later
You can set the following properties of a URLRequest object in any security sandbox:
Last updated 3/21/2011
779
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
HTTP communications
Property
Description
contentType
The MIME content type of any data sent with the URL request. If no contentType is set, values are sent as
application/x-www-form-urlencoded.
data
An object containing data to be transmitted with the URL request.
digest
A string that uniquely identifies the signed Adobe platform component to be stored to (or retrieved from) the
Adobe® Flash® Player cache.
method
The HTTP request method, such as a GET or POST. (Content running in the AIR application security domain can
specify strings other than "GET" or "POST" as the method property. Any HTTP verb is allowed and "GET" is
the default method. See “AIR security” on page 1041.)
requestHeaders
The array of HTTP request headers to be appended to the HTTP request. Note that permission to set some
headers is restricted in Flash Player as well as in AIR content running outside the application security sandbox.
url
Specifies the URL to be requested.
In AIR, you can set additional properties of the URLRequest class, which are only available to AIR content running in
the application security sandbox. Content in the application sandbox can also define URLs using new URL schemes
(in addition to standard schemes like file and http).
Property
Description
followRedirects
Specifies whether redirects are to be followed (true, the default value) or not (false). This is only supported
in the AIR application sandbox.
manageCookies
Specifies whether the HTTP protocol stack should manage cookies (true, the default value) or not (false) for
this request. Setting this property is only supported in the AIR application sandbox.
authenticate
Specifies whether authentication requests should be handled (true) for this request. Setting this property is
only supported in the AIR application sandbox. The default is to authenticate requests—which may cause an
authentication dialog box to be displayed if the server requires credentials. You can also set the user name and
password using the URLRequestDefaults class—see “Setting URLRequest defaults (AIR only)” on page 779.
cacheResponse
Specifies whether response data should be cached for this request. Setting this property is only supported in
the AIR application sandbox. The default is to cache the response (true).
useCache
Specifies whether the local cache should be consulted before this URLRequest fetches data. Setting this
property is only supported in the AIR application sandbox. The default (true) is to use the local cached
version, if available.
userAgent
Specifies the user-agent string to be used in the HTTP request.
Note: The HTMLLoader class has related properties for settings pertaining to content loaded by an HTMLLoader object.
For details, see “About the HTMLLoader class” on page 952.
Setting URLRequest defaults (AIR only)
Adobe AIR 1.0 and later
The URLRequestDefaults class lets you define application-specific default settings for URLRequest objects. For
example, the following code sets the default values for the manageCookies and useCache properties. All new
URLRequest objects will use the specified values for these properties instead of the normal defaults:
URLRequestDefaults.manageCookies = false;
URLRequestDefaults.useCache = false;
Note: The URLRequestDefaults class is defined for content running in Adobe AIR only. It is not supported in Flash Player.
Last updated 3/21/2011
780
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
HTTP communications
The URLRequestDefaults class includes a setLoginCredentialsForHost() method that lets you specify a default
user name and password to use for a specific host. The host, which is defined in the hostname parameter of the method,
can be a domain, such as "www.example.com", or a domain and a port number, such as "www.example.com:80".
Note that "example.com", "www.example.com", and "sales.example.com" are each considered unique hosts.
These credentials are only used if the server requires them. If the user has already authenticated (for example, by using
the authentication dialog box), then calling the setLoginCredentialsForHost() method does not change the
authenticated user.
The following code sets the default user name and password to use for requests sent to www.example.com:
URLRequestDefaults.setLoginCredentialsForHost("www.example.com", "Ada", "love1816$X");
The URLRequestDefaults settings only apply to the current application domain, with one exception. The credentials
passed to the setLoginCredentialsForHost() method are used for requests made in any application domain within
the AIR application.
For more information, see the URLRequestDefaults class in the ActionScript 3.0 Reference for the Adobe Flash
Platform.
URI schemes
Flash Player 9 and later, Adobe AIR 1.0 and later
The standard URI schemes, such as the following, can be used in requests made from any security sandbox:
http: and https:
Use these for standard Internet URLs (in the same way that they are used in a web browser).
file:
Use file: to specify the URL of a file located on the local file system. For example:
file:///c:/AIR Test/test.txt
In AIR, you can also use the following schemes when defining a URL for content running in the application security
sandbox:
app:
Use app: to specify a path relative to the root directory of the installed application. For example, the following path
points to a resources subdirectory of the directory of the installed application:
app:/resources
When an AIR application is launched using the AIR Debug Launcher (ADL), the application directory is the directory
that contains the application descriptor file.
app-storage:
Use app-storage: to specify a path relative to the data storage directory of the application. For each installed
application (and user), AIR creates a unique application storage directory, which is a useful place to store data specific
to that application. For example, the following path points to a prefs.xml file in a settings subdirectory of the
application store directory:
app-storage:/settings/prefs.xml
Last updated 3/21/2011
781
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
HTTP communications
The application storage directory location is based on the user name, the application ID, and the publisher ID (if
applicable):
• On Mac OS—In:
/Users/user name/Library/Preferences/applicationID.publisherID/Local Store/
For example:
/Users/babbage/Library/Preferences/com.example.TestApp.02D88EEED35F84C264A183921344EEA353
A629FD.1/Local Store
• On Windows—In the documents and Settings directory, in:
user name/Application Data/applicationID.publisherID/Local Store/
For example:
C:\Documents and Settings\babbage\Application
Data\com.example.TestApp.02D88EEED35F84C264A183921344EEA353A629FD.1\Local Store
• On Linux—In:
/home/user name/.appdata/applicationID.publisherID/Local Store/
For example:
/home/babbage/.appdata/com.example.TestApp.02D88EEED35F84C264A183921344EEA353A629FD.1\Loc
al Store
Note: As of AIR 1.5.3, not all AIR applications have a publisher ID.
The URL (and url property) for a File object created with File.applicationStorageDirectory uses the appstorage URI scheme, as in the following:
var dir:File = File.applicationStorageDirectory;
dir = dir.resolvePath("preferences");
trace(dir.url); // app-storage:/preferences
mailto:
You can use the mailto scheme in URLRequest objects passed to the navigateToURL() function. See “Opening a URL
in another application” on page 794.
You can use a URLRequest object that uses any of these URI schemes to define the URL request for a number of
different objects, such as a FileStream or a Sound object. You can also use these schemes in HTML content running in
AIR; for example, you can use them in the src attribute of an img tag.
However, you can only use these AIR-specific URI schemes (app: and app-storage:) in content in the application
security sandbox. For more information, see “AIR security” on page 1041.
Prohibited URI schemes (in AIR)
Some APIs allow you to launch content in a web browser. For security reasons, some URI schemes are prohibited when
using these APIs in AIR. The list of prohibited schemes depends on the security sandbox of the code using the API.
For details, see “Opening a URL in another application” on page 794.
Setting URL variables
While you can add variables to the URL string directly, it can be easier to use the URLVariables class to define any
variables needed for a request.
Last updated 3/21/2011
782
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
HTTP communications
There are three ways in which you can add parameters to a URLVariables object:
• Within the URLVariables constructor
• With the URLVariables.decode() method
• As dynamic properties of the URLVariables object itself
The following example illustrates all three methods and also how to assign the variables to a URLRequest object:
var urlVar:URLVariables = new URLVariables( "one=1&two=2" );
urlVar.decode("amp=" + encodeURIComponent( "&" ) );
urlVar.three = 3;
urlVar.amp2 = "&&";
trace(urlVar.toString()); //amp=%26&2=%26%26&one=1&two=2&three=3
var urlRequest:URLRequest = new URLRequest( "http://www.example.com/test.cfm" );
urlRequest.data = urlVar;
When you define variables within the URLVariables constructor or within the URLVariables.decode() method,
make sure that you URL-encode the characters that have a special meaning in a URI string. For example, when you
use an ampersand in a parameter name or value, you must encode the ampersand by changing it from & to %26 because
the ampersand acts as a delimiter for parameters. The top-level encodeURIComponent() function can be used for this
purpose.
Using the URLLoader class
Flash Player 9 and later, Adobe AIR 1.0 and later
The URLLoader class let you send a request to a server and access the information returned. You can also use the
URLLoader class to access files on the local file system in contexts where local file access is permitted (such as the Flash
Player local-with-filesystem sandbox and the AIR application sandbox). The URLLoader class downloads data from a
URL as text, binary data, or URL-encoded variables. The URLLoader class dispatches events such as complete,
httpStatus, ioError, open, progress, and securityError.
The ActionScript 3.0 event-handling model is significantly different than the ActionScript 2.0 model, which used the
LoadVars.onData, LoadVars.onHTTPStatus, and LoadVars.onLoad event handlers. For more information on
handling events in ActionScript 3.0, see “Handling events” on page 117
Downloaded data is not available until the download has completed. You can monitor the progress of the download
(bytes loaded and bytes total) by listening for the progress event to be dispatched. However, if a file loads quickly
enough a progress event might not be dispatched. When a file has successfully downloaded, the complete event is
dispatched. By setting the URLLoader dataFormat property, you can receive the data as text, raw binary data, or as a
URLVariables object.
The URLLoader.load() method (and optionally the URLLoader class’s constructor) takes a single parameter,
request, which is a URLRequest object. A URLRequest object contains all of the information for a single HTTP
request, such as the target URL, request method (GET or POST), additional header information, and the MIME type.
For example, to upload an XML packet to a server-side script, you could use the following code:
Last updated 3/21/2011
783
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
HTTP communications
var secondsUTC:Number = new Date().time;
var dataXML:XML =
;
var request:URLRequest = new URLRequest("http://www.yourdomain.com/time.cfm");
request.contentType = "text/xml";
request.data = dataXML.toXMLString();
request.method = URLRequestMethod.POST;
var loader:URLLoader = new URLLoader();
loader.load(request);
The previous snippet creates an XML document named dataXML that contains the XML packet to be sent to the server.
The example sets the URLRequest contentType property to "text/xml" and assigns the XML document to the
URLRequest data property. Finally, the example creates a URLLoader object and sends the request to the remote
script by using the load() method.
Using the URLStream class
Flash Player 9 and later, Adobe AIR 1.0 and later
The URLStream class provides access to the downloading data as the data arrives. The URLStream class also lets you
close a stream before it finishes downloading. The downloaded data is available as raw binary data.
When reading data from a URLStream object, use the bytesAvailable property to determine whether sufficient data
is available before reading it. An EOFError exception is thrown if you attempt to read more data than is available.
The httpResponseStatus event (AIR)
In Adobe AIR, the URLStream class dispatches an httpResponseStatus event in addition to the httpStatus event.
The httpResponseStatus event is delivered before any response data. The httpResponseStatus event (represented
by the HTTPStatusEvent class) includes a responseURL property, which is the URL that the response was returned
from, and a responseHeaders property, which is an array of URLRequestHeader objects representing the response
headers that the response returned.
Loading data from external documents
Flash Player 9 and later, Adobe AIR 1.0 and later
When you build dynamic applications, it can be useful to load data from external files or from server-side scripts. This
lets you build dynamic applications without having to edit or recompile your application. For example, if you build a
“tip of the day” application, you can write a server-side script that retrieves a random tip from a database and saves it
to a text file once a day. Then your application can load the contents of a static text file instead of querying the database
each time.
The following snippet creates a URLRequest and URLLoader object, which loads the contents of an external text file,
params.txt:
var request:URLRequest = new URLRequest("params.txt");
var loader:URLLoader = new URLLoader();
loader.load(request);
Last updated 3/21/2011
784
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
HTTP communications
By default, if you do not define a request method, Flash Player and Adobe AIR load the content using the HTTP GET
method. To send the request using the POST method, set the request.method property to POST using the static
constant URLRequestMethod.POST, as the following code shows:
var request:URLRequest = new URLRequest("sendfeedback.cfm");
request.method = URLRequestMethod.POST;
The external document, params.txt, that is loaded at run time contains the following data:
monthNames=January,February,March,April,May,June,July,August,September,October,November,Dece
mber&dayNames=Sunday,Monday,Tuesday,Wednesday,Thursday,Friday,Saturday
The file contains two parameters, monthNames and dayNames. Each parameter contains a comma-separated list that
is parsed as strings. You can split this list into an array using the String.split() method.
Avoid using reserved words or language constructs as variable names in external data files, because doing so makes
reading and debugging your code more difficult.
Once the data has loaded, the complete event is dispatched, and the contents of the external document are available
to use in the URLLoader’s data property, as the following code shows:
function completeHandler(event)
{
var loader2 = event.target;
air.trace(loader2.data);
}
If the remote document contains name-value pairs, you can parse the data using the URLVariables class by passing in
the contents of the loaded file, as follows:
private function completeHandler(event:Event):void
{
var loader2:URLLoader = URLLoader(event.target);
var variables:URLVariables = new URLVariables(loader2.data);
trace(variables.dayNames);
}
Each name-value pair from the external file is created as a property in the URLVariables object. Each property within
the variables object in the previous code sample is treated as a string. If the value of the name-value pair is a list of items,
you can convert the string into an array by calling the String.split() method, as follows:
var dayNameArray:Array = variables.dayNames.split(",");
If you are loading numeric data from external text files, convert the values into numeric values by using a top-level
function, such as int(), uint(), or Number().
Instead of loading the contents of the remote file as a string and creating a new URLVariables object, you could instead
set the URLLoader.dataFormat property to one of the static properties found in the URLLoaderDataFormat class.
The three possible values for the URLLoader.dataFormat property are as follows:
•
URLLoaderDataFormat.BINARY—The URLLoader.data property will contain binary data stored in a ByteArray
object.
•
•
URLLoaderDataFormat.TEXT—The URLLoader.data property will contain text in a String object.
URLLoaderDataFormat.VARIABLES—The URLLoader.data property will contain URL-encoded variables stored
in a URLVariables object.
The following code demonstrates how setting the URLLoader.dataFormat property to
URLLoaderDataFormat.VARIABLES allows you to automatically parse loaded data into a URLVariables object:
Last updated 3/21/2011
785
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
HTTP communications
package
{
import
import
import
import
import
flash.display.Sprite;
flash.events.*;
flash.net.URLLoader;
flash.net.URLLoaderDataFormat;
flash.net.URLRequest;
public class URLLoaderDataFormatExample extends Sprite
{
public function URLLoaderDataFormatExample()
{
var request:URLRequest = new URLRequest("http://www.[yourdomain].com/params.txt");
var variables:URLLoader = new URLLoader();
variables.dataFormat = URLLoaderDataFormat.VARIABLES;
variables.addEventListener(Event.COMPLETE, completeHandler);
try
{
variables.load(request);
}
catch (error:Error)
{
trace("Unable to load URL: " + error);
}
}
private function completeHandler(event:Event):void
{
var loader:URLLoader = URLLoader(event.target);
trace(loader.data.dayNames);
}
}
}
Note: The default value for URLLoader.dataFormat is URLLoaderDataFormat.TEXT.
As the following example shows, loading XML from an external file is the same as loading URLVariables. You can
create a URLRequest instance and a URLLoader instance and use them to download a remote XML document. When
the file has completely downloaded, the Event.COMPLETE event is dispatched and the contents of the external file are
converted to an XML instance, which you can parse using XML methods and properties.
Last updated 3/21/2011
786
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
HTTP communications
package
{
import
import
import
import
import
flash.display.Sprite;
flash.errors.*;
flash.events.*;
flash.net.URLLoader;
flash.net.URLRequest;
public class ExternalDocs extends Sprite
{
public function ExternalDocs()
{
var request:URLRequest = new URLRequest("http://www.[yourdomain].com/data.xml");
var loader:URLLoader = new URLLoader();
loader.addEventListener(Event.COMPLETE, completeHandler);
try
{
loader.load(request);
}
catch (error:ArgumentError)
{
trace("An ArgumentError has occurred.");
}
catch (error:SecurityError)
{
trace("A SecurityError has occurred.");
}
}
private function completeHandler(event:Event):void
{
var dataXML:XML = XML(event.target.data);
trace(dataXML.toXMLString());
}
}
}
Communicating with external scripts
Flash Player 9 and later, Adobe AIR 1.0 and later
In addition to loading external data files, you can also use the URLVariables class to send variables to a server-side
script and process the server’s response. This is useful, for example, if you are programming a game and want to send
the user’s score to a server to calculate whether it should be added to the high scores list, or even send a user’s login
information to a server for validation. A server-side script can process the user name and password, validate it against
a database, and return confirmation of whether the user-supplied credentials are valid.
The following snippet creates a URLVariables object named variables, which creates a new variable called name.
Next, a URLRequest object is created that specifies the URL of the server-side script to send the variables to. Then you
set the method property of the URLRequest object to send the variables as an HTTP POST request. To add the
URLVariables object to the URL request, you set the data property of the URLRequest object to the URLVariables
object created earlier. Finally, the URLLoader instance is created and the URLLoader.load() method is invoked,
which initiates the request.
Last updated 3/21/2011
787
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
HTTP communications
var variables:URLVariables = new URLVariables("name=Franklin");
var request:URLRequest = new URLRequest();
request.url = "http://www.[yourdomain].com/greeting.cfm";
request.method = URLRequestMethod.POST;
request.data = variables;
var loader:URLLoader = new URLLoader();
loader.dataFormat = URLLoaderDataFormat.VARIABLES;
loader.addEventListener(Event.COMPLETE, completeHandler);
try
{
loader.load(request);
}
catch (error:Error)
{
trace("Unable to load URL");
}
function completeHandler(event:Event):void
{
trace(event.target.data.welcomeMessage);
}
The following code contains the contents of the Adobe ColdFusion® greeting.cfm document used in the previous
example:
welcomeMessage=#UrlEncodedFormat("Welcome, " & Form.name)#
Web service requests
Flash Player 9 and later, Adobe AIR 1.0 and later
There are a variety of HTTP-based web services. The main types include:
• REST
• XML-RPC
• SOAP
To use a web service in ActionScript 3, you create a URLRequest object, construct the web service call using either URL
variables or an XML document, and send the call to the service using a URLLoader object. The Flex framework
contains several classes that make it easier to use web services—especially useful when accessing complex SOAP
services. Starting with Flash Professional CS3, you can use the Flex classes in applications developed with Flash
Professional as well as in applications developed in Flash Builder.
In HTML-based AIR applications, you can use either the URLRequest and URLLoader classes or the JavaScript
XMLHttpRequest class. If desired, you can also create a SWF library that exposes the web service components of the
Flex framework to your JavaScript code.
Last updated 3/21/2011
788
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
HTTP communications
When your application runs in a browser, you can only use web services in the same Internet domain as the calling
SWF unless the server hosting the web service also hosts a cross-domain policy file that permits access from other
domains. A technique that is often used when a cross-domain policy file is not available is to proxy the requests
through your own server. Adobe Blaze DS and Adobe LiveCycle support web service proxying.
In AIR applications, a cross-domain policy file is not required when the web service call originates from the application
security sandbox. AIR application content is never served from a remote domain, so it cannot participate in the types
of attacks that cross-domain policies prevent. In HTML-based AIR applications, content in the application security
sandbox can make cross-domain XMLHttpRequests. You can allow content in other security sandboxes to make crossdomain XMLHttpRequests as long as that content is loaded into an iframe.
More Help topics
“Website controls (policy files)” on page 1017
Adobe BlazeDS
Adobe LiveCycle ES2
REST architecture
XML-RPC
SOAP protocol
REST-style web service requests
Flash Player 9 and later, Adobe AIR 1.0 and later
REST-style web services use HTTP method verbs to designate the basic action and URL variables to specify the action
details. For example, a request to get data for an item could use the GET verb and URL variables to specify a method
name and item ID. The resulting URL string might look like:
http://service.example.com/?method=getItem&id=d3452
To access a REST-style web service with ActionScript, you can use the URLRequest, URLVariables, and URLLoader
classes. In JavaScript code within an AIR application, you can also use an XMLHttpRequest.
Programming a REST-style web service call in ActionScript, typically involves the following steps:
1 Create a URLRequest object.
2 Set the service URL and HTTP method verb on the request object.
3 Create a URLVariables object.
4 Set the service call parameters as dynamic properties of the variables object.
5 Assign the variables object to the data property of the request object.
6 Send the call to the service with a URLLoader object.
7 Handle the complete event dispatched by the URLLoader that indicates that the service call is complete. It is also
wise to listen for the various error events that can be dispatched by a URLLoader object.
For example, consider a web service that exposes a test method that echoes the call parameters back to the requestor.
The following ActionScript code could be used to call the service:
Last updated 3/21/2011
789
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
HTTP communications
import
import
import
import
import
import
import
import
flash.events.Event;
flash.events.ErrorEvent;
flash.events.IOErrorEvent;
flash.events.SecurityErrorEvent;
flash.net.URLLoader;
flash.net.URLRequest;
flash.net.URLRequestMethod;
flash.net.URLVariables;
private var requestor:URLLoader = new URLLoader();
public function restServiceCall():void
{
//Create the HTTP request object
var request:URLRequest = new URLRequest( "http://service.example.com/" );
request.method = URLRequestMethod.GET;
//Add the URL variables
var variables:URLVariables = new URLVariables();
variables.method = "test.echo";
variables.api_key = "123456ABC";
variables.message = "Able was I, ere I saw Elba.";
request.data = variables;
//Initiate the transaction
requestor = new URLLoader();
requestor.addEventListener( Event.COMPLETE, httpRequestComplete );
requestor.addEventListener( IOErrorEvent.IOERROR, httpRequestError );
requestor.addEventListener( SecurityErrorEvent.SECURITY_ERROR, httpRequestError );
requestor.load( request );
}
private function httpRequestComplete( event:Event ):void
{
trace( event.target.data );
}
private function httpRequestError( error:ErrorEvent ):void{
trace( "An error occured: " + error.message );
}
In JavaScript within an AIR application, you can make the same request using the XMLHttpRequest object:
Last updated 3/21/2011
790
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
HTTP communications
RESTful web service request
Request:
Result:
Last updated 3/21/2011
791
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
HTTP communications
XML-RPC web service requests
Flash Player 9 and later, Adobe AIR 1.0 and later
An XML-RPC web service takes its call parameters as an XML document rather than as a set of URL variables. To
conduct a transaction with an XML-RPC web service, create a properly formatted XML message and send it to the web
service using the HTTP POST method. In addition, you should set the Content-Type header for the request so that the
server treats the request data as XML.
The following example illustrates how to use the same web service call shown in the REST example, but this time as an
XML-RPC service:
import flash.events.Event;
import flash.events.ErrorEvent;
import flash.events.IOErrorEvent;
import flash.events.SecurityErrorEvent;
import flash.net.URLLoader;
import flash.net.URLRequest;
import flash.net.URLRequestMethod;
import flash.net.URLVariables;
public function xmlRPCRequest():void
{
//Create the XML-RPC document
var xmlRPC:XML = ;
xmlRPC.methodName = "test.echo";
//Add the method parameters
var parameters:Object = new Object();
parameters.api_key = "123456ABC";
parameters.message = "Able was I, ere I saw Elba.";
for( var propertyName:String in parameters )
{
xmlRPC..struct.member[xmlRPC..struct.member.length + 1] =
{propertyName}{parameters[propertyName]};
}
//Create the HTTP request object
var request:URLRequest = new URLRequest( "http://service.example.com/xml-rpc/" );
request.method = URLRequestMethod.POST;
request.cacheResponse = false;
request.requestHeaders.push(new URLRequestHeader("Content-Type", "application/xml"));
Last updated 3/21/2011
792
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
HTTP communications
request.data = xmlRPC;
//Initiate the request
requestor = new URLLoader();
requestor.dataFormat = URLLoaderDataFormat.TEXT;
requestor.addEventListener( Event.COMPLETE, xmlRPCRequestComplete );
requestor.addEventListener( IOErrorEvent.IO_ERROR, xmlRPCRequestError );
requestor.addEventListener( SecurityErrorEvent.SECURITY_ERROR, xmlRPCRequestError );
requestor.load( request );
}
private function xmlRPCRequestComplete( event:Event ):void
{
trace( XML(event.target.data).toXMLString() );
}
private function xmlRPCRequestError( error:ErrorEvent ):void
{
trace( "An error occurred: " + error );
}
WebKit in AIR doesn’t support E4X syntax, so the method used to create the XML document in the previous example
does not work in JavaScript code. Instead, you must use the DOM methods to create the XML document or create the
document as a string and use the JavaScript DOMParser class to convert the string to XML.
The following example uses DOM methods to create an XML-RPC message and an XMLHttpRequest to conduct the
web service transaction:
XML-RPC web service request
Request:
Result:
SOAP web service requests
Flash Player 9 and later, Adobe AIR 1.0 and later
SOAP builds on the general XML-RPC web service concept and provides a richer, albeit more complex, means for
transferring typed data. SOAP web services typically provide a Web Service Description Language file (WSDL) that
specifies the web service calls, data types, and service URL. While ActionScript 3 does not provide direct support for
SOAP, you can construct a SOAP XML message “by hand,” post it to the server, and then parse the results. However,
for anything except the simplest SOAP web service, you can probably save a significant amount of development time
using an existing SOAP library.
The Flex framework includes libraries for accessing SOAP web services. In Flash Builder the library, rpc.swc, is
automatically included in Flex projects, since it is part of the Flex framework. In Flash Professional, you can add the
Flex framework.swc and rpc.swc to the library path of a project and then access the Flex classes with ActionScript.
More Help topics
Using the Flex web service component in Flash Professional
Cristophe Coenraets: Real-time Trader Desktop for Android
Opening a URL in another application
Flash Player 9 and later, Adobe AIR 1.0 and later
You can use the navigateToURL() function to open a URL in a web browser or other application. For content running
in AIR, the navigateToURL() function opens the page in the default system web browser.
Last updated 3/21/2011
795
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
HTTP communications
For the URLRequest object you pass as the request parameter of this function, only the url property is used.
The first parameter of the navigateToURL() function, the navigate parameter, is a URLRequest object (see “Using
the URLRequest class” on page 778). The second is an optional window parameter, in which you can specify the
window name. For example, the following code opens the www.adobe.com web page:
var url:String = "http://www.adobe.com";
var urlReq:URLRequest = new URLRequest(url);
navigateToURL(urlReq);
Note: When using the navigateToURL() function, the runtime treats a URLRequest object that uses the POST method
(one that has its method property set to URLRequestMethod.POST) as using the GET method.
When using the navigateToURL() function, URI schemes are permitted based on the security sandbox of the code
calling the navigateToURL() function.
Some APIs allow you to launch content in a web browser. For security reasons, some URI schemes are prohibited when
using these APIs in AIR. The list of prohibited schemes depends on the security sandbox of the code using the API.
(For details on security sandboxes, see “AIR security” on page 1041.)
Application sandbox (AIR only)
The following schemes are allowed. Use these schemes as you would use them in a web browser.
•
http:
•
https:
•
file:
•
mailto: — AIR directs these requests to the registered system mail application
•
app:
•
app-storage:
•
sms: — on mobile devices, AIR redirects sms: requests to the default text message app. (If no app is configured to
handle sms: URLs, then the request will do nothing.) The URL format must conform to the system conventions
under which the app is running. For example, on Android, the URI scheme must be lowercase.
navigateToURL( new URLRequest( "sms:+15555550101") );
•
tel: — on mobile devices, AIR redirects tel: requests to the default telephone dialing app. (If no app is configured
to handle tel: URLs, then the request will do nothing.) The URL format must conform to the system conventions
under which the app is running. For example, on Android, the URI scheme must be lowercase.
navigateToURL( new URLRequest( "tel:5555555555") );
•
market: — on Android devices, AIR redirects market: requests to the Market app.
navigateToURL( new URLRequest( "market://search?q=Adobe Flash") );
navigateToURL( new URLRequest( "market://search?q=pname:com.adobe.flashplayer") );
All other URL schemes are prohibited.
Remote sandboxes
The following schemes are allowed. Use these schemes as you would use them in a web browser.
•
http:
•
https:
•
mailto: — AIR directs these requests to the registered system mail application
Last updated 3/21/2011
796
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
HTTP communications
All other URI schemes are prohibited.
Local-with-file sandbox
The following schemes are allowed. Use these schemes as you would use them in a web browser.
•
file:
•
mailto: — AIR directs these requests to the registered system mail application
All other URI schemes are prohibited.
Local-with-networking sandbox
The following schemes are allowed. Use these schemes as you would use them in a web browser.
•
http:
•
https:
•
mailto: — AIR directs these requests to the registered system mail application
All other URI schemes are prohibited.
Local-trusted sandbox
The following schemes are allowed. Use these schemes as you would use them in a web browser.
•
file:
•
http:
• https:
•
mailto: — AIR directs these requests to the registered system mail application
All other URI schemes are prohibited.
Last updated 3/21/2011
797
Chapter 43: Communicating with other
Flash Player and AIR instances
Flash Player 9 and later, Adobe AIR 1.0 and later
The LocalConnection class enables communications between Adobe® AIR® applications, as well as between SWF
content running in the browser. You can also use the LocalConnection class to communicate between an AIR
application and SWF content running in the browser. The LocalConnection class allows you to build versatile
applications that can share data between Flash Player and AIR instances.
About the LocalConnection class
Flash Player 9 and later, Adobe AIR 1.0 and later
The LocalConnection class lets you develop SWF files that can send instructions to other SWF files without the use of
the fscommand() method or JavaScript. LocalConnection objects can communicate only among SWF files that are
running on the same client computer, but they can run in different applications. For example, a SWF file running in a
browser and a SWF file running in a projector can share information, with the projector maintaining local information
and the browser-based SWF file connecting remotely. (A projector is a SWF file saved in a format that can run as a
stand-alone application—that is, the projector doesn’t require Flash Player to be installed because it is embedded
inside the executable.)
LocalConnection objects can be used to communicate between SWFs using different ActionScript versions:
• ActionScript 3.0 LocalConnection objects can communicate with LocalConnection objects created in ActionScript
1.0 or 2.0.
• ActionScript 1.0 or 2.0 LocalConnection objects can communicate with LocalConnection objects created in
ActionScript 3.0.
Flash Player handles this communication between LocalConnection objects of different versions automatically.
The simplest way to use a LocalConnection object is to allow communication only between LocalConnection objects
located in the same domain or the same AIR application. That way, you do not have to worry about security issues.
However, if you need to allow communication between domains, you have several ways to implement security
measures. For more information, see the discussion of the connectionName parameter of the send() method and the
allowDomain() and domain entries in the LocalConnection class listing in the ActionScript 3.0 Reference for the
Adobe Flash Platform.
It is possible to use LocalConnection objects to send and receive data within a single SWF file, but Adobe does not
recommended doing so. Instead, use shared objects.
There are three ways to add callback methods to your LocalConnection objects:
• Subclass the LocalConnection class and add methods.
• Set the LocalConnection.client property to an object that implements the methods.
• Create a dynamic class that extends LocalConnection and dynamically attach methods.
Last updated 3/21/2011
798
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Communicating with other Flash Player and AIR instances
The first way to add callback methods is to extend the LocalConnection class. You define the methods within the
custom class instead of dynamically adding them to the LocalConnection instance. This approach is demonstrated in
the following code:
package
{
import flash.net.LocalConnection;
public class CustomLocalConnection extends LocalConnection
{
public function CustomLocalConnection(connectionName:String)
{
try
{
connect(connectionName);
}
catch (error:ArgumentError)
{
// server already created/connected
}
}
public function onMethod(timeString:String):void
{
trace("onMethod called at: " + timeString);
}
}
}
In order to create a new instance of the CustomLocalConnection class, you can use the following code:
var serverLC:CustomLocalConnection;
serverLC = new CustomLocalConnection("serverName");
The second way to add callback methods is to use the LocalConnection.client property. This involves creating a
custom class and assigning a new instance to the client property, as the following code shows:
var lc:LocalConnection = new LocalConnection();
lc.client = new CustomClient();
The LocalConnection.client property indicates the object callback methods that should be invoked. In the
previous code, the client property was set to a new instance of a custom class, CustomClient. The default value for
the client property is the current LocalConnection instance. You can use the client property if you have two data
handlers that have the same set of methods but act differently—for example, in an application where a button in one
window toggles the view in a second window.
To create the CustomClient class, you could use the following code:
package
{
public class CustomClient extends Object
{
public function onMethod(timeString:String):void
{
trace("onMethod called at: " + timeString);
}
}
}
The third way to add callback methods, creating a dynamic class and dynamically attaching the methods, is very
similar to using the LocalConnection class in earlier versions of ActionScript, as the following code shows:
Last updated 3/21/2011
799
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Communicating with other Flash Player and AIR instances
import flash.net.LocalConnection;
dynamic class DynamicLocalConnection extends LocalConnection {}
Callback methods can be dynamically added to this class by using the following code:
var connection:DynamicLocalConnection = new DynamicLocalConnection();
connection.onMethod = this.onMethod;
// Add your code here.
public function onMethod(timeString:String):void
{
trace("onMethod called at: " + timeString);
}
The previous way of adding callback methods is not recommended because the code is not very portable. In addition,
using this method of creating local connections could create performance issues, because accessing dynamic properties
is dramatically slower than accessing sealed properties.
isPerUser property
The isPerUser property was added to Flash Player (10.0.32) and AIR (1.5.2) to resolve a conflict that occurs when
more than one user is logged into a Mac computer. On other operating systems, the property is ignored since the local
connection has always been scoped to individual users. The isPerUser property should be set to true in new code.
However, the default value is currently false for backward compatibility. The default may be changed in future
versions of the runtimes.
Sending messages between two applications
Flash Player 9 and later, Adobe AIR 1.0 and later
You use the LocalConnection class to communicate between different AIR applications and between different Adobe®
Flash® Player (SWF) applications running in a browser. You can also use the LocalConnection class to communicate
between an AIR application and a SWF application running in a browser.
For example, you could have multiple Flash Player instances on a web page, or have a Flash Player instance retrieve
data from a Flash Player instance in a pop-up window.
The following code defines a LocalConnection object that acts as a server and accepts incoming LocalConnection calls
from other applications:
Last updated 3/21/2011
800
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Communicating with other Flash Player and AIR instances
package
{
import flash.net.LocalConnection;
import flash.display.Sprite;
public class ServerLC extends Sprite
{
public function ServerLC()
{
var lc:LocalConnection = new LocalConnection();
lc.client = new CustomClient1();
try
{
lc.connect("conn1");
}
catch (error:Error)
{
trace("error:: already connected");
}
}
}
}
This code first creates a LocalConnection object named lc and sets the client property to an object, clientObject.
When another application calls a method in this LocalConnection instance, the runtime looks for that method in the
clientObject object.
If you already have a connection with the specified name, an Argument Error exception is thrown, indicating that the
connection attempt failed because the object is already connected.
Whenever a Flash Player instance connects to this SWF file and tries to invoke any method for the specified local
connection, the request is sent to the class specified by the client property, which is set to the CustomClient1 class:
package
{
import flash.events.*;
import flash.system.fscommand;
import flash.utils.Timer;
public class CustomClient1 extends Object
{
public function doMessage(value:String = ""):void
{
trace(value);
}
public function doQuit():void
{
trace("quitting in 5 seconds");
this.close();
var quitTimer:Timer = new Timer(5000, 1);
quitTimer.addEventListener(TimerEvent.TIMER, closeHandler);
}
public function closeHandler(event:TimerEvent):void
{
fscommand("quit");
}
}
}
Last updated 3/21/2011
801
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Communicating with other Flash Player and AIR instances
To create a LocalConnection server, call the LocalConnection.connect() method and provide a unique connection
name. If you already have a connection with the specified name, an ArgumentError error is generated, indicating that
the connection attempt failed because the object is already connected.
The following snippet demonstrates how to create a LocalConnection with the name conn1:
try
{
connection.connect("conn1");
}
catch (error:ArgumentError)
{
trace("Error! Server already exists\n");
}
Connecting to the primary application from a secondary application requires that you first create a LocalConnection
object in the sending LocalConnection object; then call the LocalConnection.send() method with the name of the
connection and the name of the method to execute. For example, to send the doQuit method to the LocalConnection
object that you created earlier, use the following code:
sendingConnection.send("conn1", "doQuit");
This code connects to an existing LocalConnection object with the connection name conn1 and invokes the
doMessage() method in the remote application. If you want to send parameters to the remote application, you specify
additional arguments after the method name in the send() method, as the following snippet shows:
sendingConnection.send("conn1", "doMessage", "Hello world");
Connecting to content in different domains and to AIR
applications
Flash Player 9 and later, Adobe AIR 1.0 and later
To allow communications only from specific domains, you call the allowDomain() or allowInsecureDomain()
method of the LocalConnection class and pass a list of one or more domains that are allowed to access this
LocalConnection object, passing one or more names of domains to be allowed.
In earlier versions of ActionScript, LocalConnection.allowDomain() and
LocalConnection.allowInsecureDomain() were callback methods that had to be implemented by developers and
that had to return a Boolean value. In ActionScript 3.0, LocalConnection.allowDomain() and
LocalConnection.allowInsecureDomain() are both built-in methods, which developers can call just like
Security.allowDomain() and Security.allowInsecureDomain(), passing one or more names of domains to be
allowed.
Flash Player 8 introduced security restrictions on local SWF files. A SWF file that is allowed to access the Internet
cannot also have access to the local file system. If you specify localhost, any local SWF file can access the SWF file.
If the LocalConnection.send() method attempts to communicate with a SWF file from a security sandbox to which
the calling code does not have access, a securityError event(SecurityErrorEvent.SECURITY_ERROR) is
dispatched. To work around this error, you can specify the caller's domain in the receiver's
LocalConnection.allowDomain() method.
Last updated 3/21/2011
802
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Communicating with other Flash Player and AIR instances
There are two special values that you can pass to the LocalConnection.allowDomain() and
LocalConnection.allowInsecureDomain() methods: * and localhost. The asterisk value (*) allows access from
all domains. The string localhost allows calls to the application from content locally installed, but outside of the
application resource directory.
If the LocalConnection.send() method attempts to communicate with an application from a security sandbox to
which the calling code does not have access, a securityError event(SecurityErrorEvent.SECURITY_ERROR) is
dispatched. To work around this error, you can specify the caller's domain in the receiver's
LocalConnection.allowDomain() method.
If you implement communication only between content in the same domain, you can specify a connectionName
parameter that does not begin with an underscore (_) and does not specify a domain name (for example,
myDomain:connectionName). Use the same string in the LocalConnection.connect(connectionName)
command.
If you implement communication between content in different domains, you specify a connectionName parameter
that begins with an underscore. Specifying the underscore makes the content with the receiving LocalConnection
object more portable between domains. Here are the two possible cases:
• If the string for connectionName does not begin with an underscore, the runtime adds a prefix with the
superdomain name and a colon (for example, myDomain:connectionName). Although this ensures that your
connection does not conflict with connections of the same name from other domains, any sending
LocalConnection objects must specify this superdomain (for example, myDomain:connectionName). If you move
the HTML or SWF file with the receiving LocalConnection object to another domain, the runtime changes the
prefix to reflect the new superdomain (for example, anotherDomain:connectionName). All sending
LocalConnection objects have to be manually edited to point to the new superdomain.
• If the string for connectionName begins with an underscore (for example, _connectionName), the runtime does
not add a prefix to the string. This means the receiving and sending LocalConnection objects use identical strings
for connectionName. If the receiving object uses LocalConnection.allowDomain() to specify that connections
from any domain will be accepted, you can move the HTML or SWF file with the receiving LocalConnection object
to another domain without altering any sending LocalConnection objects.
A downside to using underscore names in connectionName is the potential for collisions, such as when two
applications both try to connect using the same connectionName. A second, related downside is security-related.
Connection names that use underscore syntax do not identify the domain of the listening application. For these
reasons, domain-qualified names are preferred.
Adobe AIR
To communicate with content running in the AIR application security sandbox (content installed with the AIR
application), you must prefix the connection name with a superdomain identifying the AIR application. The
superdomain string starts with app# followed by the application ID followed by a dot (.) character, followed by the
publisher ID (if defined). For example, the proper superdomain to use in the connectionName parameter for an
application with the application ID, com.example.air.MyApp, and no publisher ID is:
"app#com.example.air.MyApp". Thus, if the base connection name is “appConnection,” then the entire string to use
in the connectionName parameter is: "app#com.example.air.MyApp:appConnection". If the application has the
publisher ID, then the that ID must also be included in the superdomain string:
"app#com.example.air.MyApp.B146A943FBD637B68C334022D304CEA226D129B4.1".
Last updated 3/21/2011
803
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Communicating with other Flash Player and AIR instances
When you allow another AIR application to communicate with your application through the local connection, you
must call the allowDomain() of the LocalConnection object, passing in the local connection domain name. For an
AIR application, this domain name is formed from the application and publisher IDs in the same fashion as the
connection string. For example, if the sending AIR application has an application ID of
com.example.air.FriendlyApp and a publisher ID of 214649436BD677B62C33D02233043EA236D13934.1, then
the domain string that you would use to allow this application to connect is:
app#com.example.air.FriendlyApp.214649436BD677B62C33D02233043EA236D13934.1. (As of AIR 1.5.3, not
all AIR applications have publisher IDs.)
Last updated 3/21/2011
804
Chapter 44: Communicating with native
processes in AIR
Adobe AIR 2 and later
As of Adobe AIR 2, AIR applications can run and communicate with other native processes via the command line. For
example, an AIR application can run a process and communicate with it via the standard input and output streams.
To communicate with native processes, package an AIR application to be installed via a native installer. The file type
of native installer is specific to the operating system for which it is created:
• It is a DMG file on Mac OS.
• It is an EXE file on Windows.
• It is an RPM or DEB package on Linux.
These applications are known as extended desktop profile applications. You can create a native installer file by
specifying the -target native option when calling the -package command using ADT.
More Help topics
flash.filesystem.File.openWithDefaultApplication()
flash.desktop.NativeProcess
Overview of native process communications
Adobe AIR 2 and later
An AIR application in the extended desktop profile can execute a file, as if it were invoked by the command line. It can
communicate with the standard streams of the native process. Standard streams include the standard input stream
(stdin), the output stream (stdout), the standard error stream (stderr).
Note: Applications in the extended desktop profile can also launch files and applications using the
File.openWithDefaultApplication() method. However, using this method does not provide the AIR application
with access to the standard streams. For more information, see “Opening files with the default system application” on
page 648
The following code sample shows how to launch a test.exe application in the application directory. The application
passes the argument "hello" as a command-line argument, and it adds an event listener to the process’s standard
output stream:
Last updated 3/21/2011
805
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Communicating with native processes in AIR
var nativeProcessStartupInfo:NativeProcessStartupInfo = new NativeProcessStartupInfo();
var file:File = File.applicationDirectory.resolvePath("test.exe");
nativeProcessStartupInfo.executable = file;
var processArgs:Vector. = new Vector.();
processArgs.push("hello");
nativeProcessStartupInfo.arguments = processArgs;
process = new NativeProcess();
process.addEventListener(ProgressEvent.STANDARD_OUTPUT_DATA, onOutputData);
process.start(nativeProcessStartupInfo);
public function onOutputData(event:ProgressEvent):void
{
var stdOut:ByteArray = process.standardOutput;
var data:String = stdOut.readUTFBytes(process.standardOutput.bytesAvailable);
trace("Got: ", data);
}
Launching and closing a native process
Adobe AIR 2 and later
To launch a native process, set up a NativeProcessInfo object to do the following:
• Point to the file you want to launch
• Store command-line arguments to pass to the process when launched (optional)
• Set the working directory of the process (optional)
To start the native process, pass the NativeProcessInfo object as the parameter of the start() method of a
NativeProcess object.
For example, the following code shows how to launch a test.exe application in the application directory. The
application passes the argument "hello" and sets the user’s documents directory as the working directory:
var nativeProcessStartupInfo:NativeProcessStartupInfo = new NativeProcessStartupInfo();
var file:File = File.applicationDirectory.resolvePath("test.exe");
nativeProcessStartupInfo.executable = file;
var processArgs:Vector. = new Vector.();
processArgs[0] = "hello";
nativeProcessStartupInfo.arguments = processArgs;
nativeProcessStartupInfo.workingDirectory = File.documentsDirectory;
process = new NativeProcess();
process.start(nativeProcessStartupInfo);
To terminate the process, call the exit() method of the NativeProcess object.
If you want a file to be executable in your installed application, make sure that it's executable on the file system when
you package your application. (On Mac and Linux, you can use chmod to set the executable flag, if needed.)
Last updated 3/21/2011
806
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Communicating with native processes in AIR
Communicating with a native process
Adobe AIR 2 and later
Once an AIR application has started a native process, it can communicate with the standard input, standard output,
and standard error streams of the process.
You read and write data to the streams using the following properties of the NativeProcess object:
•
standardInput—Contains access to the standard input stream data.
•
standardOutput—Contains access to the standard output stream data.
•
standardError—Contains access to the standard error stream data.
Writing to the standard input stream
You can write data to the standard input stream using the write methods of the standardInput property of the
NativeProcess object. As the AIR application writes data to the process, the NativeProcess object dispatches
standardInputProgress events.
If an error occurs in writing to the standard input stream, the NativeProcess object dispatches an
ioErrorStandardInput event.
You can close the input stream by calling the closeInput() method of the NativeProcess object. When the input
stream closes, the NativeProcess object dispatches a standardInputClose event.
var nativeProcessStartupInfo:NativeProcessStartupInfo = new NativeProcessStartupInfo();
var file:File = File.applicationDirectory.resolvePath("test.exe");
nativeProcessStartupInfo.executable = file;
process = new NativeProcess();
process.start(nativeProcessStartupInfo);
process.standardInput.writeUTF("foo");
if(process.running)
{
process.closeInput();
}
Reading from the standard output stream
You can read data from the standard output stream using the read methods of this property. As the AIR application
gets output stream data from the process, the NativeProcess object dispatches standardOutputData events.
If an error occurs in writing to the standard output stream, the NativeProcess object dispatches a
standardOutputError event.
When process closes the output stream, the NativeProcess object dispatches a standardOutputClose event.
When reading data from the standard input stream, be sure to read data as it is generated. In other words, add an event
listener for the standardOutputData event. In the standardOutputData event listener, read the data from the
standardOutput property of the NativeProcess object. Do not simply wait for the standardOutputClose event or
the exit event to read all data. If you do not read data as the native process generates the data, the buffer can fill up,
or data can be lost. A full buffer can cause the native process to stall when trying to write more data. However, if you
do not register an event listener for the standardOutputData event, then the buffer will not fill and the process will
not stall. In this case, you will not have access to the data.
Last updated 3/21/2011
807
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Communicating with native processes in AIR
var nativeProcessStartupInfo:NativeProcessStartupInfo = new NativeProcessStartupInfo();
var file:File = File.applicationDirectory.resolvePath("test.exe");
nativeProcessStartupInfo.executable = file;
process = new NativeProcess();
process.addEventListener(ProgressEvent.STANDARD_OUTPUT_DATA, dataHandler);
process.start(nativeProcessStartupInfo);
var bytes:ByteArray = new ByteArray();
function dataHandler(event:ProgressEvent):void
{
bytes.writeBytes(process.standardOutput.readBytes(process.standardOutput.bytesAvailable);
}
Reading from the standard error stream
You can read data from the standard error stream using the read methods of this property. As the AIR application
reads error stream data from the process, the NativeProcess object dispatches standardErrorData events.
If an error occurs in writing to the standard error stream, the NativeProcess object dispatches an
standardErrorIoError event.
When process closes the error stream, the NativeProcess object dispatches a standardErrorClose event.
When reading data from the standard error stream, be sure to read data as it is generated. In other words, add an event
listener for the standardErrorData event. In the standardErrorData event listener, read the data from the
standardError property of the NativeProcess object. Do not simply wait for the standardErrorClose event or the
exit event to read all data. If you do not read data as the native process generates the data, the buffer can fill up, or
data can be lost. A full buffer can cause the native process to stall when trying to write more data. However, if you do
not register an event listener for the standardErrorData event, then the buffer will not fill and the process will not
stall. In this case, you will not have access to the data.
var nativeProcessStartupInfo:NativeProcessStartupInfo = new NativeProcessStartupInfo();
var file:File = File.applicationDirectory.resolvePath("test.exe");
nativeProcessStartupInfo.executable = file;
process = new NativeProcess();
process.addEventListener(ProgressEvent.STANDARD_ERROR_DATA, errorDataHandler);
process.start(nativeProcessStartupInfo);
var errorBytes:ByteArray = new ByteArray();
function errorDataHandler(event:ProgressEvent):void
{
bytes.writeBytes(process.standardError.readBytes(process.standardError.bytesAvailable);
}
Security considerations for native process
communication
Adobe AIR 2 and later
The native process API can run any executable on the user’s system. Take extreme care when constructing and
executing commands. If any part of a command to be executed originates from an external source, carefully validate
that the command is safe to execute. Likewise, your AIR application should validate any data passed to a running
process.
Last updated 3/21/2011
808
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Communicating with native processes in AIR
However, validating input can be difficult. To avoid such difficulties, it is best to write a native application (such as an
EXE file on Windows) that has specific APIs. These APIs should process only those commands defined by the
application. For example, the application may accept only a limited set of instructions via the standard input stream.
AIR on Windows does not allow you to run .bat files directly. The command interpreter application (cmd.exe)
executes Windows .bat files. When you invoke a .bat file, this command application can interpret arguments passed to
the command as additional applications to launch. A malicious injection of extra characters in the argument string
could cause cmd.exe to execute a harmful or insecure application. For example, without proper data validation, your
AIR application may call myBat.bat myArguments c:/evil.exe. The command application would launch the
evil.exe application in addition to running your batch file.
Last updated 3/21/2011
809
Chapter 45: Using the external API
Flash Player 9 and later, Adobe AIR 1.0 and later
The ActionScript 3.0 external API (flash.external.ExternalInterface) enables straightforward communication between
ActionScript and the container application within which Adobe Flash Player is running. There are several situations
in which you may want to use the external API—for example, when you create interaction between a SWF document
and JavaScript in an HTML page, or when you build a desktop application that uses Flash Player to display a SWF file.
You can use the external API to interact with a container application, pass data between ActionScript and JavaScript
in an HTML page, and establish communication and exchange data between ActionScript and a desktop application.
Some common external API tasks are:
• Getting information about the container application
• Using ActionScript to call code in a container application, including a web page or desktop application
• Calling ActionScript code from code in a container application
• Creating a proxy to simplify calling ActionScript code from a container application
Note: This discussion of the external interface only covers communication between ActionScript in a SWF file and the
container application that includes a reference to the Flash Player or instance in which the SWF file is loaded. Any other
use of Flash Player within an application is outside the scope of this documentation. Flash Player is designed to be used
as a browser plug-in or as a projector (standalone application). Other usage scenarios may have limited support.
Using the external API in AIR
Since an AIR application does not have an external container, this external interface does not generally apply—nor is
it generally needed. When your AIR application loads a SWF file directly, the application code can communicate
directly with the ActionScript code in the SWF (subject to security sandbox restrictions).
However, when your AIR application loads a SWF file using an HTML page in an HTMLLoader object (or an HTML
component in Flex), the HTMLLoader object serves as the external container. Thus, you can use the external interface
to communicate between the ActionScript code in the loaded SWF and the JavaScript code in the HTML page loaded
in the HTMLLoader.
Basics of using the external API
Flash Player 9 and later, Adobe AIR 1.0 and later
Although in some cases a SWF file can run on its own (for example, if you use Adobe® Flash® Professional to create a
SWF projector), in the majority of cases a SWF application runs as an element inside of another application.
Commonly, the container that includes the SWF is an HTML file; somewhat less frequently, a SWF file is used for all
or part of the user interface of a desktop application.
Last updated 3/21/2011
810
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Using the external API
As you work on more advanced applications, you may find a need to set up communication between the SWF file and
the container application. For instance, it’s common for a web page to display text or other information in HTML, and
include a SWF file to display dynamic visual content such as a chart or video. In such a case, you might want to make
it so that when users click a button on the web page, it changes something in the SWF file. ActionScript contains a
mechanism, known as the external API, that facilitates this type of communication between ActionScript in a SWF file
and other code in the container application.
Important concepts and terms
The following reference list contains important terms relevant to this feature:
ActiveX container A container application (not a web browser) that includes an instance of the Flash Player ActiveX
control to display SWF content within the application.
Container application The application within which Flash Player is running a SWF file, such as a web browser and
HTML page that includes Flash Player content.
Projector An executable file that includes SWF content and an embedded version of Flash Player. You can create a
projector file using Flash Professional or the standalone Flash Player. Projectors are commonly used to distribute SWF
files by CD-ROM or in similar situations where download size is not an issue and the SWF author wants to be certain
the user will be able to run the SWF file, regardless of whether Flash Player is installed on the user’s computer.
Proxy A go-between application or code that calls code in one application (the “external application”) on behalf of
another application (the “calling application”), and returns values to the calling application. A proxy can be used for
various reasons, including:
• To simplify the process of making external function calls by converting native function calls in the calling
application into the format understood by the external application.
• To work around security or other restrictions that prevent the caller from communicating directly with the external
application.
Serialize To convert objects or data values into a format that can be used to pass the values in messages between two
programming systems, such as over the Internet or between two different applications running on a single computer.
Working through the examples
Many of the code examples provided are small listings of code for demonstration purposes rather than full working
examples or code that checks values. Because using the external API requires (by definition) writing ActionScript code
as well as code in a container application, testing the examples involves creating a container (for example, a web page
containing the SWF file) and using the code listings to interact with the container.
To test an example of ActionScript-to-JavaScript communication:
1 Create a new document using Flash Professional and save it to your computer.
2 From the main menu, choose File > Publish Settings.
3 In the Publish Settings dialog box, on the Formats tab, confirm that the Flash and HTML check boxes are selected.
4 Click the Publish button. This generates a SWF file and HTML file in the same folder and with the same name that
you used to save the document. Click OK to close the Publish Settings dialog box.
5 Deselect the HTML check box. Now that the HTML page is generated, you are going to modify it to add the
appropriate JavaScript code. Deselecting the HTML check box ensures that after you modify the HTML page, Flash
will not overwrite your changes with a new HTML page when it’s publishing the SWF file.
6 Click OK to close the Publish Settings dialog box.
Last updated 3/21/2011
811
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Using the external API
7 With an HTML or text editor application, open the HTML file that was created by Flash when you published the
SWF file. In the HTML source code, add opening and closing script tags, and copy into them the JavaScript code
from the example code listing:
8 Save the HTML file and return to Flash.
9 Select the keyframe on Frame 1 of the Timeline, and open the Actions panel.
10 Copy the ActionScript code listing into the Script pane.
11 From the main menu, choose File > Publish to update the SWF file with the changes that you’ve made.
12 Using a web browser, open the HTML page you edited to view the page and test communication between
ActionScript and the HTML page.
To test an example of ActionScript-to-ActiveX container communication:
1 Create a new document using Flash Professional and save it to your computer. You may want to save it in the folder
where your container application will expect to find the SWF file.
2 From the main menu, choose File > Publish Settings.
3 In the Publish Settings dialog box, on the Formats tab, confirm that only the Flash check box is selected.
4 In the File field next to the Flash check box, click the folder icon to select the folder into which your SWF file will
be published. By setting the location for your SWF file, you can (for example) keep the document in one folder, but
put the published SWF file in another folder such as the folder containing the source code for the container
application.
5 Select the keyframe on Frame 1 of the Timeline, and open the Actions panel.
6 Copy the ActionScript code for the example into the Script pane.
7 From the main menu, choose File > Publish to re-publish the SWF file.
8 Create and run your container application to test communication between ActionScript and the container
application.
For full examples of using the external API to communicate with an HTML page and a C# desktop application, see the
following topics:
• “External API example: Communicating between ActionScript and JavaScript in a web browser” on page 817
• “External API example: Communicating between ActionScript and a desktop application that uses the ActiveX
control” on page 823
Those examples include the full code, including ActionScript and container error-checking code, which you should
use when writing code using the external API. For another full example using the external API, see the class example
for the ExternalInterface class in the ActionScript 3.0 Reference.
Last updated 3/21/2011
812
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Using the external API
External API requirements and advantages
Flash Player 9 and later, Adobe AIR 1.0 and later
The external API is the portion of ActionScript that provides a mechanism for communication between ActionScript
and code running in an “external application” that is acting as a container for Flash Player (commonly a web browser
or stand-alone projector application). In ActionScript 3.0, the functionality of the external API is provided by the
ExternalInterface class. In Flash Player versions prior to Flash Player 8, the fscommand() action was used to carry out
communication with the container application. The ExternalInterface class is a replacement for fscommand().
Note: If you need to use the old fscommand() function—for example, to maintain compatibility with older applications
or to interact with a third-party SWF container application or the stand-alone Flash Player—it is still available as a
package-level function in the flash.system package.
The ExternalInterface class is a subsystem that lets you easily communicate from ActionScript and Flash Player to
JavaScript in an HTML page, or to any desktop application that includes an instance of Flash Player.
The ExternalInterface class is available only under the following conditions:
• In all supported versions of Internet Explorer for Windows (5.0 and later)
• In a container application such as a desktop application using an instance of the Flash Player ActiveX control
• In any browser that supports the NPRuntime interface, which currently includes Firefox 1.0 and later, Mozilla 1.7.5
and later, Netscape 8.0 and later, and Safari 1.3 and later.
In all other situations (such as running in a stand-alone player), the ExternalInterface.available property
returns false.
From ActionScript, you can call a JavaScript function on the HTML page. The external API offers the following
improved functionality compared with fscommand():
• You can use any JavaScript function, not only the functions that you can use with the fscommand() function.
• You can pass any number of arguments, with any names; you aren't limited to passing a command and a single
string argument. This gives the external API much more flexibility than fscommand().
• You can pass various data types (such as Boolean, Number, and String); you aren’t limited to String parameters.
• You can receive the value of a call, and that value returns immediately to ActionScript (as the return value of the
call you make).
Important: If the name given to the Flash Player instance in an HTML page (the object tag’s id attribute) includes a
hyphen (-) or other characters that are defined as operators in JavaScript (such as +, *, /, \, ., and so on),
ExternalInterface calls from ActionScript will not work when the container web page is viewed in Internet Explorer.In
addition, if the HTML tags that define the Flash Player instance (the object and embed tags) are nested in an HTML
form tag, ExternalInterface calls from ActionScript will not work.
Last updated 3/21/2011
813
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Using the external API
Using the ExternalInterface class
Flash Player 9 and later, Adobe AIR 1.0 and later
Communication between ActionScript and the container application can take one of two forms: either ActionScript
can call code (such as a JavaScript function) defined in the container, or code in the container can call an ActionScript
function that has been designated as being callable. In either case, information can be sent to the code being called, and
results can be returned to the code making the call.
To facilitate this communication, the ExternalInterface class includes two static properties and two static methods.
These properties and methods are used to obtain information about the external interface connection, to execute code
in the container from ActionScript, and to make ActionScript functions available to be called by the container.
Getting information about the external container
Flash Player 9 and later, Adobe AIR 1.0 and later
The ExternalInterface.available property indicates whether the current Flash Player is in a container that offers
an external interface. If the external interface is available, this property is true; otherwise, it is false. Before using any
of the other functionality in the ExternalInterface class, you should always check to make sure that the current
container supports external interface communication, as follows:
if (ExternalInterface.available)
{
// Perform ExternalInterface method calls here.
}
Note: The ExternalInterface.available property reports whether the current container is a type that supports
ExternalInterface connectivity. It doesn’t tell you if JavaScript is enabled in the current browser.
The ExternalInterface.objectID property allows you to determine the unique identifier of the Flash Player
instance (specifically, the id attribute of the object tag in Internet Explorer or the name attribute of the embed tag in
browsers using the NPRuntime interface). This unique ID represents the current SWF document in the browser, and
can be used to make reference to the SWF document—for example, when calling a JavaScript function in a container
HTML page. When the Flash Player container is not a web browser, this property is null.
Calling external code from ActionScript
Flash Player 9 and later, Adobe AIR 1.0 and later
The ExternalInterface.call() method executes code in the container application. It requires at least one
parameter, a string containing the name of the function to be called in the container application. Any additional
parameters passed to the ExternalInterface.call() method are passed along to the container as parameters of the
function call.
// calls the external function "addNumbers"
// passing two parameters, and assigning that function's result
// to the variable "result"
var param1:uint = 3;
var param2:uint = 7;
var result:uint = ExternalInterface.call("addNumbers", param1, param2);
Last updated 3/21/2011
814
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Using the external API
If the container is an HTML page, this method invokes the JavaScript function with the specified name, which must
be defined in a script element in the containing HTML page. The return value of the JavaScript function is passed
back to ActionScript.
If the container is some other ActiveX container, this method causes the Flash Player ActiveX control to dispatch its
FlashCall event. The specified function name and any parameters are serialized into an XML string by Flash Player.
The container can access that information in the request property of the event object and use it to determine how to
execute its own code. To return a value to ActionScript, the container code calls the ActiveX object’s
SetReturnValue() method, passing the result (serialized into an XML string) as a parameter of that method. For
more information about the XML format used for this communication, see “The external API’s XML format” on
page 815.
Whether the container is a web browser or another ActiveX container, if the call fails or the container method does
not specify a return value, null is returned. The ExternalInterface.call() method throws a SecurityError
exception if the containing environment belongs to a security sandbox to which the calling code does not have access.
You can work around this by setting an appropriate value for allowScriptAccess in the containing environment.
For example, to change the value of allowScriptAccess in an HTML page, you would edit the appropriate attribute
in the object and embed tags.
Calling ActionScript code from the container
Flash Player 9 and later, Adobe AIR 1.0 and later
A container can only call ActionScript code that’s in a function—no other ActionScript code can be called by a
container. To call an ActionScript function from the container application, you must do two things: register the
function with the ExternalInterface class, and then call it from the container’s code.
First, you must register your ActionScript function to indicate that it should be made available to the container. Use
the ExternalInterface.addCallback() method, as follows:
function callMe(name:String):String
{
return "busy signal";
}
ExternalInterface.addCallback("myFunction", callMe);
The addCallback() method takes two parameters. The first, a function name as a String, is the name by which the
function will be known to the container. The second parameter is the actual ActionScript function that will be executed
when the container calls the defined function name. Because these names are distinct, you can specify a function name
that will be used by the container, even if the actual ActionScript function has a different name. This is especially useful
if the function name is not known—for example, if an anonymous function is specified, or if the function to be called
is determined at run time.
Last updated 3/21/2011
815
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Using the external API
Once an ActionScript function has been registered with the ExternalInterface class, the container can actually call the
function. How this is done varies according to the type of container. For example, in JavaScript code in a web browser,
the ActionScript function is called using the registered function name as though it’s a method of the Flash Player
browser object (that is, a method of the JavaScript object representing the object or embed tag). In other words,
parameters are passed and a result is returned as though a local function is being called.
...
Alternatively, when calling an ActionScript function in a SWF file running in a desktop application, the registered
function name and any parameters must be serialized into an XML-formatted string. Then the call is actually
performed by calling the CallFunction() method of the ActiveX control with the XML string as a parameter. For
more information about the XML format used for this communication, see “The external API’s XML format” on
page 815.
In either case, the return value of the ActionScript function is passed back to the container code, either directly as a
value when the caller is JavaScript code in a browser, or serialized as an XML-formatted string when the caller is an
ActiveX container.
The external API’s XML format
Flash Player 9 and later, Adobe AIR 1.0 and later
Communication between ActionScript and an application hosting the Shockwave Flash ActiveX control uses a specific
XML format to encode function calls and values. There are two parts to the XML format used by the external API. One
format is used to represent function calls. Another format is used to represent individual values; this format is used for
parameters in functions as well as function return values. The XML format for function calls is used for calls to and
from ActionScript. For a function call from ActionScript, Flash Player passes the XML to the container; for a call from
the container, Flash Player expects the container application to pass it an XML string in this format. The following
XML fragment shows an example XML-formatted function call:
... (individual argument values)
The root node is the invoke node. It has two attributes: name indicates the name of the function to call, and
returntype is always xml. If the function call includes parameters, the invoke node has a child arguments node,
whose child nodes will be the parameter values formatted using the individual value format explained next.
Individual values, including function parameters and function return values, use a formatting scheme that includes
data type information in addition to the actual values. The following table lists ActionScript classes and the XML
format used to encode values of that data type:
Last updated 3/21/2011
816
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Using the external API
ActionScript
class/value
C# class/value
Format
null
null
Boolean true
bool true
Boolean false
bool false
String
string
string value
Number, int, uint
single, double, int, uint
27.5-12
Array (elements can be
mixed types)
A collection that allows
mixed-type elements,
such as ArrayList or
object[]
27.5Hello there!
...
The property node
defines individual
elements, and the id
attribute is the
numeric, zero-based
index.
Object
A dictionary with string
keys and object values,
such as a HashTable with
string keys
The property node
defines individual
properties, and the
id attribute is the
property name (a
string).
or
ActionScript encodes
other objects as null
or as an empty object.
In either case any
property values are
lost.
Other built-in or custom
classes
Comments
Note: By way of example, this table shows equivalent C# classes in addition to ActionScript classes; however, the external
API can be used to communicate with any programming language or run time that supports ActiveX controls, and is not
limited to C# applications.
When you are building your own applications using the external API with an ActiveX container application, you’ll
probably find it convenient to write a proxy that will perform the task of converting native function calls to the
serialized XML format. For an example of a proxy class written in C#, see “Inside the ExternalInterfaceProxy class” on
page 827.
Last updated 3/21/2011
817
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Using the external API
External API example: Communicating between
ActionScript and JavaScript in a web browser
Flash Player 9 and later, Adobe AIR 1.0 and later
This sample application demonstrates appropriate techniques for communicating between ActionScript and
JavaScript in a web browser, in the context of an Instant Messaging application that allows a person to chat with him
or herself (hence the name of the application: Introvert IM). Messages are sent between an HTML form in the web
page and a SWF interface using the external API. The techniques demonstrated by this example include the following:
• Properly initiating communication by verifying that the browser is ready to communicate before setting up
communication
• Checking whether the container supports the external API
• Calling JavaScript functions from ActionScript, passing parameters, and receiving values in response
• Making ActionScript methods available to be called by JavaScript, and performing those calls
To get the application files for this sample, see www.adobe.com/go/learn_programmingAS3samples_flash. The
Introvert IM application files can be found in the Samples/IntrovertIM_HTML folder. The application consists of the
following files:
File
Description
IntrovertIMApp.fla
The main application file for Flash (FLA) or Flex (MXML).
or
IntrovertIMApp.mxml
com/example/programmingas3/introvertIM/IMManager.as
The class that establishes and manages communication between
ActionScript and the container.
com/example/programmingas3/introvertIM/IMMessageEvent.as
Custom event type, dispatched by the IMManager class when a message
is received from the container.
com/example/programmingas3/introvertIM/IMStatus.as
Enumeration whose values represent the different “availability” status
values that can be selected in the application.
html-flash/IntrovertIMApp.html
The HTML page for the application for Flash (htmlflash/IntrovertIMApp.html) or the template that is used to create the
container HTML page for the application for Adobe Flex (htmltemplate/index.template.html). This file contains all the JavaScript
functions that make up the container part of the application.
or
html-template/index.template.html
Preparing for ActionScript-browser communication
Flash Player 9 and later, Adobe AIR 1.0 and later
One of the most common uses for the external API is to allow ActionScript applications to communicate with a web
browser. Using the external API, ActionScript methods can call code written in JavaScript and vice versa. Because of
the complexity of browsers and how they render pages internally, there is no way to guarantee that a SWF document
will register its callbacks before the first JavaScript on the HTML page runs. For that reason, before calling functions
in the SWF document from JavaScript, your SWF document should always call the HTML page to notify it that the
SWF document is ready to accept connections.
Last updated 3/21/2011
818
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Using the external API
For example, through a series of steps performed by the IMManager class, the Introvert IM determines whether the
browser is ready for communication and prepares the SWF file for communication. The first step, determining when
the browser is ready for communication, happens in the IMManager constructor, as follows:
public function IMManager(initialStatus:IMStatus)
{
_status = initialStatus;
// Check if the container is able to use the external API.
if (ExternalInterface.available)
{
try
{
// This calls the isContainerReady() method, which in turn calls
// the container to see if Flash Player has loaded and the container
// is ready to receive calls from the SWF.
var containerReady:Boolean = isContainerReady();
if (containerReady)
{
// If the container is ready, register the SWF's functions.
setupCallbacks();
}
else
{
// If the container is not ready, set up a Timer to call the
// container at 100ms intervals. Once the container responds that
// it's ready, the timer will be stopped.
var readyTimer:Timer = new Timer(100);
readyTimer.addEventListener(TimerEvent.TIMER, timerHandler);
readyTimer.start();
}
}
...
}
else
{
trace("External interface is not available for this container.");
}
}
First of all, the code checks whether the external API is even available in the current container using the
ExternalInterface.available property. If so, it begins the process of setting up communication. Because security
exceptions and other errors can occur when you attempt communication with an external application, the code is
wrapped in a try block (the corresponding catch blocks were omitted from the listing for brevity).
The code next calls the isContainerReady() method, listed here:
private function isContainerReady():Boolean
{
var result:Boolean = ExternalInterface.call("isReady");
return result;
}
The isContainerReady() method in turn uses ExternalInterface.call() method to call the JavaScript function
isReady(), as follows:
Last updated 3/21/2011
819
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Using the external API
The isReady() function simply returns the value of the jsReady variable. That variable is initially false; once the
onload event of the web page has been triggered, the variable’s value is changed to true. In other words, if
ActionScript calls the isReady() function before the page is loaded, JavaScript returns false to
ExternalInterface.call("isReady"), and consequently the ActionScript isContainerReady() method returns
false. Once the page has loaded, the JavaScript isReady() function returns true, so the ActionScript
isContainerReady() method also returns true.
Back in the IMManager constructor, one of two things happens depending on the readiness of the container. If
isContainerReady() returns true, the code simply calls the setupCallbacks() method, which completes the
process of setting up communication with JavaScript. On the other hand, if isContainerReady() returns false, the
process is essentially put on hold. A Timer object is created and is told to call the timerHandler() method every 100
milliseconds, as follows:
private function timerHandler(event:TimerEvent):void
{
// Check if the container is now ready.
var isReady:Boolean = isContainerReady();
if (isReady)
{
// If the container has become ready, we don't need to check anymore,
// so stop the timer.
Timer(event.target).stop();
// Set up the ActionScript methods that will be available to be
// called by the container.
setupCallbacks();
}
}
Each time the timerHandler() method gets called, it once again checks the result of the isContainerReady()
method. Once the container is initialized, that method returns true. The code then stops the Timer and calls the
setupCallbacks() method to finish the process of setting up communication with the browser.
Last updated 3/21/2011
820
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Using the external API
Exposing ActionScript methods to JavaScript
Flash Player 9 and later, Adobe AIR 1.0 and later
As the previous example showed, once the code determines that the browser is ready, the setupCallbacks() method
is called. This method prepares ActionScript to receive calls from JavaScript, as shown here:
private function setupCallbacks():void
{
// Register the SWF client functions with the container
ExternalInterface.addCallback("newMessage", newMessage);
ExternalInterface.addCallback("getStatus", getStatus);
// Notify the container that the SWF is ready to be called.
ExternalInterface.call("setSWFIsReady");
}
The setCallBacks() method finishes the task of preparing for communication with the container by calling
ExternalInterface.addCallback() to register the two methods that will be available to be called from JavaScript.
In this code, the first parameter—the name by which the method is known to JavaScript ("newMessage" and
"getStatus")—is the same as the method’s name in ActionScript. (In this case, there was no benefit to using different
names, so the same name was reused for simplicity.) Finally, the ExternalInterface.call() method is used to call
the JavaScript function setSWFIsReady(), which notifies the container that the ActionScript functions have been
registered.
Communication from ActionScript to the browser
Flash Player 9 and later, Adobe AIR 1.0 and later
The Introvert IM application demonstrates a range of examples of calling JavaScript functions in the container page.
In the simplest case (an example from the setupCallbacks() method), the JavaScript function setSWFIsReady() is
called without passing any parameters or receiving a value in return:
ExternalInterface.call("setSWFIsReady");
In another example from the isContainerReady() method, ActionScript calls the isReady() function and receives
a Boolean value in response:
var result:Boolean = ExternalInterface.call("isReady");
You can also pass parameters to JavaScript functions using the external API. For instance, consider the IMManager
class’s sendMessage() method, which is called when the user is sending a new message to his or her “conversation
partner”:
public function sendMessage(message:String):void
{
ExternalInterface.call("newMessage", message);
}
Once again, ExternalInterface.call() is used to call the designated JavaScript function, notifying the browser of
the new message. In addition, the message itself is passed as an additional parameter to ExternalInterface.call(),
and consequently it is passed as a parameter to the JavaScript function newMessage().
Last updated 3/21/2011
821
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Using the external API
Calling ActionScript code from JavaScript
Flash Player 9 and later, Adobe AIR 1.0 and later
Communication is supposed to be a two-way street, and the Introvert IM application is no exception. Not only does
the Flash Player IM client call JavaScript to send messages, but the HTML form calls JavaScript code to send messages
to and ask for information from the SWF file as well. For example, when the SWF file notifies the container that it has
finished establishing contact and it’s ready to communicate, the first thing the browser does is call the IMManager
class’s getStatus() method to retrieve the initial user availability status from the SWF IM client. This is done in the
web page, in the updateStatus() function, as follows:
The code checks the value of the swfReady variable, which tracks whether the SWF file has notified the browser that
it has registered its methods with the ExternalInterface class. If the SWF file is ready to receive communication, the
next line (var currentStatus = ...) actually calls the getStatus() method in the IMManager class. Three things
happen in this line of code:
• The getSWF() JavaScript function is called, returning a reference to the JavaScript object representing the SWF file.
The parameter passed to getSWF() determines which browser object is returned in case there is more than one
SWF file in an HTML page. The value passed to that parameter must match the id attribute of the object tag and
name attribute of the embed tag used to include the SWF file.
• Using the reference to the SWF file, the getStatus() method is called as though it’s a method of the SWF object.
In this case the function name “ getStatus” is used because that’s the name under which the ActionScript function
is registered using ExternalInterface.addCallback().
• The getStatus() ActionScript method returns a value, and that value is assigned to the currentStatus variable,
which is then assigned as the content (the value property) of the status text field.
Note: If you’re following along in the code, you’ve probably noticed that in the source code for the updateStatus()
function, the line of code that calls the getSWF() function, is actually written as follows: var currentStatus =
getSWF("${application}").getStatus(); The ${application} text is a placeholder in the HTML page template; when
Adobe Flash Builder generates the actual HTML page for the application, this placeholder text is replaced by the same
text that is used as the object tag’s id attribute and the embed tag’s name attribute (IntrovertIMApp in the example).
That is the value that is expected by the getSWF() function.
The sendMessage() JavaScript function demonstrates passing a parameter to an ActionScript function.
(sendMessage() is thefunction that is called when the user presses the Send button on the HTML page.)
Last updated 3/21/2011
822
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Using the external API
The newMessage() ActionScript method expects one parameter, so the JavaScript message variable gets passed to
ActionScript by using it as a parameter in the newMessage() method call in the JavaScript code.
Detecting the browser type
Flash Player 9 and later, Adobe AIR 1.0 and later
Because of differences in how browsers access content, it’s important to always use JavaScript to detect which browser
the user is running and to access the movie according to the browser-specific syntax, using the window or document
object, as shown in the getSWF() JavaScript function in this example:
If your script does not detect the user’s browser type, the user might see unexpected behavior when playing SWF files
in an HTML container.
Last updated 3/21/2011
823
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Using the external API
External API example: Communicating between
ActionScript and a desktop application that uses the
ActiveX control
Flash Player 9 and later
This example demonstrates using the external API to communicate between ActionScript and a desktop application
that uses the ActiveX control. The example reuses the Introvert IM application, including the ActionScript code and
even the same SWF file, and therefore does not describe the use of the external API in ActionScript. Familiarity with
the preceding example will be helpful in understanding this one.
The desktop application in this example is written in C# using Microsoft Visual Studio .NET. The focus of the
discussion is the specific techniques for working with the external API using the ActiveX control. This example
demonstrates the following:
• Calling ActionScript functions from a desktop application hosting the Flash Player ActiveX control
• Receiving function calls from ActionScript and processing them in an ActiveX container
• Using a proxy class to hide the details of the serialized XML format that Flash Player uses for messages sent to an
ActiveX container
To get the application files for this sample, see www.adobe.com/go/learn_programmingAS3samples_flash. The
Introvert IM C# files can be found in the Samples/IntrovertIM_CSharp folder. The application consists of the
following files:
File
Description
AppForm.cs
The main application file with the C# Windows Forms interface.
bin/Debug/IntrovertIMApp.swf
The SWF file loaded by the application.
ExternalInterfaceProxy/ExternalInterfaceProxy.cs
The class that serves as a wrapper around the ActiveX control for External Interface
communication. It provides mechanisms for calling and receiving calls from
ActionScript.
ExternalInterfaceProxy/ExternalInterfaceSerializer.cs
The class that performs the task of converting Flash Player’s XML format messages
to .NET objects.
ExternalInterfaceProxy/ExternalInterfaceEventArgs.cs
This file defines two C# types (classes): a custom delegate, and an event arguments
class, which are used by the ExternalInterfaceProxy class to notify a listener of a
function call from ActionScript.
ExternalInterfaceProxy/ExternalInterfaceCall.cs
This class is a value object representing a function call from ActionScript to the
ActiveX container, with properties for the function name and parameters.
bin/Debug/IntrovertIMApp.swf
The SWF file loaded by the application.
obj/AxInterop.ShockwaveFlashObjects.dll,
Wrapper assemblies created by Visual Studio .NET that are required to access the
Flash Player (Adobe Shockwave® Flash) ActiveX control from managed code.
obj/Interop.ShockwaveFlashObjects.dll
Last updated 3/21/2011
824
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Using the external API
Overview of the Introvert IM C# Application
Flash Player 9 and later
This sample application represents two instant-messaging client programs (one within a SWF file and another built
with Windows Forms) that communicate with each other. The user interface includes an instance of the Shockwave
Flash ActiveX control, within which the SWF file containing the ActionScript IM client is loaded. The interface also
includes several text fields that make up the Windows Forms IM client: a field for entering messages (MessageText),
another that displays the transcript of the messages sent between the clients (Transcript), and a third (Status) that
displays the availability status as set in the SWF IM client.
Including the Shockwave Flash ActiveX control
Flash Player 9 and later
To include the Shockwave Flash ActiveX control in your own Windows Forms application, you must first add it to the
Microsoft Visual Studio Toolbox.
To add the control to the toolbox:
1 Open the Visual Studio Toolbox.
2 Right-click the Windows Forms section in Visual Studio 2003 or any section in Visual Studio 2005. From the
context menu select Add/Remove Items in Visual Studio 2003 (Choose Items... in Visual Studio 2005).
This opens the Customize Toolbox (2003)/Choose Toolbox Items (2005) dialog box.
3 Select the COM Components tab, which lists all of the available COM components on your computer, including
the Flash Player ActiveX control.
4 Scroll to Shockwave Flash Object and select it.
If this item is not listed, make sure that the Flash Player ActiveX control is installed on your system.
Understanding ActionScript to ActiveX container communication
Flash Player 9 and later
Communication using the external API with an ActiveX container application works like communication with a web
browser, with one important difference. As described earlier, when ActionScript communicates with a web browser,
as far as the developer is concerned, the functions are called directly; the details of how the function calls and responses
are formatted to pass them between the player and browser are hidden. However, when the external API is used to
communicate with an ActiveX container application, Flash Player sends messages (function calls and return values) to
the application in a specific XML format, and it expects function calls and return values from the container application
to use the same XML format. The developer of the ActiveX container application must write code that understands
and can create function calls and responses in the appropriate format.
The Introvert IM C# example includes a set of classes that allow you to avoid formatting messages; instead, you can
work with standard data types when calling ActionScript functions and receiving function calls from ActionScript. The
ExternalInterfaceProxy class, together with other helper classes, provides this functionality, and can be reused in any
.NET project to facilitate external API communication.
The following sections of code, excerpted from the main application form (AppForm.cs), demonstrate the simplified
interaction that is achieved by using the ExternalInterfaceProxy class:
Last updated 3/21/2011
825
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Using the external API
public class AppForm : System.Windows.Forms.Form
{
...
private ExternalInterfaceProxy proxy;
...
public AppForm()
{
...
// Register this app to receive notification when the proxy receives
// a call from ActionScript.
proxy = new ExternalInterfaceProxy(IntrovertIMApp);
proxy.ExternalInterfaceCall += new
ExternalInterfaceCallEventHandler(proxy_ExternalInterfaceCall);
...
}
...
The application declares and creates an ExternalInterfaceProxy instance named proxy, passing in a reference to the
Shockwave Flash ActiveX control that is in the user interface (IntrovertIMApp). Next, the code registers the
proxy_ExternalInterfaceCall() method to receive the proxy’s ExternalInterfaceCall event. This event is
dispatched by the ExternalInterfaceProxy class when a function call comes from Flash Player. Subscribing to this event
is the way the C# code receives and responds to function calls from ActionScript.
When a function call comes from ActionScript, the ExternalInterfaceProxy instance (proxy) receives the call, converts
it from XML format, and notifies the objects that are listeners for the proxy’s ExternalInterfaceCall event. In the
case of the AppForm class, the proxy_ExternalInterfaceCall() method handles that event, as follows:
///
/// Called by the proxy when an ActionScript ExternalInterface call
/// is made by the SWF
///
private object proxy_ExternalInterfaceCall(object sender, ExternalInterfaceCallEventArgs e)
{
switch (e.FunctionCall.FunctionName)
{
case "isReady":
return isReady();
case "setSWFIsReady":
setSWFIsReady();
return null;
case "newMessage":
newMessage((string)e.FunctionCall.Arguments[0]);
return null;
case "statusChange":
statusChange();
return null;
default:
return null;
}
}
...
The method gets passed an ExternalInterfaceCallEventArgs instance, named e in this example. That object, in turn,
has a FunctionCall property that is an instance of the ExternalInterfaceCall class.
Last updated 3/21/2011
826
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Using the external API
An ExternalInterfaceCall instance is a simple value object with two properties. The FunctionName property contains
the function name specified in the ActionScript ExternalInterface.Call() statement. If any parameters are added
in ActionScript, those parameters are included in the ExternalInterfaceCall object’s Arguments property. In this case,
the method that handles the event is simply a switch statement that acts like a traffic manager. The value of the
FunctionName property (e.FunctionCall.FunctionName) determines which method of the AppForm class is
called.
The branches of the switch statement in the previous code listing demonstrate common method call scenarios. For
instance, any method must return a value to ActionScript (for example, the isReady() method call) or else should
return null (as seen in the other method calls). Accessing parameters passed from ActionScript is demonstrated in
the newMessage() method call (which passes along a parameter e.FunctionCall.Arguments[0], the first element
of the Arguments array).
Calling an ActionScript function from C# using the ExternalInterfaceProxy class is even more straightforward than
receiving a function call from ActionScript. To call an ActionScript function, you use the ExternalInterfaceProxy
instance’s Call() method, as follows:
///
/// Called when the "Send" button is pressed; the value in the
/// MessageText text field is passed in as a parameter.
///
/// The message to send.
private void sendMessage(string message)
{
if (swfReady)
{
...
// Call the newMessage function in ActionScript.
proxy.Call("newMessage", message);
}
}
...
///
/// Call the ActionScript function to get the current "availability"
/// status and write it into the text field.
///
private void updateStatus()
{
Status.Text = (string)proxy.Call("getStatus");
}
...
}
As this example shows, the ExternalInterfaceProxy class’s Call() method is very similar to its ActionScript
counterpart, ExternalInterface.Call(). The first parameter is a string, the name of the function to call. Any
additional parameters (not shown here) are passed along to the ActionScript function. If the ActionScript function
returns a value, that value is returned by the Call() method (as seen in the previous example).
Last updated 3/21/2011
827
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Using the external API
Inside the ExternalInterfaceProxy class
Flash Player 9 and later
Using a proxy wrapper around the ActiveX control may not always be practical, or you may wish to write your own
proxy class (for instance, in a different programming language or targeting a different platform). Although not all the
details of creating a proxy will be explained here, it is instructive to understand the inner workings of the proxy class
in this example.
You use the Shockwave Flash ActiveX control’s CallFunction() method to call an ActionScript function from the
ActiveX container using the external API. This is shown in this extract from the ExternalInterfaceProxy class’s Call()
method:
// Call an ActionScript function on the SWF in "_flashControl",
// which is a Shockwave Flash ActiveX control.
string response = _flashControl.CallFunction(request);
In this code excerpt, _flashControl is the Shockwave Flash ActiveX control. ActionScript function calls are made
using the CallFunction() method. That method takes one parameter (request in the example), which is a string
containing XML-formatted instructions including the name of the ActionScript function to call and any parameters.
Any value returned from ActionScript is encoded as an XML-formatted string and sent back as the return value of the
CallFunction() call. In this example, that XML string is stored in the response variable.
Receiving a function call from ActionScript is a multistep process. Function calls from ActionScript cause the
Shockwave Flash ActiveX control to dispatch its FlashCall event, so a class (such as the ExternalInterfaceProxy class)
that intends to receive calls from a SWF file needs to define a handler for that event. In the ExternalInterfaceProxy
class, the event handler function is named _flashControl_FlashCall(), and it is registered to listen for the event in
the class constructor, as follows:
private AxShockwaveFlash _flashControl;
public ExternalInterfaceProxy(AxShockwaveFlash flashControl)
{
_flashControl = flashControl;
_flashControl.FlashCall += new
_IShockwaveFlashEvents_FlashCallEventHandler(_flashControl_FlashCall);
}
...
private void _flashControl_FlashCall(object sender, _IShockwaveFlashEvents_FlashCallEvent e)
{
// Use the event object's request property ("e.request")
// to execute some action.
...
// Return a value to ActionScript;
// the returned value must first be encoded as an XML-formatted string.
_flashControl.SetReturnValue(encodedResponse);
}
The event object (e) has a request property (e.request) that is a string containing information about the function
call, such as the function name and parameters, in XML format. This information can be used by the container to
determine what code to execute. In the ExternalInterfaceProxy class, the request is converted from XML format to an
ExternalInterfaceCall object, which provides the same information in a more accessible form. The ActiveX control’s
SetReturnValue() method is used to return a function result to the ActionScript caller; once again, the result
parameter must be encoded in the XML format used by the external API.
Last updated 3/21/2011
828
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Using the external API
Communication between ActionScript and an application hosting the Shockwave Flash ActiveX control uses a specific
XML format to encode function calls and values. In the Introvert IM C# example, the ExternalInterfaceProxy class
makes it possible for the code in the application form to operate directly on values sent to or received from
ActionScript, and ignore the details of the XML format used by Flash Player. In order to accomplish this, the
ExternalInterfaceProxy class uses the methods of the ExternalInterfaceSerializer class to actually translate the XML
messages into .NET objects. The ExternalInterfaceSerializer class has four public methods:
•
EncodeInvoke(): Encodes a function name and a C# ArrayList of arguments into the appropriate XML format.
•
EncodeResult(): Encodes a result value into the appropriate XML format.
•
DecodeInvoke(): Decodes a function call from ActionScript. The FlashCall event object’s request property is
passed to the DecodeInvoke() method, and it translates the call into an ExternalInterfaceCall object.
•
DecodeResult(): Decodes the XML received as the result of calling an ActionScript function.
These methods encode C# values into the external API’s XML format and decode the XML into C# objects. For details
on the XML format used by Flash Player, see “The external API’s XML format” on page 815.
Last updated 3/21/2011
829
Chapter 46: XML signature validation in
AIR
Adobe AIR 1.5 and later
Use the classes in the Adobe® AIR® XMLSignatureValidator API to validate digital signatures conforming to a subset
of the W3C recommendation for XML-Signature Syntax and Processing (http://http://www.w3.org/TR/xmldsigcore/). XML signatures can be used to help verify the integrity and signer identity of data or information.
XML signatures can be used to validate messages or resources downloaded by your application. For example, if your
application provides services on a subscription basis, you could encapsulate the subscription terms in a signed XML
document. If someone attempted to alter the subscription document, validation would fail.
You could also use an XML signature to help validate downloaded resources used by your application by including a
signed manifest containing digests of those resources. Your application could verify that the resources have not been
altered by comparing the digest in the signed file with a digest computed from the loaded bytes. This is particularly
valuable when the downloaded resource is a SWF file or other active content that you want to run in the application
security sandbox.
Basics of XML signature validation
Adobe AIR 1.5 and later
For a quick explanation and code examples of validating XML signatures, see the following quick start articles on the
Adobe Developer Connection:
• Creating and validating XML signatures (Flex)
• Creating and validating XML signatures (Flash)
Adobe® AIR® provides the XMLSignatureValidator class and IURIDereferencer interface for validating XML
signatures. The XML syntax accepted by the XMLSignatureValidator class is a subset of the W3C recommendation for
XML Signature Syntax and Processing. (Because only a subset of the recommendation is supported, not all legal
signatures can be validated.) AIR does not provide an API for creating XML signatures.
XML signature validation classes
Adobe AIR 1.5 and later
The XML signature validation API includes the following classes:
Last updated 3/21/2011
830
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
XML signature validation in AIR
Package
Classes
flash.security
•
XMLSignatureValidator
•
IURIDereferencer (interface)
XMLSignatureValidator string constants are defined in the following classes:
flash.events
•
ReferencesValidationSetting
•
RevocationCheckSettings
•
SignatureStatus
•
SignerTrustSettings
•
Event
•
ErrorEvent
Using the XML signature validation classes
Adobe AIR 1.5 and later
To use the XMLSignatureValidator class to validate an XML signature, you must:
• Create an XMLSignatureValidator object
• Provide an implementation of the IURIDereferencer interface. The XMLSignatureValidator object calls the
IURIDereferencer dereference() method, passing in the URI for each reference in a signature. The
dereference() method must resolve the URI and return the referenced data (which could be in the same
document as the signature, or could be in an external resource).
• Set the certificate trust, revocation checking, and reference validation settings of the XMLSignatureValidator object
as appropriate for your application.
• Add event listeners for the complete and error events.
• Call the verify() method, passing in the signature to validate.
• Handle the complete and error events and interpret the results.
The following example implements a validate() function that verifies the validity of an XML signature. The
XMLSignatureValidator properties are set such that the signing certificate must be in the system trust store, or chain
to a certificate in the trust store. The example also assumes that a suitable IURIDereferencer class named
XMLDereferencer exists.
Last updated 3/21/2011
831
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
XML signature validation in AIR
private function validate( xmlSignature:XML ):void
{
var verifier:XMLSignatureValidator = new XMLSignatureValidator();
verifier.addEventListener(Event.COMPLETE, verificationComplete);
verifier.addEventListener(ErrorEvent.ERROR, verificationError);
try
{
verifier.uriDereferencer = new XMLDereferencer();
verifier.referencesValidationSetting =
ReferencesValidationSetting.VALID_IDENTITY;
verifier.revocationCheckSetting = RevocationCheckSettings.BEST_EFFORT;
verifier.useSystemTrustStore = true;
//Verify the signature
verifier.verify( xmlSignature );
}
catch (e:Error)
{
trace("Verification error.\n" + e);
}
}
//Trace verification results
private function verificationComplete(event:Event):void
var signature:XMLSignatureValidator = event.target as XMLSignatureValidator;
trace("Signature status: " + signature.validityStatus + "\n");
trace(" Digest status: " + signature.digestStatus + "\n");
trace(" Identity status: " + signature.identityStatus + "\n");
trace(" Reference status: " + signature.referencesStatus + "\n");
}
private function verificationError(event:ErrorEvent):void
{
trace("Verification error.\n" + event.text);
}
The XML signature validation process
Adobe AIR 1.5 and later
When you call the XMLSignatureValidator verify() method, AIR performs the following steps:
• The runtime verifies the cryptographic integrity of the signature using the public key of the signing certificate.
• The runtime establishes the cryptographic integrity, identity, and trustworthiness of the certificate based on the
current settings of the XMLSignatureValidator object.
The trust placed in the signing certificate is key to the integrity of the validation process. Signature validation is
conducted using a well-defined cryptographic process, but the trustworthiness of the signing certificate is a
judgment that cannot be made algorithmically.
In general, you have three ways to decide whether a certificate is trustworthy:
• By relying on certification authorities and the operating system trust store.
Last updated 3/21/2011
832
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
XML signature validation in AIR
• By obtaining, directly from the signer, a copy of the certificate, another certificate that serves as a trust anchor
for the certificate, or sufficient information to reliably identify the certificate, such as the public key.
• Asking the end user of your application if they trust the certificate. Such a query is invalid with self-signed
certificates since the identifying information in the certificate is inherently unreliable.
• The runtime verifies the cryptographic integrity of the signed data.
The signed data is verified with the help of your IURIDereferencer implementation. For each reference in the
signature document, the IURIDereferencer implementation dereference() method is called. The data returned
by the dereference() method is used to compute the reference digest. This digest value is compared to the digest
recorded in the signature document. If the digests match, then the data has not been altered since it was signed.
One important consideration when relying on the results of validating an XML signature is that only what is signed
is secure. For example, consider a signed manifest listing the files in a package. When the XMLSignatureValidator
verifies the signature, it only checks whether the manifest itself is unaltered. The data in the files is not signed, so
the signature will still validate when files referenced in the manifest are changed or deleted.
Note: To verify files in such a manifest, you can compute the digest of the file data (using the same hashing algorithm
used in the manifest) and compare the result to the digest stored in the signed manifest. In some cases, you should also
check for the presence of additional files.
Interpreting validation results
Adobe AIR 1.5 and later
The validation results are reported by the status properties of the XMLSignatureValidator object. These properties can
be read after the validator object dispatches the complete event. The four status properties include: validityStatus,
digestStatus, identityStatus, and referencesStatus.
The validityStatus property
Adobe AIR 1.5 and later
The validityStatus property reports the overall validity of the signature. The validityStatus depends on the state
of the other three status properties and can have one of the following values:
•
valid — If digestStatus, identityStatus, and referencesStatus are all valid.
•
invalid — If one or more of the individual status properties is invalid.
•
unknown — If one or more of the individual status properties is unknown and no individual status is invalid.
The digestStatus property
Adobe AIR 1.5 and later
The digestStatus property reports the results of the cryptographic verification of the message digest. The
digestStatus property can have one of the following values:
•
valid — If the signature document itself is unaltered since signing.
•
invalid — If the signature document has been altered or is malformed.
•
unknown — If the verify() method has not completed without error.
Last updated 3/21/2011
833
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
XML signature validation in AIR
The identityStatus property
Adobe AIR 1.5 and later
The identityStatus property reports the status of the signing certificate. The value of this property depends on
several factors including:
• the cryptographic integrity of the certificate
• whether the certificate is expired or revoked
• whether the certificate is trusted on the current machine
• the state of the XMLSignatureValidator object (such as whether additional certificates have been added for building
the trust chain, whether those certificates are trusted, and the values of the useSystemTrustStore and
revocationCheckSettings properties)
The identityStatus property can have the following values:
•
valid — To be considered valid, the signing certificate must meet the following conditions:
• The signing certificate must be unaltered.
• The signing certificate must not be expired or revoked—except when a valid timestamp is present in the
signature. If the signature is timestamped, the certificate will be considered valid as long as it was valid at the
time the document was signed. (The certificate used by the timestamp service to sign the timestamp must chain
to a trusted root certificate on the user’s computer.)
• The signing certificate is trusted. A certificate is trusted if the certificate is in the system trust store or chains to
another certificate in the system trust store and you set the useSystemTrustStore property to true. You can
also designate a certificate as trusted using the addCertificate() method of the XMLSignatureValidator
object.
• The certificate is, in fact, the signing certificate.
•
invalid — The certificate is expired or revoked—and no timestamp proving validity at the time of signing is
present—or the certificate has been altered.
•
unknown — If the certificate is not invalid, but is not trusted either. Self-signed certificates, for example, will be
reported as unknown (unless explicitly trusted). The identityStatus is also reported as unknown if the verify()
method has not completed without error or if the identity has not been checked because the signature digest is
invalid.
The referencesStatus property
Adobe AIR 1.5 and later
The referencesStatus property reports the cryptographic integrity of the references in the SignedData element of
the signature.
•
valid — If the computed digest of every reference in the signature matches the corresponding digest recorded in
the XML signature. A valid status indicates that the signed data has not been altered.
•
invalid — If any computed digest does not match the corresponding digest in the signature.
•
unknown — If the reference digests have not been checked. The references are not checked if the overall signature
digest is invalid or the signing certificate is invalid. If the identityStatus is unknown, then the references are
only checked when the referencesValidationSetting is validOrUnknown.
Last updated 3/21/2011
834
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
XML signature validation in AIR
About XML signatures
Adobe AIR 1.5 and later
An XML signature is a digital signature represented in XML syntax. The data in an XML signature can be used to
validate that the signed information has not been altered since signing. In addition, when a signing certificate has been
issued by a trusted certification authority, the identity of the signer can be verified through the public key
infrastructure.
An XML signature can be applied to any type of digital data (in binary or XML format). XML signatures are typically
used for such purposes as:
• checking whether external or downloaded resources have been modified
• verifying that messages come from a known source
• validating application license or subscription privileges
Supported XML signature syntax
Adobe AIR 1.5 and later
AIR supports the following elements from the W3C recommendation for XML Signature Syntax and Processing:
• All core signature syntax elements (section 4 of the W3C recommendation document)—except the KeyInfo
element is not fully supported
• The KeyInfo element must only contain an X509Data element
• An X509Data element must only contain an X509Certificate element
• The SHA256 digest method
• The RSA-SHA1 (PKCS1) signing algorithm
• The "Canonical XML without comments" canonicalization method and transform
• The enveloped signature transform
• timestamps
The following document illustrates a typical XML signature (most of the cryptographic data has been removed to
simplify the example):
Last updated 3/21/2011
835
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
XML signature validation in AIR
uoo...vY=Ked...w==i7d...w==
The key elements of a signature are:
• SignedInfo — Contains references to the signed data and the computed digest values at the time of signing. The
signed data itself may be included in the same document as the XML signature or may be external.
• SignatureValue — Contains a digest of the SignedInfo element encrypted with the signer’s private key.
• KeyInfo — Contains the signing certificate, as well as any additional certificates needed to establish the chain of
trust. Note that although the KeyInfo element is technically optional, AIR cannot validate the signature if it is not
included.
There are three general types of XML signatures:
• Enveloped — the signature is inserted inside the XML data that it is signing.
• Enveloping — the signed XML data is contained within an Object element within the Signature element.
• Detached — the signed data is external to the XML signature. The signed data might be in an external file.
Alternately, it might be in the same XML document as the signature, just not a parent or child element of the
Signature element.
XML signatures use URIs to reference the signed data. The signing and the validating applications must use the same
conventions for resolving these URIs. When using the XMLSignatureValidator class, you must provide an
implementation of the IURIDereferencer interface. This implementation is responsible for resolving the URI and
returning the signed data as a ByteArray object. The returned ByteArray object is digested using the same algorithm
that produced the digest in the signature.
Certificates and trust
Adobe AIR 1.5 and later
A certificate consists of a public key, identifying information, and possibly one or more certificates belonging to the
issuing certification authority.
There are two ways to establish trust in a certificate. You can establish trust by obtaining a copy of the certificate
directly from the signer, for example on physical media, or through a secure digital transmission such as an SSL
transaction. You can also rely on a certification authority to determine whether the signing certificate is trustworthy.
Last updated 3/21/2011
836
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
XML signature validation in AIR
To rely on a certification authority, the signing certificate must be issued by an authority that is trusted on the
computer upon which the signature is validated. Most operating system manufacturers place the root certificates of a
number of certification authorities into the operating system trust store. Users can also add and remove certificates
from the store.
Even if a certificate is issued by a trusted certification authority, you must still decide whether the certificate belongs
to someone you trust. In many use cases, this decision is passed along to the end-user. For example, when an AIR
application is installed, the AIR installer displays the identifying information from the publisher’s certificate when
asking the user to verify whether they want to install the application. In other cases, you might have to compare the
public key or other certificate information to a list of acceptable keys. (This list must be secured, perhaps by its own
signature, or by storing in the AIR encrypted local store, so that the list itself cannot be tampered with.)
Note: While you can elect to trust the signing certificate without independent verification—such as when a signature is
“self-signed”—you do not thereby gain much assurance of anything by verifying the signature. Without knowing who
created a signature, the assurance that the signature has not been tampered with, is of little, if any, value. The signature
could be a validly signed forgery.
Certificate expiration and revocation
Adobe AIR 1.5 and later
All certificates expire. Certificates can also be revoked by the issuing certification authority if, for example, the private
key related to the certificate is compromised or stolen. If a signature is signed with an expired or revoked certificate,
then the signature will be reported as invalid unless a timestamp has been included as part of the signature. If a
timestamp is present, then the XMLSignatureValidator class will validate the signature as long as the certificate was
valid at the time of signing.
A timestamp is a signed digital message from a timestamp service that certifies that the data was signed at a particular
time and date. Timestamps are issued by timestamp authorities and signed by the timestamp authority’s own
certificate. The timestamp authority certificate embedded in the timestamp must be trusted on the current machine
for the timestamp to be considered valid. The XMLSignatureValidator does not provide an API for designating a
different certificate to use in validating the timestamp.
Implementing the IURIDereferencer interface
Adobe AIR 1.5 and later
To validate an XML signature, you must provide an implementation of the IURIDereferencer interface. The
implementation is responsible for resolving the URIs within the Reference elements of an XML signature document
and returning the data so that the digest can be computed. The computed digest is compared with the digest in the
signature to determine if the referenced data has been altered since the signature was created.
Note: HTML-based AIR applications must import a SWF library containing an ActionScript implementation in order to
validate XML signatures. The IURIDereferencer interface cannot be implemented in JavaScript.
The IURIDerefencer interface has a single method, dereference(uri:String), that must be implemented. The
XMLSignatureValidator object calls this method for each reference in the signature. The method must return the data
in a ByteArray object.
Last updated 3/21/2011
837
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
XML signature validation in AIR
In most cases, you will also need to add properties or methods that allow your dereferencer object to locate the
referenced data. For example, if the signed data is located in the same document as the signature, you could add a
member variable that provides a reference to the XML document. The dereference() method can then use this
variable, along with the URI, to locate the referenced data. Likewise, if the signed data is located in a directory of the
local file system, the dereference() method might need a property providing the path to that directory in order to
resolve the referenced files.
The XMLSignatureValidator relies entirely on the dereferencer for interpreting URI strings. The standard rules for
dereferencing URIs are given in the section 4.3.3 of the W3C Recommendation for XML Signature Syntax and
Processing.
Dereferencing URIs in enveloped signatures
Adobe AIR 1.5 and later
When an enveloped XML signature is generated, the signature elements are inserted into the signed data. For example,
if you signed the following message using an enveloped signature structure:
...
The resulting signed document will look like this:
...
yv6...Z0Y=cCY...LQ==MII...4e
Notice that the signature contains a single Reference element with an empty string as its URI. An empty string in this
context refers to the root of the document.
Also notice that the transform algorithm specifies that an enveloped signature transform has been applied. When an
enveloped signature transform has been applied, the XMLSignatureValidator automatically removes the signature
from the document before computing the digest. This means that the dereferencer does not need to remove the
Signature element when returning the data.
Last updated 3/21/2011
838
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
XML signature validation in AIR
The following example illustrates a dereferencer for enveloped signatures:
package
{
import
import
import
import
import
flash.events.ErrorEvent;
flash.events.EventDispatcher;
flash.security.IURIDereferencer;
flash.utils.ByteArray;
flash.utils.IDataInput;
public class EnvelopedDereferencer
extends EventDispatcher implements IURIDereferencer
{
private var signedMessage:XML;
public function EnvelopedDereferencer( signedMessage:XML )
{
this.signedMessage = signedMessage;
}
public function dereference( uri:String ):IDataInput
{
try
{
if( uri.length != 0 )
{
throw( new Error("Unsupported signature type.") );
}
var data:ByteArray = new ByteArray();
data.writeUTFBytes( signedMessage.toXMLString() );
data.position = 0;
}
catch (e:Error)
{
var error:ErrorEvent =
new ErrorEvent("Ref error " + uri + " ", false, false, e.message);
this.dispatchEvent(error);
data = null;
throw new Error("Reference not resolvable: " + uri + ", " + e.message);
}
finally
{
return data;
}
}
}
}
This dereferencer class uses a constructor function with a parameter, signedMessage, to make the enveloped
signature document available to the dereference() method. Since the reference in an enveloped signature always
refers to the root of the signed data, the dereferencer() method writes the document into a byte array and returns it.
Last updated 3/21/2011
839
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
XML signature validation in AIR
Dereferencing URIs in enveloping and detached signatures
Adobe AIR 1.5 and later
When the signed data is located in the same document as the signature itself, the URIs in the references typically use
XPath or XPointer syntax to address the elements that are signed. The W3C Recommendation for XML Signature
Syntax and Processing only recommends this syntax, so you should base your implementation on the signatures you
expect to encounter (and add sufficient error checking to gracefully handle unsupported syntax).
The signature of an AIR application is an example of an enveloping signature. The files in the application are listed in
a Manifest element. The Manifest element is addressed in the Reference URI attribute using the string,
“#PackageContents”, which refers to the Id of the Manifest element:
ZMGqQdaRKQc1HirIRsDpeBDlaElS+pPotdziIAyAYDk=cQK...7Zg==MII...T4e
A dereferencer for validating this signature must take the URI string containing, "#PackageContents" from the
Reference element, and return the Manifest element in a ByteArray object. The “#” symbol refers to the value of an
element Id attribute.
Last updated 3/21/2011
840
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
XML signature validation in AIR
The following example implements a dereferencer for validating AIR application signatures. The implementation is
kept simple by relying on the known structure of an AIR signature. A general-purpose dereferencer could be
significantly more complex.
package
{
import
import
import
import
flash.events.ErrorEvent;
flash.security.IURIDereferencer;
flash.utils.ByteArray;
flash.utils.IDataInput;
public class AIRSignatureDereferencer implements IURIDereferencer {
private const XML_SIG_NS:Namespace =
new Namespace( "http://www.w3.org/2000/09/xmldsig#" );
private var airSignature:XML;
public function AIRSignatureDereferencer( airSignature:XML ) {
this.airSignature = airSignature;
}
public function dereference( uri:String ):IDataInput {
var data:ByteArray = null;
try
{
if( uri != "#PackageContents" )
{
throw( new Error("Unsupported signature type.") );
}
var manifest:XMLList =
airSignature.XML_SIG_NS::Object.XML_SIG_NS::Manifest;
data = new ByteArray();
data.writeUTFBytes( manifest.toXMLString());
data.position = 0;
}
catch (e:Error)
{
data = null;
throw new Error("Reference not resolvable: " + uri + ", " + e.message);
}
finally
{
return data;
}
}
}
}
When you verify this type of signature, only the data in the Manifest element is validated. The actual files in the package
are not checked at all. To check the package files for tampering, you must read the files, compute the SHA256 digest
and compare the result to digest recorded in the manifest. The XMLSignatureValidator does not automatically check
such secondary references.
Note: This example is provided only to illustrate the signature validation process. There is little use in an AIR application
validating its own signature. If the application has already been tampered with, the tampering agent could simply remove
the validation check.
Last updated 3/21/2011
841
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
XML signature validation in AIR
Computing digest values for external resources
Adobe AIR 1.5 and later
AIR does not include built-in functions for computing SHA256 digests, but the Flex SDK does include a SHA256
utility class. The SDK also includes the Base64 encoder utility class that is helpful for comparing the computed digest
to the digest stored in a signature.
The following example function reads and validates the files in an AIR package manifest:
import mx.utils.Base64Encoder;
import mx.utils.SHA256;
private
{
var
var
var
function verifyManifest( sigFile:File, manifest:XML ):Boolean
result:Boolean = true;
message:String = '';
nameSpace:Namespace = manifest.namespace();
if( manifest.nameSpace::Reference.length() <= 0 )
{
result = false;
message = "Nothing to validate.";
}
for each (var reference:XML in manifest.nameSpace::Reference)
{
var file:File = sigFile.parent.parent.resolvePath( reference.@URI );
var stream:FileStream = new FileStream();
stream.open(file, FileMode.READ);
var fileData:ByteArray = new ByteArray();
stream.readBytes( fileData, 0, stream.bytesAvailable );
var digestHex:String = SHA256.computeDigest( fileData );
//Convert hexidecimal string to byte array
var digest:ByteArray = new ByteArray();
for( var c:int = 0; c < digestHex.length; c += 2 ){
var byteChar:String = digestHex.charAt(c) + digestHex.charAt(c+1);
digest.writeByte( parseInt( byteChar, 16 ));
}
digest.position = 0;
Last updated 3/21/2011
842
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
XML signature validation in AIR
var base64Encoder:Base64Encoder = new Base64Encoder();
base64Encoder.insertNewLines = false;
base64Encoder.encodeBytes( digest, 0, digest.bytesAvailable );
var digestBase64:String = base64Encoder.toString();
if( digestBase64 == reference.nameSpace::DigestValue )
{
result = result && true;
message += "
" + reference.@URI + " verified.\n";
}
else
{
result = false;
message += " ---- " + reference.@URI + " has been modified!\n";
}
base64Encoder.reset();
}
trace( message );
return result;
}
The function loops through all the references in the Manifest element. For each reference, the SHA256 digest is
computed, encoded in base64 format, and compared to the digest in the manifest. The URIs in an AIR package refer
to paths relative to the application directory. The paths are resolved based on the location of the signature file, which
is always in the META-INF subdirectory within the application directory. Note that the Flex SHA256 class returns the
digest as a string of hexadecimal characters. This string must be converted into a ByteArray containing the bytes
represented by the hexadecimal string.
To use the mx.utils.SHA256 and Base64Encoder classes in Flash CS4, you can either locate and copy these classes into
your application development directory or compile a library SWF containing the classes using the Flex SDK.
Dereferencing URIs in detached signatures referencing external data
Adobe AIR 1.5 and later
When a URI refers to an external resource, the data must be accessed and loaded into a ByteArray object. If the URI
contains an absolute URL, then it is simply a matter of reading a file or requesting a URL. If, as is probably the more
common case, the URI contains to a relative path, then your IURIDereferencer implementation must include a way to
resolve the paths to the signed files.
The following example uses a File object initialized when the dereferencer instance is constructed as the base for
resolving signed files.
Last updated 3/21/2011
843
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
XML signature validation in AIR
package
{
import flash.events.ErrorEvent;
import flash.events.EventDispatcher;
import flash.filesystem.File;
import flash.filesystem.FileMode;
import flash.filesystem.FileStream;
import flash.security.IURIDereferencer;
import flash.utils.ByteArray;
import flash.utils.IDataInput;
public class RelativeFileDereferencer
extends EventDispatcher implements IURIDereferencer
{
private var base:File;
public function RelativeFileDereferencer( base:File )
{
this.base = base;
}
public function dereference( uri:String ):IDataInput
{
var data:ByteArray = null;
try{
var referent:File = this.base.resolvePath( uri );
var refStream:FileStream = new FileStream();
data = new ByteArray();
refStream.open( referent, FileMode.READ );
refStream.readBytes( data, 0, data.bytesAvailable );
} catch ( e:Error ) {
data = null;
throw new Error("Reference not resolvable: " + referent.nativePath + ", " +
e.message );
} finally {
return data;
}
}
}
}
The dereference() function simply locates the file addressed by the reference URI, loads the file contents into a byte
array, and returns the ByteArray object.
Note: Before validating remote external references, consider whether your application could be vulnerable to a “phone
home” or similar type of attack by a maliciously constructed signature document.
Last updated 3/21/2011
844
Chapter 47: Client system environment
Flash Player 9 and later, Adobe AIR 1.0 and later
This discussion explains how to interact with the user’s system. It shows you how to determine what features are
supported and how to build multilingual applications using the user’s installed input method editor (IME) if available.
It also shows typical uses for application domains.
More Help topics
flash.system.System
flash.system.Capabilities
Basics of the client system environment
Flash Player 9 and later, Adobe AIR 1.0 and later
As you build more advanced applications, you may find a need to know details about—and access functions of—your
users’ operating systems. The flash.system package contains a collection of classes that allow you to access system-level
functionality such as the following:
• Determining which application and security domain code is executing in
• Determining the capabilities of the user’s Flash runtime (such as Flash® Player or Adobe® AIR™) instance, such as
the screen size (resolution) and whether certain functionality is available, such as mp3 audio
• Building multilingual sites using the IME
• Interacting with the Flash runtime’s container (which could be an HTML page or a container application).
• Saving information to the user’s clipboard
The flash.system package also includes the IMEConversionMode and SecurityPanel classes. These classes contain
static constants that you use with the IME and Security classes, respectively.
Important concepts and terms
The following reference list contains important terms:
Operating system The main program that runs on a computer, within which all other applications run—such as
Microsoft Windows, Mac OS X, or Linux®.
Clipboard The operating system’s container for holding text or items that are copied or cut, and from which items are
pasted into applications.
Application domain A mechanism for separating classes used in different SWF files, so that if the SWF files include
different classes with the same name, the classes don’t overwrite each other.
IME (input method editor) A program (or operating system tool) that is used to enter complex characters or symbols
using a standard keyboard.
Last updated 3/21/2011
845
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Client system environment
Client system In programming terms, a client is the part of an application (or whole application) that runs on an
individual’s computer and is used by a single user. The client system is the underlying operating system on the user’s
computer.
Using the System class
Flash Player 9 and later, Adobe AIR 1.0 and later
The System class contains methods and properties that allow you to interact with the user’s operating system and
retrieve the current memory usage of the runtime. The methods and properties of the System class also allow you to
listen for imeComposition events, instruct the runtime to load external text files using the user’s current code page or
to load them as Unicode, or set the contents of the user’s clipboard.
Getting data about the user’s system at run time
Flash Player 9 and later, Adobe AIR 1.0 and later
By checking the System.totalMemory property, you can determine the amount of memory (in bytes) that the
runtime is currently using. This property allows you to monitor memory usage and optimize your applications based
on how the memory level changes. For example, if a particular visual effect causes a large increase in memory usage,
you may want to consider modifying the effect or eliminating it altogether.
The System.ime property is a reference to the currently installed Input Method Editor (IME). This property allows
you to listen for imeComposition events (flash.events.IMEEvent.IME_COMPOSITION) by using the
addEventListener() method.
The third property in the System class is useCodePage. When useCodePage is set to true, the runtime uses the
traditional code page of the operating system to load external text files. If you set this property to false, you tell the
runtime to interpret the external file as Unicode.
If you set System.useCodePage to true, remember that the traditional code page of the operating system must
include the characters used in your external text file in order for the text to display. For example, if you load an external
text file that contains Chinese characters, those characters cannot display on a system that uses the English Windows
code page because that code page does not include Chinese characters.
To ensure that users on all platforms can view the external text files that are used in your application, you should
encode all external text files as Unicode and leave System.useCodePage set to false by default. This way, the runtime
interprets the text as Unicode.
Saving text to the clipboard
Flash Player 9 and later, Adobe AIR 1.0 and later
The System class includes a method called setClipboard() that allows the Flash runtime to set the contents of the
user’s clipboard with a specified string. For security reasons, there is no Security.getClipboard() method, since
such a method could potentially allow malicious sites to access the data last copied to the user’s clipboard.
The following code illustrates how an error message can be copied to the user’s clipboard when a security error occurs.
The error message can be useful if the user wants to report a potential bug with an application.
Last updated 3/21/2011
846
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Client system environment
private function securityErrorHandler(event:SecurityErrorEvent):void
{
var errorString:String = "[" + event.type + "] " + event.text;
trace(errorString);
System.setClipboard(errorString);
}
Flash Player 10 and AIR 1.0
You can use the Clipboard class to read and write clipboard data in response to a user event. In AIR, a user event is not
required for code running in the application sandbox to access the clipboard.
Using the Capabilities class
Flash Player 9 and later, Adobe AIR 1.0 and later
The Capabilities class allows developers to determine the environment in which an application is being run. Using
various properties of the Capabilities class, you can find out the resolution of the user’s system, whether the user’s
system supports accessibility software, and the language of the user’s operating system, as well as the currently installed
version of the Flash runtime.
By checking the properties in the Capabilities class, you can customize your application to work best with the specific
user’s environment. For example, by checking the Capabilities.screenResolutionX and
Capabilities.screenResolutionY properties, you can determine the display resolution the user’s system is using
and decide which video size may be most appropriate. Or you can check the Capabilities.hasMP3 property to see
if the user’s system supports mp3 playback before attempting to load an external mp3 file.
The following code uses a regular expression to parse the Flash runtime version that the client is using:
var versionString:String = Capabilities.version;
var pattern:RegExp = /^(\w*) (\d*),(\d*),(\d*),(\d*)$/;
var result:Object = pattern.exec(versionString);
if (result != null)
{
trace("input: " + result.input);
trace("platform: " + result[1]);
trace("majorVersion: " + result[2]);
trace("minorVersion: " + result[3]);
trace("buildNumber: " + result[4]);
trace("internalBuildNumber: " + result[5]);
}
else
{
trace("Unable to match RegExp.");
}
If you want to send the user’s system capabilities to a server-side script so that the information can be stored in a
database, you can use the following ActionScript code:
Last updated 3/21/2011
847
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Client system environment
var url:String = "log_visitor.cfm";
var request:URLRequest = new URLRequest(url);
request.method = URLRequestMethod.POST;
request.data = new URLVariables(Capabilities.serverString);
var loader:URLLoader = new URLLoader(request);
Capabilities example: Detecting system capabilities
Flash Player 9 and later
The CapabilitiesExplorer example demonstrates how you can use the flash.system.Capabilities class to determine
which features the user’s version of the Flash runtime supports. This example teaches the following techniques:
• Detecting which capabilities the user’s version of the Flash runtime supports using the Capabilities class
• Using the ExternalInterface class to detect which browser settings the user’s browser supports
To get the application files for this sample, see www.adobe.com/go/learn_programmingAS3samples_flash. The
CapabilitiesExplorer application files can be found in the folder Samples/CapabilitiesExplorer. This application
consists of the following files:
File
Description
CapabilitiesExplorer.fla
The main application file in Flash (FLA) or Flex (MXML).
or
CapabilitiesExplorer.mxml
com/example/programmingas3/capabilities/CapabilitiesGrabber.as
The class that provides the main functionality of the application,
including adding the system Capabilities to an array, sorting the
items, and using the ExternalInterface class to retrieve browser
capabilities.
capabilities.html
An HTML container that contains the necessary JavaScript to
communicate with the external API.
CapabilitiesExplorer overview
Flash Player 9 and later
The CapabilitiesExplorer.mxml file is responsible for setting up the user interface for the CapabilitiesExplorer
application. The capabilities of the user’s version of the Flash runtime will be displayed within a DataGrid component
instance on the Stage. Their browser capabilities will also be displayed if they are running the application from an
HTML container and if the external API is available.
When the main application file’s creationComplete event is dispatched, the initApp() method is invoked. The
initApp() method calls the getCapabilities() method from within the
com.example.programmingas3.capabilities.CapabilitiesGrabber class. The code for the initApp() method is as
follows:
private function initApp():void
{
var dp:Array = CapabilitiesGrabber.getCapabilities();
capabilitiesGrid.dataProvider = dp;
}
Last updated 3/21/2011
848
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Client system environment
The CapabilitiesGrabber.getCapabilities() method returns a sorted array of the Flash runtime and browser
capabilities, which then gets set to the dataProvider property of the capabilitiesGrid DataGrid component
instance on the Stage.
CapabilitiesGrabber class overview
Flash Player 9 and later
The static getCapabilities() method of the CapabilitiesGrabber class adds each property from the
flash.system.Capabilities class to an array (capDP). It then calls the static getBrowserObjects() method in the
CapabilitiesGrabber class. The getBrowserObjects() method uses the external API to loop over the browser’s
navigator object, which contains the browser’s capabilities. The getCapabilities() method is as follows:
public static function getCapabilities():Array
{
var capDP:Array = new Array();
capDP.push({name:"Capabilities.avHardwareDisable", value:Capabilities.avHardwareDisable});
capDP.push({name:"Capabilities.hasAccessibility", value:Capabilities.hasAccessibility});
capDP.push({name:"Capabilities.hasAudio", value:Capabilities.hasAudio});
...
capDP.push({name:"Capabilities.version", value:Capabilities.version});
var navArr:Array = CapabilitiesGrabber.getBrowserObjects();
if (navArr.length > 0)
{
capDP = capDP.concat(navArr);
}
capDP.sortOn("name", Array.CASEINSENSITIVE);
return capDP;
}
The getBrowserObjects() method returns an array of each of the properties in the browser’s navigator object. If this
array has a length of one or more items, the array of browser capabilities (navArr) is appended to the array of Flash
Player capabilities (capDP), and the entire array is sorted alphabetically. Finally, the sorted array is returned to the main
application file, which then populates the data grid. The code for the getBrowserObjects() method is as follows:
Last updated 3/21/2011
849
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Client system environment
private static function getBrowserObjects():Array
{
var itemArr:Array = new Array();
var itemVars:URLVariables;
if (ExternalInterface.available)
{
try
{
var tempStr:String = ExternalInterface.call("JS_getBrowserObjects");
itemVars = new URLVariables(tempStr);
for (var i:String in itemVars)
{
itemArr.push({name:i, value:itemVars[i]});
}
}
catch (error:SecurityError)
{
// ignore
}
}
return itemArr;
}
If the external API is available in the current user environment, the Flash runtime calls the JavaScript
JS_getBrowserObjects() method, which loops over the browser’s navigator object and returns a string of URLencoded values to ActionScript. This string is then converted into a URLVariables object (itemVars) and added to the
itemArr array, which is returned to the calling script.
Communicating with JavaScript
Flash Player 9 and later
The final piece in building the CapabilitiesExplorer application is writing the necessary JavaScript to loop over each of
the items in the browser’s navigator object and append a name-value pair to a temporary array. The code for the
JavaScript JS_getBrowserObjects() method in the container.html file is as follows:
The code begins by creating a temporary array that will hold all the name-value pairs in the navigator object. Next, the
navigator object is looped over using a for..in loop, and the data type of the current value is evaluated to filter out
unwanted values. In this application, we are interested only in String or Boolean values, and other data types (such as
functions or arrays) are ignored. Each String or Boolean value in the navigator object is appended to the tempArr
array. Next, the browser’s screen object is looped over using a for..in loop, and each numeric value is added to the
tempArr array. Finally, the temporary array is converted into a string using the Array.join() method. The array uses
an ampersand (&) as a delimiter, which allows ActionScript to easily parse the data using the URLVariables class.
Last updated 3/21/2011
851
Chapter 48: AIR application invocation
and termination
Adobe AIR 1.0 and later
This section discusses the ways in which an installed Adobe® AIR® application can be invoked, as well as options and
considerations for closing a running application.
Note: The NativeApplication, InvokeEvent, and BrowserInvokeEvent objects are only available to SWF content running
in the AIR application sandbox. SWF content running in the Flash Player runtime, within the browser or the standalone
player (projector), or in an AIR application outside the application sandbox, cannot access these classes.
For a quick explanation and code examples of invoking and terminating AIR applications, see the following quick start
articles on the Adobe Developer Connection:
• Startup Options
More Help topics
flash.desktop.NativeApplication
flash.events.InvokeEvent
flash.events.BrowserInvokeEvent
Application invocation
Adobe AIR 1.0 and later
An AIR application is invoked when the user (or the operating system):
• Launches the application from the desktop shell.
• Uses the application as a command on a command line shell.
• Opens a type of file for which the application is the default opening application.
• (Mac OS X) clicks the application icon in the dock taskbar (whether or not the application is currently running).
• Chooses to launch the application from the installer (either at the end of a new installation process, or after doubleclicking the AIR file for an already installed application).
• Begins an update of an AIR application when the installed version has signaled that it is handling application
updates itself (by including a true declaration in the application
descriptor file).
• Visits a web page hosting a Flash badge or application that calls com.adobe.air.AIR
launchApplication()
method specifying the identifying information for the AIR application. (The application descriptor must also
include a true declaration for browser invocation to
succeed.)
Last updated 3/21/2011
852
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
AIR application invocation and termination
Whenever an AIR application is invoked, AIR dispatches an InvokeEvent object of type invoke through the singleton
NativeApplication object. To allow an application time to initialize itself and register an event listener, invoke events
are queued instead of discarded. As soon as a listener is registered, all the queued events are delivered.
Note: When an application is invoked using the browser invocation feature, the NativeApplication object only dispatches
an invoke event if the application is not already running.
To receive invoke events, call the addEventListener() method of the NativeApplication object
(NativeApplication.nativeApplication). When an event listener registers for an invoke event, it also receives
all invoke events that occurred before the registration. Queued invoke events are dispatched one at a time on a short
interval after the call to addEventListener() returns. If a new invoke event occurs during this process, it may be
dispatched before one or more of the queued events. This event queuing allows you to handle any invoke events that
have occurred before your initialization code executes. Keep in mind that if you add an event listener later in execution
(after application initialization), it will still receive all invoke events that have occurred since the application started.
Only one instance of an AIR application is started. When an already running application is invoked again, AIR
dispatches a new invoke event to the running instance. It is the responsibility of an AIR application to respond to an
invoke event and take the appropriate action (such as opening a new document window).
An InvokeEvent object contains any arguments passed to the application, as well as the directory from which the
application has been invoked. If the application was invoked because of a file-type association, then the full path to the
file is included in the command line arguments. Likewise, if the application was invoked because of an application
update, the full path to the update AIR file is provided.
When multiple files are opened in one operation a single InvokeEvent object is dispatched on Mac OS X. Each file is
included in the arguments array. On Windows and Linux, a separate InvokeEvent object is dispatched for each file.
Your application can handle invoke events by registering a listener with its NativeApplication object:
NativeApplication.nativeApplication.addEventListener(InvokeEvent.INVOKE, onInvokeEvent);
And defining an event listener:
var arguments:Array;
var currentDir:File;
public function onInvokeEvent(invocation:InvokeEvent):void {
arguments = invocation.arguments;
currentDir = invocation.currentDirectory;
}
Capturing command line arguments
Adobe AIR 1.0 and later
The command line arguments associated with the invocation of an AIR application are delivered in the InvokeEvent
object dispatched by the NativeApplication object. The InvokeEvent arguments property contains an array of the
arguments passed by the operating system when an AIR application is invoked. If the arguments contain relative file
paths, you can typically resolve the paths using the currentDirectory property.
The arguments passed to an AIR program are treated as white-space delimited strings, unless enclosed in double
quotes:
Last updated 3/21/2011
853
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
AIR application invocation and termination
Arguments
Array
tick tock
{tick,tock}
tick "tick tock"
{tick,tick tock}
"tick" “tock”
{tick,tock}
\"tick\" \"tock\"
{"tick","tock"}
The currentDirectory property of an InvokeEvent object contains a File object representing the directory from
which the application was launched.
When an application is invoked because a file of a type registered by the application is opened, the native path to the
file is included in the command line arguments as a string. (Your application is responsible for opening or performing
the intended operation on the file.) Likewise, when an application is programmed to update itself (rather than relying
on the standard AIR update user interface), the native path to the AIR file is included when a user double-clicks an
AIR file containing an application with a matching application ID.
You can access the file using the resolve() method of the currentDirectory File object:
if((invokeEvent.currentDirectory != null)&&(invokeEvent.arguments.length > 0)){
dir = invokeEvent.currentDirectory;
fileToOpen = dir.resolvePath(invokeEvent.arguments[0]);
}
You should also validate that an argument is indeed a path to a file.
Example: Invocation event log
Adobe AIR 1.0 and later
The following example demonstrates how to register listeners for and handle the invoke event. The example logs all
the invocation events received and displays the current directory and command line arguments.
ActionScript example
package
{
import
import
import
import
flash.display.Sprite;
flash.events.InvokeEvent;
flash.desktop.NativeApplication;
flash.text.TextField;
public class InvokeEventLogExample extends Sprite
{
public var log:TextField;
public function InvokeEventLogExample()
{
log = new TextField();
log.x = 15;
log.y = 15;
log.width = 520;
log.height = 370;
log.background = true;
addChild(log);
Last updated 3/21/2011
854
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
AIR application invocation and termination
NativeApplication.nativeApplication.addEventListener(InvokeEvent.INVOKE, onInvoke);
}
public function onInvoke(invokeEvent:InvokeEvent):void
{
var now:String = new Date().toTimeString();
logEvent("Invoke event received: " + now);
if (invokeEvent.currentDirectory != null)
{
logEvent("Current directory=" + invokeEvent.currentDirectory.nativePath);
}
else
{
logEvent("--no directory information available--");
}
if (invokeEvent.arguments.length > 0)
{
logEvent("Arguments: " + invokeEvent.arguments.toString());
}
else
{
logEvent("--no arguments--");
}
}
public function logEvent(entry:String):void
{
log.appendText(entry + "\n");
trace(entry);
}
}
}
Last updated 3/21/2011
855
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
AIR application invocation and termination
Flex example
0){
logEvent("Arguments: " + invokeEvent.arguments.toString());
} else {
logEvent("--no arguments--");
}
}
public function logEvent(entry:String):void {
log.text += entry + "\n";
trace(entry);
}
]]>
Invoking an AIR application on user login
Adobe AIR 1.0 and later
An AIR application can be set to launch automatically when the current user logs in by setting the NativeApplication
startAtLogin property to true. Once set, the application automatically starts whenever the user logs in. It continues
to launch at login until the setting is changed to false, the user manually changes the setting through the operating
system, or the application is uninstalled. Launching at login is a run-time setting. The setting only applies to the
current user. The application must be installed to successfully set the startAtLogin property to true. An error is
thrown if the property is set when an application is not installed (such as when it is launched with ADL).
Note: The application does not launch when the computer system starts. It launches when the user logs in.
Last updated 3/21/2011
856
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
AIR application invocation and termination
To determine whether an application has launched automatically or as a result of a user action, you can examine the
reason property of the InvokeEvent object. If the property is equal to InvokeEventReason.LOGIN, then the
application started automatically. For any other invocation path, the reason property equals
InvokeEventReason.STANDARD. To access the reason property, your application must target AIR 1.5.1 (by setting
the correct namespace value in the application descriptor file).
The following, simplified application uses the InvokeEvent reason property to decide how to behave when an invoke
event occurs. If the reason property is "login", then the application remains in the background. Otherwise, it makes the
main application visible. An application using this pattern typically starts at login so that it can carry out background
processing or event monitoring and opens a window in response to a user-triggered invoke event.
package {
import
import
import
import
flash.desktop.InvokeEventReason;
flash.desktop.NativeApplication;
flash.display.Sprite;
flash.events.InvokeEvent;
public class StartAtLogin extends Sprite
{
public function StartAtLogin()
{
try
{
NativeApplication.nativeApplication.startAtLogin = true;
}
catch ( e:Error )
{
trace( "Cannot set startAtLogin:" + e.message );
}
NativeApplication.nativeApplication.addEventListener( InvokeEvent.INVOKE, onInvoke );
}
private function onInvoke( event:InvokeEvent ):void
{
if( event.reason == InvokeEventReason.LOGIN )
{
//do background processing...
trace( "Running in background..." );
}
else
{
this.stage.nativeWindow.activate();
}
}
}
}
Note: To see the difference in behavior, package and install the application. The startAtLogin property can only be set
for installed applications.
Last updated 3/21/2011
857
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
AIR application invocation and termination
Invoking an AIR application from the browser
Adobe AIR 1.0 and later
Using the browser invocation feature, a web site can launch an installed AIR application to be launched from the
browser. Browser invocation is only permitted if the application descriptor file sets allowBrowserInvocation to true:
true
When the application is invoked via the browser, the application’s NativeApplication object dispatches a
BrowserInvokeEvent object.
To receive BrowserInvokeEvent events, call the addEventListener() method of the NativeApplication object
(NativeApplication.nativeApplication) in the AIR application. When an event listener registers for a
BrowserInvokeEvent event, it also receives all BrowserInvokeEvent events that occurred before the registration. These
events are dispatched after the call to addEventListener() returns, but not necessarily before other
BrowserInvokeEvent events that might be received after registration. This allows you to handle BrowserInvokeEvent
events that have occurred before your initialization code executes (such as when the application was initially invoked
from the browser). Keep in mind that if you add an event listener later in execution (after application initialization) it
still receives all BrowserInvokeEvent events that have occurred since the application started.
The BrowserInvokeEvent object includes the following properties:
Property
Description
arguments
An array of arguments (strings) to pass to the application.
isHTTPS
Whether the content in the browser uses the https URL scheme (true) or not (false).
isUserEvent
Whether the browser invocation resulted in a user event (such as a mouse click). In AIR 1.0, this is always set to
true; AIR requires a user event to the browser invocation feature.
sandboxType
The sandbox type for the content in the browser. Valid values are defined the same as those that can be used
in the Security.sandboxType property, and can be one of the following:
securityDomain
•
Security.APPLICATION — The content is in the application security sandbox.
•
Security.LOCAL_TRUSTED — The content is in the local-with-filesystem security sandbox.
•
Security.LOCAL_WITH_FILE — The content is in the local-with-filesystem security sandbox.
•
Security.LOCAL_WITH_NETWORK — The content is in the local-with-networking security sandbox.
•
Security.REMOTE — The content is in a remote (network) domain.
The security domain for the content in the browser, such as "www.adobe.com" or "www.example.org".
This property is only set for content in the remote security sandbox (for content from a network domain). It is
not set for content in a local or application security sandbox.
If you use the browser invocation feature, be sure to consider security implications. When a web site launches an AIR
application, it can send data via the arguments property of the BrowserInvokeEvent object. Be careful using this data
in any sensitive operations, such as file or code loading APIs. The level of risk depends on what the application is doing
with the data. If you expect only a specific web site to invoke the application, the application should check the
securityDomain property of the BrowserInvokeEvent object. You can also require the web site invoking the
application to use HTTPs, which you can verify by checking the isHTTPS property of the BrowserInvokeEvent object.
The application should validate the data passed in. For example, if an application expects to be passed URLs to a
specific domain, it should validate that the URLs really do point to that domain. This can prevent an attacker from
tricking the application into sending it sensitive data.
Last updated 3/21/2011
858
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
AIR application invocation and termination
No application should use BrowserInvokeEvent arguments that might point to local resources. For example, an
application should not create File objects based on a path passed from the browser. If remote paths are expected to be
passed from the browser, the application should ensure that the paths do not use the file:// protocol instead of a
remote protocol.
Application termination
Adobe AIR 1.0 and later
The quickest way to terminate an application is to call the NativeApplication exit() method. This works fine when your
application has no data to save or external resources to clean up. Calling exit() closes all windows and then
terminates the application. However, to allow windows or other components of your application to interrupt the
termination process, perhaps to save vital data, dispatch the proper warning events before calling exit().
Another consideration in gracefully shutting down an application is providing a single execution path, no matter how
the shut-down process starts. The user (or operating system) can trigger application termination in the following ways:
• By closing the last application window when NativeApplication.nativeApplication.autoExit is true.
• By selecting the application exit command from the operating system; for example, when the user chooses the exit
application command from the default menu. (This only happens on Mac OS; Windows and Linux do not provide
an application exit command through system chrome.)
• By shutting down the computer.
When an exit command is mediated through the operating system by one of these routes, the NativeApplication
dispatches an exiting event. If no listeners cancel the exiting event, any open windows are closed. Each window
dispatches a closing and then a close event. If any of the windows cancel the closing event, the shut-down process
stops.
If the order of window closure is an issue for your application, listen for the exiting event from the NativeApplication
and close the windows in the proper order yourself. You might need to do this, for example, if you have a document
window with tool palettes. It could be inconvenient, or worse, if the system closed the palettes, but the user decided to
cancel the exit command to save some data. On Windows, the only time you will get the exiting event is after closing
the last window (when the autoExit property of the NativeApplication object is set to true).
To provide consistent behavior on all platforms, whether the exit sequence is initiated via operating system chrome,
menu commands, or application logic, observe the following good practices for exiting the application:
1 Always dispatch an exiting event through the NativeApplication object before calling exit() in application code
and check that another component of your application doesn’t cancel the event.
public function applicationExit():void {
var exitingEvent:Event = new Event(Event.EXITING, false, true);
NativeApplication.nativeApplication.dispatchEvent(exitingEvent);
if (!exitingEvent.isDefaultPrevented()) {
NativeApplication.nativeApplication.exit();
}
}
2 Listen for the application exiting event from the NativeApplication.nativeApplication object and, in the
handler, close any windows (dispatching a closing event first). Perform any needed clean-up tasks, such as saving
application data or deleting temporary files, after all windows have been closed. Only use synchronous methods
during cleanup to ensure that they finish before the application quits.
Last updated 3/21/2011
859
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
AIR application invocation and termination
If the order in which your windows are closed doesn’t matter, then you can loop through the
NativeApplication.nativeApplication.openedWindows array and close each window in turn. If order does
matter, provide a means of closing the windows in the correct sequence.
private function onExiting(exitingEvent:Event):void {
var winClosingEvent:Event;
for each (var win:NativeWindow in NativeApplication.nativeApplication.openedWindows) {
winClosingEvent = new Event(Event.CLOSING,false,true);
win.dispatchEvent(winClosingEvent);
if (!winClosingEvent.isDefaultPrevented()) {
win.close();
} else {
exitingEvent.preventDefault();
}
}
if (!exitingEvent.isDefaultPrevented()) {
//perform cleanup
}
}
3 Windows should always handle their own clean up by listening for their own closing events.
4 Only use one exiting listener in your application since handlers called earlier cannot know whether subsequent
handlers will cancel the exiting event (and it would be unwise to rely on the order of execution).
Last updated 3/21/2011
860
Chapter 49: Working with AIR runtime
and operating system information
Adobe AIR 1.0 and later
This section discusses ways that an AIR application can manage operating system file associations, detect user activity,
and get information about the Adobe® AIR® runtime.
More Help topics
flash.desktop.NativeApplication
Managing file associations
Adobe AIR 1.0 and later
Associations between your application and a file type must be declared in the application descriptor. During the
installation process, the AIR application installer associates the AIR application as the default opening application for
each of the declared file types, unless another application is already the default. The AIR application install process
does not override an existing file type association. To take over the association from another application, call the
NativeApplication.setAsDefaultApplication() method at run time.
It is a good practice to verify that the expected file associations are in place when your application starts up. This is
because the AIR application installer does not override existing file associations, and because file associations on a
user’s system can change at any time. When another application has the current file association, it is also a polite
practice to ask the user before taking over an existing association.
The following methods of the NativeApplication class let an application manage file associations. Each of the methods
takes the file type extension as a parameter:
Method
Description
isSetAsDefaultApplication()
Returns true if the AIR application is currently associated with the specified file type.
setAsDefaultApplication()
Creates the association between the AIR application and the open action of the file type.
removeAsDefaultApplication()
Removes the association between the AIR application and the file type.
getDefaultApplication()
Reports the path of the application that is currently associated with the file type.
AIR can only manage associations for the file types originally declared in the application descriptor. You cannot get
information about the associations of a non-declared file type, even if a user has manually created the association
between that file type and your application. Calling any of the file association management methods with the extension
for a file type not declared in the application descriptor causes the application to throw a runtime exception.
Last updated 3/21/2011
861
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with AIR runtime and operating system information
Getting the runtime version and patch level
Adobe AIR 1.0 and later
The NativeApplication object has a runtimeVersion property, which is the version of the runtime in which the
application is running (a string, such as "1.0.5"). The NativeApplication object also has a runtimePatchLevel
property, which is the patch level of the runtime (a number, such as 2960). The following code uses these properties:
trace(NativeApplication.nativeApplication.runtimeVersion);
trace(NativeApplication.nativeApplication.runtimePatchLevel);
Detecting AIR capabilities
Adobe AIR 1.0 and later
For a file that is bundled with the Adobe AIR application, the Security.sandboxType property is set to the value
defined by the Security.APPLICATION constant. You can load content (which may or may not contain APIs specific
to AIR) based on whether a file is in the Adobe AIR security sandbox, as illustrated in the following code:
if (Security.sandboxType == Security.APPLICATION)
{
// Load SWF that contains AIR APIs
}
else
{
// Load SWF that does not contain AIR APIs
}
All resources that are not installed with the AIR application are assigned to the same security sandboxes as would be
assigned by Adobe® Flash® Player in a web browser. Remote resources are put in sandboxes according to their source
domains, and local resources are put in the local-with-networking, local-with-filesystem, or local-trusted sandbox.
You can check if the Capabilities.playerType static property is set to "Desktop" to see if content is executing in
the runtime (and not running in Flash Player running in a browser).
For more information, see “AIR security” on page 1041.
Tracking user presence
Adobe AIR 1.0 and later
The NativeApplication object dispatches two events that help you detect when a user is actively using a computer. If
no mouse or keyboard activity is detected in the interval determined by the NativeApplication.idleThreshold
property, the NativeApplication dispatches a userIdle event. When the next keyboard or mouse input occurs, the
NativeApplication object dispatches a userPresent event. The idleThreshold interval is measured in seconds and
has a default value of 300 (5 minutes). You can also get the number of seconds since the last user input from the
NativeApplication.nativeApplication.lastUserInput property.
Last updated 3/21/2011
862
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with AIR runtime and operating system information
The following lines of code set the idle threshold to 2 minutes and listen for both the userIdle and userPresent
events:
NativeApplication.nativeApplication.idleThreshold = 120;
NativeApplication.nativeApplication.addEventListener(Event.USER_IDLE, function(event:Event) {
trace("Idle");
});
NativeApplication.nativeApplication.addEventListener(Event.USER_PRESENT,
function(event:Event) {
trace("Present");
});
Note: Only a single userIdle event is dispatched between any two userPresent events.
Last updated 3/21/2011
863
Chapter 50: Working with AIR native
windows
Adobe AIR 1.0 and later
You use the classes provided by the Adobe® AIR® native window API to create and manage desktop windows.
Basics of native windows in AIR
Adobe AIR 1.0 and later
For quick explanations and code examples of working with native windows in AIR, see the following quick start articles
on the Adobe Developer Connection:
• Creating a transparent window application (Flex)
• Interacting with a window (Flex)
• Customizing the look and feel of a native window (Flex)
• Launching windows (Flex)
• Creating toast-style windows (Flex)
• Controlling the display order of windows (Flex)
• Creating resizable, non-rectangular windows (Flex)
• Interacting with a window (Flash)
• Customizing the look and feel of a native window (Flash)
• Creating toast-style windows (Flash)
• Controlling the display order of windows (Flash)
• Creating resizable, non-rectangular windows (Flash)
AIR provides an easy-to-use, cross-platform window API for creating native operating system windows using Flash®,
Flex™, and HTML programming techniques.
With AIR, you have a wide latitude in developing the appearance of your application. The windows you create can look
like a standard desktop application, matching Apple style when run on the Mac, conforming to Microsoft conventions
when run on Windows, and harmonizing with the window manager on Linux—all without including a line of
platform-specific code. Or you can use the skinnable, extensible chrome provided by the Flex framework to establish
your own style no matter where your application is run. You can even draw your own window chrome with vector and
bitmap artwork with full support for transparency and alpha blending against the desktop. Tired of rectangular
windows? Draw a round one.
Last updated 3/21/2011
864
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with AIR native windows
Windows in AIR
Adobe AIR 1.0 and later
AIR supports three distinct APIs for working with windows:
• The ActionScript-oriented NativeWindow class provides the lowest level window API. Use NativeWindows in
ActionScript and Flash Professional-authored applications. Consider extending the NativeWindow class to
specialize the windows used in your application.
• In the HTML environment, you can use the JavaScript Window class, just as you would in a browser-based web
application. Calls to JavaScript Window methods are forwarded to the underlying native window object.
• The Flex framework mx:WindowedApplication and mx:Window classes provide a Flex “wrapper” for the
NativeWindow class. The WindowedApplication component replaces the Application component when you create
an AIR application with Flex and must always be used as the initial window in your Flex application.
ActionScript windows
When you create windows with the NativeWindow class, use the Flash Player stage and display list directly. To add a
visual object to a NativeWindow, add the object to the display list of the window stage or to another display object
container on the stage.
HTML windows
When you create HTML windows, you use HTML, CSS, and JavaScript to display content. To add a visual object to an
HTML window, you add that content to the HTML DOM. HTML windows are a special category of NativeWindow.
The AIR host defines a nativeWindow property in HTML windows that provides access to the underlying
NativeWindow instance. You can use this property to access the NativeWindow properties, methods, and events
described here.
Note: The JavaScript Window object also has methods for scripting the containing window, such as moveTo() and
close(). Where overlapping methods are available, you can use whichever method that is convenient.
Flex Framework windows
When you create windows with the Flex framework, you typically use MXML components to populate the window.
To add a Flex component to a window, you add the component element to the window MXML definition. You can
also use ActionScript to add content dynamically. The mx:WindowedApplication and mx:Window components are
designed as Flex containers and so can accept Flex components directly, whereas NativeWindow objects cannot. When
necessary, the NativeWindow properties and methods can be accessed through the WindowedApplication and
Window objects using the nativeWindow property.
The initial application window
The first window of your application is automatically created for you by AIR. AIR sets the properties and content of
the window using the parameters specified in the initialWindow element of the application descriptor file.
If the root content is a SWF file, AIR creates a NativeWindow instance, loads the SWF file, and adds it to the window
stage. If the root content is an HTML file, AIR creates an HTML window and loads the HTML.
Native window classes
Adobe AIR 1.0 and later
The native window API contains the following classes:
Last updated 3/21/2011
865
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with AIR native windows
Package
Classes
flash.display
•
NativeWindow
•
NativeWindowInitOptions
•
NativeWindowDisplayState
•
NativeWindowResize
•
NativeWindowSystemChrome
•
NativeWindowType
•
NativeWindowBoundsEvent
•
NativeWindowDisplayStateEvent
flash.events
Native window event flow
Adobe AIR 1.0 and later
Native windows dispatch events to notify interested components that an important change is about to occur or has
already occurred. Many window-related events are dispatched in pairs. The first event warns that a change is about to
happen. The second event announces that the change has been made. You can cancel a warning event, but not a
notification event. The following sequence illustrates the flow of events that occurs when a user clicks the maximize
button of a window:
1 The NativeWindow object dispatches a displayStateChanging event.
2 If no registered listeners cancel the event, the window maximizes.
3 The NativeWindow object dispatches a displayStateChange event.
In addition, the NativeWindow object also dispatches events for related changes to the window size and position.
The window does not dispatch warning events for these related changes. The related events are:
a A move event is dispatched if the top, left corner of the window moved because of the maximize operation.
b A resize event is dispatched if the window size changed because of the maximize operation.
A NativeWindow object dispatches a similar sequence of events when minimizing, restoring, closing, moving, and
resizing a window.
The warning events are only dispatched when a change is initiated through window chrome or other operatingsystem controlled mechanism. When you call a window method to change the window size, position, or display
state, the window only dispatches an event to announce the change. You can dispatch a warning event, if desired,
using the window dispatchEvent() method, then check to see if your warning event has been canceled before
proceeding with the change.
For detailed information about the window API classes, methods, properties, and events, see the ActionScript 3.0
Reference for the Adobe Flash Platform.
Last updated 3/21/2011
866
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with AIR native windows
Properties controlling native window style and behavior
Flash Player 9 and later, Adobe AIR 1.0 and later
The following properties control the basic appearance and behavior of a window:
•
type
•
systemChrome
•
transparent
•
owner
When you create a window, you set these properties on the NativeWindowInitOptions object passed to the window
constructor. AIR reads the properties for the initial application window from the application descriptor. (Except the
type property, which cannot be set in the application descriptor and is always set to normal.) The properties cannot
be changed after window creation.
Some settings of these properties are mutually incompatible: systemChrome cannot be set to standard when either
transparent is true or type is lightweight.
Window types
Adobe AIR 1.0 and later
The AIR window types combine chrome and visibility attributes of the native operating system to create three
functional types of window. Use the constants defined in the NativeWindowType class to reference the type names in
code. AIR provides the following window types:
Type
Description
Normal
A typical window. Normal windows use the full-size style of chrome and appear on the Windows taskbar and
the Mac OS X window menu.
Utility
A tool palette. Utility windows use a slimmer version of the system chrome and do not appear on the Windows
taskbar and the Mac OS X window menu.
Lightweight
Lightweight windows have no chrome and do not appear on the Windows taskbar or the Mac OS X window
menu. In addition, lightweight windows do not have the System (Alt+Space) menu on Windows. Lightweight
windows are suitable for notification bubbles and controls such as combo-boxes that open a short-lived display
area. When the lightweight type is used, systemChrome must be set to none.
Window chrome
Adobe AIR 1.0 and later
Window chrome is the set of controls that allow users to manipulate a window in the desktop environment. Chrome
elements include the title bar, title bar buttons, border, and resize grippers.
System chrome
You can set the systemChrome property to standard or none. Choose standard system chrome to give your window
the set of standard controls created and styled by the user’s operating system. Choose none to provide your own
chrome for the window. Use the constants defined in the NativeWindowSystemChrome class to reference the system
chrome settings in code.
Last updated 3/21/2011
867
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with AIR native windows
System chrome is managed by the system. Your application has no direct access to the controls themselves, but can
react to the events dispatched when the controls are used. When you use standard chrome for a window, the
transparent property must be set to false and the type property must be normal or utility.
Flex chrome
When you use the Flex WindowedApplication or Window components, the window can be use either system chrome
or chrome provided by the Flex framework. To use the Flex chrome, set the systemChrome property used to create the
window to none. When using the Flex 4 spark components rather than the mx components, you must specify the skin
class in order to use Flex chrome. You can use the built-in skins or provide your own. The following example
demonstrates how to use the built-in spark WindowedApplication skin class to provide the window chrome:
@namespace "library://ns.adobe.com/flex/spark";
WindowedApplication
{
skinClass:ClassReference("spark.skins.spark.SparkChromeWindowedApplicationSkin");
}
For more information, see Using Flex 4: About the AIR window containers: Controlling window chrome
Custom chrome
When you create a window with no system chrome, then you must add your own chrome controls to handle the
interactions between a user and the window. You are also free to make transparent, non-rectangular windows.
To use custom chrome with the mx:WindowedApplication or mx:Window components, you must set the
showFlexChrome style to false. Otherwise, Flex will add its own chrome to your windows.
Window transparency
Adobe AIR 1.0 and later
To allow alpha blending of a window with the desktop or other windows, set the window transparent property to
true. The transparent property must be set before the window is created and cannot be changed.
A transparent window has no default background. Any window area not containing an object drawn by the application
is invisible. If a displayed object has an alpha setting of less than one, then anything below the object shows through,
including other display objects in the same window, other windows, and the desktop.
Transparent windows are useful when you want to create applications with borders that are irregular in shape or that
“fade out” or appear to be invisible. However, rendering large alpha-blended areas can be slow, so the effect should be
used conservatively.
Important: On Linux, mouse events do not pass through fully transparent pixels. You should avoid creating windows
with large, fully transparent areas since you may invisibly block the user’s access to other windows or items on their
desktop. On Mac OS X and Windows, mouse events do pass through fully transparent pixels.
Transparency cannot be used with windows that have system chrome. In addition, SWF and PDF content in HTML
may not display in transparent windows. For more information, see “Considerations when loading SWF or PDF
content in an HTML page” on page 975.
Last updated 3/21/2011
868
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with AIR native windows
The static NativeWindow.supportsTransparency property reports whether window transparency is available.
When transparency is not supported, the application is composited against a black background. In these cases, any
transparent areas of the application display as an opaque black. It is a good practice to provide a fallback in case this
property tests false. For example, you could display a warning dialog to the user, or display a rectangular, nontransparent user interface.
Note that transparency is always supported by the Mac and Windows operating systems. Support on Linux operating
systems requires a compositing window manager, but even when a compositing window manager is active,
transparency can be unavailable because of user display options or hardware configuration.
Transparency in an MXML application window
Adobe AIR 1.0 and later
By default, the background of an MXML window is opaque, even if you create the window as transparent. (Notice the
transparency effect at the corners of the window.) To present a transparent background for the window, set a
background color and alpha value in the style sheet or element contained in your application MXML file.
For example, the following style declaration gives the background a slightly transparent green shade:
WindowedApplication
{
background-alpha:".8";
background-color:"0x448234";
}
Transparency in an HTML application window
Adobe AIR 1.0 and later
By default the background of HTML content displayed in HTML windows and HTMLLoader objects is opaque, event
if the containing window is transparent. To turn off the default background displayed for HTML content, set the
paintsDefaultBackground property to false. The following example creates an HTMLLoader and turns off the
default background:
var htmlView:HTMLLoader = new HTMLLoader();
htmlView.paintsDefaultBackground = false;
This example uses JavaScript to turn off the default background of an HTML window:
window.htmlLoader.paintsDefaultBackground = false;
If an element in the HTML document sets a background color, the background of that element is not transparent.
Setting a partial transparency (or opacity) value is not supported. However, you can use a transparent PNG-format
graphic as the background for a page or a page element to achieve a similar visual effect.
Window ownership
One window can own one or more other windows. These owned windows always appear in front of the master
window, are minimized and restored along with the master window, and are closed when the master window is closed.
Window ownership cannot be transfered to another window or removed. A window can only be owned by one master
window, but can own any number of other windows.
You can use window ownership to make it easier to manage windows used for tool palettes and dialogs. For example,
if you displayed a Save dialog in association with a document window, making the document window own the dialog
will keep the dialog in front of the document window automatically.
Last updated 3/21/2011
869
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with AIR native windows
A visual window catalog
Adobe AIR 1.0 and later
The following table illustrates the visual effects of different combinations of window property settings on the Mac OS
X, Windows, and Linux operating systems:
Window settings
Mac OS X
Microsoft Windows
Type: normal
SystemChrome: standard
Transparent: false
Type: utility
SystemChrome: standard
Transparent: false
Last updated 3/21/2011
Linux*
870
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with AIR native windows
Window settings
Mac OS X
Microsoft Windows
Linux*
Type: Any
SystemChrome: none
Transparent: false
Type: Any
SystemChrome: none
Transparent: true
mxWindowedApplication or
mx:Window
Type: Any
SystemChrome: none
Transparent: true
*
Ubuntu with Compiz window manager
Note: The following system chrome elements are not supported by AIR: the Mac OS X Toolbar, the Mac OS X Proxy Icon,
Windows title bar icons, and alternate system chrome.
Creating windows
Adobe AIR 1.0 and later
AIR automatically creates the first window for an application, but you can create any additional windows you need.
To create a native window, use the NativeWindow constructor method.
To create an HTML window, either use the HTMLLoader createRootWindow() method or, from an HTML
document, call the JavaScript window.open() method. The window created is a NativeWindow object whose display
list contains an HTMLLoader object. The HTMLLoader object interprets and displays the HTML and JavaScript
content for the window. You can access the properties of the underlying NativeWindow object from JavaScript using
the window.nativeWindow property. (This property is only accessible to code running in the AIR application
sandbox.)
Last updated 3/21/2011
871
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with AIR native windows
When you initialize a window—including the initial application window—you should consider creating the window
in the invisible state, loading content or executing any graphical updates, and then making the window visible. This
sequence prevents any jarring visual changes from being visible to your users. You can specify that the initial window
of your application should be created in the invisible state by specifying the false tag in the
application descriptor (or by leaving the tag out altogether since false is the default value). New NativeWindows are
invisible by default. When you create an HTML window with the HTMLLoader createRootWindow() method, you
can set the visible argument to false. Call the NativeWindow activate() method or set the visible property to
true to make a window visible.
Specifying window initialization properties
Adobe AIR 1.0 and later
The initialization properties of a native window cannot be changed after the desktop window is created. These
immutable properties and their default values include:
Property
Default value
systemChrome
standard
type
normal
transparent
false
owner
null
maximizable
true
minimizable
true
resizable
true
Set the properties for the initial window created by AIR in the application descriptor file. The main window of an AIR
application is always type, normal. (Additional window properties can be specified in the descriptor file, such as
visible, width, and height, but these properties can be changed at any time.)
Set the properties for other native and HTML windows created by your application using the
NativeWindowInitOptions class. When you create a window, you must pass a NativeWindowInitOptions object
specifying the window properties to either the NativeWindow constructor function or the HTMLLoader
createRootWindow() method.
The following code creates a NativeWindowInitOptions object for a utility window:
var options:NativeWindowInitOptions = new NativeWindowInitOptions();
options.systemChrome = NativeWindowSystemChrome.STANDARD;
options.type = NativeWindowType.UTILITY
options.transparent = false;
options.resizable = false;
options.maximizable = false;
Setting systemChrome to standard when transparent is true or type is lightweight is not supported.
Note: You cannot set the initialization properties for a window created with the JavaScript window.open() function.
You can, however, override how these windows are created by implementing your own HTMLHost class. See “Handling
JavaScript calls to window.open()” on page 987 for more information.
Last updated 3/21/2011
872
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with AIR native windows
When you create a window with the Flex mx:Window class, specify the initialization properties on the window object
itself, either in the MXML declaration for the window, or in the code that creates the window. The underlying
NativeWindow object is not created until you call the open() method. Once a window is opened, these initialization
properties cannot be changed.
Creating the initial application window
Adobe AIR 1.0 and later
AIR creates the initial application window based on the properties specified in the application descriptor and loads the
file referenced in the content element. The content element must reference a SWF file or an HTML file.
The initial window can be the main window of your application or it can merely serve to launch one or more other
windows. You do not have to make it visible at all.
Creating the initial window with ActionScript
Adobe AIR 1.0 and later
When you create an AIR application using ActionScript, the main class of your application must extend the Sprite class
(or a subclass of Sprite). This class serves as the main entry point for the application.
When your application launches, AIR creates a window, creates an instance of the main class, and adds the instance to
the window stage. To access the window, you can listen for the addedToStage event and then use the nativeWindow
property of the Stage object to get a reference to the NativeWindow object.
The following example illustrates the basic skeleton for the main class of an AIR application built with ActionScript:
package {
import flash.display.NativeWindow;
import flash.display.Sprite;
import flash.events.Event;
public class MainClass extends Sprite
{
private var mainWindow:NativeWindow;
public function MainClass(){
this.addEventListener(Event.ADDED_TO_STAGE, initialize);
}
private function initialize(event:Event):void{
mainWindow = this.stage.nativeWindow;
//perform initialization...
mainWindow.activate(); //show the window
}
}
}
Note: Technically, you CAN access the nativeWindow property in the constructor function of the main class. However,
this is a special case applying only to the initial application window.
When creating an application in Flash Professional, the main document class is created automatically if you do not
create your own in a separate ActionScript file. You can access the NativeWindow object for the initial window using
the stage nativeWindow property. For example, the following code activates the main window in the maximized state
(from the timeline):
Last updated 3/21/2011
873
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with AIR native windows
import flash.display.NativeWindow;
var mainWindow:NativeWindow = this.stage.nativeWindow;
mainWindow.maximize();
mainWindow.activate();
Creating the initial window with Flex
Adobe AIR 1.0 and later
When creating an AIR application with the Flex framework, use the mx:WindowedApplication as the root element of
your main MXML file. (You can use the mx:Application component, but it does not support all the features available
in AIR.) The WindowedApplication component serves as the initial entry point for the application.
When you launch the application, AIR creates a native window, initializes the Flex framework, and adds the
WindowedApplication object to the window stage. When the launch sequence finishes, the WindowedApplication
dispatches an applicationComplete event. Access the desktop window object with the nativeWindow property of
the WindowedApplication instance.
The following example creates a simple WindowedApplication component that sets its x and y coordinates:
Creating a NativeWindow
Adobe AIR 1.0 and later
To create a NativeWindow, pass a NativeWindowInitOptions object to the NativeWindow constructor:
var options:NativeWindowInitOptions = new NativeWindowInitOptions();
options.systemChrome = NativeWindowSystemChrome.STANDARD;
options.transparent = false;
var newWindow:NativeWindow = new NativeWindow(options);
The window is not shown until you set the visible property to true or call the activate() method.
Once the window is created, you can initialize its properties and load content into the window using the stage property
and Flash display list techniques.
In almost all cases, you should set the stage scaleMode property of a new native window to noScale (use the
StageScaleMode.NO_SCALE constant). The Flash scale modes are designed for situations in which the application
author does not know the aspect ratio of the application display space in advance. The scale modes let the author
choose the least-bad compromise: clip the content, stretch or squash it, or pad it with empty space. Since you control
the display space in AIR (the window frame), you can size the window to the content or the content to the window
without compromise.
Last updated 3/21/2011
874
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with AIR native windows
The scale mode for Flex and HTML windows is set to noScale automatically.
Note: To determine the maximum and minimum window sizes allowed on the current operating system, use the following
static NativeWindow properties:
var maxOSSize:Point = NativeWindow.systemMaxSize;
var minOSSize:Point = NativeWindow.systemMinSize;
Creating an HTML window
Adobe AIR 1.0 and later
To create an HTML window, you can either call the JavaScript Window.open() method, or you can call the AIR
HTMLLoader class createRootWindow() method.
HTML content in any security sandbox can use the standard JavaScript Window.open() method. If the content is
running outside the application sandbox, the open() method can only be called in response to user interaction, such
as a mouse click or keypress. When open() is called, a window with system chrome is created to display the content
at the specified URL. For example:
newWindow = window.open("xmpl.html", "logWindow", "height=600, width=400, top=10, left=10");
Note: You can extend the HTMLHost class in ActionScript to customize the window created with the JavaScript
window.open() function. See “About extending the HTMLHost class” on page 980.
Content in the application security sandbox has access to the more powerful method of creating windows,
HTMLLoader.createRootWindow(). With this method, you can specify all the creation options for a new window. For
example, the following JavaScript code creates a lightweight type window without system chrome that is 300x400
pixels in size:
var options = new air.NativeWindowInitOptions();
options.systemChrome = "none";
options.type = "lightweight";
var windowBounds = new air.Rectangle(200,250,300,400);
newHTMLLoader = air.HTMLLoader.createRootWindow(true, options, true, windowBounds);
newHTMLLoader.load(new air.URLRequest("xmpl.html"));
Note: If the content loaded by a new window is outside the application security sandbox, the window object does not have
the AIR properties: runtime, nativeWindow, or htmlLoader.
If you create a transparent window, then SWF content embedded in the HTML loaded into that window is not always
displayed. You must set the wmode parameter of the object or embed tag used to reference the SWF file to either opaque
or transparent. The default value of wmode is window, so, by default, SWF content is not displayed in transparent
windows. PDF content cannot be displayed in transparent windows, no matter which wmode value is set. (Prior to AIR
1.5.2, SWF content could not be displayed in transparent windows, either.)
Windows created with the createRootWindow() method remain independent from the opening window. The
parent and opener properties of the JavaScript Window object are null. The opening window can access the
Window object of the new window using the HTMLLoader reference returned by the createRootWindow() function.
In the context of the previous example, the statement newHTMLLoader.window would reference the JavaScript
Window object of the created window.
Note: The createRootWindow() function can be called from both JavaScript and ActionScript.
Last updated 3/21/2011
875
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with AIR native windows
Creating a mx:Window
Adobe AIR 1.0 and later
To create a mx:Window, you can create an MXML file using mx:Window as the root tag, or you can call the Window
class constructor directly.
The following example creates and shows a mx:Window by calling the Window constructor:
var newWindow:Window = new Window();
newWindow.systemChrome = NativeWindowSystemChrome.NONE;
newWindow.transparent = true;
newWindow.title = "New Window";
newWindow.width = 200;
newWindow.height = 200;
newWindow.open(true);
Adding content to a window
Adobe AIR 1.0 and later
How you add content to an AIR window depends on the type of window. For example, MXML and HTML let you
declaratively define the basic content of the window. You can embed resources in the application SWF files or you can
load them from separate application files. Flex, Flash, and HTML content can all be created on the fly and added to a
window dynamically.
When you load SWF content, or HTML content containing JavaScript, you must take the AIR security model into
consideration. Any content in the application security sandbox, that is, content installed with your application and
loadable with the app: URL scheme, has full privileges to access all the AIR APIs. Any content loaded from outside this
sandbox cannot access the AIR APIs. JavaScript content outside the application sandbox is not able to use the runtime,
nativeWindow, or htmlLoader properties of the JavaScript Window object.
To allow safe cross-scripting, you can use a sandbox bridge to provide a limited interface between application content
and non-application content. In HTML content, you can also map pages of your application into a non-application
sandbox to allow the code on that page to cross-script external content. See “AIR security” on page 1041.
Loading a SWF file or image
You can load Flash SWF files or images into the display list of a native window using the flash.display.Loader
class:
Last updated 3/21/2011
876
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with AIR native windows
package {
import
import
import
import
flash.display.Sprite;
flash.events.Event;
flash.net.URLRequest;
flash.display.Loader;
public class LoadedSWF extends Sprite
{
public function LoadedSWF(){
var loader:Loader = new Loader();
loader.load(new URLRequest("visual.swf"));
loader.contentLoaderInfo.addEventListener(Event.COMPLETE,loadFlash);
}
private function loadFlash(event:Event):void{
addChild(event.target.loader);
}
}
}
Note: Older SWF files created using ActionScript 1 or 2 share global states such as class definitions, singletons, and global
variables if they are loaded into the same window. If such a SWF file relies on untouched global states to work correctly,
it cannot be loaded more than once into the same window, or loaded into the same window as another SWF file using
overlapping class definitions and variables. This content can be loaded into separate windows.
Loading HTML content into a NativeWindow
To load HTML content into a NativeWindow, you can either add an HTMLLoader object to the window stage and
load the HTML content into the HTMLLoader, or create a window that already contains an HTMLLoader object by
using the HTMLLoader.createRootWindow()method. The following example displays HTML content within a 300
by 500 pixel display area on the stage of a native window:
//newWindow is a NativeWindow instance
var htmlView:HTMLLoader = new HTMLLoader();
htmlView.width = 300;
htmlView.height = 500;
//set the stage so display objects are added to the top-left and not scaled
newWindow.stage.align = "TL";
newWindow.stage.scaleMode = "noScale";
newWindow.stage.addChild( htmlView );
//urlString is the URL of the HTML page to load
htmlView.load( new URLRequest(urlString) );
To load an HTML page into a Flex application, you can use the Flex HTML component.
SWF content in an HTML file is not displayed if the window uses transparency (that is the transparent property of
the window is true) unless the wmode parameter of the object or embed tag used to reference the SWF file is set to
either opaque or transparent. Since the default wmode value is window, by default, SWF content is not displayed in
a transparent window. PDF content is not displayed in a transparent window no matter what wmode value is used.
Also, neither SWF nor PDF content is displayed if the HTMLLoader control is scaled, rotated, or if the HTMLLoader
alpha property is set to a value other than 1.0.
Last updated 3/21/2011
877
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with AIR native windows
Adding SWF content as an overlay on an HTML window
Because HTML windows are contained within a NativeWindow instance, you can add Flash display objects both above
and below the HTML layer in the display list.
To add a display object above the HTML layer, use the addChild() method of the window.nativeWindow.stage
property. The addChild() method adds content layered above any existing content in the window.
To add a display object below the HTML layer, use the addChildAt() method of the window.nativeWindow.stage
property, passing in a value of zero for the index parameter. Placing an object at the zero index moves existing content,
including the HTML display, up one layer and insert the new content at the bottom. For content layered underneath
the HTML page to be visible, you must set the paintsDefaultBackground property of the HTMLlLoader object to
false. In addition, any elements of the page that set a background color, will not be transparent. If, for example, you
set a background color for the body element of the page, none of the page will be transparent.
The following example illustrates how to add a Flash display objects as overlays and underlays to an HTML page. The
example creates two simple shape objects, adds one below the HTML content and one above. The example also updates
the shape position based on the enterFrame event.
Bouncers
de Finibus Bonorum et Malorum
Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium
doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis
et quasi architecto beatae vitae dicta sunt explicabo.
This paragraph has a background color.
At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis
praesentium voluptatum deleniti atque corrupti quos dolores et quas molestias
excepturi sint occaecati cupiditate non provident, similique sunt in culpa qui
officia deserunt mollitia animi, id est laborum et dolorum fuga.
This example provides a rudimentary introduction to some advanced techniques that cross over the boundaries
between JavaScript and ActionScript in AIR. If your are unfamiliar with using ActionScript display objects, refer to
“Display programming” on page 143 in the ActionScript 3.0 Developer’s Guide.
Example: Creating a native window
Adobe AIR 1.0 and later
The following example illustrates how to create a native window:
Last updated 3/21/2011
879
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with AIR native windows
public function createNativeWindow():void {
//create the init options
var options:NativeWindowInitOptions = new NativeWindowInitOptions();
options.transparent = false;
options.systemChrome = NativeWindowSystemChrome.STANDARD;
options.type = NativeWindowType.NORMAL;
//create the window
var newWindow:NativeWindow = new NativeWindow(options);
newWindow.title = "A title";
newWindow.width = 600;
newWindow.height = 400;
newWindow.stage.align = StageAlign.TOP_LEFT;
newWindow.stage.scaleMode = StageScaleMode.NO_SCALE;
//activate and show the new window
newWindow.activate();
}
Managing windows
Adobe AIR 1.0 and later
You use the properties and methods of the NativeWindow class to manage the appearance, behavior, and life cycle of
desktop windows.
Note: When using the Flex framework, it is generally better to manage window behavior using the framework classes.
Most of the NativeWindow properties and methods can be accessed through the mx:WindowedApplication and
mx:Window classes.
Getting a NativeWindow instance
Adobe AIR 1.0 and later
To manipulate a window, you must first get the window instance. You can get a window instance from one of the
following places:
• The native window constructor used to create the window:
var win:NativeWindow = new NativeWindow(initOptions);
• The nativeWindow property of the window stage:
var win:NativeWindow = stage.nativeWindow;
• The stage property of a display object in the window:
var win:NativeWindow = displayObject.stage.nativeWindow;
• The target property of a native window event dispatched by the window:
private function onNativeWindowEvent(event:NativeWindowBoundsEvent):void
{
var win:NativeWindow = event.target as NativeWindow;
}
Last updated 3/21/2011
880
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with AIR native windows
• The nativeWindow property of an HTML page displayed in the window:
var win:NativeWindow = htmlLoader.window.nativeWindow;
• The activeWindow and openedWindows properties of the NativeApplication object:
var nativeWin:NativeWindow = NativeApplication.nativeApplication.activeWindow;
var firstWindow:NativeWindow = NativeApplication.nativeApplication.openedWindows[0];
NativeApplication.nativeApplication.activeWindow references the active window of an application (but
returns null if the active window is not a window of this AIR application). The
NativeApplication.nativeApplication.openedWindows array contains all of the windows in an AIR
application that have not been closed.
Because the Flex mx:WindowedApplication, and mx:Window objects are display objects, you can easily reference the
application window in an MXML file using the stage property, as follows:
label="Minimize" click="minimizeWindow()"/>
label="Restore" click="restoreWindow()"/>
label="Maximize" click="maximizeWindow()"/>
label="Close" click="closeWindow()"/>
The following ActionScript example for Flash creates four clickable text fields that trigger the NativeWindow
minimize(), maximize(), restore(), and close() methods:
Last updated 3/21/2011
885
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with AIR native windows
package
{
import flash.display.Sprite;
import flash.events.MouseEvent;
import flash.text.TextField;
public class MinimizeExample extends Sprite
{
public function MinimizeExample():void
{
var minTextBtn:TextField = new TextField();
minTextBtn.x = 10;
minTextBtn.y = 10;
minTextBtn.text = "Minimize";
minTextBtn.background = true;
minTextBtn.border = true;
minTextBtn.selectable = false;
addChild(minTextBtn);
minTextBtn.addEventListener(MouseEvent.CLICK, onMinimize);
var maxTextBtn:TextField = new TextField();
maxTextBtn.x = 120;
maxTextBtn.y = 10;
maxTextBtn.text = "Maximize";
maxTextBtn.background = true;
maxTextBtn.border = true;
maxTextBtn.selectable = false;
addChild(maxTextBtn);
maxTextBtn.addEventListener(MouseEvent.CLICK, onMaximize);
var restoreTextBtn:TextField = new TextField();
restoreTextBtn.x = 230;
restoreTextBtn.y = 10;
restoreTextBtn.text = "Restore";
restoreTextBtn.background = true;
restoreTextBtn.border = true;
restoreTextBtn.selectable = false;
addChild(restoreTextBtn);
restoreTextBtn.addEventListener(MouseEvent.CLICK, onRestore);
var closeTextBtn:TextField = new TextField();
closeTextBtn.x = 340;
closeTextBtn.y = 10;
closeTextBtn.text = "Close Window";
closeTextBtn.background = true;
closeTextBtn.border = true;
closeTextBtn.selectable = false;
addChild(closeTextBtn);
Last updated 3/21/2011
886
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with AIR native windows
closeTextBtn.addEventListener(MouseEvent.CLICK, onCloseWindow);
}
function onMinimize(event:MouseEvent):void
{
this.stage.nativeWindow.minimize();
}
function onMaximize(event:MouseEvent):void
{
this.stage.nativeWindow.maximize();
}
function onRestore(event:MouseEvent):void
{
this.stage.nativeWindow.restore();
}
function onCloseWindow(event:MouseEvent):void
{
this.stage.nativeWindow.close();
}
}
}
Resizing and moving a window
Adobe AIR 1.0 and later
When a window uses system chrome, the chrome provides drag controls for resizing the window and moving around
the desktop. If a window does not use system chrome you must add your own controls to allow the user to resize and
move the window.
Note: To resize or move a window, you must first obtain a reference to the NativeWindow instance. For information
about how to obtain a window reference, see “Getting a NativeWindow instance” on page 879.
Resizing a window
To allow a user to resize a window interactively, use the NativeWindow startResize() method. When this method
is called from a mouseDown event, the resizing operation is driven by the mouse and completes when the operating
system receives a mouseUp event. When calling startResize(), you pass in an argument that specifies the edge or
corner from which to resize the window.
To set the window size programmatically, set the width, height, or bounds properties of the window to the desired
dimensions. When you set the bounds, the window size and position can all be changed at the same time. However,
the order that the changes occur is not guaranteed. Some Linux window managers do not allow windows to extend
outside the bounds of the desktop screen. In these cases, the final window size may be limited because of the order in
which the properties are set, even though the net affect of the changes would otherwise have resulted in a legal window.
For example, if you change both the height and y position of a window near the bottom of the screen, then the full
height change might not occur when the height change is applied before the y position change.
Note: On Linux, window properties are changed asynchronously. If you resize a window in one line of your program, and
read the dimensions in the next, they will still reflect the old settings. On all platforms, the NativeWindow object
dispatches the resize event when the window resizes. If you need to take some action, such as laying out controls in the
window, based on the new size or state of the window, always do so in a resize event handler. See “Listening for window
events” on page 888.
Last updated 3/21/2011
887
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with AIR native windows
The scale mode of the stage determines how the window stage and its contents behaves when a window is resized. Keep
in mind that the stage scale modes are designed for situations, such as a web browser, where the application is not in
control of the size or aspect ratio of its display space. In general, you get the best results by setting the stage scaleMode
property to StageScaleMode.NO_SCALE. If you want the contents of the window to scale, you can still set the scaleX
and scaleY parameters of the content in response to the window bounds changes.
Moving a window
To move a window without resizing it, use the NativeWindow startMove() method. Like the startResize()
method, when the startMove() method is called from a mouseDown event, the move process is mouse-driven and
completes when the operating system receives a mouseUp event.
For more information about the startResize() and startMove() methods, see the ActionScript 3.0 Reference for
the Adobe Flash Platform.
To move a window programmatically, set the x, y, or bounds properties of the window to the desired position. When
you set the bounds, the window size and position can both be changed at the same time.
Note: On Linux, window properties are changed asynchronously. If you move a window in one line of your program, and
read the position in the next, the value read will still reflect the old setting. On all platforms, the NativeWindow object
dispatches the move event when the position changes. If you need to take some action based on the new position of the
window, always do so in a move event handler. See “Listening for window events” on page 888.
Example: Resizing and moving windows
Adobe AIR 1.0 and later
The following example shows how to initiate resizing and moving operations on a window:
package
{
import flash.display.Sprite;
import flash.events.MouseEvent;
import flash.display.NativeWindowResize;
public class NativeWindowResizeExample extends Sprite
{
public function NativeWindowResizeExample():void
{
// Fills a background area.
this.graphics.beginFill(0xFFFFFF);
this.graphics.drawRect(0, 0, 400, 300);
this.graphics.endFill();
// Creates a square area where a mouse down will start the resize.
var resizeHandle:Sprite =
createSprite(0xCCCCCC, 20, this.width - 20, this.height - 20);
resizeHandle.addEventListener(MouseEvent.MOUSE_DOWN, onStartResize);
// Creates a square area where a mouse down will start the move.
var moveHandle:Sprite = createSprite(0xCCCCCC, 20, this.width - 20, 0);
moveHandle.addEventListener(MouseEvent.MOUSE_DOWN, onStartMove);
}
public function createSprite(color:int, size:int, x:int, y:int):Sprite
{
Last updated 3/21/2011
888
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with AIR native windows
var s:Sprite = new Sprite();
s.graphics.beginFill(color);
s.graphics.drawRect(0, 0, size, size);
s.graphics.endFill();
s.x = x;
s.y = y;
this.addChild(s);
return s;
}
public function onStartResize(event:MouseEvent):void
{
this.stage.nativeWindow.startResize(NativeWindowResize.BOTTOM_RIGHT);
}
public function onStartMove(event:MouseEvent):void
{
this.stage.nativeWindow.startMove();
}
}
}
Listening for window events
Adobe AIR 1.0 and later
To listen for the events dispatched by a window, register a listener with the window instance. For example, to listen for
the closing event, register a listener with the window as follows:
myWindow.addEventListener(Event.CLOSING, onClosingEvent);
When an event is dispatched, the target property references the window sending the event.
Most window events have two related messages. The first message signals that a window change is imminent (and can
be canceled), while the second message signals that the change has occurred. For example, when a user clicks the close
button of a window, the closing event message is dispatched. If no listeners cancel the event, the window closes and
the close event is dispatched to any listeners.
Typically, the warning events, such as closing, are only dispatched when system chrome has been used to trigger an
event. Calling the window close() method, for example, does not automatically dispatch the closing event—only
the close event is dispatched. You can, however, construct a closing event object and dispatch it using the window
dispatchEvent() method.
The window events that dispatch an Event object are:
Event
Description
activate
Dispatched when the window receives focus.
deactivate
Dispatched when the window loses focus
closing
Dispatched when the window is about to close. This only occurs automatically when the system chrome close
button is pressed or, on Mac OS X, when the Quit command is invoked.
close
Dispatched when the window has closed.
Last updated 3/21/2011
889
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with AIR native windows
The window events that dispatch an NativeWindowBoundsEvent object are:
Event
Description
moving
Dispatched immediately before the top-left corner of the window changes position, either as a result of moving,
resizing or changing the window display state.
move
Dispatched after the top-left corner has changed position.
resizing
Dispatched immediately before the window width or height changes either as a result of resizing or a display
state change.
resize
Dispatched after the window has changed size.
For NativeWindowBoundsEvent events, you can use the beforeBounds and afterBounds properties to determine
the window bounds before and after the impending or completed change.
The window events that dispatch an NativeWindowDisplayStateEvent object are:
Event
Description
displayStateChanging
Dispatched immediately before the window display state changes.
displayStateChange
Dispatched after the window display state has changed.
For NativeWindowDisplayStateEvent events, you can use the beforeDisplayState and afterDisplayState
properties to determine the window display state before and after the impending or completed change.
On some Linux window managers, a display state change event is not dispatched when a window with a maximum
size setting is maximized. (The window is set to the maximized display state, but is not resized.)
Displaying full-screen windows
Adobe AIR 1.0 and later
Setting the displayState property of the Stage to StageDisplayState.FULL_SCREEN_INTERACTIVE places the
window in full-screen mode, and keyboard input is permitted in this mode. (In SWF content running in a browser,
keyboard input is not permitted). To exit full-screen mode, the user presses the Escape key.
Note: Some Linux window managers will not change the window dimensions to fill the screen if a maximum size is set
for the window (but do remove the window system chrome).
For example, the following Flex code defines a simple AIR application that sets up a simple full-screen terminal:
Last updated 3/21/2011
890
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with AIR native windows
The following ActionScript example for Flash simulates a simple full-screen text terminal:
Last updated 3/21/2011
891
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with AIR native windows
import
import
import
import
flash.display.Sprite;
flash.display.StageDisplayState;
flash.text.TextField;
flash.text.TextFormat;
public class FullScreenTerminalExample extends Sprite
{
public function FullScreenTerminalExample():void
{
var terminal:TextField = new TextField();
terminal.multiline = true;
terminal.wordWrap = true;
terminal.selectable = true;
terminal.background = true;
terminal.backgroundColor = 0x00333333;
this.stage.displayState = StageDisplayState.FULL_SCREEN_INTERACTIVE;
addChild(terminal);
terminal.width = 550;
terminal.height = 400;
terminal.text = "Welcome to the dumb terminal application. Press the ESC key to
exit.\n_";
var tf:TextFormat = new TextFormat();
tf.font = "Courier New";
tf.color = 0x00CCFF00;
tf.size = 12;
terminal.setTextFormat(tf);
terminal.setSelection(terminal.text.length - 1, terminal.text.length);
}
}
Last updated 3/21/2011
892
Chapter 51: Display screens in AIR
Adobe AIR 1.0 and later
Use the Adobe® AIR® Screen class to access information about the display screens attached to a computer or device.
More Help topics
flash.display.Screen
Basics of display screens in AIR
Adobe AIR 1.0 and later
• Measuring the virtual desktop (Flex)
• Measuring the virtual desktop (Flash)
The screen API contains a single class, Screen, which provides static members for getting system screen information,
and instance members for describing a particular screen.
A computer system can have several monitors or displays attached, which can correspond to several desktop screens
arranged in a virtual space. The AIR Screen class provides information about the screens, their relative arrangement,
and their usable space. If more than one monitor maps to the same screen, only one screen exists. If the size of a screen
is larger than the display area of the monitor, there is no way to determine which portion of the screen is currently
visible.
A screen represents an independent desktop display area. Screens are described as rectangles within the virtual
desktop. The upper-left corner of screen designated as the primary display is the origin of the virtual desktop
coordinate system. All values used to describe a screen are provided in pixels.
Last updated 3/21/2011
893
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Display screens in AIR
Screen bounds
Virtual screen
Usable bounds
In this screen arrangement, two screens exist on the virtual desktop. The coordinates of the upper-left corner of the main screen (#1) are always
(0,0). If the screen arrangement is changed to designate screen #2 as the main screen, then the coordinates of screen #1 become negative.
Menubars, taskbars, and docks are excluded when reporting the usable bounds for a screen.
For detailed information about the screen API class, methods, properties, and events, see the ActionScript 3.0
Reference for the Adobe Flash Platform.
Enumerating the screens
Adobe AIR 1.0 and later
You can enumerate the screens of the virtual desktop with the following screen methods and properties:
Method or Property
Description
Screen.screens
Provides an array of Screen objects describing the available screens. The order of the array is not
significant.
Screen.mainScreen
Provides a Screen object for the main screen. On Mac OS X, the main screen is the screen displaying the
menu bar. On Windows, the main screen is the system-designated primary screen.
Screen.getScreensForRectangle() Provides an array of Screen objects describing the screens intersected by the given rectangle. The
rectangle passed to this method is in pixel coordinates on the virtual desktop. If no screens intersect the
rectangle, then the array is empty. You can use this method to find out on which screens a window is
displayed.
Do not save the values returned by the Screen class methods and properties. The user or operating system can change
the available screens and their arrangement at any time.
The following example uses the screen API to move a window between multiple screens in response to pressing the
arrow keys. To move the window to the next screen, the example gets the screens array and sorts it either vertically
or horizontally (depending on the arrow key pressed). The code then walks through the sorted array, comparing each
screen to the coordinates of the current screen. To identify the current screen of the window, the example calls
Screen.getScreensForRectangle(), passing in the window bounds.
Last updated 3/21/2011
894
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Display screens in AIR
package {
import
import
import
import
import
import
flash.display.Sprite;
flash.display.Screen;
flash.events.KeyboardEvent;
flash.ui.Keyboard;
flash.display.StageAlign;
flash.display.StageScaleMode;
public class ScreenExample extends Sprite
{
public function ScreenExample()
{
stage.align = StageAlign.TOP_LEFT;
stage.scaleMode = StageScaleMode.NO_SCALE;
stage.addEventListener(KeyboardEvent.KEY_DOWN,onKey);
}
private function onKey(event:KeyboardEvent):void{
if(Screen.screens.length > 1){
switch(event.keyCode){
case Keyboard.LEFT :
moveLeft();
break;
case Keyboard.RIGHT :
moveRight();
break;
case Keyboard.UP :
moveUp();
break;
case Keyboard.DOWN :
moveDown();
break;
}
}
}
private function moveLeft():void{
var currentScreen = getCurrentScreen();
var left:Array = Screen.screens;
left.sort(sortHorizontal);
for(var i:int = 0; i < left.length - 1; i++){
if(left[i].bounds.left < stage.nativeWindow.bounds.left){
stage.nativeWindow.x +=
left[i].bounds.left - currentScreen.bounds.left;
stage.nativeWindow.y += left[i].bounds.top - currentScreen.bounds.top;
}
}
}
private function moveRight():void{
var currentScreen:Screen = getCurrentScreen();
var left:Array = Screen.screens;
left.sort(sortHorizontal);
for(var i:int = left.length - 1; i > 0; i--){
if(left[i].bounds.left > stage.nativeWindow.bounds.left){
stage.nativeWindow.x +=
Last updated 3/21/2011
895
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Display screens in AIR
left[i].bounds.left - currentScreen.bounds.left;
stage.nativeWindow.y += left[i].bounds.top - currentScreen.bounds.top;
}
}
}
private function moveUp():void{
var currentScreen:Screen = getCurrentScreen();
var top:Array = Screen.screens;
top.sort(sortVertical);
for(var i:int = 0; i < top.length - 1; i++){
if(top[i].bounds.top < stage.nativeWindow.bounds.top){
stage.nativeWindow.x += top[i].bounds.left - currentScreen.bounds.left;
stage.nativeWindow.y += top[i].bounds.top - currentScreen.bounds.top;
break;
}
}
}
private function moveDown():void{
var currentScreen:Screen = getCurrentScreen();
var top:Array = Screen.screens;
top.sort(sortVertical);
for(var i:int = top.length - 1; i > 0; i--){
if(top[i].bounds.top > stage.nativeWindow.bounds.top){
stage.nativeWindow.x += top[i].bounds.left - currentScreen.bounds.left;
stage.nativeWindow.y += top[i].bounds.top - currentScreen.bounds.top;
break;
}
}
}
private function sortHorizontal(a:Screen,b:Screen):int{
if (a.bounds.left > b.bounds.left){
return 1;
} else if (a.bounds.left < b.bounds.left){
return -1;
} else {return 0;}
}
private function sortVertical(a:Screen,b:Screen):int{
if (a.bounds.top > b.bounds.top){
return 1;
} else if (a.bounds.top < b.bounds.top){
return -1;
} else {return 0;}
}
private function getCurrentScreen():Screen{
var current:Screen;
var screens:Array = Screen.getScreensForRectangle(stage.nativeWindow.bounds);
(screens.length > 0) ? current = screens[0] : current = Screen.mainScreen;
return current;
}
}
}
Last updated 3/21/2011
896
Chapter 52: Printing
Flash Player 9 and later, Adobe AIR 1.0 and later
Flash runtimes (such as Adobe® Flash® Player and Adobe® AIR™) can communicate with an operating system’s printing
interface so that you can pass pages to the print spooler. Each page sent to the spooler can contain content that is
visible, dynamic, or off screen to the user, including database values and dynamic text. Additionally, the properties of
the flash.printing.PrintJob class contain values based on a user’s printer settings, so that you can format pages
appropriately.
The following content provides strategies for using the flash.printing.PrintJob class methods and properties to create
a print job, read a user’s print settings, and adjust a print job based on feedback from a Flash runtime and the user’s
operating system.
Basics of printing
Flash Player 9 and later, Adobe AIR 1.0 and later
In ActionScript 3.0, you use the PrintJob class to create snapshots of display content to convert to the ink-and-paper
representation in a printout. In some ways, setting up content for printing is the same as setting it up for on-screen
display—you position and size elements to create the desired layout. However printing has some idiosyncrasies that
make it different from screen layout. For example, printers use different resolution than computer monitors; the
contents of a computer screen are dynamic and can change, while printed content is inherently static; and in planning
printing, consider the constraints of fixed page size and the possibility of multipage printing.
Even though these differences seem obvious, it’s important to keep them in mind when setting up printing with
ActionScript. Accurate printing depends on a combination of the values specified by you and the characteristics of the
user’s printer. The PrintJob class includes properties that allow you to determine the important characteristics of the
user’s printer.
Important concepts and terms
The following reference list contains important terms related to printing:
Spooler A portion of the operating system or printer driver software that tracks the pages as they are waiting to be
printed and sends them to the printer when it is available.
Page orientation The rotation of the printed content in relation to the paper—either horizontal (landscape) or vertical
(portrait).
Print job The page or set of pages that make up a single printout.
Last updated 3/21/2011
897
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Printing
Printing a page
Flash Player 9 and later, Adobe AIR 1.0 and later
You use an instance of the PrintJob class to handle printing. To print a basic page through Flash Player or AIR, you
use these four statements in sequence:
•
new PrintJob(): Creates a new print job instance of the name you specify.
•
PrintJob.start(): Initiates the printing process for the operating system, calling the print dialog box for the user,
and populates the read-only properties of the print job.
•
PrintJob.addPage(): Contains the details about the print job contents, including the Sprite object (and any
children it contains), the size of the print area, and whether the printer prints the image as a vector or bitmap. You
can use successive calls to addPage() to print multiple sprites over several pages.
•
PrintJob.send(): Sends the pages to the operating system’s printer.
So, for example, a simple print job script is (including package, import and class statements for compiling):
package
{
import flash.printing.PrintJob;
import flash.display.Sprite;
public class BasicPrintExample extends Sprite
{
var myPrintJob:PrintJob = new PrintJob();
var mySprite:Sprite = new Sprite();
public function BasicPrintExample()
{
myPrintJob.start();
myPrintJob.addPage(mySprite);
myPrintJob.send();
}
}
}
Note: This example is intended to show the basic elements of a print job script, and does not contain any error handling.
To build a script that responds properly to a user canceling a print job, see “Working with exceptions and returns” on
page 898.
To clear a PrintJob object’s properties for any reason, set the PrintJob variable to null (as in myPrintJob = null).
Last updated 3/21/2011
898
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Printing
Flash runtime tasks and system printing
Flash Player 9 and later, Adobe AIR 1.0 and later
Because Flash runtimes dispatch pages to the operating system’s printing interface, be aware of the tasks managed by
Flash runtimes and the tasks managed by an operating system’s own printing interface. Flash runtimes can initiate a
print job, read some of a printer’s page settings, pass the content for a print job to the operating system, and verify if
the user or system has canceled a print job. Other processes, such as displaying printer specific dialog boxes, canceling
a spooled print job, or reporting on the printer’s status, are all handled by the operating system. Flash runtimes are able
to respond if there is a problem initiating or formatting a print job, but can report back only on certain properties or
conditions from the operating system’s printing interface. As a developer, your code needs to respond to these
properties or conditions.
Working with exceptions and returns
Flash Player 9 and later, Adobe AIR 1.0 and later
Check to see if the PrintJob.start() method returns true before executing addPage() and send() calls, in case
the user has canceled the print job. A simple way to check whether these methods have been canceled before
continuing is to wrap them in an if statement, as follows:
if (myPrintJob.start())
{
// addPage() and send() statements here
}
If PrintJob.start() is true, the user selected Print (or a Flash runtime, such as Flash Player or AIR, has initiated a
Print command). So, the addPage() and send() methods can be called.
Also, to help manage the printing process, Flash runtimes throw exceptions for the PrintJob.addPage() method, so
that you can catch errors and provide information and options to the user. If a PrintJob.addPage() method fails,
you can also call another function or stop the current print job. You catch these exceptions by embedding addPage()
calls within a try..catch statement, as in the following example. In the example, [params] is a placeholder for the
parameters specifying the actual content you want to print:
if (myPrintJob.start())
{
try
{
myPrintJob.addPage([params]);
}
catch (error:Error)
{
// Handle error,
}
myPrintJob.send();
}
After the print job starts, you can add the content using PrintJob.addPage() and see if that generates an exception
(for example, if the user has canceled the print job). If it does, you can add logic to the catch statement to provide the
user (or the Flash runtime) with information and options, or you can stop the current print job. If you add the page
successfully, you can proceed to send the pages to the printer using PrintJob.send().
Last updated 3/21/2011
899
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Printing
If the Flash runtime encounters a problem sending the print job to the printer (for example, if the printer is offline),
you can catch that exception, too, and provide more information or more options (such as displaying message text or
providing an alert within an animation). For example, you can assign new text to a text field in an if..else statement,
as the following code shows:
if (myPrintJob.start())
{
try
{
myPrintJob.addPage([params]);
}
catch (error:Error)
{
// Handle error.
}
myPrintJob.send();
}
else
{
myAlert.text = "Print job canceled";
}
For a working example, see “Printing example: Scaling, cropping, and responding” on page 906.
Working with page properties
Flash Player 9 and later, Adobe AIR 1.0 and later
Once the user clicks OK in the Print dialog box and PrintJob.start() returns true, you can access the properties
defined by the printer’s settings. These settings include the paper width, paper height (pageHeight and pageWidth),
and content orientation on the paper. Because these are printer settings, not controlled by the Flash runtime, you
cannot alter these settings; however, you can use them to align the content you send to the printer to match the current
settings. For more information, see “Setting size, scale, and orientation” on page 900.
Setting vector or bitmap rendering
Flash Player 9 and later, Adobe AIR 1.0 and later
You can manually set the print job to spool each page as vector graphics or a bitmap image. In some cases, vector
printing produces a smaller spool file, and a better image than bitmap printing. However, if your content includes a
bitmap image, and you want to preserve any alpha transparency or color effects, print the page as a bitmap image. Also,
a non-PostScript printer automatically converts any vector graphics to bitmap images.
You specify bitmap printing by passing a PrintJobOptions object as the third parameter of PrintJob.addPage().
For Flash Player and AIR prior to AIR 2, set the PrintJobOptions object’s printAsBitmap parameter set to true, as
follows:
var options:PrintJobOptions = new PrintJobOptions();
options.printAsBitmap = true;
myPrintJob.addPage(mySprite, null, options);
If you don’t specify a value for the third parameter, the print job uses the default, which is vector printing.
Last updated 3/21/2011
900
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Printing
For AIR 2 and later, use the PrintJobOptions object’s printMethod property to specify the print method. This
property accepts three values, which are defined as constants in the PrintMethod class:
•
PrintMethod.AUTO: Automatically chooses the best print method based on the content being printed. For
example, if a page consists of text, the vector print method is chosen. However, if a watermark image with alpha
transparency is overlaid on the text, bitmap printing is chosen to preserve the transparency.
•
PrintMethod.BITMAP: Forces bitmap printing regardless of the content
•
PrintMethod.VECTOR: Forces vector printing regardless of the content
Timing print job statements
Flash Player 9 and later, Adobe AIR 1.0 and later
ActionScript 3.0 does not restrict a PrintJob object to a single frame (as did previous versions of ActionScript).
However, because the operating system displays print status information to the user once the user has clicked the OK
button in the Print dialog box, call PrintJob.addPage() and PrintJob.send() as soon as possible to send pages to
the spooler. A delay reaching the frame containing the PrintJob.send() call delays the printing process.
In ActionScript 3.0, there is a script time-out limit of 15 seconds. Therefore, the time between each major statement
in a print job sequence cannot exceed 15 seconds. In other words, the 15-second script time-out limit applies to the
following intervals:
• Between PrintJob.start() and the first PrintJob.addPage()
• Between
PrintJob.addPage() and the next PrintJob.addPage()
• Between the last PrintJob.addPage() and PrintJob.send()
If any of these intervals spans more than 15 seconds, the next call to PrintJob.start() on the PrintJob instance
returns false, and the next PrintJob.addPage() on the PrintJob instance causes Flash Player or AIR to throw a runtime exception.
Setting size, scale, and orientation
Flash Player 9 and later, Adobe AIR 1.0 and later
The section “Printing a page” on page 897 details the steps for a basic print job, where the output directly reflects the
printed equivalent of the screen size and position of the specified sprite. However, printers use different resolutions
for printing, and can have settings that adversely affect the appearance of the printed sprite.
Flash runtimes can read an operating system’s printing settings, but note that these properties are read-only: although
you can respond to their values, you can’t set them. So, for example, you can find out the printer’s page size setting and
adjust your content to fit the size. You can also determine a printer’s margin settings and page orientation. To respond
to the printer settings, specify a print area, adjust for the difference between a screen’s resolution and a printer’s point
measurements, or transform your content to meet the size or orientation settings of the user’s printer.
Last updated 3/21/2011
901
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Printing
Using rectangles for the print area
Flash Player 9 and later, Adobe AIR 1.0 and later
The PrintJob.addPage() method allows you to specify the region of a sprite that you want printed. The second
parameter, printArea, is in the form of a Rectangle object. You have three options for providing a value for this
parameter:
• Create a Rectangle object with specific properties and then use that rectangle in the addPage() call, as in the
following example:
private var rect1:Rectangle = new Rectangle(0, 0, 400, 200);
myPrintJob.addPage(sheet, rect1);
• If you haven’t already specified a Rectangle object, you can do it within the call itself, as in the following example:
myPrintJob.addPage(sheet, new Rectangle(0, 0, 100, 100));
• If you plan to provide values for the third parameter in the addPage() call, but don’t want to specify a rectangle,
you can use null for the second parameter, as in the following;
myPrintJob.addPage(sheet, null, options);
Comparing points and pixels
Flash Player 9 and later, Adobe AIR 1.0 and later
A rectangle's width and height are pixel values. A printer uses points as print units of measurement. Points are a fixed
physical size (1/72 inch), but the size of a pixel on the screen depends on the resolution of the particular screen. The
conversion rate between pixels and points depends on the printer settings and whether the sprite is scaled. An unscaled
sprite that is 72 pixels wide prints out one inch wide, with one point equal to one pixel, independent of screen
resolution.
You can use the following equivalencies to convert inches or centimeters to twips or points (a twip is 1/20 of a point):
• 1 point = 1/72 inch = 20 twips
• 1 inch = 72 points = 1440 twips
• 1 centimeter = 567 twips
If you omit the printArea parameter, or if it is passed incorrectly, the full area of the sprite is printed.
Scaling
Flash Player 9 and later, Adobe AIR 1.0 and later
If you want to scale a Sprite object before you print it, set the scale properties (see “Manipulating size and scaling
objects” on page 170) before calling the PrintJob.addPage() method, and set them back to their original values after
printing. The scale of a Sprite object has no relation to the printArea property. In other words, if you specify a print
area that is 50 pixels by 50 pixels, 2500 pixels are printed. If you scale the Sprite object, the same 2500 pixels are printed,
but the Sprite object is printed at the scaled size.
For an example, see “Printing example: Scaling, cropping, and responding” on page 906.
Last updated 3/21/2011
902
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Printing
Printing for landscape or portrait orientation
Flash Player 9 and later, Adobe AIR 1.0 and later
Because Flash Player and AIR can detect the settings for orientation, you can build logic into your ActionScript to
adjust the content size or rotation in response to the printer settings, as the following example illustrates:
if (myPrintJob.orientation == PrintJobOrientation.LANDSCAPE)
{
mySprite.rotation = 90;
}
Note: If you plan to read the system setting for content orientation on the paper, remember to import the
PrintJobOrientation class. The PrintJobOrientation class provides constant values that define the content orientation on
the page. You import the class using the following statement:
import flash.printing.PrintJobOrientation;
Responding to page height and width
Flash Player 9 and later, Adobe AIR 1.0 and later
Using a strategy that is similar to handling printer orientation settings, you can read the page height and width settings
and respond to them by embedding some logic into an if statement. The following code shows an example:
if (mySprite.height > myPrintJob.pageHeight)
{
mySprite.scaleY = .75;
}
In addition, a page’s margin settings can be determined by comparing the page and paper dimensions, as the following
example illustrates:
margin_height = (myPrintJob.paperHeight - myPrintJob.pageHeight) / 2;
margin_width = (myPrintJob.paperWidth - myPrintJob.pageWidth) / 2;
Advanced printing techniques
Adobe AIR 2 and later
Starting with Adobe AIR 2, the PrintJob class has additional properties and methods, and three additional classes are
supported: PrintUIOptions, PaperSize, and PrintMethod. These changes allow additional printer workflows and give
authors greater control over the printing process. Changes include:
• Page setup dialogs: Both standard and custom page setup dialogs can be displayed. The user can set page ranges,
paper size, orientation, and scaling before printing.
• Print view: A viewing mode can be created which accurately shows paper size, margins, and the position of content
on the page.
• Restricted printing: Authors can restrict printing options, such as the range of printable pages.
• Quality options: Authors can adjust the print quality for a document and allow the user to select resolution and
color options.
Last updated 3/21/2011
903
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Printing
• Multiple print sessions: A single PrintJob instance can now be used for multiple printing sessions. Applications can
provide consistent settings each time the page setup and print dialogs are displayed.
Print workflow changes
The new print workflow consists of the following steps:
•
new PrintJob(): Creates a PrintJob instance (or reuse an existing instance). Many new PrintJob properties and
methods, such as selectPaperSize(), are available before the print job starts or during printing.
•
PrintJob.showPageSetupDialog(): (optional) Display the page setup dialog without starting a print job.
•
PrintJob.start() or PrintJob.start2(): In addition to the start() method, the start2() method is used to
initiate the print spooling process. The start2() method allows you to choose whether to display the Print dialog
and customize the dialog if it is shown.
•
PrintJob.addPage(): Add content to the print job. Unchanged from existing process.
•
PrintJob.send() or PrintJob.terminate(): Send the pages to the selected printer or terminate the print job
without sending. Print jobs are terminated in response to an error. If a PrintJob instance is terminated, it can still
be reused. Regardless of whether the print job is sent to the printer or terminated, the current print settings are
retained when you reuse the PrintJob instance.
Page setup dialog
The showPageSetupDialog()method displays the operating system’s Page Setup dialog, if the current environment
supports it. Always check the supportsPageSetupDialog property before calling this method. Here is a simple
example:
import flash.printing.PrintJob;
var myPrintJob:PrintJob = new PrintJob();
//check for static property supportsPageSetupDialog of PrintJob class
if (PrintJob.supportsPageSetupDialog) {
myPrintJob.showPageSetupDialog();
}
The method can optionally be called with a PrintUIOptions class property to control which options are displayed in
the Page Setup dialog. The min and max page numbers can be set. The following example limits printing to the first
three pages:
import flash.printing.PrintJob;
var myPrintJob:PrintJob = new PrintJob();
if (PrintJob.supportsPageSetupDialog) {
var uiOpt:PrintUIOptions = new PrintUIOptions();
uiOpt.minPage = 1;
uiOpt.maxPage = 3;
myPrintJob.showPageSetupDialog(uiOpt);
}
Changing print settings
The settings for a PrintJob instance can be changed at any time after it is constructed. This includes changing settings
between addPage()calls and after a print job has been sent or terminated. Some settings, such as the printer
property, apply to the entire print job, not individual pages. Those settings must be set before a call to start() or
start2().
Last updated 3/21/2011
904
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Printing
The selectPaperSize() method can be called to set the default paper size in the Page Setup and Print dialogs. It can
also be called during a print job to set the paper size for a range of pages. It is called using constants defined in the
PaperSize class, as in this example, which selects a number 10 envelope size:
import flash.printing.PrintJob;
import flash.printing.PaperSize;
var myPrintJob:PrintJob = new PrintJob();
myPrintJob.selectPaperSize(PaperSize.ENV_10);
Use the printer property to get or set the name of the printer for the current print job. By default it is set to the name
of the default printer. The printer property is null if no printers are available or the system does not support
printing. To change the printer, first get the list of available printers using the printers property. That property is a
Vector whose String elements are available printer names. Set the printer property to one of those String values to
make that printer the active one. The printer property of an active print job cannot be changed. Attempts to change
it after a successful call to start() or start2() and before the job is sent or terminated fail. Here is an example of
setting this property:
import flash.printing.PrintJob;
var myPrintJob:PrintJob = new PrintJob();
myPrintJob.printer = "HP_LaserJet_1";
myPrintJob.start();
The copies property gets the value for the number of copies set in the operating system’s Print dialog. The firstPage
and lastPage properties get the page range. The orientation property gets the paper orientation setting. These
properties can be set to override the values from the Print dialog. The following example sets these properties:
import flash.printing.PrintJob;
import flash.printing.PrintJobOrientation;
var myPrintJob:PrintJob = new PrintJob();
myPrintJob.copies = 3;
myPrintJob.firstPage = 1;
myPrintJob.lastPage = 3;
myPrintJob.orientation = PrintJobOrientation.LANDSCAPE;
The following read-only settings associated with PrintJob provide helpful information on the current printer setup:
•
paperArea: The rectangular bounds of the printer medium, in points.
•
printableArea: The rectangular bounds of the printable area, in points.
•
maxPixelsPerInch: The physical resolution of the current printer, in pixels per inch.
•
isColor: The ability of the current printer to print color (returns true if the current printer can print color).
See “Printing example: Page setup and print options” on page 908.
Printing example: Multiple-page printing
Flash Player 9 and later, Adobe AIR 1.0 and later
When printing more than one page of content, you can associate each page of content with a different sprite (in this
case, sheet1 and sheet2), and then use PrintJob.addPage() for each sprite. The following code illustrates this
technique:
Last updated 3/21/2011
905
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Printing
package
{
import
import
import
import
import
import
import
flash.display.MovieClip;
flash.printing.PrintJob;
flash.printing.PrintJobOrientation;
flash.display.Stage;
flash.display.Sprite;
flash.text.TextField;
flash.geom.Rectangle;
public class PrintMultiplePages extends MovieClip
{
private var sheet1:Sprite;
private var sheet2:Sprite;
public function PrintMultiplePages():void
{
init();
printPages();
}
private function init():void
{
sheet1 = new Sprite();
createSheet(sheet1, "Once upon a time...", {x:10, y:50, width:80, height:130});
sheet2 = new Sprite();
createSheet(sheet2, "There was a great story to tell, and it ended quickly.\n\nThe
end.", null);
}
private function createSheet(sheet:Sprite, str:String, imgValue:Object):void
{
sheet.graphics.beginFill(0xEEEEEE);
sheet.graphics.lineStyle(1, 0x000000);
sheet.graphics.drawRect(0, 0, 100, 200);
sheet.graphics.endFill();
var txt:TextField = new TextField();
txt.height = 200;
txt.width = 100;
txt.wordWrap = true;
txt.text = str;
if (imgValue != null)
{
var img:Sprite = new Sprite();
img.graphics.beginFill(0xFFFFFF);
img.graphics.drawRect(imgValue.x, imgValue.y, imgValue.width, imgValue.height);
img.graphics.endFill();
sheet.addChild(img);
}
sheet.addChild(txt);
}
private function printPages():void
{
var pj:PrintJob = new PrintJob();
Last updated 3/21/2011
906
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Printing
var pagesToPrint:uint = 0;
if (pj.start())
{
if (pj.orientation == PrintJobOrientation.LANDSCAPE)
{
throw new Error("Page is not set to an orientation of portrait.");
}
sheet1.height = pj.pageHeight;
sheet1.width = pj.pageWidth;
sheet2.height = pj.pageHeight;
sheet2.width = pj.pageWidth;
try
{
pj.addPage(sheet1);
pagesToPrint++;
}
catch (error:Error)
{
// Respond to error.
}
try
{
pj.addPage(sheet2);
pagesToPrint++;
}
catch (error:Error)
{
// Respond to error.
}
if (pagesToPrint > 0)
{
pj.send();
}
}
}
}
}
Printing example: Scaling, cropping, and responding
Flash Player 9 and later, Adobe AIR 1.0 and later
In some cases, you want to adjust the size (or other properties) of a display object when printing it to accommodate
differences between the way it appears on screen and the way it appears printed on paper. When you adjust the
properties of a display object before printing (for example, by using the scaleX and scaleY properties), be aware that
if the object scales larger than the defined rectangle for the print area, the object is cropped. You will also probably
want to reset the properties after the pages have been printed.
Last updated 3/21/2011
907
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Printing
The following code scales the dimensions of the txt display object (but not the green box background), and the text
field ends up cropped by the dimensions of the specified rectangle. After printing, the text field is returned to its
original size for display on screen. If the user cancels the print job from the operating system’s Print dialog box, the
content in the Flash runtime changes to alert the user that the job has been canceled.
package
{
import
import
import
import
import
flash.printing.PrintJob;
flash.display.Sprite;
flash.text.TextField;
flash.display.Stage;
flash.geom.Rectangle;
public class PrintScaleExample extends Sprite
{
private var bg:Sprite;
private var txt:TextField;
public function PrintScaleExample():void
{
init();
draw();
printPage();
}
private function printPage():void
{
var pj:PrintJob = new PrintJob();
txt.scaleX = 3;
txt.scaleY = 2;
if (pj.start())
{
trace(">> pj.orientation: " + pj.orientation);
trace(">> pj.pageWidth: " + pj.pageWidth);
trace(">> pj.pageHeight: " + pj.pageHeight);
trace(">> pj.paperWidth: " + pj.paperWidth);
trace(">> pj.paperHeight: " + pj.paperHeight);
try
{
pj.addPage(this, new Rectangle(0, 0, 100, 100));
}
catch (error:Error)
{
// Do nothing.
}
pj.send();
}
else
{
txt.text
}
// Reset the
txt.scaleX =
txt.scaleY =
= "Print job canceled";
txt scale properties.
1;
1;
}
Last updated 3/21/2011
908
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Printing
private function init():void
{
bg = new Sprite();
bg.graphics.beginFill(0x00FF00);
bg.graphics.drawRect(0, 0, 100, 200);
bg.graphics.endFill();
txt = new TextField();
txt.border = true;
txt.text = "Hello World";
}
private function draw():void
{
addChild(bg);
addChild(txt);
txt.x = 50;
txt.y = 50;
}
}
}
Printing example: Page setup and print options
Adobe AIR 2 and later
The following example initializes the PrintJob settings for number of copies, paper size (legal), and page orientation
(landscape). It forces the Page Setup dialog to be displayed first, then starts the print job by displaying the Print dialog.
package
{
import
import
import
import
import
import
import
import
flash.printing.PrintJob;
flash.printing.PrintJobOrientation;
flash.printing.PaperSize;
flash.printing.PrintUIOptions;
flash.display.Sprite;
flash.text.TextField;
flash.display.Stage;
flash.geom.Rectangle;
public class PrintAdvancedExample extends Sprite
{
private var bg:Sprite = new Sprite();
private var txt:TextField = new TextField();
private var pj:PrintJob = new PrintJob();
private var uiOpt:PrintUIOptions = new PrintUIOptions();
public function PrintAdvancedExample():void
{
initPrintJob();
initContent();
draw();
printPage();
Last updated 3/21/2011
909
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Printing
}
private function printPage():void
{
//test for dialog support as a static property of PrintJob class
if (PrintJob.supportsPageSetupDialog)
{
pj.showPageSetupDialog();
}
if (pj.start2(uiOpt, true))
{
try
{
pj.addPage(this, new Rectangle(0, 0, 100, 100));
}
catch (error:Error)
{
// Do nothing.
}
pj.send();
}
else
{
txt.text = "Print job terminated";
pj.terminate();
}
}
private function initContent():void
{
bg.graphics.beginFill(0x00FF00);
bg.graphics.drawRect(0, 0, 100, 200);
bg.graphics.endFill();
txt.border = true;
txt.text = "Hello World";
}
private function initPrintJob():void
{
pj.selectPaperSize(PaperSize.LEGAL);
pj.orientation = PrintJobOrientation.LANDSCAPE;
pj.copies = 2;
pj.jobName = "Flash test print";
}
private function draw():void
{
addChild(bg);
addChild(txt);
txt.x = 50;
txt.y = 50;
}
}
}
Last updated 3/21/2011
910
Chapter 53: Geolocation
If a device supports geolocation, you can use the geolocation API to obtain the current geographical location of the
device. If the device supports this feature, you can obtain geolocation information. This information includes the
altitude, accuracy, heading, speed, and timestamp of the latest change in the location.
The Geolocation class dispatches update events in response to the device’s location sensor. The update event is a
GeolocationEvent object.
More Help topics
flash.sensors.Geolocation
flash.events.GeolocationEvent
Detecting geolocation changes
To use the geolocation sensor, instantiate a Geolocation object and register for update events it dispatches. The
update event is a Geolocation event object. The event has eight properties:
•
altitude—The altitude in meters.
•
heading—The direction of movement (with respect to true north) in degrees.
•
horizontalAccuracy—The horizontal accuracy in meters.
•
latitude—The latitude in degrees.
•
longitude—The longitude in degrees.
•
speed—The speed in meters per second.
•
timestamp—The number of milliseconds at the time of the event since the runtime was initialized.
•
verticalAccuracy—The vertical accuracy in meters.
The timestamp property is an int object. The others are Number objects.
Here is a basic example that displays geolocation data in a text field:
Last updated 3/21/2011
911
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Geolocation
var geo:Geolocation;
if (Geolocation.isSupported)
{
geo = new Geolocation();
geo.addEventListener(GeolocationEvent.UPDATE, updateHandler);
}
else
{
geoTextField.text = "Geolocation feature not supported";
}
function updateHandler(event:GeolocationEvent):void
{
geoTextField.text = "latitude: " + event.latitude.toString() + "\n"
+ "longitude: " + event.longitude.toString() + "\n"
+ "altitude: " + event.altitude.toString()
+ "speed: " + event.speed.toString()
+ "heading: " + event.heading.toString()
+ "horizontal accuracy: " + event.horizontalAccuracy.toString()
+ "vertical accuracy: " + event.verticalAccuracy.toString()
}
To use this example, be sure to create the geoTextField text field and add it to the display list before using this code.
You can adjust the desired time interval for geolocation events by calling the setRequestedUpdateInterval()
method of the Geolocation object. This method takes one parameter, interval, which is the requested update interval
in milliseconds:
var geo:Geolocation = new Geolocation();
geo.setRequestedUpdateInterval(10000);
The actual time between geolocation updates may be greater or lesser than this value. Any change in the update interval
affects all registered listeners. If you don’t call the setRequestedUpdateInterval() method, the application receives
updates based on the device's default interval.
The user can prevent an application from accessing geolocation data. For example, the iPhone prompts the user when
an application attempts to obtain geolocation data. In response to the prompt, the user can deny the application access
to geolocation data. The Geolocation object dispatches a status event when the user makes access to geolocation data
unavailable. Also, the Geolocation object has a muted property, which is set to true when the geolocation sensor is
unavailable. The Geolocation object dispatches a status event when the muted property changes. The following code
shows how to detect when geolocation data is unavailable:
Last updated 3/21/2011
912
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Geolocation
var geo:Geolocation;
var latitude:Number;
var longitude:Number;
if (Geolocation.isSupported)
{
geo = new Geolocation();
if (!geo.muted)
{
geo.addEventListener(GeolocationEvent.UPDATE, updateHandler);
geo.addEventListener(StatusEvent.STATUS, geoStatusHandler);
}
}
else
{
trace("not supported");
}
function updateHandler(event:GeolocationEvent):void
{
latitude = event.latitude;
longitude = event.longitude;
}
function geoStatusHandler(event:StatusEvent):void
{
geo.removeEventListener(GeolocationEvent.UPDATE, updateHandler);
}
Note: First-generation iPhones, which do not include a GPS unit, dispatch update events only occasionally. On these
devices, a Geolocation object initially dispatches one or two update events. It then dispatches update events when
information changes noticeably.
Checking geolocation support
Use the Geolocation.isSupported property to test the runtime environment for the ability to use this feature:
if (Geolocation.isSupported)
{
// Set up geolocation event listeners and code.
}
Currently, geolocation is only supported on ActionScript-based applications for the iPhone and in Flash Lite 4. If
Geolocation.isSupported is true at run time, then geolocation support exists.
Some iPhone models do not have a GPS unit. These models use other means (such as mobile phone triangulation) to
obtain geolocation data. For these models, or on any iPhone that has the GPS disabled, a Geolocation object may only
dispatch one or two initial update events.
Last updated 3/21/2011
913
Chapter 54: Internationalizing
applications
Flash Player 10.1 and later, Adobe AIR 2.0 and later
The flash.globalization package makes it easier to create international software that adapts to the conventions of
different languages and regions.
More Help topics
flash.globalization package
“Localizing applications” on page 930
Charles Bihis: Want to Localize your Flex/AIR Apps?
Basics of internationalizing applications
The terms globalization and internationalization are sometimes used interchangeably. But most definitions of these
terms say that globalization refers to a combination of business and engineering processes while internationalization
refers to engineering alone.
Here are some definitions for important terms:
Globalization A broad range of engineering and business processes needed for preparing and launching products and
company activities globally. Globalization consists of engineering activities like internationalization, localization and
culturization and business activities like product management, financial planning, marketing, and legal work.
Globalization is sometimes abbreviated as G11n (which stands for the letter G, then 11 more letters, and then the letter
n). “Globalization is what businesses do.”
Internationalization An engineering process for generalizing a product so that it can handle multiple languages,
scripts and cultural conventions (including currencies, sorting rules, number and date formats, and more) without the
need for redesign or recompilation. This process can be divided into two sets of activities: enablement and localization.
Internationalization is sometimes known as world-readiness, and sometimes abbreviated as I18n. “Internationalization
is what engineers do.”
Localization A process of adapting a product or service to a particular language, culture, and desired local appearance.
Localization is sometimes abbreviated as L10n. “Localization is what translators do.”
Culturization An engineering process for developing or adapting specific features for the unique needs of a culture.
Examples include the Japanese publishing features available in Adobe InDesign, and the Hanko support feature in
Adobe Acrobat.
Some other important internationalization terms can be defined as follows:
Character Set The characters used by a language or by a group of languages. A character set includes national
characters, special characters (such as punctuation marks and mathematical symbols), numeric digits, and computer
control characters.
Collation The sorting of text into a proper order for a given locale.
Last updated 3/21/2011
914
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Internationalizing applications
Locale A value that represents the language and cultural conventions used in a geographical, political, or cultural
region (which in many cases indicates a single country). A unique locale identifier (locale ID) represents this value.
The locale ID is used to look up a set of locale data that provides locale-specific support. This support applies to
measurement units, the parsing and formatting of numbers and dates, and so on.
Resource Bundle A stored set of locale-specific elements that are created for a locale in which an application is used.
A resource bundle typically contains all text elements in the application’s user interface. Within the bundle, these
elements are translated into the appropriate language for the given locale. It can also contain other settings that alter
the layout or behavior of the user interface for a specific locale. A resource bundle can contain other media types, or
references to other media types, that are locale-specific.
Overview of the flash.globalization package
Flash Player 10.1 and later, Adobe AIR 2.0 and later
The flash.globalization package harnesses the cultural support capabilities of the underlying operating system. It
makes it easier to write applications that follow the cultural conventions of individual users.
The main classes in the package include:
• The Collator class which governs the sorting and matching of strings
• The CurrencyFormatter class which formats numbers into currency amount strings, and parses currency amounts
and symbols from input strings
• The DateTimeFormatter class which formats date values
• The LocaleID class for retrieving information about a specific locale
• The NumberFormatter class which formats and parses numeric values
• The StringTools class which handles locale-sensitive case conversion of strings
The flash.globalization package and resource localization
The flash.globalization package doesn’t handle resource localization. However you can use the flash.globalization
locale ID as the key value for retrieving localized resources using other techniques. For example, you can localize
application resources built with Flex using the ResourceManager and ResourceBundle classes. For more information,
see Localizing Flex Applications.
Adobe AIR 1.1 also contains some features to help localize AIR applications, as discussed in “Localizing AIR
applications” on page 931.
A general approach to internationalizing an application
The following steps describe a high-level common approach for internationalizing an application using the
flash.globalization package:
1 Determine or set the locale.
2 Create an instance of a service class (Collator, CurrencyFormatter, DateTimeFormatter, NumberFormatter, or
StringTools).
3 Check for errors and fallbacks using lastOperationStatus properties.
4 Format and display information using locale-specific settings.
Last updated 3/21/2011
915
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Internationalizing applications
The next step is to load and display strings and user interface resources that are specific to the locale. This step can
include tasks such as:
• Using the autolayout features to resize the UI to accommodate the string lengths
• Choosing the right fonts and supporting font fallbacks
• Using the FTE text engine to support other writing systems
• Ensuring that input method editors are correctly handled
Checking for errors and fallbacks
The flash.globalization service classes all follow a similar pattern for identifying errors. They also share a pattern for
falling back from an unavailable requested locale to one that the user’s operating system supports.
The following example shows how to check for errors and fallbacks when instantiating service classes. Each service
class has a lastOperationStatus property that indicates whether the most recent method call triggered their errors or
warnings.
var nf:NumberFormatter = new NumberFormatter("de-DE");
if(nf.lastOperationStatus != LastOperationStatus.NO_ERROR)
{
if(nf.lastOperationStatus == LastOperationStatus.USING_FALLBACK_WARNING)
{
// perform fallback logic here, if needed
trace("Warning - Fallback locale ID: " + nf.actualLocaleIDName);
}
else
{
// perform error handling logic here, if needed
trace("Error: " + nf.lastOperationStatus);
}
}
This example simply traces a message if a fallback locale ID is used, or if there is an error. Your application can perform
additional error handling logic, if needed. For example, you could display a message to the user or force the application
to use a specific, supported locale.
Determining the locale
Flash Player 10.1 and later, Adobe AIR 2.0 and later
A locale identifies a specific combination of language and cultural conventions for a country or region.
A locale identifier can be safely managed as a string. But you can use the LocaleID class to obtain additional
information related to a locale.
You create a LocaleID object as follows:
var locale:LocaleID = new LocaleID("es-MX");
After the LocaleID object is created, you can retrieve data about the locale ID. Use the getKeysAndValues(),
getLanguage(), getRegion(), getScript(), getVariant(), and isRightToLeft() methods, and the name
property.
Last updated 3/21/2011
916
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Internationalizing applications
The values retrieved from these methods and properties can reflect additional information that cannot be extracted
directly from the locale identifier about the locale.
When an application creates a locale-aware service, such as a date formatter, it must specify the intended locale. The
list of supported locales varies from one operating system to another; hence, the requested locale can be unavailable.
Flash Player first tries to match the language code of the locale that you requested. Then it tries to refine the locale by
finding a matching writing system (script) and region. For example:
var loc:LocaleID = new LocaleID("es");
trace(loc.getLanguage()); // es
trace(loc.getScript()); // Latn
trace(loc.getRegion()); // ES
In this example, the LocaleID() constructor retrieved data about the locale that best matches the language code “es”
for that user.
Setting the locale ID
There are a number of ways to set the current locale for an application, including:
• Hard-code a single locale ID into the application. This approach is common, but it does not support
internationalization of the application.
• Use the locale ID preferences from the user’s operating system, or browser, or other user preferences. This
technique usually results in the best locale settings for the user, but it is not always accurate. There is a risk that the
operating system settings do not reflect the user’s actual preferences. For example, the user could be using a shared
computer and be unable to change the operating system’s preferred locales.
• After setting the locale ID based on the user’s preferences, let the user select from a list of supported locales. This
strategy is normally the best option if your application can support more than one locale.
You can implement this third option as follows:
1 Retrieve a list of the user’s preferred locales or languages from a user profile, browser settings, operating system
settings, or a cookie. (Your application would need to implement this logic itself. The flash.globalization library
does not support reading such preferences directly.)
2 Determine which of those locales your application supports and select the best one by default. Use the method
LocaleID.determinePreferredLocales() to find the best locales for a user based on their preferred locales and the
locales supported by the operating system.
3 Give the user a way to change the default locale setting in case the default locale is not satisfactory.
Limitations of other locale and language classes
The fl.lang.Locale class lets you replace text strings based on a locale, using resource bundles containing string
values. However this class does not support other internationalization features such as number, currency, or date
formatting, sorting and matching, and so on. In addition, this class is only available with Flash Professional.
You can also retrieve the current language code setting for the operating system using the
flash.system.Capabilities.language property. However, this property retrieves only the two-character ISO
639-1 language code—not the full locale ID—and it only supports a specific set of locales.
With AIR 1.5, you can use the flash.system.Capabilities.languages property. This property provides an array
of the user’s preferred user interface languages. Thus, it does not have the limitations of Capabilities.language.
Last updated 3/21/2011
917
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Internationalizing applications
Formatting numbers
Flash Player 10.1 and later, Adobe AIR 2.0 and later
The display format of numeric values varies widely from region to region. For example, here is how the number
123456.78 is formatted for certain locales:
Locale
Number Format
en-US (English, USA)
-123,456.78
de-DE (German, Germany)
-123.456,78
fr-FR (France, French)
-123 456,78
de-CH (German, Switzerland)
-123'456.78
en-IN (English, India)
-1,23,456.78
Many Arabic locales
123,456.78-
There are many factors that influence number formats, including:
• Separators. The decimal separator is placed between the integer and fractional portions of a number. It can be a
period, comma, or another character. The grouping separator or thousands separator can be a period, a comma, a
non-breaking space, or another character.
• Grouping patterns. The number of digits between each grouping separator to the left of the decimal point can be
two or three or another value.
• Negative number indicators. Negative numbers can be shown with a minus sign to the left or the right of the
number, or within parentheses for financial applications. For example, negative 19 can be shown as -19, 19-, or (19).
• Leading and trailing zeroes. Some cultural conventions add leading or trailing zeroes to displayed numbers. For
example the value 0.17 can be displayed as .17, 0.17, or 0.170, among other options.
• Sets of digit characters. Many languages, including Hindi, Arabic, and Japanese, use different sets of digit
characters. The flash.globalization package supports any digit character sets that map to the digits 0-9.
The NumberFormatter class considers all of these factors when formatting numeric values.
Using the NumberFormatter class
The NumberFormatter class formats numeric values (of type int, uint, or Number) according to the conventions of a
specific locale.
The following example shows the simplest way to format a number using the default formatting properties provided
by the user’s operating system:
var nf:NumberFormatter = new NumberFormatter(LocaleID.DEFAULT);
trace(nf.formatNumber(-123456.789))
The result vary based on the user’s locale settings and user preferences. For example, if the user’s locale is fr-FR then
the formatted value would be:
-123.456,789
If you only want to format a number for a specific locale, regardless of the user’s settings, set the locale name
specifically. For example:
Last updated 3/21/2011
918
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Internationalizing applications
var nf:NumberFormatter = new NumberFormatter("de-CH");
trace(nf.formatNumber(-123456.789));
The result in this case are:
-123'456.789
The formatNumber() method takes a Number as a parameter. The NumberFormatter class also has a formatInt()
method that takes an int as input, and a formatUint() method that takes a uint.
You can explicitly control the formatting logic by setting properties of the NumberFormatter class, as shown in this
example:
var nf:NumberFormatter = new NumberFormatter("de-CH");
nf.negativeNumberFormat = 0;
nf.fractionalDigits = 5;
nf.trailingZeros = true;
nf.decimalSeparator = ",";
nf.useGrouping = false;
trace(nf.formatNumber(-123456.789)); //(123456.78900)
This example first creates a NumberFormatter object and then:
• sets the negative number format to use parentheses (as in financial applications);
• sets the number of digits after the decimal separator to 5;
• specifies that trailing zeroes be used to ensure five decimal places;
• sets the decimal separator to a comma;
• tells the formatter not to use any grouping separators.
Note: When some of these properties change, the resulting number format no longer corresponds to the preferred format
for the specified locale. Use some of these properties only when locale-awareness is not important; when you need detailed
control over a single aspect of the format, such as the number of trailing zeroes; or when the user requests the change
directly, for example, through the Windows Control Panel.
Parsing strings that contain numeric values
The NumberFormatter class can also extract numeric values from strings that conform to locale-specific formatting
requirements. The NumberFormatter.parseNumber() method extracts a single numeric value from a string. For
example:
var nf:NumberFormatter = new NumberFormatter( "en-US" );
var inputNumberString:String = "-1,234,567.890"
var parsedNumber:Number = nf.parseNumber(inputNumberString);
trace("Value:" + parsedNumber); // -1234567.89
trace("Status:" + nf.lastOperationStatus); // noError
The parseNumber() method handles strings that contain only digits and number formatting characters such as
negative signs and separators. If the string contains other characters, an error code is set:
var nf:NumberFormatter = new NumberFormatter( "en-US" );
var inputNumberString:String = "The value is 1,234,567.890"
var parsedNumber:Number = nf.parseNumber(inputNumberString);
trace("Value:" + parsedNumber); // NaN
trace("Status:" + nf.lastOperationStatus); // parseError
To extract numbers from strings that contain additional alphabetic characters, use the NumberFormatter.parse()
method:
Last updated 3/21/2011
919
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Internationalizing applications
var nf:NumberFormatter = new NumberFormatter( "en-US" );
var inputNumberString:String = "The value is 123,456,7.890";
var parseResult:NumberParseResult = nf.parse(inputNumberString);
trace("Value:" + parseResult.value); // 1234567.89
trace("startIndex: " + parseResult.startIndex); // 14
trace("Status:" + nf.lastOperationStatus); // noError
The parse() method returns a NumberParseResult object that contains the parsed numeric value in its value property.
The startIndex property indicates the index of the first numeric character that was found. You can use the startIndex
and endIndex properties to extract the portions of the string that come before and after the digits.
Formatting currency values
Flash Player 10.1 and later, Adobe AIR 2.0 and later
The display formats of currency values vary as much as number formats do. For example, here is how the US dollar
value $123456.78 is formatted for certain locales:
Locale
Number Format
en-US (English, USA)
$123,456.78
de-DE (German, Germany)
123.456,78 $
en-IN (English, India)
$ 1,23,456.78
Currency formatting involves all the same factors as number formatting, plus these additional factors:
• Currency ISO code. The three letter ISO 4217 currency code for the actual locale being used, such as USD or EUR.
• Currency symbol. The currency symbol or string for the actual locale being used, such as $ or €.
• Negative currency format. Defines the location of the currency symbol and the negative symbol or parentheses in
relation to the numeric portion of the currency amount.
• Positive currency format. Defines the location of currency symbol relative to the numeric portion of the currency
amount.
Using the CurrencyFormatter class
The CurrencyFormatter class formats numeric values into strings that contain currency strings and formatted
numbers, according to the conventions of a specific locale.
When you instantiate a new CurrencyFormatter object, it sets its currency to the default currency for the given locale.
The following example shows that a CurrencyFormatter object created using a German locale assumes that currency
amounts are in Euros:
var cf:CurrencyFormatter = new CurrencyFormatter( "de-DE" );
trace(cf.format(1234567.89)); // 1.234.567,89 EUR
In most cases, do not rely on the default currency for a locale. If the user’s default locale is not supported, then the
CurrencyFormatter class assigns a fallback locale. The fallback locale can have a different default currency. In addition,
you normally want the currency formats to look correct to your user, even if the amounts are not in the user’s local
currency. For example, a Canadian user can want to see a German company’s prices in Euros, but formatted in the
Canadian style.
Last updated 3/21/2011
920
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Internationalizing applications
The CurrencyFormatter.setCurrency() method specifies the exact currency string and currency symbol to use.
The following example shows currency amounts in Euros to users in the French part of Canada:
var cf:CurrencyFormatter = new CurrencyFormatter( "fr-CA" );
cf.setCurrency("EUR", "€");
trace(cf.format(1234567.89)); // 1.234.567,89 EUR
The setCurrency() method can also be used to reduce confusion by setting unambiguous currency symbols. For
example:
cf.setCurrency("USD","US$");
By default the format() method displays a three character ISO 4217 currency code instead of the currency symbol. ISO
4217 codes are unambiguous and do not require localization. However many users prefer to see currency symbols
rather than ISO codes.
The CurrencyFormatter class can help you decide which symbol a formatted currency string uses: a currency symbol,
like a dollar sign or Euro sign, or a three character ISO currency string, such as USD or EUR. For example, an amount
in Canadian dollars could be displayed as $200 for a user in Canada. For a user in the United States, however, it could
be displayed as CAD 200. Use the method formattingWithCurrencySymbolIsSafe() to determine whether the
amount’s currency symbol would be ambiguous or incorrect given the user’s locale settings.
The following example formats a value in Euros into a format for the en-US locale. Depending on the user’s locale, the
output string uses either the ISO currency code or the currency symbol.
var cf:CurrencyFormatter = new CurrencyFormatter( "en-CA");
if (cf.formattingWithCurrencySymbolIsSafe("USD"))
{
trace(cf.format(1234567.89, true)); // $1,234,567.89
}
else
{
cf.setCurrency("USD", "$");
trace(cf.format(1234567.89)); // USD1,234,567.89
}
Parsing strings that contain currency values
The CurrencyFormatter class can also extract a currency amount and a currency string from an input string that
conforms to locale-specific formatting requirements. The CurrencyFormatter.parse() method stores the parsed
amount and currency string in a CurrencyParseResult object, as shown here:
var cf:CurrencyFormatter = new CurrencyFormatter( "en-US" );
var inputCurrencyString:String = "(GBP 123,56,7.890)";
var parseResult:CurrencyParseResult = cf.parse(inputCurrencyString);
trace("parsed amount: " + parseResult.value); // -1234567.89
trace("currencyString: " + parseResult.currencyString ); // GBP
The currency string portion of the input string can contain a currency symbol, a currency ISO code, and additional
text characters. The positions of the currency string, the negative number indicator, and the numeric value, match the
formats specified by the negativeCurrencyFormat and positiveCurrencyFormat properties. For example:
Last updated 3/21/2011
921
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Internationalizing applications
var cf:CurrencyFormatter = new CurrencyFormatter( "en-US" );
var inputCurrencyString:String = "Total $-123,56,7.890";
var parseResult:CurrencyParseResult = cf.parse(inputCurrencyString);
trace("status: " + cf.lastOperationStatus ); // parseError
trace("parsed amount: " + parseResult.value); // NaN
trace("currencyString: " + parseResult.currencyString ); //
cf.negativeCurrencyFormat = 2;
parseResult = cf.parse(inputCurrencyString);
trace("status: " + cf.lastOperationStatus ); // noError
trace("parsed amount: " + parseResult.value); // -123567.89
trace("currencyString: " + parseResult.currencyString ); // Total $
In this example, the input string has a currency string followed by a minus sign and a number. However the default
negativeCurrencyFormat value for the en-US locale specifies that the negative indicator comes first. As a result, the
parse() method generates an error and the parsed value is NaN.
After it sets the negativeCurrencyFormat to 2, which specifies that the currency string comes first, the parse() method
succeeds.
Formatting dates and times
Flash Player 10.1 and later, Adobe AIR 2.0 and later
The display format of date and time values also varies widely from region to region. For example, here is how the
second day of January, 1962 at 1:01 PM is displayed in a short format for certain locales:
Locale
Date and Time Format
en-US (English, USA)
1/2/62 1:01pm
fr-FR (France, French)
2/1/62 13:01
ja-JP (Japan, Japanese)
1962/2/1 13:01
Using the DateTimeFormatter class
The DateTimeFormatter class formats Date values into date and time strings according to the conventions of a specific
locale.
Formatting follows a pattern string which contains sequences of letters that are replaced with date or time values. For
example, in the pattern "yyyy/MM" the characters "yyyy" are replaced with a four-digit year, followed by a "/" character,
and a two-digit month.
The pattern string can be set explicitly using the setDateTimePattern() method. However it is best to let the pattern be
set automatically according to the user’s locale and operating system preferences. This practice helps assure that the
result is culturally appropriate.
The DateTimeFormatter can represent dates and times in three standard styles (LONG, MEDIUM, and SHORT) and
it can also use a CUSTOM pattern. One style can be used for the date, and a second style for the time. The actual
patterns used for each style vary somewhat by operating system.
You can specify the styles when you create a DateTimeFormatter object. If the style parameters are not specified, then
they are set to DateTimeStyle.LONG by default. You can change the styles later by using the setDateTimeStyles()
method, as shown in the following example:
Last updated 3/21/2011
922
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Internationalizing applications
var date:Date = new Date(2009, 2, 27, 13, 1);
var dtf:DateTimeFormatter = new DateTimeFormatter("en-US",
DateTimeStyle.LONG, DateTimeStyle.LONG);
var longDate:String = dtf.format(date);
trace(longDate); // March 27, 2009 1:01:00 PM
dtf.setDateTimeStyles(DateTimeStyle.SHORT, DateTimeStyle.SHORT);
var shortDate:String = dtf.format(date);
trace(shortDate); // 3/27/09 1:01 PM
Localizing month names and day names
Many applications use lists of month names and the names of the days of the week in calendar displays or pull-down
lists.
You can retrieve a localized list of the month names using the method DateTimeFormatter.getMonthNames().
Depending on the operating system, full and abbreviated forms might be available. Pass the value
DateTimeNameStyle.FULL to get full length month names. Pass the values
DateTimeNameStyle.LONG_ABBREVIATION or DateTimeNameStyle.SHORT_ABBREVIATION to get shorter
versions.
In some languages, a month name changes (into its genitive form) when it is placed next to the day value in a date
format. If you plan to use the month names alone, pass the value DateTimeNameContext.STANDALONE to the
getMonthNames() method. To use the month names in formatted dates, however, pass the value
DateTimeNameContext.FORMAT.
var dtf:DateTimeFormatter = new DateTimeFormatter("fr-FR");
var months:Vector. = dtf.getMonthNames(DateTimeNameStyle.FULL,
DateTimeNameContext.STANDALONE);
trace(months[0]); // janvier
months = dtf.getMonthNames(DateTimeNameStyle.SHORT_ABBREVIATION,
DateTimeNameContext.STANDALONE);
trace(months[0]); // janv.
The DateTimeFormatter.getWeekdayNames() method provides a localized list of the names of the days of the week.
The getWeekdayNames() method accepts the same nameStyle and context parameters that the getMonthNames()
method does.
var dtf:DateTimeFormatter = new DateTimeFormatter("fr-FR");
var weekdays:Vector. = dtf.getWeekdayNames(DateTimeNameStyle.FULL,
DateTimeNameContext.STANDALONE);
trace(weekdays[0]); // dimanche
weekdays = dtf.getWeekdayNames(DateTimeNameStyle.LONG_ABBREVIATION,
DateTimeNameContext.STANDALONE);
trace(weekdays[0]); // dim.
In addition, the getFirstWeekday() method returns the index value of the day that traditionally marks the beginning
of the week in the selected locale.
Last updated 3/21/2011
923
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Internationalizing applications
Sorting and comparing strings
Flash Player 10.1 and later, Adobe AIR 2.0 and later
Collation is the process of arranging things in their proper order. Collation rules vary significantly by locale. The rules
also differ if you are sorting a list or matching similar items, such as in a text search algorithm.
When sorting, small differences such as upper and lowercase letters or diacritic marks such as accents, are often
significant. For example, the letter ö (o with a diaeresis) is considered mostly equivalent to the plain letter o in French
or English. The same letter, however, follows the letter z in Swedish. Also, in French and some other languages, the last
accent difference in a word determines its order in a sorted list.
When searching, you often want to ignore differences in case or diacritics, to increase the chance of finding relevant
matches. For example, a search for the characters “cote” in a French document conceivably returns matches for “cote”,
“côte”, and “coté”.
Using the Collator class
The main methods of the Collator class are the compare() method, used primarily for sorting, and the equals() method,
used for matching values.
The following example shows the different behavior of the compare() and equals() methods.
var words:Array = new
Array("coté", "côte");
var sorter:Collator = new Collator("fr-FR", CollatorMode.SORTING);
words.sort(sorter.compare);
trace(words); // côte,coté
var matcher:Collator = new Collator("fr-FR", CollatorMode.MATCHING);
if (matcher.equals(words[0], words[1]))
{
trace(words[0] + " = " + words[1]); // côte = coté
}
The example first creates a Collator object in SORTING mode for the French-France locale. Then it sorts two words
that differ only by diacritical marks. This shows that the SORTING comparison distinguishes between accented and
non-accented characters.
The sorting is performed by passing a reference to the Collator object’s sort() method as a parameter to the Array.sort()
method. This technique is one of the most efficient ways of using a Collator object to control sort order.
The example then creates a Collator object in MATCHING mode. When that Collator object compares the two words, it
treats them as equal. That shows that the MATCHING comparison values accented and non-accented characters the same.
Customizing the behavior of the Collator class
By default, the Collator class uses string comparison rules obtained from the operating system based on the locale and
the user’s system preferences. You can customize the behavior of the compare() and equals() methods by explicitly
setting various properties. The following table lists the properties and the effect they have upon comparisons:
Last updated 3/21/2011
924
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Internationalizing applications
Collator Property
Effect
numericComparison
Controls whether digit characters are treated as numbers or as text.
ignoreCase
Controls whether uppercase and lowercase differences are ignored.
ignoreCharacterWidth
Controls whether full-width and half-width forms of some Chinese and Japanese characters are
evaluated as equal.
ignoreDiacritics
Controls whether strings that use the same base characters but different accents or other diacritic
marks are evaluated as equal.
ignoreKanaType
Controls whether strings that differ only by the type of kana character being used are treated as equal.
ignoreSymbols
Controls whether symbol characters such as spaces, currency symbols, math symbols, and others are
ignored.
The following code shows that setting the ignoreDiacritics property to true changes the sort order of a list of French
words:
var words:Array = new Array("COTE", "coté", "côte", "Coté","cote");
var sorter:Collator = new Collator("fr-CA", CollatorMode.SORTING);
words.sort(sorter.compare);
trace(words); // cote,COTE,côte,coté,Coté
sorter.ignoreDiacritics = true;
words.sort(sorter.compare);
trace(words); // côte,coté,cote,Coté,COTE
Case conversion
Flash Player 10.1 and later, Adobe AIR 2.0 and later
Languages also differ in their rules for converting letters between uppercase forms (majiscules) and lowercase forms
(miniscules).
For example, in most languages that use the Latin alphabet the lowercase form of the capital letter “I” is “i”. However
in some languages (such as Turkish and Azeri) there is an additional dotless letter “ı”. As a result in those languages a
lowercase dotless “ı” transforms into an uppercase ”I”. A lowercase “i” transforms into an uppercase “İ” with a dot.
The StringTools class provides methods that use language-specific rules to perform such transformations.
Using the StringTools class
The StringTools class provides two methods to perform case transformations: toLowerCase() and toUpperCase(). You
create a StringTools object by calling the constructor with a locale ID. The StringTools class retrieves the case
conversion rules for that locale (or a fallback locale) from the operating system. It is not possible to further customize
the case conversion algorithm.
The following example uses the toUpperCase() and toLowerCase() methods to transform a German phrase that
includes the letter “ß” (sharp S).
Last updated 3/21/2011
925
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Internationalizing applications
var phrase:String = "Schloß Neuschwanstein";
var converter:StringTools = new StringTools("de-DE");
var upperPhrase:String = converter.toUpperCase(phrase);
trace(upperPhrase); // SCHLOSS NEUSCHWANSTEIN
var lowerPhrase:String = converter.toLowerCase(upperPhrase);
trace(lowerPhrase);// schloss neuschwanstein
The toUpperCase() method transforms the lowercase letter “ß” into the uppercase letters “SS”. This transformation
works only in one direction. When the letters “SS” are transformed back to lowercase, the result is “ss” not “ß”.
Example: Internationalizing a stock ticker application
Flash Player 10.1 and later, Adobe AIR 2.0 and later
The Global Stock Ticker application retrieves and displays fictitious data about stocks in three different stock markets:
the United States, Japan, and Europe. It formats the data according to the conventions of various locales.
This example illustrates the following features of the flash.globalization package:
• Locale-aware number formatting
• Locale-aware currency formatting
• Setting currency ISO code and currency symbols
• Locale-aware date formatting
• Retrieving and displaying appropriate month name abbreviations
To get the application files for this sample, see www.adobe.com/go/learn_programmingAS3samples_flash. The Global
Stock Ticker application files can be found in the folder Samples/GlobalStockTicker. The application consists of the
following files:
File
Description
GlobalStockTicker.mxm The user interface for the application for Flex (MXML) or Flash (FLA).
l
or
GlobalStockTicker.fla
styles.css
Styles for the application user interface (Flex only).
com/example/program An MXML component that displays a chart of simulated stock data, for Flex only.
mingas3/stockticker/fle
x/FinGraph.mxml
com/example/program Document class containing the user interface logic for the application (Flash only).
mingas3/stockticker/fla
sh/GlobalStockTicker.as
comp/example/progra A custom cell renderer for the Flash DataGrid component (Flash only).
mmingas3/stockticker/f
lash/RightAlignedColu
mn.as
Last updated 3/21/2011
926
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Internationalizing applications
File
Description
com/example/program An ActionScript class that draws a chart of simulated stock data.
mingas3/stockticker/Fi
nancialGraph.as
com/example/program An ActionScript class that manages the locale and currency and handles the localized formatting of numbers,
mingas3/stockticker/Lo currency amounts, and dates.
calizer.as
com/example/program An ActionScript class that holds all the sample data for the Global Stock Ticker example.
mingas3/stockticker/St
ockDataModel.as
Understanding the user interface and sample data
The application’s main user interface elements are:
• a combo box for selecting a Locale
• a combo box for selecting a Market
• a DataGrid that displays data for six companies in each market
• a chart that shows simulated historical data for the selected company’s stock
The application stores all of its sample data about locales, markets, and company stocks in the StockDataModel class.
A real application would retrieve data from a server and then store it in a class like StockDataModel. In this example,
all the data is hard coded in the StockDataModel class.
Note: The data displayed in the financial chart doesn’t necessarily match the data shown in the DataGrid control. The
chart is randomly redrawn each time a different company is selected. It is for illustration purposes only.
Setting the locale
After some initial setup work, the application calls the method Localizer.setLocale() to create formatter objects for the
default locale. The setLocale() method is also called each time the user selects a new value from the Locale combo box.
public function setLocale(newLocale:String):void
{
locale = new LocaleID(newLocale);
nf = new NumberFormatter(locale.name);
traceError(nf.lastOperationStatus, "NumberFormatter", nf.actualLocaleIDName);
cf = new CurrencyFormatter(locale.name);
traceError(cf.lastOperationStatus, "CurrencyFormatter", cf.actualLocaleIDName);
symbolIsSafe = cf.formattingWithCurrencySymbolIsSafe(currentCurrency);
cf.setCurrency(currentCurrency, currentSymbol);
cf.fractionalDigits = currentFraction;
df = new DateTimeFormatter(locale.name, DateTimeStyle.LONG, DateTimeStyle.SHORT);
traceError(df.lastOperationStatus, "DateTimeFormatter", df.actualLocaleIDName);
monthNames = df.getMonthNames(DateTimeNameStyle.LONG_ABBREVIATION);
}
public function traceError(status:String, serviceName:String, localeID:String) :void
{
if(status != LastOperationStatus.NO_ERROR)
{
Last updated 3/21/2011
927
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Internationalizing applications
if(status == LastOperationStatus.USING_FALLBACK_WARNING)
{
trace("Warning - Fallback locale ID used by "
+ serviceName + ": " + localeID);
}
else if (status == LastOperationStatus.UNSUPPORTED_ERROR)
{
trace("Error in " + serviceName + ": " + status);
//abort application
throw(new Error("Fatal error", 0));
}
else
{
trace("Error in " + serviceName + ": " + status);
}
}
else
{
trace(serviceName + " created for locale ID: " + localeID);
}
}
First the setLocale() method creates a LocaleID object. This object makes it easier to get details about the actual locale
later, if needed.
Next it creates new NumberFormatter, CurrencyFormatter, and DateTimeFormatter objects for the locale. After
creating each formatter object it calls the traceError() method. This method displays error and warning messages in
the console if there is a problem with the requested locale. (A real application should react based on such errors rather
than just tracing them).
After creating the CurrencyFormatter object, the setLocale() method sets the formatter’s currency ISO code, currency
symbol, and fractionalDigits properties to previously determined values. (Those values are set each time the user
selects a new market from the Markets combo box).
After creating the DateTimeFormatter object, the setLocale() method also retrieves an array of localized month name
abbreviations.
Formatting the data
The formatted stock data is presented in a DataGrid control. The DataGrid columns each call a label function that
formats the column value using the appropriate formatter object.
In the Flash version, for example, the following code sets up the DataGrid columns:
Last updated 3/21/2011
928
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Internationalizing applications
var col1:DataGridColumn = new DataGridColumn("ticker");
col1.headerText = "Company";
col1.sortOptions = Array.NUMERIC;
col1.width = 200;
var col2:DataGridColumn = new DataGridColumn("volume");
col2.headerText = "Volume";
col2.width = 120;
col2.cellRenderer = RightAlignedCell;
col2.labelFunction = displayVolume;
var col3:DataGridColumn = new DataGridColumn("price");
col3.headerText = "Price";
col3.width = 70;
col3.cellRenderer = RightAlignedCell;
col3.labelFunction = displayPrice;
var col4:DataGridColumn = new DataGridColumn("change");
col4.headerText = "Change";
col4.width = 120;
col4.cellRenderer = RightAlignedCell;
col4.labelFunction = displayPercent;
The Flex version of the example declares its DataGrid in MXML. It also defines similar label functions for each column.
The labelFunction properties refer to the following functions, which call formatting methods of the Localizer class:
private function displayVolume(item:Object):String
{
return localizer.formatNumber(item.volume, 0);
}
private function displayPercent(item:Object):String
{
return localizer.formatPercent(item.change ) ;
}
private function displayPrice(item:Object):String
{
return localizer.formatCurrency(item.price);
}
The Localizer methods then set up and call the appropriate formatters:
Last updated 3/21/2011
929
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Internationalizing applications
public function formatNumber(value:Number, fractionalDigits:int = 2):String
{
nf.fractionalDigits = fractionalDigits;
return nf.formatNumber(value);
}
public function formatPercent(value:Number, fractionalDigits:int = 2):String
{
// HACK WARNING: The position of the percent sign, and whether a space belongs
// between it and the number, are locale-sensitive decisions. For example,
// in Turkish the positive format is %12 and the negative format is -%12.
// Like most operating systems, flash.globalization classes do not currently
// provide an API for percentage formatting.
nf.fractionalDigits = fractionalDigits;
return nf.formatNumber(value) + "%";
}
public function formatCurrency(value:Number):String
{
return cf.format(value, symbolIsSafe);
}
public function formatDate(dateValue:Date):String
{
return df.format(dateValue);
}
|
Last updated 3/21/2011
930
Chapter 55: Localizing applications
Flash Player 9 and later, Adobe AIR 1.0 and later
Localization is the process of including assets to support multiple locales. A locale is the combination of a language
and a country code. For example, en_US refers to the English language as spoken in the United States, and fr_FR refers
to the French language as spoken in France. To localize an application for these locales, you would provide two sets of
assets: one for the en_US locale and one for the fr_FR locale.
Locales can share languages. For example, en_US and en_GB (Great Britain) are different locales. In this case, both
locales use the English language, but the country code indicates that they are different locales, and might therefore use
different assets. For example, an application in the en_US locale might spell the word "color", whereas the word would
be "colour" in the en_GB locale. Also, units of currency would be represented in dollars or pounds, depending on the
locale, and the format of dates and times might also be different.
You can also provide a set of assets for a language without specifying a country code. For example, you can provide en
assets for the English language and provide additional assets for the en_US locale, specific to U.S. English.
Localization goes beyond just translating strings used in your application. It can also include any type of asset such as
audio files, images, and videos.
Choosing a locale
Flash Player 9 and later, Adobe AIR 1.0 and later
To determine which locale your content or application uses, you can use one of the following methods:
• flash.globalization package — Use the locale-aware classes in the flash.globalization package to retrieve the default
locale for the user based on the operating system and user preferences. This is the preferred approach for
applications that will run on the Flash Player 10.1 or later or AIR 2.0 or later runtimes. See “Determining the locale”
on page 915 for more information.
• User prompt — You can start the application in some default locale, and then ask the user to choose their preferred
locale.
•
(AIR only) Capabilities.languages — The Capabilities.languages property lists an array of languages
available on the user’s preferred languages, as set through the operating system. The strings contain language tags
(and script and region information, where applicable) defined by RFC4646 (http://www.ietf.org/rfc/rfc4646.txt).
The strings use hyphens as a delimiter (for example, "en-US" or "ja-JP"). The first entry in the returned array has
the same primary language ID as the language property. For example, if languages[0] is set to "en-US", then the
language property is set to "en". However, if the language property is set to "xu" (specifying an unknown
language), the first element in the languages array is different.
•
Capabilities.language — The Capabilities.language property provides the user interface language code of
the operating system. However, this property is limited to 20 known languages. And on English systems, this
property returns only the language code, not the country code. For these reasons, it is better to use the first element
in the Capabilities.languages array.
Last updated 3/21/2011
931
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Localizing applications
Localizing Flex content
Flash Player 9 and later, Adobe AIR 1.0 and later
Adobe Flex includes a framework for localizing Flex content. This framework includes the Locale, ResourceBundle,
and ResourceManagerImpl classes, as well as the IResourceBundle, IResourceManagerImpl interfaces.
A Flex localization library containing utility classes for sorting application locales is available on Google Code
(http://code.google.com/p/as3localelib/).
More Help topics
http://code.google.com/p/as3localelib/
Localizing Flash content
Flash Player 9 and later, Adobe AIR 1.0 and later
Adobe Flash Professional includes a Locale class in the ActionScript 3.0 components. The Locale class allows you to
control how a SWF file displays multilanguage text. The Flash Strings panel allows you to use string IDs instead of
string literals in dynamic text fields. This facility allows you to create a SWF file that displays text loaded from a
language-specific XML file. For information on using the Locale class, see the ActionScript 3.0 Reference for the Adobe
Flash Platform.
Localizing AIR applications
Adobe AIR 1.0 and later
The AIR SDK provides an HTML Localization Framework (contained in an AIRLocalizer.js file). This framework
includes APIs that assist in working with multiple locales in an HTML-based application. An ActionScript library for
sorting locales is provided at http://code.google.com/p/as3localelib/.
More Help topics
http://code.google.com/p/as3localelib/
Localizing dates, times, and currencies
Flash Player 9 and later, Adobe AIR 1.0 and later
The way applications present dates, times, and currencies varies greatly for each locale. For example, the U.S. standard
for representing dates is month/day/year, whereas the European standard for representing dates is day/month/year.
Last updated 3/21/2011
932
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Localizing applications
You can write code to format dates, times, and currencies. For example, the following code converts a Date object into
month/day/year format or day/month/year format. if the locale variable (representing the locale) is set to "en_US",
the function returns month/day/year format. The example converts a Date object into day/month/year format for all
other locales:
function convertDate(date)
{
if (locale == "en_US")
{
return (date.getMonth() + 1) + "/" + date.getDate() + "/" + date.getFullYear();
}
else
{
return date.getDate() + "/" + (date.getMonth() + 1) + "/" + date.getFullYear();
}
}
ADOBE FLEX
The Flex framework includes controls for formatting dates, times, and currencies. These controls include the
DateFormatter and CurrencyFormatter controls.
• mx:DateFormatter
• mx:CurrencyFormatter
Last updated 3/21/2011
933
Chapter 56: About the HTML
environment
Adobe AIR 1.0 and later
Adobe® AIR® uses WebKit (www.webkit.org), also used by the Safari web browser, to parse, layout, and render HTML
and JavaScript content. Using the AIR APIs in HTML content is optional. You can program in the content of an
HTMLLoader object or HTML window entirely with HTML and JavaScript. Most existing HTML pages and
applications should run with few changes (assuming they use HTML, CSS, DOM, and JavaScript features compatible
with WebKit).
Important: New versions of the Adobe AIR runtime may include updated versions of WebKit. A WebKit update in a
new version of AIR may result in unexpected changes in a deployed AIR application. These changes may affect the
behavior or appearance of HTML content in an application. For example, improvements or corrections in WebKit
rendering may change the layout of elements in an application’s user interface. For this reason, it is highly
recommended that you provide an update mechanism in your application. Should you need to update your application
due to a change in the WebKit version included in AIR, the AIR update mechanism can prompt the user to install the
new version of your application.
The following table lists the version of WebKit used in each release of AIR. The closest corresponding release of the
Safari web browser is also given:
AIR version
1.0
1.1
1.5
2.0
2.5
2.6
WebKit version
420
523
526.9
531.9
531.9
531.9
Safari version
2.04
3.04
4.0 Beta
4.03
4.03
4.03
You can always determine the installed version of WebKit by examining the default user agent string returned by a
HTMLLoader object:
var htmlLoader:HTMLLoader = new HTMLLoader();
trace( htmlLoader.userAgent );
Keep in mind that the version of WebKit used in AIR is not identical to the open source version. Some features are not
supported in AIR and the AIR version can include security and bug fixes not yet available in the corresponding WebKit
version. See “WebKit features not supported in AIR” on page 948.
Because AIR applications run directly on the desktop, with full access to the file system, the security model for HTML
content is more stringent than the security model of a typical web browser. In AIR, only content loaded from the
application installation directory is placed in the application sandbox. The application sandbox has the highest level of
privilege and allows access to the AIR APIs. AIR places other content into isolated sandboxes based on where that
content came from. Files loaded from the file system go into a local sandbox. Files loaded from the network using the
http: or https: protocols go into a sandbox based on the domain of the remote server. Content in these non-application
sandboxes is prohibited from accessing any AIR API and runs much as it would in a typical web browser.
HTML content in AIR does not display SWF or PDF content if alpha, scaling, or transparency settings are applied. For
more information, see “Considerations when loading SWF or PDF content in an HTML page” on page 975 and
“Window transparency” on page 867.
Last updated 3/21/2011
934
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
About the HTML environment
More Help topics
Webkit DOM Reference
Safari HTML Reference
Safari CSS Reference
www.webkit.org
Overview of the HTML environment
Adobe AIR 1.0 and later
Adobe AIR provides a complete browser-like JavaScript environment with an HTML renderer, document object
model, and JavaScript interpreter. The JavaScript environment is represented by the AIR HTMLLoader class. In
HTML windows, an HTMLLoader object contains all HTML content, and is, in turn, contained within a
NativeWindow object. In SWF content, the HTMLLoader class, which extends the Sprite class, can be added to the
display list of a stage like any other display object. The Adobe® ActionScript® 3.0 properties of the class are described
in “Scripting the AIR HTML Container” on page 974 and also in the ActionScript 3.0 Reference for the Adobe Flash
Platform. In the Flex framework, the AIR HTMLLoader class is wrapped in a mx:HTML component. The mx:HTML
component extends the UIComponent class, so it can be used directly with other Flex containers. The JavaScript
environment within the mx:HTML component is otherwise identical.
About the JavaScript environment and its relationship to the AIR host
Adobe AIR 1.0 and later
The following diagram illustrates the relationship between the JavaScript environment and the AIR run-time
environment. Although only a single native window is shown, an AIR application can contain multiple windows. (And
a single window can contain multiple HTMLLoader objects.)
Last updated 3/21/2011
935
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
About the HTML environment
AIR Run-time Environment
NativeWindow
HTMLLoader
window
JavaScript
Environment
window
document
body
head
htmlLoader
nativeWindow
runtime
h1
div
table
p
The JavaScript environment has its own Document and Window objects. JavaScript code can interact with the AIR run-time environment
through the runtime, nativeWindow, and htmlLoader properties. 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.
The runtime property provides access to AIR API classes, allowing you to create new AIR objects as well as access class
(also called static) members. To access an AIR API, you add the name of the class, with package, to the runtime
property. For example, to create a File object, you would use the statement:
var file = new window.runtime.filesystem.File();
Note: The AIR SDK provides a JavaScript file, AIRAliases.js, that defines more convenient aliases for the most
commonly used AIR classes. When you import this file, you can use the shorter form air.Class instead of
window.runtime.package.Class. For example, you could create the File object with new air.File().
The NativeWindow object provides properties for controlling the desktop window. From within an HTML page, you
can access the containing NativeWindow object with the window.nativeWindow property.
The HTMLLoader object provides properties, methods, and events for controlling how content is loaded and
rendered. From within an HTML page, you can access the parent HTMLLoader object with the window.htmlLoader
property.
Last updated 3/21/2011
936
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
About the HTML environment
Important: Only pages installed as part of an application have the htmlLoader, nativeWindow, or runtime properties
and only when loaded as the top-level document. These properties are not added when a document is loaded into a frame
or iframe. (A child document can access these properties on the parent document as long as it is in the same security
sandbox. For example, a document loaded in a frame could access the runtime property of its parent with
parent.runtime.)
About security
Adobe AIR 1.0 and later
AIR executes all code within a security sandbox based on the domain of origin. Application content, which is limited
to content loaded from the application installation directory, is placed into the application sandbox. Access to the runtime environment and the AIR APIs are only available to HTML and JavaScript running within this sandbox. At the
same time, most dynamic evaluation and execution of JavaScript is blocked in the application sandbox after all
handlers for the page load event have returned.
You can map an application page into a non-application sandbox by loading the page into a frame or iframe and setting
the AIR-specific sandboxRoot and documentRoot attributes of the frame. By setting the sandboxRoot value to an
actual remote domain, you can enable the sandboxed content to cross-script content in that domain. Mapping pages
in this way can be useful when loading and scripting remote content, such as in a mash-up application.
Another way to allow application and non-application content to cross-script each other, and the only way to give nonapplication content access to AIR APIs, is to create a sandbox bridge. A parent-to-child bridge allows content in a child
frame, iframe, or window to access designated methods and properties defined in the application sandbox. Conversely,
a child-to-parent bridge allows application content to access designated methods and properties defined in the sandbox
of the child. Sandbox bridges are established by setting the parentSandboxBridge and childSandboxBridge
properties of the window object. For more information, see “HTML security in Adobe AIR” on page 1045 and “HTML
frame and iframe elements” on page 944.
About plug-ins and embedded objects
Adobe AIR 1.0 and later
AIR supports the Adobe® Acrobat® plug-in. Users must have Acrobat or Adobe® Reader® 8.1 (or better) to display PDF
content. The HTMLLoader object provides a property for checking whether a user’s system can display PDF. SWF file
content can also be displayed within the HTML environment, but this capability is built in to AIR and does not use an
external plug-in.
No other WebKit plug-ins are supported in AIR.
More Help topics
“HTML security in Adobe AIR” on page 1045
“HTML Sandboxes” on page 937
“HTML frame and iframe elements” on page 944
“JavaScript Window object” on page 942
“The XMLHttpRequest object” on page 938
“Adding PDF content in AIR” on page 518
Last updated 3/21/2011
937
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
About the HTML environment
AIR and WebKit
Adobe AIR 1.0 and later
Adobe AIR uses the open source WebKit engine, also used in the Safari web browser. AIR adds several extensions to
allow access to the runtime classes and objects as well as for security. In addition, WebKit itself adds features not
included in the W3C standards for HTML, CSS, and JavaScript.
Only the AIR additions and the most noteworthy WebKit extensions are covered here; for additional documentation
on non-standard HTML, CSS, and JavaScript, see www.webkit.org and developer.apple.com. For standards
information, see the W3C web site. Mozilla also provides a valuable general referenceon HTML, CSS, and DOM topics
(of course, the WebKit and Mozilla engines are not identical).
JavaScript in AIR
Flash Player 9 and later, Adobe AIR 1.0 and later
AIR makes several changes to the typical behavior of common JavaScript objects. Many of these changes are made to
make it easier to write secure applications in AIR. At the same time, these differences in behavior mean that some
common JavaScript coding patterns, and existing web applications using those patterns, might not always execute as
expected in AIR. For information on correcting these types of issues, see “Avoiding security-related JavaScript errors”
on page 954.
HTML Sandboxes
Adobe AIR 1.0 and later
AIR places content into isolated sandboxes according to the origin of the content. The sandbox rules are consistent
with the same-origin policy implemented by most web browsers, as well as the rules for sandboxes implemented by
the Adobe Flash Player. In addition, AIR provides a new application sandbox type to contain and protect application
content. See “Security sandboxes” on page 1010 for more information on the types of sandboxes you may encounter
when developing AIR applications.
Access to the run-time environment and AIR APIs are only available to HTML and JavaScript running within the
application sandbox. At the same time, however, dynamic evaluation and execution of JavaScript, in its various forms,
is largely restricted within the application sandbox for security reasons. These restrictions are in place whether or not
your application actually loads information directly from a server. (Even file content, pasted strings, and direct user
input may be untrustworthy.)
The origin of the content in a page determines the sandbox to which it is consigned. Only content loaded from the
application directory (the installation directory referenced by the app: URL scheme) is placed in the application
sandbox. Content loaded from the file system is placed in the local-with-file system or the local-trusted sandbox, which
allows access and interaction with content on the local file system, but not remote content. Content loaded from the
network is placed in a remote sandbox corresponding to its domain of origin.
To allow an application page to interact freely with content in a remote sandbox, the page can be mapped to the same
domain as the remote content. For example, if you write an application that displays map data from an Internet service,
the page of your application that loads and displays content from the service could be mapped to the service domain.
The attributes for mapping pages into a remote sandbox and domain are new attributes added to the frame and iframe
HTML elements.
Last updated 3/21/2011
938
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
About the HTML environment
To allow content in a non-application sandbox to safely use AIR features, you can set up a parent sandbox bridge. To
allow application content to safely call methods and access properties of content in other sandboxes, you can set up a
child sandbox bridge. Safety here means that remote content cannot accidentally get references to objects, properties,
or methods that are not explicitly exposed. Only simple data types, functions, and anonymous objects can be passed
across the bridge. However, you must still avoid explicitly exposing potentially dangerous functions. If, for example,
you exposed an interface that allowed remote content to read and write files anywhere on a user’s system, then you
might be giving remote content the means to do considerable harm to your users.
JavaScript eval() function
Adobe AIR 1.0 and later
Use of the eval() function is restricted within the application sandbox once a page has finished loading. Some uses
are permitted so that JSON-formatted data can be safely parsed, but any evaluation that results in executable
statements results in an error. “Code restrictions for content in different sandboxes” on page 1047 describes the
allowed uses of the eval() function.
Function constructors
Adobe AIR 1.0 and later
In the application sandbox, function constructors can be used before a page has finished loading. After all page load
event handlers have finished, new functions cannot be created.
Loading external scripts
Adobe AIR 1.0 and later
HTML pages in the application sandbox cannot use the script tag to load JavaScript files from outside of the
application directory. For a page in your application to load a script from outside the application directory, the page
must be mapped to a non-application sandbox.
The XMLHttpRequest object
Adobe AIR 1.0 and later
AIR provides an XMLHttpRequest (XHR) object that applications can use to make data requests. The following
example illustrates a simple data request:
xmlhttp = new XMLHttpRequest();
xmlhttp.open("GET", "http:/www.example.com/file.data", true);
xmlhttp.onreadystatechange = function() {
if (xmlhttp.readyState == 4) {
//do something with data...
}
}
xmlhttp.send(null);
In contrast to a browser, AIR allows content running in the application sandbox to request data from any domain. The
result of an XHR that contains a JSON string can be evaluated into data objects unless the result also contains
executable code. If executable statements are present in the XHR result, an error is thrown and the evaluation attempt
fails.
To prevent accidental injection of code from remote sources, synchronous XHRs return an empty result if made before
a page has finished loading. Asynchronous XHRs will always return after a page has loaded.
Last updated 3/21/2011
939
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
About the HTML environment
By default, AIR blocks cross-domain XMLHttpRequests in non-application sandboxes. A parent window in the
application sandbox can choose to allow cross-domain requests in a child frame containing content in a nonapplication sandbox by setting allowCrossDomainXHR, an attribute added by AIR, to true in the containing frame or
iframe element:
Because the sandboxRoot attribute remaps the root URL of the www.example.com address, all requests are loaded
from the application directory and not the remote server. Requests are remapped whether they derive from page
navigation or from an XMLHttpRequest.
To avoid accidentally blocking data requests to your remote server, map the sandboxRoot to a subdirectory of the
remote URL rather than the root. The directory does not have to exist. For example, to allow requests to the
www.example.com to load from the remote server rather than the application directory, change the previous iframe to
the following:
The ui.html page could load a javascript file from the local, sandbox folder using the following script tag:
It could also load content from a directory on the remote server using a script tag such as the following:
The sandboxRoot URL will mask any content at the same URL on the remote server. In the above example, you would
not be able to access any remote content at www.example.com/local/ (or any of its subdirectories) because AIR
remaps the request to the local application directory. Requests are remapped whether they derive from page
navigation, from an XMLHttpRequest, or from any other means of loading content.
Setting up a sandbox bridge interface
Adobe AIR 1.0 and later
You can use a sandbox bridge when content in the application sandbox must access properties or methods defined by
content in a non-application sandbox, or when non-application content must access properties and methods defined
by content in the application sandbox. Create a bridge with the childSandboxBridge and parentSandboxBridge
properties of the window object of any child document.
Establishing a child sandbox bridge
Adobe AIR 1.0 and later
The childSandboxBridge property allows the child document to expose an interface to content in the parent
document. To expose an interface, you set the childSandbox property to a function or object in the child document.
You can then access the object or function from content in the parent document. The following example shows how a
script running in a child document can expose an object containing a function and a property to its parent:
Last updated 3/21/2011
972
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Programming HTML and JavaScript in AIR
var interface = {};
interface.calculatePrice = function(){
return ".45 cents";
}
interface.storeID = "abc"
window.childSandboxBridge = interface;
If this child content was loaded into an iframe assigned an id of “child”, you could access the interface from parent
content by reading the childSandboxBridge property of the frame:
var childInterface = document.getElementById("child").contentWindow.childSandboxBridge;
air.trace(childInterface.calculatePrice()); //traces ".45 cents"
air.trace(childInterface.storeID)); //traces "abc"
Establishing a parent sandbox bridge
Adobe AIR 1.0 and later
The parentSandboxBridge property allows the parent document to expose an interface to content in a child
document. To expose an interface, the parent document sets the parentSandbox property of the child document to a
function or object defined in the parent document. You can then access the object or function from content in the
child. The following example shows how a script running in a parent frame can expose an object containing a function
to a child document:
var interface = {};
interface.save = function(text){
var saveFile = air.File("app-storage:/save.txt");
//write text to file
}
document.getElementById("child").contentWindow.parentSandboxBridge = interface;
Using this interface, content in the child frame could save text to a file named save.txt, but would not have any other
access to the file system. The child content could call the save function as follows:
var textToSave = "A string.";
window.parentSandboxBridge.save(textToSave);
Application content should expose the narrowest interface possible to other sandboxes. Non-application content
should be considered inherently untrustworthy since it may be subject to accidental or malicious code injection. You
must put appropriate safeguards in place to prevent misuse of the interface you expose through the parent sandbox
bridge.
Accessing a parent sandbox bridge during page loading
Adobe AIR 1.0 and later
In order for a script in a child document to access a parent sandbox bridge, the bridge must be set up before the script
is run. Window, frame and iframe objects dispatch a dominitialize event when a new page DOM has been created,
but before any scripts have been parsed, or DOM elements added. You can use the dominitialize event to establish
the bridge early enough in the page construction sequence that all scripts in the child document can access it.
The following example illustrates how to create a parent sandbox bridge in response to the dominitialize event
dispatched from the child frame:
Last updated 3/21/2011
973
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Programming HTML and JavaScript in AIR
The following child.html document illustrates how child content can access the parent sandbox bridge:
To listen for the dominitialize event on a child window, rather than a frame, you must add the listener to the new
child window object created by the window.open() function:
var childWindow = window.open();
childWindow.addEventListener("dominitialize", engageBridge());
childWindow.document.location = "http://www.example.com/air/child.html";
In this case, there is no way to map application content into a non-application sandbox. This technique is only useful
when child.html is loaded from outside the application directory. You can still map application content in the
window to a non-application sandbox, but you must first load an intermediate page that itself uses frames to load the
child document and map it to the desired sandbox.
If you use the HTMLLoader class createRootWindow() function to create a window, the new window is not a child
of the document from which createRootWindow() is called. Thus, you cannot create a sandbox bridge from the
calling window to non-application content loaded into the new window. Instead, you must use load an intermediate
page in the new window that itself uses frames to load the child document. You can then establish the bridge from the
parent document of the new window to the child document loaded into the frame.
Last updated 3/21/2011
974
Chapter 58: Scripting the AIR HTML
Container
Adobe AIR 1.0 and later
The HTMLLoader class serves as the container for HTML content in Adobe® AIR®. The class provides many properties
and methods, inherited from the Sprite class, for controlling the behavior and appearance of the object on the
ActionScript® 3.0 display list. In addition, the class defines properties and methods for such tasks as loading and
interacting with HTML content and managing history.
The HTMLHost class defines a set of default behaviors for an HTMLLoader. When you create an HTMLLoader object,
no HTMLHost implementation is provided. Thus when HTML content triggers one of the default behaviors, such as
changing the window location, or the window title, nothing happens. You can extend the HTMLHost class to define
the behaviors desired for your application.
A default implementation of the HTMLHost is provided for HTML windows created by AIR. You can assign the
default HTMLHost implementation to another HTMLLoader object by setting the htmlHost property of the object
using a new HTMLHost object created with the defaultBehavior parameter set to true.
Note: In the Adobe® Flex™ Framework, the HTMLLoader object is wrapped by the mx:HTML component. When using
Flex, use the HTML component.
Display properties of HTMLLoader objects
Adobe AIR 1.0 and later
An HTMLLoader object inherits the display properties of the Adobe® Flash® Player Sprite class. You can resize, move,
hide, and change the background color, for example. Or you can apply advanced effects like filters, masks, scaling, and
rotation. When applying effects, consider the impact on legibility. SWF and PDF content loaded into an HTML page
cannot be displayed when some effects are applied.
HTML windows contain an HTMLLoader object that renders the HTML content. This object is constrained within
the area of the window, so changing the dimensions, position, rotation, or scale factor does not always produce
desirable results.
Basic display properties
Adobe AIR 1.0 and later
The basic display properties of the HTMLLoader allow you to position the control within its parent display object, to
set the size, and to show or hide the control. You should not change these properties for the HTMLLoader object of an
HTML window.
The basic properties include:
Last updated 3/21/2011
975
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Scripting the AIR HTML Container
Property
Notes
x, y
Positions the object within its parent container.
width, height
Changes the dimensions of the display area.
visible
Controls the visibility of the object and any content it contains.
Outside an HTML window, the width and height properties of an HTMLLoader object default to 0. You must set the
width and height before the loaded HTML content can be seen. HTML content is drawn to the HTMLLoader size, laid
out according to the HTML and CSS properties in the content. Changing the HTMLLoader size reflows the content.
When loading content into a new HTMLLoader object (with width still set to 0), it can be tempting to set the display
width and height of the HTMLLoader using the contentWidth and contentHeight properties. This technique
works for pages that have a reasonable minimum width when laid out according the HTML and CSS flow rules.
However, some pages flow into a long and narrow layout in the absence of a reasonable width provided by the
HTMLLoader.
Note: When you change the width and height of an HTMLLoader object, the scaleX and scaleY values do not change, as
would happen with most other types of display objects.
Transparency of HTMLLoader content
Adobe AIR 1.0 and later
The paintsDefaultBackground property of an HTMLLoader object, which is true by default, determines whether
the HTMLLoader object draws an opaque background. When paintsDefaultBackground is false, the background
is clear. The display object container or other display objects below the HTMLLoader object are visible behind the
foreground elements of the HTML content.
If the body element or any other element of the HTML document specifies a background color (using
style="background-color:gray", for example), then the background of that portion of the HTML is opaque and
rendered with the specified background color. If you set the opaqueBackground property of the HTMLLoader object,
and paintsDefaultBackground is false, then the color set for the opaqueBackground is visible.
Note: You can use a transparent, PNG-format graphic to provide an alpha-blended background for an element in an
HTML document. Setting the opacity style of an HTML element is not supported.
Scaling HTMLLoader content
Adobe AIR 1.0 and later
Avoid scaling an HTMLLoader object beyond a scale factor of 1.0. Text in HTMLLoader content is rendered at a
specific resolution and appears pixelated if the HTMLLoader object is scaled up. To prevent the HTMLLoader, as well
as its contents, from scaling when a window is resized, set the scaleMode property of the Stage to
StageScaleMode.NO_SCALE.
Considerations when loading SWF or PDF content in an HTML page
Adobe AIR 1.0 and later
SWF and PDF content loaded into in an HTMLLoader object disappears in the following conditions:
• If you scale the HTMLLoader object to a factor other that 1.0.
Last updated 3/21/2011
976
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Scripting the AIR HTML Container
• If you set the alpha property of the HTMLLoader object to a value other than 1.0.
• If you rotate the HTMLLoader content.
The content reappears if you remove the offending property setting and remove the active filters.
In addition, the runtime cannot display PDF content in transparent windows. The runtime only displays SWF content
embedded in an HTML page when the wmode parameter of the object or embed tag is set to opaque or transparent.
Since the default value of wmode is window, SWF content is not displayed in transparent windows unless you explicitly
set the wmode parameter.
Note: Prior to AIR 1.5.2, SWF embedded in HTML could not be displayed no matter which wmode value was used.
For more information on loading these types of media in an HTMLLoader, see “Embedding SWF content in HTML”
on page 963and “Adding PDF content in AIR” on page 518.
Advanced display properties
Adobe AIR 1.0 and later
The HTMLLoader class inherits several methods that can be used for special effects. In general, these effects have
limitations when used with the HTMLLoader display, but they can be useful for transitions or other temporary effects.
For example, if you display a dialog window to gather user input, you could blur the display of the main window until
the user closes the dialog. Likewise, you could fade the display out when closing a window.
The advanced display properties include:
Property
Limitations
alpha
Can reduce the legibility of HTML content
filters
In an HTML Window, exterior effects are clipped by the window edge
graphics
Shapes drawn with graphics commands appear below HTML content,
including the default background. The paintsDefaultBackground property
must be false for the drawn shapes to be visible.
opaqueBackground
Does not change the color of the default background. The
paintsDefaultBackground property must be false for this color layer to be
visible.
rotation
The corners of the rectangular HTMLLoader area can be clipped by the
window edge. SWF and PDF content loaded in the HTML content is not
displayed.
scaleX, scaleY
The rendered display can appear pixelated at scale factors greater than 1. SWF
and PDF content loaded in the HTML content is not displayed.
transform
Can reduce legibility of HTML content. The HTML display can be clipped by the
window edge. SWF and PDF content loaded in the HTML content is not
displayed if the transform involves rotation, scaling, or skewing.
The following example illustrates how to set the filters array to blur the entire HTML display:
Last updated 3/21/2011
977
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Scripting the AIR HTML Container
var html:HTMLLoader = new HTMLLoader();
var urlReq:URLRequest = new URLRequest("http://www.adobe.com/");
html.load(urlReq);
html.width = 800;
html.height = 600;
var blur:BlurFilter = new BlurFilter(8);
var filters:Array = [blur];
html.filters = filters;
Scrolling HTML content
Adobe AIR 1.0 and later
The HTMLLoader class includes the following properties that let you control the scrolling of HTML content:
Property
Description
contentHeight
The height, in pixels, of the HTML content.
contentWidth
The width, in pixels, of the HTML content.
scrollH
The horizontal scroll position of the HTML content within the HTMLLoader object.
scrollV
The vertical scroll position of the HTML content within the HTMLLoader object.
The following code sets the scrollV property so that HTML content is scrolled to the bottom of the page:
var html:HTMLLoader = new HTMLLoader();
html.addEventListener(Event.HTML_BOUNDS_CHANGE, scrollHTML);
const SIZE:Number = 600;
html.width = SIZE;
html.height = SIZE;
var urlReq:URLRequest = new URLRequest("http://www.adobe.com");
html.load(urlReq);
this.addChild(html);
function scrollHTML(event:Event):void
{
html.scrollV = html.contentHeight - SIZE;
}
The HTMLLoader does not include horizontal and vertical scroll bars. You can implement scroll bars in ActionScript
or by using a Flex component. The Flex HTML component automatically includes scroll bars for HTML content. You
can also use the HTMLLoader.createRootWindow() method to create a window that contains an HTMLLoader object
with scroll bars (see “Creating windows with scrolling HTML content” on page 989).
Last updated 3/21/2011
978
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Scripting the AIR HTML Container
Accessing the HTML history list
Adobe AIR 1.0 and later
As new pages are loaded in an HTMLLoader object, the runtime maintains a history list for the object. The history list
corresponds to the window.history object in the HTML page. The HTMLLoader class includes the following
properties and methods that let you work with the HTML history list:
Class member
Description
historyLength
The overall length of the history list, including back and forward entries.
historyPosition
The current position in the history list. History items before this position represent “back” navigation, and
items after this position represent “forward” navigation.
getHistoryAt()
Returns the URLRequest object corresponding to the history entry at the specified position in the history list.
historyBack()
Navigates back in the history list, if possible.
historyForward()
Navigates forward in the history list, if possible.
historyGo()
Navigates the indicated number of steps in the browser history. Navigates forward if positive, backward if
negative. Navigating to zero reloads the page. Specifying a position beyond the end navigates to the end of
the list.
Items in the history list are stored as objects of type HTMLHistoryItem. The HTMLHistoryItem class has the following
properties:
Property
Description
isPost
Set to true if the HTML page includes POST data.
originalUrl
The original URL of the HTML page, before any redirects.
title
The title of the HTML page.
url
The URL of the HTML page.
Setting the user agent used when loading HTML content
Adobe AIR 1.0 and later
The HTMLLoader class has a userAgent property, which lets you set the user agent string used by the HTMLLoader.
Set the userAgent property of the HTMLLoader object before calling the load() method. If you set this property on
the HTMLLoader instance, then the userAgent property of the URLRequest passed to the load() method is not used.
You can set the default user agent string used by all HTMLLoader objects in an application domain by setting the
URLRequestDefaults.userAgent property. The static URLRequestDefaults properties apply as defaults for all
URLRequest objects, not only URLRequests used with the load() method of HTMLLoader objects. Setting the
userAgent property of an HTMLLoader overrides the default URLRequestDefaults.userAgent setting.
Last updated 3/21/2011
979
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Scripting the AIR HTML Container
If you do not set a user agent value for either the userAgent property of the HTMLLoader object or for
URLRequestDefaults.userAgent, then the default AIR user agent value is used. This default value varies depending
on the runtime operating system (such as Mac OS or Windows), the runtime language, and the runtime version, as in
the following two examples:
•
"Mozilla/5.0 (Macintosh; U; PPC Mac OS X; en) AppleWebKit/420+ (KHTML, like Gecko)
AdobeAIR/1.0"
•
"Mozilla/5.0 (Windows; U; en) AppleWebKit/420+ (KHTML, like Gecko) AdobeAIR/1.0"
Setting the character encoding to use for HTML content
Adobe AIR 1.0 and later
An HTML page can specify the character encoding it uses by including meta tag, such as the following:
meta http-equiv="content-type" content="text/html" charset="ISO-8859-1";
Override the page setting to ensure that a specific character encoding is used by setting the textEncodingOverride
property of the HTMLLoader object:
var html:HTMLLoader = new HTMLLoader();
html.textEncodingOverride = "ISO-8859-1";
Specify the character encoding for the HTMLLoader content to use when an HTML page does not specify a setting
with the textEncodingFallback property of the HTMLLoader object:
var html:HTMLLoader = new HTMLLoader();
html.textEncodingFallback = "ISO-8859-1";
The textEncodingOverride property overrides the setting in the HTML page. And the textEncodingOverride
property and the setting in the HTML page override the textEncodingFallback property.
Set the textEncodingOverride property or the textEncodingFallback property before loading the HTML
content.
Defining browser-like user interfaces for HTML content
Adobe AIR 1.0 and later
JavaScript provides several APIs for controlling the window displaying the HTML content. In AIR, these APIs can be
overridden by implementing a custom HTMLHost class.
Last updated 3/21/2011
980
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Scripting the AIR HTML Container
About extending the HTMLHost class
Adobe AIR 1.0 and later
If, for example, your application presents multiple HTMLLoader objects in a tabbed interface, you may want title
changes made by the loaded HTML pages to change the label of the tab, not the title of the main window. Similarly,
your code could respond to a window.moveTo() call by repositioning the HTMLLoader object in its parent display
object container, by moving the window that contains the HTMLLoader object, by doing nothing at all, or by doing
something else entirely.
The AIR HTMLHost class controls the following JavaScript properties and methods:
•
window.status
•
window.document.title
•
window.location
•
window.blur()
•
window.close()
•
window.focus()
•
window.moveBy()
•
window.moveTo()
•
window.open()
•
window.resizeBy()
•
window.resizeTo()
When you create an HTMLLoader object using new HTMLLoader(), the listed JavaScript properties or methods are
not enabled. The HTMLHost class provides a default, browser-like implementation of these JavaScript APIs. You can
also extend the HTMLHost class to customize the behavior. To create an HTMLHost object supporting the default
behavior, set the defaultBehaviors parameter to true in the HTMLHost constructor:
var defaultHost:HTMLHost = new HTMLHost(true);
When you create an HTML window in AIR with the HTMLLoader class createRootWindow() method, an
HTMLHost instance supporting the default behaviors is assigned automatically. You can change the host object
behavior by assigning a different HTMLHost implementation to the htmlHost property of the HTMLLoader, or you
can assign null to disable the features entirely.
Note: AIR assigns a default HTMLHost object to the initial window created for an HTML-based AIR application and
any windows created by the default implementation of the JavaScript window.open() method.
Example: Extending the HTMLHost class
Adobe AIR 1.0 and later
The following example shows how to customize the way that an HTMLLoader object affects the user interface, by
extending the HTMLHost class:
Flex example:
1 Create a class that extends the HTMLHost class (a subclass).
Last updated 3/21/2011
981
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Scripting the AIR HTML Container
2 Override methods of the new class to handle changes in the user interface-related settings. For example, the
following class, CustomHost, defines behaviors for calls to window.open() and changes to
window.document.title. Calls to window.open() open the HTML page in a new window, and changes to
window.document.title (including the setting of the element of an HTML page) set the title of that
window.
package
{
import
import
import
import
flash.html.*;
flash.display.StageScaleMode;
flash.display.NativeWindow;
flash.display.NativeWindowInitOptions;
public class CustomHost extends HTMLHost
{
import flash.html.*;
override public function
createWindow(windowCreateOptions:HTMLWindowCreateOptions):HTMLLoader
{
var initOptions:NativeWindowInitOptions = new NativeWindowInitOptions();
var bounds:Rectangle = new Rectangle(windowCreateOptions.x,
windowCreateOptions.y,
windowCreateOptions.width,
windowCreateOptions.height);
var htmlControl:HTMLLoader = HTMLLoader.createRootWindow(true, initOptions,
windowCreateOptions.scrollBarsVisible, bounds);
htmlControl.htmlHost = new HTMLHostImplementation();
if(windowCreateOptions.fullscreen){
htmlControl.stage.displayState =
StageDisplayState.FULL_SCREEN_INTERACTIVE;
}
return htmlControl;
}
override public function updateTitle(title:String):void
{
htmlLoader.stage.nativeWindow.title = title;
}
}
}
3 In the code that contains the HTMLLoader (not the code of the new subclass of HTMLHost), create an object of
the new class. Assign the new object to the htmlHost property of the HTMLLoader. The following Flex code uses
the CustomHost class defined in the previous step:
Last updated 3/21/2011
982
ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Scripting the AIR HTML Container
<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication
xmlns:mx="http://www.adobe.com/2006/mxml"
layout="vertical"
applicationComplete="init()">
<mx:Script>
<![CDATA[
import flash.html.HTMLLoader;
import CustomHost;
private function init():void
{
var html:HTMLLoader = new HTMLLoader();
html.width = container.width;
html.height = container.height;
var urlReq:URLRequest = new URLRequest("Test.html");
html.htmlHost = new CustomHost();
html.load(urlReq);
container.addChild(html);
}
]]>
</mx:Script>
<mx:UIComponent id="container" width="100%" height="100%"/>
</mx:WindowedApplication>
To test the code described here, include an HTML file with the following content in the application directory:
<html>
<head>
<title>Testwindow.open('Test.html')
.