Bind#

Binding attaches a callback to an event on a widget. The event pattern names which event fires the callback — its full grammar (types, modifiers, key symbols, and built-in virtual events) is the Events reference. Every widget carries these methods.

The canonical upstream references are the Tk bind and bindtags manual pages (Tcl 8.6).

Binding callbacks#

bind(sequence=None, func=None, add=None)

Bind func to the event sequence on this widget. func is called with one event object argument. Return "break" from the callback to stop further handling of that event.

Parameters:

  • sequence – an event pattern such as "<Button-1>" or "<<Custom>>".

  • func – the callback; receives one event argument.

  • add – "+" to add to the existing bindings instead of replacing them.

Returns:

the binding’s function id (a string) — pass it to unbind — when func is given; otherwise the current binding.

bind_all(sequence=None, func=None, add=None)

Like bind, but application-wide — the binding applies to every widget, via the all bind tag.

Returns:

the binding’s function id.

bind_class(className, sequence=None, func=None, add=None)

Bind at the widget-class level: every widget whose bind tags include className (e.g. "TButton") responds, current and future.

Returns:

the binding’s function id.

unbind(sequence, funcid=None)

Remove the binding for sequence on this widget. Pass the funcid returned by bind to remove a single added callback rather than all of them.

Returns:

None.

unbind_all(sequence)

Remove an application-wide binding made with bind_all.

Parameters:

sequence (str) – the event sequence to unbind.

Returns:

None.

unbind_class(className, sequence)

Remove a class binding made with bind_class. This affects every widget of that class, including the ones Tk installs by default — removing a built-in class binding takes that behavior away from every widget of the class.

Parameters:

  • className (str) – the Tk class name, e.g. "TEntry".

  • sequence (str) – the event sequence to unbind.

Returns:

None.

Bind tags#

bindtags(tagList=None)

Get or set this widget’s bind tags — the ordered list of names Tk searches for bindings when an event fires (by default: the widget, its class, its toplevel, and all). Pass a list or tuple to reorder or replace them — for example to insert a custom tag shared by several widgets. Call with no argument to read the current tags.

Parameters:

tagList – the new ordered tags, or omit to query.

Returns:

the current tags (a tuple) when queried, otherwise None.

Synthesizing events#

To send an event rather than receive one, use event_generate; custom <<virtual>> names are managed with event_add / event_delete. These belong to the event system — their options live in the Events reference.

See also#