flash.desktopNativeProcess The NativeProcess class provides command line integration and general launching capabilities.flash.events:EventDispatcher The NativeProcess class provides command line integration and general launching capabilities. The NativeProcess class lets an AIR application execute native processes on the host operating system. The AIR applcation can monitor the standard input (stdin) and standard output (stdout) stream of the process as well as the process's standard error (stderr) stream.

The NativeProcess class and its capabilities are only available to AIR applications installed with a native installer (extended desktop profile applications). When debugging, you can pass the -profile extendedDesktop argument to ADL to enable the NativeProcess functionality. At runtime, you can check the NativeProcess.isSupported property to to determine whether native process communication is supported.

AIR profile support: This feature is supported on applications that are deployed to desktop operating systems via native installers. The feature is not supported on mobile devices or on AIR for TV devices. You can test for support at run time using the NativeProcess.isSupported property. See AIR Profile Support for more information regarding API support across multiple profiles.

AIR applications installed with a native installer (extended desktop profile applications) can also use the File.openWithDefaultApplication to open an application. However, the NativeProcess class provides direct access to the standard input, standard output, and standard error pipes.

Note: AIR for TV applications using the extendedTV profile can use ActionScript native extensions to execute native processes.

The following example checks to see if native process communication is supported on the machine. If it is, the application sets up event listeners for the native process and launches the test.py file in the main application directory). : package { import flash.display.Sprite; import flash.desktop.NativeProcess; import flash.desktop.NativeProcessStartupInfo; import flash.events.Event; import flash.events.ProgressEvent; import flash.events.IOErrorEvent; import flash.events.NativeProcessExitEvent; import flash.filesystem.File; public class NativeProcessExample extends Sprite { public var process:NativeProcess; public function NativeProcessExample() { if(NativeProcess.isSupported) { setupAndLaunch(); } else { trace("NativeProcess not supported."); } } public function setupAndLaunch():void { var nativeProcessStartupInfo:NativeProcessStartupInfo = new NativeProcessStartupInfo(); var file:File = File.applicationDirectory.resolvePath("test.py"); nativeProcessStartupInfo.executable = file; var processArgs:Vector.<String> = new Vector.<String>(); processArgs[0] = "foo"; nativeProcessStartupInfo.arguments = processArgs; process = new NativeProcess(); process.start(nativeProcessStartupInfo); process.addEventListener(ProgressEvent.STANDARD_OUTPUT_DATA, onOutputData); process.addEventListener(ProgressEvent.STANDARD_ERROR_DATA, onErrorData); process.addEventListener(NativeProcessExitEvent.EXIT, onExit); process.addEventListener(IOErrorEvent.STANDARD_OUTPUT_IO_ERROR, onIOError); process.addEventListener(IOErrorEvent.STANDARD_ERROR_IO_ERROR, onIOError); } public function onOutputData(event:ProgressEvent):void { trace("Got: ", process.standardOutput.readUTFBytes(process.standardOutput.bytesAvailable)); } public function onErrorData(event:ProgressEvent):void { trace("ERROR -", process.standardError.readUTFBytes(process.standardError.bytesAvailable)); } public function onExit(event:NativeProcessExitEvent):void { trace("Process exited with ", event.exitCode); } public function onIOError(event:IOErrorEvent):void { trace(event.toString()); } } } Add the following Python script to a file named test.py in your application directory (and the ensure that Python is installed):

 #!/usr/bin/python
 # ------------------------------------------------------------------------------
 # Sample Python script
 # ------------------------------------------------------------------------------
 
 import sys
 
 for word in sys.argv: #echo the command line arguments
     print word
 
 print "HI FROM PYTHON"
 print "Enter user name" 
 line = sys.stdin.readline()
 
 sys.stdout.write("hello," + line)

exit Signals the native process has exited.flash.events.NativeProcessExitEventflash.events.NativeProcessExitEvent Signals the native process has exited. The exitCode property contains the value the process returns to the host operating system on exit. If the AIR application terminates the process by calling the exit() method of the NativeProcess object, the exitCode property is set to NaN. standardInputIoError Signals that writing to the standard input (stdin) stream has failed.flash.events.IOErrorEventflash.events.IOErrorEvent Signals that writing to the standard input (stdin) stream has failed. The NativeProcess object dispatches this event when the closeInput() method fails or when the runtime cannot write data to the native process's standard input pipe. standardOutputIoError Signals that reading from the stdout stream has failed.flash.events.IOErrorEventflash.events.IOErrorEvent Signals that reading from the stdout stream has failed. The NativeProcess object can dispatch this event when the runtime cannot read data from the native process's standard output pipe. standardErrorIoError Signals that reading from the standard error (stderror) stream has failed.flash.events.IOErrorEventflash.events.IOErrorEvent Signals that reading from the standard error (stderror) stream has failed. The NativeProcess object can dispatch this event when the runtime cannot read data from the native process's standard error pipe. standardInputClose Signals that the NativeProcess object has closed its input stream by calling the closeInput() method.flash.events.Eventflash.events.Event Signals that the NativeProcess object has closed its input stream by calling the closeInput() method. The NativeProcess object does not dispatch this event when the actual native process itself closes the input stream. standardInputProgress Signals that the NativeProcess has written data to the input stream for the child process.flash.events.ProgressEventflash.events.ProgressEvent Signals that the NativeProcess has written data to the input stream for the child process. The NativeProcess object dispatches this event when data is written to the stream. This event does not indicate whether or not the child process has read any of the data. standardErrorClose Signals that the NativeProcess has closed its error stream.flash.events.Eventflash.events.Event Signals that the NativeProcess has closed its error stream. standardErrorData Signals that the native process has data available to read on the standard error (stderror) stream.flash.events.ProgressEventflash.events.ProgressEvent Signals that the native process has data available to read on the standard error (stderror) stream. The NativeProcess object dispatches this event when the child process flushes its standard error stream or when the internal buffer used to communicate between the processes is full. Do not write code that depend on the size of this internal buffer; it varies between versions and operating systems. standardOutputClose Signals that the NativeProcess has closed its output stream.flash.events.Eventflash.events.Event Signals that the NativeProcess has closed its output stream. standardOutputData Signals that the native process has data available to read on the output stream.flash.events.ProgressEventflash.events.ProgressEvent Signals that the native process has data available to read on the output stream. The NativeProcess object dispatches this event when the child process flushes its stdout stream or when the internal buffer used to communicate between the processes is full. Do not write code that depend on the size of this internal buffer; it varies between versions and operating systems. NativeProcess Constructs an uninitialized NativeProcess object. Constructs an uninitialized NativeProcess object. Call the start() method to start the process. closeInput Closes the input stream on this process. Closes the input stream on this process. Some command line applications wait until the input stream is closed to start some operations. Once the stream is closed it cannot be re-opened until the process exits and is started again. ioErrorStandardInputflash.events:IOErrorEventThere is a problem closing the input stream to the process There is a problem closing the input stream to the process standardInputCloseflash.events:EventThe input stream has been closed. The input stream has been closed.exit Attempts to exit the native process.forceBooleanfalseWhether the application should attempt to forcibly exit the native process, if necessary.

If the force parameter is set to false, this method attempts to gracefully exit the native process. This method "asks" the native process to exit. This request may be ignored by the native process, and as a result this method is not guaranteed to actually cause the native process to exit. The NativeProcess object only dispatches a NativeProcessExitEvent event if the native process exits.

If the force parameter is set to true, this method attempts to forcibly exit the native process. Calling this method with the force parameter is set to true should be a last resort. Calling this method with the force parameter is set to true may have adverse affects on the state of system resources associated with the native process. For example, opened files may be left in an inconsistent state. The runtime will make its best effort to try to force the native process to exit. However, it is not guaranteed that the native process will exit. The NativeProcess object only dispatches a NativeProcessExitEvent event if the native process exits.

If the NativeProcess does successfully exit, it dispatches a NativeProcessExitEvent event.

Attempts to exit the native process. start Starts the native process identified by the start up info specified.if the NativeProcess is currently running. IllegalOperationErrorflash.errors:IllegalOperationErrorif the nativePath property of the NativeProcessStartupInfo does not exist. ArgumentErrorArgumentErrorif the NativeProcess did not start successfully. ErrorErrorinfoflash.desktop:NativeProcessStartupInfoNativeProcessStartupInfo Defines information about how to start the native process. Starts the native process identified by the start up info specified. Once the process starts, all of the input and output streams will be opened. This method returns immediately after the request to start the specified process has been made to the operating system. The NativeProcess object throws an IllegalOperationError exception if the process is currently running. The process is running if the running property of the NativeProcess object returns true. If the operating system is unable to start the process, an Error is thrown.

A NativeProcess instance corresponds to a single process on the underlying operating system. If you want to execute more than one instance of the same operating system process concurrently, you can create one NativeProcess instance per child process.

You can call this method whenever the running property of the NativeProcess object returns false. This means that the NativeProcess object can be reused. In other words you can construct a NativeProcess instance, call the start() method, wait for the exit event, and then call the start() method again. You may use a different NativeProcessStartupInfo object as the info parameter value in the subsequent call to the start() method.

The NativeProcess class and its capabilities are only available to AIR applications installed with a native installer. When debugging, you can pass the -profile extendedDesktop argument to ADL to enable the NativeProcess functionality. Check the NativeProcess.isSupported property to to determine whether native process communication is supported.

Important security considerations:

The native process API can run any executable on the user's system. Take extreme care when constructing and executing commands. If any part of a command to be executed originates from an external source, carefully validate that the command is safe to execute. Likewise, your AIR application should validate data passed to a running process.

However, validating input can be difficult. To avoid such difficulties, it is best to write a native application (such as an EXE file on Windows) that has specific APIs. These APIs should process only those commands specifically required by the AIR application. For example, the native application may accept only a limited set of instructions via the standard input stream.

AIR on Windows does not allow you to run .bat files directly. Windows .bat files are executed by the command interpreter application (cmd.exe). When you invoke a .bat file, this command application can interpret arguments passed to the command as additional applications to launch. A malicious injection of extra characters in the argument string could cause cmd.exe to execute a harmful or insecure application. For example, without proper data validation, your AIR application may call myBat.bat myArguments c:/evil.exe. The command application would launch the evil.exe application in addition to running your batch file.

If you call the start() method with a .bat file, the NativeProcess object throws an exception. The message property of the Error object contains the string "Error #3219: The NativeProcess could not be started."

isSupported Indicates if running native processes is supported in the current profile.Boolean Indicates if running native processes is supported in the current profile. This property returns true only when running in the extendedDesktop profile. In addition, NativeProcess.isSupported is always false for applications installed as an AIR file. You must package an AIR application using the ADT -target native flag in order to use the NativeProcess class. running Indicates if this native process is currently running.Boolean Indicates if this native process is currently running. The process is running if you have called the start() method and the NativeProcess object has not yet dispatched an exit event. A NativeProcess instance corresponds to a single process on the underlying operating system. This property remains true as long as the underlying operating system process is executing (while the native process is starting and until the process returns an exit code to the operating system.) standardError Provides access to the standard error output from this native process.flash.utils:IDataInputif no data is present and a read operation is attempted. EOFErrorflash.errors:EOFError Provides access to the standard error output from this native process. As data becomes available on this pipe, the NativeProcess object dispatches a ProgressEvent object. If you attempt to read data from this stream when no data is available, the NativeProcess object throw an EOFError exception.

The type is IDataInput because data is input from the perspective of the current process, even though it is an output stream of the child process.

standardInput Provides access to the standard input of this native process.flash.utils:IDataOutputwhen writing to this value when running returns false or when attempting to write data to a closed input stream. IllegalOperationErrorflash.errors:IllegalOperationError Provides access to the standard input of this native process. Use this pipe to send data to this process. Each time data is written to the input property that data is written to the native process's input pipe as soon as possible.

The type is IDataOutput because data is output from the perspective of the current process, even though it is an input stream of the child process.

standardOutput Provides access to the standard output pipe of this native process.flash.utils:IDataInputif no data is present and a read operation is attempted. EOFErrorflash.errors:EOFError Provides access to the standard output pipe of this native process. Use this pipe to read data from the native process's standard output. When data is present on this pipe, the NativeProcess object dispatches a ProgressEvent. If you attempt to read data from this stream when no data is available, the NativeProcess object throws an EOFError.

The type is IDataInput because data is input from the perspective of the current process even though it is an output stream of the child process.

InteractiveIcon The InteractiveIcon class is the base class for the operating system icons associated with applications.flash.desktop:Icon The InteractiveIcon class is the base class for the operating system icons associated with applications.

Use the icon property of the NativeApplication object to get an instance of the application icon. The icon type will be one of the subclasses of InteractiveIcon, either DockIcon on Mac OS X^® or SystemTrayIcon on Windows^® and Linux.

You cannot instantiate the InteractiveIcon class directly. Calls to the new InteractiveIcon() constructor will throw an ArgumentError exception.

bitmaps The icon image as an array of BitmapData objects of different sizes.Array The icon image as an array of BitmapData objects of different sizes.

When an icon is displayed in a given operating system context, the bitmap in the array closest to the displayed size is used (and scaled if necessary). Common sizes include 16x16, 32x32, 48x48, and 128x128. (512x512 pixel icons may be used for some operating system icons in the near future.)

In some contexts, the operating system may use a default system icon if nothing has been assigned to the bitmaps property. In other contexts, no icon appears.

To set or change the icon appearance, assign an array of BitmapData objects to the bitmaps property:

icon.bitmaps = new Array(icon16x16.bitmapData, icon128x128.bitmapData);

Modifying the bitmaps array directly has no effect.

To clear the icon image, assign an empty array to the bitmaps property.

Note: When loading image files for an icon, the PNG file format generally provides the best alpha blending. The GIF format supports only on or off transparency (no blending). The JPG format does not support transparency at all.

height The current display height of the icon in pixels.int The current display height of the icon in pixels.

Some icon contexts support dynamic sizes. The height property indicates the height of the icon chosen from the bitmaps array for the current context. The actual display height may be different if the operating system has scaled the icon.

width The current display width of the icon in pixels.int The current display width of the icon in pixels.

Some icon contexts support dynamic sizes. The width property indicates the width of the icon chosen from the bitmaps array for the current context. The actual display width may be different if the operating system has scaled the icon.

InvokeEventReason The InvokeEventReason class enumerates values returned by the reason property of an InvokeEvent object.Defines constants representing the ways in which an application can be invoked via the operating system. Object The InvokeEventReason class enumerates values returned by the reason property of an InvokeEvent object. STANDARD Indicates that the InvokeEvent occured for any reason other than login.standardString Indicates that the InvokeEvent occured for any reason other than login. NativeDragActions The NativeDragActions class defines string constants for the names of the drag-and-drop actions.Object The NativeDragActions class defines string constants for the names of the drag-and-drop actions.

The NativeDragActions constants are used as values for the dropAction property of the NativeDragManager and NativeDragEvent classes.

COPY Defines the string to use for the copy action.copyString Defines the string to use for the copy action. LINK Defines the string to use for the link action.linkString Defines the string to use for the link action. MOVE Defines the string to use for the move action.moveString Defines the string to use for the move action. NONE Defines the string to use when no action is specified.noneString Defines the string to use when no action is specified.

In a nativeDragComplete event, an action of none indicates that the drag-and-drop operation was abandoned by the user.

ClipboardFormats The ClipboardFormats class defines constants for the names of the standard data formats used with the Clipboard class.Clipboard, ClipboardFormats and ClipboardTransferMode were all added to AIR 1.0. These are also being added, with some exceptions listed in this file, to FP10. Object The ClipboardFormats class defines constants for the names of the standard data formats used with the Clipboard class. Flash Player 10 only supports TEXT_FORMAT, RICH_TEXT_FORMAT, and HTML_FORMAT. BITMAP_FORMAT Image data (AIR only).Not supported in FP10. air:bitmapString Image data (AIR only). FILE_LIST_FORMAT An array of files (AIR only).Not supported in FP10. air:file listString An array of files (AIR only). FILE_PROMISE_LIST_FORMAT File promise list (AIR only).Not supported in FP10. air:file promise listString File promise list (AIR only). HTML_FORMAT HTML data.air:htmlString HTML data. RICH_TEXT_FORMAT Rich Text Format data.air:rtfString Rich Text Format data. TEXT_FORMAT String data.air:textString String data. URL_FORMAT A URL string (AIR only).Not supported in FP10. air:urlString A URL string (AIR only). NativeApplication The NativeApplication class represents this AIR application.flash.events:EventDispatcher 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.

keyUp Dispatched when the user releases a key.flash.events.KeyboardEvent.KEY_UPflash.events.KeyboardEvent 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. keyDown Dispatched when the user presses a key.flash.events.KeyboardEvent.KEY_DOWNflash.events.KeyboardEvent 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. userPresent Dispatched when the operating system detects mouse or keyboard activity after an idle period.flash.events.Event.USER_PRESENTflash.events.Event 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.

userIdle Dispatched when the user has been idle.flash.events.Event.USER_IDLEflash.events.Event 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.

networkChange Dispatched when either a new network connection becomes available or an existing network connection is lost.flash.events.Event.NETWORK_CHANGEflash.events.Event 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.

exiting Dispatched when the application exit sequence is started.flash.events.Event.EXITINGflash.events.Event 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().

deactivate Dispatched when the desktop focus is switched to a different application.flash.events.Event.DEACTIVATEflash.events.Event Dispatched when the desktop focus is switched to a different application. activate Dispatched when this application becomes the active desktop application.flash.events.Event.ACTIVATEflash.events.Event Dispatched when this application becomes the active desktop application. browserInvoke Dispatched when an application is invoked by a SWF file running in the user's browser.flash.events.BrowserInvokeEvent.Browser_INVOKEflash.events.BrowserInvokeEvent 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:

<allowBrowserInvocation>true</allowBrowserInvocation> invoke Dispatched when an application is invoked.flash.events.InvokeEvent.INVOKEflash.events.InvokeEvent 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.

activate Activates this application.windowflash.display:NativeWindownullThe NativeWindow object of the window to activate along with the application. 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.

activateflash.events:EventDispatched if the activation state changes. Dispatched if the activation state changes.addEventListener Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event.typeStringThe type of event. listenerFunctionThe 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: function(evt:Event):void

The function can have any name.

useCaptureBooleanfalse 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. priorityint0The 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. useWeakReferenceBooleanfalseDetermines 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.

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

clear Invokes an internal delete command on the focused display object.true. Boolean 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.

copy Invokes an internal copy command on the focused display object.Boolean 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.

cut Invokes an internal cut command on the focused display object.true. Boolean 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.

dispatchEvent Dispatches an event into the event flow.A value of true if the event was successfully dispatched. A value of false indicates failure or that preventDefault() was called on the event. Booleaneventflash.events:EventThe 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. Dispatches an event into the event flow. The event target is the EventDispatcher object upon which the dispatchEvent() method is called. exit Terminates this application.errorCodeint0The exit code reported to the operating system when this application exits. 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.

getDefaultApplication Gets the default application for opening files with the specified extension.If the extension parameter does not contain one of the file extensions declared in the application descriptor. ErrorErrorThe path of the default application. StringextensionStringA String containing the extension of the file type of interest (without the "."). 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.

isSetAsDefaultApplication Specifies whether this application is currently the default application for opening files with the specified extension.If the extension parameter does not contain one of the file extensions declared in the application descriptor. ErrorErrortrue if this application is the default. BooleanextensionStringA String containing the extension of the file type of interest (without the "."). 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.

paste Invokes an internal paste command on the focused display object.true. Boolean 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.

removeAsDefaultApplication Removes this application as the default for opening files with the specified extension.If the extension parameter does not contain one of the file extensions declared in the application descriptor. ErrorErrorextensionStringA String containing the extension of the file type of interest (without the "."). 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.

removeEventListener Removes a listener from the EventDispatcher object.typeStringThe type of event. listenerFunctionThe listener object to remove. useCaptureBooleanfalse 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. 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. selectAll Invokes an internal selectAll command on the focused display object.true. Boolean 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.

setAsDefaultApplication Sets this application as the default application for opening files with the specified extension.If the extension parameter does not contain one of the file extensions declared in the application descriptor. ErrorErrorextensionStringA String containing the extension of the file type of interest (without the "."). 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.

activeWindow The active application window.flash.display:NativeWindow 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.

applicationDescriptor The contents of the application descriptor file for this AIR application.XML The contents of the application descriptor file for this AIR application. 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. 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 The application ID of this application.String The application ID of this application.

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

autoExit Specifies whether the application should automatically terminate when all windows have been closed.Boolean 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.

icon The application icon.flash.desktop:InteractiveIcon 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.

idleThreshold The number of seconds that must elapse without user input before a userIdle event is dispatched.intIf 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. ArgumentErrorArgumentError 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.

menu The application menu.flash.display:NativeMenu 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 or Linux. Assigning a NativeMenu object to this property when NativeApplication.nativeApplication.supportsMenu is false is allowed, but does nothing. Be sure to use the NativeApplication.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.

nativeApplication The singleton instance of the NativeApplication object.flash.desktop:NativeApplicationIf accessed by content outside the application security sandbox. ErrorError The singleton instance of the NativeApplication object. openedWindows An array containing all the open native windows of this application.Array 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.

publisherID The publisher ID of this application.String 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 The patch level of the runtime hosting this application.uint The patch level of the runtime hosting this application. runtimeVersion The version number of the runtime hosting this application.String The version number of the runtime hosting this application. startAtLogin Specifies whether this application is automatically launched whenever the current user logs in.BooleanOn 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. IllegalOperationErrorflash.errors:IllegalOperationErrorIf this application is not installed, which may be the case when launched by the AIR Debug Launcher (ADL). IllegalOperationErrorflash.errors:IllegalOperationError 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.

supportsDefaultApplication Indicates whether setAsDefaultApplication(), removeAsDefaultApplication(), and isSetAsDefaultApplication() are supported on the current platform.Boolean 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.

supportsDockIcon Indicates whether AIR supports dock-style application icons on the current operating system.Boolean 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).

supportsMenu Specifies whether the current operating system supports a global application menu bar.Boolean 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).

supportsStartAtLogin Indicates whether startAtLogin is supported on the current platform.Boolean Indicates whether startAtLogin is supported on the current platform.

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

supportsSystemTrayIcon Specifies whether AIR supports system tray icons on the current operating system.Boolean 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).

systemIdleMode Provides a way for applications to prevent the user interface from going into "idle" mode.String 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.

timeSinceLastUserInput The time, in seconds, since the last user input.int The time, in seconds, since the last user input. Updater The Updater class is used to update the currently running application with a different version.Object The Updater class is used to update the currently running application with a different version. To use it, instantiate an Updater object and then call its update() method.

The Updater class is only supported in the desktop profile. It is not supported for extended desktop applications (applications installed with a native installer), and it is not supported on the AIR mobile profile or AIR for TV profiles. Check the Updater.isSupported property.

Extended desktop application (applications installed with a native installer) can download a new version of the native installer and launch it using the File.openWithDefaultApplication() method.

Updater The constructor function for the Updater class. The constructor function for the Updater class. Note that the update() method is not a static member of the class. You must instantiate an Updater object and call the update() method on it. update Updates the currently running application with the version of the application contained in the specified AIR file.The method was called when running in ADL. IllegalOperationErrorflash.errors:IllegalOperationErrorairFileflash.filesystem:FileThe File object pointing to the AIR file that contains the update version of the application. versionStringThe required version in the new AIR file. The string in the version attribute of the main application element of the application descriptor file for the AIR file must match this value in order for the update to succeed. Updates the currently running application with the version of the application contained in the specified AIR file. The application in the AIR file must have the same application identifier (appID) as the currently running application.

Calling this method causes the current application to exit (as if the NativeApplication.exit() method had been called). This is necessary because Adobe AIR cannot fully update an application while the application is running. Upon successfully installing the new version of the application, the application launches. If the runtime cannot successfully install the new version (for example, if its application ID does not match the existing version), the AIR installer presents an error message to the user, and then the old version relaunches.

The update process relaunches the application whether or not the update is successful. Updates can fail for a variety of reasons, including some that the application cannot control (such as the user having insufficient privileges to install the application). Applications should take care to detect failures and avoid reattempting the same failed update repeatedly. The resulting infinite loop would effectively disable the application. One way to check for a successful update is to write the current version number to a file before starting the update, and then compare that to the version number when the application is relaunched.

When testing an application using the AIR Debug Launcher (ADL) application, calling the update() method results in an IllegalOperationError exception.

On Mac OS, to install an updated version of an application, the user needs to have adequate system privileges to install to the application directory. On Windows or Linux, the user needs to have adminstrative privileges.

If the updated version of the application requires an updated version of the runtime, the new runtime version is installed. To update the runtime, a user needs to have administrative privileges for the computer.

Note: Specifying the version parameter is required for security reasons. By requiring the application to verify the version number in the AIR file, the application will not inadvertantly install an older version, which might contain a security vulnerability that has been fixed.

Note that the update() method is not a static method of the class. You instantiate an Updater object and call the update() method of that object. import flash.fileSystem.File; import flash.desktop.Updater; var updater:Updater = new Updater(); var airFile:File = File.applicationStorageDirectory.resolvePath("Example Application.air"); var version:String = "2.01"; updater.update(airFile, version); isSupported The isSupported property is set to true if the Updater class is available on the current platform, otherwise it is set to false.Boolean The isSupported property is set to true if the Updater class is available on the current platform, otherwise it is set to false. SystemTrayIcon The SystemTrayIcon class represents the Windows taskbar® notification area (system tray)-style icon.A taskbar icon. flash.desktop:InteractiveIcon The SystemTrayIcon class represents the Windows taskbar^® notification area (system tray)-style icon.

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

Not all desktop operating systems have system tray icons. Check NativeApplication.supportsSystemTrayIcon to determine whether system tray icons are supported on the current system.

An instance of the SystemTrayIcon class cannot be created. Get the object representing the system tray icon from the icon property of the "global" NativeApplication object.

When system tray icons are supported, the icon will be of type SystemTrayIcon. Otherwise, the type of icon will be another subclass of InteractiveIcon, typically DockIcon.

Important: Attempting to call a SystemTrayIcon class method on the NativeApplication.icon object on an operating system for which AIR does not support system tray icons will generate a run-time exception.

rightClick Dispatched by this SystemTrayIcon object on right mouse click.flash.events.ScreenMouseEvent.RIGHT_CLICKflash.events.ScreenMouseEvent Dispatched by this SystemTrayIcon object on right mouse click. rightMouseUp Dispatched by this SystemTrayIcon object on right mouse up.flash.events.ScreenMouseEvent.RIGHT_MOUSE_UPflash.events.ScreenMouseEvent Dispatched by this SystemTrayIcon object on right mouse up. rightMouseDown Dispatched by this SystemTrayIcon object on right mouse down.flash.events.ScreenMouseEvent.RIGHT_MOUSE_DOWNflash.events.ScreenMouseEvent Dispatched by this SystemTrayIcon object on right mouse down. click Dispatched by this SystemTrayIcon object on mouse click.flash.events.ScreenMouseEvent.CLICKflash.events.ScreenMouseEvent Dispatched by this SystemTrayIcon object on mouse click. mouseUp Dispatched by this SystemTrayIcon object on mouse up.flash.events.ScreenMouseEvent.MOUSE_UPflash.events.ScreenMouseEvent Dispatched by this SystemTrayIcon object on mouse up. mouseDown Dispatched by this SystemTrayIcon object on mouse down.flash.events.ScreenMouseEvent.MOUSE_DOWNflash.events.ScreenMouseEvent Dispatched by this SystemTrayIcon object on mouse down. MAX_TIP_LENGTH The permitted length of the system tray icon tooltip.63Number The permitted length of the system tray icon tooltip. bitmaps The icon image as an array of BitmapData objects of different sizes.Array The icon image as an array of BitmapData objects of different sizes.

In some contexts, the operating system may use a default system icon if nothing has been assigned to the bitmaps property. In other contexts, no icon appears.

To set or change the icon appearance, assign an array of BitmapData objects to the bitmaps property:

icon.bitmaps = new Array(icon16x16.bitmapData, icon128x128.bitmapData);

Modifying the bitmaps array directly has no effect.

To clear the icon image, assign an empty array to the bitmaps property.

height The current display height of the icon in pixels.int The current display height of the icon in pixels.

tooltip The tooltip that pops up for the system tray icon.String The tooltip that pops up for the system tray icon. If the string is longer than SystemTrayIcon.MAX_TIP_LENGTH, the tip will be truncated. width The current display width of the icon in pixels.int The current display width of the icon in pixels.

Clipboard The Clipboard class provides a container for transferring data and objects through the clipboard.NativeDragManager is AIR only and is not in FP10. Object The Clipboard class provides a container for transferring data and objects through the clipboard. The operating system clipboard can be accessed through the static generalClipboard property.

A Clipboard object can contain the same information in more than one format. By supplying information in multiple formats, you increase the chances that another application will be able to use that information. Add data to a Clipboard object with the setData() or setDataHandler() method.

The standard formats are:

BITMAP_FORMAT: a BitmapData object (AIR only)
FILE_LIST_FORMAT: an array of File objects (AIR only)
HTML_FORMAT: HTML-formatted string data
TEXT_FORMAT: string data
RICH_TEXT_FORMAT: a ByteArray containing Rich Text Format data
URL_FORMAT: a URL string (AIR only)

These constants for the names of the standard formats are defined in the ClipboardFormats class.

When a transfer to or from the operating system occurs, the standard formats are automatically translated between ActionScript data types and the native operating system clipboard types.

You can use application-defined formats to add ActionScript objects to a Clipboard object. If an object is serializable, both a reference and a clone of the object can be made available. Object references are valid only within the originating application.

When it is computationally expensive to convert the information to be transferred into a particular format, you can supply the name of a function that performs the conversion. The function is called if and only if that format is read by the receiving component or application. Add a deferred rendering function to a Clipboard object with the setDataHandler() method. Note that in some cases, the operating system calls the function before a drop occurs. For example, when you use a handler function to provide the data for a file dragged from an AIR application to the file system, the operating system calls the data handler function as soon as the drag gesture leaves the AIR application—typically resulting in an undesireable pause as the file data is downloaded or created.

Note for AIR applications: The clipboard object referenced by the event objects dispatched for HTML drag-and-drop and copy-and-paste events are not the same type as the AIR Clipboard object. The JavaScript clipboard object is described in the AIR developer's guide.

Note for Flash Player applications: In Flash Player 10, a paste operation from the clipboard first requires a user event (such as a keyboard shortcut for the Paste command or a mouse click on the Paste command in a context menu). Clipboard.getData() will return the contents of the clipboard only if the InteractiveObject has received and is acting on a paste event. Calling Clipboard.getData() under any other circumstances will be unsuccessful. The same restriction applies in AIR for content outside the application sandbox.

On Linux, clipboard data does not persist when an AIR application closes.

The following example, for Adobe AIR, uses the ClipboardExample class to copy a string from one variable to another via the system clipboard. This task is accomplished by performing the following steps:

Write the data, in this case a string, to Clipboard.generalClipboard.
Read the clipboard contents from Clipboard.generalClipboard.

Note: Because of security restrictions on accessing clipboard data, this example does not work in Flash Player. In Flash Player, you can only call the getData() method of the Clipboard object in a paste event handler.

package { import flash.display.Sprite; import flash.desktop.Clipboard; import flash.desktop.ClipboardFormats; import flash.desktop.ClipboardTransferMode; public class ClipboardExample extends Sprite { public function ClipboardExample() { var sally:String = "Sally"; var person:String; copy(sally); person = paste(); trace(person); //traces: "Sally" } private function copy(text:String):void { Clipboard.generalClipboard.clear(); Clipboard.generalClipboard.setData(ClipboardFormats.TEXT_FORMAT, text); } private function paste():String { if(Clipboard.generalClipboard.hasFormat(ClipboardFormats.TEXT_FORMAT)) { return String(Clipboard.generalClipboard.getData(ClipboardFormats.TEXT_FORMAT)); } else { return null; } } } } Clipboard Creates an empty Clipboard object.the example located at examples\Clipboard.clipboard.1.as should not be displayed with FP10 docs because FP10 will throw an error when new Clipboard() is called. new Clipboard() is not supported in Flash Player, since only the operating system clipboard can be used in Flash Player. For copy-and-paste operations involving the operating system clipboard, use the Clipboard.generalClipboard object rather than creating a new Clipboard object. Does not throw an error in an AIR application. IllegalOperationErrorflash.errors:IllegalOperationError Creates an empty Clipboard object.

Create Clipboard objects to hold the data of a native drag-and-drop gesture in Adobe AIR. Clipboard objects can be used for only one drag-and-drop gesture; they cannot be reused.

Do not create a Clipboard object for copy-and-paste operations. Use the single Clipboard.generalClipboard object instead.

The following example creates a new clipboard for use with the NativeDragManager class.

Note: For copy-and-paste operations involving the operating system clipboard, use the Clipboard.generalClipboard object rather than creating a new clipboard.

import flash.desktop.Clipboard; var clipboard:Clipboard = new Clipboard(); clearData Deletes the data representation for the specified format.Call to generalClipboard.clearData() is not permitted in this context. In Flash Player, you can only call this method successfully during the processing of a user event (as in a key press or mouse click). In AIR, this restriction only applies to content outside of the application security sandbox. SecurityErrorSecurityErrorformatStringThe data format to remove. Deletes the data representation for the specified format. The following example clears any data having the format ClipboardFormats.TEXT_FORMAT from the system clipboard: import flash.desktop.ClipboardFormats; Clipboard.generalClipboard.clearData(ClipboardFormats.TEXT_FORMAT); clear Deletes all data representations from this Clipboard object.Call to generalClipboard.clear() is not permitted in this context. In Flash Player, you can only call this method successfully during the processing of a user event (as in a key press or mouse click). In AIR, this restriction only applies to content outside of the application security sandbox. SecurityErrorSecurityError Deletes all data representations from this Clipboard object. The following example clears the system clipboard: Clipboard.generalClipboard.clear(); getData Gets the clipboard data if data in the specified format is present.transferMode is not one of the names defined in the ClipboardTransferMode class. ErrorErrorThe Clipboard object requested is no longer in scope (AIR only). IllegalOperationErrorflash.errors:IllegalOperationErrorReading from or writing to the clipboard is not permitted in this context. In Flash Player, you can only call this method successfully during the processing of a paste event. In AIR, this restriction only applies to content outside of the application security sandbox. SecurityErrorSecurityErrorAn object of the type corresponding to the data format. ObjectformatStringThe data format to return. The format string can contain one of the standard names defined in the ClipboardFormats class, or an application-defined name. transferModeStringoriginalPreferredSpecifies whether to return a reference or serialized copy when an application-defined data format is accessed. The value must be one of the names defined in the ClipboardTransferMode class. This value is ignored for the standard data formats; a copy is always returned. Gets the clipboard data if data in the specified format is present.

Flash Player requires that the getData() be called in a paste event handler. In AIR, this restriction only applies to content outside of the application security sandbox.

When a standard data format is accessed, the data is returned as a new object of the corresponding Flash data type.

When an application-defined format is accessed, the value of the transferMode parameter determines whether a reference to the original object or an anonymous object containing a serialized copy of the original object is returned. When an originalPreferred or clonePreferred mode is specified, Flash Player or AIR returns the alternate version if the preferred version is not available. When an originalOnly or cloneOnly mode is specified, Flash Player or AIR returns null if the requested version is not available.

The following example reads text from the system clipboard, if available: import flash.desktop.ClipboardFormats; var pasteData:String = Clipboard.generalClipboard.getData(ClipboardFormats.TEXT_FORMAT) as String; hasFormat Checks whether data in the specified format exists in this Clipboard object.The Clipboard object requested is no longer in scope. IllegalOperationErrorflash.errors:IllegalOperationErrorReading from or writing to the clipboard is not permitted in this context. SecurityErrorSecurityErrortrue, if data in the specified format is present. BooleanformatStringThe format type to check. Checks whether data in the specified format exists in this Clipboard object.

Use the constants in the ClipboardFormats class to reference the standard format names.

The following example tests the system clipboard to determine whether text-formatted data is available: if(Clipboard.generalClipboard.hasFormat(ClipboardFormats.TEXT_FORMAT)){ //do something } setDataHandler Adds a reference to a handler function that produces the data to be transfered.format or handler is null. TypeErrorTypeErrorThe Clipboard object requested is no longer in scope (AIR only). IllegalOperationErrorflash.errors:IllegalOperationErrorReading from or writing to the clipboard is not permitted in this context. In Flash Player, you can only call this method successfully during the processing of a user event (such as a key press or mouse click). In AIR, this restriction only applies to content outside of the application security sandbox. SecurityErrorSecurityErrortrue if the handler was succesfully set; false otherwise. BooleanformatStringA function that returns the data to be transferred. handlerFunctionThe format of the data. serializableBooleantrueSpecify true if the object returned by handler can be serialized (and deserialized). Adds a reference to a handler function that produces the data to be transfered.

Use a handler function to defer creation or rendering of the data until it is actually accessed.

The handler function must return the appropriate data type for the specified format:

FormatReturn TypeClipboardFormats.TEXT_FORMATStringClipboardFormats.HTML_FORMATStringClipboardFormats.URL_FORMATString (AIR only)ClipboardFormats.RICH_TEXT_FORMATByteArrayClipboardFormats.BITMAP_FORMATBitmapData (AIR only)ClipboardFormats.FILE_LIST_FORMATArray of File (AIR only)ClipboardFormats.FILE_PROMISE_LIST_FORMATArray of File (AIR only)Custom format nameNon-void

The handler function is called when and only when the data in the specified format is read. Note that in some cases, the operating system calls the function before a drop occurs. For example, when you use a handler function to provide the data for a file dragged from an AIR application to the file system, the operating system calls the data handler function as soon as the drag gesture leaves the AIR application—typically resulting in an undesireable pause as the file data is downloaded or created. You can use a URLFilePromise for this purpose instead.

Note that the underlying data can change between the time the handler is added and the time the data is read unless your application takes steps to protect the data. The behavior that occurs when data on the clipboard represented by a handler function is read more than once is not guaranteed. The clipboard might return the data produced by the first function call or it might call the function again. Do not rely on either behavior.

In the application sandbox of Adobe AIR, setDataHandler() can be called anytime. In other contexts, setDataHandler() can only be called in response to a user-generated event such as a key press or mouse click.

To add data directly to this Clipboard object, use the setData() method instead. If both the setData() and the setDataHandler() methods are called with the same format name, then the handler function is never called.

Note: On Mac OS, when you set the format parameter to ClipboardFormats.URL_FORMAT, the URL is transferred only if the handler function returns a valid URL. Otherwise, the Clipboard object is emptied (and calling getData() returns null).

The following example adds a random number to the system clipboard through a deferred data function: import flash.desktop.ClipboardFormats; Clipboard.generalClipboard.setDataHandler(ClipboardFormats.TEXT_FORMAT, randomNumberGenerator); public function randomNumberGenerator():String{ return Math.random().toString(); } setData Adds a representation of the information to be transferred in the specified data format.The Clipboard object requested is no longer in scope (which can occur with clipboards created for drag-and-drop operations). IllegalOperationErrorflash.errors:IllegalOperationErrorReading from or writing to the clipboard is not permitted in this context. In Flash Player, you can only call this method successfully during the processing of a user event (as in a key press or mouse click). In AIR, this restriction only applies to content outside of the application security sandbox. SecurityErrorSecurityErrorformat or data is null. TypeErrorTypeErrortrue if the data was succesfully set; false otherwise. In Flash Player, returns false when format is an unsupported member of ClipboardFormats. (Flash Player does not support ClipboardFormats.URL_FORMAT, ClipboardFormats.FILE_LIST_FORMAT, ClipboardFormats.FILE_PROMISE_LIST_FORMAT, or ClipboardFormats.BITMAP_FORMAT). BooleanformatStringThe format of the data. dataObjectThe information to add. serializableBooleantrueSpecify true for objects that can be serialized (and deserialized). Adds a representation of the information to be transferred in the specified data format.

In the application sandbox of Adobe AIR, setData() can be called anytime. In other contexts, setData() can only be called in response to a user-generated event such as a key press or mouse click.

Different representations of the same information can be added to the clipboard as different formats, which increases the ability of other components or applications to make use of the available data. For example, an image could be added as bitmap data for use by image editing applications, as a URL, and as an encoded PNG file for transfer to the native file system.

The data parameter must be the appropriate data type for the specified format:

FormatTypeDescriptionClipboardFormats.TEXT_FORMATStringstring dataClipboardFormats.HTML_FORMATStringHTML string dataClipboardFormats.URL_FORMATStringURL string (AIR only)ClipboardFormats.RICH_TEXT_FORMATByteArrayRich Text Format dataClipboardFormats.BITMAP_FORMATBitmapDatabitmap data (AIR only)ClipboardFormats.FILE_LIST_FORMATarray of Filean array of files (AIR only)Custom format nameanyobject reference and serialized clone

Custom format names cannot begin with "air:" or "flash:". To prevent name collisions when using custom formats, you may want to use your application ID or a package name as a prefix to the format, such as "com.example.applicationName.dataPacket".

When transferring within or between applications, the serializable parameter determines whether both a reference and a copy are available, or whether only a reference to an object is available. Set serializable to true to make both the reference and a copy of the data object available. Set serializable to false to make only the object reference available. Object references are valid only within the current application so setting serializable to false also means that the data in that format is not available to other Flash Player or AIR applications. A component can choose to get the reference or the copy of the object by setting the appropriate clipboard transfer mode when accessing the data for that format.

Note: The standard formats are always converted to native formats when data is pasted or dragged outside a supported application, so the value of the serializable parameter does not affect the availability of data in the standard formats to non-Flash-based applications.

To defer rendering of the data for a format, use the setDataHandler() method instead. If both the setData() and the setDataHandler() methods are used to add a data representation with the same format name, then the handler function will never be called.

Note: On Mac OS, when you set the format parameter to ClipboardFormats.URL_FORMAT, the URL is transferred only if it is a valid URL. Otherwise, the Clipboard object is emptied (and calling getData() returns null).

The following example adds content to the system clipboard in both text and HTML formats: import flash.desktop.ClipboardFormats; var htmlString:String = "<html><body>Body content</body></html>"; Clipboard.generalClipboard.setData(ClipboardFormats.TEXT_FORMAT, urlString); Clipboard.generalClipboard.setData(ClipboardFormats.HTML_FORMAT, urlString); formats An array of strings containing the names of the data formats available in this Clipboard object.Array An array of strings containing the names of the data formats available in this Clipboard object.

String constants for the names of the standard formats are defined in the ClipboardFormats class. Other, application-defined, strings may also be used as format names to transfer data as an object.

The following example reads the formats array of the system clipboard: var availableFormats:Array = Clipboard.generalClipboard.formats; generalClipboard The operating system clipboard.flash.desktop:Clipboard The operating system clipboard.

Any data pasted to the system clipboard is available to other applications. This may include insecure remote code running in a web browser.

Note: In Flash Player 10 applications, a paste operation from the clipboard first requires a user event (such as a keyboard shortcut for the Paste command or a mouse click on the Paste command in a context menu). Clipboard.getData() will return the contents of the clipboard only if the InteractiveObject has received and is acting on a paste event. Calling Clipboard.getData() under any other circumstances will be unsuccessful. The same restriction applies in AIR for content outside the application sandbox.

The generalClipboard object is created automatically. You cannot assign another instance of a Clipboard to this property. Instead, you use the getData() and setData() methods to read and write data to the existing object.

You should always clear the clipboard before writing new data to it to ensure that old data in all formats is erased.

The generalClipboard object cannot be passed to the AIR NativeDragManager. Create a new Clipboard object for native drag-and-drop operations in an AIR application.

To write to the operating system clipboard: import flash.desktop.ClipboardFormats; var copy:String = "A string to copy to the system clipboard."; Clipboard.generalClipboard.clear(); Clipboard.generalClipboard.setData(ClipboardFormats.TEXT_FORMAT, copy); To read from the operating system clipboard: import flash.desktop.ClipboardFormats; var pasteData:String = Clipboard.generalClipboard.getData(ClipboardFormats.TEXT_FORMAT) as String; supportsFilePromise Indicates whether the file promise clipboard format is supported on the client system.Boolean Indicates whether the file promise clipboard format is supported on the client system. NotificationType The NotificationType class defines constants for use in the priority parameter of the DockIcon bounce() method and the type parameter of the NativeWindow notifyUser() method.constants for the supported urgency ratings of a notification. Object The NotificationType class defines constants for use in the priority parameter of the DockIcon bounce() method and the type parameter of the NativeWindow notifyUser() method. CRITICAL Specifies that a notification alert is critical in nature and the user should attend to it promptly.criticalString Specifies that a notification alert is critical in nature and the user should attend to it promptly. INFORMATIONAL Specifies that a notification alert is informational in nature and the user can safely ignore it.informationalString Specifies that a notification alert is informational in nature and the user can safely ignore it. IFilePromise The IFilePromise interface defines the interface used by the AIR runtime to read data for a file promise. The IFilePromise interface defines the interface used by the AIR runtime to read data for a file promise.

A file promise is a drag-and-drop clipboard format that allows a user to drag a file that does not yet exist out of an AIR application. AIR uses the methods and properties defined by the IFilePromise interface to access the data to be written when the file promise is dropped.

When a file promise is dropped on a suitable target, AIR calls the IFilePromise open() method. The implementation of this method must return the data provider as an object that implements the IDataInput interface. The provider object can be one of the built-in classes, such as ByteArray, FileStream, Socket, and URLStream, or it can be a custom class.

If the data from the data provider is accessed synchronously, such as with a ByteArray, AIR reads the amount of data indicated by the IDataInput bytesAvailable property and writes it to the destination file.

If the data from the data provider is accessed asynchronously, such as with a Socket, AIR uses events dispatched by the provider to regulate the process of reading the data and writing it to the file. Data is read at each progress event until a complete or a close event is received. The runtime listens for the following events (but a data provider does not need to dispatch every event):

Event.OPEN
ProgressEvent.PROGRESS
ProgressEvent.SOCKET_DATA
Event.COMPLETE
Event.CLOSE
IOErrorEvent.IOERROR
SecurityErrorEvent.SECURITY_ERROR
HTTPStatusEvent.HTTP_STATUS
HTTPStatusEvent.HTTP_RESPONSE_STATUS

Custom data provider classes should dispatch either a progress event or a socketData event when data is available. Likewise, either a complete or a close event should be dispatched when all the requested data has been read. The error events inform the runtime that the data transfer has failed and should be aborted. The other events should be dispatched as appropriate to aid in error handling and in debugging application logic.

The methods defined by IFilePromise are only intended to be called by the AIR runtime after a drag and drop operation has completed. Developers should not typically call these methods from their own code.

Note: The URLFilePromise class, available in the air.desktop library implements the IFilePromise interface and uses the URLStream as a data provider. The air.desktop library is included as separate SWF and SWC files in the AIR SDK.

close Called by the AIR runtime when it has finished reading all data. Called by the AIR runtime when it has finished reading all data.

No methods will be called on the object reference returned by open() after close() has been called. The data provider object can be safely destroyed.

open Returns the data provider object.IDataInput An object implementing the IDataInput interface. If the data is provided asynchronously, the returned object must also implement the IEventDispatcher interface. flash.utils:IDataInput Returns the data provider object.

The data provider object must implement the IDataInput interface, which defines methods for reading data. If the IFilePromise isAsync property returns true, then the data provider object must also implement the IEventDispatcher interface. The following built-in classes can be used as a data provider:

ByteArray (synchronous)
FileStream (synchronous or asynchronous)
Socket (asynchronous)
URLStream (asynchronous)

You can also provide an object of a custom class that implements the required interfaces (or extends another class that implements them).

reportError Called by the AIR runtime to inform the IFilePromise implementation of errors that occur when reading data from the data provider object.eflash.events:ErrorEventThe error event containing detailed error information. Called by the AIR runtime to inform the IFilePromise implementation of errors that occur when reading data from the data provider object. isAsync Indicates whether asynchronous data transfer is supported.Boolean Indicates whether asynchronous data transfer is supported.

If true, then the data provider object returned by the open() method must implement the IEventDispatcher interface (or extend a class implementing this interface). The data transfer is driven by progress or socketData events. AIR waits for these data progress events until a complete or a close event is dispatched.

If isAsync returns false, then the AIR runtime assumes that all data is available immediately. In this case, the runtime reads the bytesAvailable property of the data provider object to determine the amount of data available and synchronously reads that amount of data.

relativePath The relative path and file name of the file that will be created by this file promise.Stringif the relative path uses .. shortcuts to traverse one or more parent directories of the drop target. ArgumentErrorArgumentError The relative path and file name of the file that will be created by this file promise.

This property must provide a valid path or an argument error is thrown when the file promise is dropped.

The path can include subdirectories, which are resolved based on the drop location. The subdirectories are created, if needed. When including subdirectories, use the File.separator constant to insert the proper path separator character for the current operating system. Using the .. shortcut to navigate to a parent directory is not allowed. If attempted, an argument error is thrown. Invalid file system characters are stripped from the path without throwing an error.

Note: To allow client code to set the path, you can implement a setter function with the signature: function set relativePath( value:String ):void.

NativeProcessStartupInfo This class provides the basic information used to start a process on the host operating system.Object This class provides the basic information used to start a process on the host operating system. It is constructed and passed to the start() method of a NativeProcess object.

Native process access is only available to AIR applications installed with native installers (applications in the extended desktop profile).

NativeProcessStartupInfo Constructs an empty NativeProcessStartupInfo object. Constructs an empty NativeProcessStartupInfo object. arguments The command line arguments that will be passed to the process on startup. The command line arguments that will be passed to the process on startup.

Each string in the arguments Vector will be passed as a separate argument to the executable, regardless of what characters the string contains. In other words, there is an exact one-to-one correspondence; no re-interpretation occurs. AIR automatically escapes any characters in the string that need to be escaped (such as space characters).

executable The File object that references an executable on the host operating system.flash.filesystem:Fileif the value specified is null, if it references a directory, or if it references a file that does not exist. ArgumentErrorArgumentError The File object that references an executable on the host operating system. This should be the full path to the executable including any extension required.

Note: On Mac OS, to launch an executable within an application bundle, be sure to have the path of the File object include the full path the the executable (within the bundle), not just the path to the app file.

workingDirectory The File object that references the initial working directory for the new native process.flash.filesystem:Fileif the value doesn't exist or is not a directory ArgumentErrorArgumentError The File object that references the initial working directory for the new native process. If assigned a value where isDirectory is false, an ArgumentError is thrown. SystemIdleMode The SystemIdleMode class provides constant values for system idle behaviors.Object The SystemIdleMode class provides constant values for system idle behaviors. These constants are used in the systemIdleMode property of the NativeApplication class. KEEP_AWAKE Prevents the system from dropping into an idle mode.keepAwakeString Prevents the system from dropping into an idle mode.

On Android, the application must specify the Android permissions for DISABLE_KEYGUARD and WAKE_LOCK in the application descriptor or the operating system will not honor this setting.

NORMAL The system follows the normal "idle user" behavior.normalString The system follows the normal "idle user" behavior. ClipboardTransferMode The ClipboardTransferMode class defines constants for the modes used as values of the transferMode parameter of the Clipboard.getData() method.Clipboard, ClipboardFormats and ClipboardTransferMode were all added to AIR 1.0. These are also being added, with some exceptions listed in this file, to FP10. Defines constants for the clipboard transfer modes. Object The ClipboardTransferMode class defines constants for the modes used as values of the transferMode parameter of the Clipboard.getData() method.

The transfer mode provides a hint about whether to return a reference or a copy when accessing an object contained on a clipboard.

CLONE_ONLY The Clipboard object should only return a copy.cloneOnlyString The Clipboard object should only return a copy. CLONE_PREFERRED The Clipboard object should return a copy if available and a reference if not.clonePreferredString The Clipboard object should return a copy if available and a reference if not. ORIGINAL_ONLY The Clipboard object should only return a reference.originalOnlyString The Clipboard object should only return a reference. ORIGINAL_PREFERRED The Clipboard object should return a reference if available and a copy if not.originalPreferredString The Clipboard object should return a reference if available and a copy if not. NativeDragManager The NativeDragManager class coordinates drag-and-drop operations.Object The NativeDragManager class coordinates drag-and-drop operations. With the native drag-and-drop API, you can allow a user to drag data between an AIR application and the native operating system, between two applications, or between components within a single application.

The following kinds of data can be transferred:

Bitmaps
Files
Text
URL strings
Serialized objects
Object references (valid only within the originating application)

Note: all NativeDragManager members are static. An instance of this class does not need to be created.

A drag-and-drop operation is a user interface gesture that begins with the user clicking a visible item and dragging it elsewhere. During the drag gesture, interactive objects on the display list dispatch native drag events as the gesture moves across the AIR application window. Handlers for these events can call the methods of the NativeDragManager class to indicate whether a dragged item can be dropped on an object. In response, the NativeDragManager changes the mouse pointer to provide feedback to the user.

AIR profile support: This feature is not supported on AIR for TV devices. Also, it is not supported on all mobile devices. You can test for support at run time using the NativeDragManager.isSupported property. See AIR Profile Support for more information regarding API support across multiple profiles.

Drag actions

Drag-and-drop gestures are typically used for three types of operations, called actions. Since the meaning of these actions depends on the application context, the runtime does not enforce any particular behavior with respect to actions. However, properly implementing the actions improves the user experience with your application.

The possible actions are:

Copy — A copy of the data is made, leaving the original untouched. (When dragging objects within an application, care should be taken to copy the original object itself rather than the reference to that object.)
Move — The data is moved from its original context into the context defined by the drop target, such as when moving an item from one list to another.
Link — A reference or shortcut to the original data is created, leaving the item in its original context.

The allowed actions can be set for a drag gesture by supplying an allowedActions parameter in the NativeDragManager.doDrag() call that starts the drag operation. If no allowedActions parameter is provided, all of the actions are allowed. Potential drag targets can check which actions are allowed by using the allowedActions property of a NativeDragEvent object, and should not accept a drop that allows only incompatible actions (this is not enforced by the runtime, however).

If a drop target only implements a single action, the object can set the dropAction property of the NativeDragManager in the handlers for both the nativeDragEnter and nativeDragOver events. Setting the property before the drop, allows the drag manager to update the mouse pointer to indicate the supported action and also prevents a user from choosing an incompatible action using modifier keys. If the specified action is not one of the allowed actions, then a drop is not allowed, even if the target calls the acceptDrop() method.

When accepting a drop, a potential drop target should specify the action chosen by setting the NativeDragManager.dropAction property in response to the nativeDragDrop event. This action is reported back to the initiating display object in the nativeDragComplete event. If no action is set by a drop target, then a default action is chosen from the allowed actions in this order of precedence: copy, move, link. The initiating object is responsible for updating its internal state in response to the chosen action.

String constants for the action names are defined in the NativeDragActions class.

Sequence of events

A drag gesture is begun by calling the NativeDragManager.doDrag() method within a mouseDown or mouseMove event handler and proceeds through the following event sequence in response to user actions:

nativeDragStart event — When NativeDragManager.doDrag() is called, the interactive object passed as a paramter to the method becomes the initiator object and dispatches a nativeDragStart event.
nativeDragUpdate event — While the drag is in progress, the initiator object continually dispatches nativeDragUpdate events.
nativeDragEnter, nativeDragOver events — When a drag gesture passes over an interactive object, that object dispatches a nativeDragEnter event. While the drag gesture remains over the interactive object, it continually dispatches nativeDragOver events. In response to either of these events, an object that serves as a potential drop target should check the properties of the event object to decide whether it can accept the drop. If the data format and allowed actions are appropriate, then the event handler for these events must call NativeDragManager.acceptDrop(), passing in a reference to the display object to serve as the drag target (typically the object that dispatched the nativeDragEnter or nativeDragOver event). The user can then drop the dragged item onto the target.
nativeDragExit event — When a drag gesture passes out of an interactive object, the object dispatches a nativeDragExit event. If the object had been designated as the drag target by an earlier call to the NativeDragManager.acceptDrop() method, that call is no longer valid and acceptDrop() must be called again if the gesture re-enters the interactive object.
nativeDragDrop event — The target display object dispatches a nativeDragDrop event when the user releases the mouse button over the object. The handler for this event can access the data in the transferable property of the event object and should set the NativeDragManager.dropAction property to signal which action should be taken by the initiator object.
nativeDragComplete — When the user releases the mouse button at the end of a drag gesture, the initiator object dispatches a nativeDragComplete event (whether or not the drop itself was consumated). The handler for this event can check the dropAction property of the event object to determine what, if any, modification should be made to its internal data state, such as removing a dragged-out item from a list. If dropAction is NativeDragActions.NONE, then the dragged item was not dropped on an eligible target.

Gestures between applications

When a drag gesture enters an AIR application window from a non-AIR application, there is no initiator object to dispatch the nativeDragStart or nativeDragComplete event. The events dispatched during the gesture will otherwise follow the same pattern as that of a gesture starting and ending within the same AIR application.

When a drag gesture leaves an AIR application window, there is no target object to dispatch nativeDragEnter, nativeDragOver, or nativeDragDrop events. The initiator object still dispatches a nativeDragComplete event, which reports the drag action set by the native operating system (or none, if the drop was not accepted).

When a drag gesture moves from one AIR application to another, the initiator and target display objects dispatch events within their separate applications as usual.

Transfering information

The data transfered during a drag-and-drop gesture is contained in a Clipboard object. This data object is added to the drag operation with the NativeDragManager.doDrag() method that starts the drag gesture. Potential drop targets can access the Clipboard object through the clipboard property of the native drag event object. Once a drag operation has started, the Clipboard object can only be accessed in the event handler of a NativeDragEvent. Any other attempt to access the object generates a run-time error.

Security considerations

The security sandboxes of the initiator and potential target objects determine how the the data being dragged can be accessed. If both objects are in the same sandbox, then the data can be accessed from any NativeDragEvent object. However, if the initiator and target objects are in different sandboxes, the data can only be accessed in the target sandbox within the event handler for the nativeDragDrop event. Other native drag event handlers can still still access the Clipboard object referenced in the event clipboard property to determine which data formats are available, but calling the clipboard.getData() method generates a security error.

acceptDragDrop Informs the NativeDragManager object that the specified target interactive object can accept a drop corresponding to the current drag event.targetflash.display:InteractiveObject Informs the NativeDragManager object that the specified target interactive object can accept a drop corresponding to the current drag event.

This method should be called only when there is a nativeDragDrop handler on the specified target object that can handle at least one of the data formats in the dragged item and at least one of the allowed actions.

This function can be called only within a nativeDragEnter or nativeDragOver event handler.

doDrag Starts a drag-and-drop operation.dragInitiatorflash.display:InteractiveObjectTypically the object from which the drag gesture began. Receives the nativeDragStart and nativeDragComplete events. clipboardflash.desktop:ClipboardThe container object for data being dragged. dragImageflash.display:BitmapDatanullAn optional proxy image displayed under the mouse pointer during the drag gesture. If null, no image is displayed. offsetflash.geom:PointnullThe offset between the mouse hotspot and the top left corner of the drag image. Negative coordinates move the image up and to the left in relation to the hotspot. If null, the top left corner of the drag image is positioned at the mouse hotspot. allowedActionsflash.desktop:NativeDragOptionsnullRestricts the drag-and-drop actions allowed for this operation. If null, all actions are allowed. Starts a drag-and-drop operation.

To start a drag operation:

Create a new Clipboard object.
Add the data to be transferred in one or more formats.
Optionally, create a BitmapData object to serve as a proxy image during the drag.
Optionally, create a NativeDragOptions object to restrict the actions allowed in this operation. (If the allowedActions parameter is left null, all actions are allowed.)
Call NativeDragManager.doDrag().

The initiator object dispatches a nativeDragStart event after this method is called, nativeDragStart events while the drag is in progress, and a nativeDragComplete event when the user releases the mouse button to end the drag gesture. The handler for the nativeDragComplete event can check the dropAction property of the event to determine whether the drag-and-drop operation was successfully completed. If dropAction is NativeDragActions.NONE, then the dragged item was not dropped on an eligible target.

This method can be called only from within a mouseDown or mouseMove event handler. (If called in response to a mouseMove event, the mouse button must also be down.)

dragInitiator The interactive object passed to the NativeDragManager.doDrag() call that initiated the drag operation.flash.display:InteractiveObject The interactive object passed to the NativeDragManager.doDrag() call that initiated the drag operation. dropAction The drag action specified by the drop target.String The drag action specified by the drop target.

The dropAction property should be set in the handler for the nativeDragDrop event. If dropAction is not set before the nativeDragComplete, the NativeDragManager sets the value with the first allowed action from the list: copy, move, or link (in that order).

isDragging Reports whether a drag operation is currently in progress.Boolean Reports whether a drag operation is currently in progress. isSupported The isSupported property is set to true if the NativeDragManager class is supported on the current platform, otherwise it is set to false.BooleanReports whether native drag-and-drop operations are supported. The isSupported property is set to true if the NativeDragManager class is supported on the current platform, otherwise it is set to false. NativeDragOptions The NativeDragOptions class defines constants for the names of drag-and-drop actions allowed in a drag-and-drop operation.Object The NativeDragOptions class defines constants for the names of drag-and-drop actions allowed in a drag-and-drop operation.

Drag actions are part of a feedback mechanism to allow the initiating and target objects to cooperate in the drag-and-drop exchange. The actions are only a hint to the operating system. It is up to the drag initiator and target objects involved in the transaction to implement the proper behavior.

An initiating object should only allow the actions that it supports. For example, an initiating object should allow the move action only if that object's internal logic removes the source data when a target accepts a drop with a move action.

A new NativeDragOptions object has all properties initialized to true (all actions allowed).

toString Constructs a string containing the current settings of this NativeDragOptions object.String The current settings of this object in a string. String Constructs a string containing the current settings of this NativeDragOptions object. allowCopy A drop target is allowed to copy the dragged data.trueBoolean A drop target is allowed to copy the dragged data. allowLink A drop target is allowed to create a link to the dragged data.trueBoolean A drop target is allowed to create a link to the dragged data. allowMove A drop target is allowed to move the dragged data.trueBoolean A drop target is allowed to move the dragged data. DockIcon The DockIcon class represents the Mac OS X®-style dock icon.The Mac OS X-style dock icon. flash.desktop:InteractiveIcon The DockIcon class represents the Mac OS X^®-style dock icon.

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

You can use the DockIcon class to change the appearance of the standard icon; for example, to animate the icon or add informational graphics. You can also add items to the dock icon menu. The menu items that you add are displayed above the standard menu items.

An instance of the DockIcon class cannot be created. Get the object representing the operating system dock icon from NativeApplication.icon.

Not all operating systems have dock icons. Check NativeApplication.supportsDockIcon to determine whether dock icons are supported on the current system. If dock icons are supported, the NativeApplication.icon property is of type DockIcon. Otherwise, the type of NativeApplication.icon is another subclass of InteractiveIcon, typically SystemTrayIcon.

Important: Attempting to call a DockIcon class method on the NativeApplication.icon object on an operating system for which AIR does not support dock icons generates a run-time exception.

The following example loads a sequence of images and, when the timer is started with the dock icon menu, animates the icon image. (For the example to work, you must supply a set of icon images and change the URLs in the imageURLs array.) package { import flash.desktop.DockIcon; import flash.desktop.NativeApplication; import flash.display.Loader; import flash.display.NativeMenu; import flash.display.NativeMenuItem; import flash.display.Sprite; import flash.events.Event; import flash.events.TimerEvent; import flash.net.URLRequest; import flash.utils.Timer; public class AnimatedDockIcon extends Sprite { private var imageURLs:Array = ['gfx/frame01.png', 'gfx/frame02.png', 'gfx/frame03.png', 'gfx/frame04.png']; private var images:Array = new Array(); private var animTimer:Timer = new Timer(100); public function AnimatedDockIcon() { NativeApplication.nativeApplication.autoExit = false; addEventListener(Event.COMPLETE, loadImages); loadImages(); animTimer.addEventListener(TimerEvent.TIMER,advanceFrame); addMenu(); stage.nativeWindow.close(); } private function addMenu():void{ var menu:NativeMenu = new NativeMenu(); var start:NativeMenuItem = menu.addItem(new NativeMenuItem("Start animation")); var stop:NativeMenuItem = menu.addItem(new NativeMenuItem("Stop animation")); start.addEventListener(Event.SELECT, startTimer); stop.addEventListener(Event.SELECT, stopTimer); var dockIcon:DockIcon = NativeApplication.nativeApplication.icon as DockIcon; dockIcon.menu = menu; } private function startTimer(event:Event):void{ animTimer.start(); } private function stopTimer(event:Event):void{ animTimer.stop(); } private var currentFrame:int = 0; private function advanceFrame(event:Event):void{ if(currentFrame < images.length){ currentFrame++; } else { currentFrame = 0; } NativeApplication.nativeApplication.icon.bitmaps = [images[currentFrame]]; } private function loadImages(event:Event = null):void{ if(event != null){ images.push(event.target.content.bitmapData); } if(imageURLs.length > 0){ var urlString:String = imageURLs.pop(); var loader:Loader = new Loader(); loader.contentLoaderInfo.addEventListener(Event.COMPLETE, loadImages, false, 0, true); loader.load(new URLRequest(urlString)); } else { var complete:Event = new Event(Event.COMPLETE,false,false); dispatchEvent(complete); } } } } bounce Notifies the user that an event has occurred that may require attention.NotificationType.Informational priorityStringinformationalThe urgency with which to bounce the dock. Notifies the user that an event has occurred that may require attention.

Calling this method bounces the dock icon if, and only if, the application is in the background. If the priority is NotificationType.Informational then the icon bounces once. If the priority is NotificationType.Critical then the icon bounces until the application is brought to the foreground.

The following example bounces the dock icon until the user activates the application: import flash.display.DockIcon; import flash.display.NotificationType; import flash.desktop.NativeApplication; if(NativeApplication.supportsDockIcon){ var dockIcon:DockIcon = NativeApplication.nativeApplication.icon As DockIcon; dockIcon.bounce(NotificationType.CRITICAL); } bitmaps The icon image as an array of BitmapData objects of different sizes.ArrayThe icon image as an array of BitmapData objects of different sizes. The icon image as an array of BitmapData objects of different sizes.

In some contexts, the operating system may use a default system icon if nothing has been assigned to the bitmaps property. In other contexts, no icon appears.

To set or change the icon appearance, assign an array of BitmapData objects to the bitmaps property:

icon.bitmaps = new Array(icon16x16.bitmapData, icon128x128.bitmapData);

Modifying the bitmaps array directly has no effect.

To clear the icon image, assign an empty array to the bitmaps property.

height The current display height of the icon in pixels.int The current display height of the icon in pixels.

menu The system-supplied menu of this dock icon.flash.display:NativeMenu The system-supplied menu of this dock icon.

Any items in the menu are displayed above the standard items. The standard items cannot be modified or removed.

The following example adds an item to the dock icon menu: import flash.desktop.NativeApplication; import flash.events.Event; private function createDockIconMenu():void{ if(NativeApplication.supportsDockIcon){ var dockIcon:DockIcon = NativeApplication.nativeApplication.icon as DockIcon; var dockMenu:NativeMenu = new NativeMenu(); var command:NativeMenuItem = dockMenu.addItem(new NativeMenuItem("Command")); command.addEventListener(Event.SELECT, onCommand); dockIcon.menu = dockMenu; } } private function onCommand(event:Event):void{ //do command... } width The current display width of the icon in pixels.int The current display width of the icon in pixels.

Icon The Icon class represents an operating system icon.flash.events:EventDispatcher The Icon class represents an operating system icon.

An Icon object has one property, bitmaps, which is an array of BitmapData objects. Only one image is displayed at a time. The operating system selects the image closest in size to the icon's current display size, scaling if necessary.

bitmaps The icon image as an array of BitmapData objects of different sizes.Array The icon image as an array of BitmapData objects of different sizes.

In some contexts, the operating system may use a default system icon if nothing has been assigned to the bitmaps property. In other contexts, no icon appears.

To set or change the icon appearance, assign an array of BitmapData objects to the bitmaps property:

icon.bitmaps = new Array(icon16x16.bitmapData, icon128x128.bitmapData);

Modifying the bitmaps array directly has no effect.

To clear the icon image, assign an empty array to the bitmaps property.