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
write_clipboard FORMAT DATA
write_clipboard_text TEXT

DESCRIPTION

This module provides procedures to read and write the clipboard.

Overview

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:

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.

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

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

COPYRIGHT

Copyright © 2004-2006 Ashok P. Nadkarni