Macromedia Air - 1.5 User Manual

Developing Adobe® AIR

HTML and Ajax

™

1.5 Applications with

Last updated 12/9/2009

If this guide is distributed with software that includes an end user agreement, this guide, as well as the software described in it, is furnished under license and may be used or copied only in accordance with the terms of such license. Except as permitted by any such license, no part of this guide may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written permission of Adobe Systems Incorporated. Please note that the content in this guide is protected under copyright law even if it is not distributed with software that includes an end user license agreement.

The content of this guide is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in the informational content contained in this guide.

Please remember that existing artwork or images that you may want to include in your project may be protected under copyright law. The unauthorized incorporation of such material into your new work could be a violation of the rights of the copyright owner. Please be sure to obtain any permission required from the copyright owner.

Any references to company or person names in sample templates are for demonstration purposes only and are not intended to refer to any actual organization or person.

Adobe, the Adobe logo, Acrobat, ActionScript, Adobe AIR, ColdFusion, Dreamweaver, Flash, Flex, Flex Builder, and Reader are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries.

Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Apple, Macintosh, and Mac OS are trademarks of Apple Inc., registered in the United States and other countries. Java is a trademark or registered trademark of Sun Microsystems, Inc. in the United States and other countries. Linux is the registered trademark of Linus Torvalds in the U.S. and other countries. All other trademarks are the property of their respective owners.

This work is licensed under the Creative Commons Attribution Non-Commercial 3.0 License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc/3.0/us/

This product includes software developed by the Apache Software Foundation (http://www.apache.org/)

MPEG Layer-3 audio compression technology licensed by Fraunhofer IIS and Thomson Multimedia (http://www.mp3licensing.com).

Speech compression and decompression technology licensed from Nellymoser, Inc. (www.nellymoser.com)

This product includes software developed by the OpenSymphony Group (http://www.opensymphony.com/)

This product contains either BSAFE and/or TIPEM software by RSA Security, Inc.

Sorenson Spark™ video compression and decompression technology licensed from Sorenson Media, Inc.

This product includes software developed by the IronSmith Project (http://www.ironsmith.org/).

Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA.

Notice to U.S. Government End Users. The Software and Documentation are “Commercial Items,” as that term is defined at 48 C.F.R. §2.101, consisting of “Commercial Computer Software” and “Commercial Computer Software Documentation,” as such terms are used in 48 C.F.R. §12.212 or 48 C.F.R. §227.7202, as applicable. Consistent with 48 C.F.R. §12.212 or 48 C.F.R. §§227.7202-1 through 227.7202-4, as applicable, the Commercial Computer Software and Commercial Computer Software Documentation are being licensed to U.S. Government end users (a) only as Commercial Items and (b) with only those rights as are granted to all other end users pursuant to the terms and conditions herein. Unpublished-rights reserved under the copyright laws of the United States. Adobe Systems Incorporated, 345 Park Avenue, San Jose, CA 95110-2704, USA. For U.S. Government End Users, Adobe agrees to comply with all applicable equal opportunity laws including, if appropriate, the provisions of Executive Order 11246, as amended, Section 402 of the Vietnam Era Veterans Readjustment Assistance Act of 1974 (38 USC 4212), and Section 503 of the Rehabilitation Act of 1973, as amended, and the regulations at 41 CFR Parts 60-1 through 60-60, 60-250, and 60-741. The affirmative action clause and regulations contained in the preceding sentence shall be incorporated by reference.

Last updated 12/9/2009

Chapter 1: Adobe AIR installation

Installing Adobe AIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Removing Adobe AIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Installing and running the AIR sample applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Chapter 2: Setting up HTML development tools

Installing the AIR Extension for Dreamweaver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Installing the AIR SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Chapter 3: Introducing Adobe AIR

What’s new in AIR 1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

What’s new in AIR 1.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Chapter 4: Finding AIR Resources

Chapter 5: Creating your first HTML-based AIR application with the AIR SDK

Create the project files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Create the AIR application descriptor file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Create the application HTML page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Test the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Create the AIR installation file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Next Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

iii

Chapter 6: Create your first HTML-based AIR application with Dreamweaver

Prepare the application files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Create the Adobe AIR application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Install the application on a desktop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Preview the Adobe AIR application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Chapter 7: Using the AIR Extension for Dreamweaver

Creating an AIR application in Dreamweaver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Signing an application with a digital certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Editing associated AIR file types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Editing AIR application settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Previewing a web page in an AIR application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Using AIR code hinting and code coloring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Accessing the Adobe AIR documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Chapter 8: Creating an AIR application using the command line tools

Using the AIR Debug Launcher (ADL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Packaging an AIR installation file using the AIR Developer Tool (ADT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Signing an AIR file to change the application certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Creating a self-signed certificate with ADT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Using Apache Ant with the SDK tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Last updated 12/9/2009

DEVELOPING ADOBE AIR 1.5 APPLICATIONS WITH HTML AND AJAX

Contents

Chapter 9: Debugging with the AIR HTML Introspector

About the AIR Introspector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Loading the AIR Introspector code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Inspecting an object in the Console tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Configuring the AIR Introspector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

AIR Introspector interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Using the AIR Introspector with content in a non-application sandbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Chapter 10: Programming in HTML and JavaScript

Creating an HTML-based AIR application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

An example application and security implications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Avoiding security-related JavaScript errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Accessing AIR API classes from JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

About URLs in AIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Embedding SWF content in HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Using ActionScript libraries within an HTML page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Converting Date and RegExp objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Manipulating an HTML stylesheet from ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Cross-scripting content in different security sandboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Chapter 11: About the HTML environment

Overview of the HTML environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

AIR and WebKit extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Chapter 12: Handling HTML-related events

HTMLLoader events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

How AIR class-event handling differs from other event handling in the HTML DOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Adobe AIR event objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Handling runtime events with JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Chapter 13: Scripting the HTML Container

Display properties of HTMLLoader objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Accessing the HTML history list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Setting the user agent used when loading HTML content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Setting the character encoding to use for HTML content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Defining browser-like user interfaces for HTML content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Chapter 14: AIR security

AIR security basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Installation and updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Sandboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

HTML security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Scripting between content in different domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Writing to disk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Working securely with untrusted content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Best security practices for developers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Code signing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Last updated 12/9/2009

DEVELOPING ADOBE AIR 1.5 APPLICATIONS WITH HTML AND AJAX

Contents

Chapter 15: Setting AIR application properties

The application descriptor file structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Defining properties in the application descriptor file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Chapter 16: ActionScript basics for JavaScript developers

Differences between ActionScript and JavaScript: an overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

ActionScript 3.0 data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

ActionScript 3.0 classes, packages, and namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Required parameters and default values in ActionScript 3.0 functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

ActionScript 3.0 event listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Chapter 17: Working with native windows

Additional online information about native windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

AIR window basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Creating windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Managing windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

Listening for window events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Displaying full-screen windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

Chapter 18: Screens

Additional online information about screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Screen basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Enumerating the screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Chapter 19: Working with native menus

Additional online information about native menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

AIR menu basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Creating native menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

About context menus in HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

Displaying pop-up menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

Handling menu events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

Example: Window and application menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

Using the MenuBuilder framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

Chapter 20: Taskbar icons

Additional online information about taskbar icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

About taskbar icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Dock icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

System Tray icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

Window taskbar icons and buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

Chapter 21: Working with the file system

Additional online information about the AIR File API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

AIR file basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Working with File objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Getting file system information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

Working with directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

Last updated 12/9/2009

DEVELOPING ADOBE AIR 1.5 APPLICATIONS WITH HTML AND AJAX

Contents

Working with files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Reading and writing files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Chapter 22: Drag and drop

Additional online information about dragging and dropping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Drag and drop basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Default drag-and-drop behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

Drag-and-drop events in HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

MIME types for the HTML drag-and-drop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Drag effects in HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Dragging data out of an HTML element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Dragging data into an HTML element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

Example: Overriding the default HTML drag-in behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

Handling file drops in non-application HTML sandboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

Chapter 23: Copy and paste

Additional online information about copying and pasting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

Copy-and-paste basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

Reading from and writing to the system clipboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

HTML copy and paste . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

Menu commands and keystrokes for copy and paste . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

Clipboard data formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

Chapter 24: Working with byte arrays

Reading and writing a ByteArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

ByteArray example: Reading a .zip file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

Chapter 25: Working with local SQL databases

Additional online information about local SQL databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

About local SQL databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

Creating and modifying a database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

Manipulating SQL database data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

Using synchronous and asynchronous database operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

Using encryption with SQL databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

Strategies for working with SQL databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

Chapter 26: Storing encrypted data

Adding data to the encrypted local store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

Accessing data in the encrypted local store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

Removing data from the encrypted local store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

Chapter 27: Adding PDF content

Detecting PDF Capability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

Loading PDF content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

Scripting PDF content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

Known limitations for PDF content in AIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

Last updated 12/9/2009

DEVELOPING ADOBE AIR 1.5 APPLICATIONS WITH HTML AND AJAX

Contents

Chapter 28: Working with sound

Basics of working with sound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298

Understanding the sound architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298

Loading external sound files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

Working with embedded sounds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

Working with streaming sound files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

Working with dynamically generated audio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

Playing sounds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

Working with sound metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308

Accessing raw sound data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

Capturing sound input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

Chapter 29: Using digital rights management

Additional online information about digital rights management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

Understanding the encrypted FLV workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

DRM-related members and events of the NetStream class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320

Using the DRMStatusEvent class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

Using the DRMAuthenticateEvent class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

Using the DRMErrorEvent class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

Using the DRMManager class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

Using the DRMContentData class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

vii

Chapter 30: Application launching and exit options

Additional online information about launch and exit options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

Application invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

Capturing command line arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Launching on login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

Browser invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

Application termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334

Chapter 31: Reading application settings

Reading the application descriptor file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336

Getting the application and publisher identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336

Chapter 32: Working with runtime and operating system information

Managing file associations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

Getting the runtime version and patch level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

Detecting AIR capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338

Tracking user presence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338

Chapter 33: Monitoring network connectivity

Detecting network connectivity changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

Service monitoring basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

Detecting HTTP connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

Detecting socket connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

Last updated 12/9/2009

DEVELOPING ADOBE AIR 1.5 APPLICATIONS WITH HTML AND AJAX

Contents

Chapter 34: URL requests and networking

Basics of networking and communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

Using the URLRequest class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343

Working with external data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

Using the URLStream class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350

Socket connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350

Opening a URL in the default system web browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354

Sending a URL to a server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

Chapter 35: Inter-application communication

About the LocalConnection class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

Sending messages between two applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

Connecting to content in different domains and to other AIR applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

Chapter 36: Distributing, Installing, and Running AIR applications

Installing and running an AIR application from the desktop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360

Installing and running AIR applications from a web page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

Enterprise deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

Digitally signing an AIR file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

viii

Chapter 37: Updating AIR applications

About updating applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

Presenting a custom application update user interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

Downloading an AIR file to the user’s computer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

Checking to see if an application is running for the first time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379

Using the update framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381

Chapter 38: Viewing Source Code

Loading, configuring, and opening the Source Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391

Source Viewer user interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394

Chapter 39: Localizing AIR applications

Introduction to localization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395

Localizing the application name and description in the application installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395

Choosing a locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396

Localizing HTML content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396

Localizing dates, times, and currencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404

Chapter 40: XML signature validation

Additional online information about XML signature validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406

Basics of XML signature validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406

About XML signatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410

Implementing the IURIDereferencer interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413

Index ...............................................................................................................421

Last updated 12/9/2009

Chapter 1: Adobe AIR installation

Adobe® AIR® allows you to run AIR applications on the desktop. You can install the runtime in the following ways:

• By installing the runtime separately (without also installing an AIR application)

• By installing an AIR application for the first time (you are prompted to also install the runtime)

• By setting up an AIR development environment such as the AIR SDK, Adobe® Flex™ Builder™ 3, or the Adobe Flex™

3 SDK (which includes the AIR command line development tools)

The runtime only needs to be installed once per computer.

The system requirements for installing AIR and running AIR applications are detailed here: Adobe AIR: System

requirements (http://www.adobe.com/products/air/systemreqs/).

Installing Adobe AIR

Use the following instructions to download and install the Windows®, Mac OS X, and Linux versions of AIR.

To update the runtime, a user must have administrative privileges for the computer.

Install the runtime on a Windows computer

1 Download the runtime installation file.

2 Double-click the runtime installation file.

3 In the installation window, follow the prompts to complete the installation.

Install the runtime on a Mac computer

1 Download the runtime installation file.

2 Double-click runtime installation file.

3 In the installation window, follow the prompts to complete the installation.

4 If the Installer displays an Authenticate window, enter your Mac OS user name and password.

Install the runtime on a Linux computer

1 Download the runtime installation file.

2 Set the file permissions so that the installer application can be executed:

From a command line, you can set the file permissions with the chmod +x installer.bincommand. Some versions of Linux allow you to set the file permissions on the Properties dialog opened through a context menu.

3 Run the installer from the command line or by double-clicking the runtime installation file.

4 In the installation window, follow the prompts to complete the installation.

AIR is installed as either rpm or dpkg packages, with package names: adobeairv.n and adobecerts. Installation requires a running X server. AIR registers the mime type:

installer-package+zip.

application/vnd.adobe.air-application-

Last updated 12/9/2009

DEVELOPING ADOBE AIR 1.5 APPLICATIONS WITH HTML AND AJAX

Removing Adobe AIR

Once you have installed the runtime, you can remove it using the following procedures.

Remove the runtime on a Windows computer

1 In the Windows Start menu, select Settings > Control Panel.

2 Select the Add or Remove Programs control panel.

3 Select “Adobe AIR” to remove the runtime.

4 Click the Change/Remove button.

Remove the runtime on a Mac computer

• Double-click the “Adobe AIR Uninstaller”, which is located in the /Applications/Utilities folder.

Remove the runtime on a Linux computer

Do one of the following:

• Select the “Adobe AIR Uninstaller” command from the Applications menu.

• Run the AIR installer binary with the -uninstall option

• Remove the AIR packages (adobeairv.n and adobecerts) with your package manager.

Adobe AIR installation

Installing and running the AIR sample applications

Some sample applications are available that demonstrate AIR features. You can access and install them using the following instructions:

1 Download and run the AIR sample applications. The compiled applications as well as the source code are available.

2 To download and run a sample application, click the sample application Install Now button. You are prompted to

install and run the application.

3 If you choose to download sample applications and run them later, select the download links. You can run AIR

applications at any time by:

• On Windows, double-clicking the application icon on the desktop or selecting it from the Windows Start menu.

• On Mac OS, double-clicking the application icon, which is installed in the Applications folder of your user

directory (for example, in Macintosh HD/Users/JoeUser/Applications/) by default.

• On Linux, double-clicking the application icon on the desktop or selecting it from the Applications menu. AIR

applications are installed in their own folder under the

Note: Check the AIR release notes for updates to these instructions, which are located here:

http://www.adobe.com/go/learn_air_relnotes.

/opt directory.

Last updated 12/9/2009

Chapter 2: Setting up HTML development tools

To develop HTML-based Adobe® AIR® applications, you can use the Adobe®AIR® Extension for Dreamweaver, the AIR SDK command-line tools, or other Web development tools that support Adobe AIR. This topic explains how to install the Adobe AIR Extension for Dreamweaver and the AIR SDK.

Installing the AIR Extension for Dreamweaver

The AIR Extension for Dreamweaver helps you to create rich Internet applications for the desktop. For example, you might have a set of web pages that interact with each other to display XML data. You can use the Adobe AIR Extension for Dreamweaver to package this set of pages into a small application that can be installed on a user’s computer. When the user runs the application from their desktop, the application loads and displays the website in its own application window, independent of a browser. The user can then browse the website locally on their computer without an Internet connection.

Dynamic pages such as Adobe® ColdFusion® and PHP pages won’t run in Adobe AIR. The runtime only works with HTML and JavaScript. However, you can use JavaScript in your pages to call any web service exposed on the Internet— including ColdFusion- or PHP-generated services—with Ajax methods such as XMLHTTPRequest or Adobe AIRspecific APIs.

For more information about the types of applications you can develop with Adobe AIR, see “Introducing Adobe AIR” on page 6.

System requirements

To use the Adobe AIR Extension for Dreamweaver, the following software must be installed and properly configured:

• Dreamweaver CS3 or Dreamweaver CS4

• Adobe® Extension Manager CS3

• Java JRE 1.4 or later (necessary for creating the Adobe AIR file). The Java JRE is available at http://java.sun.com/.

The preceding requirements are only for creating and previewing Adobe AIR applications in Dreamweaver. To install and run an Adobe AIR application on the desktop, you must also install Adobe AIR on your computer. To download the runtime, see

www.adobe.com/go/air.

Install the Adobe AIR Extension for Dreamweaver

1 Download the Adobe AIR Extension for Dreamweaver here: http://www.adobe.com/products/air/tools/ajax/.

2 Double-click the .mxp extension file in Windows Explorer (Windows) or in the Finder (Macintosh).

3 Follow the onscreen instructions to install the extension.

4 After you’re finished, restart Dreamweaver.

For information about using the Adobe AIR Extension for Dreamweaver, see “Using the AIR Extension for

Dreamweaver” on page 18.

Last updated 12/9/2009

DEVELOPING ADOBE AIR 1.5 APPLICATIONS WITH HTML AND AJAX

Setting up HTML development tools

Installing the AIR SDK

The Adobe AIR SDK contains the following command-line tools that you use to launch and package applications:

AIR Debug Launcher (ADL) Allows you to run AIR applications without having to first install them. See “Using the

AIR Debug Launcher (ADL)” on page 23.

AIR Development Tool (ADT) Packages AIR applications into distributable installation packages. See “Packaging an

AIR installation file using the AIR Developer Tool (ADT)” on page 25.

The AIR command-line tools require Java to be installed your computer. You can use the Java virtual machine from either the JRE or the JDK (version 1.4 or newer). The Java JRE and the Java JDK are available at

Note: Java is not required for end users to run AIR applications.

Download and install the AIR SDK

You can download and install the AIR SDK using the following instructions:

Install the AIR SDK in Windows

1 Download the AIR SDK installation file.

2 The AIR SDK is distributed as a standard file archive. To install AIR, extract the contents of the SDK to a folder on

your computer (for example: C:\Program Files\Adobe\AIRSDK or C:\AIRSDK).

3 The ADL and ADT tools are contained in the bin folder in the AIR SDK; add the path to this folder to your PATH

environment variable.

http://java.sun.com/.

Install the AIR SDK in Mac OS X

1 Download the AIR SDK installation file.

2 The AIR SDK is distributed as a standard file archive. To install AIR, extract the contents of the SDK to a folder on

your computer (for example: /Users/<userName>/Applications/AIRSDK).

3 The ADL and ADT tools are contained in the bin folder in the AIR SDK; add the path to this folder to your PATH

environment variable.

For information about getting started using the AIR SDK tools, see “Creating an AIR application using the

command line tools” on page 23.

What's included in the AIR SDK

The following table describes the purpose of the files contained in the AIR SDK:

Last updated 12/9/2009

SDK folder Files/tools description

DEVELOPING ADOBE AIR 1.5 APPLICATIONS WITH HTML AND AJAX

Setting up HTML development tools

BIN adl.exe - The AIR Debug Launcher (ADL) allows you to run an AIR application without first packaging and

FRAMEWORKS AIRAliases.js - Provides "alias" definitions that allow you to access the ActionScript runtime classes. For

LIB adt.jar - The adt executable file, which is called by the adt.bat file.

RUNTIME The AIR runtime - The runtime is used by ADL to launch your AIR applications before they have been packaged

SAMPLES This folder contains a sample application descriptor file, a sample of the seamless install feature (badge.swf),

SRC This folder contains the source files for the seamless install sample.

TEMPLATES descriptor-template.xml - A template of the application descriptor file, which is required for each AIR

installing it. For information about using this tool, see

adt.bat - The AIR Developer Tool (ADT) packages your application as an AIR file for distribution. For information about using this tool, see on page 25.

information about using this alias file, see

servicemonitor.swf - Provides AIR applications with an event-based means of responding to changes in network connectivity to a specified host. For information about using this framework, see

network connectivity” on page 339.

Descriptor.1.0.xsd - The application schema file.

or installed.

and the default AIR application icons; see

application. For a detailed description of the application descriptor file, see

properties” on page 116.

“Packaging an AIR installation file using the AIR Developer Tool (ADT)”

“Using the AIRAliases.js file” on page 58

“Distributing, Installing, and Running AIR applications” on page 360.

“Using the AIR Debug Launcher (ADL)” on page 23.

“Monitoring

“Setting AIR application

Last updated 12/9/2009

Chapter 3: Introducing Adobe AIR

Adobe® AIR® is a cross-operating system runtime that allows you to leverage your existing web development skills (Adobe® Flash® CS3 Professional, Adobe® Flash® CS4 Professional, Adobe® Flex™, Adobe® ActionScript® 3.0, HTML, JavaScript®, Ajax) to build and deploy Rich Internet Applications (RIAs) to the desktop.

You can find more information about getting started with and using Adobe AIR at the Adobe AIR Developer Connection (

AIR enables you to work in familiar environments, to leverage the tools and approaches you find most comfortable, and by supporting Flash, Flex, HTML, JavaScript, and Ajax, to build the best possible experience that meets your needs.

For example, applications can be developed using one or a combination of the following technologies:

• Flash / Flex / ActionScript

• HTML / JavaScript / CSS / Ajax

• PDF can be leveraged with any application

As a result, AIR applications can be:

http://www.adobe.com/devnet/air/).

• Based on Flash or Flex: Application whose root content is Flash/Flex (SWF)

• Based on Flash or Flex with HTML or PDF. Applications whose root content is Flash/Flex (SWF) with HTML

(HTML, JS, CSS) or PDF content included

• HTML-based. Application whose root content is HTML, JS, CSS

• HTML-based with Flash/Flex or PDF. Applications whose root content is HTML with Flash/Flex (SWF) or PDF

content included

Users interact with AIR applications in the same way that they interact with native desktop applications. The runtime is installed once on the user's computer, and then AIR applications are installed and run just like any other desktop application.

The runtime provides a consistent cross-operating system platform and framework for deploying applications and therefore eliminates cross-browser testing by ensuring consistent functionality and interactions across desktops. Instead of developing for a specific operating system, you target the runtime, which has the following benefits:

• Applications developed for AIR run across multiple operating systems without any additional work by you. The

runtime ensures consistent and predictable presentation and interactions across all the operating systems supported by AIR.

• Applications can be built faster by enabling you to leverage existing web technologies and design patterns and

extend your web based applications to the desktop without learning traditional desktop development technologies or the complexity of native code.

• Application development is easier than using lower level languages such as C and C++. You do not need to manage

the complex, low-level APIs specific to each operating system.

When developing applications for AIR, you can leverage a rich set of frameworks and APIs:

• APIs specific to AIR provided by the runtime and the AIR framework

• ActionScript APIs used in SWF files and Flex framework (as well as other ActionScript based libraries and

frameworks)

• HTML, CSS and JavaScript

Last updated 12/9/2009

DEVELOPING ADOBE AIR 1.5 APPLICATIONS WITH HTML AND AJAX

Introducing Adobe AIR

• Most Ajax frameworks

AIR dramatically changes how applications can be created, deployed, and experienced. You gain more creative control and can extend your Flash, Flex, HTML, and Ajax-based applications to the desktop, without learning traditional desktop development technologies.

What’s new in AIR 1.1

Adobe AIR 1.1 introduced the following new capabilities:

• Installation and other runtime dialog boxes have been translated into:

• Brazilian Portuguese

• Chinese (Traditional and Simplified)

• French

• German

• Italian

• Japanese

• Korean

• Russian

• French

• Spanish

• Support for building internationalized applications, including keyboard input for double-byte languages. See

“Localizing AIR applications” on page 395.

• Support for localizing the name and description attributes in the application descriptor file.

• Support for localizing error messages, such as SQLError.detailID and SQLError.detailArguments, in the SQLite

database.

• Addition of Capabilities.languages property to obtain an array of preferred UI languages as set by the operating

system.

• HTML button labels and default menus, such as context menus and the Mac menu bar, have been localized to

all supported languages.

• Support for certificate migration from a self-signed application to one that chains to a certificate of authority (CA).

• Support for Microsoft Windows XP Tablet PC Edition and support for 64-bit editions of Windows Vista® Home

Premium, Business, Ultimate, or Enterprise.

• Addition of File.spaceAvailable API to obtain the amount of disk space available on a disk.

• Addition of NativeWindow.supportsTransparency property to determine whether a window can be drawn as

transparent by the current operating system.

For more information about the AIR 1.1 release, see the Adobe AIR 1.1 Release Notes

http://www.adobe.com/go/learn_air_relnotes_en).

(

Last updated 12/9/2009

DEVELOPING ADOBE AIR 1.5 APPLICATIONS WITH HTML AND AJAX

Introducing Adobe AIR

What’s new in AIR 1.5

Adobe AIR 1.5 introduces the following new features:

• Support for the following features of Flash Player 10.

• Custom Filters and Effects

• Enhanced Drawing API

• Dynamic Sound Generation

• Vector Data Type

• Enhanced file upload and download APIs

• Real Time Media Flow Protocol (RTMFP)

• 3D Effects

• Advanced Text Support

• Color Management

• Text Engine

• Dynamic Streaming

• Speex Audio Codec

For more information, see http://www.adobe.com/products/flashplayer/features/ for details of these features.

• Additional languages supported in the AIR 1.5 installer and other runtime dialog boxes: Czech, Dutch, Swedish,

Turkish, Polish.

• Database encryption.

Database files can be encrypted in AIR 1.5. All database content, including the metadata, can be encrypted so that the data is unreadable outside of the AIR application that encrypted it. This feature will allow a developer to encrypt, decrypt, and re-encrypt database files. See

“Storing encrypted data” on page 290.

• The version of WebKit used by Adobe AIR has been updated and it now includes support for the SquirrelFish

JavaScript interpreter.

• New XML signature validation APIs that can be used to help verify the integrity and signer identity of data or

information. See

For more information about the AIR 1.5 release, see the Adobe AIR 1.5 Release Notes

http://www.adobe.com/go/learn_air_relnotes_en).

(

“XML signature validation” on page 406.

Last updated 12/9/2009

Chapter 4: Finding AIR Resources

For more information on developing Adobe® AIR® applications, see the following resources:

Source Location

Adobe AIR Language Reference for HTML Developers http://www.adobe.com/go/learn_air_html_jslr_en

Adobe AIR Quick Starts for HTML http://www.adobe.com/go/learn_air_html_qs_en

You can find articles, samples and presentations by both Adobe and community experts on the Adobe AIR Developer Connection at there.

You can find a section specifically for HTML and Ajax developers at http://www.adobe.com/devnet/air/ajax/.

Visit the Adobe Support website, at http://www.adobe.com/support/, to find troubleshooting information for your product and to learn about free and paid technical support options. Follow the Training link for access to Adobe Press books, a variety of training resources, Adobe software certification programs, and more.

http://www.adobe.com/devnet/air/. You can also download Adobe AIR and related software from

Last updated 12/9/2009

Chapter 5: Creating your first HTMLbased AIR application with the AIR SDK

For a quick, hands-on illustration of how Adobe® AIR® works, use these instructions to create and package a simple HTML-based AIR “Hello World” application.

To begin, you must have installed the runtime and set up the AIR SDK. You will use the AIR Debug Launcher (ADL) and the AIR Developer Tool (ADT) in this tutorial. ADL and ADT are command-line utility programs and can be found in the assumes that you are already familiar with running programs from the command line and know how to set up the necessary path environment variables for your operating system.

Create the project files

Every HTML-based AIR project must contain the following two files: an application descriptor file, which specifies the application metadata, and a top-level HTML page. In addition to these required files, this project includes a JavaScript code file,

bin directory of the AIR SDK (see “Setting up HTML development tools” on page 3). This tutorial

AIRAliases.js, that defines convenient alias variables for the AIR API classes.

To begin:

1 Create a directory named HelloWorld to contain the project files.

2 Create an XML file, named HelloWorld-app.xml.

3 Create an HTML file named HelloWorld.html.

4 Copy AIRAliases.js from the frameworks folder of the AIR SDK to the project directory.

Create the AIR application descriptor file

To begin building your AIR application, create an XML application descriptor file with the following structure:

1 Open the HelloWorld-app.xml for editing.

2 Add the root <application> element, including the AIR namespace attribute:

<application xmlns="http://ns.adobe.com/air/application/1.5"> The last segment of the namespace, “1.5”, specifies the version of the runtime required by the application.

Last updated 12/9/2009

3 Add the <id> element:

DEVELOPING ADOBE AIR 1.5 APPLICATIONS WITH HTML AND AJAX

Creating your first HTML-based AIR application with the AIR SDK

<id>examples.html.HelloWorld</id> The application id uniquely identifies your application along with the publisher id (which AIR derives from the certificate used to sign the application package). The recommended form is a dot-delimited, reverse-DNS-style string, such as

"com.company.AppName". The application id is used for

installation, access to the private application file-system storage directory, access to private encrypted storage, and interapplication communication.

4 Add the <version> element:

<version>0.1</version> Helps users to determine which version of your application they are installing.

5 Add the <filename> element:

<filename>HelloWorld</filename> The name used for the application executable, install directory, and other references to the application in the operating system.

6 Add the <initialWindow> element containing the following child elements to specify the properties for your

initial application window:

<content>HelloWorld.html</content> Identifies the root HTML file for AIR to load.

<visible>true</visible> Makes the window visible immediately.

<width>400</width> Sets the window width (in pixels).

<height>200</height> Sets the window height.

7 Save the file. The completed application descriptor file should look like the following:

<?xml version="1.0" encoding="UTF-8"?> <application xmlns="http://ns.adobe.com/air/application/1.5"> <id>examples.html.HelloWorld</id> <version>0.1</version> <filename>HelloWorld</filename> <initialWindow> <content>HelloWorld.html</content> <visible>true</visible> <width>400</width> <height>200</height> </initialWindow> </application>

This example only sets a few of the possible application properties. For the full set of application properties, which allow you to specify such things as window chrome, window size, transparency, default installation directory, associated file types, and application icons, see

“Setting AIR application properties” on page 116.

Create the application HTML page

You now need to create a simple HTML page to serve as the main file for the AIR application.

1 Open the HelloWorld.html file for editing. Add the following HTML code:

Last updated 12/9/2009

<html> <head> <title>Hello World</title> </head> <body onLoad="appLoad()"> <h1>Hello World</h1> </body> </html>

DEVELOPING ADOBE AIR 1.5 APPLICATIONS WITH HTML AND AJAX

Creating your first HTML-based AIR application with the AIR SDK

2 In the <head> section of the HTML, import the AIRAliases.js file:

AIR defines a property named runtime on the HTML window object. The runtime property provides access to the built-in AIR classes, using the fully qualified package name of the class. For example, to create an AIR File object you could add the following statement in JavaScript:

var textFile = new runtime.flash.filesystem.File("app:/textfile.txt");

The AIRAliases.js file defines convenient aliases for the most useful AIR APIs. Using AIRAliases.js, you could shorten the reference to the File class to the following:

var textFile = new air.File("app:/textfile.txt");

3 Below the AIRAliases script tag, add another script tag containing a JavaScript function to handle the onLoad event:

The appLoad() function simply calls the air.trace() function. The trace message print to the command console when you run the application using ADL. Trace statements can be very useful for debugging.

4 Save the file.

Your HelloWorld.html file should now look like the following:

<html> <head> <title>Hello World</title> <script type="text/javascript" src="AIRAliases.js"></script> <script type="text/javascript"> function appLoad(){ air.trace("Hello World"); } </script> </head> <body onLoad="appLoad()"> <h1>Hello World</h1> </body> </html>

Last updated 12/9/2009

DEVELOPING ADOBE AIR 1.5 APPLICATIONS WITH HTML AND AJAX

Creating your first HTML-based AIR application with the AIR SDK

Test the application

To run and test the application from the command line, use the AIR Debug Launcher (ADL) utility. The ADL executable can be found in the

up HTML development tools” on page 3.

❖ First, open a command console or shell. Change to the directory you created for this project. Then, run the

following command:

adl HelloWorld-app.xml

An AIR window opens, displaying your application. Also, the console window displays the message resulting from

air.trace() call.

the

For more information, see “Using the AIR Debug Launcher (ADL)” on page 23.

bin directory of the AIR SDK. If you haven’t already set up the AIR SDK, see “Setting

Create the AIR installation file

When your application runs successfully, you can use the ADT utility to package the application into an AIR installation file. An AIR installation file is an archive file that contains all the application files, which you can distribute to your users. You must install Adobe AIR before installing a packaged AIR file.

To ensure application security, all AIR installation files must be digitally signed. For development purposes, you can generate a basic, self-signed certificate with ADT or another certificate generation tool. You can also buy a commercial code-signing certificate from a commercial certificate authority such as VeriSign or Thawte. When users install a selfsigned AIR file, the publisher is displayed as “unknown” during the installation process. This is because a self-signed certificate only guarantees that the AIR file has not been changed since it was created. There is nothing to prevent someone from self-signing a masquerade AIR file and presenting it as your application. For publicly released AIR files, a verifiable, commercial certificate is strongly recommended. For an overview of AIR security issues, see

security” on page 100.

Generate a self-signed certificate and key pair

❖ From the command prompt, enter the following command (the ADT executable is located in the bin directory of

the AIR SDK):

adt –certificate -cn SelfSigned 1024-RSA sampleCert.pfx samplePassword

ADT generates a keystore file named sampleCert.pfx containing a certificate and the related private key.

This example uses the minimum number of attributes that can be set for a certificate. You can use any values for the parameters in italics. The key type must be either 1024-RSA or 2048-RSA (see page 369).

Create the AIR installation file

❖ From the command prompt, enter the following command (on a single line):

“Digitally signing an AIR file” on

“AIR

Last updated 12/9/2009

adt -package -storetype pkcs12 -keystore sampleCert.pfx HelloWorld.air HelloWorld-app.xml HelloWorld.html AIRAliases.js

You will be prompted for the keystore file password.

The HelloWorld.air argument is the AIR file that ADT produces. HelloWorld-app.xml is the application descriptor file. The subsequent arguments are the files used by your application. This example only uses two files, but you can include any number of files and directories.

After the AIR package is created, you can install and run the application by double-clicking the package file. You can also type the AIR filename as a command in a shell or command window.

DEVELOPING ADOBE AIR 1.5 APPLICATIONS WITH HTML AND AJAX

Creating your first HTML-based AIR application with the AIR SDK

Next Steps

In AIR, HTML and JavaScript code generally behaves the same as it would in a typical web browser. (In fact, AIR uses the same WebKit rendering engine used by the Safari web browser.) However, there are some important differences that you must understand when you develop HTML applications in AIR. For more information on these differences, and other important topics, see:

Last updated 12/9/2009

Chapter 6: Create your first HTML-based AIR application with Dreamweaver

For a quick, hands-on illustration of how Adobe® AIR® works, use these instructions to create and package a simple HTML-based AIR “Hello World” application using the Adobe® AIR® Extension for Dreamweaver®.

If you haven’t already done so, download and install Adobe AIR , which is located here: www.adobe.com/go/air.

For instructions on installing the Adobe AIR Extension for Dreamweaver, see “Installing the AIR Extension for

Dreamweaver” on page 3.

For an overview of the extension, including system requirements, see “Using the AIR Extension for Dreamweaver” on page 18.

Prepare the application files

Your Adobe AIR application must have a start page and all of its related pages defined in a Dreamweaver site. (For more information on Dreamweaver sites, see Dreamweaver Help.) To create a start page for a simple "Hello World" AIR application, follow these instructions:

1 Start Dreamweaver and make sure you have a site defined.

2 Open a new HTML page by selecting File > New, selecting HTML in the Page Type column, selecting None in the

Layout column, and clicking Create.

3 In the new page, type Hello World!

This example is extremely simple, but if you want you can style the text to your liking, add more content to the page, link other pages to this start page, and so on.

4 Save the page (File > Save) as hello_world.html. Make sure you save the file in a Dreamweaver site.

Create the Adobe AIR application

1 Make sure you have the hello_world.html page open in the Dreamweaver Document window. (See the previous

section for instructions on creating it.)

2 Select Site > Air Application Settings.

Most of the required settings in the AIR Application and Settings dialog box are auto-populated for you. You must, however, select the initial content (or start page) of your application.

3 Click the Browse button next to the Initial Content option, navigate to your hello_world.html page, and select it.

4 Next to the Digital signature option, click the Set button.

A digital signature provides an assurance that the code for an application has not been altered or corrupted since its creation by the software author, and is required on all Adobe AIR applications.

5 In the Digital Signature dialog box, select Sign the AIR package with a digital certificate, and click the Create button.

(If you already have access to a digital certificate, you can click the Browse button to select it instead.)

Last updated 12/9/2009

6 Complete the required fields in the Self-Signed Digital Certificate dialog box. You’ll need to enter your name, enter

DEVELOPING ADOBE AIR 1.5 APPLICATIONS WITH HTML AND AJAX

Create your first HTML-based AIR application with Dreamweaver

a password and confirm it, and enter a name for the digital certificate file. Dreamweaver saves the digital certificate in your site root.

7 Click OK to return to the Digital Signature dialog box.

8 In the Digital Signature dialog box, enter the password you specified for your digital certificate and click OK.

Your completed AIR Application and Installer Settings dialog box might look like this:

For further explanation about all of the dialog box options and how to edit them, see “Creating an AIR application

in Dreamweaver” on page 18.

9 Click the Create AIR File button.

Dreamweaver creates the Adobe AIR application file and saves it in your site root folder. Dreamweaver also creates an application.xml file and saves it in the same place. This file serves as a manifest, defining various properties of the application.

Last updated 12/9/2009

DEVELOPING ADOBE AIR 1.5 APPLICATIONS WITH HTML AND AJAX

Create your first HTML-based AIR application with Dreamweaver

Install the application on a desktop

Now that you’ve created the application file, you can install it on any desktop.

1 Move the Adobe AIR application file out of your Dreamweaver site and onto your desktop, or to another desktop.

This step is optional. You can actually install the new application on your computer right from your Dreamweaver site directory if you prefer.

2 Double-click the application executable file (.air file) to install the application.

Preview the Adobe AIR application

You can preview pages that will be part of AIR applications at any time. That is, you don’t necessarily need to package the application before seeing what it will look like when it’s installed.

1 Make sure your hello_world.html page is open in the Dreamweaver Document window.

2 On the Document toolbar, click the Preview/Debug in Browser button, and then select Preview In AIR.

You can also press Ctrl+Shift+F12 (Windows) or Cmd+Shift+F12 (Macintosh).

When you preview this page, you are essentially seeing what a user would see as the start page of the application after they’ve installed the application on a desktop.

Last updated 12/9/2009

Chapter 7: Using the AIR Extension for Dreamweaver

The Adobe® AIR® Extension for Dreamweaver® lets you transform a web-based application into a desktop application. Users can then run the application on their desktops and, in some cases, without an Internet connection.

You can use the extension with Dreamweaver CS3 and Dreamweaver CS4. It is not compatible with Dreamweaver 8.

For information about installing the extension, see “Installing the AIR Extension for Dreamweaver” on page 3.

Note: Adobe AIR does not support Adobe InContext Editing. If you use the AIR Extension for Dreamweaver to export an application that contains InContext Editing regions, the InContext Editing functionality will not work.

Creating an AIR application in Dreamweaver

To create an HTML-based AIR application in Dreamweaver, you select an existing site to package as an AIR application.

1 Make sure that the web pages you want to package into an application are contained in a defined Dreamweaver site.

2 In Dreamweaver, open the home page of the set of pages you want to package.

3 Select Site > Air Application Settings.

4 Complete the AIR Application and Installer Settings dialog box, and then click Create AIR File.

For more information, see the dialog box options listed below.

The first time you create an Adobe AIR file, Dreamweaver creates an application.xml file in your site root folder. This file serves as a manifest, defining various properties of the application.

The following describes the options in the AIR Application and Installer Settings dialog box:

Application File Name is the name used for the application executable file. By default, the extension uses the name

of the Dreamweaver site to name the file. You can change the name if you prefer. However, the name must contain only valid characters for files or folder names. (That is, it can only contain ASCII characters, and cannot end with a period.) This setting is required.

Application Name is the name that appears on installation screens when users install the application. Again, the

extension specifies the name of the Dreamweaver site by default. This setting does not have character restrictions, and is not required.

Application ID identifies your application with a unique ID. You can change the default ID if you prefer. Do not

use spaces or special characters in the ID. The only valid characters are 0-9, a-z, A-Z, . (dot), and - (dash). This setting is required.

Version specifies a version number for your application. This setting is required.

Initial Content specifies the start page for your application. Click the Browse button to navigate to your start page

and select it. The chosen file must reside inside the site root folder. This setting is required.

Description lets you specify a description of the application to display when the user installs the application.

Last updated 12/9/2009

DEVELOPING ADOBE AIR 1.5 APPLICATIONS WITH HTML AND AJAX

Using the AIR Extension for Dreamweaver

installed on the Macintosh. This information is not used for applications installed on Windows.

Window Style specifies the window style (or chrome) to use when the user runs the application on their computer.

System chrome surrounds the application with the operating system standard window control. Custom chrome (opaque) eliminates the standard system chrome and lets you create a chrome of your own for the application. (You build the custom chrome directly in the packaged HTML page.) Custom chrome (transparent) is like Custom chrome (opaque), but adds transparent capabilities to the edges of the page, allowing for application windows that are not rectangular in shape.

Window Size specifies the dimensions of your application window when it opens.

Icon lets you select custom images for the application icons. (The default images are Adobe AIR images that come

with the extension.) To use custom images, click the Select Icon Images button. Then, in the Icon Images dialog box that appears, click the folder for each icon size and select the image file you want to use. AIR only supports PNG files for application icon images.

Note: Selected custom images must reside in the application site, and their paths must be relative to the site root.

Associated File Types lets you associate file types with your application. For more information, see the section that

follows.

Application Updates determines whether the Adobe AIR Application Installer or the application itself performs

updates to new versions of Adobe AIR applications. The check box is selected by default, which causes the Adobe AIR Application Installer to perform updates. If you want your application to perform its own updates, deselect the checkbox. Keep in mind that if you deselect the checkbox, you then need to write an application that can perform updates.

Included Files specifies which files or folders to include in your application. You can add HTML and CSS files,

image files, and JavaScript library files. Click the Plus (+) button to add files, and the folder icon to add folders. You should not include certain files such as _mmServerScripts, _notes, and so on. To delete a file or folder from your list, select the file or folder and click the Minus (-) button.

Digital Signature Click Set to sign your application with a digital signature. This setting is required. For more

information, see the section that follows.

Program Menu Folder specifies a subdirectory in the Windows Start Menu where you want the application’s

shortcut created. (Not applicable on Macintosh.)

Destination specifies where to save the new application installer (.air file). The default location is the site root. Click

the Browse button to select a different location. The default file name is based on the site name with an .air extension added to it. This setting is required.

Last updated 12/9/2009

The following is an example of the dialog box with some basic options set:

DEVELOPING ADOBE AIR 1.5 APPLICATIONS WITH HTML AND AJAX

Using the AIR Extension for Dreamweaver

Signing an application with a digital certificate

A digital signature provides an assurance that the code for an application has not been altered or corrupted since its creation by the software author. All Adobe AIR applications require a digital signature, and can’t be installed without one. You can sign your application with a purchased digital certificate, create your own certificate, or prepare an Adobe AIRI file (an Adobe AIR intermediate file) that you’ll sign at a later time.

1 In the AIR Application and Installer Settings dialog box, click the Set button next to the Digital Signature option.

2 In the Digital Signature dialog box, do one of the following:

• To sign an application with a pre-purchased digital certificate, click the Browse button, select the certificate,

enter the corresponding password, and click OK.

• To create your own self-signed digital certificate, click the Create button and complete the dialog box. The

certificate Type option refers to the level of security: 1024-RSA uses a 1024-bit key (less secure), and 2048-RSA uses a 2048-bit key (more secure). When you’re finished click OK. Then enter the corresponding password in the Digital Signature dialog box and click OK.

Last updated 12/9/2009

DEVELOPING ADOBE AIR 1.5 APPLICATIONS WITH HTML AND AJAX

Using the AIR Extension for Dreamweaver

• Select Prepare an AIRI package that will be signed later and click OK. This option lets you create an AIR

Intermediate (AIRI) application without a digital signature. A user is not able to install the application, however, until you add a digital signature.

About Timestamping

When you sign an Adobe AIR application with a digital certificate, the packaging tool queries the server of a timestamp authority to obtain an independently verifiable date and time of signing. The timestamp obtained is embedded in the AIR file. As long as the signing certificate is valid at the time of signing, the AIR file can be installed, even after the certificate has expired. On the other hand, if no timestamp is obtained, the AIR file ceases to be installable when the certificate expires or is revoked.

By default, the Adobe AIR Extension for Dreamweaver obtains a timestamp when creating an Adobe AIR application. You can, however, turn timestamping off by deselecting the Timestamp option in the Digital Signature dialog box. (You might want to do this, for example, if a timestamping service is unavailable.) Adobe recommends that all publically distributed AIR files include a timestamp.

The default timestamp authority used by the AIR packaging tools is Geotrust. For more information on timestamping and digital certificates, see

Editing associated AIR file types

You can associate different file types with your Adobe AIR application. For example, if you want file types with an .avf extension to open in Adobe AIR when a user double-clicks them, you can add the .avf extension to your list of associated file types.

1 In the AIR Application and Installer Settings dialog box, click the Edit list button next to the Associated File Types

option.

2 In the Associated File Types dialog box, do one of the following:

• Select a file type and click the minus (-) button to delete the file type.

• Click the plus (+) button to add a file type.

If you click the plus button to add a file type, the File Type Settings dialog box appears. Complete the dialog box and click OK to close it.

Following is a list of options:

Name specifies the name of the file type that appears in the Associated File Types list. This option is required,

and can only include alphanumeric ASCII characters (a-z, A-Z, 0-9) and dots (for example, adobe.VideoFile). The name must start with a letter. The maximum length is 38 characters.

Extension specifies the extension of the file type. Do not include a preceding dot. This option is required, and

can only include alphanumeric ASCII characters (a-z, A-Z, 0-9). The maximum length is 38 characters.

Description lets you specify an optional description for the file type.

Content Type specifies the MIME type or media type for the file (for example text/html, image/gif, and so on).

Icon File Locations lets you select custom images for the associated file types. (The default images are Adobe

AIR images that come with the extension.)

Last updated 12/9/2009

DEVELOPING ADOBE AIR 1.5 APPLICATIONS WITH HTML AND AJAX

Using the AIR Extension for Dreamweaver

Editing AIR application settings

You can edit the settings for your Adobe AIR application at any time.

❖ Select Site > AIR Application Settings and make your changes.

Previewing a web page in an AIR application

You can preview an HTML page in Dreamweaver as it would appear in an Adobe AIR application. Previewing is useful when you want to see what a web page will look like in the application without having to create the entire application.

❖ On the Document toolbar, click the Preview/Debug in Browser button, and then select Preview In AIR.

You can also press Ctrl+Shift+F12 (Windows) or Cmd+Shift+F12 (Macintosh).

Using AIR code hinting and code coloring

The Adobe AIR Extension for Dreamweaver also adds code hinting and code coloring for Adobe AIR language elements in Code view in Dreamweaver.

• Open an HTML or JavaScript file in Code view and enter Adobe AIR code.

Note: The code hinting mechanism only works inside <script> tags, or in .js files.

For more information on the Adobe AIR language elements, see the developer documentation in the rest of this guide.

Accessing the Adobe AIR documentation

The Adobe AIR extension adds a Help menu item in Dreamweaver that lets you access Developing AIR Applications with HTML and Ajax.

❖ Select Help > Adobe AIR Help.

Macromedia Air - 1.5 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

Chapter 1: Adobe AIR installation

Installing Adobe AIR

Removing Adobe AIR

Installing and running the AIR sample applications

Chapter 2: Setting up HTML development tools

Installing the AIR Extension for Dreamweaver

System requirements

Install the Adobe AIR Extension for Dreamweaver

Installing the AIR SDK

Download and install the AIR SDK

What's included in the AIR SDK

Chapter 3: Introducing Adobe AIR

What’s new in AIR 1.1

What’s new in AIR 1.5

Chapter 4: Finding AIR Resources

Create the project files

Create the AIR application descriptor file

Create the application HTML page

Test the application

Create the AIR installation file

Next Steps

Chapter 6: Create your first HTML-based AIR application with Dreamweaver

Prepare the application files

Create the Adobe AIR application

Install the application on a desktop

Preview the Adobe AIR application

Chapter 7: Using the AIR Extension for Dreamweaver

Creating an AIR application in Dreamweaver

Signing an application with a digital certificate

About Timestamping

Editing associated AIR file types

Editing AIR application settings

Previewing a web page in an AIR application

Using AIR code hinting and code coloring

Accessing the Adobe AIR documentation