Implementing guiEvent
The guiEvent function serves as a gateway for all events.
Therefore, a typical implementation will consist of switching logic that dispatches the events to other functions that actually provide functionality to handle the events.
In this section the calling syntax, arguments and return values will be discussed, followed by a small example.
Syntax
function payload = guiEvent(metaData, payload)
...
end
def gui_event(meta_data: dict, payload: dict) -> dict:
...
return payload
Arguments
metaData:
Meta data describing the client session. It is a struct/dict with fields:
session_id: unique ID for the session, can be used to differentiate between multiple instances of the applicationnamespace: package name of the application
payload:
When entering the function, this contains the event data containing all values as provided by the client. It is a struct/dict with fields:
action:'event'download: information regarding the download of a file. Empty when no file is being downloaded.event: name of the event that was triggered.followUp(optional): name of a follow-up event that will be triggered after the current one has completed.formMap: Map representing the form definition.key: identifier of the component that triggered the eventsubmission: struct/dict with fields:data: struct/dict with fields:eventCounter: incrementing counter; do not change.<key>: multiple fields containing the values of the components identified by the keys.<nested form key>: See Nested forms for more information. Struct/dict with fields:data: struct/dict with fields:<key>: multiple fields containing the values of the components identified by the keys.
updateForm: whentrue, the form definition is sent to the front end. The default value isfalse. Use this only when the form definition changes. Updating the form definition will be slower than only updating the submission data.alerts(optional): array of struct/dict with fields:type: message type, see Alertsmessage: string
In the guiEvent function, the submission field may be altered before sending payload back to the front-end in order to present results to the user.
Additionally, the followUp field can be changed, which is described below.
Key & Event
The key is unique for each component within the context of its parent and/or nested form, but event can be shared between components.
This can be useful when multiple components (partially) share functionality. See Example.
Dispatching events
As the number of possible events in your application grows, your guiEvent function may contain an enormous switch/case or if/elif construction. In order to mitigate this, it is possible to automatically call functions based on event names without having to specify every single event. This can be achieved by using the dispatchEvent or getEventFunction utility functions:
payload = utils.dispatchEvent(metaData, payload);
caller = utils.getEventFunction(meta_data, payload)
payload = caller(meta_data, payload)
The dispatchEvent function calls a function equal to the name of the event that was triggered, whereas getEventFunction only returns the function object.
Note: In Python, breakpoints cannot be detected in functions executed via the
dispatchEventfunction. It is therefore recommended to usegetEventFunctioninstead.
The functionality of the dispatching mechanism is illustrated with the example below. Consider the initialization code of a form with several buttons, each with their own event:
btn1 = component.Button("btn1", parent);
btn1.setEvent("ModelS.getResults");
btn2 = component.Button("btn2", parent);
btn2.setEvent("writeToDatabase");
btn3 = component.Button("btn3", parent);
btn3.setEvent("ModelX.getValue");
The following guiEvent functions handle these events, the first one using conditional logic and the second one using the dispatchEvent or getEventFunction functions:
function payload = guiEvent(metaData, payload)
switch payload.event
case "ModelS.getResults"
payload = ModelS.getResults(metaData, payload);
case "writeToDatabase"
payload = writeToDatabase(metaData, payload);
case "ModelX.getValue"
payload = ModelX.getValue(metaData, payload);
end
end
function payload = guiEvent(metaData, payload)
% Use the automatic dispatch.
payload = utils.dispatchEvent(metaData, payload);
end
def gui_event(meta_data, payload):
if payload["event"] == "ModelS.getResults":
ModelS.getResults(meta_data, payload)
elif payload["event"] == "writeToDatabase":
writeToDatabase(meta_data, payload)
elif payload["event"] == "ModelX.getValue":
ModelX.getValue(meta_data, payload)
def gui_event(meta_data, payload):
# Use the automatic dispatch.
caller = utils.getEventFunction(meta_data, payload)
payload = caller(meta_data, payload)
Follow-up Event
When the followUp field is added to payload, and its value is the name of another event, the follow-up event will be triggered after completion of the current one.
The component key will be identical for both events. The most common use case of this feature is to present the user with intermediate results of a calculation that consists of multiple stages.
Consider combining this with the StatusIndicator component.
An example of the follow-up event is given below:
function payload = guiInit(metaData)
form = Form();
payload.form = form;
btnLoadData = component.Button("run", form);
btnLoadData.label = "Run";
btnLoadData.setEvent("Run");
txtId = component.TextField("id", form);
txtId.label = "ID";
end
function payload = guiEvent(metaData, payload)
switch payload.event
case "Run"
pause(1);
payload = utils.setSubmissionData(payload, "id", "Running phase 1");
payload.followUp = "RunNext";
case "RunNext"
pause(1);
payload = utils.setSubmissionData(payload, "id", "Finalizing...");
payload.followUp = "RunFinal";
case "RunFinal"
pause(2);
payload = utils.setSubmissionData(payload, "id", "Done!");
end
end
import time
def gui_init(meta_data: dict) -> dict:
form = Form()
payload = {"form": form}
btnLoadData = component.Button("run", form)
btnLoadData.label = "Run"
btnLoadData.setEvent("Run")
txtId = component.TextField("id", form)
txtId.label = "ID"
return payload
def gui_event(meta_data: dict, payload: dict) -> dict:
if payload["event"] == "Run":
time.sleep(1)
utils.setSubmissionData(payload, "id", "Running phase 1")
payload["followUp"] = "RunNext"
elif payload["event"] == "RunNext":
time.sleep(1)
utils.setSubmissionData(payload, "id", "Finalizing...")
payload["followUp"] = "RunFinal"
elif payload["event"] == "RunFinal":
time.sleep(2)
utils.setSubmissionData(payload, "id", "Done!")
return payload
Example
The following example shows an implementation of guiEvent that uses the event names and component keys to dispatch the event to the correct function.
function payload = guiEvent(metaData, payload)
% Switch on event name.
switch payload.event
case "calculate"
% The calculate event has an application-specific preprocessing step.
% Preprocess the data entered in the form before performing calculations.
preprocessed_data = preprocess(payload);
% Switch on the component key.
% Each component starts a different calculation.
switch payload.key
case "stage1StartButton"
payload = runStage1(payload, preprocessed_data);
case "stage2StartButton"
payload = runStage2(payload, preprocessed_data);
end
case "estimate"
payload = estimate(payload);
end
end
def gui_event(meta_data, payload):
# Switch on event name.
if payload['event'] == 'calculate':
# The calculate event has an application-specific preprocessing step.
# Preprocess the data entered in the form before performing calculations.
preprocessed_data = preprocess(payload)
# Switch on the component key. Each component starts a different calculation.
if payload['key'] == 'stage1StartButton':
runStage1(payload, preprocessed_data)
elif payload['key'] == 'stage2StartButton':
runStage2(payload, preprocessed_data)
elif payload['event'] == 'estimate':
estimate(payload)
return payload