| 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 | |