Event Types

These are all of the event types that are fired by the various components in the Vision module. Events are organized into event sets. For example, the mouse event set includes mouseClicked, mousePressed, and mouseReleased. All of the events in an event set share the same properties for their event object.

Event Sets

action Events

Events

Properties in 'event'

The actionPerformed event is fired when an "action" occurs. What that "action" is depends on the component. The most common example is the Button component. You should always use the action event on a button instead of a mouse click, because it will be fired whenever the button is pressed, whether it is via the mouse or the keyboard (via a mnemonic shortcut or tabbing over to the button and pressing enter or space). The Timer component is another example of a component that fires an action event. In this case, the action is the timer firing.

cell Events

Events

Properties in 'event'

Cell events are fired by a Table component that has editable columns. When a user edits a cell, this event will fire. The oldValue and newValue properties in the event can be used to determine what value the cell used to hold, and what new value the user has entered. The row and column properties, both integers, show what position in the table's data property the edit occurred at.

Example

Commonly, the event handler for a cell event will issue a SQL update query to persist changes to the table back to an external database. You can use the row to determine what the primary keys were for the row that was edited by looking at the table's data property. You can use the column index to find the column name of the edited column.

columnName = event.source.data.getColumnName(event.column)

primaryKeyValue = event.source.data.getValueAt(event.row, "keycolumn")

query = "UPDATE mytable SET %s=? WHERE keycolumn=?" % columnName

system.db.runPrepUpdate(query, [event.newValue, primaryKeyValue])

focus Events

Events

Properties in 'event'

Focus events are fired for components that can receive input focus. For both the focus gained and focus lost events, you can also access the "opposite" component. For a focus gain, this is the component that previously had the focus. For a focus lost event, the opposite component is the component that took the focus away.

You can programatically request that focus be given to a component by calling the function requestFocusInWindow() on that function. This function is actually defined by Java's JComponent class, from which all Vision components extend.

If you are trying to alter the focus from within a focus event handler, you must wrap your code in a call to system.util.invokeLater. This will let your focus change be processed after the current focus change event that is being processed has a chance to finish.

internalFrame Events

Events

Properties in 'event'

Internal frame events are fired by windows. ( They are known as "internal frames" in the underlying Java windowing system that the Vision component uses). Note that the source of these events is the window itself. To get the root container of the window, use event.source.rootContainer, not event.source.getComponent("Root Container").

The Activated/Deactivated events get fired when the component receives or loses input focus. The Activated event is a more reliable event to use as a window startup event than the Opened event, because the Opened event will not be called if the window was opened when it was already cached.

See also:

Window Cache Policies

item Events

Events

Properties in 'event'

The itemStateChanged event is used by components that choose between a selected or deselected state. For example, a Check Box or Radio Button. You can respond to this event to be notified when the state has changed (via any mechanism - click, keyboard, property bindings, etc). To check whether the event represents a selection or a deselection, you compare the event's stateChange property with the SELECTED or DESELECTED constants, like this;

if event.stateChange == event.SELECTED:

   print "Turned ON"

else:

   print "Turned OFF"

key Events

Events

Properties in 'event'

Key events are used to respond to keyboard input. They will only be fired on components that receive input focus. Handling key events often involves checking exactly what key was pressed. These events make a distinction between character keys (A,B,C...) and non-printable keys (F3, Esc, Enter). All keys will get keyPressed and keyReleased events, but only character keys will get keyTyped events. For keyTyped events, checking what key was pressed is relatively simple, you can simply do a comparison on keyChar, like event.keyChar == 'a'. For other keys, however, you need to compare the keyCode to a constant, enumerated below. These constants can be referenced through the event object itself, like: event.keyCode == event.VK_ENTER.

All of this information comes straight out of the Java documentation for java.awt.KeyEvent. See http://java.sun.com/j2se/1.5.0/docs/api/java/awt/event/KeyEvent.html

mouse Events

Events

Properties in 'event'

mouseMotion Events

Events

Properties in 'event'

paint Events

Events

Properties in 'event'

This event is fired by the Paintable Canvas component. This component is provided for highly script-literate users, and is decidedly not user-friendly. Don't say you weren't warned. It allows you to use Java2D through Python to programatically "paint" your own dynamic, vector-based component. This event is called every time the component needs to repaint. It will repaint when any of its custom properties change, or when .repaint() is called on it. Drop a Paintable Canvas onto a window and look at the paint event handler for an example.

propertyChange Events

Events

Properties in 'event'

The propertyChange event is called any time a bindable property changes on a component. This includes all custom properties. This can be a very useful tool, allowing you to respond via scripting when a property changes. Because this one event handler is called for multiple properties, it is typical for a handler to first have to filter based on the propertyName, so that it is responding to a specific property changing.

Example

#This script might go on a Table whose data must be filled in before continuing

if event.propertyName == "data":

   newData = system.db.toPyDataSet(event.newValue)

   if len(newData)>0:

      # Data exists - let the user know they may proceed

      system.gui.messageBox("You may proceed.")