Tkinter 8.4 reference: a GUI for Python

You can bind a handler to an event at any of three levels:

Tkinter has a powerful and general method for allowing you to define exactly which events, both specific and general, you want to bind to handlers.

In general, an event sequence is a string containing one or more event patterns. Each event pattern describes one thing that can happen. If there is more than one event pattern in a sequence, the handler will be called only when all the patterns happen in that same sequence.

The general form of an event pattern is:

<[modifier-]...type[-detail]>

Here are some examples to give you the flavor of event patterns:

The full set of event types is rather large, but a lot of them are not commonly used. Here are most of the ones you'll need:

The modifier names that you can use in event sequences include:

You can use shorter forms of the events. Here are some examples:

Note that you can leave out the enclosing "<…>" for most single-character keypresses, but you can't do that for the space character (whose name is "<space>") or the less-than (<) character (whose name is "<less>").

The detail part of an event pattern for a KeyPress or KeyRelease event specifies which key you're binding. (See the Any modifier, above, if you want to get all keypresses or key releases).

The table below shows several different ways to name keys. See Section 30.6, “Writing your handler: The Event class”, below, for more information on Event objects, whose attributes will describe keys in these same ways.

There are many more key names for international character sets. This table shows only the “Latin-1” set for the usual USA-type 101-key keyboard. For the currently supported set, see the manual page for Tk keysym values.

The sections above tell you how to describe what events you want to handle, and how to bind them. Now let us turn to the writing of the handler that will be called when the event actually happens.

The handler will be passed an Event object that describes what happened. The handler can be either a function or a method. Here is the calling sequence for a regular function:

def handlerName ( event ):

And as a method:

    def handlerName ( self, event ):

The attributes of the Event object passed to the handler are described below. Some of these attributes are always set, but some are set only for certain types of events.

Use these masks to test the bits of the .state value to see what modifier keys and buttons were pressed during the event:

Here's an example of an event handler. Under Section 30.1, “Levels of binding”, above, there is an example showing how to bind mouse button 2 clicks on a canvas named self.canv to a handler called self.__drawOrangeBlob(). Here is that handler:

    def __drawOrangeBlob ( self, event ):
        "Draws an orange blob in self.canv where the mouse is."
        r = 5   # Blob radius
        self.canv.create_oval ( event.x-r, event.y-r,
            event.x+r, event.y+r, fill="orange" )

When this handler is called, the current mouse position is (event.x, event.y). The .create_oval() method draws a circle whose bounding box is square and centered on that position and has sides of length 2*r.

Sometimes you would like to pass other arguments to a handler besides the event.

Here is an example. Suppose your application has an array of ten checkbuttons whose widgets are stored in a list self.cbList, indexed by the checkbutton number in range(10).

Suppose further that you want to write one handler named .__cbHandler for <Button-1> events in all ten of these checkbuttons. The handler can get the actual Checkbutton widget that triggered it by referring to the .widget attribute of the Event object that gets passed in, but how does it find out that checkbutton's index in self.cbList?

It would be nice to write our handler with an extra argument for the checkbutton number, something like this:

    def __cbHandler ( self, event, cbNumber ):

But event handlers are passed only one argument, the event. So we can't use the function above because of a mismatch in the number of arguments.

Fortunately, Python's ability to provide default values for function arguments gives us a way out. Have a look at this code:

    def __createWidgets ( self ):
        …
        self.cbList = []    # Create the checkbutton list
        for i in range(10):
            cb = Checkbutton ( self, … )
            self.cbList.append ( cb )
            cb.grid( row=1, column=i )
            def handler ( event, self=self, i=i ):   
                return self.__cbHandler ( event, i )
            cb.bind ( "<Button-1>", handler )
        …
    def __cbHandler ( self, event, cbNumber ):
        …

These lines define a new function handler that expects three arguments. The first argument is the Event object passed to all event handlers, and the second and third arguments will be set to their default values—the extra arguments we need to pass it.

This technique can be extended to supply any number of additional arguments to handlers.

You can create your own new kinds of events called virtual events. You can give them any name you want so long as it is enclosed in double pairs of <<…>>.

For example, suppose you want to create a new event called <<panic>>, that is triggered either by mouse button 3 or by the pause key. To create this event, call this method on any widget w:

    w.event_add ( "<<panic>>", "<Button-3>",
                  "<KeyPress-Pause>" )

You can then use "<<panic>>" in any event sequence. For example, if you use this call:

    w.bind ( "<<panic>>", h )

any mouse button 3 or pause keypress in widget w will trigger the handler h.

See .event_add(), .event_delete(), and .event_info() under Section 25, “Universal widget methods” for more information about creating and managing virtual events.