Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | # $Id: callbacks.pod 1.3 Thu, 27 Nov 1997 00:26:00 +0100 ach $ |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | Tk::callbacks - Specifying code for Tk to call. | |
6 | ||
7 | =for category Binding Events and Callbacks | |
8 | ||
9 | =head1 SYNOPSIS | |
10 | ||
11 | One can specify a callback in one of the following ways: | |
12 | ||
13 | Without arguments: | |
14 | ||
15 | ... => \&subname, ... | |
16 | ... => sub { ... }, ... | |
17 | ... => 'methodname', ... | |
18 | ||
19 | or with arguments: | |
20 | ||
21 | ... => [ \&subname ?, args ...? ], ... | |
22 | ... => [ sub { ... } ?, args...? ], ... | |
23 | ... => [ 'methodname' ?, args...?], ... | |
24 | ||
25 | =head1 DESCRIPTION | |
26 | ||
27 | Perl/Tk has a callback, where Tcl/Tk has a command string (i.e. a fragment of | |
28 | Tcl to be executed). A perl/Tk callback can take one of the following | |
29 | basic forms: | |
30 | ||
31 | =over 4 | |
32 | ||
33 | =item * Reference to a subroutine C<\E<amp>subname> | |
34 | ||
35 | =item * Anonymous subroutine (closure) C<sub { ... }> | |
36 | ||
37 | =item * A method name C<'methodname'> | |
38 | ||
39 | =back | |
40 | ||
41 | Any of these can be provided with arguments by enclosing them and the | |
42 | arguments in B<[]>. Here are some examples: | |
43 | ||
44 | I<$mw>->B<bind>(I<$class,> B<"E<lt>DeleteE<gt>" =E<gt> 'Delete'>); | |
45 | ||
46 | This will call I<$widget>->B<Delete>, the I<$widget> being provided (by bind) as | |
47 | the one where the Delete key was pressed. | |
48 | ||
49 | While having bind provide a widget object for you is ideal in many cases | |
50 | it can be irritating in others. Using the list form this behaviour | |
51 | can be modified: | |
52 | ||
53 | I<$a>-E<gt>B<bind>(B<"E<lt>DeleteE<gt>">,[I<$b> =E<gt> 'Delete']); | |
54 | ||
55 | because the first element I<$b> is an object bind | |
56 | will call I<$b>-E<gt>B<Delete>. | |
57 | ||
58 | Note that method/object ordering only matters for C<bind> callbacks, | |
59 | the auto-quoting in perl5.001 makes the first of these a little more readable: | |
60 | ||
61 | $w-E<gt>configure(-yscrollcommand =E<gt> [ set =E<gt> $ysb]); | |
62 | ||
63 | $w-E<gt>configure(-yscrollcommand =E<gt> [ $ysb =E<gt> 'set' ]); | |
64 | ||
65 | but both will call C<$ysb>-E<gt>set(args provided by Tk) | |
66 | ||
67 | Another use of arguments allows you to write generalized methods which are | |
68 | easier to re-use: | |
69 | ||
70 | $a-E<gt>bind("E<lt>NextE<gt>",['Next','Page']); | |
71 | ||
72 | $a-E<gt>bind("E<lt>DownE<gt>",['Next','Line']); | |
73 | ||
74 | This will call C<$a>-E<gt>I<Next>('Page') or C<$a>-E<gt>I<Next>('Line') respectively. | |
75 | ||
76 | Note that the contents of the C<[]> are evaluated by perl when the | |
77 | callback is created. It is often desirable for the arguments provided | |
78 | to the callback to depend on the details of the event which caused | |
79 | it to be executed. To allow for this callbacks can be nested using the | |
80 | C<Ev(...)> "constructor". | |
81 | C<Ev(...)> inserts callback objects into the | |
82 | argument list. When perl/Tk glue code is preparing the argument list for | |
83 | the callback it is about to call it spots these special objects and | |
84 | recursively applies the callback process to them. | |
85 | ||
86 | =head1 EXAMPLES | |
87 | ||
88 | $entry->bind('<Return>' => [$w , 'validate', Ev(['get'])]); | |
89 | ||
90 | $toplevel->bind('all', '<Visibility>', [\&unobscure, Ev('s')]); | |
91 | ||
92 | $mw->bind($class, '<Down>', ['SetCursor', Ev('UpDownLine',1)]); | |
93 | ||
94 | =head1 SEE ALSO | |
95 | ||
96 | L<Tk::bind|Tk::bind> | |
97 | L<Tk::after|Tk::after> | |
98 | L<Tk::options|Tk::options> | |
99 | L<Tk::fileevent|Tk::fileevent> | |
100 | ||
101 | =head1 KEYWORDS | |
102 | ||
103 | callback, closure, anonymous subroutine, bind | |
104 | ||
105 | =cut | |
106 | ||
107 | ## pod2man complain and I can see why | |
108 | ||
109 | #=head1 EXAMPLES | |
110 | # | |
111 | #$e-E<gt>bind('E<lt>ReturnE<gt>' =E<gt> [$w , 'validate', Ev(['get'])] ); | |
112 | # | |
113 | #$topLevelWin-E<gt>bind('all',"E<lt>VisibilityE<gt>", [\E<amp>unobscure, Ev('s')] ); | |
114 | # | |
115 | #$mw-E<gt>bind($class,"E<lt>DownE<gt>",['SetCursor', Ev('UpDownLine',1)] ); | |
116 | ||
117 | =cut | |
118 |