Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | # Copyright (c) 1994 The Regents of the University of California. |
2 | # Copyright (c) 1994-1996 Sun Microsystems, Inc. | |
3 | # See the file "license.terms" for information on usage and redistribution | |
4 | # of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
5 | # | |
6 | # | |
7 | ||
8 | =head1 NAME | |
9 | ||
10 | Tk::clipboard - Manipulate Tk clipboard | |
11 | ||
12 | =for category User Interaction | |
13 | ||
14 | =head1 SYNOPSIS | |
15 | ||
16 | I<$widget>-E<gt>B<clipboard>I<Option>?(I<args>)? | |
17 | ||
18 | =head1 DESCRIPTION | |
19 | ||
20 | This command provides an interface to the Tk clipboard, | |
21 | which stores data for later retrieval using the selection mechanism. | |
22 | In order to copy data into the clipboard, B<clipboardClear> must | |
23 | be called, followed by a sequence of one or more calls to | |
24 | B<clipboardAppend>. To ensure that the clipboard is updated atomically, all | |
25 | appends should be completed before returning to the event loop. | |
26 | ||
27 | The following methods are currently supported: | |
28 | ||
29 | =over 4 | |
30 | ||
31 | =item I<$widget>-E<gt>B<clipboardClear> | |
32 | ||
33 | Claims ownership of the clipboard on I<$widget>'s display and removes | |
34 | any previous contents. Returns an empty string. | |
35 | ||
36 | =item I<$widget>-E<gt>B<clipboardAppend>(?B<-format>=E<gt>I<format>?,?B<-type>=E<gt>I<type>?,?B<-->?,I<data>) | |
37 | ||
38 | Appends I<data> to the clipboard on $widget's | |
39 | display in the form given by I<type> with the representation given | |
40 | by I<format> and claims ownership of the clipboard on $widget's | |
41 | display. | |
42 | ||
43 | =over 8 | |
44 | ||
45 | I<Type> specifies the form in which the selection is to be returned | |
46 | (the desired ``target'' for conversion, in ICCCM terminology), and | |
47 | should be an atom name such as STRING or FILE_NAME; see the | |
48 | Inter-Client Communication Conventions Manual for complete details. | |
49 | I<Type> defaults to STRING. | |
50 | ||
51 | The I<format> argument specifies the representation that should be | |
52 | used to transmit the selection to the requester (the second column of | |
53 | Table 2 of the ICCCM), and defaults to STRING. If I<format> is | |
54 | STRING, the selection is transmitted as 8-bit ASCII characters. | |
55 | See the L<Tk::Selection> documentation for explanation of what happens | |
56 | if I<format> is not STRING. | |
57 | Note that arguments passed to | |
58 | B<clipboardAppend> 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 | I<type> must have the same I<format>. | |
62 | ||
63 | A B<--> argument may be specified to mark the end of options: the | |
64 | next argument will always be used as I<data>. | |
65 | This feature may be convenient if, for example, I<data> starts | |
66 | with a B<->. | |
67 | ||
68 | =back | |
69 | ||
70 | =back | |
71 | ||
72 | =head1 KEYWORDS | |
73 | ||
74 | clear, format, clipboard, append, selection, type | |
75 | ||
76 | =cut | |
77 |