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     * @result NS_OK if no errors
 149     */
 150
 151     void getData ( in nsITransferable aTransferable, in long aWhichClipboard ) ;
 152
 153     /**
 154      * Requests getting data asynchronously from the native clipboard. This does
 155      * not actually retreive the data, but returns a nsIAsyncGetClipboardData
 156      * contains current avaiable data formats. If the native clipboard is
 157      * updated, either by us or other application, the existing
 158      * nsIAsyncGetClipboardData becomes invalid.
 159      *
 160      * @param  aFlavorList
 161      *         Specific data formats ('flavors') that can be retrieved from the
 162      *         clipboard.
 163      * @param  aWhichClipboard
 164      *         Specifies the clipboard to which this operation applies.
 165      * @param  aCallback
 166      *         The callback object that will be notified upon completion.
 167      * @result NS_OK if no errors
 168      */
 169     void asyncGetData(in Array<ACString> aFlavorList,
 170                       in long aWhichClipboard,
 171                       in WindowContext aRequestingWindowContext,
 172                       in nsIPrincipal aRequestingPrincipal,
 173                       in nsIAsyncClipboardGetCallback aCallback);
 174
 175    /**
 176     * This empties the clipboard and notifies the clipboard owner.
 177     * This empties the "logical" clipboard. It does not clear the native clipboard.
 178     *
 179     * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
 180     * @result NS_OK if successful.
 181     */
 182
 183     void emptyClipboard ( in long aWhichClipboard ) ;
 184
 185    /**
 186     * This provides a way to give correct UI feedback about, for instance, a paste
 187     * should be allowed. It does _NOT_ actually retreive the data and should be a very
 188     * inexpensive call. All it does is check if there is data on the clipboard matching
 189     * any of the flavors in the given list.
 190     *
 191     * @param  aFlavorList     An array of ASCII strings.
 192     * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
 193     * @outResult - if data is present matching one of
 194     * @result NS_OK if successful.
 195     */
 196     boolean hasDataMatchingFlavors ( in Array<ACString> aFlavorList,
 197                                      in long aWhichClipboard ) ;
 198
 199     /**
 200      * Allows clients to determine if the implementation supports the concept of a
 201      * separate clipboard.
 202      *
 203      * @param aWhichClipboard  Specifies the clipboard to which this operation applies.
 204      * @outResult  true if the implementaion supports specific clipboard type.
 205      * @result  NS_OK if successful.
 206      */
 207     [infallible]
 208     boolean isClipboardTypeSupported(in long aWhichClipboard);
 209 };