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 for selection.
  83     *
  84     * @outResult - true if
  85     * @result NS_OK if successful.
  86     */
  87     boolean supportsSelectionClipboard ( ) ;
  88
  89     /**
  90     * Allows clients to determine if the implementation supports the concept of a
  91     * separate clipboard for find search strings.
  92     *
  93     * @result NS_OK if successful.
  94     */
  95     boolean supportsFindClipboard ( ) ;
  96
  97     /**
  98      * Filters the flavors aTransferable can import (see
  99      * `nsITransferable::flavorsTransferableCanImport`) and gets the data for the
 100      * first flavor. That data is set for aTransferable.
 101      *
 102      * @param  aTransferable   The transferable
 103      * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
 104      * @return MozPromise      The returned promise will resolve when the data is ready or reject
 105      *                         if any error occurs.
 106      */
 107     [noscript, notxpcom, nostdcall]
 108     AsyncGetDataPromise asyncGetData(in nsITransferable aTransferable, in long aWhichClipboard);
 109
 110     /**
 111      * Check if there is data on the clipboard matching each of the flavors in the
 112      * given list.
 113      *
 114      * @param  aFlavorList     An array of ASCII strings.
 115      * @param  aWhichClipboard Specifies the clipboard to which this operation applies.
 116      * @return MozPromise      The returned promise will resolve with the list of matched flavors
 117      *                         when the check is completed or reject if any error occurs.
 118      */
 119     [noscript, notxpcom, nostdcall]
 120     AsyncDataFlavorsPromise asyncHasDataMatchingFlavors(in Array<ACString> aFlavorList, in long aWhichClipboard);
 121 };