Client Event Scripts
Client Event Scripts Overview​
Client Event Scripts run on the computer running the Client. They allow you to execute Jython code in a running instance of a Vision Client, as opposed to running them in the Gateway.
Client Event Scripts are not intended to run while in the Designer's preview mode. It is recommended that you test your Client Event Scripts in a Vision Client instead.
Startup Script​
These trigger when the user logs into the client. These scripts trigger before any windows in the project are opened, so they are ideal to use when you need to dynamically open certain windows based on which user logged on.
Configurations for Client Event Startup Scripts are similar to Gateway Event Startup scripts. See the Gateway Event Scripts page for more information
Shutdown Script​
These trigger when the user "shuts down" the client. The following interactions count as a shutdown:
- Logging out of the client
- The trial expiring
- The project being deleted while a client is running
- The client being terminated from the Gateway's web interface
- Closing the client, from the client
Configurations for Client Event Shutdown Scripts are similar to Gateway Event Shutdown scripts. See the Gateway Event Scripts page for more information
Shutdown-Intercept Script​
The Shutdown-Intercept Script is unique in that it runs when a user attempts to close a client, but before the actual closing occurs. The main reason to use a Shutdown-Intercept script is to prevent the client from closing.
Even though this event has a similar name to the Shutdown Script, Shutdown-Intercept will only trigger when the client is requested to close from the client. Other interactions that trigger a Shutdown Script, such as logging out, will not trigger Shutdown-Intercept.
Preventing Client Shutdown​
There is a special property on the event object inside the Shutdown-Intercept script that can be used to prevent the client from closing: simply type "event.cancel = 1." somewhere in your code. Doing this will cancel the shutdown event and leave the client open. This allows you to set special restrictions in regard to when the client is actually allowed to shut down, such as having a certain role, as seen in the example below:
# Check to see if the user has a certain role.
if "SuperUser" not in system.security.getRoles():
# If the role is not present, it will warn the user and cancel the shutdown process.
system.gui.warningBox("Only administrators are allowed to shutdown the client.")
event.cancel = 1
Keystroke Scripts​
The Keystroke Scripts let you create different events that will activate on certain key combinations, allowing you to add keyboard shortcuts to your projects.
Client Keystroke Script Interface​
Add Script - Adds a new keystroke script.
Delete Script - Deletes the currently selected keystroke script.
Script Settings - Opens the Choose Keystroke window, allowing you to modify the keystroke that will trigger the script.
Choose Keystroke Window​
The following areas are available on the Choose Keystroke window:
- Modifiers - Additional keys or mouse buttons that must be held to trigger your script. Modifiers are inclusive, so multiple modifiers must all be held down when the key is typed to trigger the script.
- Action - Similar to the Key Event Handlers, determines what action must occur to the key to trigger the script:
- Pressed means the key was pressed,
- Released means the key was released. When used in conjunction with a modifier, this action provides the user a means to prevent the script from happening after the key has already been pressed: if the user releases the modifier before releasing the key, then the script will not trigger.
- Typed means the user typed a specific character. Selecting this action enabled the Char field under the key section. This provides an easier way to trigger the script based on non-standard ascii characters.
- Key- Which key will trigger the script. A dropdown is available when the Action is set to Pressed or Released. A Text Field is available if the Action is set to Typed.
Special keys like the Function keys (F1) or ESC key are only available in the pressed and released actions.
Some operating systems reserve certain keys for certain functions, 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.
Timer Scripts​
Run on a timer in the same fashion as their Gateway counterpart, except each instance of the project (i.e., client looking at the project containing the timer script) has a separate instance of the timer script running. Timer scripts that insert records into a database, or write to a Tag, are better suited as Gateway Event Scripts, since there will only ever be one running. If there are not any open clients, there will not be an instances of this script running.
Configurations for Client Event Timer Scripts are similar to Gateway Event Timer scripts. See the Gateway Event Scripts page for more information
Tag Change Scripts​
Monitor one or more Tags, and trigger a script in each instance of the client on Tag change. Unlike the Gateway Tag Change Script, Client Tag Change Scripts can monitor a Client Tag. Much like Timer Scripts, they only run in each instance of the client, so if there aren't any open clients, then the script will never execute.
Configurations for Client Event Tag Change Scripts are similar to Gateway Event Tag Change scripts. See the Gateway Event Scripts page for more information
Menubar Scripts​
The Client Menubar Scripts create and control the options available in the menubar of the Client. As such, these scripts are only available in the Client Scope. By default, a Client will have three menus: Command, Windows, and Help. The Windows and Help Menu are separate, and controlled through the project properties, but the Command menu is actually created in the Client Menubar Scripts.
Selecting Menubar displays the Menu Structure list.
The structure is then mimicked in the client when the menu name is selected.
Menubar Script Interface​
The user interface on the Menubar script is divided into two sections.
Menu Structure​
A tree representing the layout of the menu bar. Items at the root of the tree will appear on the menu bar in the client, and nested items will appear as subitems in the client. In the image of the Client Event Script above, notice that the Logout, Lock Screen, and Exit items are children of the Command item. When looking at the image of the menubar in the Client, these three items appear under the Command Item.
Because the Menu Structure ultimately impacts the order, the following buttons are available to help sort each item.
Add Sibling - Adds a new sibling, or peer item, to the selected item. 
Add Child - Adds a new child to the selected item. 
Move Up and 
Move Down - Moves the selected item up or down in the list. The order in the list determines the order that items appear in the menu, so these buttons can be used to group meaningful items together. - Delete - Deletes the selected item, removing it from the menu.
Item Properties​
- Name - The text on the item in the menu.
- Icon - What image should appear next to the item, if any.
- Tooltip - Optional property allowing you to specify a tooltip when the user hovers the mouse cursor on top of the item.
- Accelerator - Allows you to define a keyboard shortcut that will quickly select the item. Please see the Accelerator section below for more details.
- Mnemonic Character - Allows you to define a character key that will trigger the option when the menu is open. Please see the Mnemonics section below for more details.
- Action Script - The script that will run when the user selects the item. Every item, even those at the root and branches may have a script defined.
It is uncommon to have a script defined on a branch, as they usually act as a means to list other items.
Accelerators​
An accelerator is a key or key combination that can be pressed at any time in the client to initiate that menu item's event. If an accelerator has been configured for an item, then it will be listed on the menu in the client. Below we see our initial menu bar has been modified with the accelerator Shift+F1. Now the Lock Screen item may be called anywhere in the client by holding Shift and pressing the F1 key.
Mnemonics​
The mnemonic character is a key that can be pressed when the menu is opened. This is functionally similar to an Accelerator, in that it allows the user to select an item in the menu without clicking on it. However, mnemonics differ in that they only call an item when the menu is open, and the item is visible on the screen.
Users can identify mnemonics by a character to the right of the command in the menu. In the image below, we see that the Logout item has an "L" character. This means the user can now press the "L" key to select the Logout item. However, this will not work unless the menu is open, so if the user accidentally presses the L key while the menu is closed, the script will not trigger. Notice, how each command also has a mnemonic character defined for each command.
Message Scripts​
Client Message Handlers are created and called using the same mechanisms as Gateway Event Scripts. There are two main differences that make Client Message Handlers stand out from Gateway Message Handlers: they run in the Client, and they have different settings.
Client Message Handler Settings​
Client Message Handlers have the following settings:
- Name - The name of the message handler. Each message handler must have a unique name per project.
- Threading - Determines the threading for the message handler. Contains the following options:
- Shared - The default way of running a message handler. Will execute the handler on a shared pool of threads in the order that they are invoked. If too many message handlers are called all at once and they take long periods of time to execute, there may be delays before each message handler gets to execute.
- Dedicated - The message handler will run on its own dedicated thread. This is useful when a message handler will take a long time to execute, so that it does not hinder the execution of other message handlers. Threads have a bit of overhead, so this option uses more of the Gateway's resources, but is desirable if you want the message handler to not be impeded by the execution of other message handlers.
- EDT - This will run the message handler on the Event Dispatch Thread (EDT) which also updates the GUI. If a message handler were to take a long time to execute, it would block the GUI from running which may lock up your client. This is helpful when your message handler will be interacting with the GUI in some way, as the GUI will not be able to update until the message handler finishes.
For more information on Message Handlers, such as working with the Payload argument, or calling them, please see the Gateway Event Scripts page.
Troubleshooting Client Scripts​
The Console is very a important tool in Ignition for troubleshooting Client scripts. You can check to see if your script is working directly from the Client window, or the Designer while in Preview Mode. Any client scripting errors along with printouts go to the Console. The Console will identify the script name, error message, what line the script error is in, and a description of the problem.
To access the Console from a Client, go to the menubar and select Help > Diagnostics > Console. To access the Console from Preview Mode in the Designer, go to the menubar Tools > Console.