.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "bindtags 3"
.TH bindtags 3 2023-07-25 "perl v5.38.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Tk::bindtags \- Determine which bindings apply to a window, and order of evaluation
.SH SYNOPSIS
.IX Header "SYNOPSIS"
\&\fR\f(CI$widget\fR\fI\fR\->\fBbindtags\fR([\fItagList\fR]);
.PP
\&\fR\f(CI@tags\fR\fI\fR = \fI\fR\f(CI$widget\fR\fI\fR\->\fBbindtags\fR;
.SH DESCRIPTION
.IX Header "DESCRIPTION"
When a binding is created with the \fBbind\fR command, it is
associated either with a particular window such as \fR\f(CI$widget\fR\fI\fR,
a class name such as \fBTk::Button\fR, the keyword \fBall\fR, or any
other string.
All of these forms are called \fIbinding tags\fR.
Each window has a list of binding tags 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 binding
that matches the given tag and event is executed.
See the Tk::bind documentation for more information on the matching
process.
.PP
By default, each window has four binding tags consisting of the
the window's class name, name of the window, the name of the window's
nearest toplevel ancestor, and \fBall\fR, in that order.
Toplevel windows have only three tags by default, since the toplevel
name is the same as that of the window.
.PP
Note that this order is \fIdifferent\fR from 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.
.PP
The \fBbindtags\fR command allows the binding tags for a window to be
read and modified.
.PP
If \fR\f(CI$widget\fR\fI\fR\->\fBbindtags\fR is invoked without an argument, then the
current set of binding tags for \f(CW$widget\fR is returned as a list.
If the \fItagList\fR argument is specified to \fBbindtags\fR,
then it must be a reference to and array; the tags for \f(CW$widget\fR are changed
to the elements of the array. (A reference to an anonymous array can
be created by enclosin the elements in \fB[ ]\fR.)
The elements of \fItagList\fR 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 \fItagList\fR determines the order in
which binding callbacks are executed in response to events.
For example, the command
.PP
.Vb 1
\& $b\->bindtags([$b,ref($b),$b\->toplevel,\*(Aqall\*(Aq])
.Ve
.PP
applies the Tcl/Tk binding order which binding callbacks will be
evaluated for a button (say) \fR\f(CB$b\fR\fB\fR so that \fB\fR\f(CB$b\fR\fB\fR's instance bindings
are invoked first, following by bindings for \fB\fR\f(CB$b\fR\fB\fR's class, followed by
bindings for \fB\fR\f(CB$b\fR\fB\fR's toplevel, followed by '\fBall\fR' bindings.
.PP
If \fItagList\fR is an empty list i.e. \fB[]\fR, then the binding
tags for \f(CW$widget\fR are returned to the perl/Tk default state described above.
.PP
The \fBbindtags\fR command may be used to introduce arbitrary
additional binding tags for a window, or to remove standard tags.
For example, the command
.PP
.Vb 1
\& $b\->bindtags([\*(AqTrickyButton\*(Aq,$b\->toplevel,\*(Aqall\*(Aq])
.Ve
.PP
replaces the (say) \fBTk::Button\fR tag for \fR\f(CB$b\fR\fB\fR with \fBTrickyButton\fR.
This means that the default widget bindings for buttons, which are
associated with the \fBTk::Button\fR tag, will no longer apply to \fB\fR\f(CB$b\fR\fB\fR,
but any bindings associated with \fBTrickyButton\fR (perhaps some
new button behavior) will apply.
.SH BUGS
.IX Header "BUGS"
The current mapping of the 'native' Tk behaviour of this method
i.e. returning a list but only accepting a reference to an array is
counter intuitive. The perl/Tk interface  may be tidied up, returning
a list is sensible so, most likely fix will be to allow a list to be
passed to \fIset\fR the bindtags.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Tk::bind
Tk::callbacks
.SH KEYWORDS
.IX Header "KEYWORDS"
binding, event, tag