Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: clipboard.getNativeFormat() and clipboard.writeBuffers() #229

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: clipboard.getNativeFormat() and clipboard.writeBuffers() #229

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions wg-api/spec-documents/clipboard-getnativeformat.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# `clipboard.getNativeFormat(portableFormat)`

## Summary
A new `clipboard.getNativeFormat(portableFormat)` API method is introduced. It returns a `String` representing the underlying _native_ clipboard type for the supplied _portable_ format.

## Platforms
macOS, Windows, Linux

## Impetus

Each operating system supported by Electron utilizes a different convention to identify the data format of the clipboard contents: macOS uses [UTIs](https://en.wikipedia.org/wiki/Uniform_Type_Identifier), Linux uses [MIME types](https://en.wikipedia.org/wiki/MIME) and Windows uses [numeric values](https://docs.microsoft.com/en-us/windows/win32/dataxchg/standard-clipboard-formats).

To increase portability, Electron's `clipboard` API exposes read/write access to several high-level _portable_ clipboard formats (via `write()`, `writeText()`, `readImage()` etc). Lower-level access to the _native_ formats is also provided via `Buffer`-based read/write APIs (via `readBuffer()`, `writeBuffer()`)

There's however, no currently available mechanism to query the underlying low-level _native_ format for a given high-level _portable_ format. Applications that want to have `Buffer` access to these formats are therefore required to make use of hardcoded, platform-specific string contants.

The introduction of the [proposed](clipboard-writebuffers.md) `writeBuffers()` API (that allows simultaneous writes to multiple low-level clipboard formats) makes this issue more prominent, since Chromium's underlying `ScopedClipboardWriter` implementation currently disallows simultaneously writing `portable` and `native` formats on the same call.

## API Design

The new API is comprised of a single method:

```markdown
### `clipboard.getNativeFormat(portableFormat)`

* `portableFormat` String - One of the supported native formats: `text`, `bookmark`, `html`, `rtf`, `image`

Returns `String` - An opaque, platform-dependent value representing a clipboard format (e.g. `text/plain`, `public.text` or `13`)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Presumably the only useful application of this value would be to pass it into the new clipboard.writeBuffers (or existing clipboard.writeBuffer) function, yes?

So this would be used like:

clipboard.writeBuffers({
  [clipboard.getNativeFormat('text')]: Buffer.from(...),
  [myCustomFormat[os.platform()]]: Buffer.from(...),
})

That seems a little awkward to me, though I'm not sure I have a better suggestion. Here are some random thoughts, maybe useful, maybe not.

  1. Given that custom formats will also necessarily be platform-specific, how do we expect users of the API to handle those? Should we have some examples to guide best practices?
  2. These values are effectively constants. Should we expose them as such? e.g. clipboard.format.TEXT
  3. Could we use JS Symbols effectively here...? e.g. if clipboard.format.TEXT was a special symbol, that could distinguish it from custom formats while avoiding the collision problem.


If an unsupported portable format is provided, this function will throw an error.
```

## Rollout Plan

This new API would be available at the next major release of Electron. There are no special backporting, backwards compatibility or rollout requirements.
26 changes: 26 additions & 0 deletions wg-api/spec-documents/clipboard-writebuffers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# `clipboard.writeBuffers(buffersObject)`

## Summary

A new `clipboard.writeBuffers(buffersObject)` API method is introduced, tht allows writing multiple low-level `Buffer`-based _native_ formats to the clipboard.

## Platforms
macOS, Windows, Linux

## Impetus

Electron currently provides the `clipboard.write()` API to write multiple high-level _portable_ clipboard formats, but there's currently no similar method to write to multiple low-level _native_ formats: The existing `clipboard.writeBuffer()` API clears the preexisting clipboard contents on each call, due to the behavior of the underlying `ScopedClipboardWriter` Chromium class. Apps that need this functionality currently have to resort to requiring native Node.js modules.

## API Design

The new API is comprised of a single method:

```markdown
### `clipboard.writeBuffers(buffersObject)`

* `buffersObject` Object - An object with `String` keys representing native, platform-dependent clipboard formats and `Buffer` values to be written for each format.
```

## Rollout Plan

This new API would be available at the next major release of Electron. There are no special backporting, backwards compatibility or rollout requirements.