This article describes the integration of an Embedded Wizard generated GUI application into your main application. It covers the necessary steps to initialize and de-initialize the entire system and it describes the details about launching the GUI application and providing the necessary user or system events.

First of all, some header files from the appropriate Platform Package directory have to be included into your main.c file to get access to the Runtime Environment (RTE), the Graphics Engine (GFX) and some generated header files from Mosaic class library:

In order to find all of the above header files during the compilation of your main.c file, the include path has to be set correctly within your makefile. In case of a GCC compiler, this is typically done by using the -I compiler flag.

Before the Embedded Wizard generated GUI application can be executed on the target platform, the framebuffer and the Graphics Engine have to be initialized.

The initialization of the framebuffer depends completely on your target system and the underlying graphics API. For example in case of DirectFB, a DirectFB surface needs to be created, in case of OpenGL ES 2.0 the frame buffer is typically created via EGL.

In order to simplify this task, a template of the main.c file including the necessary initialization is provided as so called Build Environment together with a Platform Package.

Nevertheless, the following code snippet illustrates the necessary steps to initialize the Embedded Wizard generated GUI application:

The parameter EwScreenSize is an automatically generated constant in the module Core.c of type XPoint. This value contains the size of the screen as it was defined in the attribute ScreenSize within the profile for that the code was generated.

The parameter EwApplicationClass, contains the root object of the GUI application. This application class is also defined within the attribute ApplicationClass of the profile.

The initialization of your device driver is needed in case that your GUI application contains a Device Interface that exchanges data, commands or events with an underlying system. For more details, please have look to the article Implementing a Device Interface.

Embedded Wizard generated UI applications are running in an (endless) loop, which drives the UI application. This main loop is responsible to provide all user inputs to the UI application, to start the processing of timers and signals, to take care for the update of the display and finally to start the garbage collection.

The main loop can be implemented within your main() function or it can be implemented as a separate OS task. However, it is absolutely important, that the complete Embedded Wizard generated UI is running within one task! Splitting the different actions in several tasks (e.g. to start the garbage collection from another task) will cause unpredictable results…

The following code snipped shows the typical implementation of a main loop:

In the following, we want to have a closer look into the single steps of this main loop.

Typically, every GUI application exchanges data with an underlying system in order to get data from a certain hardware device or to start a certain action. The interface between the GUI application and the underlying system is implemented by a Device Interface class and a device driver: The Device Interface class is accessed by the GUI application. The device driver is the counterpart that communicates with the real devices (e.g. by calling BSP functions, by setting registers, by calling other drivers,...).

The function YourDevice_ProcessData() is called from the main UI loop, in order to process data and events from your particular device. This function is responsible to update properties within the device class if the corresponding state or value of the real device has changed. This function is also responsible to trigger system events if necessary. The return value of the function indicates, that properties have been updated or events have been triggered.

For more details, please have look to the article Implementing a Device Interface.

Depending on the operating system or generally speaking the application runtime environment, the input device drivers (keyboard, remote control, hardware buttons, etc.) will generate messages when the input device state changes (e. g. a remote control button is pressed). Typically, the input task will have to write the input data into a message queue and the main loop can then process these events out of this queue and feed them to the GUI application.

If an event is in the message queue (e.g. a remote control key pressed event) the main loop first has to examine the event. This means, the event information has to be translated into a Mosaic key code. This has to be done within the function GetKeyCommand(): all key events which are needed within your UI application, need to be translated into a Mosaic key code. Typically this function is part of the main.c template.

For this purpose, the Mosaic class library contains a set of predefined keys in the enumeration KeyCode of unit Core. For example, the identifier CoreKeyCodeOk corresponds to the Ok key on the remote control or the Enter key on a keyboard.

As soon as the incoming key event is translated into an appropriate Mosaic key code, it can be passed to the GUI application by using the method DriveKeyboardHitting().

Some devices are cursor operated (e.g. via the touch panel, a joystick or the mouse device). In this case a device driver will generate cursor information and write it into a message queue. Similar to key events, the main loop have then to read the mouse or touch events from this message queue and feed them to the application.

The Mosaic class Core::Root (the base class for every GUI application) provides the both methods DriveCursorHitting() and DriveCursorMovement(). These serve as interface you call from the main loop to feed the GUI application with events generated by a mouse device or a touch screen. These both methods are limited to handle a single interaction at the same time. They are thus ideal when your device is not using any multi-touch capable touch screen.

If the touch screen in your device is able to distinguish between simultaneous touch interactions you can adapt the above source code to call the methods DriveMultiTouchHitting() and DriveMultiTouchMovement() instead of DriveCursorHitting() and DriveCursorMovement(). The unique difference to the single-touch version of the methods is, that they expect a number in range 0 .. 9 identifying the finger, which has caused the event.

Usually, multi-touch screen drivers do track every movement of every finger touching actually the screen and are so able to identify the fingers individually. You have to translate this finger identification in a number lying in range 0 .. 9 and pass this value to the method DriveMultiTouchHitting() and DriveMultiTouchMovement() when calling it.

For example, the user touches the screen with one finger, then you call the methods with the number 0 since this number identifies the first finger. When the user presses then a second finger you have to use the value 0 for all events associated with the first finger and the value 1 for all events caused by the second finger. Similarly, when the user presses third finger on the screen, all events generated by this third finger should be passed with the value 2 when calling the methods DriveMultiTouchHitting() and DriveMultiTouchMovement().

Within an Embedded Wizard generated UI application all timer objects, that are currently running, are stored in a timer list. In this step, the timer list is traversed and all expired timers are handled. The number of processed timers is returned by this function. In order to activate the timer processing, the function EwProcessTimers() of the Runtime Environment has to be called.

In an Embedded Wizard generated UI application, signals can be sent in order to trigger slot methods with certain behavior. Beside the regular signal statement, which is processed immediately, special postsignal and idlesignal statements are collected and executed right before, respectively after a screen update is performed. The processing of the deferred signals is done by calling EwProcessSignals().

In reaction to any system/key/cursor event, any signal or any expired timer the UI application can change its look and for example open a new dialog box or move a bitmap across the screen. In that case, all affected objects are marked as invalid. During the update of the root object, all invalid areas are examined and changes to the visible objects are processed. Finally, the resulting display is shown within the visible framebuffer.

The following function contains the complete display update cycle:

In the last step of the main loop the garbage collection is only triggered if any processing has happened. The function EwReclaimMemory() of the Runtime Environment is called.

When the application is finished, the unused resources have to be released using the following commands: