Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | # Copyright (c) 1990-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::Selection - Manipulate the X selection | |
11 | ||
12 | =for category User Interaction | |
13 | ||
14 | =head1 SYNOPSIS | |
15 | ||
16 | I<$widget>-E<gt>B<Selection>I<Option>?(I<args>)? | |
17 | ||
18 | =head1 DESCRIPTION | |
19 | ||
20 | This command provides an interface to the X selection mechanism and | |
21 | implements the full selection functionality described in the | |
22 | X Inter-Client Communication Conventions Manual (ICCCM). | |
23 | ||
24 | The widget object used to invoke the methods below determines which | |
25 | display is used to access the selection. | |
26 | In order to avoid conflicts with B<selection> methods of widget classes | |
27 | (e.g. B<Text>) this set of methods uses the prefix B<Selection>. | |
28 | The following methods are currently supported: | |
29 | ||
30 | =over 4 | |
31 | ||
32 | =item I<$widget>-E<gt>B<SelectionClear>?(B<-selection>=E<gt>I<selection>)? | |
33 | ||
34 | If I<selection> exists anywhere on I<$widget>'s display, clear it | |
35 | so that no window owns the selection anymore. I<Selection> | |
36 | specifies the X selection that should be cleared, and should be an | |
37 | atom name such as PRIMARY or CLIPBOARD; see the Inter-Client | |
38 | Communication Conventions Manual for complete details. | |
39 | I<Selection> defaults to PRIMARY. | |
40 | Returns an empty string. | |
41 | ||
42 | =item I<$widget>-E<gt>B<SelectionGet>?(?B<-selection>=E<gt>I<selection>?,?B<-type>=E<gt>I<type>?)? | |
43 | ||
44 | Retrieves the value of I<selection> from I<$widget>'s display and | |
45 | returns it as a result. I<Selection> defaults to PRIMARY. | |
46 | ||
47 | I<Type> specifies the form in which the selection is to be returned | |
48 | (the desired ``target'' for conversion, in ICCCM terminology), and | |
49 | should be an atom name such as STRING or FILE_NAME; see the | |
50 | Inter-Client Communication Conventions Manual for complete details. | |
51 | I<Type> defaults to STRING. The selection owner may choose to | |
52 | return the selection in any of several different representation | |
53 | formats, such as STRING, ATOM, INTEGER, etc. (this format is different | |
54 | than the selection type; see the ICCCM for all the confusing details). | |
55 | ||
56 | If I<format> is not STRING then things get messy, the following | |
57 | description is from the Tcl/Tk man page as yet incompetely translated for | |
58 | the perl version - it is misleading at best. | |
59 | ||
60 | If the selection is returned in a non-string format, such as INTEGER | |
61 | or ATOM, the B<SelectionGet> converts it to a list of perl | |
62 | values: atoms are converted to their | |
63 | textual names, and anything else is converted integers. | |
64 | ||
65 | A goal of the perl port is to provide better handling of different | |
66 | formats than Tcl/Tk does, which should be possible given perl's | |
67 | wider range of ``types''. Although some thought went into this | |
68 | in very early days of perl/Tk what exactly happens is still | |
69 | "not quite right" and subject to change. | |
70 | ||
71 | =item I<$widget>-E<gt>B<SelectionHandle>(?B<-selection>=E<gt>I<selection>?,?B<-type>=E<gt>I<type>?,?B<-format>=E<gt>I<format>? I<callback>) | |
72 | ||
73 | Creates a handler for selection requests, such that I<callback> will | |
74 | be executed whenever I<selection> is owned by I<$widget> and | |
75 | someone attempts to retrieve it in the form given by I<type> | |
76 | (e.g. I<type> is specified in the B<selection get> command). | |
77 | I<Selection> defaults to PRIMARY, I<type> defaults to STRING, and | |
78 | I<format> defaults to STRING. If I<callback> is an empty string | |
79 | then any existing handler for I<$widget>, I<type>, and | |
80 | I<selection> is removed. | |
81 | ||
82 | =over 8 | |
83 | ||
84 | When I<selection> is requested, I<$widget> is the selection owner, | |
85 | and I<type> is the requested type, I<callback> will be executed | |
86 | with two additional arguments. | |
87 | The two additional arguments | |
88 | are I<offset> and I<maxBytes>: I<offset> specifies a starting | |
89 | character position in the selection and I<maxBytes> gives the maximum | |
90 | number of bytes to retrieve. The command should return a value consisting | |
91 | of at most I<maxBytes> of the selection, starting at position | |
92 | I<offset>. For very large selections (larger than I<maxBytes>) | |
93 | the selection will be retrieved using several invocations of I<callback> | |
94 | with increasing I<offset> values. If I<callback> returns a string | |
95 | whose length is less than I<maxBytes>, the return value is assumed to | |
96 | include all of the remainder of the selection; if the length of | |
97 | I<callback>'s result is equal to I<maxBytes> then | |
98 | I<callback> will be invoked again, until it eventually | |
99 | returns a result shorter than I<maxBytes>. The value of I<maxBytes> | |
100 | will always be relatively large (thousands of bytes). | |
101 | ||
102 | If I<callback> returns an error (e.g. via B<die>) | |
103 | then the selection retrieval is rejected | |
104 | just as if the selection didn't exist at all. | |
105 | ||
106 | The I<format> argument specifies the representation that should be | |
107 | used to transmit the selection to the requester (the second column of | |
108 | Table 2 of the ICCCM), and defaults to STRING. If I<format> is | |
109 | STRING, the selection is transmitted as 8-bit ASCII characters (i.e. | |
110 | just in the form returned by I<command>). | |
111 | ||
112 | If I<format> is not STRING then things get messy, the following | |
113 | description is from the Tcl/Tk man page as yet untranslated for | |
114 | the perl version - it is misleading at best. | |
115 | ||
116 | If I<format> is | |
117 | ATOM, then the return value from I<command> is divided into fields | |
118 | separated by white space; each field is converted to its atom value, | |
119 | and the 32-bit atom value is transmitted instead of the atom name. | |
120 | For any other I<format>, the return value from I<command> is | |
121 | divided into fields separated by white space and each field is | |
122 | converted to a 32-bit integer; an array of integers is transmitted | |
123 | to the selection requester. | |
124 | ||
125 | The I<format> argument is needed only for compatibility with | |
126 | many selection requesters, except Tcl/Tk. If Tcl/Tk is being | |
127 | used to retrieve the selection then the value is converted back to | |
128 | a string at the requesting end, so I<format> is | |
129 | irrelevant. | |
130 | ||
131 | A goal of the perl port is to provide better handling of different | |
132 | formats than Tcl/Tk does, which should be possible given perl's | |
133 | wider range of ``types''. Although some thought went into this | |
134 | in very early days of perl/Tk what exactly happens is still | |
135 | "not quite right" and subject to change. | |
136 | ||
137 | =item I<$widget>-E<gt>B<SelectionOwner>?(B<-selection>=E<gt>I<selection>)? | |
138 | ||
139 | B<SelectionOwner> returns the | |
140 | window in this application that owns I<selection> on the display | |
141 | containing I<$widget>, or an empty string if no window in this | |
142 | application owns the selection. I<Selection> defaults to PRIMARY. | |
143 | ||
144 | =item I<$widget>-E<gt>B<SelectionOwn>?(?B<-command>=E<gt>I<callback>?,?B<-selection>=E<gt>I<selection>?)? | |
145 | ||
146 | B<SelectionOwn> causes I<$widget> to become | |
147 | the new owner of I<selection> on I<$widget>'s display, returning | |
148 | an empty string as result. The existing owner, if any, is notified | |
149 | that it has lost the selection. | |
150 | If I<callback> is specified, it will be executed when | |
151 | some other window claims ownership of the selection away from | |
152 | I<$widget>. I<Selection> defaults to PRIMARY. | |
153 | ||
154 | =back | |
155 | ||
156 | =back | |
157 | ||
158 | =head1 KEYWORDS | |
159 | ||
160 | clear, format, handler, ICCCM, own, selection, target, type | |
161 | ||
162 | =cut | |
163 |