The [pasteboard] command.

Introduction

The pasteboard command lets you read or write data from and to the standard OS X pasteboards, in particular the general pasteboard used for ordinary cut, copy, and paste operations.
A pasteboard can contain several items and each item may be available in different types. For instance, a pasteboard could contain both a text and an image: the text could be stored in several different text encodings (such as macRoman, utf-8 and utf-16) and the image could be available in different formats (such as JPEG, TIFF, etc.).
Each type is identified by a UTI (Uniform Type Identifier) which is a string to uniquely identify a given class or type of item. There are built-in UTIs provided by Mac OS X but one can also create a custom UTI for custom data. UTIs are plain strings, commonly formed in reverse-DNS notation. Here are some examples corresponding to the type of objects mentionned above:

    com.apple.traditional-mac-plain-text 
    public.utf8-plain-text 
    public.utf16-plain-text
    public.jpeg
    public.tiff

See the Uniform Type Identifiers section below for usual UTIs.

Synopsis

The formal syntax of the [pasteboard] command is:

pasteboard subcommand ?options?

The possible subcommands are described below. Depending on the subcommand, some options may be specified.

The [clear] subcommand

This subcommand clears the existing contents of the pasteboard. The syntax is:

    pasteboard clear ?-name str?

The -name option is explained in the Pasteboard Names section.

The [count] subcommand

This subcommand returns the number of items stored in the pasteboard. The syntax is:

    pasteboard count ?-name str?

Each item may be represented in different types: see the [pasteboard types] command. The -name option is explained in the Pasteboard Names section.

The [read] subcommand

This subcommand returns the data for the given item in a specified type. The complete syntax is:

    pasteboard read ?-index num? ?-name str? ?-type UTI?

The -index option specifies the index of the item in the pasteboard. Its default value is 0, meaning the first item.
The -name option is explained in the Pasteboard Names section.
The -type option specifies the type of data. Each type is represented by a UTI as explained in the introduction. See the Uniform Type Identifiers section.
The default value for the -type option is public.utf8-plain-text which means text in UTF8 encoding. In that case, the data are returned as a Tcl string.
If the type is com.apple.cocoa.pasteboard.multiple-text-selection and if there is a multiple string in the pasteboard, it is returned as a Tcl list.
For all the other types, the data are returned as a Tcl binary string.

The [types] subcommand

This subcommand returns a list of the different types available for a given item stored in the pasteboard. The complete syntax is:

    pasteboard types ?-index num? ?-name str?

One may specify the index of a particular item: the index is 0-based. The command [pasteboard count] can be used to know the number of items present in the pasteboard. If the -index option is not specified, the command applies to the first item (that is to say the item at index 0) in the pasteboard if any. If the pasteboard is empty, the command returns an empty string.
Each type is represented by a UTI as explained in the introduction. See the Uniform Type Identifiers section.
The -name option is explained in the Pasteboard Names section.

The [write] subcommand

This subcommand writes data to the pasteboard. The complete syntax is:

    pasteboard write ?-name str? ?-type UTI? data

This command erases the contents of the pasteboard before writing the new data.
The -type option lets you specify the type of the data. Each type is represented by a UTI as explained in the introduction. See the Uniform Type Identifiers section. The default value is public.utf8-plain-text which means text in UTF8 encoding. In that case, the data argument should be a simple Tcl string.
If the type is com.apple.cocoa.pasteboard.multiple-text-selection (used to store multiple selections for instance), the data argument is expected to be a Tcl list of strings.
For all the other types, the data argument should be a Tcl binary string.
The -name option is explained in the Pasteboard Names section.

Uniform Type Identifiers

Here is a list of the main UTIs supported by Mac OS X pasteboards:

Data type	UTI
String	public.utf8-plain-text
PDF	com.adobe.pdf
TIFF	public.tiff
PNG	public.png
RTF	public.rtf
RTFD	com.apple.flat-rtfd
HTML	public.html
Tabular Text	public.utf8-tab-separated-values-text
Font	com.apple.cocoa.pasteboard.character-formatting
Ruler	com.apple.cocoa.pasteboard.paragraph-formatting
Color	com.apple.cocoa.pasteboard.color
Sound	com.apple.cocoa.pasteboard.sound
Multiple Text Selection	com.apple.cocoa.pasteboard.multiple-text-selection
Find Panel Search Options	com.apple.cocoa.pasteboard.find-panel-search-options

You can also use your own custom UTIs.

Pasteboard Names

All the subcommands accept a -name option to specify the name of a standard OS X pasteboard. The possible values are described below:

general: The pasteboard that's used for ordinary cut, copy, and paste operations. This pasteboard holds the contents of the last selection that's been cut or copied.
font: The pasteboard that holds font and character information and is used by Copy Font and Paste Font commands that may be implemented in some applications.
ruler: The pasteboard that holds information about paragraph formats in support of the Copy Ruler and Paste Ruler commands that may be implemented in some applications.
find: The pasteboard that holds information about the current state of the active application's find panel. This information permits users to enter a search string into the find panel, then switch to another application to conduct another search. See also the [findBar] command.
drag: The pasteboard that stores data to be moved as the result of a drag operation.

If the -name option is not specified, the general pasteboard is used by default.

Examples

Here are a few basic examples which can be executed one by one in the Tcl Shell (⌘Y).
Get the number of items in the general pasteboard:

«» pasteboard count

Get the type of the first item:

«» pasteboard types -index 0

Write a string in the general pasteboard:

«» pasteboard write "The quick brown fox jumps over the lazy dog"

Write the contents of the general pasteboard:

«» pasteboard read

Get the types contained in the find pasteboard (used by the Find Bar in Alpha):

«» pasteboard types -name find

Write data with a specific type:

«» set htmlStr "<HTML><BODY>The <I>quick brown fox</I> jumps over the <B>lazy dog</B>.</BODY></HTML>"
«» set htmlType "public.html"
«» pasteboard write -type $htmlType $htmlStr

Last updated 2019-11-27 14:13:09