24.6. Writing your handler

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.

`.char`	If the event was related to a `KeyPress` or `KeyRelease` for a key that produces a regular ASCII character, this string will be set to that character. (For special keys like delete, see the `.keysym` attribute, below.)
`.height`	If the event was a `Configure`, this attribute is set to the widget's new height in pixels.
`.keysym`	For `KeyPress` or `KeyRelease` events involving a special key, this attribute is set to the key's string name, e.g., `"Prior"` for the PageUp key. See Section 24.5, “Key names” for a complete list of `.keysym` names.
`.keysym_num`	For `KeyPress` or `KeyRelease` events, this is set to a numeric version of the `.keysym` field. For regular keys that produce a single character, this field is set to the integer value of the key's ASCII code. For special keys, refer to Section 24.5, “Key names”.
`.num`	If the event was related to a mouse button, this attribute is set to the button number (1, 2, or 3).
`.serial`	An integer serial number that is incremented every time the server processes a client request. You can use `.serial` values to find the exact time sequence of events: those with lower values happened sooner.
`.time`	This attribute is set to an integer which has no absolute meaning, but is incremented every millisecond. This allows your application to determine, for example, the length of time between two mouse clicks.
`.widget`	Always set to the widget that caused the event. For example, if the event was a mouse click that happened on a canvas, this attribute will be the actual `Canvas` widget.
`.width`	If the event was a `Configure`, this attribute is set to the widget's new width in pixels.
`.x`	The `x` coordinate of the mouse at the time of the event, relative to the upper left corner of the widget.
`.y`	The `y` coordinate of the mouse at the time of the event, relative to the upper left corner of the widget.
`.x_root`	The `x` coordinate of the mouse at the time of the event, relative to the upper left corner of the screen.
`.y_root`	The `y` coordinate of the mouse at the time of the event, relative to the upper left corner of the screen.

Here's an example of an event handler. Under Section 24.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.

Tkinter reference: a GUI for Python

24.6. Writing your handler