flash.desktop

# NativeApplication - AS3

Package | flash.desktop
Class | public final class NativeApplication
Inheritance | NativeApplication EventDispatcher Object

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The NativeApplication class represents this AIR application.

The NativeApplication class provides application information, application-wide functions, and dispatches application-level events.

The NativeApplication object is a singleton object, created automatically at startup. Get the NativeApplication instance of an application with the static property `NativeApplication.nativeApplication`.

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | activeWindow : NativeWindow [read-only] The active application window. | NativeApplication
|  | applicationDescriptor : XML [read-only] The contents of the application descriptor file for this AIR application. | NativeApplication
|  | applicationID : String [read-only] The application ID of this application. | NativeApplication
|  | autoExit : Boolean Specifies whether the application should automatically terminate when all windows have been closed. | NativeApplication
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | executeInBackground : Boolean Specifies whether the application will run in background or not. | NativeApplication
|  | icon : InteractiveIcon [read-only] The application icon. | NativeApplication
|  | idleThreshold : int The number of seconds that must elapse without user input before a userIdle event is dispatched. | NativeApplication
|  | isCompiledAOT : Boolean [read-only] Specifies whether the application is compiled or interpreted for the desired platform. | NativeApplication
|  | menu : NativeMenu The application menu. | NativeApplication
|  | nativeApplication : NativeApplication [static] [read-only] The singleton instance of the NativeApplication object. | NativeApplication
|  | openedWindows : Array [read-only] An array containing all the open native windows of this application. | NativeApplication
|  | publisherID : String [read-only] The publisher ID of this application. | NativeApplication
|  | runtimePatchLevel : uint [read-only] The patch level of the runtime hosting this application. | NativeApplication
|  | runtimeVersion : String [read-only] The version number of the runtime hosting this application. | NativeApplication
|  | startAtLogin : Boolean Specifies whether this application is automatically launched whenever the current user logs in. | NativeApplication
|  | supportsDefaultApplication : Boolean [static] [read-only] Indicates whether setAsDefaultApplication(), removeAsDefaultApplication(), and isSetAsDefaultApplication() are supported on the current platform. | NativeApplication
|  | supportsDockIcon : Boolean [static] [read-only] Indicates whether AIR supports dock-style application icons on the current operating system. | NativeApplication
|  | supportsMenu : Boolean [static] [read-only] Specifies whether the current operating system supports a global application menu bar. | NativeApplication
|  | supportsStartAtLogin : Boolean [static] [read-only] Indicates whether startAtLogin is supported on the current platform. | NativeApplication
|  | supportsSystemTrayIcon : Boolean [static] [read-only] Specifies whether AIR supports system tray icons on the current operating system. | NativeApplication
|  | systemIdleMode : String Provides a way for applications to prevent the user interface from going into "idle" mode. | NativeApplication
|  | timeSinceLastUserInput : int [read-only] The time, in seconds, since the last user input. | NativeApplication

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | activate(window:NativeWindow = null):void Activates this application. | NativeApplication
|  | addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void [override] Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event. | NativeApplication
|  | clear():Boolean Invokes an internal delete command on the focused display object. | NativeApplication
|  | copy():Boolean Invokes an internal copy command on the focused display object. | NativeApplication
|  | cut():Boolean Invokes an internal cut command on the focused display object. | NativeApplication
|  | dispatchEvent(event:Event):Boolean [override] Dispatches an event into the event flow. | NativeApplication
|  | exit(errorCode:int = 0):void Terminates this application. | NativeApplication
|  | getDefaultApplication(extension:String):String Gets the default application for opening files with the specified extension. | NativeApplication
|  | hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event. | EventDispatcher
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | isSetAsDefaultApplication(extension:String):Boolean Specifies whether this application is currently the default application for opening files with the specified extension. | NativeApplication
|  | paste():Boolean Invokes an internal paste command on the focused display object. | NativeApplication
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | removeAsDefaultApplication(extension:String):void Removes this application as the default for opening files with the specified extension. | NativeApplication
|  | removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void [override] Removes a listener from the EventDispatcher object. | NativeApplication
|  | selectAll():Boolean Invokes an internal selectAll command on the focused display object. | NativeApplication
|  | setAsDefaultApplication(extension:String):void Sets this application as the default application for opening files with the specified extension. | NativeApplication
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object
|  | willTrigger(type:String):Boolean Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. | EventDispatcher

Events
Click for more information on events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | activate | Dispatched when this application becomes the active desktop application. | NativeApplication
|  | browserInvoke | Dispatched when an application is invoked by a SWF file running in the user's browser. | NativeApplication
|  | deactivate | Dispatched when the desktop focus is switched to a different application. | NativeApplication
|  | exiting | Dispatched when the application exit sequence is started. | NativeApplication
|  | invoke | Dispatched when an application is invoked. | NativeApplication
|  | keyDown | Dispatched when the user presses a key. | NativeApplication
|  | keyUp | Dispatched when the user releases a key. | NativeApplication
|  | networkChange | Dispatched when either a new network connection becomes available or an existing network connection is lost. | NativeApplication
|  | suspend | Dispatched when the application is about to be suspended by the operating system. | NativeApplication
|  | userIdle | Dispatched when the user has been idle. | NativeApplication
|  | userPresent | Dispatched when the operating system detects mouse or keyboard activity after an idle period. | NativeApplication

Property Detail

### activeWindow

property

`activeWindow:NativeWindow` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The active application window.

If the active desktop window does not belong to this application, or there is no active window, `activeWindow` is `null`.

This property is not supported on platforms that do not support the NativeWindow class.

Implementation
`public function get activeWindow():NativeWindow`

### applicationDescriptor

property

`applicationDescriptor:XML` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The contents of the application descriptor file for this AIR application.

Implementation
`public function get applicationDescriptor():XML`
Example ( How to use this example )
The following example reads the `copyright` and `version` elements from the application descriptor file. Note that you must use the default namespace defined in the application descriptor XML.
Copy

    var appDescriptor:XML = NativeApplication.nativeApplication.applicationDescriptor;
    var ns:Namespace = appDescriptor.namespace();
    var appCopyright:String = appDescriptor.ns::copyright;
    var appVersion:String = appDescriptor.ns::version;
    trace("appId:", appCopyright);
    trace("version:", appVersion);

### applicationID

property

`applicationID:String` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The application ID of this application.

The value of this ID is set in the application descriptor file.

Implementation
`public function get applicationID():String`

### autoExit

property

`autoExit:Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Specifies whether the application should automatically terminate when all windows have been closed.

When `autoExit` is `true`, which is the default, the application terminates when all windows are closed. Both `exiting` and `exit` events are dispatched. When `autoExit` is `false`, you must call `NativeApplication.nativeApplication.exit()` to terminate the application.

This property is not supported on platforms that do not support the NativeWindow class.

Implementation
`public function get autoExit():Boolean`
`public function set autoExit(value:Boolean):void`

### executeInBackground

property

`executeInBackground:Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 3.3

Specifies whether the application will run in background or not.

When `executeInBackground` is `false`, which is the default, the application remains in suspended state when it goes to background. When `executeInBackground` is `true`, the application may execute in background.

Note: With swf-version 21 and its earlier versions, AIR does not support background execution on iOS and Android when render mode direct is set. Due to this restriction, Stage3D based apps cannot execute background tasks like audio playback, location updates, network upload or download, etc. iOS does not allow OpenGLES or rendering of calls in the background. Applications which attempt to make OpenGL calls in the background are terminated by iOS. Android does not restrict applications from either making OpenGLES calls in the background or performing other background tasks like audio playback. With swf-version 22 and later, AIR mobile applications can execute in the background when renderMode direct is set. The AIR iOS runtime results in an ActionScript error (3768 - The Stage3D API may not be used during background execution) if OpenGLES calls are made in the background. However, there are no errors on Android because its native applications are allowed to make OpenGLES calls in the background. For optimal utilization of mobile resource, do not make rendering calls while an application is executing in the background.

This property is supported on AIR iOS and Android.

Implementation
`public function get executeInBackground():Boolean`
`public function set executeInBackground(value:Boolean):void`

### icon

property

`icon:InteractiveIcon` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The application icon.

Use `NativeApplication.supportsDockIcon` and `NativeApplication.supportsSystemTrayIcon` to determine the icon class. The type will be one of the subclasses of InteractiveIcon. On Mac® OS X, `NativeApplication.icon` is an object of type `DockIcon`. On Windows®, `NativeApplication.icon` is an object of type `SystemTrayIcon`. When an application icon is not supported, `NativeApplication.supportsDockIcon` and `NativeApplication.supportsSystemTrayIcon` are both `false` and the `icon` property is `null`.

The `icon` object is automatically created, but it is not initialized with image data. On some operating systems, such as Mac OS X, a default image is supplied. On others, such as Windows, the icon is not displayed unless image data is assigned to it. To assign an icon image, set the `icon.bitmaps` property with an array containing at least one BitmapData object. If more than one BitmapData object is included in the array, then the operating system chooses the image that is closest in size to the icon's display dimensions, scaling the image if necessary.

Implementation
`public function get icon():InteractiveIcon`

Related API Elements

supportsDockIcon
flash.desktop.DockIcon
supportsSystemTrayIcon
flash.desktop.SystemTrayIcon

### idleThreshold

property

`idleThreshold:int`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The number of seconds that must elapse without user input before a userIdle event is dispatched.

By default, the idle threshold is 300 seconds (5 minutes). The acceptable range of values is from 5 (5 seconds) through 86,400 (1 day), inclusive.

Implementation
`public function get idleThreshold():int`
`public function set idleThreshold(value:int):void`
Throws

| `ArgumentError` — If you attempt to set the property to an invalid value. The acceptable range of values is from 5 (5 seconds) through 86,400 (1 day), inclusive.

Related API Elements

userIdle
userPresent

### isCompiledAOT

property

`isCompiledAOT:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 25.0

Specifies whether the application is compiled or interpreted for the desired platform. This API returns (`true`) only for iOS for targets(ipa-app-store, ipa-test, ipa-debug, ipa-ad-hoc). For other AIR platforms, this API returns (`false`).

Implementation
`public function get isCompiledAOT():Boolean`

### menu

property

`menu:NativeMenu`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The application menu.

Application menus are supported when `NativeApplication.supportsMenu` is `true`. Not all operating systems support application menus. For example, application menus are supported on Mac OS X, but not on Windows or Linux. Assigning a NativeMenu object to this property when `NativeApplication.supportsMenu` is `false` is allowed, but does nothing. Be sure to use the `NativeApplication.supportsMenu` property to determine whether the operating system supports application menus. Using other means (such as `Capabilities.os`) to determine support can lead to programming errors (if some possible target operating systems are not considered).

AIR profile support: This feature is not supported on mobile devices or AIR for TV devices. See AIR Profile Support for more information regarding API support across multiple profiles.

Note: On Mac OS X, the `menu` property references the operating-system-supplied default application menu. You can modify the existing menu structure by adding and removing items and submenus, and by adding event listeners. You can also replace the default menus entirely by assigning a new NativeMenu object to this `menu` property.

Implementation
`public function get menu():NativeMenu`
`public function set menu(value:NativeMenu):void`

Related API Elements

flash.display.NativeMenu
flash.display.NativeWindow.supportsMenu

### nativeApplication

property

`nativeApplication:NativeApplication` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The singleton instance of the NativeApplication object.

Implementation
`public static function get nativeApplication():NativeApplication`
Throws

| `Error` — If accessed by content outside the application security sandbox.

### openedWindows

property

`openedWindows:Array` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

An array containing all the open native windows of this application.

This property is not supported on platforms that do not support the NativeWindow class.

Implementation
`public function get openedWindows():Array`

### publisherID

property

`publisherID:String` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The publisher ID of this application.

The value of this ID is set in the application's publisherid file, which is generated at installation from the certificate chain used to sign the application.

Implementation
`public function get publisherID():String`

### runtimePatchLevel

property

`runtimePatchLevel:uint` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The patch level of the runtime hosting this application.

Implementation
`public function get runtimePatchLevel():uint`

### runtimeVersion

property

`runtimeVersion:String` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The version number of the runtime hosting this application.

Implementation
`public function get runtimeVersion():String`

### startAtLogin

property

`startAtLogin:Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Specifies whether this application is automatically launched whenever the current user logs in.

AIR profile support: This feature is supported on all desktop operating systems, but is not supported on mobile devices or AIR for TV devices. You can test for support at run time using the `NativeApplication.supportsStartAtLogin` property. See AIR Profile Support for more information regarding API support across multiple profiles.

The `startAtLogin` property reflects the status of the operating-system-defined mechanism for designating that an application should start automatically when a user logs in. The user can change the status manually by using the operating system user interface. This property reflects the current status, whether the status was last changed by the AIR application or by the operating system.

Implementation
`public function get startAtLogin():Boolean`
`public function set startAtLogin(value:Boolean):void`
Throws

| `IllegalOperationError` — On Windows when another application with the same name (but with a different path to the executable) is already set to launch when this user logs in.
| `IllegalOperationError` — If this application is not installed, which may be the case when launched by the AIR Debug Launcher (ADL).

Related API Elements

supportsStartAtLogin

### supportsDefaultApplication

property

`supportsDefaultApplication:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2

Indicates whether `setAsDefaultApplication()`, `removeAsDefaultApplication()`, and `isSetAsDefaultApplication()` are supported on the current platform.

If `true`, then the above methods will work as documented. If `false`, then `setAsDefaultApplication()` and `removeDefaultApplication()` do nothing and `isSetAsDefaultApplication()` returns `false`.

Implementation
`public static function get supportsDefaultApplication():Boolean`

Related API Elements

setAsDefaultApplication()
removeAsDefaultApplication()
isSetAsDefaultApplication()

### supportsDockIcon

property

`supportsDockIcon:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Indicates whether AIR supports dock-style application icons on the current operating system.

If `true`, the `NativeApplication.icon` property is of type `DockIcon`.

The Mac OS X user interface provides an application "dock" containing icons for applications that are running or are frequently used.

Be sure to use the `NativeApplication.supportsDockIcon` property to determine whether the operating system supports application dock icons. Using other means (such as `Capabilities.os`) to determine support can lead to programming errors (if some possible target operating systems are not considered).

Implementation
`public static function get supportsDockIcon():Boolean`

Related API Elements

icon
flash.desktop.DockIcon

### supportsMenu

property

`supportsMenu:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Specifies whether the current operating system supports a global application menu bar.

When `true`, the `NativeApplication.menu` property can be used to define (or access) a native application menu.

Be sure to use the `NativeApplication.supportsMenu` property to determine whether the operating system supports the application menu bar. Using other means (such as `Capabilities.os`) to determine support can lead to programming errors (if some possible target operating systems are not considered).

Implementation
`public static function get supportsMenu():Boolean`

Related API Elements

menu
flash.display.NativeWindow.supportsMenu

### supportsStartAtLogin

property

`supportsStartAtLogin:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2

Indicates whether startAtLogin is supported on the current platform.

If `true`, then startAtLogin works as documented. If `false`, then startAtLogin has no effect.

Implementation
`public static function get supportsStartAtLogin():Boolean`

Related API Elements

startAtLogin

### supportsSystemTrayIcon

property

`supportsSystemTrayIcon:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Specifies whether AIR supports system tray icons on the current operating system.

If `true`, the `NativeApplication.icon` property is of type `SystemTrayIcon`.

The Windows user interface provides the "system tray" region of the task bar, officially called the Notification Area, in which application icons can be displayed. No default icon is shown. You must set the `bitmaps` array of the icon object to display an icon.

Be sure to use the `NativeApplication.supportsSystemTrayIcon` property to determine whether the operating system supports system tray icons. Using other means (such as `Capabilities.os`) to determine support can lead to programming errors (if some possible target operating systems are not considered).

Implementation
`public static function get supportsSystemTrayIcon():Boolean`

Related API Elements

icon
flash.desktop.SystemTrayIcon

### systemIdleMode

property

`systemIdleMode:String`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2

Provides a way for applications to prevent the user interface from going into "idle" mode.

A value from the SystemIdleMode class to influence the host system's idle mode behavior. This property is only effective for the application with input focus and can only be accessed from content running in the application sandbox.

AIR profile support: This feature is supported on mobile devices, but it is not supported on desktop operating systems or AIR for TV devices. See AIR Profile Support for more information regarding API support across multiple profiles.

Implementation
`public function get systemIdleMode():String`
`public function set systemIdleMode(value:String):void`

Related API Elements

flash.desktop.SystemIdleMode

### timeSinceLastUserInput

property

`timeSinceLastUserInput:int` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

The time, in seconds, since the last user input.

Implementation
`public function get timeSinceLastUserInput():int`

Related API Elements

userIdle
userPresent
Method Detail

### activate

()
method

`public function activate(window:NativeWindow = null):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Activates this application.

This method is not supported on platforms that do not support the NativeWindow class.

Under some circumstances determined by the operating system, this method does not activate an application. Most operating systems restrict the ability of an application to activate itself to prevent it from accidentally or maliciously making it impossible for a user to use other applications.

If the operating system allows activation, then the specified window is activated and brought to the desktop foreground; that is, in front of the windows of other applications. (If the `window` parameter is `null`, then any visible window of this application is activated.)

The `activate()` method has no effect if the application has no visible windows.

The activate operation is synchronous.

Parameters

| `window:NativeWindow` (default = `null`)`` — The NativeWindow object of the window to activate along with the application.

Events

| `activate:`Event`` — Dispatched if the activation state changes.

### addEventListener

()
method

`override public function addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void`

Runtime Versions: | AIR 1.0

Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event. You can register event listeners on all nodes in the display list for a specific type of event, phase, and priority.

After you successfully register an event listener, you cannot change its priority through additional calls to `addEventListener()`. To change a listener's priority, you must first call `removeListener()`. Then you can register the listener again with the new priority level.

Keep in mind that after the listener is registered, subsequent calls to `addEventListener()` with a different `type` or `useCapture` value result in the creation of a separate listener registration. For example, if you first register a listener with `useCapture` set to `true`, it listens only during the capture phase. If you call `addEventListener()` again using the same listener object, but with `useCapture` set to `false`, you have two separate listeners: one that listens during the capture phase and another that listens during the target and bubbling phases.

You cannot register an event listener for only the target phase or the bubbling phase. Those phases are coupled during registration because bubbling applies only to the ancestors of the target node.

If you no longer need an event listener, remove it by calling `removeEventListener()`, or memory problems could result. Event listeners are not automatically removed from memory because the garbage collector does not remove the listener as long as the dispatching object exists (unless the `useWeakReference` parameter is set to `true`).

Copying an EventDispatcher instance does not copy the event listeners attached to it. (If your newly created node needs an event listener, you must attach the listener after creating the node.) However, if you move an EventDispatcher instance, the event listeners attached to it move along with it.

If the event listener is being registered on a node while an event is being processed on this node, the event listener is not triggered during the current phase but can be triggered during a later phase in the event flow, such as the bubbling phase.

If an event listener is removed from a node while an event is being processed on the node, it is still triggered by the current actions. After it is removed, the event listener is never invoked again (unless registered again for future processing).

Parameters

| `type:String` — The type of event.
| `listener:Function` — The listener function that processes the event. This function must accept an Event object as its only parameter and must return nothing, as this example shows: Copy
    function(evt:Event):void
The function can have any name.
| `useCapture:Boolean` (default = `false`)`` — Determines whether the listener works in the capture phase or the target and bubbling phases. If `useCapture` is set to `true`, the listener processes the event only during the capture phase and not in the target or bubbling phase. If `useCapture` is `false`, the listener processes the event only during the target or bubbling phase. To listen for the event in all three phases, call `addEventListener` twice, once with `useCapture` set to `true`, then again with `useCapture` set to `false`.
| `priority:int` (default = `0`)`` — The priority level of the event listener. The priority is designated by a signed 32-bit integer. The higher the number, the higher the priority. All listeners with priority n are processed before listeners of priority n-1. If two or more listeners share the same priority, they are processed in the order in which they were added. The default priority is 0.
| `useWeakReference:Boolean` (default = `false`)`` — Determines whether the reference to the listener is strong or weak. A strong reference (the default) prevents your listener from being garbage-collected. A weak reference does not. Class-level member functions are not subject to garbage collection, so you can set `useWeakReference` to `true` for class-level member functions without subjecting them to garbage collection. If you set `useWeakReference` to `true` for a listener that is a nested inner function, the function will be garbage-collected and no longer persistent. If you create references to the inner function (save it in another variable) then it is not garbage-collected and stays persistent.

### clear

()
method

`public function clear():Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Invokes an internal delete command on the focused display object.

This function call is ignored if the focused object does not implement the command. Only display objects descending from the TextField or HTMLLoader classes currently implement this command.

Note: The `clear()` command deletes selected text. If nothing is selected, it does not clear all text.

Returns

| `Boolean` — `true`.

### copy

()
method

`public function copy():Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Invokes an internal copy command on the focused display object.

This function call is ignored if the component does not implement the command. Only display objects descending from the TextField or HTMLLoader classes currently implement this command.

Returns

| `Boolean`

### cut

()
method

`public function cut():Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Invokes an internal cut command on the focused display object.

This function call is ignored if the component does not implement the command. Only display objects descending from the TextField or HTMLLoader classes currently implement this commands.

Returns

| `Boolean` — `true`.

### dispatchEvent

()
method

`override public function dispatchEvent(event:Event):Boolean`

Runtime Versions: | AIR 1.0

Dispatches an event into the event flow. The event target is the EventDispatcher object upon which the `dispatchEvent()` method is called.

Parameters

| `event:Event` — The Event object that is dispatched into the event flow. If the event is being redispatched, a clone of the event is created automatically. After an event is dispatched, its `target` property cannot be changed, so you must create a new copy of the event for redispatching to work.

Returns

| `Boolean` — A value of `true` if the event was successfully dispatched. A value of `false` indicates failure or that `preventDefault()` was called on the event.

### exit

()
method

`public function exit(errorCode:int = 0):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Terminates this application.

The call to the `exit()` method will return; the shutdown sequence does not begin until the currently executing code (such as a current event handler) has completed. Pending asynchronous operations are canceled and may or may not complete.

Note that an `exiting` event is not dispatched. If an `exiting` event is required by application logic, call `NativeApplication.nativeApplication.dispatchEvent()`, passing in an Event object of type `exiting`. For any open windows, NativeWindow objects do dispatch `closing` and `close` events. Calling the `preventDefault()` method of `closing` event object prevents the application from exiting.

Note: This method is not supported on the iOS operating system.

Parameters

| `errorCode:int` (default = `0`)`` — The exit code reported to the operating system when this application exits.

### getDefaultApplication

()
method

`public function getDefaultApplication(extension:String):String`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Gets the default application for opening files with the specified extension.

Note: This method can only be used with file types declared in the `fileTypes` statement of the application descriptor.

This method is not applicable for AIR for TV devices. If you call it with a file type declared in the application descriptor, it returns `null`.

Parameters

| `extension:String` — A String containing the extension of the file type of interest (without the ".").

Returns

| `String` — The path of the default application.

Throws

| `Error` — If the `extension` parameter does not contain one of the file extensions declared in the application descriptor.

Related API Elements

applicationDescriptor

### isSetAsDefaultApplication

()
method

`public function isSetAsDefaultApplication(extension:String):Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Specifies whether this application is currently the default application for opening files with the specified extension.

AIR profile support: This feature is supported on all desktop operating systems, but is not supported on mobile devices or AIR for TV devices. You can test for support at run time using the `NativeApplication.supportsDefaultApplication` property. See AIR Profile Support for more information regarding API support across multiple profiles.

Parameters

| `extension:String` — A String containing the extension of the file type of interest (without the ".").

Returns

| `Boolean` — `true` if this application is the default.

Throws

| `Error` — If the `extension` parameter does not contain one of the file extensions declared in the application descriptor.

Related API Elements

applicationDescriptor
supportsDefaultApplication

### paste

()
method

`public function paste():Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Invokes an internal paste command on the focused display object.

This function call is ignored if the component does not implement the command. Only display objects descending from the TextField or HTMLLoader classes currently implement this command.

Returns

| `Boolean` — `true`.

### removeAsDefaultApplication

()
method

`public function removeAsDefaultApplication(extension:String):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Removes this application as the default for opening files with the specified extension.

Note: This method can only be used with file types listed in the `fileTypes` statement in the application descriptor.

Parameters

| `extension:String` — A String containing the extension of the file type of interest (without the ".").

Throws

| `Error` — If the `extension` parameter does not contain one of the file extensions declared in the application descriptor.

Related API Elements

applicationDescriptor
supportsDefaultApplication

### removeEventListener

()
method

`override public function removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void`

Runtime Versions: | AIR 1.0

Removes a listener from the EventDispatcher object. If there is no matching listener registered with the EventDispatcher object, a call to this method has no effect.

Parameters

| `type:String` — The type of event.
| `listener:Function` — The listener object to remove.
| `useCapture:Boolean` (default = `false`)`` — Specifies whether the listener was registered for the capture phase or the target and bubbling phases. If the listener was registered for both the capture phase and the target and bubbling phases, two calls to `removeEventListener()` are required to remove both, one call with `useCapture()` set to `true`, and another call with `useCapture()` set to `false`.

### selectAll

()
method

`public function selectAll():Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Invokes an internal selectAll command on the focused display object.

This function call is ignored if the component does not implement the command. Only display objects descending from the TextField or HTMLLoader classes currently implement this command.

Returns

| `Boolean` — `true`.

### setAsDefaultApplication

()
method

`public function setAsDefaultApplication(extension:String):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Sets this application as the default application for opening files with the specified extension.

Note: This method can only be used with file types declared in the `fileTypes` statement in the application descriptor.

Parameters

| `extension:String` — A String containing the extension of the file type of interest (without the ".").

Throws

| `Error` — If the `extension` parameter does not contain one of the file extensions declared in the application descriptor.

Related API Elements

applicationDescriptor
supportsDefaultApplication
Event Detail

### activate

Event

Event Object Type: `flash.events.Event`
property Event.type = `flash.events.Event.ACTIVATE`

Runtime Versions: | AIR 1.0

Dispatched when this application becomes the active desktop application.

The `ACTIVATE` constant defines the value of the `type` property of an `activate` event object.

Note: This event has neither a "capture phase" nor a "bubble phase", which means that event listeners must be added directly to any potential targets, whether the target is on the display list or not.

AIR for TV devices never automatically dispatch this event. You can, however, dispatch it manually.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | Any DisplayObject instance with a listener registered for the `activate` event.

### browserInvoke

Event

Event Object Type: `flash.events.BrowserInvokeEvent`
property BrowserInvokeEvent.type = `flash.events.BrowserInvokeEvent.Browser_INVOKE`

Runtime Versions: | AIR 1.0

Dispatched when an application is invoked by a SWF file running in the user's browser.

Browser invocation is permitted only if an application specifies the following in the application descriptor file:

Copy

    <allowBrowserInvocation>true</allowBrowserInvocation>

### deactivate

Event

Event Object Type: `flash.events.Event`
property Event.type = `flash.events.Event.DEACTIVATE`

Runtime Versions: | AIR 1.0

Dispatched when the desktop focus is switched to a different application.

The `Event.DEACTIVATE` constant defines the value of the `type` property of a `deactivate` event object.

Note: This event has neither a "capture phase" nor a "bubble phase", which means that event listeners must be added directly to any potential targets, whether the target is on the display list or not.

AIR for TV devices never automatically dispatch this event. You can, however, dispatch it manually.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | Any DisplayObject instance with a listener registered for the `deactivate` event.

### exiting

Event

Event Object Type: `flash.events.Event`
property Event.type = `flash.events.Event.EXITING`

Runtime Versions: | AIR 1.0

Dispatched when the application exit sequence is started.

The `exiting` event is dispatched when application exit is initiated by the operating system; for example, when a user issues the `Cmd-Q` key sequence on Mac OS X, or when the `autoExit` property of the NativeApplication object is `true` and the last application window is closed. Canceling this event prevents the application from exiting.

AIR for TV devices never dispatch the `exiting` event.

Note: Calling the NativeApplication `exit()` method does not cause an `exiting` event to be dispatched. To warn components of an impending exit, dispatch the `exiting` event before calling `exit().`

The `Event.EXITING` constant defines the value of the `type` property of an `exiting` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `true`; canceling this event object stops the exit operation.
`currentTarget` | The NativeApplication object.
`target` | The NativeApplication object.

### invoke

Event

Event Object Type: `flash.events.InvokeEvent`
property InvokeEvent.type = `flash.events.InvokeEvent.INVOKE`

Runtime Versions: | AIR 1.0

Dispatched when an application is invoked.

When an application is invoked a second time, another instance of the application is not started. Instead, the first instance receives an additional invoke event. It is the responsibility of the application to handle subsequent `invoke` events appropriately.

Note: All `invoke` events are queued. When a listener for this event is registered, it receives all events in the queue as well as any new events. Queued events may be delivered before or after any new `invoke` events.

The `InvokeEvent.INVOKE` constant defines the value of the `type` property of an InvokeEvent object.

The InvokeEvent object has the following properties:

Properties | Values
--- | ---
`arguments` | The array of string arguments passed during this invocation.
`currentDirectory` | a File object representing the directory that should be used to resolve any relative paths in the arguments array.
`reason` | a code indicating whether the invoke event was dispatched because the application started automatically at login (`InvokeEventReason.LOGIN`), started as a response to a remote notification (`InvokeEventReason.NOTIFICATION` - iOS only), because the application was invoked by another application (`InvokeEventReason.OPEN_URL`), or for another reason (`InvokeEventReason.STANDARD`). Available as of AIR version 1.5.1.
`bubbles` | `false`.
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | Indicates the object that is actively processing this InvokeEvent object with an event listener.
`target` | Always the NativeApplication object.

### keyDown

Event

Event Object Type: `flash.events.KeyboardEvent`
property KeyboardEvent.type = `flash.events.KeyboardEvent.KEY_DOWN`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Dispatched when the user presses a key. The NativeApplication instance provides this event to support keyboard accelerators. This keyboard event is dispatched first to the NativeApplication. Canceling this event also cancels NativeWindow menu accelerators. This event occurs before the `keyUp` event.

The `KeyboardEvent.KEY_DOWN` constant defines the value of the `type` property of a `keyDown` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `true`
`cancelable` | `true` in AIR, `false` in Flash Player; in AIR, canceling this event prevents the character from being entered into a text field.
`charCode` | The character code value of the key pressed or released.
`commandKey` | `true` on Mac if the Command key is active. Otherwise, `false`
`controlKey` | `true` on Windows and Linux if the Ctrl key is active. `true` on Mac if either the Control key is active. Otherwise, `false`
`ctrlKey` | `true` on Windows and Linux if the Ctrl key is active. `true` on Mac if either the Ctrl key or the Command key is active. Otherwise, `false`.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`keyCode` | The key code value of the key pressed or released.
`keyLocation` | The location of the key on the keyboard.
`shiftKey` | `true` if the Shift key is active; `false` if it is inactive.
`target` | The InteractiveObject instance with focus. The `target` is not always the object in the display list that registered the event listener. Use the `currentTarget` property to access the object in the display list that is currently processing the event.

Related API Elements

flash.display.InteractiveObject.keyDown

### keyUp

Event

Event Object Type: `flash.events.KeyboardEvent`
property KeyboardEvent.type = `flash.events.KeyboardEvent.KEY_UP`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0

Dispatched when the user releases a key. The NativeApplication instance provides this event to support keyboard accelerators. This keyboard event is dispatched first to the NativeApplication. Canceling this event has no effects on other objects (such as NativeWindow menu accelerators). This event occurs after a `keyDown` event.

The `KeyboardEvent.KEY_UP` constant defines the value of the `type` property of a `keyUp` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `true`
`cancelable` | `false`; there is no default behavior to cancel.
`charCode` | Contains the character code value of the key pressed or released.
`commandKey` | `true` on Mac if the Command key is active. Otherwise, `false`
`controlKey` | `true` on Windows and Linux if the Ctrl key is active. `true` on Mac if either the Control key is active. Otherwise, `false`
`ctrlKey` | `true` on Windows if the Ctrl key is active. `true` on Mac if either the Ctrl key or the Command key is active. Otherwise, `false`.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`keyCode` | The key code value of the key pressed or released.
`keyLocation` | The location of the key on the keyboard.
`shiftKey` | `true` if the Shift key is active; `false` if it is inactive.
`target` | The InteractiveObject instance with focus. The `target` is not always the object in the display list that registered the event listener. Use the `currentTarget` property to access the object in the display list that is currently processing the event.

Related API Elements

flash.display.InteractiveObject.keyUp

### networkChange

Event

Event Object Type: `flash.events.Event`
property Event.type = `flash.events.Event.NETWORK_CHANGE`

Runtime Versions: | AIR 1.0

Dispatched when either a new network connection becomes available or an existing network connection is lost.

A `networkChange` event does not necessarily mean that the host computer has gone online or offline; it may just be transitioning from one type of connection to another. Applications can use this event to help optimize the task of monitoring remote resource availability. The dispatch of a `networkChange` event is often a good time to verify the availability of any remote resources.

Notes:

- There may be a short delay between a network change and the delivery of this event.
- On Android, the NativeApplication object may dispatch more than one networkChange event for each change in a network connection.

The `Event.NETWORK_CHANGE` constant defines the value of the `type` property of a `networkChange` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The NativeApplication object.

### suspend

Event

Event Object Type: `flash.events.Event`
property Event.type = `flash.events.Event.SUSPEND`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 3.3

Dispatched when the application is about to be suspended by the operating system.

The `Event.SUSPEND` constant defines the value of the `type` property of an `suspend` event object. This event is dispatched only on AIR iOS.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The NativeApplication object.
`target` | The NativeApplication object.

### userIdle

Event

Event Object Type: `flash.events.Event`
property Event.type = `flash.events.Event.USER_IDLE`

Runtime Versions: | AIR 1.0

Dispatched when the user has been idle.

Specify the period of time for which a user must be idle before this event is dispatched using the `idleThreshold` property. The amount of time that the user has been idle can be determined from the `timeSinceLastUserInput` property.

Note: This event is not dispatched on mobile devices or AIR for TV devices.

The `Event.USER_IDLE` constant defines the value of the `type` property of a `userIdle` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`target` | The NativeApplication object.

Related API Elements

idleThreshold
timeSinceLastUserInput

### userPresent

Event

Event Object Type: `flash.events.Event`
property Event.type = `flash.events.Event.USER_PRESENT`

Runtime Versions: | AIR 1.0

Dispatched when the operating system detects mouse or keyboard activity after an idle period.

Note: This event is not dispatched on mobile devices or AIR for TV devices.

The period of time that is considered idle is configurable with the `idleThreshold` property. The amount of time that the user has been idle can be determined from the `timeSinceLastUserInput` property.

The `Event.USER_PRESENT` constant defines the value of the `type` property of a `userPresent` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`target` | The NativeApplication object.

Related API Elements

idleThreshold
timeSinceLastUserInput

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00