Previous section   Next section

Practical Programming in Tcl & Tk, Third Edition
By Brent B. Welch

Table of Contents
Chapter 26.  Binding Commands to Events

The bind Command

The bind command creates event bindings, and it returns information about current bindings. The general form of the command is:

bind bindingTag ?eventSequence? ?command?

If all arguments are present, a binding from eventSequence to command is defined for bindingTag. The bindingTag is typically a widget class name (e.g., Button) or a widget instance name (e.g., .buttons.foo). Binding tags are described in more detail later. Called with a single argument, a binding tag, bind returns the events for which there are command bindings:

bind Menubutton
=> <Key-Return> <Key-space> <ButtonRelease-1>
     <B1-Motion> <Motion> <Button-1> <Leave> <Enter>

The events in this example are keystroke and mouse events. <Button-1> is the event generated when the user presses the first, or left-hand, mouse button. <B1-Motion> is generated when the user moves the mouse while holding down the first mouse button. The <Key-space> event occurs when the user presses the space bar. The surrounding angle brackets delimit a single event, and you can define bindings for a sequence of events. The event syntax is described on page 371, and event sequences are described on page 377.

If bind is given a binding tag and an event sequence, it returns the Tcl command bound to that event sequence:

bind Menubutton <B1-Motion>
=> tkMbMotion %W down %X %Y

The Tcl commands in event bindings support an additional syntax for event keywords. These keywords begin with a percent sign and have one more character that identifies some attribute of the event. The keywords are substituted with event-specific data before the Tcl command is evaluated. For example, %W is replaced with the widget's pathname. The %X and %Y keywords are replaced with the coordinates of the event relative to the screen. The %x and %y keywords are replaced with the coordinates of the event relative to the widget. The event keywords are summarized on page 379.

The % substitutions are performed throughout the entire command bound to an event, without regard to other quoting schemes. You must use %% to obtain a single percent sign. For this reason you should make your binding commands short, adding a new procedure if necessary (e.g., tkMbMotion), instead of littering percent signs throughout your code.

A new binding is created by specifying a binding tag, an event sequence, and a command:

bind Menubutton <B1-Motion> {tkMbMotion %W down %X %Y}

If the first character of the binding command is +, the command (without the +) is added to the commands, if any, for that event and binding tag:

bind bindingTag event {+ command args}

To delete a binding for an event, bind the event to the null string:

bind bindingTag event {}


Bindings execute in the global scope.

When a binding is triggered, the command is evaluated at the global scope. A very common mistake is to confuse the scope that is active when the bind command creates a binding, and the scope that is active when the binding is triggered. The same problem crops up with the commands associated with buttons, and it is discussed in more detail at the beginning of Chapter 27.

      Previous section   Next section