Client Event Scripts

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

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

  Note: 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. 

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.