util/src/TclTk/tk8.6.12/doc/clipboard.n

   1 '\"
   2 '\" Copyright (c) 1994 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 .TH clipboard n 8.4 Tk "Tk Built-In Commands"
   9 .so man.macros
  10 .BS
  11 '\" Note:  do not modify the .SH NAME line immediately below!
  12 .SH NAME
  13 clipboard \- Manipulate Tk clipboard
  14 .SH SYNOPSIS
  15 \fBclipboard \fIoption\fR ?\fIarg arg ...\fR?
  16 .BE
  17 .SH DESCRIPTION
  18 .PP
  19 This command provides a Tcl interface to the Tk clipboard,
  20 which stores data for later retrieval using the selection mechanism
  21 (via the \fB\-selection CLIPBOARD\fR option).
  22 In order to copy data into the clipboard, \fBclipboard clear\fR must
  23 be called, followed by a sequence of one or more calls to \fBclipboard
  24 append\fR.  To ensure that the clipboard is updated atomically, all
  25 appends should be completed before returning to the event loop.
  26 .PP
  27 The first argument to \fBclipboard\fR determines the format of the
  28 rest of the arguments and the behavior of the command.  The following
  29 forms are currently supported:
  30 .TP
  31 \fBclipboard append\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-format\fR \fIformat\fR? ?\fB\-type\fR \fItype\fR? ?\fB\-\|\-\fR? \fIdata\fR
  32 .
  33 Appends \fIdata\fR to the clipboard on \fIwindow\fR's
  34 display in the form given by \fItype\fR with the representation given
  35 by \fIformat\fR and claims ownership of the clipboard on \fIwindow\fR's
  36 display.
  37 .RS
  38 .PP
  39 \fIType\fR specifies the form in which the selection is to be returned
  40 (the desired
  41 .QW target
  42 for conversion, in ICCCM terminology), and
  43 should be an atom name such as \fBSTRING\fR or \fBFILE_NAME\fR; see the
  44 Inter-Client Communication Conventions Manual for complete details.
  45 \fIType\fR defaults to \fBSTRING\fR.
  46 .PP
  47 The \fIformat\fR argument specifies the representation that should be
  48 used to transmit the selection to the requester (the second column of
  49 Table 2 of the ICCCM), and defaults to \fBSTRING\fR.  If \fIformat\fR is
  50 \fBSTRING\fR, the selection is transmitted as 8-bit ASCII characters.  If
  51 \fIformat\fR is \fBATOM\fR, then the \fIdata\fR is
  52 divided into fields separated by white space; each field is converted
  53 to its atom value, and the 32-bit atom value is transmitted instead of
  54 the atom name.  For any other \fIformat\fR,  \fIdata\fR is divided
  55 into fields separated by white space and each
  56 field is converted to a 32-bit integer; an array of integers is
  57 transmitted to the selection requester.  Note that strings passed to
  58 \fBclipboard append\fR are concatenated before conversion, so the
  59 caller must take care to ensure appropriate spacing across string
  60 boundaries.  All items appended to the clipboard with the same
  61 \fItype\fR must have the same \fIformat\fR.
  62 .PP
  63 The \fIformat\fR argument is needed only for compatibility with
  64 clipboard requesters that do not use Tk.  If the Tk toolkit is being
  65 used to retrieve the \fBCLIPBOARD\fR selection then the value is
  66 converted back to a string at the requesting end, so \fIformat\fR is
  67 irrelevant.
  68 .PP
  69 A \fB\-\|\-\fR argument may be specified to mark the end of options:  the
  70 next argument will always be used as \fIdata\fR.
  71 This feature may be convenient if, for example, \fIdata\fR starts
  72 with a \fB\-\fR.
  73 .RE
  74 .TP
  75 \fBclipboard clear\fR ?\fB\-displayof\fR \fIwindow\fR?
  76 .
  77 Claims ownership of the clipboard on \fIwindow\fR's display and removes
  78 any previous contents.  \fIWindow\fR defaults to
  79 .QW . .
  80 Returns an empty string.
  81 .TP
  82 \fBclipboard get\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-type\fR \fItype\fR?
  83 .
  84 Retrieve data from the clipboard on \fIwindow\fR's display.
  85 \fIWindow\fR defaults to
  86 .QW . .
  87 \fIType\fR specifies the form in which
  88 the data is to be returned and should be an atom name such as \fBSTRING\fR
  89 or \fBFILE_NAME\fR.  \fIType\fR defaults to \fBSTRING\fR.  This command is
  90 equivalent to
  91 .QW "\fBselection get\fR \fB\-selection CLIPBOARD\fR" .
  92 .RS
  93 .PP
  94 Note that on modern X11 systems, the most useful type to retrieve for
  95 transferred strings is not \fBSTRING\fR, but rather \fBUTF8_STRING\fR.
  96 .RE
  97 .SH EXAMPLES
  98 .PP
  99 Get the current contents of the clipboard.
 100 .CS
 101 if {[catch {\fBclipboard get\fR} contents]} {
 102     # There were no clipboard contents at all
 103 }
 104 .CE
 105 .PP
 106 Set the clipboard to contain a fixed string.
 107 .CS
 108 \fBclipboard clear\fR
 109 \fBclipboard append\fR "some fixed string"
 110 .CE
 111 .PP
 112 You can put custom data into the clipboard by using a custom \fB\-type\fR
 113 option. This is not necessarily portable, but can be very useful. The
 114 method of passing Tcl scripts this way is effective, but should be mixed
 115 with safe interpreters in production code.
 116 .CS
 117 # This is a very simple canvas serializer;
 118 # it produces a script that recreates the item(s) when executed
 119 proc getItemConfig {canvas tag} {
 120    set script {}
 121    foreach item [$canvas find withtag $tag] {
 122       append script {$canvas create } [$canvas type $item]
 123       append script { } [$canvas coords $item] { }
 124       foreach config [$canvas itemconf $item] {
 125          lassign $config name \- \- \- value
 126          append script [list $name $value] { }
 127       }
 128       append script \en
 129    }
 130    return [string trim $script]
 131 }
 132
 133 # Set up a binding on a canvas to cut and paste an item
 134 set c [canvas .c]
 135 pack $c
 136 $c create text 150 30 \-text "cut and paste me"
 137 bind $c <<Cut>> {
 138    \fBclipboard clear\fR
 139    \fBclipboard append \-type\fR TkCanvasItem \e
 140          [getItemConfig %W current]
 141    # Delete because this is cut, not copy.
 142    %W delete current
 143 }
 144 bind $c <<Paste>> {
 145    catch {
 146       set canvas %W
 147       eval [\fBclipboard get \-type\fR TkCanvasItem]
 148    }
 149 }
 150 .CE
 151 .SH "SEE ALSO"
 152 interp(n), selection(n)
 153 .SH KEYWORDS
 154 clear, format, clipboard, append, selection, type
 155 '\" Local Variables:
 156 '\" mode: nroff
 157 '\" End: