Clipboard

Description

The Clipboard class offers a simple mechanism to copy and paste data between applications.

Clipboard features are implemented as a module named clipboard. Use an import statement (from another module) or require() function call (from any code) to import desired features.

import clipboard from "clipboard";
// or
import { text as clipboardText } from "clipboard";

Or using require():

const clipboard = require("clipboard");
// or
const { text: clipboardText } = require("clipboard");

Clipboard data can potentially contain multiple types of data, identified by a MIME (or "media") type. For example copying text from a Web page may put it on the clipboard in both plain-text and HTML formats ("text/plain" and "text/html" MIME types, respectively).

The text(), setText(), data() and setData() function versions with no parameters operate with "text/plain" and "application/octet-stream" default MIME types (as further explained in their documentation). Alternatively, the more explicit function overloads can be used which allow specifying a MIME type.

On MacOS and Linux/X11 systems there are two other "clipboard modes" available besides the primary shared clipbaord.
On X11 this can work with whatever text is currently selected in a focused application (Clipboard.Selection mode).
On MacOS there is a special "search buffer" which can be shared between applications (Clipboard.SearchBuffer mode).
Most of the functions in this class accept an optional mode parameter which sets which clipboard to use. By default the main clipboard is used, and on Windows this is the only clipboard mode available.
See supportsSelection, supportsFindBuffer, and Mode enumeration docs for more details.

Usage examples

Copy text to clipboard

const { setText } = require("clipboard");
setText("This text will be copied to the clipboard");

Get text from clipboard

const { text: clipboardText } = require("clipboard");
let text = clipboardText();
// text == "This text will be copied to the clipboard"

Copy the contents of a text file to the clipboard

const { setText: copy } = require("clipboard");
try {
  copy(File.readText("path/to/myFile.txt"));
}
catch (e) {
  console.error("Error reading file: ", e);
}

Copy an image from a file to the clipboard

const { setData: copy } = require("clipboard");
try {
  copy("image/png", File.read("path/to/myImage.png", 'b'));
}
catch (e) {
  console.error("Error reading file: ", e);
}

Get text from the clipboard, preferring HTML format if it is available.

const clipboard = require("clipboard");
let text = clipboard.hasMimeType("text/html") ? clipboard.text("html") : clipboard.text();

Loop over all available formats on the clipboard and log the contents of each one as a string.

const { mimeTypes, data: clipboardData } = require("clipboard");
const availableTypes = mimeTypes();
for (const type of availableTypes)
  console.log(type + " :", '\n', clipboardData(type).toString());

Public Types
enum class	Mode

Properties
bool	supportsFindBuffer = QGuiApplication::clipboard()->supportsFindBuffer()
bool	supportsSelection = QGuiApplication::clipboard()->supportsSelection()

Public Member Functions
bool	dataAvailable (int mode=Mode.Clipboard)
bool	textAvailable (int mode=Mode.Clipboard)
String	text (int mode=Mode.Clipboard)
String	text (String subType, int mode=Mode.Clipboard)
String	setText (String text, int mode=Mode.Clipboard)
String	setText (String subType, String text, int mode=Mode.Clipboard)
ArrayBuffer	data (int mode=Mode.Clipboard)
ArrayBuffer	data (String mimeType, int mode=Mode.Clipboard)
void	setData (ArrayBuffer data, int mode=Mode.Clipboard)
void	setData (String mimeType, ArrayBuffer data, int mode=Mode.Clipboard)
void	clear (int mode=Mode.Clipboard)
bool	hasMimeType (String mimeType, int mode=Mode.Clipboard)
bool	hasMediaType (String mediaType, int mode=Mode.Clipboard)
Array< String >	mimeTypes (String mimeType, int mode=Mode.Clipboard)
Events
See Event Handling for details about connecting handlers to events. Note** that since Clipboard is a global static object, assigning a handler to any of the event properties (like onclipboardChanged) in one script will replace any handler assigned in another script.
void	clipboardChanged ()
void	findBufferChanged ()
void	selectionChanged ()

Member Enumeration Documentation

Mode

enum class Mode

strong

This enumeration is used in the mode argument of several methods and controls which part of the system clipboard is used.
With Clipboard mode (the deafult for all methods), the data is stored/retrieved with the global clipboard.
If mode is Selection, the data is stored/retrieved with the global mouse selection (requires a supporting system, eg. X11).
If mode is FindBuffer, the data is stored/retrieved with the search string buffer (eg. on MacOS).

See also

supportsFindBuffer, supportsSelection

Enumerator
Clipboard	Indicates that data should be stored and retrieved from the global clipboard.
Selection	Indicates that data should be stored and retrieved from the global mouse selection. Support for Selection is provided only on systems with a global mouse selection (e.g. X11).
FindBuffer	Indicates that data should be stored and retrieved from the Find buffer. This mode is used for holding search strings on macOS.

Property Documentation

supportsFindBuffer

bool supportsFindBuffer = QGuiApplication::clipboard()->supportsFindBuffer()

readwrite

This property value is true if the system clipboard supports a separate search buffer, or false otherwise. This is only supported on MacOS and possibly some Android systems.

supportsSelection

bool supportsSelection = QGuiApplication::clipboard()->supportsSelection()

readwrite

This property value is true if the system clipboard supports mouse selection, or false otherwise. Mouse selection is generally only supported on X11-based systems (Linux, BSD, etc).

Member Function Documentation

clipboardChanged()

void clipboardChanged

(

)

This event is raised whenever the contents of the system clipboard change. Use text(), data(), or the other methods to get the current value after receiving this event.

This event has a corresponding onclipboardChanged property to which a single event handler may be assigned.

findBufferChanged()

void findBufferChanged

(

)

This event is raised whenever the contents of the Find text change on MacOS. Use text(), data(), etc methods with mode argument set to Clipboard.FindBuffer to get the current value after receiving this event.

This event has a corresponding onfindBufferChanged property to which a single event handler may be assigned.

See also

supportsFindBuffer

selectionChanged()

void selectionChanged

(

)

This event is raised whenever the contents of the system selection change. Use text(), data(), etc, methods with mode argument set to Clipboard.Selection to get the current value after receiving this event.

This event has a corresponding onselectionChanged property to which a single event handler may be assigned.

See also

supportsSelection

dataAvailable()

bool dataAvailable

(

int

mode = Mode.Clipboard

)

Returns true if the current system clipboard contains any type of data at all (ie. is not empty), or false otherwise (if the clipboard is empty).
The opitonal mode argument is used to control which part of the system clipboard is used.

See also

textAvailable(), hasMimeType(), hasMediaType()

textAvailable()

bool textAvailable

(

int

mode = Mode.Clipboard

)

Returns true if the current system clipboard contains any type of string data, or false otherwise. String data would be any type with a "text" primary MIME type, eg "text/plain", "text/html", "text/csv", etc.
The opitonal mode argument is used to control which part of the system clipboard is used.

See also

dataAvailable(), hasMimeType(), hasMediaType()

text() [1/2]

String text

(

int

mode = Mode.Clipboard

)

Returns the current system clipboard value as a plain text String type (ASCII/UTF8/UTF16). If the clipboard contains multipe value data types it will return:

• "text/plain" type with charset=utf-8 is preferred, if it exists (this supports the full Unicode character range, it is just expressed in the most portable UTF-8 format);
• "text/plain" type with any or no character encoding specified, if that exists;
• the first "text" type found will be returned (eg. "text/html", "text/csv", etc);

if no text types are found, or the clipboard is entirely empty, an empty string is returned.

To specify an explicit text type, use the text() function version which takes that option as the first parameter (see below).
The opitonal mode argument is used to control which part of the system clipboard is used.

See also

mimeTypes(), hasMimeType(), setText(), data()

text() [2/2]

String text	(	String	subType,
		int	mode = Mode.Clipboard
	)

Returns the clipboard text with MIME subtype subType, or an empty string if the clipboard does not contain any text of the given subtype. The subtype is just the part after "text/" of a MIME type, eg. "plain", "html", "csv", etc. It can optionally include peropery(ies), for example a character encoding like "plain;charset=utf-8". The name search is case-insensitive.
The opitonal mode argument is used to control which part of the system clipboard is used.

See also

hasMimeType(), setText(), Clipboard.Mode

setText() [1/2]

String setText	(	String	text,
		int	mode = Mode.Clipboard
	)

This function sets the current system clipboard value as a plain text String type (ASCII/UTF8/UTF16). It is written to the clipboard as "text/plain" MIME type.
The opitonal mode argument is used to control which part of the system clipboard is used.

See also

setData()

setText() [2/2]

String setText	(	String	subType,
		String	text,
		int	mode = Mode.Clipboard
	)

Sets the clipboard text with MIME subtype subType to text. The subtype is just the part after "text/" of a MIME type, eg. "plain", "html", "csv", etc.
The opitonal mode argument is used to control which part of the system clipboard is used.

See also

text(), Clipboard.Mode

data() [1/2]

ArrayBuffer data

(

int

mode = Mode.Clipboard

)

Returns the current system clipboard value as raw bytes.
When reading the value:

• if the clipboard has no data, an empty ArrayBuffer is returned;
• if the clipboard contains data of only one MIME type (or with no type specified), then that data is returned;
• if the clipboard contains multiple data types:
  • it first looks for data with an "application/octet-stream" MIME type;
  • if that fails, the first MIME type that starts with "application" will be returned;
  • if no such types were found, then the first data type is returned.

To specify a MIME type, use data() function version which takes that as the first parameter.
The opitonal mode argument is used to control which part of the system clipboard is used.

See also

setData(), mimeTypes(), hasMimeType()

data() [2/2]

ArrayBuffer data	(	String	mimeType,
		int	mode = Mode.Clipboard
	)

Get the raw byte data associated with MIME type mimeType from the current system clipboard. If the clipboard didn't have the specified MIME type, then an empty ArrayBuffer is returned.
The opitonal mode argument is used to control which part of the system clipboard is used.

See also

hasMimeType(), setData(), data, text, Clipboard.Mode

setData() [1/2]

void setData	(	ArrayBuffer	data,
		int	mode = Mode.Clipboard
	)

Sets the current system clipboard value as raw bytes. It is written to the clipboard as "application/octet-stream" MIME type.
The opitonal mode argument is used to control which part of the system clipboard is used.

See also

data(), setDataType()

setData() [2/2]

void setData	(	String	mimeType,
		ArrayBuffer	data,
		int	mode = Mode.Clipboard
	)

Set raw byte data with MIME type mimeType to data on the current system clipboard. The opitonal mode argument is used to control which part of the system clipboard is used.

See also

data(), data, text, Clipboard.Mode

clear()

void clear

(

int

mode = Mode.Clipboard

)

Clears the system clipboard of all values.
The opitonal mode argument is used to control which part of the system clipboard is used.

hasMimeType()

bool hasMimeType	(	String	mimeType,
		int	mode = Mode.Clipboard
	)

Checks if the clipboard contains data with full MIME type mimeType and returns true or false. The full MIME type is a combination of type, subtype, and possibly one or more parameters/values. For example: "text/plain" or "text/plain;charset=UTF-8"
The opitonal mode argument is used to control which part of the system clipboard is used.

See also

mimeTypes(), Clipboard.Mode

hasMediaType()

bool hasMediaType	(	String	mediaType,
		int	mode = Mode.Clipboard
	)

Checks if the clipboard contains data with base MIME type mediaType and returns true or false. The "media type" is the first part of a full MIME type before the slash (/), w/out a subtype or parameters. For example: "text", "application", "image", etc.
The opitonal mode argument is used to control which part of the system clipboard is used.

See also

mimeTypes(), Clipboard.Mode

mimeTypes()

Array< String > mimeTypes	(	String	mimeType,
		int	mode = Mode.Clipboard
	)

Returns an array of formats contained in the clipboard, if any. This is a list of MIME types for which the object can return suitable data. The formats in the list are in a priority order.
The opitonal mode argument is used to control which part of the system clipboard is used.

See also

hasMimeType(), Clipboard.Mode, text(), data()