Tcl Windows API extension

This module provides procedures to read and write the clipboard as well as to monitor changes. 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 ownership

Access to the clipboard requires it to be first opened with open_clipboard and closed afterwards with close_clipboard. However, several commands will do this on behalf of the caller if the clipboard was not already opened.

The get_clipboard_owner and get_open_clipboard_window return information about the clipboard owner and the window that has the clipboard open.

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, write_clipboard_text read_clipboard_paths, write_clipboard_paths commands which assume the data is text and file paths respectively.

Writing Data

To store data in a single format, the write_clipboard, write_clipboard_text or write_clipboard_paths may be directly called.

To store multiple formats, the clipboard must first be opened with the open_clipboard call followed by a call to empty_clipboard. Data may then be stored in the clipboard in different formats by calling write_clipboard, write_clipboard_text or write_clipboard_paths multiple times. Finally the clipboard must be closed with close_clipboard.

Reading Data

To read data from the clipboard, call read_clipboard, read_clipboard_text or read_clipboard_paths.

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. The clipboard also maintains a sequence number that is incremented on every change. This sequence number can be retrieved with get_clipboard_sequence.

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.
empty_clipboard: Empties the clipboard and claims ownership for further writes. The clipboard must have been previously opened with open_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.
get_clipboard_owner: Returns the window handle of the window that owns the clipboard. This is the window associated with the last call to EmptyClipboard and is generally the window that last wrote to the clipboard. The returned window handle may be NULL if the clipboard is not currently owned.
get_clipboard_sequence: Returns the current clipboard sequence number. This number is incremented every time the clipboard changes and can therefore be used by applications that track the clipboard to figure out if the contents have changed.
get_open_clipboard_window: Returns the window handle of the window that has the clipboard open. This may be NULL if no window has the clipboard open or if the current OpenClipboard call specified a NULL window handle.
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.
read_clipboard FORMAT: Reads the contents of the clipboard in the given format and returns it. If the clipboard was already opened through open_clipboard, it remains open when the command returns except in the case of any Tcl exceptions. If the clipboard was not open, it will opened and closed before the command returns. In all cases where an exception is raised, the clipboard is closed before the command returns.

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.
read_clipboard_paths: Returns a list of file paths stored in the clipboard. If the clipboard was already opened through open_clipboard, it remains open when the command returns except in the case of any Tcl exceptions. If the clipboard was not open, it will be opened and closed before the command returns. In all cases where an exception is raised, the clipboard is closed before the command returns.
read_clipboard_text ?-raw BOOLEAN?: Retrieves the content of the clipboard as text. If the clipboard was already opened through open_clipboard, it remains open when the command returns except in the case of any Tcl exceptions. If the clipboard was not open, it will be opened and closed before the command returns. In all cases where an exception is raised, the clipboard is closed before the command returns.

If -raw is specified as false (default), the command converts CR-LF line terminators in clipboard content to LF line terminators. If -raw specified as true, the command does no conversion of the clipboard data.
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.
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. If the clipboard is already open, caller must have also claimed ownership through the empty_clipboard command. In this case, the clipboard remains open when the command returns after writing the data except in the case of any Tcl exceptions.

If the clipboard was not open when this command is called, the command opens the clipboard, clears it of all content by calling empty_clipboard, writes the data to the clipboard and closes it.

In all cases, the clipboard is closed before returning if an exception is thrown. This ensures other applications are not locked out of the clipboard on errors.

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_paths PATHS: Stores the specified list of file paths in the clipboard in the CF_HDROP (15) clipboard format. Each path is normalized and converted to native format.

If the clipboard is already open, caller must have also claimed ownership through the empty_clipboard command. In this case, the clipboard remains open when the command returns after writing the data except in the case of any Tcl exceptions.

If the clipboard was not open when this command is called, the command opens the clipboard, clears it of all content by calling empty_clipboard, writes the data to the clipboard and closes it.

In all cases, the clipboard is closed before returning if an exception is thrown. This ensures other applications are not locked out of the clipboard on errors.
write_clipboard_text TEXT ?-raw BOOLEAN?: Writes the given text string to the clipboard. If the clipboard is already open, caller must have also claimed ownership through the empty_clipboard command. In this case, the clipboard remains open when the command returns after writing the data except in the case of any Tcl exceptions.

If the clipboard was not open when this command is called, the command opens the clipboard, clears it of all content by calling empty_clipboard, writes the data to the clipboard and closes it.

In all cases, the clipboard is closed before returning if an exception is thrown. This ensures other applications are not locked out of the clipboard on errors.

If -raw is specified as false (default), the command converts LF line terminators without a preceding CR to CRLF line terminators. If -raw specified as true, the command does no conversion.

Clipboard

SYNOPSIS

DESCRIPTION