Component Event Handlers

When you're writing component event handlers, you'll do a lot of work with components. You'll need to reference various components on the window or on other windows, you'll need to reference and set properties of the component, you may even want to move components around on the screen.

Finding Components

When you have an event object, that object becomes your window into the entire component hierarchy. event.source references the component that fired whatever event you're responding to. event.source.parent references the container that component is in event.source.parent. getComponent("Name") finds a sibling component with a certain name. The manual page for the event object covers this topic in more detail.

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

Each component can have its own set of events, however most components share events, therefore, understanding the way one event works with one component will result in understanding how it works will all other components that have the same event.

The most common event sets are as follows:

  • action

  • cell

  • focus

  • internalFrame

  • item

  • key

  • mouse

  • mouseMotion

  • paint

  • propertyChange

action Events

Events

actionPerformed

Properties in 'event'

source

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

cellEdited

Properties in 'event'

source
oldValue - the previous value in the cell
newValue - the newly entered value for the cell
row
column

Cell events a re fired by a Table component that ha s 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

focusGained
focusLost

Properties in 'event'

source
oppositeComponent - the component that either gave up focus to this component, or took it away

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.

Requesting Focus in the Window

You can programmatically 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.

The following is an example of the requestfocusinwindow function.

Example - Requesting Focus
#The following example will pass focus to a specific component in a window. This could be placed on the
#internalFrameOpened event on the window, so that the component gains focus once the window is opened for the first time.
#Define a function that will pass focus to a component
def focus():
 
#From the parent window, define a path to the component that should have focus. In this case, we are
#passing focus to a component named 'Text Field' that is located directly in the Root Container
system.gui.getParentWindow(event).getRootContainer().getComponent('Text Field').requestFocusInWindow()
 
 
#Call invokeLater, and pass the function we defined above
system.util.invokeLater(focus)

internalFrame Events

Events

internalFrameActivated - fired when the window becomes the focused window
internalFrameClosed - fired after the window is closed
internalFrameClosing - fired just before the window is closed
internalFrameDeactivated - fired when the window loses focus
internalFrameOpened - fired the first time a window is opened after not being in the cache

Properties in 'event'

source

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's Cache Policy

item Events

Events

itemStateChanged

Properties in 'event'

source

stateChange - a code that will be equal to either the SELECTED or DESELECTED constants.

SELECTED - a constant representing a selection event.

DESELECTED - a constant representing a deselection event.

The itemStateChanged event is used by components that choose between a selected or deselected state. For exam ple, 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, and so on). 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

keyPressed - fires when a key is pressed while the source component has input focus. Works for all keyboard keys.

keyReleased - fires when a key is released while the source component has input focus. Works for all keyboard keys.

keyTyped - fired when a character key is pressed and then released while a component has input focus.

Properties in 'event'

source

keyCode - an integer code representing the key that was pressed or released. Only valid on keyPressed and keyReleased events. See table below.

keyChar - a string that represents the character that was typed, if applicable (e.g. used for letters, but not an F-key). Only valid on keyTyped event.

keyLocation - the location of the key. E.g. to differentiate between left shift from right shift.

altDown - true (1) if the alt key was held down during this event, false (0) otherwise.

controlDown - true (1) if the control key was held down during this event, false (0) otherwise.

shiftDown - true (1) if the shift key was held down during this event, false (0) otherwise.

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.

Key Code Constants

VK_0 - VK_9

VK_END

VK_PAGE_UP

VK_A - VK_Z

VK_ENTER

VK_RIGHT

VK_F1 - VK_F24

VK_HOME

VK_SHIFT

VK_ALT

VK_INSERT

VK_SPACE

VK_CONTROL

VK_LEFT

VK_TAB

VK_DOWN

VK_PAGE_DOWN

VK_UP

Location Code Constants

KEY_LOCATION_LEFT

KEY_LOCATION_RIGHT

KEY_LOCATION_UNKNOWN

KEY_LOCATION_NUMPAD

KEY_LOCATION_STANDARD

 

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

mouseClicked - fired when the mouse is pressed and released in the same spot on the component.
mouseEntered - fired when the mouse is moved so that it is hovering over the component
mouseExited - fired when the mouse had been hovering over the component and exits
mousePressed - fired when the mouse is pressed within the bounds of the component
mouseReleased - fired when the mouse is released after having been pressed within the bounds of the component

Properties in 'event'

source

button - an integer code representing the button that was clicked. Use the constants event.BUTTON1, event.BUTTON2, and event.BUTTON3.

clickCount - an integer count of the number of successive clicks.

Click Count
#Use code like this to ensure a specific number of clicks before your code runs.
if event.clickCount == 2:
print "I was clicked twice!"

x - the x-axis location of the mouse click, with (0,0) being the upper left corner of the component.
y - the y-axis location of the mouse click, with (0,0) being the upper left corner of the component.
popupTrigger - true(1) if this mouse event should pop up a context menu. Meaning is OS-dependent. On windows, it is a release of BUTTON3.
altDown - true (1) if the alt key was held down during this event, false (0) otherwise.
controlDown - true (1) if the control key was held down during this event, false (0) otherwise.
shiftDown - true (1) if the shift key was held down during this event, false (0) otherwise.

mouseMotion Events

mouseMotion events will not trigger when the project is viewed from a mobile project as these gestures are used by the browser/device to zoom or pan.

Events

mouseDragged - fires when the mouse is pressed within the component, and then moved. Will continue to fire until the button is released, even if the mouse moves outside the component.
mouseMoved - fired when the mouse moves over the component.

Properties in 'event'

See mouse events.

paint Events

Events

repaint

Properties in 'event'

source

graphics - An instance of java.awt.Graphics2D that can be used to paint this component. The point (0,0) is located at the upper left of the component.
width - The width of the paintable area of the component. This takes into account the component's border.
height - The height of the paintable area of the component. This takes into account the component's border.

This event is fired by the Paintable Canvas co mponent. This component is provided for highly scriptliterate 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

propertyChange

Properties in 'event'

source

newValue - The new value of the property.

oldValue - The previous value of the property. Not all properties provide this information.

propertyName - The name of the property that has changed.

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.")

Next ...