# -*- mode: text; fill-column: 80; comment-column: 80; -*-

# Tk::boundtags --
#
#	This file provides out of bounds mechanics.
#
# Copyright (c) 2000-2007 Meccanomania
#
# See the file "license.terms" for information on usage and redistribution
# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
#
# svn: @(#) $Id: boundtags.pod 58 2008-01-10 23:29:20Z meccanomania $
#-------------------------------------------------------------------------------

=head1 NAME

Tk::boundtags - Determine which boundings apply to a window, and order
of evaluation  

=for category Binding Events and Callbacks

=head1 SYNOPSIS

I<$widget>-E<gt>B<boundtags>([I<tagList>],[I<levellist>]);
I<@tags> = I<$widget>-E<gt>B<boundtags>;

=head1 DESCRIPTION

When a bounding is created with the B<bound> command, it is associated either
with a particular window such as I<$widget>, a class name such as B<Tk::Button>,
the keyword B<all>, or any other string. All of these forms are called
I<bounding tags>. Each window has a list of bounding tags and levels that
determine how events are processed for the window.  When an event occurs in a
window, it is applied to each of the window's tags in order:  for each tag, the
most specific bounding that matches the given tag and event is executed. See the
L<Tk::bound> documentation for more information on the matching process.

By default, each window has four bounding tags consisting of the the window's
class name, name of the window, the name of the window's nearest toplevel
ancestor, and B<all>, in that order. Toplevel windows have only three tags by
default, since the toplevel name is the same as that of the window.

Note that the out of bounds tag order is I<different> from binding tag order
used by Tcl/Tk. Tcl/Tk has the window ahead of the class name in the binding
order. This is because Tcl is procedural rather than object oriented and the
normal way for Tcl/Tk applications to override class bindings is with an instance
binding. However, with perl/Tk the normal way to override a class binding is to
derive a class. The perl/Tk order causes instance bindings to execute after the
class binding, and so instance bind callbacks can make use of state changes
(e.g. changes to the selection) than the class bindings have made.

The B<boundtags> command allows the bounding tags for a window to be read and
modified. 

If I<$widget>-E<gt>B<boundtags> is invoked without an argument, then the current
set of bounding tags for $widget is returned as a list. If the I<tagList>
argument is specified to B<boundtags>, then it must be a reference to and array;
the tags for $widget are changed to the elements of the array. (A reference to
an anonymous array can be created by enclosing the elements in B<[ ]>.) The
elements of I<tagList> may be arbitrary strings or widget objects, if no window
exists for an object at the time an event is processed, then the tag is ignored
for that event. The order of the elements in I<tagList> determines the order in
which binding callbacks are executed in response to events. For example, the
command

$b->boundtags([$b,ref($b),$b->toplevel,'all'], [ 1, 1, 1, 1 ])

applies the Tcl/Tk bounding order which binding callbacks will be evaluated for
a button (say) B<$b> so that B<$b>'s instance boundings are invoked first,
following by boundings for B<$b>'s class, followed by boundings for B<$b>'s
toplevel, followed by 'B<all>' boundings. 

If I<tagList> is an empty list i.e. B<[]>, then the bounding tags for $widget
are returned to the perl/Tk default state described above. 

The B<boundtags> command may be used to introduce arbitrary additional bounding
tags for a window, or to remove standard tags. For example, the command

$b->boundtags(['TrickyButton',$b->toplevel,'all'], [ 1, 1, 1, 1 ])

replaces the (say) B<Tk::Button> tag for B<$b> with B<TrickyButton>. This means
that the default widget boundings for buttons, which are associated with the
B<Tk::Button> tag, will no longer apply to B<$b>, but any boundings associated
with B<TrickyButton> (perhaps some new button behavior) will apply.

=head1 SEE ALSO

L<Tk::bound|Tk::bound>
L<Tk::bind|Tk::bind>
L<Tk::callbacks|Tk::callbacks>

=head1 KEYWORDS

bounding, binding, event, tag

=cut
