package openfl.desktop; #if (display || !flash)


import openfl.utils.Object;

@:jsRequire("openfl/desktop/Clipboard", "default")


/**
 * The Clipboard class provides a container for transferring data and objects
 * through the clipboard. The operating system clipboard can be accessed
 * through the static <code>generalClipboard</code> property.
 *
 * <p>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 <code>setData()</code> or
 * <code>setDataHandler()</code> method.</p>
 *
 * <p>The standard formats are:</p>
 *
 * <ul>
 *   <li>BITMAP_FORMAT: a BitmapData object (AIR only)</li>
 *   <li>FILE_LIST_FORMAT: an array of File objects (AIR only)</li>
 *   <li>HTML_FORMAT: HTML-formatted string data</li>
 *   <li>TEXT_FORMAT: string data</li>
 *   <li>RICH_TEXT_FORMAT: a ByteArray containing Rich Text Format data</li>
 *   <li>URL_FORMAT: a URL string (AIR only)</li>
 * </ul>
 *
 * <p>These constants for the names of the standard formats are defined in the
 * ClipboardFormats class.</p>
 *
 * <p>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.</p>
 *
 * <p>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.</p>
 *
 * <p>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
 * <code>setDataHandler()</code> 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.</p>
 *
 * <p><b>Note for AIR applications:</b> 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.</p>
 *
 * <p><b>Note for Flash Player applications:</b> 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). <code>Clipboard.getData()</code> will return
 * the contents of the clipboard only if the InteractiveObject has received
 * and is acting on a paste event. Calling <code>Clipboard.getData()</code>
 * under any other circumstances will be unsuccessful. The same restriction
 * applies in AIR for content outside the application sandbox.</p>
 *
 * <p>On Linux, clipboard data does not persist when an AIR application
 * closes.</p>
 */
extern class Clipboard {



    /**
     * The operating system clipboard.
     *
     * <p>Any data pasted to the system clipboard is available to other
     * applications. This may include insecure remote code running in a web
     * browser.</p>
     *
     * <p><b>Note:</b> 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). <code>Clipboard.getData()</code> will return the
     * contents of the clipboard only if the InteractiveObject has received
     * and is acting on a paste event. Calling
     * <code>Clipboard.getData()</code> under any other circumstances will be
     * unsuccessful. The same restriction applies in AIR for content outside
     * the application sandbox.</p>
     *
     * <p>The <code>generalClipboard</code> object is created automatically.
     * You cannot assign another instance of a Clipboard to this property.
     * Instead, you use the <code>getData()</code> and <code>setData()</code>
     * methods to read and write data to the existing object.</p>
     *
     * <p>You should always clear the clipboard before writing new data to it
     * to ensure that old data in all formats is erased.</p>
     *
     * <p>The <code>generalClipboard</code> object cannot be passed to the AIR
     * NativeDragManager. Create a new Clipboard object for native
     * drag-and-drop operations in an AIR application.</p>
     */
    public static var generalClipboard (default, null):Clipboard;


    /**
     * An array of strings containing the names of the data formats available
     * in this Clipboard object.
     *
     * <p>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.</p>
     */
    public var formats (get, never):Array<ClipboardFormats>;

    @:noCompletion private function get_formats ():Array<ClipboardFormats>;

    public function clear ():Void;
    public function clearData (format:ClipboardFormats):Void;
    public function getData (format:ClipboardFormats, transferMode:ClipboardTransferMode = null):Object;
    public function hasFormat (format:ClipboardFormats):Bool;
    public function setData (format:ClipboardFormats, data:Object, serializable:Bool = true):Bool;
    public function setDataHandler (format:ClipboardFormats, handler:Void->Dynamic, serializable:Bool = true):Bool;


}


#else
typedef Clipboard = flash.desktop.Clipboard;
#end