<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<link rel="stylesheet" href="../PythonCard.css" type="text/css" />
<title>Framework Overview - Events and Handlers</title>
</head>
<body>
<div id="banner">
<h1>Framework Overview - Events and Handlers</h1>
</div>
<?php include "../sidebar.php" ?>
<div id="content">
<p>Updated: March 31, 2006 for release 0.8.2</p>
<p>I'll cover the main points from a user point of view.</p>
<p>I listed most of the events supported by PythonCard components in an earlier message, but here they are again:</p>
<pre>
gainFocus
loseFocus
mouseContextDoubleClick
mouseContextDown
mouseContextUp
mouseDoubleClick
mouseDown
mouseDrag
mouseEnter
mouseLeave
mouseMiddleDoubleClick
mouseMiddleDown
mouseMiddleUp
mouseMove
mouseUp
timer
</pre>
<p>The most common events you see in the samples are not the ones above, but these:</p>
<pre>
command
mouseClick
initialize
select
</pre>
<p>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.</p>
<pre>
{ 'type':"MenuItem",
'name':"menuEditNewCard",
'label':"&New Card\tCtrl+N",
'command':'editNewCard'},
def on_editNewCard_command(self, event):
self.newRecord()
</pre>
<p>All component and menu event handlers take the form
<pre> on_componentName_eventName</pre>
or
<pre> on_commandName_command</pre>
more examples...
<pre>
def on_menuFileExit_select(self, event):
def on_btnColor_mouseClick(self, event):
def on_bufOff_mouseDrag(self, event):
</pre>
<p>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.</p>
<p>It is common to have an initialize event such as </p>
<pre>
def on_initialize(self, event):
</pre>
<p>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:</p>
<pre>
activate
deactivate
close
idle <- sent when the message queue empties
minimize
maximize
restore
move
size
</pre>
<p>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.</p>
<pre>
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
</pre>
<hr>
| <a href="general_concepts_and_limitations.html">General Concepts and Limitations</a>
| <a href="components.html">Components</a>
| <a href="dialogs.html">Dialogs</a>
| <a href="events_and_handlers.html">Events and Handlers</a>
| <a href="menus.html">Menus</a>
| <a href="resource_files.html">Resource Files</a>
| <a href="runtime_tools.html">Runtime Tools</a>
<hr>
<?php include "../footer.php" ?>
<p>$Revision: 1.4 $ : $Author: alextweedly $ : Last updated $Date: 2006/04/06 11:00:26 $</p>
</div> <!-- end of content -->
</body>
</html>
