Handling AppleEvents

AppleEvents are special kinds of high-level system events used by the OS X operating system to pass information between processes. In order to handle system events, such as when a file is dropped in the application's Dock icon, it's necessary to handle AppleEvents. Implementing the handlers for these methods can allow your app to behave more natively when run on OS X.

Note

This recipe is specific to the OS X operating system and will have no effect on other operating systems.

How to do it…

Perform the following steps:

1. Define an app object in which we will override the available AppleEvent handlers through the following code:

   class MyApp(wx.App):
       def OnInit(self):
           self.frame = MyFrame("Apple Events")
           self.frame.Show()
           return True

2. Override the handlers that are available to deal with the opening of files:

       def MacNewFile(self):
           """Called in response to an open-application event"""
           self.frame.AddNewFile()
   
       def MacOpenFiles(self, fileNames):
           """Called in response to an openFiles message in Cocoa
           or an open-document event in Carbon
           """
           self.frame.AddFiles(fileNames)

3. Finally, let's also override the remaining available AppleEvent handlers that are defined in wx.App and have them redirected to some actions with our application's main window. The following code can help us do this:

       def MacOpenURL(self, url):
           """Called in response to get-url event"""
           self.frame.AddURL(url)
   
   def MacPrintFile(self, fileName):
           """Called in response to a print-document event"""
           self.frame.PrintFile(fileName)
   
       def MacReopenApp(self):
           """Called in response to a reopen-application event"""
           if self.frame.IsIconized():
               self.frame.Iconize(False)
           self.frame.Raise()

How it works…

In the Carbon and Cocoa builds of wxPython, these additional Mac-specific virtual overrides are available for apps to implement. The app object has special handling for these events and turns them into simple function calls that can be overridden in derived applications to provide an app-specific handling of them.

The first two methods that we overrode are called in response to creating a new file or opening existing files, such as when a file is dragged and dropped in the application icon in the dock. The MacOpenFiles method is new since wxPython 2.9.3 and should be used instead of the MacOpenFile method that was provided in previous versions.

The other method that most apps should implement in some form is the MacReopenApp method. This method is called when a user clicks on the application icon in the dock. In this implementation, we ensure that the app is brought back to the foreground in response to this action.

There's more…

If there are other OS X-specific actions you want your app to handle, it is also possible to add support for additional AppleEvents to a wxPython application. It is not a particularly easy task as it requires writing a native extension module to catch the event, block the event loop, and then restore the Python interpreter's state back to wx after handling the event. There is a pretty good example that can be used as a starting point on the wxPython Wiki page (refer to http://wiki.wxpython.org/Catching%20AppleEvents%20in%20wxMAC) if you find yourself needing to venture down this route.