Gateway Events versus Client Events
Some Client Events are similar conceptually to events located in Gateway Events scripts. These events work in a similar manner to Gateway Event Scripts, with some small differences. Those differences are listed below.
- Startup Scripts - 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.
- Shutdown Scripts - These trigger when the user closes the client, or logs out.
- 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. Also note that if there are not any open clients, there will not be an instances of this script running.
- 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.
- Message Handlers - Client Message Handlers do have some notable differences, so those will be discussed further down on this page.
The Shutdown-Intercept Script is unique in that it runs when a user attempts to shutdown a client, but before actual shutdown occurs. The main reason to use a Shutdown-Intercept script is to prevent the client from closing.
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:
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.
Below we see a configured Menu Structure list.
Next we see the results of the structure in the client.
Menubar Script Interface
The user interface on the Menubar script is divided into two sections.
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, note 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.
- 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 however that it is uncommon to have a script defined on a branch, as they usually act as a means to list other items.
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.
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 the underlined character in the menu. In the image below, we see that the Logout item has an underlined "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.
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.