Previous | Tutorial index | Next

Tutorial 6: Event Handling and Callback Functions in Tkinter

Learning Objectives

• Discuss the functions and methods provided in the Tkinter module (event‑related).
• Understand the event‑driven programming paradigm and its contrast with procedural code.
• Master the command option, the bind() method, and Tkinter variable classes.
• Learn how to pass arguments to callbacks using lambda functions and avoid common pitfalls.
• Implement advanced event handling including keyboard shortcuts, mouse events, and variable tracing.

1. Introduction – What Is Event‑Driven Programming?

In traditional procedural programming, you write code that runs from top to bottom, and the program terminates when it finishes. But a GUI application is different—it waits. It waits for the user to do something: click a button, press a key, move the mouse, or close the window.

This paradigm is called event‑driven programming. Your program defines a set of event handlers (functions) and then enters an infinite event loop (mainloop()). The event loop constantly monitors the system for events and dispatches them to the appropriate handlers.

Think of a restaurant:

• Event loop: The host stands at the door waiting for customers.
• Events: A customer arrives, a customer orders, a customer asks for the bill.
• Handlers: Seat the customer, take the order to the kitchen, prepare the bill.

Tkinter provides three primary mechanisms for handling events:

1. command – The simplest, used specifically for button‑like widgets.
2. bind() – The most flexible, attaches any event to any widget.
3. Variable classes (StringVar, etc.) – Automatically trigger callbacks when values change via trace().

We will explore each in depth.

2. Part 1: The command Option – The Simplest Handler

2.1 How It Works

The command option is available on widgets that are "clickable" or "actionable": Button, Checkbutton, Radiobutton, Menu, Scale, and Spinbox. When the user activates the widget (clicks, selects, or changes it), the function referenced by command is called with no arguments (by default).

2.2 Basic Syntax

def say_hello():
    print("Hello, Tkinter!")

btn = tk.Button(root, text="Say Hello", command=say_hello)
btn.pack()

Crucial: When you assign command=say_hello, you are passing the function object (without parentheses). If you write command=say_hello(), you would call the function immediately at creation time, and the button would do nothing on click.

2.3 Widgets That Support command

2.4 The state Option and Command Execution

You can disable a button using state=tk.DISABLED. When disabled, the command will not fire.

btn.config(state=tk.DISABLED)  # Grayed out, cannot be clicked
btn.config(state=tk.NORMAL)    # Re‑enable

2.5 The invoke() Method – Programmatic Click

You can simulate a button click programmatically:

btn.invoke()   # Calls the command function immediately

3. Part 2: The bind() Method – Universal Event Handling

3.1 Why Do We Need bind()?

command is limited to a small set of widgets and only handles the "activation" event. bind() works with any widget (including root, Frame, Label) and can listen for any event—key presses, mouse movements, focus changes, window resizing, etc.

3.2 Syntax

widget.bind(event_sequence, callback_function)

• event_sequence – a string describing the event (e.g., "<Button-1>").
• callback_function – a function that receives one argument, an Event object containing details about the event.

3.3 The Event Object – What's Inside?

When a bound callback is called, Tkinter passes an Event object with useful attributes:

3.4 Common Event Patterns

3.5 Binding Levels – Order Matters

Tkinter has three levels of binding, in order of precedence (highest to lowest):

1. Instance binding – widget.bind(event, handler) – specific to one widget.
2. Class binding – widget.bind_class(className, event, handler) – applies to all widgets of a class (e.g., all Entry widgets).
3. Application binding – root.bind_all(event, handler) – applies to all widgets in the application, globally.

Crucial: Multiple bindings can fire for the same event. A key press, for example, will first trigger an instance binding, then a class binding, then an application binding.

3.6 Stopping Event Propagation – return "break"

If you want to prevent further handlers from processing the event (e.g., stop an Entry widget from inserting a character), return the string "break" from your callback:

def prevent_input(event):
    print("No typing allowed!")
    return "break"   # Prevents the character from being inserted

entry.bind("<Key>", prevent_input)

3.7 Unbinding – unbind()

To remove a binding, use:

widget.unbind("<Key>")   # Removes the binding for that event on this widget

4. Part 3: Tkinter Variable Classes – StringVar, IntVar, DoubleVar, BooleanVar

4.1 What Are They?

These are Tkinter's special "observable" variables. When you change their value using .set(value), any widget that is linked to them via the textvariable, variable, or value options automatically updates its display. This is much more efficient than manually calling .config().

4.2 Creating and Using Variables

name_var = tk.StringVar()          # Default value is empty string
age_var = tk.IntVar(value=18)      # Default value is 18
is_student = tk.BooleanVar(value=True)

4.3 Linking to Widgets

# Link to Entry – changes to the Entry update the variable, and vice versa
entry = tk.Entry(root, textvariable=name_var)
entry.pack()

# Link to Label – shows whatever is in name_var
label = tk.Label(root, textvariable=name_var)
label.pack()

# Link to Checkbutton
check_var = tk.IntVar()
check = tk.Checkbutton(root, text="Agree", variable=check_var)

4.4 The Most Powerful Feature: trace()

trace() allows you to attach a callback that runs whenever the variable changes. This is incredibly powerful for validation, auto‑completion, and dynamic UI updates.

Syntax:

variable.trace(mode, callback)

• mode – "w" (write, when value changes), "r" (read, when value is accessed), "u" (unset, when variable is deleted), or a combination.
• callback – a function that takes three arguments: (var_name, var_index, operation).

Example: Auto‑uppercase

def on_name_change(var_name, var_index, operation):
    current = name_var.get()
    name_var.set(current.upper())   # Force uppercase

name_var = tk.StringVar()
name_var.trace("w", on_name_change)
entry = tk.Entry(root, textvariable=name_var)
entry.pack()

Caution: Recursive modification (changing the variable inside its own trace callback) can cause infinite loops. Use carefully.

4.5 Removing a Trace

The .trace() method returns a trace ID (a string). You can remove it using .trace_remove(trace_id).

trace_id = name_var.trace("w", callback)
# Later:
name_var.trace_remove(trace_id)

5. Part 4: Lambda Functions in Callbacks – Passing Arguments

5.1 The Problem

The command option and bind() callbacks are designed to receive no arguments (command) or one argument (the event object). But what if you need to pass custom data to your function?

5.2 The Solution: Lambda Functions

A lambda function acts as a wrapper that calls your function with the required arguments.

def save_file(filename):
    print(f"Saving {filename}...")

btn1 = tk.Button(root, text="Save Report", command=lambda: save_file("report.txt"))
btn2 = tk.Button(root, text="Save Data", command=lambda: save_file("data.csv"))

5.3 Important: The "Late Binding" Trap

This is one of the most common bugs in Tkinter. If you create lambda functions inside a loop and capture a loop variable, all lambdas may end up using the last value of that variable.

Buggy Example:

buttons = []
for i in range(3):
    btn = tk.Button(root, text=f"Button {i}", command=lambda: print(i))
    btn.pack()
    buttons.append(btn)
# Clicking any button prints "2" (the last value), not the expected 0, 1, 2!

Why? The lambda function does not evaluate i at the time of creation; it captures a reference to the variable i. By the time you click the button, the loop has finished and i == 2.

The Fix – Default Argument Binding:

for i in range(3):
    btn = tk.Button(root, text=f"Button {i}", command=lambda val=i: print(val))
    btn.pack()

Here, val=i evaluates i immediately and stores its value in the lambda's default argument.

5.4 Using Lambda with bind() – Passing Extra Arguments

Since bind() callbacks receive an event object, you can use a lambda to pass both the event and custom data:

def on_click(event, custom_arg):
    print(f"Clicked {custom_arg} at x={event.x}")

widget.bind("<Button-1>", lambda event: on_click(event, "Hello"))

5.5 Lambda vs. functools.partial

An alternative to lambda is functools.partial, which is sometimes more readable:

from functools import partial
btn = tk.Button(root, text="Save", command=partial(save_file, "report.txt"))

6. Part 5: Advanced Event Handling Techniques

6.1 Keyboard Shortcuts (Accelerators)

You can bind global keyboard shortcuts to the root window:

root.bind("<Control-s>", lambda e: save_file("document.txt"))
root.bind("<Escape>", lambda e: root.destroy())

On macOS, Command is represented by <Command> or <Meta>.

6.2 Mouse Wheel on Windows and Linux

• Windows / Linux: <MouseWheel>
• macOS: <MouseWheel> also works, but you need to check event.delta for direction.

6.3 Combining Multiple Events

Some widgets (like Listbox) require double‑click detection:

def on_double_click(event):
    widget = event.widget
    selection = widget.curselection()
    if selection:
        print(f"Selected item: {widget.get(selection[0])}")

listbox.bind("<Double-Button-1>", on_double_click)

6.4 Event break – Preventing Default Behavior

Returning "break" stops the event from being processed further. This is useful for custom input validation:

def numeric_only(event):
    if not event.char.isdigit():
        return "break"   # Don't insert the character

entry.bind("<Key>", numeric_only)

7. Check Your Understanding (Quizzes)

Quiz 1: Multiple Choice

1. Which of the following widgets does NOT support the command option?
   • A) Button
   • B) Label
   • C) Checkbutton
   • D) Radiobutton

1. A function bound with bind() receives how many arguments?
   • A) None
   • B) One (the event object)
   • C) Two (event and widget)
   • D) It depends on the widget

1. What is the correct way to get the character pressed from a keyboard event?
   • A) event.key
   • B) event.char
   • C) event.value
   • D) event.keysym

1. Why does the following code print "2" for all buttons when clicked?

   for i in range(3):
       tk.Button(root, text=str(i), command=lambda: print(i)).pack()
   

   • A) Because the buttons share the same memory address.
   • B) Because lambda captures i by reference, and by the time you click, i == 2.
   • C) Because i is a local variable that is garbage‑collected.
   • D) This code actually prints 0, 1, 2 correctly.

1. Which method is used to stop an event from propagating to other bindings?
   • A) event.stop()
   • B) return "break"
   • C) event.prevent()
   • D) return False

Quiz 2: True or False

1. True / False: The command option can be used with an Entry widget to validate text as the user types.

1. True / False: Tkinter variable classes (StringVar, IntVar) automatically update their linked widgets without any extra calls.

1. True / False: A lambda function inside a loop that uses a loop variable will always capture the current value at the time of loop iteration.

1. True / False: The <Key> event triggers for modifier keys like Shift and Ctrl.

1. True / False: The trace() method on a StringVar can be used to run a callback every time the variable is read ("r" mode).

Quiz 3: Fill in the Blanks

1. To pass arguments to a command callback, you typically use a ________ function.

1. The event pattern for a left‑mouse click is <________-1>.

1. The method that programmatically triggers a button's command is .________().

1. To remove a binding, you use .________(event_sequence).

1. The three trace modes are "w" (write), "r" (read), and "____" (unset).

8. Hands‑On Lab (In‑Class Exercises)

Exercise 1: Command and Lambda Practice

Create a window with three buttons labelled "Red", "Green", and "Blue". When clicked, each button should change the background colour of a central Label to the corresponding colour. Use a single callback function that accepts a colour argument, and use lambda (with default argument binding) to pass the colours.

Exercise 2: Keyboard Shortcut Dashboard

Create a simple dashboard with a Label that displays the text "Press a key". Bind the <Key> event to the root window. Whenever the user presses a key, update the label to show: "Key pressed: {char} (Keysym: {keysym}, Code: {keycode})". Use the event object to extract the information.

Exercise 3: Input Validation with trace

Create an Entry that only accepts numeric digits (0‑9). Use a StringVar with a trace("w", callback) that checks the new value. If the new value contains any non‑digit, revert it to the previous valid value (you will need to store the previous value in a separate variable).

Exercise 4: Mouse Events on a Canvas

Draw a circle on a Canvas. Bind <Enter> and <Leave> events to the circle (or the canvas) to change its colour when the mouse hovers over it. Also bind <Button-1> to print the (x, y) coordinates of the click on the canvas.

Exercise 5: Dynamic Button Creation (and the Lambda Trap)

Write a loop that creates 5 buttons numbered 1 to 5. Each button, when clicked, should print its own number. You must use a lambda and avoid the late‑binding trap. Test it thoroughly.

9. Homework Assignment

Objective

Demonstrate mastery of event handling by building a semi‑functional GUI application that uses command, bind, variable trace, and lambda functions appropriately.

Part A: Interactive Drawing Tool (20 points)

Build a simple drawing tool on a Canvas (400x400). The app must have:

• Canvas – the drawing area.
• Buttons at the bottom: "Draw", "Clear", "Exit".
• Bindings:
  1. <Button-1> (mouse click) on the canvas should draw a small filled circle (radius 5) at the click position.
  2. <B1-Motion> (mouse drag) should draw circles along the mouse path (creating a continuous line effect). Hint: This is a classic drawing app feature.
  3. <Button-3> (right‑click) on the canvas should change the drawing colour to a random colour from a predefined list.
• Global key shortcuts:
  • Press c key to clear the canvas.
  • Press d key to toggle between "Draw mode" (always draw circles) and "Eraser mode" (draw white circles to erase). Use a StringVar to store the current mode and display it in a Label.
• Variable trace: Use a StringVar linked to a Label that shows the current mouse coordinates as you move the mouse over the canvas (use <Motion> event).

Requirements:

• Use command for the buttons.
• Use bind() for mouse and key events.
• Use a StringVar for the mode and trace it to update the mode label (or just update the label directly, but use a trace to demonstrate understanding).
• Use a lambda (or partial) for the random colour button if needed.
• Ensure the "Clear" button calls a function that deletes all canvas items.

Part B: Debugging Event Handlers (10 points)

The following code is supposed to create a form where typing in the first Entry automatically copies the text to a second Entry (mirroring), but it has three distinct errors. Identify each error, explain the consequence, and provide the corrected code.

import tkinter as tk

root = tk.Tk()

def copy_text():
    # Error 1: Wrong way to get/set text
    text = entry1.get()
    entry2.config(text=text)   # Error 2: Entry uses textvariable, not text

entry1 = tk.Entry(root)
entry1.pack()

entry2 = tk.Entry(root)
entry2.pack()

# Error 3: Binding to the wrong event and wrong target
entry1.bind("<Button-1>", copy_text)

root.mainloop()

Note: Entry widgets use textvariable or .insert()/.delete()/.get(), not .config(text=...).

import tkinter as tk
root = tk.Tk()
def copy_text(event):
    entry2.delete(0, tk.END)
    entry2.insert(0, entry1.get())
entry1 = tk.Entry(root)
entry1.pack()
entry2 = tk.Entry(root)
entry2.pack()
entry1.bind("<KeyRelease>", copy_text)
root.mainloop()

Part C: The Late Binding Trap – Analysis and Fix (5 points)

Given the following code that creates a grid of buttons (3x3) representing a numeric keypad, explain why all buttons print 8 when clicked. Then rewrite the loop correctly using either lambda with default arguments or functools.partial.

buttons = []
for row in range(3):
    for col in range(3):
        num = row * 3 + col
        btn = tk.Button(root, text=str(num), command=lambda: print(num))
        btn.grid(row=row, column=col)
        buttons.append(btn)

btn = tk.Button(root, text=str(num), command=lambda val=num: print(val))

from functools import partial
btn = tk.Button(root, text=str(num), command=partial(print, num))

Part D: Variable Trace Implementation (5 points)

Write a complete, runnable script that:

• Contains an Entry widget linked to a StringVar.
• Contains a Label that shows the current length of the text in the entry.
• Uses a trace("w") on the StringVar to update the label with the character count every time the user types.
• Ensure the label shows "Length: 0" initially.

Part E: Reflection – Why Event‑Driven is Different (5 points)

Write a short essay (7‑10 sentences) explaining the fundamental difference between event‑driven programming and procedural programming. Use the restaurant analogy or create your own. Explain how the mainloop() acts as the "engine" and why command, bind, and trace are all necessary in different situations.

10. Summary of Key Terms (Glossary)

11. Further Resources for Self‑Study

• Tkinter Event Types: The official Tkinter documentation lists all event patterns (<Key>, <Button>, <Configure>, etc.).
• Event Object Attributes: A comprehensive list of all attributes available on the Event object.
• Variable Trace Deep Dive: Advanced usage of trace for model‑view‑controller (MVC) patterns in Tkinter.
• Practice Challenge: Build a text editor with a "Find" feature that uses trace to highlight search terms as you type them.

This tutorial is designed to take approximately 3 hours of study, lab work, and homework. Event handling is what breathes life into your GUI – mastering it separates a static display from a truly interactive application.

Previous | Tutorial index | Next