[00:00] In this lesson, I'll demonstrate how message handlers work. Message handlers allow you to write a script that can then be invoked from another window, project, or gateway. This gives you the ability to send messages between projects or gateways, or even execute code that alters your project. Message handlers can be set up for Vision clients, Perspective sessions, or gateways, but in this video I'll focus on showing client message handlers. I can access client message handlers via the client events window in the project browser. To create a message handler, I'll need to give it a name and then choose between shared, dedicated, or EDT threading. I'll include a link to our user manual below the video if you'd like a refresher on shared and dedicated threading, but client event scripts include the extra EDT option. Picking EDT will run the message handler on the event dispatch thread, which updates the GUI. This is helpful when your message handler will be interacting with the GUI in some way, such as window navigation, getting or setting component properties, or showing message popups. Once it's created, the script can be written to decide what logic is executed when it's invoked. You'll notice that the parameters box above the script tells us about the payload that's passed to this message handler and if you wanna access any specific object in the payload dictionary, it can be accessed with a key for that argument name.

[01:18] Then once the script is written, it can be called with one of three functions from the system util library. sendMessage, sendRequest, and sendRequestAsync. I'll provide a link to the appendix of our user manual If you'd like to learn more about these functions. In short though, sendMessage, will only call the message handler, but sendRequest and sendRequestAsync will call the message handlers, but will also expect a return value. It's important that your message handler script returns something if you're gonna use one of those two functions. Because these are client event scripts, the message handlers will be called on all open clients. However, the system functions have optional parameters that allow you to specify users or roles so that you can filter which clients will actually run the scripts. I'll demonstrate a client message handler with two different projects I've created. My first project, test, has a window with a text area and a button.

[02:05] The script on the button calls the sendMessage function and passes an argument for the name of the project I'm testing, the name of the message handler I'm trying to call in that project, and then I'm passing it a payload containing the contents of the text area. As a reminder, the payload is a dictionary and I'm calling the key to the text area value "message". Then if I open the message handler project, I'll find the "Message Test" message handler, and this is calling system.gui.messageBox to open up pop-up message with the text area contents, and I'm accessing that via the "message" key of the payload dictionary. So I'll open up my clients, click the button, and test. And then any clients that currently have MessageHandlerProject open, will see the popup and the contents of the text area from the test project. And with that, I was able to send a message and pass information from one project to another.