Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | .\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "EVENT 1" | |
132 | .TH EVENT 1 "2000-12-30" "perl v5.8.0" "User Contributed Perl Documentation" | |
133 | .SH "NAME" | |
134 | Tk::event \- Miscellaneous event facilities: define virtual events and generate events | |
135 | .SH "SYNOPSIS" | |
136 | .IX Header "SYNOPSIS" | |
137 | \&\fI$widget\fR\->\fBevent\fR\fIAction\fR(?\fIarg, arg, ...\fR?); | |
138 | .SH "DESCRIPTION" | |
139 | .IX Header "DESCRIPTION" | |
140 | The \fBevent\fR\fIAction\fR methods provides several facilities for dealing with | |
141 | window system events, such as defining virtual events and synthesizing | |
142 | events. Virtual events are shared by all widgets of the same | |
143 | \&\fBMainWindow\fR. Different MainWindows can have different | |
144 | virtual event. | |
145 | .PP | |
146 | The following methods are currently supported: | |
147 | .IP "\fI$widget\fR\->\fBeventAdd\fR(\fB'<<\fR\fIvirtual\fR\fB>>'\fR\fI, sequence \fR?,\fIsequence, ...\fR?)" 4 | |
148 | .IX Item "$widget->eventAdd('<<virtual>>', sequence ?,sequence, ...?)" | |
149 | Associates the virtual event \fIvirtual\fR with the physical | |
150 | event sequence(s) given by the \fIsequence\fR arguments, so that | |
151 | the virtual event will trigger whenever any one of the \fIsequence\fRs | |
152 | occurs. | |
153 | \&\fIVirtual\fR may be any string value and \fIsequence\fR may have | |
154 | any of the values allowed for the \fIsequence\fR argument to the | |
155 | bind method. | |
156 | If \fIvirtual\fR is already defined, the new physical event sequences | |
157 | add to the existing sequences for the event. | |
158 | .IP "\fI$widget\fR\->\fBeventDelete\fR(\fB'<<\fR\fIvirtual\fR\fB>>'\fR ?,\fIsequence,\fR \fIsequence, ...\fR?)" 4 | |
159 | .IX Item "$widget->eventDelete('<<virtual>>' ?,sequence, sequence, ...?)" | |
160 | Deletes each of the \fIsequence\fRs from those associated with | |
161 | the virtual event given by \fIvirtual\fR. | |
162 | \&\fIVirtual\fR may be any string value and \fIsequence\fR may have | |
163 | any of the values allowed for the \fIsequence\fR argument to the | |
164 | bind method. | |
165 | Any \fIsequence\fRs not currently associated with \fIvirtual\fR | |
166 | are ignored. | |
167 | If no \fIsequence\fR argument is provided, all physical event sequences | |
168 | are removed for \fIvirtual\fR, so that the virtual event will not | |
169 | trigger anymore. | |
170 | .IP "\fI$widget\fR\->\fBeventGenerate\fR(\fIevent\fR ?,\fIoption => value, option => value, ...\fR?)" 4 | |
171 | .IX Item "$widget->eventGenerate(event ?,option => value, option => value, ...?)" | |
172 | Generates a window event and arranges for it to be processed just as if | |
173 | it had come from the window system. | |
174 | \&\fI$window\fR is a reference to the window for which the event | |
175 | will be generated. | |
176 | \&\fIEvent\fR provides a basic description of | |
177 | the event, such as \fB<Shift\-Button\-2>\fR or \fB<<Paste>>\fR. | |
178 | If \fIWindow\fR is empty the whole screen is meant, and coordinates | |
179 | are relative to the screen. | |
180 | \&\fIEvent\fR may have any of the forms allowed for the \fIsequence\fR | |
181 | argument of the bind method except that it must consist | |
182 | of a single event pattern, not a sequence. | |
183 | \&\fIOption-value\fR pairs may be used to specify additional | |
184 | attributes of the event, such as the x and y mouse position; | |
185 | see \*(L"\s-1EVENT\s0 \s-1FIELDS\s0\*(R" below. If the \fB\-when\fR option is not specified, the | |
186 | event is processed immediately: all of the handlers for the event | |
187 | will complete before the \fBeventGenerate\fR method returns. | |
188 | If the \fB\-when\fR option is specified then it determines when the | |
189 | event is processed. | |
190 | .IP "\fI$widget\fR\->\fBeventInfo\fR(?'\fB<<\fR\fIvirtual\fR\fB>>'\fR?)" 4 | |
191 | .IX Item "$widget->eventInfo(?'<<virtual>>'?)" | |
192 | Returns information about virtual events. | |
193 | If the \fB<<\fR\fIvirtual\fR\fB>>\fR argument is omitted, the return value | |
194 | is a list of all the virtual events that are currently defined. | |
195 | If \fB<<\fR\fIvirtual\fR\fB>>\fR is specified then the return value is | |
196 | a list whose elements are the physical event sequences currently | |
197 | defined for the given virtual event; if the virtual event is | |
198 | not defined then \fBundef\fR is returned. | |
199 | .SH "EVENT FIELDS" | |
200 | .IX Header "EVENT FIELDS" | |
201 | The following options are supported for the \fBeventGenerate\fR | |
202 | method. These correspond to the ``%'' expansions | |
203 | allowed in binding callback for the bind method. | |
204 | .IP "\fB\-above\fR => \fIwindow\fR" 4 | |
205 | .IX Item "-above => window" | |
206 | \&\fIWindow\fR specifies the \fIabove\fR field for the event, | |
207 | either as a window path name or as an integer window id. | |
208 | Valid for \fBConfigure\fR events. | |
209 | Corresponds to the %a substitution for binding scripts. | |
210 | .IP "\fB\-borderwidth\fR => \fIsize\fR" 4 | |
211 | .IX Item "-borderwidth => size" | |
212 | \&\fISize\fR must be a screen distance; it specifies the | |
213 | \&\fIborder_width\fR field for the event. | |
214 | Valid for \fBConfigure\fR events. | |
215 | Corresponds to the %B substitution for binding scripts. | |
216 | .IP "\fB\-button\fR => \fInumber\fR" 4 | |
217 | .IX Item "-button => number" | |
218 | \&\fINumber\fR must be an integer; it specifies the \fIdetail\fR field | |
219 | for a \fBButtonPress\fR or \fBButtonRelease\fR event, overriding | |
220 | any button number provided in the base \fIevent\fR argument. | |
221 | Corresponds to the %b substitution for binding scripts. | |
222 | .IP "\fB\-count\fR => \fInumber\fR" 4 | |
223 | .IX Item "-count => number" | |
224 | \&\fINumber\fR must be an integer; it specifies the \fIcount\fR field | |
225 | for the event. Valid for \fBExpose\fR events. | |
226 | Corresponds to the %c substitution for binding scripts. | |
227 | .IP "\fB\-detail\fR => \fIdetail\fR" 4 | |
228 | .IX Item "-detail => detail" | |
229 | \&\fIDetail\fR specifies the \fIdetail\fR field for the event | |
230 | and must be one of the following: | |
231 | .RS 4 | |
232 | .Sp | |
233 | .Vb 4 | |
234 | \& NotifyAncestor NotifyNonlinearVirtual | |
235 | \& NotifyDetailNone NotifyPointer | |
236 | \& NotifyInferior NotifyPointerRoot | |
237 | \& NotifyNonlinear NotifyVirtual | |
238 | .Ve | |
239 | .Sp | |
240 | .RS 8 | |
241 | Valid for \fBEnter\fR, \fBLeave\fR, \fBFocusIn\fR and | |
242 | \&\fBFocusOut\fR events. | |
243 | Corresponds to the %d substitution for binding scripts. | |
244 | .RE | |
245 | .RE | |
246 | .RS 4 | |
247 | .RE | |
248 | .IP "\fB\-focus\fR\fI boolean\fR" 4 | |
249 | .IX Item "-focus boolean" | |
250 | \&\fIBoolean\fR must be a boolean value; it specifies the \fIfocus\fR | |
251 | field for the event. | |
252 | Valid for \fBEnter\fR and \fBLeave\fR events. | |
253 | Corresponds to the %f substitution for binding scripts. | |
254 | .IP "\fB\-height\fR\fI size\fR" 4 | |
255 | .IX Item "-height size" | |
256 | \&\fISize\fR must be a screen distance; it specifies the \fIheight\fR | |
257 | field for the event. Valid for \fBConfigure\fR events. | |
258 | Corresponds to the %h substitution for binding scripts. | |
259 | .IP "\fB\-keycode\fR\fI number\fR" 4 | |
260 | .IX Item "-keycode number" | |
261 | \&\fINumber\fR must be an integer; it specifies the \fIkeycode\fR | |
262 | field for the event. | |
263 | Valid for \fBKeyPress\fR and \fBKeyRelease\fR events. | |
264 | Corresponds to the %k substitution for binding scripts. | |
265 | .IP "\fB\-keysym\fR\fI name\fR" 4 | |
266 | .IX Item "-keysym name" | |
267 | \&\fIName\fR must be the name of a valid keysym, such as \fBg\fR, | |
268 | \&\fBspace\fR, or \fBReturn\fR; its corresponding | |
269 | keycode value is used as the \fIkeycode\fR field for event, overriding | |
270 | any detail specified in the base \fIevent\fR argument. | |
271 | Valid for \fBKeyPress\fR and \fBKeyRelease\fR events. | |
272 | Corresponds to the %K substitution for binding scripts. | |
273 | .IP "\fB\-mode\fR\fI notify\fR" 4 | |
274 | .IX Item "-mode notify" | |
275 | \&\fINotify\fR specifies the \fImode\fR field for the event and must be | |
276 | one of \fBNotifyNormal\fR, \fBNotifyGrab\fR, \fBNotifyUngrab\fR, or | |
277 | \&\fBNotifyWhileGrabbed\fR. | |
278 | Valid for \fBEnter\fR, \fBLeave\fR, \fBFocusIn\fR, and | |
279 | \&\fBFocusOut\fR events. | |
280 | Corresponds to the %m substitution for binding scripts. | |
281 | .IP "\fB\-override\fR\fI boolean\fR" 4 | |
282 | .IX Item "-override boolean" | |
283 | \&\fIBoolean\fR must be a boolean value; it specifies the | |
284 | \&\fIoverride_redirect\fR field for the event. | |
285 | Valid for \fBMap\fR, \fBReparent\fR, and \fBConfigure\fR events. | |
286 | Corresponds to the %o substitution for binding scripts. | |
287 | .IP "\fB\-place\fR\fI where\fR" 4 | |
288 | .IX Item "-place where" | |
289 | \&\fIWhere\fR specifies the \fIplace\fR field for the event; it must be | |
290 | either \fBPlaceOnTop\fR or \fBPlaceOnBottom\fR. | |
291 | Valid for \fBCirculate\fR events. | |
292 | Corresponds to the %p substitution for binding scripts. | |
293 | .IP "\fB\-root\fR\fI window\fR" 4 | |
294 | .IX Item "-root window" | |
295 | \&\fIWindow\fR must be either a window path name or an integer window | |
296 | identifier; it specifies the \fIroot\fR field for the event. | |
297 | Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, | |
298 | \&\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR | |
299 | events. | |
300 | Corresponds to the %R substitution for binding scripts. | |
301 | .IP "\fB\-rootx\fR\fI coord\fR" 4 | |
302 | .IX Item "-rootx coord" | |
303 | \&\fICoord\fR must be a screen distance; it specifies the \fIx_root\fR | |
304 | field for the event. | |
305 | Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, | |
306 | \&\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR | |
307 | events. Corresponds to the %X substitution for binding scripts. | |
308 | .IP "\fB\-rooty\fR\fI coord\fR" 4 | |
309 | .IX Item "-rooty coord" | |
310 | \&\fICoord\fR must be a screen distance; it specifies the \fIy_root\fR | |
311 | field for the event. | |
312 | Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, | |
313 | \&\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR | |
314 | events. | |
315 | Corresponds to the %Y substitution for binding scripts. | |
316 | .IP "\fB\-sendevent\fR\fI boolean\fR" 4 | |
317 | .IX Item "-sendevent boolean" | |
318 | \&\fBBoolean\fR must be a boolean value; it specifies the \fIsend_event\fR | |
319 | field for the event. Valid for all events. Corresponds to the | |
320 | %E substitution for binding scripts. | |
321 | .IP "\fB\-serial\fR\fI number\fR" 4 | |
322 | .IX Item "-serial number" | |
323 | \&\fINumber\fR must be an integer; it specifies the \fIserial\fR field | |
324 | for the event. Valid for all events. | |
325 | Corresponds to the %# substitution for binding scripts. | |
326 | .IP "\fB\-state\fR\fI state\fR" 4 | |
327 | .IX Item "-state state" | |
328 | \&\fIState\fR specifies the \fIstate\fR field for the event. | |
329 | For \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, | |
330 | \&\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR events | |
331 | it must be an integer value. | |
332 | For \fBVisibility\fR events it must be one of \fBVisibilityUnobscured\fR, | |
333 | \&\fBVisibilityPartiallyObscured\fR, or \fBVisibilityFullyObscured\fR. | |
334 | This option overrides any modifiers such as \fBMeta\fR or \fBControl\fR | |
335 | specified in the base \fIevent\fR. | |
336 | Corresponds to the %s substitution for binding scripts. | |
337 | .IP "\fB\-subwindow\fR\fI window\fR" 4 | |
338 | .IX Item "-subwindow window" | |
339 | \&\fIWindow\fR specifies the \fIsubwindow\fR field for the event, either | |
340 | as a path name for a Tk widget or as an integer window identifier. | |
341 | Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, | |
342 | \&\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR events. | |
343 | Similar to %S substitution for binding scripts. | |
344 | .IP "\fB\-time\fR\fI integer\fR" 4 | |
345 | .IX Item "-time integer" | |
346 | \&\fIInteger\fR must be an integer value; it specifies the \fItime\fR field | |
347 | for the event. | |
348 | Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, | |
349 | \&\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, \fBMotion\fR, | |
350 | and \fBProperty\fR events. | |
351 | Corresponds to the %t substitution for binding scripts. | |
352 | .IP "\fB\-warp\fR\fI boolean\fR" 4 | |
353 | .IX Item "-warp boolean" | |
354 | \&\fIboolean\fR must be a boolean value; it specifies whether | |
355 | the screen pointer should be warped as well. | |
356 | Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, | |
357 | \&\fBButtonRelease\fR, and \fBMotion\fR events. | |
358 | .IP "\fB\-width\fR\fI size\fR" 4 | |
359 | .IX Item "-width size" | |
360 | \&\fISize\fR must be a screen distance; it specifies the \fIwidth\fR field | |
361 | for the event. | |
362 | Valid for \fBConfigure\fR events. | |
363 | Corresponds to the %w substitution for binding scripts. | |
364 | .IP "\fB\-when\fR\fI when\fR" 4 | |
365 | .IX Item "-when when" | |
366 | \&\fIWhen\fR determines when the event will be processed; it must have one | |
367 | of the following values: | |
368 | .RS 4 | |
369 | .IP "\fBnow\fR" 8 | |
370 | .IX Item "now" | |
371 | Process the event immediately, before the command returns. | |
372 | This also happens if the \fB\-when\fR option is omitted. | |
373 | .IP "\fBtail\fR" 8 | |
374 | .IX Item "tail" | |
375 | Place the event on perl/Tk's event queue behind any events already | |
376 | queued for this application. | |
377 | .IP "\fBhead\fR" 8 | |
378 | .IX Item "head" | |
379 | Place the event at the front of perl/Tk's event queue, so that it | |
380 | will be handled before any other events already queued. | |
381 | .IP "\fBmark\fR" 8 | |
382 | .IX Item "mark" | |
383 | Place the event at the front of perl/Tk's event queue but behind any | |
384 | other events already queued with \fB\-when mark\fR. | |
385 | This option is useful when generating a series of events that should | |
386 | be processed in order but at the front of the queue. | |
387 | .RE | |
388 | .RS 4 | |
389 | .RE | |
390 | .IP "\fB\-x\fR\fI coord\fR" 4 | |
391 | .IX Item "-x coord" | |
392 | \&\fICoord\fR must be a screen distance; it specifies the \fIx\fR field | |
393 | for the event. | |
394 | Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, | |
395 | \&\fBButtonRelease\fR, \fBMotion\fR, \fBEnter\fR, \fBLeave\fR, | |
396 | \&\fBExpose\fR, \fBConfigure\fR, \fBGravity\fR, and \fBReparent\fR | |
397 | events. | |
398 | Corresponds to the the %x substitution for binding scripts. | |
399 | If \fIWindow\fR is empty the coordinate is relative to the | |
400 | screen, and this option corresponds to the %X substitution | |
401 | for binding scripts. | |
402 | .IP "\fB\-y\fR\fI coord\fR" 4 | |
403 | .IX Item "-y coord" | |
404 | \&\fICoord\fR must be a screen distance; it specifies the \fIy\fR | |
405 | field for the event. | |
406 | Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR, | |
407 | \&\fBButtonRelease\fR, \fBMotion\fR, \fBEnter\fR, \fBLeave\fR, | |
408 | \&\fBExpose\fR, \fBConfigure\fR, \fBGravity\fR, and \fBReparent\fR | |
409 | events. | |
410 | Corresponds to the the %y substitution for binding scripts. | |
411 | If \fIWindow\fR is empty the coordinate is relative to the | |
412 | screen, and this option corresponds to the %Y substitution | |
413 | for binding scripts. | |
414 | .Sp | |
415 | Any options that are not specified when generating an event are filled | |
416 | with the value 0, except for \fIserial\fR, which is filled with the | |
417 | next X event serial number. | |
418 | .SH "VIRTUAL EVENT EXAMPLES" | |
419 | .IX Header "VIRTUAL EVENT EXAMPLES" | |
420 | In order for a virtual event binding to trigger, two things must | |
421 | happen. First, the virtual event must be defined with the | |
422 | \&\fBeventAdd\fR method. Second, a binding must be created for | |
423 | the virtual event with the \fBbind\fR method. | |
424 | Consider the following virtual event definitions: | |
425 | .PP | |
426 | .Vb 4 | |
427 | \& $widget->eventAdd('<<Paste>>' => '<Control-y>'); | |
428 | \& $widget->eventAdd('<<Paste>>' => '<Button-2>'); | |
429 | \& $widget->eventAdd('<<Save>>' => '<Control-X><Control-S>'); | |
430 | \& $widget->eventAdd('<<Save>>' => '<Shift-F12>'); | |
431 | .Ve | |
432 | .PP | |
433 | In the \fBbind\fR method, a virtual event can be bound like any other | |
434 | builtin event type as follows: | |
435 | .PP | |
436 | .Vb 2 | |
437 | \& $entry->bind('Tk::Entry', '<<Paste>>' => sub { | |
438 | \& $entry->Insert($entry->selectionGet) }); | |
439 | .Ve | |
440 | .PP | |
441 | The double angle brackets are used to specify that a virtual event is being | |
442 | bound. If the user types Control-y or presses button 2, or if | |
443 | a \fB<<Paste>>\fR virtual event is synthesized with \fBeventGenerate\fR, | |
444 | then the \fB<<Paste>>\fR binding will be invoked. | |
445 | .PP | |
446 | If a virtual binding has the exact same sequence as a separate | |
447 | physical binding, then the physical binding will take precedence. | |
448 | Consider the following example: | |
449 | .PP | |
450 | .Vb 3 | |
451 | \& $mw->eventAdd('<<Paste>>' => '<Control-y>','<Meta-Control-y>'); | |
452 | \& $mw->bind('Tk::Entry', '<Control-y>' => sub{print 'Control-y'}); | |
453 | \& $mw->bind('Tk::Entry', '<<Paste>>' => sub{print 'Paste'}); | |
454 | .Ve | |
455 | .PP | |
456 | When the user types Control-y the \fB<Control-y>\fR binding | |
457 | will be invoked, because a physical event is considered | |
458 | more specific than a virtual event, all other things being equal. | |
459 | However, when the user types Meta-Control-y the | |
460 | \&\fB<<Paste>>\fR binding will be invoked, because the | |
461 | \&\fBMeta\fR modifier in the physical pattern associated with the | |
462 | virtual binding is more specific than the \fB<Control-y\fR> sequence for | |
463 | the physical event. | |
464 | .PP | |
465 | Bindings on a virtual event may be created before the virtual event exists. | |
466 | Indeed, the virtual event never actually needs to be defined, for instance, | |
467 | on platforms where the specific virtual event would meaningless or | |
468 | ungeneratable. | |
469 | .PP | |
470 | When a definition of a virtual event changes at run time, all windows | |
471 | will respond immediately to the new definition. | |
472 | Starting from the preceding example, if the following code is executed: | |
473 | .PP | |
474 | .Vb 2 | |
475 | \& $entry->bind(ref($entry), '<Control-y>' => undef); | |
476 | \& $entry->eventAdd('<<Paste>>' => '<Key-F6>'); | |
477 | .Ve | |
478 | .PP | |
479 | the behavior will change such in two ways. First, the shadowed | |
480 | \&\fB<<Paste>>\fR binding will emerge. | |
481 | Typing Control-y will no longer invoke the \fB<Control-y>\fR binding, | |
482 | but instead invoke the virtual event \fB<<Paste>>\fR. Second, | |
483 | pressing the F6 key will now also invoke the \fB<<Paste>>\fR binding. | |
484 | .SH "SEE ALSO" | |
485 | .IX Header "SEE ALSO" | |
486 | Tk::bind | |
487 | Tk::callbacks | |
488 | .SH "KEYWORDS" | |
489 | .IX Header "KEYWORDS" | |
490 | event, binding, define, handle, virtual event |