[Pythoncard-users] state of the framework - events and handlers

[Kevin A. <al...@se...>]

Rowland should probably be the one describing the prototype event model, but
I'll cover the main points from a user point of view.

I listed most of the events supported by PythonCard widgets in an earlier
message, but here they are again:
  gainFocus
  loseFocus
  mouseContextDoubleClick
  mouseContextDown
  mouseContextUp
  mouseDoubleClick
  mouseDown
  mouseDrag
  mouseEnter
  mouseLeave
  mouseMiddleDoubleClick
  mouseMiddleDown
  mouseMiddleUp
  mouseMove
  mouseUp

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

Every widget 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, target, event):
        self.newRecord()

All widget and menu event handlers take the form

  on_commandName_command
or
  on_widgetName_eventName

more examples...

    def on_menuFileExit_select(self, menu, event):

    def on_btnColor_mouseClick(self, target, event):

    def on_bufOff_mouseDrag(self, target, 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 or stack level. We aren't doing stack events yet, but the
tictactoe sample shows an example of using a background handler for
mouseClick events. It is also common to have an openBackground event such as

  def on_openBackground(self, target, event):

which can be used to perform app initialization (in the prototype framework
it is more like the HyperCard openStack system message).

The handler method arguments (self, target, 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 and something description
like menu and target depending on the handler type. The 'target' is the
actual widget target, which simplifies manipulating the widget. For example:

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

bufOff is a BitmapCanvas and line is one of its methods. Another thing to
notice about the example above is that it was necessary to use the method
getNativeEvent to get the coordinates of the event. This is because while
wxPython events are wrapped by PythonCard, virtually none of the information
available in the raw/native event is wrapped at this point. In some cases
there is not a corresponding wxPython event class. The wrapping is
non-trivial and will take a fair amount of time to get right.

There was a method for posting events not generated internally by wxPython,
but it is not currently used and probably needs to be refactored.

There are no events in the prototype for window positioning and resizing,
activating or exiting the app, idle or timer events.

ka