Implementing a Device Interface: Property Observer

The Property Observer provides a convenient way to handle notifications broadcasted by a Property. When at the runtime the value of the Property is changed, all Observers connected to it are notified automatically. This, for example, can be a notification when the electric current measured in a power supply device changes. Thereupon the GUI application can react to the event and e.g. display the actual current value. As such, Property Observers and Properties build an integral element of the interface separating the GUI application and the underlying device.

Usually, you use the Property Observer template when implementing a GUI component interested in observing a particular Property. You add in such case a new Property Observer to the GUI component and configure it to be connected to the original Property of interest. If necessary your application can manage several Observers and multiple Properties. The Property Observers are not restricted to be used in GUI components only. If your application case it requires you can add the Observer to any other, non visual component.

The figure below demonstrates the principle function of a Property Observer. In this example we assume that the GUI belongs to a laboratory power supply device. In such device, the measured electric current and voltage should be displayed on the screen. The corresponding Device Interface is thus composed of two Properties Voltage and Current representing the respective values in the device. The both GUI components, in turn, contain Property Observers connected to the Properties. Consequently, when one Property is changed, the respective Observers are notified automatically. The Observers 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, etc. For example, the implementation in the first component calculates and displays the actual electric power:

The Property and the Property Observer 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 Property Observers. 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 Property Observer

Property Observers are usually used when implementing a component. Accordingly, you add the Property Observer to a class:

Ensure that Composer shows the class where you want to add the new Property Observer.

Then ensure that the Templates window is visible.

In Templates window switch to the folder Device.

In the folder locate the template Property Observer.

Drag & Drop the template into the Composer window:

Eventually name the new added Observer.

In the screenshot above you see that new added Property Observers consist of two members: an object and slot method. Within the method you implement code to execute when the event occurs. The object, in turn, takes care of the connection to the Property of interest so that when the Property is notified 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 Property Observer

As long as the Observer object is selected you can inspect and modify its properties (its attributes) conveniently in the Inspector window as demonstrated with the property Outlet in the screenshot below:

This is in so far worth mentioning as all following sections describe diverse features of the Observer by explicitly referring to its corresponding properties (attributes). 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 Observer to a Property

In order to react to events, you have to connect the Property Observer to the corresponding Property existing usually in a Device Interface. This connection is established by simply initializing the property Outlet of the respective Observer with a reference to the Property of interest. With the Inspector Assistant you can conveniently select the right Property when you edit the initialization expression for the property Outlet. For example:

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

Implement the onEvent slot method

When the Observer receives a notification from its associated Property, it sends a signal to the slot method stored in the Observer'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. In the simplest case, your implementation will probably update a view (e.g. Text view) displaying the value from the associated Property:

Text.String = string( Application::Device.Current ) + " Ampere";

Also common is the application case to present alerts to the user, especially when the event notifies about critical situations like an Overload. Assuming, you have implemented such alert as Dialog component, following could be the code to execute in the slot method. Each time the Property Current in the Device Interface changes, the code verifies whether the Property value does exceed 20 Ampere. If this is the case, the alert dialog is presented:

// The electric current exceeds 20 Ampere
if ( Application::Device.Current > 20 )
{
  // Create a new instance of the Warning Dialog
  var Core::Group dialog = new Application::OverloadDialog;

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

New added Property Observers 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 Property Observer object.

IMPORTANT

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

Following example project demonstrates the usage of Observers and Device Interface Properties. The project consists of a GUI component containing a Horizontal Slider. The slider is connected to the Device Interface property Voltage. Accordingly, dragging on it modifies this Property. The GUI component contains further two Property Observers connected to the Voltage and Current Properties existing in the Device Interface. Each time one of the Properties is altered, a slot method is executed calculating and displaying the resulting electric power. Since the example is detached from a real device, it limits to log a message that the Property has been changed. In practice the implementation could modify/read GPIO pins, etc. and so control the voltage and track the electric current in the power supply:

DOWNLOAD EXAMPLE

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

Trigger the Property Observers

Property Observers are notified automatically via associated Properties belonging typically to the Device Interface. This is concrete the case when at the runtime the GUI application assigns a new value to the Property or the external software running on the device updates the Property.

Disable a Property Observer

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