Grlib - Widget Tree Structure

StellarisWare Grlib

StellarisWare Grlib Block Diagram

The Grlib (Graphic Library) delivered in StellarisWare software package offers the possibility to develop a complex GUI (Graphical User Interface) on widget levels with high-level API (Application Programming Interface). The Widget Classes of Grlib is build on top of the lower layers basic Graphics Functions (to draw lines, rectangles, circles, etc.) and display drivers (e.g. LCD driver) allowing user to easily build the user interface with pre-defined controls such as buttons, sliders, checkboxes, etc.

The Grlib supports the following widget types:

• Canvas: simple drawing surface providing no means for interaction with the user (can be filled with a color, outlined with a color, having an image/test drawn within the canvas area, and allowing application to draw into the canvas)
• Checkbox: graphical element whcih can be selected or unselected, resulting in a binary selection.
• Container: providing means of grouping widget together within the widget hierarchy.
• Image Button: providing a button that can be pressed, causing an action to be performed.
• Listbox: allowing the user to select one from a list of several strings held by the widget.
• Push Button: providing a button that can be pressed, causing an action to be performed.
• Radio Button: providing a graphical element that can be grouped with other radio buttons to form a means of selecting one of many items.
• Slider: allowing the user to drag a marker either horizontally or vertically to select a value from within an application-supplied range.

Grlib Widget Tree Structure

The widgets in Grlib are organized in a tree like structure to enable the Widget Manager painting the widgets and processing/passing user's input to the widgets in a deterministic manner. Each widget has basically three pointers which connect them with the other widgets in the tree structure:

• Parent pointer (pParent): pointer to the widget on the above level
• Sibling pointer (pNext): pointer to the widget on the same level
• Child pointer (pChild): pointer to the widget on the below level

The following image shows an example of a widget tree structure:

As can be seen above, the widgets are anchored by a global called WIDGET_ROOT. The other user defined widgets can be attached to the WIDGET_ROOT in a tree like structure either during compile-time (hard-coded in the Widget Class structure definitions) or run-time (by using WidgetAddr(tWidget*pParent, tWidget *pWidget) function).

Determining the correct tree structure hierarchy is vital for the application to ensure the correct repainting process and handling of user input. Consider the following example with two containers, one contains two radio buttons, and another one contains a push button:

Painting The Widget Tree

The Widget Tree is painted starting at WIDGET_ROOT downwards (parents are painted before children - therefore parents can be thought of as being below their children on the screen). For the example above, the following repainting process will be executed by the Widget Manager if the application executes (re)painting by calling WidgetPaint(WIDGET_ROOT):

Passing User Input

In contrast of how the Widget Manager (re)paints the widgets downwards in the widget tree structure hierarchy, the User Input is passed upwards in the tree structure (children gets the input first before the parents). The user input message passed to the widgets in the tree structure contains the following information:

• Message type (WIDGET_MSG_PTR_DOWN, WIDGET_MSG_PTR_MOVE, or WIDGET_MSG_PTR_UP):
  • When a pointer down message (WIDGET_MSG_PTR_DOWN) is received, the Widget Manager passes it to all widgets, children first.
  • Each widget checks to see if the pointer is within its area and, if so, claims the message by returning “true” from the message procedure.
  • All further pointer move messages (WIDGET_MSG_PTR_MOVE) are sent to this widget until pointer up (WIDGET_MSG_PTR_UP) is received or the widget is removed.

• X and Y coordinates of the input.

For the example with the two containers above, the following user input processing will be executed by the Widget Manager if the application receives a user input: