Implementing a Device Interface: System Event Handler

The System Event Handler provides a convenient way to handle notifications broadcasted by a System Event. When the event is triggered at the runtime, all Handlers connected to it will be notified automatically. This, for example, can be a notification when the device starts to charge the battery. Thereupon the GUI application can react to the event and e.g. update the battery symbol or display an alert informing the user about the new situation. As such, System Event Handlers and System Events build an integral element of the interface separating the GUI application and the underlying device.

Usually, you use the System Event Handler template when implementing a GUI component interested in processing of the particular event. You add in such case a new System Event Handler to the GUI component and configure it to be connected with the original System Event. If necessary your application can manage several different events and Handlers. The System Event Handlers are not restricted to be used in GUI components only. If your application case it requires you can add the Handler to any other, non visual component.

The figure below demonstrates the principle function of a System Event Handler. This example assumes that the device contains a battery. As soon as the battery charging begins, the software running on the device triggers the System Event object BatteryChargingEvent found in the Device Interface. This in turn notifies all associated System Event Handlers. The Handlers signal thereupon their associated slot methods onEvent. The slot methods are executed updating e.g. the appearance of the belonging GUI components or presenting alerts:

The System Events and the System Event Handlers help to separate the GUI components from the device functionality by what the structure of the entire GUI application can be simplified. The following sections are intended to provide you an introduction and useful tips of how to add and use System Event Handlers. To better understand the underlying concepts we also recommend you to read the chapter Implementing a Device Interface as well as Integrating with the device.

Add a new System Event Handler

System Event Handlers are usually used when implementing a component. Accordingly, you add the System Event Handler to a class:

Ensure that Composer shows the class where you want to add the new System Event Handler.

Then ensure that the Templates window is visible.

In Templates window switch to the folder Device.

In the folder locate the template System Event Handler.

Drag & Drop the template into the Composer window:

Eventually name the new added Handler.

In the screenshot above you see that new added System Event Handlers consist of two members: an object and slot method. Within the method you implement code to execute when the event is triggered. The object, in turn, takes care of the connection to the System Event so that when the event is triggered the slot method is signaled. The both members are also accompanied by an annotation providing helpful tips how to proceed. If undesired, you can select and delete the annotation.

Inspect the System Event Handler object

As long as the System Event Handler object is selected you can inspect and modify its properties conveniently in the Inspector window as demonstrated with the property Event in the screenshot below:

This is in so far worth mentioning as all following sections describe diverse features of the System Event Handler by explicitly referring to its corresponding properties. If you are not familiar with the concept of a property and the usage of Inspector window, please read first the preceding chapter Compositing component appearance.

Connect the Handler with a System Event object

In order to react to events, you have to connect the System Event Handler to the corresponding event source, to the System Event object existing usually in a Device Interface. This connection is established by simply assigning the event object to the property Event of the respective Handler. With the Inspector Assistant you can conveniently select the right event object when you edit the initialization expression for the property Event. For example:

As soon as you have connected the both, the Handler is able to react to notifications broadcasted by the associated event object. To dissolve the connection again just assign the value null to the property Event or revert it to its original value.

Implement the onEvent slot method

When the Handler receives a notification from its associated System Event, it sends a signal to the slot method stored in the Handler's property OnEvent. Within the slot method your particular implementation can react and process the event. It's completely up to you what the implementation does. For example, if the event indicates the beginning of a battery charging process, your implementation could show an Image view with the respective battery charging symbol:

BatteryChargingSymbol.Visible = true;

Also common is the application case to present alerts to the user, especially when the event notifies about critical situations like a Low Battery Warning. Assuming, you have implemented such alert as Dialog component, following could be the code to execute in the slot method. Accordingly, when the event arrives the dialog is presented:

// Create a new instance of the Warning Dialog
var Core::Group dialog = new Application::LowBatteryWarningDialog;

// Present the Dialog now
PresentDialog( dialog, null, null, null, null, null, null,
                       null, null, false );

New added System Event Handlers provide per default an own onEvent slot method connected already to their OnEvent property. Usually after adding a new Handler you will open this slot method for editing and modify its implementation as required in your application case. You can, of course, rename or even remove the default slot method and replace it by your own. In such case, don't forget to assign the new slot method to the property OnEvent of the affected System Event Handler object.

IMPORTANT

If there are several Handlers connected to one and the same System Event, the order in which the Handlers are notified is not predictable. Accordingly, the order in which the onEvent slot methods are executed can't be predetermined.

Trigger the System Event

Triggering of events occurs via corresponding System Event object belonging typically to the Device Interface. How to do this is explained in the section Trigger the System Event.

Evaluate values passed with the System Event

As explained in the section Provide data together with a System Event, it is possible to associated optional data when event is triggered. This so-called context can be evaluated during the execution of the onEvent slot method. To access this data you use the variable Context. Following code example demonstrates the implementation of such adapted onEvent slot method:

// Try to cast the object provided in 'Context' to the expected class
// e.g. 'Application::BatteryChargingLevel'
var Application::BatteryChargingLevel data =
  (Application::BatteryChargingLevel)SystemEventHandler.Context;

// Only if valid data is provided with the event, access and evaluate
// the provided information
if ( data != null )
  Text.String = "Charging " + string( data.Level ) + " %%";

The above code assumes that the System Event has been triggered together with associated object of user defined class Application::BatteryChargingLevel. Since System Events can be triggered with any arbitrary objects, we have to test as first whether the provided data is really of the expected class. For this purpose the value stored in the Context variable is subjected an object runtime cast. If the cast was successful, we can access the values stored inside the object. The above code limits to update the Charging .. % string displayed in a Text view.

Following example project demonstrates the above explained application case of a Battery Charging Level Event. For the sake of simplicity, the project does not depend on any extern software running on the device. Instead the events are simulated by a simple timer. Each time the timer expires, the event is triggered and new battery charging level is passed together with it. The System Event Handler reacts to the event and adapts a progress bar within a GUI component. As soon as the charging is finished (battery is full), another event Battery Charging Finished Event is sent. Thereupon the GUI component knows that the battery is full:

DOWNLOAD EXAMPLE

Please note, the example presents eventually features available as of version 9.00

Disable a System Event Handler

By initializing the property Enabled with the value false you can explicitly suppress a System Event Handler from being able to react to notifications triggered by the associated System Event.