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 interface nsIArray;
  13
  14 webidl WindowContext;
  15
  16 [scriptable, builtinclass, uuid(801e2318-c8fa-11ed-afa1-0242ac120002)]
  17 interface nsIAsyncSetClipboardData : nsISupports {
  18   /**
  19    * Provide the data for the set request.
  20    *
  21    * @param  aTransferable
  22    *         The transferable contains the data to be written.
  23    * @param  aOwner [optional]
  24    *         The owner of the transferable.
  25    */
  26   void setData(in nsITransferable aTransferable, [optional] in nsIClipboardOwner aOwner);
  27
  28   /**
  29    * Abort the request to set data.
  30    *
  31    * @param  aReason
  32    *         The reason for the abort, can not be NS_OK.
  33    */
  34   void abort(in nsresult aReason);
  35 };
  36
  37 [scriptable, function, uuid(78f7c18e-c8fa-11ed-afa1-0242ac120002)]
  38 interface nsIAsyncClipboardRequestCallback : nsISupports
  39 {
  40   /**
  41    * Indicates that the clipboard request has either succeeded, been canceled or
  42    * rejected.
  43    *
  44    * @param  aResult
  45    *         The result of the request. NS_OK if successful, or another value
  46    *         that indicates the reason for failure or cancellation.
  47    */
  48   void onComplete(in nsresult aResult);
  49 };
  50
  51 [scriptable, builtinclass, uuid(c18ea2f7-6b6f-4a38-9ab3-a8781fdfcc39)]
  52 interface nsIAsyncGetClipboardData : nsISupports {
  53   /**
  54    * Determines whether this request is still valid (e.g., the clipboard content
  55    * associated with this request is not stale).
  56    */
  57   readonly attribute boolean valid;
  58
  59   /**
  60    * The available flavors in the clipboard.
  61    */
  62   readonly attribute Array<ACString> flavorList;
  63
  64   /**
  65    * Filters the flavors that `aTransferable` can import (see
  66    * `nsITransferable::flavorsTransferableCanImport`). Every specified flavors
  67    * must exist in `flavorList`, or the request will be rejected. If the request
  68    * remains valid, it retrieves the data for the first flavor. The data is then
  69    * set for `aTransferable`.
  70    *
  71    * @param  aTransferable
  72    *         The transferable which contains the flavors to be read.
  73    * @param  aCallback
  74    *         The nsIAsyncClipboardRequestCallback to be invoked once the get
  75    *         request is either successfully completed or rejected.
  76    * @result NS_OK if no errors
  77    */
  78   void getData(in nsITransferable aTransferable,
  79                in nsIAsyncClipboardRequestCallback aCallback);
  80 };
  81
  82 [scriptable, uuid(ce23c1c4-58fd-4c33-8579-fa0796d9652c)]
  83 interface nsIAsyncClipboardGetCallback : nsISupports
  84 {
  85   /**
  86    * Indicates that the clipboard get request has succeeded.
  87    */
  88   void onSuccess(in nsIAsyncGetClipboardData aAsyncGetClipboardData);
  89
  90   /**
  91    * Indicates that the clipboard get request has rejected.
  92    *
  93    * @param  aResult
  94    *         The reason for the rejection, can not be NS_OK.
  95    */
  96   void onError(in nsresult aResult);
  97 };
  98
  99 [scriptable, builtinclass, uuid(ceaa0047-647f-4b8e-ad1c-aff9fa62aa51)]
 100 interface nsIClipboard : nsISupports
 101 {
 102     const long kSelectionClipboard = 0;
 103     const long kGlobalClipboard = 1;
 104     const long kFindClipboard = 2;
 105     // Used to cache current selection on (nsClipboard) for macOS service menu.
 106     const long kSelectionCache = 3;
 107
 108 %{ C++
 109     static const uint32_t kClipboardTypeCount = kSelectionCache + 1;
 110 %}
 111
 112    /**
 113     * Given a transferable, set the data on the native clipboard
 114     *
 115     * @param  aTransferable The transferable
 116     * @param  anOwner The owner of the transferable
 117     * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
 118     * @result NS_Ok if no errors
 119     */
 120
 121     void setData ( in nsITransferable aTransferable, in nsIClipboardOwner anOwner,
 122                     in long aWhichClipboard ) ;
 123
 124     /**
 125      * Requests setting data to the native clipboard. The acutal set occur
 126      * when the data is provided by calling nsIAsyncSetClipboardData::setData().
 127      * The result will be notified by nsIClipboardCallback. A new set request
 128      * will cancel any prior pending requests, if any exist.
 129      *
 130      * @param  aWhichClipboard
 131      *         Specifies the clipboard to which this operation applies.
 132      * @param  aCallback [optional]
 133      *         The callback object that will be notified upon completion.
 134      * @return nsIAsyncSetClipboardData
 135      *         The write request object. The actual write will occur when the
 136      *         data is provided by calling nsIAsyncSetClipboardData::setData().
 137      */
 138     nsIAsyncSetClipboardData asyncSetData(in long aWhichClipboard,
 139                                           [optional] in nsIAsyncClipboardRequestCallback aCallback);
 140
 141    /**
 142     * Filters the flavors aTransferable can import (see
 143     * `nsITransferable::flavorsTransferableCanImport`) and gets the data for the
 144     * first flavor. That data is set for aTransferable.
 145     *
 146     * @param  aTransferable The transferable
 147     * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
 148     * @param  aRequestingWindowContext [optional]
 149     *         The window context window that is requesting the clipboard, which is
 150     *         used for content analysis. Passing null means that the content is
 151     *         exempt from content analysis. (for example, scripted clipboard read by
 152     *         system code) This parameter should not be null when calling this from a
 153     *         content process.
 154     * @result NS_OK if no errors
 155     */
 156
 157     void getData ( in nsITransferable aTransferable, in long aWhichClipboard, [optional] in WindowContext aRequestingWindowContext) ;
 158
 159     /**
 160      * Requests getting data asynchronously from the native clipboard. This does
 161      * not actually retrieve the data, but returns a nsIAsyncGetClipboardData
 162      * contains current avaiable data formats. If the native clipboard is
 163      * updated, either by us or other application, the existing
 164      * nsIAsyncGetClipboardData becomes invalid.
 165      *
 166      * @param  aFlavorList
 167      *         Specific data formats ('flavors') that can be retrieved from the
 168      *         clipboard.
 169      * @param  aWhichClipboard
 170      *         Specifies the clipboard to which this operation applies.
 171      * @param  aCallback
 172      *         The callback object that will be notified upon completion.
 173      * @result NS_OK if no errors
 174      */
 175     void asyncGetData(in Array<ACString> aFlavorList,
 176                       in long aWhichClipboard,
 177                       in WindowContext aRequestingWindowContext,
 178                       in nsIPrincipal aRequestingPrincipal,
 179                       in nsIAsyncClipboardGetCallback aCallback);
 180
 181     /**
 182      * Requests getting data from the native clipboard. This does not actually
 183      * retreive the data, but returns a nsIAsyncGetClipboardData contains
 184      * current avaiable data formats. If the native clipboard is updated, either
 185      * by us or other application, the existing nsIAsyncGetClipboardData becomes
 186      * invalid.
 187      *
 188      * @param  aFlavorList
 189      *         Specific data formats ('flavors') that can be retrieved from the
 190      *         clipboard.
 191      * @param  aWhichClipboard
 192      *         Specifies the clipboard to which this operation applies.
 193      * @param  aRequestingWindowContext [optional]
 194      *         The window context window that is requesting the clipboard, which is
 195      *         used for content analysis. Passing null means that the content is
 196      *         exempt from content analysis. (for example, scripted clipboard read by
 197      *         system code) This parameter should not be null when calling this from a
 198      *         content process.
 199      * @return nsIAsyncSetClipboardData if successful.
 200      * @throws if the request can not be made.
 201      */
 202     nsIAsyncGetClipboardData getDataSnapshotSync(in Array<ACString> aFlavorList,
 203                                                  in long aWhichClipboard,
 204                                                  [optional] in WindowContext aRequestingWindowContext);
 205
 206    /**
 207     * This empties the clipboard and notifies the clipboard owner.
 208     * This empties the "logical" clipboard. It does not clear the native clipboard.
 209     *
 210     * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
 211     * @result NS_OK if successful.
 212     */
 213
 214     void emptyClipboard ( in long aWhichClipboard ) ;
 215
 216    /**
 217     * This provides a way to give correct UI feedback about, for instance, a paste
 218     * should be allowed. It does _NOT_ actually retreive the data and should be a very
 219     * inexpensive call. All it does is check if there is data on the clipboard matching
 220     * any of the flavors in the given list.
 221     *
 222     * @param  aFlavorList     An array of ASCII strings.
 223     * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
 224     * @outResult - if data is present matching one of
 225     * @result NS_OK if successful.
 226     */
 227     boolean hasDataMatchingFlavors ( in Array<ACString> aFlavorList,
 228                                      in long aWhichClipboard ) ;
 229
 230     /**
 231      * Allows clients to determine if the implementation supports the concept of a
 232      * separate clipboard.
 233      *
 234      * @param aWhichClipboard  Specifies the clipboard to which this operation applies.
 235      * @outResult  true if the implementaion supports specific clipboard type.
 236      * @result  NS_OK if successful.
 237      */
 238     [infallible]
 239     boolean isClipboardTypeSupported(in long aWhichClipboard);
 240 };