Skip to content

Commit dbd72b2

Browse files
codebytereJohn Kleinschmidt
codebytere
authored and
John Kleinschmidt
committed
docs: improve and add examples for clipboard (electron#20224) (electron#20283)
* docs: improve and add examples for clipboard * address feedback from jkleinsc review
1 parent 10a9e9c commit dbd72b2

File tree

1 file changed

+128
-33
lines changed

1 file changed

+128
-33
lines changed

‎docs/api/clipboard.md

Lines changed: 128 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -4,18 +4,12 @@
44
55
Process: [Main](../glossary.md#main-process), [Renderer](../glossary.md#renderer-process)
66

7-
The following example shows how to write a string to the clipboard:
8-
9-
```javascript
10-
const { clipboard } = require('electron')
11-
clipboard.writeText('Example String')
12-
```
13-
147
On Linux, there is also a `selection` clipboard. To manipulate it
158
you need to pass `selection` to each method:
169

1710
```javascript
1811
const { clipboard } = require('electron')
12+
1913
clipboard.writeText('Example String', 'selection')
2014
console.log(clipboard.readText('selection'))
2115
```
@@ -28,56 +22,106 @@ The `clipboard` module has the following methods:
2822

2923
### `clipboard.readText([type])`
3024

31-
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
25+
* `type` String (optional) - Can be `selection` or `clipboard`; default is 'clipboard'. `selection` is only available on Linux.
3226

3327
Returns `String` - The content in the clipboard as plain text.
3428

29+
```js
30+
const { clipboard } = require('electron')
31+
32+
clipboard.writeText('hello i am a bit of text!')
33+
34+
const text = clipboard.readText()
35+
console.log(text)
36+
// hello i am a bit of text!'
37+
```
38+
3539
### `clipboard.writeText(text[, type])`
3640

3741
* `text` String
38-
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
42+
* `type` String (optional) - Can be `selection` or `clipboard`; default is 'clipboard'. `selection` is only available on Linux.
3943

4044
Writes the `text` into the clipboard as plain text.
4145

46+
```js
47+
const { clipboard } = require('electron')
48+
49+
const text = 'hello i am a bit of text!'
50+
clipboard.writeText(text)
51+
```
52+
4253
### `clipboard.readHTML([type])`
4354

44-
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
55+
* `type` String (optional) - Can be `selection` or `clipboard`; default is 'clipboard'. `selection` is only available on Linux.
4556

4657
Returns `String` - The content in the clipboard as markup.
4758

59+
```js
60+
const { clipboard } = require('electron')
61+
62+
clipboard.writeHTML('<b>Hi</b>')
63+
const html = clipboard.readHTML()
64+
65+
console.log(html)
66+
// <meta charset='utf-8'><b>Hi</b>
67+
```
68+
4869
### `clipboard.writeHTML(markup[, type])`
4970

5071
* `markup` String
51-
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
72+
* `type` String (optional) - Can be `selection` or `clipboard`; default is 'clipboard'. `selection` is only available on Linux.
5273

5374
Writes `markup` to the clipboard.
5475

76+
```js
77+
const { clipboard } = require('electron')
78+
79+
clipboard.writeHTML('<b>Hi</b')
80+
```
81+
5582
### `clipboard.readImage([type])`
5683

57-
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
84+
* `type` String (optional) - Can be `selection` or `clipboard`; default is 'clipboard'. `selection` is only available on Linux.
5885

5986
Returns [`NativeImage`](native-image.md) - The image content in the clipboard.
6087

6188
### `clipboard.writeImage(image[, type])`
6289

6390
* `image` [NativeImage](native-image.md)
64-
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
91+
* `type` String (optional) - Can be `selection` or `clipboard`; default is 'clipboard'. `selection` is only available on Linux.
6592

6693
Writes `image` to the clipboard.
6794

6895
### `clipboard.readRTF([type])`
6996

70-
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
97+
* `type` String (optional) - Can be `selection` or `clipboard`; default is 'clipboard'. `selection` is only available on Linux.
7198

7299
Returns `String` - The content in the clipboard as RTF.
73100

101+
```js
102+
const { clipboard } = require('electron')
103+
104+
clipboard.writeRTF('{\\rtf1\\ansi{\\fonttbl\\f0\\fswiss Helvetica;}\\f0\\pard\nThis is some {\\b bold} text.\\par\n}')
105+
106+
const rtf = clipboard.readRTF()
107+
console.log(rtf)
108+
// {\\rtf1\\ansi{\\fonttbl\\f0\\fswiss Helvetica;}\\f0\\pard\nThis is some {\\b bold} text.\\par\n}
109+
```
110+
74111
### `clipboard.writeRTF(text[, type])`
75112

76113
* `text` String
77-
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
114+
* `type` String (optional) - Can be `selection` or `clipboard`; default is 'clipboard'. `selection` is only available on Linux.
78115

79116
Writes the `text` into the clipboard in RTF.
80117

118+
```js
119+
const { clipboard } = require('electron')
120+
121+
const rtf = '{\\rtf1\\ansi{\\fonttbl\\f0\\fswiss Helvetica;}\\f0\\pard\nThis is some {\\b bold} text.\\par\n}'
122+
clipboard.writeRTF(rtf)
123+
```
124+
81125
### `clipboard.readBookmark()` _macOS_ _Windows_
82126

83127
Returns `Object`:
@@ -93,7 +137,7 @@ bookmark is unavailable.
93137

94138
* `title` String
95139
* `url` String
96-
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
140+
* `type` String (optional) - Can be `selection` or `clipboard`; default is 'clipboard'. `selection` is only available on Linux.
97141

98142
Writes the `title` and `url` into the clipboard as a bookmark.
99143

@@ -102,47 +146,60 @@ you can use `clipboard.write` to write both a bookmark and fallback text to the
102146
clipboard.
103147

104148
```js
105-
clipboard.write({
149+
const { clipboard } = require('electron')
150+
151+
clipboard.writeBookmark({
106152
text: 'https://electronjs.org',
107153
bookmark: 'Electron Homepage'
108154
})
109155
```
110156

111157
### `clipboard.readFindText()` _macOS_
112158

113-
Returns `String` - The text on the find pasteboard. This method uses synchronous
114-
IPC when called from the renderer process. The cached value is reread from the
115-
find pasteboard whenever the application is activated.
159+
Returns `String` - The text on the find pasteboard, which is the pasteboard that holds information about the current state of the active application’s find panel.
160+
161+
This method uses synchronous IPC when called from the renderer process.
162+
The cached value is reread from the find pasteboard whenever the application is activated.
116163

117164
### `clipboard.writeFindText(text)` _macOS_
118165

119166
* `text` String
120167

121-
Writes the `text` into the find pasteboard as plain text. This method uses
122-
synchronous IPC when called from the renderer process.
168+
Writes the `text` into the find pasteboard (the pasteboard that holds information about the current state of the active application’s find panel) as plain text. This method uses synchronous IPC when called from the renderer process.
123169

124170
### `clipboard.clear([type])`
125171

126-
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
172+
* `type` String (optional) - Can be `selection` or `clipboard`; default is 'clipboard'. `selection` is only available on Linux.
127173

128174
Clears the clipboard content.
129175

130176
### `clipboard.availableFormats([type])`
131177

132-
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
178+
* `type` String (optional) - Can be `selection` or `clipboard`; default is 'clipboard'. `selection` is only available on Linux.
133179

134180
Returns `String[]` - An array of supported formats for the clipboard `type`.
135181

182+
```js
183+
const { clipboard } = require('electron')
184+
185+
const formats = clipboard.availableFormats()
186+
console.log(formats)
187+
// [ 'text/plain', 'text/html' ]
188+
```
189+
136190
### `clipboard.has(format[, type])` _Experimental_
137191

138192
* `format` String
139-
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
193+
* `type` String (optional) - Can be `selection` or `clipboard`; default is 'clipboard'. `selection` is only available on Linux.
140194

141195
Returns `Boolean` - Whether the clipboard supports the specified `format`.
142196

143-
```javascript
197+
```js
144198
const { clipboard } = require('electron')
145-
console.log(clipboard.has('<p>selection</p>'))
199+
200+
const hasFormat = clipboard.has('<p>selection</p>')
201+
console.log(hasFormat)
202+
// 'true' or 'false
146203
```
147204

148205
### `clipboard.read(format)` _Experimental_
@@ -157,26 +214,64 @@ Returns `String` - Reads `format` type from the clipboard.
157214

158215
Returns `Buffer` - Reads `format` type from the clipboard.
159216

217+
```js
218+
const { clipboard } = require('electron')
219+
220+
const buffer = Buffer.from('this is binary', 'utf8')
221+
clipboard.writeBuffer('public.utf8-plain-text', buffer)
222+
223+
const ret = clipboard.readBuffer('public.utf8-plain-text')
224+
225+
console.log(buffer.equals(out))
226+
// true
227+
```
228+
160229
### `clipboard.writeBuffer(format, buffer[, type])` _Experimental_
161230

162231
* `format` String
163232
* `buffer` Buffer
164-
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
233+
* `type` String (optional) - Can be `selection` or `clipboard`; default is 'clipboard'. `selection` is only available on Linux.
165234

166235
Writes the `buffer` into the clipboard as `format`.
167236

237+
```js
238+
const { clipboard } = require('electron')
239+
240+
const buffer = Buffer.from('writeBuffer', 'utf8')
241+
clipboard.writeBuffer('public.utf8-plain-text', buffer)
242+
```
243+
168244
### `clipboard.write(data[, type])`
169245

170246
* `data` Object
171247
* `text` String (optional)
172248
* `html` String (optional)
173249
* `image` [NativeImage](native-image.md) (optional)
174250
* `rtf` String (optional)
175-
* `bookmark` String (optional) - The title of the url at `text`.
176-
* `type` String (optional) - Can be `selection` or `clipboard`. `selection` is only available on Linux.
251+
* `bookmark` String (optional) - The title of the URL at `text`.
252+
* `type` String (optional) - Can be `selection` or `clipboard`; default is 'clipboard'. `selection` is only available on Linux.
177253

178-
```javascript
254+
Writes `data` to the clipboard.
255+
256+
```js
179257
const { clipboard } = require('electron')
180-
clipboard.write({ text: 'test', html: '<b>test</b>' })
258+
259+
clipboard.write({
260+
text: 'test',
261+
html: '<b>Hi</b>',
262+
rtf: '{\\rtf1\\utf8 text}',
263+
bookmark: 'a title'
264+
})
265+
266+
console.log(clipboard.readText())
267+
// 'test'
268+
269+
console.log(clipboard.readHTML())
270+
// <meta charset='utf-8'><b>Hi</b>
271+
272+
console.log(clipboard.readRTF())
273+
// '{\\rtf1\\utf8 text}'
274+
275+
console.log(clipboard.readBookmark())
276+
// { title: 'a title', url: 'test' }
181277
```
182-
Writes `data` to the clipboard.

0 commit comments

Comments
 (0)