home *** CD-ROM | disk | FTP | other *** search
/ Netrunner 2004 October / NETRUNNER0410.ISO / regular / ActivePerl-5.8.4.810-MSWin32-x86.msi / _62752b07fac6dfa05a2061b448ed5c43 < prev    next >
Text File  |  2004-06-01  |  4KB  |  107 lines
  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.  
  107.