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(ceaa0047-647f-4b8e-ad1c-aff9fa62aa51)]
  24 interface nsIClipboard : nsISupports
  25 {
  26     const long kSelectionClipboard = 0;
  27     const long kGlobalClipboard = 1;
  28     const long kFindClipboard = 2;
  29     // Used to cache current selection on (nsClipboard) for macOS service menu.
  30     const long kSelectionCache = 3;
  31
  32    /**
  33     * Given a transferable, set the data on the native clipboard
  34     *
  35     * @param  aTransferable The transferable
  36     * @param  anOwner The owner of the transferable
  37     * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
  38     * @result NS_Ok if no errors
  39     */
  40
  41     void setData ( in nsITransferable aTransferable, in nsIClipboardOwner anOwner,
  42                     in long aWhichClipboard ) ;
  43
  44    /**
  45     * Filters the flavors aTransferable can import (see
  46     * `nsITransferable::flavorsTransferableCanImport`) and gets the data for the
  47     * first flavor. That data is set for aTransferable.
  48     *
  49     * @param  aTransferable The transferable
  50     * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
  51     * @result NS_OK if no errors
  52     */
  53
  54     void getData ( in nsITransferable aTransferable, in long aWhichClipboard ) ;
  55
  56    /**
  57     * This empties the clipboard and notifies the clipboard owner.
  58     * This empties the "logical" clipboard. It does not clear the native clipboard.
  59     *
  60     * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
  61     * @result NS_OK if successful.
  62     */
  63
  64     void emptyClipboard ( in long aWhichClipboard ) ;
  65
  66    /**
  67     * This provides a way to give correct UI feedback about, for instance, a paste
  68     * should be allowed. It does _NOT_ actually retreive the data and should be a very
  69     * inexpensive call. All it does is check if there is data on the clipboard matching
  70     * any of the flavors in the given list.
  71     *
  72     * @param  aFlavorList     An array of ASCII strings.
  73     * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
  74     * @outResult - if data is present matching one of
  75     * @result NS_OK if successful.
  76     */
  77     boolean hasDataMatchingFlavors ( in Array<ACString> aFlavorList,
  78                                      in long aWhichClipboard ) ;
  79
  80     /**
  81      * Allows clients to determine if the implementation supports the concept of a
  82      * separate clipboard.
  83      *
  84      * @param aWhichClipboard  Specifies the clipboard to which this operation applies.
  85      * @outResult  true if the implementaion supports specific clipboard type.
  86      * @result  NS_OK if successful.
  87      */
  88     [infallible]
  89     boolean isClipboardTypeSupported(in long aWhichClipboard);
  90
  91     /**
  92      * Filters the flavors aTransferable can import (see
  93      * `nsITransferable::flavorsTransferableCanImport`) and gets the data for the
  94      * first flavor. That data is set for aTransferable.
  95      *
  96      * @param  aTransferable   The transferable
  97      * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
  98      * @return MozPromise      The returned promise will resolve when the data is ready or reject
  99      *                         if any error occurs.
 100      */
 101     [noscript, notxpcom, nostdcall]
 102     AsyncGetDataPromise asyncGetData(in nsITransferable aTransferable, in long aWhichClipboard);
 103
 104     /**
 105      * Check if there is data on the clipboard matching each of the flavors in the
 106      * given list.
 107      *
 108      * @param  aFlavorList     An array of ASCII strings.
 109      * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
 110      * @return MozPromise      The returned promise will resolve with the list of matched flavors
 111      *                         when the check is completed or reject if any error occurs.
 112      */
 113     [noscript, notxpcom, nostdcall]
 114     AsyncDataFlavorsPromise asyncHasDataMatchingFlavors(in Array<ACString> aFlavorList, in long aWhichClipboard);
 115 };