Event Handlers

When running scripts on a component, we typically don't want it to be constantly running, but instead want the script to trigger when the user does something on screen such as clicks with the mouse. That something the user does is called an Event and can range from a simple mouse click, keypress to a window opening, or a component property change. When certain events happen, they trigger Event Handlers, which use a script to handle what happens when the event occurs.

This page lists out all of the event handlers that are on Ignition's standard modules. Any third party modules may add new components which may potentially have new event handlers.

Event Object

Every Event Handler contains an event object, which allows you to interact with the component and the entire window hierarchy within your script. While each event object has different properties depending on what Event Handler it resides in, each event object contains a source property, which is a reference to the component that fired the event. Using event.source not only gives us access to all of the properties available on that particular component, such as the text property of a text field,

# Here we start with the event object, then use source to go to the component that fired the event,
# and then use the name of the property to access its value. In this case, we accessed the text property.
text = event.source.text

but it also provides us with a way to navigate to other components within the hierarchy. For example, here we have a script on a button that references a text field.

# Here again we start with event.source to get to the component that fired the event, but now we use
# parent to go up to the root container, and then getComponent to navigate back down to a different component.
text = event.source.parent.getComponent("Text Field")






 




Even when components are disabled, most scripting events can still occur. For example, a mouse click can still happen on a disabled component, which is why we recommend using the action performed event when placing a script on a button.

Action Event Handlers

The Action category of event handlers pertains to components being "used" from the client, such as a button being pressed or a checkbox component being selected.

Events

EventsDescription
actionPerformed

This event is fired when the 'action' of the component occurs. What this action is depends on the type of the component. Most commonly, this is used with buttons, where the action is that the button was pushed, via a mouse click or a key press. See the component reference for details on what the action means for other components.

It is recommended to use this event over mouseClicked whenever possible.

Event Object Properties

PropertiesDescription
sourceThe component that fired this event.


# On the actionPerformed of a button, this will print Hello World! to the console each time the button is pressed.
print "Hello World!"



Property Event Handlers

Property event handlers typically trigger based on the property of a component. 

Events

EventsDescription
propertyChangeFires whenever a bindable property of the source component changes. This works for standard and custom (dynamic) properties.

Event Object Properties

PropertiesDescription
sourceThe component that fired this event.
newValueThe new value that this property changed to.
oldValueThe value that this property was before it changed. Note that not all components include an accurate oldValue in their events.
propertyNameThe name of the property that changed. NOTE: remember to always filter out these events for the property that you are looking for! Components often have many properties that change.


# On the propertyChange of a component, this script will print out the name of the property that is changing.
print event.propertyName


# It is common to use propertyName to look for specific properties to change. This is a great way to restrict how often your scripts execute
if event.propertyName == 'text':
  print 'The Text property changed'



Mouse Event Handlers

The mouse events all correspond to the clicking and movement of the mouse. They are triggered in the client by an operator interacting with a mouse. Touchscreen monitors will trigger these events when a user touches the screen, but not all touchscreens will fire the mouseEntered and mouseExited events.

Events

EventsDescription
mouseClickedThis event signifies a mouse click on the source component. A mouse click the combination of a mouse press and a mouse release, both of which must have occurred over the source component. Note that this event fires after the pressed and released events have fired.
mouseEnteredThis event fires when the mouse enters the space over the source component.
mouseExitedThis event fires when the mouse leaves the space over the source component.
mousePressedThis event fires when the mouse presses down on the source component.
mouseReleasedThis event fires when a mouse button is released, if that mouse button's press happened over this component.

Event Object Properties

PropertiesDescription
sourceThe component that fired this event.
buttonThe code for the button that caused this event to fire. Use the constants event.BUTTON1event.BUTTON2, and event.BUTTON3.
clickCountThe number of mouse clicks associated with this event.
xThe x-coordinate (with respect to the source component) of this mouse event.
yThe y-coordinate (with respect to the source component) of this mouse event.
popupTriggerReturns True (1) if this mouse event is a popup trigger. What constitutes a popup trigger is operating system dependent, which is why this abstraction exists.
altDownTrue (1) if the Alt key was held down during this event, false (0) otherwise.
controlDownTrue (1) if the Control key was held down during this event, false (0) otherwise.
shiftDownTrue (1) if the Shift key was held down during this event, false (0) otherwise.


# On the mouseEntered event of a component, this script will only fire if the mouse enters the bounds of the component.
print "The mouse is inside the component space!"



MouseMotion Event Handlers

The mouseMotion events deal with the motion of the mouse over a component. Not all touchscreen monitors will fire these 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

EventsDescription
mouseDraggedFires when a mouse button is clicked on a component and held, and the pointer is then dragged around.
mouseMovedFires when the mouse moves over a component, but no buttons are being held.

Event Object Properties

PropertiesDescriptions
sourceThe component that fired this event.
buttonThe code for the button that caused this event to fire. Use the constants event.BUTTON1event.BUTTON2, and event.BUTTON3.
clickCountThe number of mouse clicks associated with this event.
xThe x-coordinate (with respect to the source component) of this mouse event.
yThe y-coordinate (with respect to the source component) of this mouse event.
popupTriggerReturns True (1) if this mouse event is a popup trigger. What constitutes a popup trigger is operating system dependent, which is why this abstraction exists.
altDownTrue (1) if the Alt key was held down during this event, false (0) otherwise.
controlDownTrue (1) if the Control key was held down during this event, false (0) otherwise.
shiftDownTrue (1) if the Shift key was held down during this event, false (0) otherwise


# From the mouseMotion event on a component, this will print each time the mouse moves when it is over the component.
print "The mouse is moving over the component!"



Key Event Handlers

The key events all have to do with the user pressing a key on the keyboard.

Events

EventsDescription
keyPressedFires when a key is pressed and the source component has the input focus. Works for all characters, including non-printable ones, such as SHIFT and F3.
keyReleasedFires when a key is released and the source component has the input focus. Works for all characters, including non-printable ones, such as SHIFT and F3.
keyTypedFires when a key is pressed and then released when source component has the input focus. Only works for characters that can be printed on the screen.

Event Object Properties

PropertiesDescription
sourceThe component that fired this event.
keyCodeThe key code for this event. Used with the keyPressed and keyReleased events. Uses the standard Java key codes, see below for more information.
keyChar The character that was typed. Used with the keyTyped event.
keyLocationReturns the location of the key that originated this key event. Some keys occur more than once on a keyboard, e.g. the left and right shift keys. Additionally, some keys occur on the numeric keypad. This provides a way of distinguishing such keys. The keyTyped event always has a location of KEY_LOCATION_UNKNOWN. Uses the standard Java key locations, see below for more information.
altDownTrue (1) if the Alt key was held down during this event, false (0) otherwise.
controlDownTrue (1) if the Control key was held down during this event, false (0) otherwise.
shiftDownTrue (1) if the Shift key was held down during this event, false (0) otherwise.


# On the keyReleased event of a component, this will print out the key code of the key that was hit on the keyboard,
# but only on release of the key, and only when the component has focus.
print event.keyCode

Java Keys

The key Event Handlers use the Java KeyEvent class, which has unique identifiers for both keys and locations on the keyboard to help differentiate which key is actually being pressed on the keyboard. The numeric codes for each unique location and character can be called from the event object using a constant. For example, the letter "a" has the constant name VK_A. This can then be used to compare against the keyCode value like this:

if event.keyCode == event.VK_A:
	print "The key press was a"

We listed the locations and some common codes below, but the full list of codes can be accessed by going to https://docs.oracle.com/javase/8/docs/api/java/awt/event/KeyEvent.html.

Some Operating Systems reserve certain keys for certain function, and will capture the key press or release before it gets sent to the Client. For example, many Operating Systems use the TAB key to shift focus to the next field.



Key Code Constants

VK_0 - VK_9

VK_END

VK_PAGE_UP

VK_DOWNVK_CONTROL

VK_A - VK_Z

VK_ENTER

VK_RIGHT

VK_PAGE_DOWNVK_LEFT

VK_F1 - VK_F24

VK_HOME

VK_SHIFT

VK_UPVK_TAB

VK_ALT

VK_INSERT

VK_SPACE

VK_ESCAPE



Key Location Constants

KEY_LOCATION_LEFT

KEY_LOCATION_RIGHTKEY_LOCATION_NUMPAD
KEY_LOCATION_STANDARDKEY_LOCATION_UNKNOWN



Focus Event Handlers

Focus events deal with focus moving between different components on a window. Opening windows, using tab to move around the screen, or clicking on components will trigger these events. Note that not all components can hold focus.

Events

EventsDescription
focusGainedThis event occurs when a component that can receive input, such as a text box, receives the input focus. This usually occurs when a user clicks on the component or tabs over to it.
focusLostThis event occurs when a component that had the input focus lost it to another component.

Event Object Properties

PropertiesDescription
sourceThe component that fired this event.
oppositeComponentThe other component involved in this focus change. That is, the component that lost focus in order for this one to gain it, or vise versa.


# On the focusGained event of a few different components, this script can print out when the component has gained focus.
print "The component name now has focus!"



VisionWindow Event Handlers

The visionWindow events are specific to windows and not available elsewhere. Right-Click on the window name in the Project Browser pane and select Scripting to get access to these events. These are triggered by a window opening or closing.

Events

EventsDescription
visionWindowOpenedThis event is fired each time the window is opened and before any bindings are evaluated.
visionWindowClosedThis event is fired each time the window is closed.

Event Object Properties

PropertiesDescription
sourceThe vision window that fired this event.


# From a visionWindowOpened event on a window, you can request the focus of components in the window, to start the focus on a component other than the upper left most component.

# Here we grab the reference to the component using the property selector on the upper right side of the script editor.
system.gui.getParentWindow(event).getComponentForPath('Root Container.Text Field').requestFocusInWindow()

# Here we can manually enter in the path to the component using our knowledge of the component hierarchy and
# the getRootContainer function. Both of these functions work in the same way.
system.gui.getParentWindow(event).getRootContainer().getComponent("Text Field").requestFocusInWindow()



InternalFrame Event Handlers

The internalFrame events are fired by windows: windows 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, just like the visionWindow events above.

Events

EventsDescriptions
internalFrameActivatedFires whenever the window is shown or focused. If you want a script to fire every time a window is opened, use this event.
internalFrameClosedFires when a window is closed.
internalFrameClosingFires right before a window is closed.
internalFrameDeactivatedFires when a window loses focus.
internalFrameOpenedFires the first time a window is opened. Note that when windows are closed and cached, next time they are opened this event will not be fired. Use internalFrameActivated instead.

Event Object Properties

PropertiesDescription
sourceThe window that fired this event. Use source.rootContainer to get the root container.


# From the internalFrameActivated event on a window, this will fire each time the window is focused, so clicking between two different windows will trigger it.
print "This window is now in focus!"



Cell Event Handlers

The cell event is unique in that it only appears on the Table component. It will trigger when something within a cell changes, and once for each cell changed.

Events

EventsDescription
cellEditedThis event is fired when one of the cells in a table component has been modified.

Event Object Properties

PropertiesDescription
sourceThe table component that fired this event.
oldValueThe old value in the cell that changed.
newValueThe new value in the cell that changed.
rowThe row of the dataset this cell represents.
columnThe column of the dataset this cell represents.


# From the cellEdited event of a table component, this script can update our database table with any new data that is entered in the table

# Get the id of the row we edited and the headers
id = event.source.data.getValueAt(event.row, 'id')
headers = system.dataset.getColumnHeaders(event.source.data)

# Build our Update query.
query = "UPDATE User SET %s = ? WHERE id = ?" % (headers[event.column])
args = [event.newValue, id]

# Run the query with the specified arguments.
system.db.runPrepUpdate(query, args)



Item Event Handlers

The item event is unique in that it only appears on components that can be "on" or "off, such as with Radio Buttons, Check Boxes, and Toggle Buttons.

Events

EventsDescription
itemStateChangedThis event fires when the state of the component changed. This event is the best way to respond to the state of that component changing.

Event Object Properties

PropertiesDescription
sourceThe component that fired this event.
stateChange An integer that indicates whether the state was changed to "Selected" (on) or "Deselected" (off). Compare this to the event object's constants to determine what the new state is.
SELECTEDThe constant that the stateChange property will be equal to if this event represents a selection.
DESELECTEDThe constant that the stateChange property will be equal to if this event represents a de-selection.


# On the itemStateChanged event of a radio button, this will print when this specific radio button is selected.
if event.stateChange == event.SELECTED:
	print "This radio button is selected!"



Paint Event Handlers

The paint event is only found on the Paintable Canvas component, and is used to customize how the component gets painted. This event requires a heavy knowledge of programming using the Java 2D drawing tools, but there is code for a pump shape each time you add a new Paintable Canvas to a window.

Events

EventsDescription
repaintThis event will fire whenever the component needs to repaint itself. It will repaint when any of its custom properties change, or when .repaint() is called on it. When a Paintable Canvas is first dragged onto the screen, the repaint Event Handler will be filled with an example that draws out a pump.

Event Object Properties

PropertiesDescription
sourceThe Paintable Canvas component that fired this event.
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.
widthThe width of the paintable area of the component. This takes into account the component's border.
heightThe height of the paintable area of the component. This takes into account the component's border.


# On the repaint event of a paintable canvas component, this will create a circle with a gradient background color of orange and white.

from java.awt import Color
from java.awt import GradientPaint
from java.awt.geom import Ellipse2D

g = event.graphics

# Body
innerBody = Ellipse2D.Float(8,8,72,72)

#### Scale graphics to actual component size
dX = (event.width-1)/100.0
dY = (event.height-1)/100.0
g.scale(dX,dY)

# Paint body
g.setPaint(GradientPaint(0,40,Color.WHITE, 0,100, Color.ORANGE,1))
g.fill(innerBody)
g.setColor(Color.ORANGE)
g.draw(innerBody)