Skip to content

Commit

Permalink
New terminology: ClipboardItem entry as data type → value.
Browse files Browse the repository at this point in the history
Right now, the spec refers to two things as "items":

- A list of `ClipboardItem`s.
- The individual data values inside a single `ClipboardItem`.

This is rather confusing, so this PR proposes to rename the latter to
"entries", where an entry conceptually corresponds to a data type (e.g.
`"text/string"`) that maps to a value (e.g. a Blob). This:

- Matches the JS naming convention (think of `Object.entries`).
- Does not change any spec semantics, only the names of some identifiers.

In addition, this PR also renames:

- `ClipboardItemDataType` → `ClipboardItemValue`, and
- `ClipboardItemData` → `ClipboardItemValuePromise`.

This matches the "entry is a type type mapping to a value" convention,
and makes it clear what is a Promise. The previous names may have caused
a semantic typo (w3c#126).
  • Loading branch information
lgarron committed Jun 25, 2020
1 parent b56441b commit 4d7c705
Showing 1 changed file with 14 additions and 14 deletions.
28 changes: 14 additions & 14 deletions index.bs
Original file line number Diff line number Diff line change
Expand Up @@ -589,16 +589,16 @@ urlPrefix: https://w3c.github.io/FileAPI/#dfn-; type: dfn;
Promise<void> writeText(DOMString data);
};

typedef (DOMString or Blob) ClipboardItemDataType;
typedef Promise<ClipboardItemDataType> ClipboardItemData;
typedef (DOMString or Blob) ClipboardItemValue;
typedef Promise<ClipboardItemValue> ClipboardEntryValuePromise;

callback ClipboardItemDelayedCallback = ClipboardItemData ();
callback ClipboardItemDelayedCallback = ClipboardEntryValuePromise ();

[Exposed=Window] interface ClipboardItem {
constructor(record<DOMString, ClipboardItemData> items,
constructor(record<DOMString, ClipboardEntryValue> entries,
optional ClipboardItemOptions options = {});
static ClipboardItem createDelayed(
record<DOMString, ClipboardItemDelayedCallback> items,
record<DOMString, ClipboardEntryDelayedCallback> entries,
optional ClipboardItemOptions options = {});

readonly attribute PresentationStyle presentationStyle;
Expand Down Expand Up @@ -820,7 +820,7 @@ urlPrefix: https://w3c.github.io/FileAPI/#dfn-; type: dfn;
1. Else, if the event was canceled, then

1. Call the [=write content to the clipboard=] algorithm,
passing on the {{DataTransferItemList}} list <em>items</em>,
passing on the {{DataTransferItemList}} list <em>entries</em>,
a <em>clear-was-called</em> flag and a <em>types-to-clear</em>
list.

Expand Down Expand Up @@ -869,7 +869,7 @@ urlPrefix: https://w3c.github.io/FileAPI/#dfn-; type: dfn;
1. Else, if the event was canceled, then

1. Call the [=write content to the clipboard=] algorithm,
passing on the {{DataTransferItemList}} list <em>items</em>,
passing on the {{DataTransferItemList}} list <em>entries</em>,
a <em>clear-was-called</em> flag and a <em>types-to-clear</em>
list.

Expand Down Expand Up @@ -1159,7 +1159,7 @@ urlPrefix: https://w3c.github.io/FileAPI/#dfn-; type: dfn;
files. For example, if the data contains
&lt;img src="file://localhost/example.jpg"&gt;
but the data's origin is an online resource, the implementation must not
add an entry for example.jpg to the clipboardData.items list.
add an entry for example.jpg to the clipboardData.entries list.

<h3 id="image-transcode">Transcoding images</h3>

Expand Down Expand Up @@ -1302,14 +1302,14 @@ urlPrefix: https://w3c.github.io/FileAPI/#dfn-; type: dfn;
<h3 id="to-write-content-to-clipboard"><dfn>write content to the clipboard</dfn></h3>

: Input
:: |items|, a {{DataTransferItemList}} list of items to write
:: |entries|, a {{DataTransferItemList}} list of entries to write
:: |clear-was-called|, a boolean
:: |types-to-clear|, a list

: Output
:: None

1. If the |items| list is not empty, then
1. If the |entries| list is not empty, then

1. Clear the clipboard

Expand Down Expand Up @@ -1346,10 +1346,10 @@ urlPrefix: https://w3c.github.io/FileAPI/#dfn-; type: dfn;
<a>setData()</a>'s type argument, sticking to the
[=mandatory data types=] is strongly recommended.

1. Else, the |items| list is empty. Follow these steps to determine
1. Else, the |entries| list is empty. Follow these steps to determine
whether to clear the clipboard:

1. If the list of items is empty and the |clear-was-called|
1. If the list of entries is empty and the |clear-was-called|
flag is <i>true</i>, then

1. If the |types-to-clear| list is empty, then
Expand Down Expand Up @@ -1508,7 +1508,7 @@ urlPrefix: https://w3c.github.io/FileAPI/#dfn-; type: dfn;
argument is given, add the argument to the
|types-to-clear| list.

1. If a script calls <a>setData()</a> or modifies items and the
1. If a script calls <a>setData()</a> or modifies entries and the
|clear-was-called| flag is true, then

1. If the |types-to-clear| list is empty, then
Expand All @@ -1522,7 +1522,7 @@ urlPrefix: https://w3c.github.io/FileAPI/#dfn-; type: dfn;
1. Remove it from the list. If the list is now empty,
set the |clear-was-called| flag to false.

1. If a script calls <a>getData()</a> or accesses items in the
1. If a script calls <a>getData()</a> or accesses entries in the
{{DataTransferItemList}} and |clipboard-entry| is
set, then

Expand Down

0 comments on commit 4d7c705

Please sign in to comment.