Binding to events

wxPython is an event-driven framework; this means that all actions and the running of the UI is driven by events. Events are fired by objects to indicate that something has happened or needs to happen. MainLoop then dispatches these events to callback methods that are registered to be notified of the event. This recipe will show how to bind callback functions to events.

How to do it…

Perform the following functions:

1. First, start by creating a frame and binding to some of its events with the following code:

   class MyApp(wx.App):
       def OnInit(self):
           self.frame = wx.Frame(None, title="Binding Events")
           
           # Bind to events we are interested in
           self.frame.Bind(wx.EVT_SHOW, self.OnFrameShow)
           self.frame.Bind(wx.EVT_CLOSE, self.OnFrameExit)
           
           # Show the frame
           self.frame.Show()
           return True

2. Next, define the event handler callback methods we specified in the Bind calls. These will get executed when the bound event occurs, as follows:

       def OnFrameShow(self, event):
           theFrame = event.EventObject
           print("Frame (%s) Shown!" % theFrame.Title)
           event.Skip()
   
       def OnFrameExit(self, event):
           theFrame = event.EventObject
           print("Frame (%s) is closing!" % theFrame.Title)
           event.Skip()

How it works…

In the OnInit method, we created a frame object and then called Bind on it two times in order to bind our own two callback methods to these events that the frame emits. In this case, we bound to EVT_SHOW and EVT_CLOSE; these two events will be emitted by a window when the window transitions from being hidden to shown on screen and then when it is closed. Binding to events allows us to add some application-specific response when these two events occur. Now, our app's OnFrameShow and OnFrameExit callbacks will be executed by the framework in response to the event and allow us to print our log messages.

The first event, EVT_SHOW, happens as part of when the Show method is called on the frame in the app's OnInit method. The other event, EVT_CLOSE, occurs when the frame's close button is clicked on.

The event handler methods used in Bind always take one argument, which is an event object. This object is passed into the handler by the framework when it is called. The event object contains information about the event, such as a reference to the object that emitted it and other state information depending on what type of event was emitted.

There's more…

The Bind function can also take some additional optional parameters to set more fine-grain control on when the callback should be executed, as follows:

Bind(event, handler, source=None, id=-1, id2=-1)

The arguments to this function are described as follows:

• event: This is the event to bind to.
• handler: This is the event handler callback function to bind.
• source: This can be used to specify the window object that is the source of the event. If specified, then only when the source object generates the event will the handler be executed. By default, any event of the type that gets to the control will cause the handler to execute.
• id1: This is used to specify the source object's ID instead of using the instance.
• id2: When specified with id1, this can be used to specify a range of IDs to bind to.

There are many kinds of events that can be bound to depending on the type of control. The wxPython and wxWidgets online documentation provides a fairly complete list of events that are available for each control in the library. Note that the documentation is based on object hierarchy, so you may have to look to the base classes of an object to find the more general events that many controls share. You can find the documentation at http://wxpython.org/onlinedocs.php.

See also

• Take a look at the Controlling the propagation of events recipe section in this chapter for information on the behavior of events.