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

  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

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

Framework Overview - Events and Handlers

General

Development

Exits