Source code
Revision control
Copy as Markdown
Other Tools
/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
#include "nsISupports.idl"
#include "nsITransferable.idl"
#include "nsIClipboardOwner.idl"
interface nsIArray;
webidl WindowContext;
[scriptable, builtinclass, uuid(801e2318-c8fa-11ed-afa1-0242ac120002)]
interface nsIAsyncSetClipboardData : nsISupports {
/**
* Provide the data for the set request.
*
* @param aTransferable
* The transferable contains the data to be written.
* @param aOwner [optional]
* The owner of the transferable.
*/
void setData(in nsITransferable aTransferable, [optional] in nsIClipboardOwner aOwner);
/**
* Abort the request to set data.
*
* @param aReason
* The reason for the abort, can not be NS_OK.
*/
void abort(in nsresult aReason);
};
[scriptable, function, uuid(78f7c18e-c8fa-11ed-afa1-0242ac120002)]
interface nsIAsyncClipboardRequestCallback : nsISupports
{
/**
* Indicates that the clipboard request has either succeeded, been canceled or
* rejected.
*
* @param aResult
* The result of the request. NS_OK if successful, or another value
* that indicates the reason for failure or cancellation.
*/
void onComplete(in nsresult aResult);
};
[scriptable, builtinclass, uuid(c18ea2f7-6b6f-4a38-9ab3-a8781fdfcc39)]
interface nsIClipboardDataSnapshot : nsISupports {
/**
* Determines whether this request is still valid (e.g., the clipboard content
* associated with this request is not stale).
*/
readonly attribute boolean valid;
/**
* The available flavors in the clipboard.
*/
readonly attribute Array<ACString> flavorList;
/**
* Filters the flavors that `aTransferable` can import (see
* `nsITransferable::flavorsTransferableCanImport`). Every specified flavors
* must exist in `flavorList`, or the request will be rejected. If the request
* remains valid, it retrieves the data for the first flavor. The data is then
* set for `aTransferable`.
*
* @param aTransferable
* The transferable which contains the flavors to be read.
* @param aCallback
* The nsIAsyncClipboardRequestCallback to be invoked once the get
* request is either successfully completed or rejected.
* @result NS_OK if no errors
*/
void getData(in nsITransferable aTransferable,
in nsIAsyncClipboardRequestCallback aCallback);
};
[scriptable, uuid(ce23c1c4-58fd-4c33-8579-fa0796d9652c)]
interface nsIClipboardGetDataSnapshotCallback : nsISupports
{
/**
* Indicates that the clipboard get request has succeeded.
*/
void onSuccess(in nsIClipboardDataSnapshot aClipboardDataSnapshot);
/**
* Indicates that the clipboard get request has rejected.
*
* @param aResult
* The reason for the rejection, can not be NS_OK.
*/
void onError(in nsresult aResult);
};
[scriptable, builtinclass, uuid(ceaa0047-647f-4b8e-ad1c-aff9fa62aa51)]
interface nsIClipboard : nsISupports
{
cenum ClipboardType : 32 {
kSelectionClipboard = 0,
kGlobalClipboard = 1,
kFindClipboard = 2,
// Used to cache current selection on (nsClipboard) for macOS service menu.
kSelectionCache = 3,
};
%{ C++
static const uint32_t kClipboardTypeCount = kSelectionCache + 1;
%}
/**
* Given a transferable, set the data on the native clipboard
*
* @param aTransferable The transferable
* @param anOwner The owner of the transferable
* @param aWhichClipboard Specifies the clipboard to which this operation applies.
* @param aSettingWindowContext [optional]
* The window context that is setting the clipboard, if any. This is used
* to possibly bypass Content Analysis if a set clipboard and get clipboard
* operation are done on the same page.
* @result NS_OK if no errors
*/
void setData (in nsITransferable aTransferable, in nsIClipboardOwner anOwner,
in nsIClipboard_ClipboardType aWhichClipboard, [optional] in WindowContext aSettingWindowContext);
/**
* Requests setting data to the native clipboard. The actual set occurs
* when the data is provided by calling nsIAsyncSetClipboardData::setData().
* The result will be notified by nsIClipboardCallback. A new set request
* will cancel any prior pending requests, if any exist.
*
* @param aWhichClipboard
* Specifies the clipboard to which this operation applies.
* @param aSettingWindowContext [optional]
* The window context that is setting the clipboard, if any. This is used
* to possibly bypass Content Analysis if a set clipboard and get clipboard
* operation are done on the same page.
* @param aCallback [optional]
* The callback object that will be notified upon completion.
* @return nsIAsyncSetClipboardData
* The write request object. The actual write will occur when the
* data is provided by calling nsIAsyncSetClipboardData::setData().
*/
nsIAsyncSetClipboardData asyncSetData(in nsIClipboard_ClipboardType aWhichClipboard,
[optional] in WindowContext aSettingWindowContext,
[optional] in nsIAsyncClipboardRequestCallback aCallback);
/**
* Filters the flavors aTransferable can import (see
* `nsITransferable::flavorsTransferableCanImport`) and gets the data for the
* first flavor. That data is set for aTransferable.
*
* @param aTransferable The transferable
* @param aWhichClipboard Specifies the clipboard to which this operation applies.
* @param aRequestingWindowContext [optional]
* The window context window that is requesting the clipboard, which is
* used for content analysis. Passing null means that the content is
* exempt from content analysis. (for example, scripted clipboard read by
* system code) This parameter should not be null when calling this from a
* content process.
* @result NS_OK if no errors
*/
void getData ( in nsITransferable aTransferable, in nsIClipboard_ClipboardType aWhichClipboard, [optional] in WindowContext aRequestingWindowContext) ;
/**
* Requests getting data asynchronously from the native clipboard. This does
* not actually retrieve the data, but returns a nsIAsyncGetClipboardData
* contains current avaiable data formats. If the native clipboard is
* updated, either by us or other application, the existing
* nsIAsyncGetClipboardData becomes invalid.
*
* @param aFlavorList
* Specific data formats ('flavors') that can be retrieved from the
* clipboard.
* @param aWhichClipboard
* Specifies the clipboard to which this operation applies.
* @param aCallback
* The callback object that will be notified upon completion.
* @result NS_OK if no errors
*/
void getDataSnapshot(in Array<ACString> aFlavorList,
in nsIClipboard_ClipboardType aWhichClipboard,
in WindowContext aRequestingWindowContext,
in nsIPrincipal aRequestingPrincipal,
in nsIClipboardGetDataSnapshotCallback aCallback);
/**
* Requests getting data from the native clipboard. This does not actually
* retreive the data, but returns a nsIAsyncGetClipboardData contains
* current avaiable data formats. If the native clipboard is updated, either
* by us or other application, the existing nsIAsyncGetClipboardData becomes
* invalid.
*
* @param aFlavorList
* Specific data formats ('flavors') that can be retrieved from the
* clipboard.
* @param aWhichClipboard
* Specifies the clipboard to which this operation applies.
* @param aRequestingWindowContext [optional]
* The window context window that is requesting the clipboard, which is
* used for content analysis. Passing null means that the content is
* exempt from content analysis. (for example, scripted clipboard read by
* system code) This parameter should not be null when calling this from a
* content process.
* @return nsIAsyncSetClipboardData if successful.
* @throws if the request can not be made.
*/
nsIClipboardDataSnapshot getDataSnapshotSync(in Array<ACString> aFlavorList,
in nsIClipboard_ClipboardType aWhichClipboard,
[optional] in WindowContext aRequestingWindowContext);
/**
* This empties the clipboard and notifies the clipboard owner.
* This empties the "logical" clipboard. It does not clear the native clipboard.
*
* @param aWhichClipboard Specifies the clipboard to which this operation applies.
* @result NS_OK if successful.
*/
void emptyClipboard ( in nsIClipboard_ClipboardType aWhichClipboard ) ;
/**
* This provides a way to give correct UI feedback about, for instance, a paste
* should be allowed. It does _NOT_ actually retreive the data and should be a very
* inexpensive call. All it does is check if there is data on the clipboard matching
* any of the flavors in the given list.
*
* @param aFlavorList An array of ASCII strings.
* @param aWhichClipboard Specifies the clipboard to which this operation applies.
* @outResult - if data is present matching one of
* @result NS_OK if successful.
*/
boolean hasDataMatchingFlavors ( in Array<ACString> aFlavorList,
in nsIClipboard_ClipboardType aWhichClipboard ) ;
/**
* Allows clients to determine if the implementation supports the concept of a
* separate clipboard.
*
* @param aWhichClipboard Specifies the clipboard to which this operation applies.
* @outResult true if the implementaion supports specific clipboard type.
* @result NS_OK if successful.
*/
[infallible]
boolean isClipboardTypeSupported(in nsIClipboard_ClipboardType aWhichClipboard);
};