Tcl Windows API extension

Clipboard

Commands related to accessing the clipboard

SYNOPSIS

package require twapi

clipboard_format_available FORMAT

close_clipboard

get_clipboard_formats

get_registered_clipboard_format_name FORMAT

open_clipboard

read_clipboard FORMAT

read_clipboard_text ?-raw?

register_clipboard_format FORMATNAME

start_clipboard_monitor SCRIPT

stop_clipboard_monitor MONITOR_ID

write_clipboard FORMAT DATA

write_clipboard_text TEXT

DESCRIPTION

This module provides procedures to read and write the clipboard.

The command read_clipboard and write_clipboard allow reading and writing to the Windows clipboard. Tcl/Tk has a clipboard command that provides similar functionality. The TWAPI commands are useful in two circumstances:

The Tcl clipboard command is not available in console-based Tcl programs that do not load Tk. The TWAPI command may be used to access the clipboard in this case.
More control is desired over the specific format of the data stored into the clipboard.

In other cases, the Tcl/Tk clipboard command should be preferred.

Clipboard formats

Data may be stored in the clipboard in any number for formats identified by integer values. When reading clipboard data, applications must check in what formats the current clipboard data is currently available and specify one of these formats when reading the data. Similarly, when writing data to the clipboard, applications need to specify the format in which data is to stored in the clipboard. In some cases, Windows will automatically make multiple formats available. For example, storing text in format type 1 (text) will also make format type 13 (Unicode) available in the clipboard.

In addition to the standard set of formats defined by Windows applications may register their own formats with the system. The format values associated with these are created the first time the format name is registered through register_clipboard_format and can be retrieved later with the same call. Conversely, the name associated with a format can be obtained through the get_registered_clipboard_format_name command. An example of a registered application format name is "HTML Format" which is used by Internet Explorer to store HTML fragments on the clipboard.

Multiple formats may be simultaneously stored into the clipboard. The formats currently stored in the clipboard may be obtained through the get_clipboard_formats command.

When reading or writing data, the application is responsible for formatting data appropriately, possibly through the use of Tcl's binary command. The exceptions to this are the read_clipboard_text and write_clipboard_text commands which assume the data is just text.

Reading and Writing Data

In the general case, the clipboard must first be opened with the open_clipboard call before data can be read or written to it. Data may be read and written using the read_clipboard and write_clipboard commands respectively. The clipboard must then be closed by calling close_clipboard. There may be multiple write commands between the clipboard open and close to store data in multiple formats.

For the simple case of reading and storing text data, the commands write_clipboard and write_clipboard_text may be used.

Monitoring clipboard changes

An application can monitor the clipboard by calling start_clipboard_monitor to set up a notification callback that is invoked when the contents of the clipboard change.

Commands

clipboard_format_available FORMAT: Returns 1 if the clipboard contains data in the specified format, and 0 otherwise. This command does not require the clipboard to have been opened.
close_clipboard: Closes the clipboard which must have been previously opened with open_clipboard.

Example: Copy standard input to the clipboard
get_clipboard_formats: Returns a list of the formats currently available in the clipboard. The clipboard must have been opened before this function is called.

Example: Get HTML format data from the clipboard
get_registered_clipboard_format_name FORMAT: Returns the name associated with a registered clipboard format. FORMAT identifies the format and must correspond to a registered format. An exception will be raised if FORMAT is a standard Windows format or a unregistered private format.
open_clipboard: Opens the clipboard for reading or writing. Most clipboard operations require the clipboard to have been previously opened. The clipboard must be closed once the operations are done by calling close_clipboard.

Example: Copy standard input to the clipboard
read_clipboard FORMAT: Reads the contents of the clipboard in the given format and returns it. The clipboard must have been previously opened through open_clipboard and remains open when the command returns except in the case of any Tcl exceptions. In these cases, the clipboard is closed before the exception is thrown.

FORMAT must be one of the clipboard formats as defined in Clipboard formats. The content is an exact copy of the contents of the clipboard in binary format. Callers will need to use Tcl commands such as binary and encoding to parse the data.

Example: Get HTML format data from the clipboard
read_clipboard_text ?-raw?: Retrieves the content of the clipboard as text. The clipboard must have been previously opened through open_clipboard and remains open when the command returns except in the case of any Tcl exceptions. In these cases, the clipboard is closed before the exception is thrown.

Normally the command converts CR-LF line terminators in clipboard content to LF line terminators. If the -raw option is specified, the command does no conversion of the clipboard data.

Example: Copy clipboard contents to standard output
register_clipboard_format FORMATNAME: Registers an application defined format with the system (see Clipboard Formats). FORMATNAME is the name associated with the format. The command returns an integer format identifier that may be used in calls to read and write data. If the format name is already registered, the same integer format value is returned. This command does not require the clipboard to be open.

Example: Get HTML format data from the clipboard
start_clipboard_monitor SCRIPT: Begins monitoring of clipboard contents. SCRIPT will be invoked when the clipboard is written to by any application.

The command returns a handle. When no longer required, this handle must be passed to the command stop_clipboard_monitor.

Multiple clipboard monitoring scripts may be active at the same time. However, all returned handles must be passed to stop_clipboard_monitor. before the application exits.
stop_clipboard_monitor MONITOR_ID: Stops a previously registered script that monitors clipboard contents. MONITOR_ID is monitoring handle previously returned by start_clipboard_monitor.
write_clipboard FORMAT DATA: Writes DATA to the clipboard in the given format. The clipboard must have been previously opened through open_clipboard and remains open when the command returns except in the case of any Tcl exceptions. In these cases, the clipboard is closed before the exception is thrown.

FORMAT must be one of the clipboard formats as defined in Clipboard formats. The content is an exact copy of the contents of the clipboard in binary format. Callers will need to use Tcl commands such as binary and encoding to parse the data.

Multiple write_clipboard commands may be executed between a open_clipboard and close_clipboard pair as long as the specified formats are different for each. Writing a format previously specified in the sequence overwrites the previous contents of that format.
write_clipboard_text TEXT: Writes the given text string to the clipboard. The clipboard must have been previously opened through open_clipboard and remains open when the command returns except in the case of any Tcl exceptions. In these cases, the clipboard is closed before the exception is thrown.

Example: Copy standard input to the clipboard