1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 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/. */
8 #include
"nsISupports.idl"
9 #include
"nsITransferable.idl"
10 #include
"nsIClipboardOwner.idl"
16 [scriptable
, builtinclass
, uuid(801e2318
-c8fa
-11ed
-afa1
-0242ac120002
)]
17 interface nsIAsyncSetClipboardData
: nsISupports
{
19 * Provide the data for the set request.
21 * @param aTransferable
22 * The transferable contains the data to be written.
23 * @param aOwner [optional]
24 * The owner of the transferable.
26 void setData
(in nsITransferable aTransferable
, [optional] in nsIClipboardOwner aOwner
);
29 * Abort the request to set data.
32 * The reason for the abort, can not be NS_OK.
34 void abort
(in nsresult aReason
);
37 [scriptable
, function
, uuid(78f7c18e
-c8fa
-11ed
-afa1
-0242ac120002
)]
38 interface nsIAsyncClipboardRequestCallback
: nsISupports
41 * Indicates that the clipboard request has either succeeded, been canceled or
45 * The result of the request. NS_OK if successful, or another value
46 * that indicates the reason for failure or cancellation.
48 void onComplete
(in nsresult aResult
);
51 [scriptable
, builtinclass
, uuid(c18ea2f7
-6b6f
-4a38
-9ab3
-a8781fdfcc39
)]
52 interface nsIAsyncGetClipboardData
: nsISupports
{
54 * Determines whether this request is still valid (e.g., the clipboard content
55 * associated with this request is not stale).
57 readonly attribute
boolean valid
;
60 * The available flavors in the clipboard.
62 readonly attribute Array
<ACString
> flavorList
;
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`.
71 * @param aTransferable
72 * The transferable which contains the flavors to be read.
74 * The nsIAsyncClipboardRequestCallback to be invoked once the get
75 * request is either successfully completed or rejected.
76 * @result NS_OK if no errors
78 void getData
(in nsITransferable aTransferable
,
79 in nsIAsyncClipboardRequestCallback aCallback
);
82 [scriptable
, uuid(ce23c1c4
-58fd
-4c33
-8579-fa0796d9652c
)]
83 interface nsIAsyncClipboardGetCallback
: nsISupports
86 * Indicates that the clipboard get request has succeeded.
88 void onSuccess
(in nsIAsyncGetClipboardData aAsyncGetClipboardData
);
91 * Indicates that the clipboard get request has rejected.
94 * The reason for the rejection, can not be NS_OK.
96 void onError
(in nsresult aResult
);
99 [scriptable
, builtinclass
, uuid(ceaa0047
-647f
-4b8e
-ad1c
-aff9fa62aa51
)]
100 interface nsIClipboard
: nsISupports
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;
109 static
const uint32_t kClipboardTypeCount
= kSelectionCache
+ 1;
113 * Given a transferable, set the data on the native clipboard
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 * @param aSettingWindowContext [optional]
119 * The window context that is setting the clipboard, if any. This is used
120 * to possibly bypass Content Analysis if a set clipboard and get clipboard
121 * operation are done on the same page.
122 * @result NS_OK if no errors
125 void setData
(in nsITransferable aTransferable
, in nsIClipboardOwner anOwner
,
126 in long aWhichClipboard
, [optional] in WindowContext aSettingWindowContext
);
129 * Requests setting data to the native clipboard. The actual set occurs
130 * when the data is provided by calling nsIAsyncSetClipboardData::setData().
131 * The result will be notified by nsIClipboardCallback. A new set request
132 * will cancel any prior pending requests, if any exist.
134 * @param aWhichClipboard
135 * Specifies the clipboard to which this operation applies.
136 * @param aSettingWindowContext [optional]
137 * The window context that is setting the clipboard, if any. This is used
138 * to possibly bypass Content Analysis if a set clipboard and get clipboard
139 * operation are done on the same page.
140 * @param aCallback [optional]
141 * The callback object that will be notified upon completion.
142 * @return nsIAsyncSetClipboardData
143 * The write request object. The actual write will occur when the
144 * data is provided by calling nsIAsyncSetClipboardData::setData().
146 nsIAsyncSetClipboardData asyncSetData
(in long aWhichClipboard
,
147 [optional] in WindowContext aSettingWindowContext
,
148 [optional] in nsIAsyncClipboardRequestCallback aCallback
);
151 * Filters the flavors aTransferable can import (see
152 * `nsITransferable::flavorsTransferableCanImport`) and gets the data for the
153 * first flavor. That data is set for aTransferable.
155 * @param aTransferable The transferable
156 * @param aWhichClipboard Specifies the clipboard to which this operation applies.
157 * @param aRequestingWindowContext [optional]
158 * The window context window that is requesting the clipboard, which is
159 * used for content analysis. Passing null means that the content is
160 * exempt from content analysis. (for example, scripted clipboard read by
161 * system code) This parameter should not be null when calling this from a
163 * @result NS_OK if no errors
166 void getData
( in nsITransferable aTransferable
, in long aWhichClipboard
, [optional] in WindowContext aRequestingWindowContext
) ;
169 * Requests getting data asynchronously from the native clipboard. This does
170 * not actually retrieve the data, but returns a nsIAsyncGetClipboardData
171 * contains current avaiable data formats. If the native clipboard is
172 * updated, either by us or other application, the existing
173 * nsIAsyncGetClipboardData becomes invalid.
176 * Specific data formats ('flavors') that can be retrieved from the
178 * @param aWhichClipboard
179 * Specifies the clipboard to which this operation applies.
181 * The callback object that will be notified upon completion.
182 * @result NS_OK if no errors
184 void asyncGetData
(in Array
<ACString
> aFlavorList
,
185 in long aWhichClipboard
,
186 in WindowContext aRequestingWindowContext
,
187 in nsIPrincipal aRequestingPrincipal
,
188 in nsIAsyncClipboardGetCallback aCallback
);
191 * Requests getting data from the native clipboard. This does not actually
192 * retreive the data, but returns a nsIAsyncGetClipboardData contains
193 * current avaiable data formats. If the native clipboard is updated, either
194 * by us or other application, the existing nsIAsyncGetClipboardData becomes
198 * Specific data formats ('flavors') that can be retrieved from the
200 * @param aWhichClipboard
201 * Specifies the clipboard to which this operation applies.
202 * @param aRequestingWindowContext [optional]
203 * The window context window that is requesting the clipboard, which is
204 * used for content analysis. Passing null means that the content is
205 * exempt from content analysis. (for example, scripted clipboard read by
206 * system code) This parameter should not be null when calling this from a
208 * @return nsIAsyncSetClipboardData if successful.
209 * @throws if the request can not be made.
211 nsIAsyncGetClipboardData getDataSnapshotSync
(in Array
<ACString
> aFlavorList
,
212 in long aWhichClipboard
,
213 [optional] in WindowContext aRequestingWindowContext
);
216 * This empties the clipboard and notifies the clipboard owner.
217 * This empties the "logical" clipboard. It does not clear the native clipboard.
219 * @param aWhichClipboard Specifies the clipboard to which this operation applies.
220 * @result NS_OK if successful.
223 void emptyClipboard
( in long aWhichClipboard
) ;
226 * This provides a way to give correct UI feedback about, for instance, a paste
227 * should be allowed. It does _NOT_ actually retreive the data and should be a very
228 * inexpensive call. All it does is check if there is data on the clipboard matching
229 * any of the flavors in the given list.
231 * @param aFlavorList An array of ASCII strings.
232 * @param aWhichClipboard Specifies the clipboard to which this operation applies.
233 * @outResult - if data is present matching one of
234 * @result NS_OK if successful.
236 boolean hasDataMatchingFlavors
( in Array
<ACString
> aFlavorList
,
237 in long aWhichClipboard
) ;
240 * Allows clients to determine if the implementation supports the concept of a
241 * separate clipboard.
243 * @param aWhichClipboard Specifies the clipboard to which this operation applies.
244 * @outResult true if the implementaion supports specific clipboard type.
245 * @result NS_OK if successful.
248 boolean isClipboardTypeSupported
(in long aWhichClipboard
);