Trigger an event when a component's value changes

Components that contain a value can trigger an event whenever that value changes by using the following command on them:

obj.properties = {"triggerHappy": True}
obj.properties = {"triggerHappy": "my.module.change"}

obj.addCustomProperty("triggerHappy", true);
obj.addCustomProperty("triggerHappy", "my.package.change");

The event that is triggered will end up in the gui_event function of the form. The payload will contain the following information on the event:

  • action: "event"
  • event: "change" when triggerHappy is true, or the triggerHappy value when it is a string
  • key: key of the component whose value has changed

Note that using this option causes the component to trigger an event for every value change. This is convenient for checkboxes and similar components. However, for example for TextField components, an event will be triggered after every keystroke. In order to only trigger an event when the user is done editing a field, it is advised to use the EventOnBlur option for components with entered text. Unlike that feature, this option does not apply to child components.

Debouncing

Some components may emit many change events in rapid succession (e.g. a slider being dragged more than one step). When such a component has triggerHappy configured, multiple calls to the back-end may be queued without waiting for the back-end to respond, causing unpredictable behaviour, such as infinite loops switching between a number of values.

To prevent multiple change events being sent at the same time, a debounceTime (in milliseconds) can be specified to delay calling the back-end. When other change events occur during the delay, only the latest event is let through.

obj.properties = {"triggerHappy": True, "debounceTime": 1000}

obj.addCustomProperty("triggerHappy", true, "debounceTime", 1000);