-
Notifications
You must be signed in to change notification settings - Fork 7
/
Copy pathindex.html
237 lines (232 loc) · 9.14 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>EyeDropper API</title>
<script src="https://www.w3.org/Tools/respec/respec-w3c" class="remove"></script>
<script class='remove'>
var respecConfig = {
specStatus: "CG-DRAFT",
shortName: "eyedropper-api",
editors: [{
name: "Ionel Popescu",
mailto: "iopopesc@microsoft.com",
company: "Microsoft Corporation",
companyURL: "https://www.microsoft.com/"
}],
group: "wicg",
github: "https://github.com/wicg/eyedropper-api",
xref: "web-platform",
};
</script>
</head>
<body>
<section id="abstract">
<p>
This document describes an API providing access to a browser supplied eyedropper.
</p>
</section>
<section id="sotd"></section>
<section class="informative" id="introduction">
<h2>Introduction</h2>
<p>
Currently on the web, creative application developers are unable to implement an eyedropper,
a tool that allows users to select a color from the pixels on their screen, including the pixels
rendered outside of the web page requesting the color data.
<p>
This API enables authors to use a browser supplied eyedropper in the construction of custom color pickers.
</p>
</p>
</section>
<section id="conformance"></section>
<section>
<h2>API Description</h2>
<section data-dfn-for="ColorSelectionResult">
<h3>ColorSelectionResult dictionary</h3>
<pre class="idl">
dictionary ColorSelectionResult {
DOMString sRGBHex;
};
</pre>
<dl>
<dt><dfn data-dfn-for="ColorSelectionResult">sRGBHex</dfn></dt>
<dd>
must have a value that is a <dfn data-cite="!HTML#valid-simple-colour">valid simple color</dfn>
</dd>
</dl>
</section>
<section data-dfn-for="ColorSelectionOptions">
<h3>ColorSelectionOptions dictionary</h3>
<pre class="idl">
dictionary ColorSelectionOptions {
AbortSignal signal;
};
</pre>
<dl>
<dt><dfn data-dfn-for="ColorSelectionOptions">signal</dfn></dt>
<dd>
allows to abort the {{EyeDropper/open}} operation.
</dd>
</dl>
</section>
<section data-dfn-for="EyeDropper">
<h3>EyeDropper interface</h3>
<pre class="idl">
[Exposed=Window, SecureContext]
interface EyeDropper {
constructor();
Promise<ColorSelectionResult> open(optional ColorSelectionOptions options = {});
};
</pre>
<dl>
<dt><dfn data-dfn-for="EyeDropper">open()</dfn></dt>
<dd>
The method must follow these steps:
<ol>
<li>
If the [=relevant global object=] of [=this=] does not have [=transient
activation=], return [=a new promise=] [=rejected=] with a "{{NotAllowedError}}"
{{DOMException}}.
</li>
<li>
If another eye dropper is already open then return [=a new promise=] [=rejected=] with an "{{InvalidStateError}}"
{{DOMException}}.
</li>
<li>
Let |result| be [=a new promise=].
</li>
<li>
If options.<dfn data-cite="!dom#abortsignal">signal</dfn> is present, then perform the following sub-steps:
<ol>
<li>
If options.[=signal=] is <dfn data-cite="!dom#dom-abortsignal-aborted">aborted</dfn>,
then [=reject=] |result| with options.[=signal=]'s <dfn data-cite="!dom#abortsignal-abort-reason">abort reason</dfn>
and return |result|.
</li>
<li>
<dfn data-cite="!dom#abortsignal-add">Add the following abort steps</dfn> to options.[=signal=]:
<ol>
<li>Exit "eyedropper mode" and dismiss UI.</li>
<li>[=Reject=] |result| with options.[=signal=]'s <a data-cite="!dom#abortsignal-abort-reason">abort reason</a>.</li>
</ol>
</li>
</ol>
</li>
<li>
Place the web page into an "eyedropper mode" where user input is suppressed: no UI events are dispatched to the web page.
</li>
<li>
[=In parallel=]:
<ol>
<li>Let |colorSelectionResult| be the result of the user succesfully selecting a color. If this fails, then:
<ol>
<li>
If the user aborts the selection, [=reject=] |result| with an "{{AbortError}}" {{DOMException}}, otherwise
[=reject=] |result| with an "{{OperationError}}" {{DOMException}}.
</li>
<li>
Abort these steps.
</li>
</ol>
</li>
<li>Exit "eyedropper mode" and dismiss UI.</li>
<li>[=Resolve=] |result| with |colorSelectionResult|.</li>
</ol>
</li>
<li>
Return |result|.
</li>
</ol>
</dd>
</dl>
</section>
</section>
<section>
<h2>EyeDropper</h2>
<p>
To {{EyeDropper/open}} an eyedropper, the user agent MUST present a user interface that follows these rules:
<ul>
<li>
If presenting a user interface fails or accessing screen content fails, then return failure.
</li>
<li>
The UI MUST ensure that it was visible before allowing a color selection.
</li>
<li>
The UI MUST make it clear which color is going to be selected.
</li>
<li>
The UI MUST provide an option to cancel/return without selecting a color.
</li>
</ul>
</p>
</section>
<section class="informative" id="privacy">
<h2>Security and Privacy Considerations</h2>
<p>
Exposing endpoints allowing developers to access unrestricted pixel data from a user's machine presents security challenges.
In particular any eyedropper implementation should not allow a web page to "screen scrape" information the user didn't intend
to share with the web application, for example, while the user moves the mouse around the screen.
<p>
One way to mitigate this threat is to require that pixel data only be made available to the web application when the user takes
some explicit action like pressing a mouse button.
</p>
<p>
Additionally, browsers should provide a clear indication as to when the user has been transitioned into an eyedropper mode,
for example by changing the cursor, and provide the means for the user to exit that mode, for example,
by pressing an ESC key and not allowing the behavior to be cancelled by the author.
</p>
<p>
Before allowing a user to select a color, browsers should ensure that the user had a chance to see the UI. This could be accomplished
by enforcing a minimum time interval between opening the eyedropper and allowing color selection.
</p>
<p>
The transition into eyedropper mode should require consumable user activation, for example, clicking on a button from the web page,
to help avoid unintentionally revealing pixel data.
</p>
</p>
</section>
<section class="informative" id="examples">
<h2>Examples</h2>
<section>
<h3>Platform support</h3>
<aside class="example">
<pre>
<xmp>
if (window.EyeDropper == undefined) {
console.error('EyeDropper API is not supported on this platform');
}
</xmp>
</pre>
</aside>
</section>
<section>
<h3>Selecting a color</h3>
<aside class="example">
<pre>
<xmp>
<button id="eyedropperButton">Open eyedropper</button>
<script>
// Create an EyeDropper object
let eyeDropper = new EyeDropper();
document.getElementById("eyedropperButton").addEventListener('click', e => {
// Enter eyedropper mode
eyeDropper.open()
.then(colorSelectionResult => {
// returns hex color value (#RRGGBB) of the selected pixel
console.log(colorSelectionResult.sRGBHex);
})
.catch(error => {
// handle the user choosing to exit eyedropper mode without a selection
});
});
</script>
</xmp>
</pre>
</aside>
</section>
</section>
<section id="idl-index" class="appendix"></section>
<section id="references" class="appendix"></section>
</body>
</html>