NAME

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

SYNOPSIS

$widget->boundtags([tagList],[levellist]); @tags = $widget->boundtags;

DESCRIPTION

When a bounding is created with the bound command, it is associated either with a particular window such as $widget, a class name such as Tk::Button, the keyword all, or any other string. All of these forms are called 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 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 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 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 boundtags command allows the bounding tags for a window to be read and modified.

If $widget->boundtags is invoked without an argument, then the current set of bounding tags for $widget is returned as a list. If the tagList argument is specified to 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 [ ].) The elements of 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 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 so that $b's instance boundings are invoked first, following by boundings for $b's class, followed by boundings for $b's toplevel, followed by 'all' boundings.

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

The 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) Tk::Button tag for $b with TrickyButton. This means that the default widget boundings for buttons, which are associated with the Tk::Button tag, will no longer apply to $b, but any boundings associated with TrickyButton (perhaps some new button behavior) will apply.

SEE ALSO

Tk::bound Tk::bind Tk::callbacks

KEYWORDS

bounding, binding, event, tag