Search

User Manual

GETTING STARTED


MODULES AND PLATFORM


APPENDIX


TUTORIALS & HELPFUL TRICKS


GLOSSARY


STRATEGIC PARTNER LINKS

Sepasoft - MES Modules
Cirrus Link - MQTT Modules

RESOURCES

Inductive University
Ignition Demo Project
Knowledge Base Articles
Forum
IA Support
SDK Documentation
SDK Examples

ALL MANUAL VERSIONS

Ignition 8
Ignition 7.9
Ignition 7.8

Deprecated Pages

Skip to end of metadata
Go to start of metadata


Client Event Scripts Overview

Client Event Scripts execute in the running Client, which means that they may never execute if no clients are running, or they may execute many times if multiple clients are running. Client Event Scripts will also execute in the Designer, but only in Preview Mode. Because Clients are full-fledged applications, Client Event Scripts run on the computer running the Client, not on the Gateway's host server computer. This means that they don't have access to the Gateway's file system, and so on.


On this page ...


IULocgo


Gateway vs Client Event Scripts

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. 

System functions are available for both Client Event Scripts and Gateway Event Scripts, but some system functions are specific to either one or the other.  When you're writing event scripts, it's important to remember the scope of where you writing the script: Client or Gateway. You can check Scripting Functions in the Appendix to see list of all system functions, their descriptions, and what scope they run in. 


Shutdown-Intercept Script

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:

Python - Cancel Application Exit
# 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.


IULocgo


Keystroke Scripts



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. 

Below we see a configured Menu Structure list.

Next we see the results of the structure in the client. 


IULocgo


Menu Bar

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

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

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.



IULocgo


Script Messaging

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.   


Related Topics ...

  • No labels