# Framework Overview - Events and Handlers

Updated: March 31, 2006 for release 0.8.2

I'll cover the main points from a user point of view.

I listed most of the events supported by PythonCard components in an earlier message, but here they are again:

      gainFocus
      loseFocus
      mouseContextDoubleClick
      mouseContextDown
      mouseContextUp
      mouseDoubleClick
      mouseDown
      mouseDrag
      mouseEnter
      mouseLeave
      mouseMiddleDoubleClick
      mouseMiddleDown
      mouseMiddleUp
      mouseMove
      mouseUp
      timer

The most common events you see in the samples are not the ones above, but these:

      command
      mouseClick
      initialize
      select

Every component and menu can have an associated command event. As an example, here's a menu item definition from addresses.rsrc.py that uses 'command' and the associated handler.

        { 'type':"MenuItem",
          'name':"menuEditNewCard",
          'label':"&New Card\tCtrl+N",
          'command':'editNewCard'},

        def on_editNewCard_command(self, event):
            self.newRecord()

All component and menu event handlers take the form

      on_componentName_eventName

or

      on_commandName_command

more examples...

        def on_menuFileExit_select(self, event):

        def on_btnColor_mouseClick(self, event):

        def on_bufOff_mouseDrag(self, event):

The underscores are used by the framework to identify a handler method and they have the added benefit of making the handlers stick out from other methods in the user code. All events go first to the target of the event and if they aren't handled, then the framework searches for a match at the background level. The tictactoe sample shows an example of using a background handler for mouseClick events.

It is common to have an initialize event such as

        def on_initialize(self, event):

which can be used to perform app initialization (in the prototype framework it is more like the HyperCard openStack system message). The other background events are:

      activate
      deactivate
      close
      idle       <- sent when the message queue empties
      minimize
      maximize
      restore
      move
      size

The handler method arguments (self, event) are just names, so like any other Python program you can use what names you want, but for readability it is better to use self and event. The 'target' of the event can be referenced as event.target, which simplifies manipulating the component. In the example below bufOff is a BitmapCanvas and line is one of its methods.

        def on_bufOff_mouseDrag(self, event):
            x, y = event.position
            event.target.line(self.x, self.y, x, y)
            self.x = x
            self.y = y

| General Concepts and Limitations | Components | Dialogs | Events and Handlers | Menus | Resource Files | Runtime Tools

$Revision: 1.4 $ : $Author: alextweedly $ : Last updated $Date: 2006/04/06 11:00:26 $