widget/nsIClipboard.idl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7
   8 #include "nsISupports.idl"
   9 #include "nsITransferable.idl"
  10 #include "nsIClipboardOwner.idl"
  11
  12 %{C++
  13 #include "mozilla/MozPromise.h"
  14
  15 using DataFlavorsPromise = mozilla::MozPromise<nsTArray<nsCString>, nsresult, true>;
  16 %}
  17
  18 interface nsIArray;
  19
  20 native AsyncGetDataPromise(RefPtr<mozilla::GenericPromise>);
  21 native AsyncDataFlavorsPromise(RefPtr<DataFlavorsPromise>);
  22
  23 [scriptable, builtinclass, uuid(801e2318-c8fa-11ed-afa1-0242ac120002)]
  24 interface nsIAsyncSetClipboardData : nsISupports {
  25   /**
  26    * Provide the data for the set request.
  27    *
  28    * @param  aTransferable
  29    *         The transferable contains the data to be written.
  30    * @param  aOwner [optional]
  31    *         The owner of the transferable.
  32    */
  33   void setData(in nsITransferable aTransferable, [optional] in nsIClipboardOwner aOwner);
  34
  35   /**
  36    * Abort the request to set data.
  37    *
  38    * @param  aReason
  39    *         The reason for the abort, can not be NS_OK.
  40    */
  41   void abort(in nsresult aReason);
  42 };
  43
  44 [scriptable, uuid(78f7c18e-c8fa-11ed-afa1-0242ac120002)]
  45 interface nsIAsyncSetClipboardDataCallback : nsISupports
  46 {
  47   /**
  48    * Indicates that the clipboard asyncSetData request has either succeeded or
  49    * been canceled.
  50    *
  51    * @param  aResult
  52    *         The result of the request. NS_OK if successful, or another value
  53    *         that indicates the reason for failure or cancellation.
  54    */
  55   void onComplete(in nsresult aResult);
  56 };
  57
  58 [scriptable, builtinclass, uuid(ceaa0047-647f-4b8e-ad1c-aff9fa62aa51)]
  59 interface nsIClipboard : nsISupports
  60 {
  61     const long kSelectionClipboard = 0;
  62     const long kGlobalClipboard = 1;
  63     const long kFindClipboard = 2;
  64     // Used to cache current selection on (nsClipboard) for macOS service menu.
  65     const long kSelectionCache = 3;
  66
  67 %{ C++
  68     static const uint32_t kClipboardTypeCount = kSelectionCache + 1;
  69 %}
  70
  71    /**
  72     * Given a transferable, set the data on the native clipboard
  73     *
  74     * @param  aTransferable The transferable
  75     * @param  anOwner The owner of the transferable
  76     * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
  77     * @result NS_Ok if no errors
  78     */
  79
  80     void setData ( in nsITransferable aTransferable, in nsIClipboardOwner anOwner,
  81                     in long aWhichClipboard ) ;
  82
  83     /**
  84      * Requests setting data to the native clipboard. The acutal set occur
  85      * when the data is provided by calling nsIAsyncSetClipboardData::setData().
  86      * The result will be notified by nsIClipboardCallback. A new set request
  87      * will cancel any prior pending requests, if any exist.
  88      *
  89      * @param  aWhichClipboard
  90      *         Specifies the clipboard to which this operation applies.
  91      * @param  aCallback [optional]
  92      *         The callback object that will be notified upon completion.
  93      * @return nsIAsyncSetClipboardData
  94      *         The write request object. The actual write will occur when the
  95      *         data is provided by calling nsIAsyncSetClipboardData::setData().
  96      */
  97     nsIAsyncSetClipboardData asyncSetData(in long aWhichClipboard,
  98                                           [optional] in nsIAsyncSetClipboardDataCallback aCallback);
  99
 100    /**
 101     * Filters the flavors aTransferable can import (see
 102     * `nsITransferable::flavorsTransferableCanImport`) and gets the data for the
 103     * first flavor. That data is set for aTransferable.
 104     *
 105     * @param  aTransferable The transferable
 106     * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
 107     * @result NS_OK if no errors
 108     */
 109
 110     void getData ( in nsITransferable aTransferable, in long aWhichClipboard ) ;
 111
 112    /**
 113     * This empties the clipboard and notifies the clipboard owner.
 114     * This empties the "logical" clipboard. It does not clear the native clipboard.
 115     *
 116     * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
 117     * @result NS_OK if successful.
 118     */
 119
 120     void emptyClipboard ( in long aWhichClipboard ) ;
 121
 122    /**
 123     * This provides a way to give correct UI feedback about, for instance, a paste
 124     * should be allowed. It does _NOT_ actually retreive the data and should be a very
 125     * inexpensive call. All it does is check if there is data on the clipboard matching
 126     * any of the flavors in the given list.
 127     *
 128     * @param  aFlavorList     An array of ASCII strings.
 129     * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
 130     * @outResult - if data is present matching one of
 131     * @result NS_OK if successful.
 132     */
 133     boolean hasDataMatchingFlavors ( in Array<ACString> aFlavorList,
 134                                      in long aWhichClipboard ) ;
 135
 136     /**
 137      * Allows clients to determine if the implementation supports the concept of a
 138      * separate clipboard.
 139      *
 140      * @param aWhichClipboard  Specifies the clipboard to which this operation applies.
 141      * @outResult  true if the implementaion supports specific clipboard type.
 142      * @result  NS_OK if successful.
 143      */
 144     [infallible]
 145     boolean isClipboardTypeSupported(in long aWhichClipboard);
 146
 147     /**
 148      * Filters the flavors aTransferable can import (see
 149      * `nsITransferable::flavorsTransferableCanImport`) and gets the data for the
 150      * first flavor. That data is set for aTransferable.
 151      *
 152      * @param  aTransferable   The transferable
 153      * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
 154      * @return MozPromise      The returned promise will resolve when the data is ready or reject
 155      *                         if any error occurs.
 156      */
 157     [noscript, notxpcom, nostdcall]
 158     AsyncGetDataPromise asyncGetData(in nsITransferable aTransferable, in long aWhichClipboard);
 159
 160     /**
 161      * Check if there is data on the clipboard matching each of the flavors in the
 162      * given list.
 163      *
 164      * @param  aFlavorList     An array of ASCII strings.
 165      * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
 166      * @return MozPromise      The returned promise will resolve with the list of matched flavors
 167      *                         when the check is completed or reject if any error occurs.
 168      */
 169     [noscript, notxpcom, nostdcall]
 170     AsyncDataFlavorsPromise asyncHasDataMatchingFlavors(in Array<ACString> aFlavorList, in long aWhichClipboard);
 171 };