11// Copyright (c) 2024, the Dart project authors. Please see the AUTHORS file
22// for details. All rights reserved. Use of this source code is governed by a
33// BSD-style license that can be found in the LICENSE file.
4+ //
5+ // API docs from [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web).
6+ // Attributions and copyright licensing by Mozilla Contributors is licensed
7+ // under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/.
48
59// Generated from Web IDL definitions.
610
@@ -23,6 +27,12 @@ extension type ClipboardEventInit._(JSObject _) implements EventInit, JSObject {
2327 external set clipboardData (DataTransfer ? value);
2428 external DataTransfer ? get clipboardData;
2529}
30+
31+ /// The **`ClipboardEvent` ** interface of the
32+ /// [Clipboard API] (https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API)
33+ /// represents events providing information related to modification of the
34+ /// clipboard, that is [Element/cut_event] , [Element/copy_event] , and
35+ /// [Element/paste_event] events.
2636extension type ClipboardEvent ._(JSObject _) implements Event , JSObject {
2737 external factory ClipboardEvent (
2838 String type, [
@@ -31,13 +41,29 @@ extension type ClipboardEvent._(JSObject _) implements Event, JSObject {
3141
3242 external DataTransfer ? get clipboardData;
3343}
44+
45+ /// The **`ClipboardItem` ** interface of the
46+ /// [Clipboard API] (https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API)
47+ /// represents a single item format, used when reading or writing clipboard data
48+ /// using [clipboard.read] and [clipboard.write] respectively.
49+ ///
50+ /// The benefit of having the **`ClipboardItem` ** interface to represent data,
51+ /// is that it enables developers to cope with the varying scope of file types
52+ /// and data.
53+ ///
54+ /// > **Note:** To work with text see the [Clipboard.readText] and
55+ /// > [Clipboard.writeText] methods of the [Clipboard] interface.
3456extension type ClipboardItem ._(JSObject _) implements JSObject {
3557 external factory ClipboardItem (
3658 JSObject items, [
3759 ClipboardItemOptions options,
3860 ]);
3961
4062 external static bool supports (String type);
63+
64+ /// The **`getType()` ** method of the [ClipboardItem] interface returns a
65+ /// `Promise` that resolves with a [Blob] of the requested or an error if the
66+ /// MIME type is not found.
4167external JSPromise <Blob > getType (String type);
4268 external PresentationStyle get presentationStyle;
4369 external JSArray <JSString > get types;
@@ -48,11 +74,58 @@ extension type ClipboardItemOptions._(JSObject _) implements JSObject {
4874 external set presentationStyle (PresentationStyle value);
4975 external PresentationStyle get presentationStyle;
5076}
77+
78+ /// The **`Clipboard` ** interface of the
79+ /// [Clipboard API] (https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API)
80+ /// provides read and write access to the contents of the system clipboard.
81+ /// This allows a web application to implement cut, copy, and paste features.
82+ ///
83+ /// The system clipboard is exposed through the global [Navigator.clipboard]
84+ /// property.
85+ ///
86+ /// All of the Clipboard API methods operate asynchronously; they return a
87+ /// `Promise` which is resolved once the clipboard access has been completed.
88+ /// The promise is rejected if clipboard access is denied.
89+ ///
90+ /// All the methods require a
91+ /// [secure context] (https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts).
92+ /// Additional requirements for using the API are discussed in the
93+ /// [Security consideration] (https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API#security_considerations)
94+ /// section of the API overview topic.
5195extension type Clipboard ._(JSObject _) implements EventTarget , JSObject {
96+ /// The **`read()` ** method of the [Clipboard] interface requests a copy of
97+ /// the clipboard's contents, fulfilling the returned `Promise` with the data.
98+ ///
99+ /// The method can in theory return arbitrary data (unlike
100+ /// [Clipboard.readText] , which can only return text).
101+ /// Browsers commonly support reading text, HTML, and PNG image data — see
102+ /// [browser compatibility] (#browser_compatibility) for more information.
52103external JSPromise <ClipboardItems > read (
53104 [ClipboardUnsanitizedFormats formats]);
105+
106+ /// The **`readText()` ** method of the [Clipboard] interface returns a
107+ /// `Promise` which fulfils with a copy of the textual contents of the system
108+ /// clipboard.
109+ ///
110+ /// > **Note:** To read non-text contents from the clipboard, use the
111+ /// > [Clipboard.read] method instead.
112+ /// > You can write text to the clipboard using [Clipboard.writeText] .
54113external JSPromise <JSString > readText ();
114+
115+ /// The **`write()` ** method of the [Clipboard] interface writes arbitrary
116+ /// data to the clipboard, such as images, fulfilling the returned `Promise`
117+ /// on completion.
118+ /// This can be used to implement cut and copy functionality.
119+ ///
120+ /// The method can in theory write arbitrary data (unlike
121+ /// [Clipboard.writeText] , which can only write text).
122+ /// Browsers commonly support writing text, HTML, and PNG image data — see
123+ /// [browser compatibility] (#browser_compatibility) for more information.
55124external JSPromise <JSAny ?> write (ClipboardItems data);
125+
126+ /// The **`writeText()` ** method of the [Clipboard] interface writes the
127+ /// specified text to the system clipboard, returning a `Promise` that is
128+ /// resolved once the system clipboard has been updated.
56129external JSPromise <JSAny ?> writeText (String data);
57130}
58131extension type ClipboardUnsanitizedFormats ._(JSObject _) implements JSObject {
![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4&size=40){kind=avatar}
0 commit comments