Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | # Copyright (c) 1990 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::bindtags - Determine which bindings apply to a window, and order of evaluation | |
11 | ||
12 | =for category Binding Events and Callbacks | |
13 | ||
14 | =head1 SYNOPSIS | |
15 | ||
16 | I<$widget>-E<gt>B<bindtags>([I<tagList>]); | |
17 | I<@tags> = I<$widget>-E<gt>B<bindtags>; | |
18 | ||
19 | =head1 DESCRIPTION | |
20 | ||
21 | When a binding is created with the B<bind> command, it is | |
22 | associated either with a particular window such as I<$widget>, | |
23 | a class name such as B<Tk::Button>, the keyword B<all>, or any | |
24 | other string. | |
25 | All of these forms are called I<binding tags>. | |
26 | Each window has a list of binding tags that determine how | |
27 | events are processed for the window. | |
28 | When an event occurs in a window, it is applied to each of the | |
29 | window's tags in order: for each tag, the most specific binding | |
30 | that matches the given tag and event is executed. | |
31 | See the L<Tk::bind> documentation for more information on the matching | |
32 | process. | |
33 | ||
34 | By default, each window has four binding tags consisting of the | |
35 | the window's class name, name of the window, the name of the window's | |
36 | nearest toplevel ancestor, and B<all>, in that order. | |
37 | Toplevel windows have only three tags by default, since the toplevel | |
38 | name is the same as that of the window. | |
39 | ||
40 | Note that this order is I<different> from order used by Tcl/Tk. | |
41 | Tcl/Tk has the window ahead of the class name in the binding order. | |
42 | This is because Tcl is procedural rather than object oriented and | |
43 | the normal way for Tcl/Tk applications to override class bindings | |
44 | is with an instance binding. However, with perl/Tk the normal way | |
45 | to override a class binding is to derive a class. The perl/Tk order | |
46 | causes instance bindings to execute after the class binding, and | |
47 | so instance bind callbacks can make use of state changes (e.g. changes | |
48 | to the selection) than the class bindings have made. | |
49 | ||
50 | The B<bindtags> command allows the binding tags for a window to be | |
51 | read and modified. | |
52 | ||
53 | If I<$widget>-E<gt>B<bindtags> is invoked without an argument, then the | |
54 | current set of binding tags for $widget is returned as a list. | |
55 | If the I<tagList> argument is specified to B<bindtags>, | |
56 | then it must be a reference to and array; the tags for $widget are changed | |
57 | to the elements of the array. (A reference to an anonymous array can | |
58 | be created by enclosin the elements in B<[ ]>.) | |
59 | The elements of I<tagList> may be arbitrary strings or widget objects, | |
60 | if no window exists for an object at the time an event is processed, | |
61 | then the tag is ignored for that event. | |
62 | The order of the elements in I<tagList> determines the order in | |
63 | which binding callbacks are executed in response to events. | |
64 | For example, the command | |
65 | ||
66 | $b->bindtags([$b,ref($b),$b->toplevel,'all']) | |
67 | ||
68 | applies the Tcl/Tk binding order which binding callbacks will be | |
69 | evaluated for a button (say) B<$b> so that B<$b>'s instance bindings | |
70 | are invoked first, following by bindings for B<$b>'s class, followed by | |
71 | bindings for B<$b>'s toplevel, followed by 'B<all>' bindings. | |
72 | ||
73 | If I<tagList> is an empty list i.e. B<[]>, then the binding | |
74 | tags for $widget are returned to the perl/Tk default state described above. | |
75 | ||
76 | The B<bindtags> command may be used to introduce arbitrary | |
77 | additional binding tags for a window, or to remove standard tags. | |
78 | For example, the command | |
79 | ||
80 | $b->bindtags(['TrickyButton',$b->toplevel,'all']) | |
81 | ||
82 | replaces the (say) B<Tk::Button> tag for B<$b> with B<TrickyButton>. | |
83 | This means that the default widget bindings for buttons, which are | |
84 | associated with the B<Tk::Button> tag, will no longer apply to B<$b>, | |
85 | but any bindings associated with B<TrickyButton> (perhaps some | |
86 | new button behavior) will apply. | |
87 | ||
88 | =head1 BUGS | |
89 | ||
90 | The current mapping of the 'native' Tk behaviour of this method | |
91 | i.e. returning a list but only accepting a reference to an array is | |
92 | counter intuitive. The perl/Tk interface may be tidied up, returning | |
93 | a list is sensible so, most likely fix will be to allow a list to be | |
94 | passed to /fIset/fR the bindtags. | |
95 | ||
96 | =head1 SEE ALSO | |
97 | ||
98 | L<Tk::bind|Tk::bind> | |
99 | L<Tk::callbacks|Tk::callbacks> | |
100 | ||
101 | =head1 KEYWORDS | |
102 | ||
103 | binding, event, tag | |
104 | ||
105 | =cut | |
106 |