TIP #419: A New Command for Binding to Tk Events
_____________________________________________________________________________
TIP:	419
Title:	A New Command for Binding to Tk Events
Version:	$Revision: 1.2 $
Authors:	Jeff Rogers <dvrsn@diphi.com>
State:	Draft
Type:	Project
Tcl-Version:	8.7
Vote:	Pending
Created:	Tue Aug 28 00:00:00 UTC 2012
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
This document has been placed in the public domain.
_____________________________________________________________________________
Colophon
TIP AutoGenerator - written by Donal K. Fellows