14.6 Event Bindings

An event binding associates a callback function with any type of event. You have already seen instances of event bindings - the button widget's command property arranges for a user-defined procedure to be called on a mouse click, for example. The bind() command provides a more general (and hence low-level) access to the most fundamental events such as keyboard and mouse button presses and releases. (A mouse click is a press and release, so we are talking about really low-level events here.) Other "interesting" event types include mouse motion, the mouse pointer entering or leaving a window, and windows getting mapped or resized on the display. All widgets themselves rely on the bind method for their own functionality, and allow you to create extra bindings yourself. The bound procedure executes if the event you're tracking happens inside that widget or is related to that widget (such as a window resize).

The syntax of bind is as follows:

$widget->bind(event sequence, callback);

The event sequence is a string containing a sequence of basic events, with each basic event contained in angle brackets. Examples of event sequences are as follows:

"<a>"                   # Key "a" pressed (Control/shift/meta not
                        # pressed)
"<Control-a>            # Control and a pressed
"<Escape> <Control-a>"  # Two-event sequence
"<Button1>"             # Mouse button 1 clicked
"<Button1-Motion>"      # Mouse moves while Button 1 is down

A single event (within angle brackets) has the following generic syntax:

"<modifier-modifier...-modifier-type-detail>" 

Examples of modifiers are Control, Meta, Alt, Shift, Button1 (or B1), Button2, Double (double click), and Triple. The modifier Any is a wildcard - all possible modifiers (including none of them) match the basic event.

The type of the event is one of KeyPress, KeyRelease, ButtonPress (or Button), ButtonRelease, Enter, Leave, and Motion.

For keyboard event specifications, the detail is a textual string describing the exact key. X Windows calls this a keysym. For printable ASCII characters, the keysym is the printed character itself. Other examples of keysyms are Enter, Right, Pickup, Delete, BackSpace, Escape, Help, F1 (function key), and so on.

The most common event types are key presses and button clicks, so Tk allows an abbreviated form of binding: instead of saying <KeyPress-a>, you can say, <a>; instead of writing <Button1-ButtonPress>, you can say, <1>.

The text and canvas widgets support bindings at a finer level of granularity. They support event bindings for different tags in addition to bindings for the widget itself. bind allows you to specify the name of the tag as the first parameter and the event sequence and callback as the second and third parameters, respectively:

$text->bind('hyper-link', '<1>', \&open_page);

This code ensures that any stretch of text tagged with "hyper-link" will respond to a button click event and call the procedure open_page.

$label->bind("<Any-KeyPress>" => [\&move, Ev('k')]);
sub move {
    my $key = shift;
    if ($key eq 'k') {
       move_left();
    } elsif ($key eq 'l') {
       move_right();
    }
}