Difference between revisions of "Creating a widget"

Revision as of 18:30, 10 April 2016

It's possible to implement custom widgets. A custom widget can be declared and implemented outside of the µGFX library. This means that it can be part of the actual project and that it's not necessary to do any modification of the µGFX library itself. This article will explain and show how to create a custom widget. As an example we'll create a statusbar widget. The statusbar consists of a rectangular area, the current system time, two icons to indicate USB and SD-Card state and a button to open the settings dialog.

It's vital that you've read the GWIN article and the corresponding sub-articles about windows, widgets and containers before following this guide.

Note: If you just want to change the look of an existing widget, please have a look at WidgetStyles and custom rendering functions.

Architecture

A widget consists of three main parts: The object structure, the VMT and the rendering routine.

Object structure

The C language is not object oriented - yet it's possible to write object oriented software without any problems. The philosophy is to create a struct which is the object and to pass that struct as the first parameter to any function that has to have access to the object. A widget is an object and hence it needs a struct that defines the object. The only thing that makes the widget object struct become a widget struct is that the very first field is a GWidgetObject:

typedef struct StatusbarObject_t {
    GWidgetObject w;  // Base Class
} StatusbarObject;

Note that it is absolutely mandatory that the GWidgetObject is the very first field in the struct. This is needed to implement inheritance and polymorphism. After that first field you can add any field you want to the widget object struct. For example, a slider would add fields to hold the minimum, maximum and current value. A list widget would hold a list here. A text edit (line edit) would hold the current cursor position and so on. In terms of an object oriented language this is the private area of the class. In our case we store three variables to store the current system time in hours, minutes and seconds. The information whether the USB or SD-Card are present will be stored in the flags (see below) to save memory.

typedef struct StatusbarObject_t {
    GWidgetObject w;  // Base Class
 
    uint8_t hours;
    uint8_t minutes;
    uint8_t seconds;
} StatusbarObject;

Note that we store the time in the statusbar object because the statusbar widget is not supposed to query the system time itself. Instead, the application that uses the statusbar will use a GTIMER to periodically update the time fields of the statusbar using the statusbarSetTime() function that we will implement later. The GWidgetObject itself is based on a GWindowObject as explained in the article about widgets. Therefore, the following attributes are already part of our StatusbarObject and don't need to be added manually:

• Position relative to parent (x, y)
• Dimensions (width, height)
• Parent
• Font
• Text
• WidgetStyle
• Widget Tag
• Flags

Flags

The flags need some explanation: The GWindowObject contains a field of the type uint32_t and can therefore represent 32 flags. Some of these flags are used by the GWIN module internally to store certain information like the enable state, the visibility, whether the widget was allocated dynamically and so on. However, the first 8 bits are reserved for widget internal use. For example, the pushbutton widget uses one of these bits to keep record of the pressed/release state. The label widget uses the flags to keep the information whether the a border around the text should be rendered and so on. In our case we will use the flags to keep information about whether the USB and the SD-Card are present. In order to allow the user of the widget to write a custom rendering routine we must declare those flags in the header file, not the source file:

#define STATUSBAR_FLG_USB_PRESENT      0x01
#define STATUSBAR_FLG_SDCARD_PRESENT   0x02

VMT

ToDo

Rendering routine

ToDo