Author:         Jeff Rogers <dvrsn@diphi.com>
State:          Draft
Type:           Project
Vote:           Pending
Created:        28-Aug-2012
Post-History:   
Tcl-Version:    8.7

Abstract

This TIP proposes a more modern mechanism for binding callbacks to Tk's events.

Rationale

The Tk bind' command passes details about an event to a callback script by doing a textual substitution of percent markers. This has worked well for years, however most recent code prefers to use command prefixes to which set arguments are appended rather than scripts which are evaluated. This TIP proposes such an approach for tk event binding.

Specification

A new command, "tkevent" is introduced with the following syntax:

tkevent tag sequence cmd

The tag and sequence arguments are the same as used in the bind command. The cmd is evaluated by appending a single argument which is a dictionary containing the event details. The implementation of cmd can retrieve details of the event using that dictionary.

Bindings created by tkevent are compatible with those created by bind. When a sequence is bound to a tag using tkevent, it replaces any previous binding, and vice versa. Appending to a binding with "bind tag sequence +script" may not work as expected.

The possible keys in the dict passed to the handler are:

        serial        above         button
        count         detail        focus
        height        window        keycode
        mode          override_redirect
        place         state         time
        width         x             y
        character     border_width  delta
        send_event    keysym        keysym_num
        property      root          subwindow
        type          window        xroot
        yroot

These keys are intended to be be the same as the options to event generate where applicable.

Not all values are legal for all event types; where a key is not legal for an event type, it will not be present in the dictionary when the cmd bound to that event is evaluated.

Reference Implementation

A sample implementation of these commands in pure tcl is available at http://wiki.tcl.tk/tkevent

Cross-Compatibility with Bind

Except for the "+script" feature, bind and tkevent support identical functionality, and either could be implemented in terms of the other. If bind as a core command was dropped in favor of tkevent, it could be provided as a library implementation.

Copyright