Controlling the propagation of events

There are two main types of events in wxPython:

• Normal events
• Command events

Understanding how these events travel through the framework is important to understanding how to develop an application in this event-driven framework. This recipe will develop an example to show how to control the way an event is propagated.

How to do it…

The following steps can help us:

1. Let's start by creating a panel that has two buttons in it, by creating the following class:

   class MyPanel(wx.Panel):
       def __init__(self, parent):
           super(MyPanel, self).__init__(parent)
           
           sizer = wx.BoxSizer()
           self.button1 = wx.Button(self, label="Button 1")
           sizer.Add(self.button1)
           self.button2 = wx.Button(self, label="Button 2")
           sizer.Add(self.button2)
           self.SetSizer(sizer)
           
           self.Bind(wx.EVT_BUTTON, self.OnButton)

2. Next, let's define the event handler for the panel to handle the button events as follows:

       def OnButton(self, event):
           button = event.EventObject
           print("Button (%s) event at Panel!" % button.Label)
           if button is self.button1:
               event.Skip()

3. In the next layer, let's make a frame to hold the panel and also set it up to catch button events through the following code:

   class MyFrame(wx.Frame):
       def __init__(self, parent, title=""):
           super(MyFrame, self).__init__(parent, title=title)
           
           self.panel = MyPanel(self)
           
           self.Bind(wx.EVT_BUTTON, self.OnButton)
   
       def OnButton(self, event):
           button = event.EventObject
           print("Button (%s) event at Frame!" % button.Label)
           event.Skip()

4. Finally, let's do the same thing at the app level:

   class MyApp(wx.App):
       def OnInit(self):
           self.frame = MyFrame(None, title="Event Propagation")
           self.frame.Show();
           
           self.Bind(wx.EVT_BUTTON, self.OnButton)
           return True
   
       def OnButton(self, event):
           button = event.EventObject
           print("Button (%s) event at App!" % button.Label)
           event.Skip()

Tip

Downloading the example code

You can download the example code files for all Packt books you have purchased from your account at http://www.packtpub.com. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.

How it works…

When you run this application and click on each of the buttons, you should see two distinct differences in behavior between how the events propagate. When clicking on the first button, the event handlers from the panel to the frame and finally to the app will be executed, whereas when clicking the second button, only the event handler at the panel is executed.

The EVT_BUTTON object is a command event, meaning it will propagate upward until it is stopped or it reaches the app. In this example, the second button is only propagated to the Panel handler because we called event.Skip when the event originated from the first button. Calling the Skip method tells the framework to propagate the event to the next handler in the chain, whereas not calling the Skip method tells the framework that the event has been handled and does not require further processing. So, it's important to know when to call Skip and when not to as sometimes it is necessary for the event to propagate to the base default handler in order for additional processing to occur. Try going back to the Binding to events recipe and removing the call to Skip in OnFrameExit to ensure that it prevents the frame from closing.

There's more…

As discussed at the beginning of this recipe, there are two types of events. This recipe only explored the more common types of command events that were propagated. Normal events stay local to where they are generated and do not propagate.

You can also create your own custom events if you want to use the event loop to pass messages using the newevent module in wx.lib, as follows:

import wx
import wx.lib.newevent

# Create a special event
MyEvent, EVT_MYEVENT = wx.lib.newevent.NewCommandEvent();

This creates a new event object type and event binder object. The EVT_MYEVENT binder object can be bound to as any other event. Then, the MyEvent event object can be emitted through the use of the wx.PostEvent function, which sends the instance of the event through the event handler chain.