Macromedia Air User Manual

HTML Developer’s Guide for

ADOBE® AIR®

Legal notices

For legal notices, see http://help.adobe.com/en_US/legalnotices/index.html.

Last updated 9/28/2011

Chapter 1: About the HTML environment

Overview of the HTML environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

AIR and WebKit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 2: Programming HTML and JavaScript in AIR

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

An example application and security implications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Avoiding security-related JavaScript errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Accessing AIR API classes from JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

About URLs in AIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Embedding SWF content in HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

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

Converting Date and RegExp objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

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

iii

Chapter 3: Handling HTML-related events in AIR

HTMLLoader events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

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

Adobe AIR event objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Handling runtime events with JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Chapter 4: Scripting the AIR HTML Container

Display properties of HTMLLoader objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Accessing the HTML history list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

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

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

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

Chapter 5: Working with vectors

Basics of vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Creating vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Inserting elements into a vector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Retrieving values and removing vector elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Properties and methods of Vector objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Example: Using AIR APIs that require vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Chapter 6: AIR security

AIR security basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Installation and updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

HTML security in Adobe AIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Scripting between content in different domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Writing to disk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Working securely with untrusted content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Last updated 9/28/2011

HTML DEVELOPER’S GUIDE FOR ADOBE AIR

Contents

Best security practices for developers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Code signing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Chapter 7: Working with AIR native windows

Basics of native windows in AIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Creating windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Managing windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Listening for window events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Displaying full-screen windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Chapter 8: Display screens in AIR

Basics of display screens in AIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Enumerating the screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Chapter 9: Working with menus

Menu basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Creating native menus (AIR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

About context menus in HTML (AIR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Displaying pop-up native menus (AIR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Handling menu events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Native menu example: Window and application menu (AIR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Using the MenuBuilder framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Chapter 10: Taskbar icons in AIR

About taskbar icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

Dock icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

System Tray icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Window taskbar icons and buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Chapter 11: Working with the file system

Using the AIR file system API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Chapter 12: Drag and drop in AIR

Drag and drop in HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

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

Dragging data into an HTML element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

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

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

Dropping file promises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Chapter 13: Copy and paste

Basics of copy-and-paste . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

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

HTML copy and paste in AIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

Clipboard data formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Chapter 14: Working with local SQL databases in AIR

About local SQL databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

Creating and modifying a database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Last updated 9/28/2011

HTML DEVELOPER’S GUIDE FOR ADOBE AIR

Contents

Manipulating SQL database data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Using synchronous and asynchronous database operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

Using encryption with SQL databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

Strategies for working with SQL databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

Chapter 15: Encrypted local storage

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

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

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

Chapter 16: Working with byte arrays

Reading and writing a ByteArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

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

Chapter 17: Adding PDF content in AIR

Detecting PDF Capability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

Loading PDF content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

Scripting PDF content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

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

Chapter 18: Working with sound

Basics of working with sound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

Understanding the sound architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

Loading external sound files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

Working with embedded sounds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279

Working with streaming sound files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279

Working with dynamically generated audio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280

Playing sounds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

Working with sound metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Accessing raw sound data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

Capturing sound input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

Chapter 19: Client system environment

Basics of the client system environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

Using the System class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

Using the Capabilities class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

Chapter 20: AIR application invocation and termination

Application invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

Capturing command line arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

Invoking an AIR application on user login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

Invoking an AIR application from the browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

Application termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

Chapter 21: Working with AIR runtime and operating system information

Managing file associations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

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

Detecting AIR capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

Tracking user presence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

Last updated 9/28/2011

HTML DEVELOPER’S GUIDE FOR ADOBE AIR

Contents

Chapter 22: Sockets

TCP sockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

UDP sockets (AIR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

IPv6 addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

Chapter 23: HTTP communications

Loading external data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

Web service requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

Opening a URL in another application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

Sending a URL to a server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

Chapter 24: Communicating with other Flash Player and AIR instances

About the LocalConnection class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

Sending messages between two applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

Connecting to content in different domains and to AIR applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

Chapter 25: ActionScript basics for JavaScript developers

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

ActionScript 3.0 data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336

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

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

ActionScript 3.0 event listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

Chapter 26: SQL support in local databases

Supported SQL syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

Data type support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362

Chapter 27: SQL error detail messages, ids, and arguments

Last updated 9/28/2011

Chapter 1: About the HTML environment

Adobe AIR 1.0 and later

AIR uses WebKit (www.webkit.org), also used by the Safari web browser, to parse, layout, and render HTML and JavaScript content. The built-in host classes and objects of AIR provide an API for features traditionally associated with desktop applications. Such features include reading and writing files and managing windows. Adobe AIR also inherits APIs from the Adobe® Flash® Player, which include features like sound and binary sockets.

Important: New versions of the Adobe AIR runtime may include updated versions of WebKit. A WebKit update in a new version of AIR may result in unexpected changes in a deployed AIR application. These changes may affect the behavior or appearance of HTML content in an application. For example, improvements or corrections in WebKit rendering may change the layout of elements in an application’s user interface. For this reason, it is highly recommended that you provide an update mechanism in your application. Should you need to update your application due to a change in the WebKit version included in AIR, the AIR update mechanism can prompt the user to install the new version of your application.

The following table lists the version of WebKit used in each release of AIR. The closest corresponding release of the Safari web browser is also given:

AIR version WebKit version Safari version

1.0 420 2.04

1.1 523 3.04

1.5 526.9 4.0 Beta

2.0 531.9 4.03

2.5 531.9 4.03

2.6 531.9 4.03

You can always determine the installed version of WebKit by examining the default user agent string returned by a HTMLLoader object:

air.trace( window.htmlLoader.userAgent );

Keep in mind that the version of WebKit used in AIR is not identical to the open source version. Some features are not supported in AIR and the AIR version can include security and bug fixes not yet available in the corresponding WebKit version. See

“WebKit features not supported in AIR” on page 16.

Using the AIR APIs in HTML content is entirely optional. You can program an AIR application entirely with HTML and JavaScript. Most existing HTML applications should run with few changes (assuming they use HTML, CSS, DOM, and JavaScript features compatible with WebKit).

AIR gives you complete control over the look-and-feel of your application. You can make your application look like a native desktop application. You can turn off the window chrome provided by the operating system and implement your own controls for moving, resizing, and closing windows. You can even run without a window.

Because AIR applications run directly on the desktop, with full access to the file system, the security model is more stringent than the security model of the typical web browser. In AIR, only content loaded from the application installation directory is placed in the application sandbox. The application sandbox has the highest level of privilege and allows access to the AIR APIs. AIR places other content into isolated sandboxes based on where that content came from. Files loaded from the file system go into a local sandbox. Files loaded from the network using the http: or https: protocols go into a sandbox based on the domain of the remote server. Content in these non-application sandboxes is prohibited from accessing any AIR API and runs much as it would in a typical web browser.

Last updated 9/28/2011

HTML DEVELOPER’S GUIDE FOR ADOBE AIR

About the HTML environment

HTML content in AIR does not display SWF or PDF content if alpha, scaling, or transparency settings are applied. For more information, see “Window transparency” on page 87.

“Considerations when loading SWF or PDF content in an HTML page” on page 48 and

Overview of the HTML environment

Adobe AIR 1.0 and later

Adobe AIR provides a complete browser-like JavaScript environment with an HTML renderer, document object model, and JavaScript interpreter. The JavaScript environment is represented by the AIR HTMLLoader class. In HTML windows, an HTMLLoader object contains all HTML content, and is, in turn, contained within a NativeWindow object. The NativeWindow object allows an application to script the properties and behavior of native operating system window displayed on the user’s desktop.

About the JavaScript environment and its relationship to the AIR host

Adobe AIR 1.0 and later

The following diagram illustrates the relationship between the JavaScript environment and the AIR run-time environment. Although only a single native window is shown, an AIR application can contain multiple windows. (And a single window can contain multiple HTMLLoader objects.)

Last updated 9/28/2011

HTML DEVELOPER’S GUIDE FOR ADOBE AIR

About the HTML environment

AIR Run-time Environment

NativeWindow

HTMLLoader

window

JavaScript Environment

window

document

body

h1 divptable

The JavaScript environment has its own Document and Window objects. JavaScript code can interact with the AIR run-time environment through the runtime, nativeWindow, and htmlLoader properties. ActionScript code can interact with the JavaScript environment through the window property of an HTMLLoader object, which is a reference to the JavaScript Window object. In addition, both ActionScript and JavaScript objects can listen for events dispatched by both AIR and JavaScript objects.

head

htmlLoader

nativeWindow

runtime

The runtime property provides access to AIR API classes, allowing you to create new AIR objects as well as access class (also called static) members. To access an AIR API, you add the name of the class, with package, to the

runtime

property. For example, to create a File object, you would use the statement:

var file = new window.runtime.filesystem.File();

Note: The AIR SDK provides a JavaScript file, AIRAliases.js, that defines more convenient aliases for the most commonly used AIR classes. When you import this file, you can use the shorter form air.Class instead of window.runtime.package.Class. For example, you could create the File object with

new air.File().

The NativeWindow object provides properties for controlling the desktop window. From within an HTML page, you can access the containing NativeWindow object with the

window.nativeWindow property.

The HTMLLoader object provides properties, methods, and events for controlling how content is loaded and rendered. From within an HTML page, you can access the parent HTMLLoader object with the

window.htmlLoader

property.

Last updated 9/28/2011

HTML DEVELOPER’S GUIDE FOR ADOBE AIR

About the HTML environment

Important: Only pages installed as part of an application have the htmlLoader, nativeWindow, or runtime properties and only when loaded as the top-level document. These properties are not added when a document is loaded into a frame or iframe. (A child document can access these properties on the parent document as long as it is in the same security sandbox. For example, a document loaded in a frame could access the

parent.runtime.)

runtime property of its parent with

About security

Adobe AIR 1.0 and later

AIR executes all code within a security sandbox based on the domain of origin. Application content, which is limited to content loaded from the application installation directory, is placed into the application sandbox. Access to the runtime environment and the AIR APIs are only available to HTML and JavaScript running within this sandbox. At the same time, most dynamic evaluation and execution of JavaScript is blocked in the application sandbox after all handlers for the page

You can map an application page into a non-application sandbox by loading the page into a frame or iframe and setting the AIR-specific actual remote domain, you can enable the sandboxed content to cross-script content in that domain. Mapping pages in this way can be useful when loading and scripting remote content, such as in a mash-up application.

load event have returned.

sandboxRoot and documentRoot attributes of the frame. By setting the sandboxRoot value to an

Another way to allow application and non-application content to cross-script each other, and the only way to give nonapplication content access to AIR APIs, is to create a sandbox bridge. A parent-to-child bridge allows content in a child frame, iframe, or window to access designated methods and properties defined in the application sandbox. Conversely, a child-to-parent bridge allows application content to access designated methods and properties defined in the sandbox of the child. Sandbox bridges are established by setting the properties of the window object. For more information, see

parentSandboxBridge and childSandboxBridge

“HTML security in Adobe AIR” on page 73 and “HTML

frame and iframe elements” on page 12.

About plug-ins and embedded objects

Adobe AIR 1.0 and later

AIR supports the Adobe® Acrobat® plug-in. Users must have Acrobat or Adobe® Reader® 8.1 (or better) to display PDF content. The HTMLLoader object provides a property for checking whether a user’s system can display PDF. SWF file content can also be displayed within the HTML environment, but this capability is built in to AIR and does not use an external plug-in.

No other WebKit plug-ins are supported in AIR.

AIR and WebKit

Adobe AIR 1.0 and later

Adobe AIR uses the open source WebKit engine, also used in the Safari web browser. AIR adds several extensions to allow access to the runtime classes and objects as well as for security. In addition, WebKit itself adds features not included in the W3C standards for HTML, CSS, and JavaScript.

Only the AIR additions and the most noteworthy WebKit extensions are covered here; for additional documentation on non-standard HTML, CSS, and JavaScript, see information, see the W3C web site. Mozilla also provides a valuable general referenceon HTML, CSS, and DOM topics (of course, the WebKit and Mozilla engines are not identical).

JavaScript in AIR

Flash Player 9 and later, Adobe AIR 1.0 and later

AIR makes several changes to the typical behavior of common JavaScript objects. Many of these changes are made to make it easier to write secure applications in AIR. At the same time, these differences in behavior mean that some common JavaScript coding patterns, and existing web applications using those patterns, might not always execute as expected in AIR. For information on correcting these types of issues, see on page 22.

www.webkit.org and developer.apple.com. For standards

“Avoiding security-related JavaScript errors”

HTML Sandboxes

Adobe AIR 1.0 and later

AIR places content into isolated sandboxes according to the origin of the content. The sandbox rules are consistent with the same-origin policy implemented by most web browsers, as well as the rules for sandboxes implemented by the Adobe Flash Player. In addition, AIR provides a new application sandbox type to contain and protect application content. See Security sandboxes for more information on the types of sandboxes you may encounter when developing AIR applications.

Access to the run-time environment and AIR APIs are only available to HTML and JavaScript running within the application sandbox. At the same time, however, dynamic evaluation and execution of JavaScript, in its various forms, is largely restricted within the application sandbox for security reasons. These restrictions are in place whether or not your application actually loads information directly from a server. (Even file content, pasted strings, and direct user input may be untrustworthy.)

The origin of the content in a page determines the sandbox to which it is consigned. Only content loaded from the application directory (the installation directory referenced by the sandbox. Content loaded from the file system is placed in the local-with-file system or the local-trusted sandbox, which allows access and interaction with content on the local file system, but not remote content. Content loaded from the network is placed in a remote sandbox corresponding to its domain of origin.

To allow an application page to interact freely with content in a remote sandbox, the page can be mapped to the same domain as the remote content. For example, if you write an application that displays map data from an Internet service, the page of your application that loads and displays content from the service could be mapped to the service domain. The attributes for mapping pages into a remote sandbox and domain are new attributes added to the frame and iframe HTML elements.

app: URL scheme) is placed in the application

Last updated 9/28/2011

HTML DEVELOPER’S GUIDE FOR ADOBE AIR

About the HTML environment

To allow content in a non-application sandbox to safely use AIR features, you can set up a parent sandbox bridge. To allow application content to safely call methods and access properties of content in other sandboxes, you can set up a child sandbox bridge. Safety here means that remote content cannot accidentally get references to objects, properties, or methods that are not explicitly exposed. Only simple data types, functions, and anonymous objects can be passed across the bridge. However, you must still avoid explicitly exposing potentially dangerous functions. If, for example, you exposed an interface that allowed remote content to read and write files anywhere on a user’s system, then you might be giving remote content the means to do considerable harm to your users.

JavaScript eval() function

Adobe AIR 1.0 and later

Use of the eval() function is restricted within the application sandbox once a page has finished loading. Some uses are permitted so that JSON-formatted data can be safely parsed, but any evaluation that results in executable statements results in an error.

“Code restrictions for content in different sandboxes” on page 76 describes the allowed

uses of the eval() function.

Function constructors

Adobe AIR 1.0 and later

In the application sandbox, function constructors can be used before a page has finished loading. After all page load event handlers have finished, new functions cannot be created.

Loading external scripts

Adobe AIR 1.0 and later

HTML pages in the application sandbox cannot use the script tag to load JavaScript files from outside of the application directory. For a page in your application to load a script from outside the application directory, the page must be mapped to a non-application sandbox.

The XMLHttpRequest object

Adobe AIR 1.0 and later

AIR provides an XMLHttpRequest (XHR) object that applications can use to make data requests. The following example illustrates a simple data request:

xmlhttp = new XMLHttpRequest(); xmlhttp.open("GET", "http:/www.example.com/file.data", true); xmlhttp.onreadystatechange = function() { if (xmlhttp.readyState == 4) { //do something with data... } } xmlhttp.send(null);

In contrast to a browser, AIR allows content running in the application sandbox to request data from any domain. The result of an XHR that contains a JSON string can be evaluated into data objects unless the result also contains executable code. If executable statements are present in the XHR result, an error is thrown and the evaluation attempt fails.

To prevent accidental injection of code from remote sources, synchronous XHRs return an empty result if made before a page has finished loading. Asynchronous XHRs will always return after a page has loaded.

Last updated 9/28/2011

HTML DEVELOPER’S GUIDE FOR ADOBE AIR

About the HTML environment

By default, AIR blocks cross-domain XMLHttpRequests in non-application sandboxes. A parent window in the application sandbox can choose to allow cross-domain requests in a child frame containing content in a nonapplication sandbox by setting

allowCrossDomainXHR, an attribute added by AIR, to true in the containing frame or

iframe element:

Note: When convenient, the AIR URLStream class can also be used to download data.

If you dispatch an XMLHttpRequest to a remote server from a frame or iframe containing application content that has been mapped to a remote sandbox, make sure that the mapping URL does not mask the server address used in the XHR. For example, consider the following iframe definition, which maps application content into a remote sandbox for the example.com domain:

Because the sandboxRoot attribute remaps the root URL of the www.example.com address, all requests are loaded from the application directory and not the remote server. Requests are remapped whether they derive from page navigation or from an XMLHttpRequest.

To avoid accidentally blocking data requests to your remote server, map the sandboxRoot to a subdirectory of the remote URL rather than the root. The directory does not have to exist. For example, to allow requests to the www.example.com to load from the remote server rather than the application directory, change the previous iframe to the following:

In this case, only content in the air subdirectory is loaded locally.

For more information on sandbox mapping see “HTML frame and iframe elements” on page 12 and “HTML security

in Adobe AIR” on page 73.

Cookies

Adobe AIR 1.0 and later

In AIR applications, only content in remote sandboxes (content loaded from http: and https: sources) can use cookies

document.cookie property). In the application sandbox, other means for storing persistent data are available,

(the including the EncryptedLocalStore, SharedObject, and FileStream classes.

Last updated 9/28/2011

HTML DEVELOPER’S GUIDE FOR ADOBE AIR

About the HTML environment

The Clipboard object

Adobe AIR 1.0 and later

The WebKit Clipboard API is driven with the following events: copy, cut, and paste. The event object passed in these events provides access to the clipboard through the

clipboardData object to read or write clipboard data:

Method Description

clearData(mimeType) Clears the clipboard data. Set the mimeType parameter to the MIME type of the data to clear.

clipboardData property. Use the following methods of the

getData(mimeType) Get the clipboard data. This method can only be called in a handler for the paste event. Set the mimeType

setData(mimeType, data) Copy data to the clipboard. Set the mimeType parameter to the MIME type of the data.

parameter to the MIME type of the data to return.

JavaScript code outside the application sandbox can only access the clipboard through theses events. However, content in the application sandbox can access the system clipboard directly using the AIR Clipboard class. For example, you could use the following statement to get text format data on the clipboard:

var clipping = air.Clipboard.generalClipboard.getData("text/plain", air.ClipboardTransferMode.ORIGINAL_ONLY);

The valid data MIME types are:

MIME type Value

Text "text/plain"

HTML "text/html"

URL "text/uri-list"

Bitmap "image/x-vnd.adobe.air.bitmap"

File list "application/x-vnd.adobe.air.file-list"

Important: Only content in the application sandbox can access file data present on the clipboard. If non-application content attempts to access a file object from the clipboard, a security error is thrown.

For more information on using the clipboard, see “Copy and paste” on page 195 and Using the Pasteboard from

JavaScript (Apple Developer Center).

Drag and Drop

Adobe AIR 1.0 and later

Drag-and-drop gestures into and out of HTML produce the following DOM events: dragstart, drag, dragend,

dragenter, dragover, dragleave, and drop. The event object passed in these events provides access to the dragged

data through the methods as the function to get text format data from a

function onDrop(dragEvent){ return dragEvent.dataTransfer.getData("text/plain", air.ClipboardTransferMode.ORIGINAL_ONLY); }

The dataTransfer object has the following important members:

dataTransfer property. The dataTransfer property references an object that provides the same

clipboardData object associated with a clipboard event. For example, you could use the following

drop event:

Last updated 9/28/2011

HTML DEVELOPER’S GUIDE FOR ADOBE AIR

About the HTML environment

Member Description

clearData(mimeType) Clears the data. Set the mimeType parameter to the MIME type of the data representation to clear.

getData(mimeType) Get the dragged data. This method can only be called in a handler for the drop event. Set the mimeType

setData(mimeType, data) Set the data to be dragged. Set the mimeType parameter to the MIME type of the data.

types An array of strings containing the MIME types of all data representations currently available in the

effectsAllowed Specifies whether the data being dragged can be copied, moved, linked, or some combination thereof. Set the

dropEffect Specifies which of the allowed drop effects are supported by a drag target. Set the dropEffect property in

parameter to the MIME type of the data to get.

dataTransfer object.

effectsAllowed property in the handler for the dragstart event.

the handler for the occur if the user released the mouse. If no chosen. The copy effect has priority over the move effect, which itself has priority over the link effect. The user can modify the default priority using the keyboard.

dragEnter event. During the drag, the cursor changes to indicate which effect would

dropEffect is specified, an effectsAllowed property effect is

For more information on adding support for drag-and-drop to an AIR application see “Drag and drop in AIR” on page 177 and Using the Drag-and-Drop from JavaScript (Apple Developer Center).

innerHTML and outerHTML properties

Adobe AIR 1.0 and later

AIR places security restrictions on the use of the innerHTML and outerHTML properties for content running in the application sandbox. Before the page load event, as well as during the execution of any load event handlers, use of the

innerHTML and outerHTML properties is unrestricted. However, once the page has loaded, you can only use innerHTML or outerHTML properties to add static content to the document. Any statement in the string assigned to innerHTML or outerHTML that evaluates to executable code is ignored. For example, if you include an event callback

attribute in an element definition, the event listener is not added. Likewise, embedded evaluated. For more information, see the

“HTML security in Adobe AIR” on page 73.

Document.write() and Document.writeln() methods

Adobe AIR 1.0 and later

Use of the write() and writeln() methods is not restricted in the application sandbox before the load event of the page. However, once the page has loaded, calling either of these methods does not clear the page or create a new one. In a non-application sandbox, as in most web browsers, calling

document.write() or writeln() after a page has

finished loading clears the current page and opens a new, blank one.

Document.designMode property

Adobe AIR 1.0 and later

Set the document.designMode property to a value of on to make all elements in the document editable. Built-in editor support includes text editing, copy, paste, and drag-and-drop. Setting

contentEditable property of the body element to true. You can use the contentEditable property on most

HTML elements to define which sections of a document are editable. See page 14 for additional information.

Last updated 9/28/2011

designMode to on is equivalent to setting the

“HTML contentEditable attribute” on

HTML DEVELOPER’S GUIDE FOR ADOBE AIR

About the HTML environment

unload events (for body and frameset objects)

Adobe AIR 1.0 and later

In the top-level frameset or body tag of a window (including the main window of the application), do not use the

unload event to respond to the window (or application) being closed. Instead, use exiting event of the

NativeApplication object (to detect when an application is closing). Or use the

closing event of the NativeWindow

object (to detect when a window is closing). For example, the following JavaScript code displays a message

"Goodbye.") when the user closes the application:

(

var app = air.NativeApplication.nativeApplication; app.addEventListener(air.Event.EXITING, closeHandler); function closeHandler(event) { alert("Goodbye."); }

However, scripts can successfully respond to the unload event caused by navigation of a frame, iframe, or top-level window content.

Note: These limitations may be removed in a future version of Adobe AIR.

JavaScript Window object

Adobe AIR 1.0 and later

The Window object remains the global object in the JavaScript execution context. In the application sandbox, AIR adds new properties to the JavaScript Window object to provide access to the built-in classes of AIR, as well as important host objects. In addition, some methods and properties behave differently depending on whether they are within the application sandbox or not.

Window.runtime property The runtime property allows you to instantiate and use the built-in runtime classes from

within the application sandbox. These classes include the AIR and Flash Player APIs (but not, for example, the Flex framework). For example, the following statement creates an AIR file object:

var preferencesFile = new window.runtime.flash.filesystem.File();

The AIRAliases.js file, provided in the AIR SDK, contains alias definitions that allow you to shorten such references. For example, when

var preferencesFile = new air.File();

AIRAliases.js is imported into a page, a File object can be created with the following statement:

The window.runtime property is only defined for content within the application sandbox and only for the parent document of a page with frames or iframes.

See “Using the AIRAliases.js file” on page 28.

Window.nativeWindow property The nativeWindow property provides a reference to the underlying native window

object. With this property, you can script window functions and properties such as screen position, size, and visibility, and handle window events such as closing, resizing, and moving. For example, the following statement closes the window:

window.nativeWindow.close();

Note: The window control features provided by the NativeWindow object overlap the features provided by the JavaScript Window object. In such cases, you can use whichever method you find most convenient.

The window.nativeWindow property is only defined for content within the application sandbox and only for the parent document of a page with frames or iframes.

Last updated 9/28/2011

HTML DEVELOPER’S GUIDE FOR ADOBE AIR

About the HTML environment

Window.htmlLoader property The htmlLoader property provides a reference to the AIR HTMLLoader object that

contains the HTML content. With this property, you can script the appearance and behavior of the HTML environment. For example, you can use the

htmlLoader.paintsDefaultBackground property to determine whether

the control paints a default, white background:

window.htmlLoader.paintsDefaultBackground = false;

Note: The HTMLLoader object itself has a window property, which references the JavaScript Window object of the HTML content it contains. You can use this property to access the JavaScript environment through a reference to the containing HTMLLoader.

The window.htmlLoader property is only defined for content within the application sandbox and only for the parent document of a page with frames or iframes.

Window.parentSandboxBridge and Window.childSandboxBridge properties The parentSandboxBridge and

childSandboxBridge properties allow you to define an interface between a parent and a child frame. For more

information, see

Window.setTimeout() and Window.setInterval() functions AIR places security restrictions on use of the

setTimeout() and setInterval() functions within the application sandbox. You cannot define the code to be

executed as a string when calling information, see

“Cross-scripting content in different security sandboxes” on page 34.

setTimeout() or setInterval(). You must use a function reference. For more

“setTimeout() and setInterval()” on page 25.

Window.open() function When called by code running in a non-application sandbox, the open() method only opens

a window when called as a result of user interaction (such as a mouse click or keypress). In addition, the window title is prefixed with the application title (to prevent windows opened by remote content from impersonating windows opened by the application). For more information, see the

“Restrictions on calling the JavaScript window.open()

method” on page 78.

air.NativeApplication object

Adobe AIR 1.0 and later

The NativeApplication object provides information about the application state, dispatches several important application-level events, and provides useful functions for controlling application behavior. A single instance of the NativeApplication object is created automatically and can be accessed through the class-defined

NativeApplication.nativeApplication property.

To access the object from JavaScript code you could use:

var app = window.runtime.flash.desktop.NativeApplication.nativeApplication;

Or, if the AIRAliases.js script has been imported, you could use the shorter form:

var app = air.NativeApplication.nativeApplication;

The NativeApplication object can only be accessed from within the application sandbox. For more information about the NativeApplication object, see

“Working with AIR runtime and operating system information” on page 304.

The JavaScript URL scheme

Adobe AIR 1.0 and later

Execution of code defined in a JavaScript URL scheme (as in href="javascript:alert('Test')") is blocked within the application sandbox. No error is thrown.

Last updated 9/28/2011

HTML DEVELOPER’S GUIDE FOR ADOBE AIR

About the HTML environment

HTML in AIR

Adobe AIR 1.0 and later

AIR and WebKit define a couple of non-standard HTML elements and attributes, including:

“HTML frame and iframe elements” on page 12

“HTML element event handlers” on page 14

HTML frame and iframe elements

Adobe AIR 1.0 and later

AIR adds new attributes to the frame and iframe elements of content in the application sandbox:

sandboxRoot attribute The sandboxRoot attribute specifies an alternate, non-application domain of origin for the file

specified by the frame domain. Content in the file and content loaded from the specified domain can cross-script each other.

Important: If you set the value of sandboxRoot to the base URL of the domain, all requests for content from that domain are loaded from the application directory instead of the remote server (whether that request results from page navigation, from an XMLHttpRequest, or from any other means of loading content).

src attribute. The file is loaded into the non-application sandbox corresponding to the specified

documentRoot attribute The documentRoot attribute specifies the local directory from which to load URLs that

resolve to files within the location specified by

sandboxRoot.

When resolving URLs, either in the frame src attribute, or in content loaded into the frame, the part of the URL matching the value specified in

sandboxRoot is replaced with the value specified in documentRoot. Thus, in the

following frame tag:

child.html is loaded from the sandbox subdirectory of the application installation folder. Relative URLs in child.html are resolved based on sandbox directory. Note that any files on the remote server at www.example.com/air are not accessible in the frame, since AIR would attempt to load them from the app:/sandbox/

directory.

allowCrossDomainXHR attribute Include allowCrossDomainXHR="allowCrossDomainXHR" in the opening frame

tag to allow content in the frame to make XMLHttpRequests to any remote domain. By default, non-application content can only make such requests to its own domain of origin. There are serious security implications involved in allowing cross-domain XHRs. Code in the page is able to exchange data with any domain. If malicious content is somehow injected into the page, any data accessible to code in the current sandbox can be compromised. Only enable cross-domain XHRs for pages that you create and control and only when cross-domain data loading is truly necessary. Also, carefully validate all external data loaded by the page to prevent code injection or other forms of attack.

Important: If the allowCrossDomainXHR attribute is included in a frame or iframe element, cross-domain XHRs are enabled (unless the value assigned is "0" or starts with the letters "f" or "n"). For example, setting

deny" would still enable cross-domain XHRs. Leave the attribute out of the element declaration altogether if you do

to "

allowCrossDomainXHR

not want to enable cross-domain requests.

ondominitialize attribute Specifies an event handler for the dominitialize event of a frame. This event is an AIR-

specific event that fires when the window and document objects of the frame have been created, but before any scripts have been parsed or document elements created.

Last updated 9/28/2011

HTML DEVELOPER’S GUIDE FOR ADOBE AIR

About the HTML environment

The frame dispatches the dominitialize event early enough in the loading sequence that any script in the child page can reference objects, variables, and functions added to the child document by the

dominitialize handler. The

parent page must be in the same sandbox as the child to directly add or access any objects in a child document. However, a parent in the application sandbox can establish a sandbox bridge to communicate with content in a nonapplication sandbox.

The following examples illustrate use of the iframe tag in AIR:

Place child.html in a remote sandbox, without mapping to an actual domain on a remote server:

Place child.html in a remote sandbox, allowing XMLHttpRequests only to www.example.com:

Place child.html in a remote sandbox, allowing XMLHttpRequests to any remote domain:

Place child.html in a local-with-file-system sandbox:

Place child.html in a remote sandbox, using the dominitialize event to establish a sandbox bridge:

<html> <head> <script> var bridgeInterface = {}; bridgeInterface.testProperty = "Bridge engaged"; function engageBridge(){ document.getElementById("sandbox").parentSandboxBridge = bridgeInterface; } </script> </head> <body> <iframe id="sandbox" src="http://www.example.com/air/child.html" documentRoot="app:/" sandboxRoot="http://www.example.com/air/" ondominitialize="engageBridge()"/> </body> </html>

The following child.html document illustrates how child content can access the parent sandbox bridge:

Last updated 9/28/2011

HTML DEVELOPER’S GUIDE FOR ADOBE AIR

About the HTML environment

<html> <head> <script> document.write(window.parentSandboxBridge.testProperty); </script> </head> <body></body> </html>

For more information, see “Cross-scripting content in different security sandboxes” on page 34 and “HTML security

in Adobe AIR” on page 73.

HTML element event handlers

Adobe AIR 1.0 and later

DOM objects in AIR and WebKit dispatch some events not found in the standard DOM event model. The following table lists the related event attributes you can use to specify handlers for these events:

Callback attribute name Description

oncontextmenu Called when a context menu is invoked, such as through a right-click

oncopy Called when a selection in an element is copied.

oncut Called when a selection in an element is cut.

ondominitialize Called when the DOM of a document loaded in a frame or iframe is

ondrag Called when an element is dragged.

ondragend Called when a drag is released.

ondragenter Called when a drag gesture enters the bounds of an element.

ondragleave Called when a drag gesture leaves the bounds of an element.

ondragover Called continuously while a drag gesture is within the bounds of an

ondragstart Called when a drag gesture begins.

ondrop Called when a drag gesture is released while over an element.

onerror Called when an error occurs while loading an element.

oninput Called when text is entered into a form element.

onpaste Called when an item is pasted into an element.

onscroll Called when the content of a scrollable element is scrolled.

or command-click on selected text.

created, but before any DOM elements are created or scripts parsed.

element.

onselectstart Called when a selection begins.

HTML contentEditable attribute

Adobe AIR 1.0 and later

You can add the contentEditable attribute to any HTML element to allow users to edit the content of the element. For example, the following example HTML code sets the entire document as editable, except for first

Last updated 9/28/2011

p element:

HTML DEVELOPER’S GUIDE FOR ADOBE AIR

About the HTML environment

<html> <head/> <body contentEditable="true"> <h1>de Finibus Bonorum et Malorum</h1> <p contentEditable="false">Sed ut perspiciatis unde omnis iste natus error.</p> <p>At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis.</p> </body> </html>

Note: If you set the document.designMode property to on, then all elements in the document are editable, regardless of the setting of editing of elements for which

contentEditable for an individual element. However, setting designMode to off, does not disable

contentEditable is true. See “Document.designMode property” on page 9 for additional

information.

Data: URLs

Adobe AIR 2 and later

AIR supports data: URLs for the following elements:

• img

• input type=”image”

• CSS rules allowing images (such as background-image)

Data URLs allow you to insert binary image data directly into a CSS or HTML document as a base64-encoded string. The following example uses a data: URL as a repeating background:

<html> <head> <style> body { backgroundimage:url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGQAAABkCAMAAABHPGVmAAAAGXRFWHRTb2Z 0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAAZQTFRF%2F6cA%2F%2F%2F%2Fgxp3lwAAAAJ0Uk5T%2FwDltzBKAAA BF0lEQVR42uzZQQ7CMAxE0e%2F7X5oNCyRocWzPiJbMBZ6qpIljE%2BnwklgKG7kwUjc2IkIaxkY0CPdEsCCasws6ShX BgmBBmEagpXQQLAgWBAuSY2gaKaWPYEGwIEwg0FRmECwIFoQeQjJlhJWUEFazjFDJCkI5WYRWMgjtfEGYyQnCXD4jTCd m1zmngFpBFznwVNi5RPSbwbWnpYr%2BBHi%2FtCTfgPLEPL7jBctAKBRptXJ8M%2BprIuZKu%2BUKcg4YK1PLz7kx4bS qHyPaT4d%2B28OCJJiRBo4FCQsSA0bziT3XubMgYUG6fc5fatmGBQkL0hoJ1IaZMiQsSFiQ8vRscTjlQOI2iHZwtpHuf %2BJAYiOiJSkj8Z%2FIQ4ABANvXGLd3%2BZMrAAAAAElFTkSuQmCC'); background-repeat:repeat; } </style> </head> <body> </body> </html>

When using data: URLS, be aware that extra whitespace is significant. For example, the data string must be entered as a single, unbroken line. Otherwise, the line breaks are treated as part of the data and the image cannot be decoded.

Last updated 9/28/2011

HTML DEVELOPER’S GUIDE FOR ADOBE AIR

About the HTML environment

CSS in AIR

Adobe AIR 1.0 and later

WebKit supports several extended CSS properties. Many of these extensions use the prefix: -webkit. Note that some of these extensions are experimental in nature and may be removed from a future version of WebKit. For more information about the Webkit support for CSS and its extensions to CSS, see

Safari CSS Reference.

WebKit features not supported in AIR

Adobe AIR 1.0 and later

AIR does not support the following features available in WebKit or Safari 4:

• Cross-domain messaging via window.postMessage (AIR provides its own cross-domain communication APIs)

• CSS variables

• Web Open Font Format (WOFF) and SVG fonts.

• HTML video and audio tags

• Media device queries

• Offline application cache

• Printing (AIR provides its own PrintJob API)

• Spelling and grammar checkers

• SVG

• WAI-ARIA

• WebSockets (AIR provides its own socket APIs)

• Web workers

• WebKit SQL API (AIR provides its own API)

• WebKit geolocation API (AIR provides its own geolocation API on supported devices)

• WebKit multi-file upload API

• WebKit touch events (AIR provides its own touch events)

• Wireless Markup Language (WML)

The following lists contain specific JavaScript APIs, HTML elements, and CSS properties and values that AIR does not support:

Unsupported JavaScript Window object members:

• applicationCache()

• console

• openDatabase()

• postMessage()

• document.print()

Unsupported HTML tags:

• audio

Last updated 9/28/2011

HTML DEVELOPER’S GUIDE FOR ADOBE AIR

About the HTML environment

• video

Unsupported HTML attributes:

• aria-*

• draggable

• formnovalidate

• list

• novalidate

• onbeforeload

• onhashchange

• onorientationchange

• onpagehide

• onpageshow

• onpopstate

• ontouchstart

• ontouchmove

• ontouchend

• ontouchcancel

• onwebkitbeginfullscreen

• onwebkitendfullscreen

• pattern

• required

• sandbox

Unsupported JavaScript events:

• beforeload

• hashchange

• orientationchange

• pagehide

• pageshow

• popstate

• touchstart

• touchmove

• touchend

• touchcancel

• webkitbeginfullscreen

• webkitendfullscreen

Last updated 9/28/2011

HTML DEVELOPER’S GUIDE FOR ADOBE AIR

About the HTML environment

Unsupported CSS properties:

• background-clip

• background-origin (use -webkit-background-origin)

• background-repeat-x

• background-repeat-y

• background-size (use -webkit-background-size)

• border-bottom-left-radius

• border-bottom-right-radius

• border-radius

• border-top-left-radius

• border-top-right-radius

• text-rendering

• -webkit-animation-play-state

• -webkit-background-clip

• -webkit-color-correction

• -webkit-font-smoothing

Unsupported CSS values:

• appearance property values:

• media-volume-slider-container

• media-volume-slider

• media-volume-sliderthumb

• outer-spin-button

• border-box (background-clip and background-origin)

• contain (background-size)

• content-box (background-clip and background-origin)

• cover (background-size)

• list property values:

• afar

• amharic

• amharic-abegede

• cjk-earthly-branch

• cjk-heavenly-stem

• ethiopic

• ethiopic-abegede

• ethiopic-abegede-am-et

• ethiopic-abegede-gez

• ethiopic-abegede-ti-er

Last updated 9/28/2011

HTML DEVELOPER’S GUIDE FOR ADOBE AIR

About the HTML environment

• ethiopic-abegede-ti-et

• ethiopic-halehame-aa-er

• ethiopic-halehame-aa-et

• ethiopic-halehame-am-et

• ethiopic-halehame-gez

• ethiopic-halehame-om-et

• ethiopic-halehame-sid-et

• ethiopic-halehame-so-et

• ethiopic-halehame-ti-er

• ethiopic-halehame-ti-et

• ethiopic-halehame-tig

• hangul

• hangul-consonant

• lower-norwegian

• oromo

• sidama

• somali

• tigre

• tigrinya-er

• tigrinya-er-abegede

• tigrinya-et

• tigrinya-et-abegede

• upper-greek

• upper-norwegian

• -wap-marquee (display property)

Last updated 9/28/2011

Chapter 2: Programming HTML and JavaScript in AIR

Adobe AIR 1.0 and later

A number of programming topics are unique to developing Adobe® AIR® applications with HTML and JavaScript. The following information is important whether you are programming an HTML-based AIR application or programming a SWF-based AIR application that runs HTML and JavaScript using the HTMLLoader class (or mx:HTML Flex™ component).

Creating an HTML-based AIR application

Adobe AIR 1.0 and later

The process of developing an AIR application is much the same as that of developing an HTML-based web application. Application structure remains page-based, with HTML providing the document structure and JavaScript providing the application logic. In addition, an AIR application requires an application descriptor file, which contains metadata about the application and identifies the root file of the application.

If you are using Adobe® Dreamweaver®, you can test and package an AIR application directly from the Dreamweaver user interface. If you are using the AIR SDK, you can test an AIR application using the command-line ADL utility. ADL reads the application descriptor and launches the application. You can package the application into an AIR installation file using the command-line ADT utility.

The basic steps to creating an AIR application are:

1 Create the application descriptor file. The content element identifies the root page of the application, which is

loaded automatically when your application is launched.

2 Create the application pages and code.

3 Test the application using the ADL utility or Dreamweaver.

4 Package the application into an AIR installation file with the ADT utility or Dreamweaver.

Last updated 9/28/2011

HTML DEVELOPER’S GUIDE FOR ADOBE AIR

Programming HTML and JavaScript in AIR

An example application and security implications

Adobe AIR 1.0 and later

The following HTML code uses uses the filesystem APIs to list the files and directories in the user’s desktop directory.

Here’s the HTML code for the application:

<html> <head> <title>Sample application</title> <script type="text/javascript" src="AIRAliases.js"></script> <script> function getDesktopFileList() { var log = document.getElementById("log"); var files = air.File.desktopDirectory.getDirectoryListing(); for (i = 0; i < files.length; i++) { log.innerHTML += files[i].name + "<br/>"; } } </script> </head> <body onload="getDesktopFileList();" style="padding: 10px"> <h2>Files and folders on the desktop:</h2> <div id="log" style="width: 450px; height: 200px; overflow-y: scroll;" /> </body> </html>

You also must set up an application descriptor file and test the application using the AIR Debug Launcher (ADL) application.

You could use most of the sample code in a web browser. However, there are a few lines of code that are specific to the runtime.

The getDesktopFileList() method uses the File class, which is defined in the runtime APIs. The first script tag in the application loads the AIRAliases.js file (supplied with the AIR SDK), which lets you easily access the AIR APIs. (For example, the example code accesses the AIR File class using the syntax

air.File.) For details, see “Using the

AIRAliases.js file” on page 28.

Last updated 9/28/2011

HTML DEVELOPER’S GUIDE FOR ADOBE AIR

Programming HTML and JavaScript in AIR

The File.desktopDirectory property is a File object (a type of object defined by the runtime). A File object is a reference to a file or directory on the user’s computer. The user’s desktop directory. The File objects. The

File.desktopDirectory.getDirectoryListing() method returns an array of File objects

getDirectoryListing() method is defined for any File object and returns an array of

File.desktopDirectory property is a reference to the

representing files and directories on the user’s desktop.

Each File object has a name property, which is the filename as a string. The for loop in the getDesktopFileList() method iterates through the files and directories on the user’s desktop directory and appends their names to the

innerHTML property of a div object in the application.

Important security rules when using HTML in AIR applications

Adobe AIR 1.0 and later

The files you install with the AIR application have access to the AIR APIs. For security reasons, content from other sources do not. For example, this restriction prevents content from a remote domain (such as http://example.com) from reading the contents the user’s desktop directory (or worse).

Because there are security loopholes that can be exploited through calling the eval() function (and related APIs), content installed with the application, by default, is restricted from using these methods. However, some Ajax frameworks use the calling the

eval() function and related APIs.

To properly structure content to work in an AIR application, you must take the rules for the security restrictions on content from different sources into account. Content from different sources is placed in separate security classifications, called sandboxes (see Security sandboxes). By default, content installed with the application is installed in a sandbox known as the application sandbox, and this grants it access to the AIR APIs. The application sandbox is generally the most secure sandbox, with restrictions designed to prevent the execution of untrusted code.

The runtime allows you to load content installed with your application into a sandbox other than the application sandbox. Content in non-application sandboxes operates in a security environment similar to that of a typical web browser. For example, code in non-application sandboxes can use

eval() and related methods (but at the same time

is not allowed to access the AIR APIs). The runtime includes ways to have content in different sandboxes communicate securely (without exposing AIR APIs to non-application content, for example). For details, see

“Cross-scripting

content in different security sandboxes” on page 34.

If you call code that is restricted from use in a sandbox for security reasons, the runtime dispatches a JavaScript error: “Adobe AIR runtime security violation for JavaScript code in the application security sandbox.”

To avoid this error, follow the coding practices described in the next section, “Avoiding security-related JavaScript

errors” on page 22.

For more information, see “HTML security in Adobe AIR” on page 73.

Avoiding security-related JavaScript errors

Adobe AIR 1.0 and later

If you call code that is restricted from use in a sandbox due to these security restrictions, the runtime dispatches a JavaScript error: “Adobe AIR runtime security violation for JavaScript code in the application security sandbox.” To avoid this error, follow these coding practices.

Last updated 9/28/2011

HTML DEVELOPER’S GUIDE FOR ADOBE AIR

Programming HTML and JavaScript in AIR

Causes of security-related JavaScript errors

Adobe AIR 1.0 and later

Code executing in the application sandbox is restricted from most operations that involve evaluating and executing strings once the document following types of JavaScript statements that evaluate and execute potentially insecure strings generates JavaScript errors:

• eval() function

• setTimeout() and setInterval()

• Function constructor

In addition, the following types of JavaScript statements fail without generating an unsafe JavaScript error:

• javascript: URLs

• Event callbacks assigned through onevent attributes in innerHTML and outerHTML statements

• Loading JavaScript files from outside the application installation directory

• document.write() and document.writeln()

• Synchronous XMLHttpRequests before the load event or during a load event handler

• Dynamically created script elements

Note: In some restricted cases, evaluation of strings is permitted. See “Code restrictions for content in different

sandboxes” on page 76for more information.

load event has fired and any load event handlers have exited. Attempting to use the

Adobe maintains a list of Ajax frameworks known to support the application security sandbox, at

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

The following sections describe how to rewrite scripts to avoid these unsafe JavaScript errors and silent failures for code running in the application sandbox.

Mapping application content to a different sandbox

Adobe AIR 1.0 and later

In most cases, you can rewrite or restructure an application to avoid security-related JavaScript errors. However, when rewriting or restructuring is not possible, you can load the application content into a different sandbox using the technique described in must access AIR APIs, you can create a sandbox bridge, as described in “Setting up a sandbox bridge interface” on page 36.

“Loading application content into a non-application sandbox” on page 35. If that content also

eval() function

Flash Player 9 and later, Adobe AIR 1.0 and later

In the application sandbox, the eval() function can only be used before the page load event or during a load event handler. After the page has loaded, calls to rewrite your code to avoid the use of

eval() will not execute code. However, in the following cases, you can

eval().

Last updated 9/28/2011

HTML DEVELOPER’S GUIDE FOR ADOBE AIR

Programming HTML and JavaScript in AIR

Assigning properties to an object

Adobe AIR 1.0 and later

Instead of parsing a string to build the property accessor:

eval("obj." + propName + " = " + val);

access properties with bracket notation:

obj[propName] = val;

Creating a function with variables available in context

Adobe AIR 1.0 and later

Replace statements such as the following:

function compile(var1, var2){ eval("var fn = function(){ this."+var1+"(var2) }"); return fn; }

with:

function compile(var1, var2){ var self = this; return function(){ self[var1](var2) }; }

Creating an object using the name of the class as a string parameter

Adobe AIR 1.0 and later

Consider a hypothetical JavaScript class defined with the following code:

var CustomClass = { Utils: { Parser: function(){ alert('constructor') } }, Data: {

} }; var constructorClassName = "CustomClass.Utils.Parser";

The simplest way to create a instance would be to use eval():

var myObj; eval('myObj=new ' + constructorClassName +'()')

However, you could avoid the call to eval() by parsing each component of the class name and building the new object using bracket notation:

Last updated 9/28/2011

+ 346 hidden pages