Event Object

Event handling scripts are just regular Python scripts except for one important detail. They all have a special variable defined in their namespace called event. This is an object that represents information about the event that just occurred. For example, the event object for a mouse click will have the x and y coordinates where the click occurred. A key press event, on the other hand, will have a keycode, but not a coordinate.

In addition to information about the event that has just occurred, the event object has a source property. The source of an event is the component that fired it. This is a crucial concept to understand. The reference to the component is your handle into the entire hierarchy of the window that your script is contained in.

Example

Suppose you're handling the mouse-pressed event of a label component. The following script would print out the coordinates of the click, as well as the text of the label:

currentText = event.source.text
print 'Mouse clicked on label "%s" at %dx%d' % (currentText, event.x, event.y)

The output would look like this if the label's text was "this is my label":

Mouse clicked on label "this is my label" at 27x99

Using the event object to access the component hierarchy

Because event.source is the component that fired the event, you can use this reference to access the entire hierarchy of your window. This means you can access properties of any other component in the window. You just need to know how to navigate up and down the component tree.

To navigate up the component tree (going from a component to its parent container), simply use the parent property.

To navigate down the component tree (going from a container to one if its children), use the getComponent(name) function.

To navigate sideways (getting a reference to a sibling component), simply go up one level and then back down.

Example

Suppose the component hierarchy in our window looked like this:

Root Container
HeaderLabel
StartButton
Options
ProductCode
BatchSize
PreviewTable

This window has a start button, a header, some options, and a preview table. Lets say that it is a window that lets the operator start a new batch. It has some options that are grouped into their own container. Lets say that the Root Container also has some parameters that our start button needs to know about.

The following table shows some script expressions and what they will evaluate to if you're writing an event handler for the StartButton component:

event.source #The start button
event.source.parent # The root container
event.source.parent.MyProperty #The value of custom property "MyProperty" on the Root Container
event.source.parent.getComponent("Options") #The Options container
event.source.parent.getComponent("Options").getComponent("ProductCode").selectedValue #The selected value of the ProductCode dropdown component
event.source.parent.getComponent("PreviewTable").selectedRow #The index of the selected row in the PreviewTable

There is one exception to the pattern of using .parent to go up the hierarchy and using .getComponent(name) to go down. The parent of a root container is not the window, and a reference to the window does not have a .getComponent(name) function. To get a reference to a window, simply use system.gui.getParentWindow with any component's event object as the parameter. Once you have a reference to a window, you can use its .rootContainer property to get to the root of the component hierarchy, and from here you can follow the rules laid out above.