Message handler scripts run when system.util.sendMessage() is called on a remote Client or on the Gateway to send a message. Message handlers can be created for both Gateway and Client scopes.
Threading
By default, all message handlers for a project execute on a single shared background thread. This arrangement is normally the most efficient. However, if a message handler is performing a lengthy operation, messages may become backed up while waiting for the shared thread. In order to prevent this, you can specify that a message handler runs on its own dedicated thread by setting the Threading value to "Dedicated".
WARNING: Both the shared thread and dedicated threads run in the background, meaning that if you need to update a component in the GUI (window navigation, setting and getting component properties, showing error/message popups, etc) you must wrap the code in a function and use system.util.invokeLater() to run the function as shown in the example below. An alternative is to set the threading value to "EDT". This value will execute the message handler code directly on the Event Dispatch Thread (EDT). The disadvantage of this approach is that your entire Client will freeze if the message handler script does not execute its code quickly.
Message payload
A message sent using system.util.sendMessage()may optionally contain a message payload Dictionary object to access custom message parameters. This Dictionary can be accessed from the "payload" variable as shown in the example below. If no Dictionary was passed when sending the message, then the "payload" variable will be an empty Dictionary.
Example send script
payloadDict = {}
payloadDict['first']="Hello"
payloadDict['second']="World"
system.util.sendMessage("ProjectX","myHandler",payloadDict)
Example message handler using invokeLater()
def handleMessage(payload):
"""
message = "Message received by ProjectX myHandler. "
if payload.has_key('first'):
message += "First param=" + str(payload['first']) + ". "
if payload.has_key('second'):
message += "Second param=" + str(payload['second']) + ". "
def handleMessage(theMessage=message):
import system
window = system.gui.getWindow("Main Window")
rootContainer = window.getRootContainer()
textarea = rootContainer.getComponent("receivedMessages")
textarea.text += theMessage + "\n"
system.util.invokeLater(handleMessage)