summaryrefslogtreecommitdiffstats
path: root/doc/clipboard.n
diff options
context:
space:
mode:
Diffstat (limited to 'doc/clipboard.n')
-rw-r--r--doc/clipboard.n81
1 files changed, 81 insertions, 0 deletions
diff --git a/doc/clipboard.n b/doc/clipboard.n
new file mode 100644
index 0000000..770463d
--- /dev/null
+++ b/doc/clipboard.n
@@ -0,0 +1,81 @@
+'\"
+'\" Copyright (c) 1994 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+'\" SCCS: @(#) clipboard.n 1.9 96/03/26 18:21:12
+'\"
+.so man.macros
+.TH clipboard n 4.0 Tk "Tk Built-In Commands"
+.BS
+'\" Note: do not modify the .SH NAME line immediately below!
+.SH NAME
+clipboard \- Manipulate Tk clipboard
+.SH SYNOPSIS
+\fBclipboard \fIoption\fR ?\fIarg arg ...\fR?
+.BE
+
+.SH DESCRIPTION
+.PP
+This command provides a Tcl interface to the Tk clipboard,
+which stores data for later retrieval using the selection mechanism.
+In order to copy data into the clipboard, \fBclipboard clear\fR must
+be called, followed by a sequence of one or more calls to \fBclipboard
+append\fR. To ensure that the clipboard is updated atomically, all
+appends should be completed before returning to the event loop.
+.PP
+The first argument to \fBclipboard\fR determines the format of the
+rest of the arguments and the behavior of the command. The following
+forms are currently supported:
+.PP
+.TP
+\fBclipboard clear\fR ?\fB\-displayof\fR \fIwindow\fR?
+Claims ownership of the clipboard on \fIwindow\fR's display and removes
+any previous contents. \fIWindow\fR defaults to ``.''. Returns an
+empty string.
+.TP
+\fBclipboard append\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-format\fR \fIformat\fR? ?\fB\-type\fR \fItype\fR? ?\fB\-\|\-\fR? \fIdata\fR
+Appends \fIdata\fR to the clipboard on \fIwindow\fR's
+display in the form given by \fItype\fR with the representation given
+by \fIformat\fR and claims ownership of the clipboard on \fIwindow\fR's
+display.
+.RS
+.PP
+\fIType\fR specifies the form in which the selection is to be returned
+(the desired ``target'' for conversion, in ICCCM terminology), and
+should be an atom name such as STRING or FILE_NAME; see the
+Inter-Client Communication Conventions Manual for complete details.
+\fIType\fR defaults to STRING.
+.PP
+The \fIformat\fR argument specifies the representation that should be
+used to transmit the selection to the requester (the second column of
+Table 2 of the ICCCM), and defaults to STRING. If \fIformat\fR is
+STRING, the selection is transmitted as 8-bit ASCII characters. If
+\fIformat\fR is ATOM, then the \fIdata\fR is
+divided into fields separated by white space; each field is converted
+to its atom value, and the 32-bit atom value is transmitted instead of
+the atom name. For any other \fIformat\fR, \fIdata\fR is divided
+into fields separated by white space and each
+field is converted to a 32-bit integer; an array of integers is
+transmitted to the selection requester. Note that strings passed to
+\fBclipboard append\fR are concatenated before conversion, so the
+caller must take care to ensure appropriate spacing across string
+boundaries. All items appended to the clipboard with the same
+\fItype\fR must have the same \fIformat\fR.
+.PP
+The \fIformat\fR argument is needed only for compatibility with
+clipboard requesters that don't use Tk. If the Tk toolkit is being
+used to retrieve the CLIPBOARD selection then the value is converted back to
+a string at the requesting end, so \fIformat\fR is
+irrelevant.
+.PP
+A \fB\-\|\-\fR argument may be specified to mark the end of options: the
+next argument will always be used as \fIdata\fR.
+This feature may be convenient if, for example, \fIdata\fR starts
+with a \fB\-\fR.
+.RE
+
+.SH KEYWORDS
+clear, format, clipboard, append, selection, type