Skip to main content

module util::Clipboard

rascal-0.40.16

Programmatic access to the native system clipboard (copy and paste), with some handy (de)-escaping features.

Usage​

import util::Clipboard;

Dependencies​

import Exception;

function paste​

If there is textual content in the current clipboard, then return it as a string.

str paste()

This will transfer any plaintext content that is currently on the system clipboard, no matter the source to a string value.

If the system's clipboard is not accessible (say we are running in a headless environment), then paste always returns the empty string.

Benefits​

  • past never throws exceptions, it just returns "" if something fails and prints an exception. If you need a less robust version look at past(str mimetype) below.
  • copy/paste allow for interesting and useful user interactions, especially while experimenting on the REPL.
  • paste encodes and escapes all kinds of wild characters automatically.

Pitfalls​

  • the first time paste or copy are called the UI toolkit must boot up; it can take a few seconds.
  • paste provides the content of the current clipboard, where other processes can always put new content int. The paste function is thread-safe, it will provide the contents of the clipboard as it was at a certain time, but it does not have to be the latest version.

function copy​

Load the contents of a string value into the system clipboard.

void copy(str content)

This will put the contents of the string value in into the system clipboard. So this is not the string value with quotes and escapes, but the pure string data.

If the system's clipboard is not accessible (say we are running in a headless environment), then copy always has no effect.

Benefits​

  • copy/paste allow for interesting and useful user interactions, especially while experimenting on the REPL.
  • copy transfers the pure content of the string, no quotes or escapes.

Pitfalls​

  • the first time paste or copy are called the UI toolkit must boot up; it can take a few seconds.
  • if another application copies something to the clipboard, or content can be overwritten. There is always a race for the clipboard, but this function is thread-safe. Right after its execution the content of the clipboard is guaranteed to contain content.

function availableTextMimetypes​

Lists the available mimetypes on the current clipboard, restricted to the ones we can serialize to string.

rel[str humanReadable, str fullMimetype] availableTextMimetypes()

The clipboard can contain many kinds of textual data. With this query you retrieve all the supported mimetypes that we can safely and correctly serialize to a string.

Most of the mimetypes contain the exact charset encoding parameter, such that we do not have to worry about that here. Using paste(str mimetype) those details will be taken care off. However if you call paste with an unavailable encoding, there will be an appropriate exception.

If this function returns {} then there is nothing on the clipboard that can be serialized to a string.

Pitfalls​

  • after calling this function, the user may have selected another content for the clipboard. There is always a race for the clipboard. This function is thread-friendly, however and will not crash but just provide outdated information.

function availableTextMimetypesFor​

Lists the available mimetypes on the current clipboard, restricted to the ones we can serialize to string and that start with shortMimetype.

rel[str humanReadable, str fullMimetype] availableTextMimetypesFor(str shortMimetype)

The clipboard can contain many kinds of textual data. With this query you retrieve all the exact supported mimetypes for, for example, text/html. The function will fill in the specific charset and implementation class parameters of the mimetype, for all supported formats.

Most of the mimetypes contain the exact charset encoding parameter, such that we do not have to worry about that here. Using paste(str mimetype) those details will be taken care off. However if you call paste with an unavailable encoding, there will be an appropriate exception.

If this function returns {} then there is nothing on the clipboard that can be serialized to a string and matches the shortMimetype.

Pitfalls​

  • after calling this function, the user may have selected another content for the clipboard. There is always a race for the clipboard. This function is thread-friendly, however and will not crash but just provide outdated information.

function paste​

str paste(str mimetype) throws IO, IllegalArgument

This only works for Available Text Mimetypes, otherwise an exception is thrown.

This function behaves as paste(), but it can serialize all kinds of other data, as long as the internal data flavors for the given mimetypes support textual serialization. In principle these are the mimetypes that list a charset parameter, but there are also some heuristics that enlarge the set a bit. The supported mimetypes are always listed in Available Text Mimetypes.