flash.desktop.NativeApplication

	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
		icon : InteractiveIcon [read-only] The application icon.	NativeApplication
		idleThreshold : int The number of seconds that must elapse without keyboard or mouse input before a presenceChange event is dispatched.	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
		prototype : Object [static] A reference to the prototype object of a class or function object.	Object
		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
		supportsDockIcon : Boolean [static] [read-only] Indicates whether AIR supports application dock 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
		supportsSystemTrayIcon : Boolean [static] [read-only] Specifies whether AIR supports system tray icons on the current operating system.	NativeApplication
		timeSinceLastUserInput : int [read-only] The time, in seconds, since the last mouse or keyboard input.	NativeApplication

	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 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 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 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
		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

Summary	Defined By
activate	Dispatched when this application becomes the active desktop application.	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
networkChange	Dispatched when either a new network connection becomes available or an existing network connection is lost.	NativeApplication
userIdle	Dispatched when the user has been idle for the period of time specified by the idleThreshold property.	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]

Runtime Versions:

AIR 1.0

The active application window.

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

applicationDescriptor

property

applicationDescriptor:XML [read-only]

Runtime Versions:

AIR 1.0

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

ActionScript 3.0 code in SWF files supports E4X syntax for for working with XML data. However in HTML-based AIR applications, you will want to convert the XML value of this property to a DOMParser object, using the parseFromString() method of a DOMParser object.

Example

The following example detects the copyright and version properties in the application descriptor file.

Note: To test this example:

Add the AIRAliases.js file to the project directory.
Create an application descriptor file for the project, and test the project using ADL.

<html>
    <head>
      <script src="AIRAliases.js" />
      <script>
        function getInfo() {
            var xmlString = air.NativeApplication.nativeApplication.applicationDescriptor;
            var appXml = new DOMParser();
            var xmlObject = appXml.parseFromString(xmlString, "text/xml");
            var root = xmlObject.getElementsByTagName('application')[0];
            var appCopyright = root.getElementsByTagName("copyright")[0];
            var appVersion = root.getElementsByTagName("version")[0];
            air.trace("copyright:", appCopyright.firstChild.data);
            air.trace("version:", appVersion.firstChild.data);
        }
      </script>
    </head>
    <body>
        <button onclick="getInfo()">Get Info</button>
    </body>
</html>

applicationID

property

applicationID:String [read-only]

Runtime Versions:

AIR 1.0

The application ID of this application.

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

autoExit

property

autoExit:Boolean [read-write]

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.

icon

property

icon:InteractiveIcon [read-only]

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.

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.

idleThreshold

property

idleThreshold:int [read-write]

Runtime Versions:

AIR 1.0

The number of seconds that must elapse without keyboard or mouse input before a presenceChange event is dispatched.

By default, the idle threshold is 300 seconds (5 minutes).

See also

userIdle
userPresent

property

menu:NativeMenu [read-write]

Runtime Versions:

AIR 1.0

The application menu.

Application menus are supported when NativeApplication.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. Assigning a NativeMenu object to this property when NativeApplication.nativeApplication.supportsMenu is false is allowed, but does nothing.

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.

See also

NativeMenu
NativeWindow.supportsMenu

nativeApplication

property

nativeApplication:NativeApplication [read-only]

Runtime Versions:

AIR 1.0

The singleton instance of the NativeApplication object.

Throws

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

openedWindows

property

openedWindows:Array [read-only]

Runtime Versions:

AIR 1.0

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

publisherID

property

publisherID:String [read-only]

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.

runtimePatchLevel

property

runtimePatchLevel:uint [read-only]

Runtime Versions:

AIR 1.0

The patch level of the runtime hosting this application.

runtimeVersion

property

runtimeVersion:String [read-only]

Runtime Versions:

AIR 1.0

The version number of the runtime hosting this application.

startAtLogin

property

startAtLogin:Boolean [read-write]

Runtime Versions:

AIR 1.0

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

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.

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).

supportsDockIcon

property

supportsDockIcon:Boolean [read-only]

Runtime Versions:

AIR 1.0

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

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

Mac OS X and various Linux^® user interfaces provide an application "dock" containing icons for applications that are running or are frequently used.

See also

icon

supportsMenu

property

supportsMenu:Boolean [read-only]

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.

See also

menu
NativeWindow.supportsMenu

supportsSystemTrayIcon

property

supportsSystemTrayIcon:Boolean [read-only]

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.

Note: On Windows, the system tray region of the task bar is officially called the Notification Area.

See also

icon

timeSinceLastUserInput

property

timeSinceLastUserInput:int [read-only]

Runtime Versions:

AIR 1.0

The time, in seconds, since the last mouse or keyboard input.

See also

userIdle
userPresent

Method Detail

activate

()

method

function activate(window:NativeWindow = null):void

Runtime Versions:

AIR 1.0

Activates this application.

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 a 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

  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.

JavaScript code in the AIR runtime uses this method to register event listeners for events defined by the AIR APIs. For other JavaScript events (such as the onload event of the DOM body object), you can use standard event handling techniques, as you would for content running in the browser.

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.

If you no longer need an event listener, remove it by calling removeEventListener(), or memory problems could result. Objects with registered event listeners are not automatically removed from memory because the garbage collector does not remove objects that still have references.

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.

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 . The function can have any name.

	`useCapture:Boolean` (default = `false`) — This parameter applies to display objects in the ActionScript 3.0 display list architecture, used by SWF content.

	`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

function clear():Boolean

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

function copy():Boolean

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

function cut():Boolean

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

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

function exit(errorCode:int = 0):void

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. Likewise, closing and close events are not dispatched before application windows are closed. If windows should be notified before your application exits, you can dispatch closing events for each open window. If a window close event is required, call the window's close() method before exiting.

Parameters

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

getDefaultApplication

()

method

function getDefaultApplication(extension:String):String

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.

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.

See also

applicationDescriptor

isSetAsDefaultApplication

()

method

function isSetAsDefaultApplication(extension:String):Boolean

Runtime Versions:

AIR 1.0

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

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.

See also

applicationDescriptor

paste

()

method

function paste():Boolean

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

function removeAsDefaultApplication(extension:String):void

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.

See also

applicationDescriptor

removeEventListener

()

method

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`) — This parameter applies to display objects in the ActionScript 3.0 display list architecture, used by SWF content.

selectAll

()

method

function selectAll():Boolean

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

function setAsDefaultApplication(extension:String):void

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.

See also

applicationDescriptor

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 Event.ACTIVATE constant defines the value of the type property of an activate event object.

Note: This event does not go through a "capture phase" and is dispatched directly to the target, whether the target is on the display list or not.

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.

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 does not go through a "capture phase" and is dispatched directly to the target, whether the target is on the display list or not.

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.

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.
`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.

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.

Note: There may be a short delay between a network change and the delivery of this event.

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.

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 for the period of time specified by the idleThreshold property.

The amount of time that the user has been idle can be determined from the timeSinceLastUserInput property.

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.

See also

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.

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.

See also

idleThreshold
timeSinceLastUserInput

window.runtime property	window.runtime.flash.desktop.NativeApplication

Inheritance	NativeApplication EventDispatcher Object

Adobe AIR Language Reference for HTML Developers	Index \| Frames No Frames
NativeApplication