Clipboard
Commands related to accessing the clipboard
package require twapi
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.
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.
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.
- 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 © 2004-2006 Ashok P. Nadkarni