Widgets

Note: Make sure you read the article about windows first!

The widget class is based on the window. In addition to the window functionalities, it implements the following features:

• Widgets can always redraw themselves
• Widgets are able to accept user input such as from a touchscreen/toggle/dial/keyboard
• Widgets can have their drawing routine overwritten to provide fancier versions of the object. For example, their are predefined drawing routines for round buttons, image buttons, arrow buttons etc. along with the normal button drawing routine.
• Widgets support a "style". By changing the style you can affect the colors used to draw the widget similar to the way you can apply color schemes in Windows and Linux.

A list with descriptions of the common container API can be found here.

Initialization

If widgets are used, a default font and a default styling have to be selected:

gwinSetDefaultFont(gdispOpenFont("DejaVu Sans 16"));   // Select your font
gwinSetDefaultStyle(&WhiteWidgetStyle, FALSE);         // Select the widget style

Widget creation

Each widget provides a creation call with is named gwinXxxCreate() where Xxx is the name of the widget. The first parameter is either a pointer to a static widget object or NULL. If NULL, the object will be allocated dynamically from the heap. The second parameter is a pointer to a GWidgetInit struct. This struct contains all the attributes which are needed to create the widget (position, size, font, colors...):

typedef struct GWidgetInit {
    GWindowInit                g;			// The GWIN initializer
    const char*                text;			// The initial text
    CustomWidgetDrawFunction   customDraw;		// A custom draw function - use NULL for the standard
    void*                      customParam;		// A parameter for the custom draw function (default = NULL)
    const GWidgetStyle*        customStyle;		// A custom style to use - use NULL for the default style
} GWidgetInit;

As the widget class is based on the window class, the widget initialization structure contains a window initialization structure. See window creation to learn more about the window initialization structure.
Examples on how to use this struct correctly can be found on each widget documentation page.

gwinDestroy() can be used to destroy a window that is no longer needed.

Widget Style

The GWIN module provides a simple implementation of widget styles. The widget style allows to change the look of a widget. Currently the the widget style is just a struct of different colors. However, for the future it would be possible to add additional parameters to the widget style. The widget style contains the same set of colors multiple times but for different states of the widget.

Note: If you need more control over how a widget is rendering have a look at Custom Rendering Interface.

The widget style struct looks like this (pseudo-code):

WidgetStyle {
	Background color
	Focus highlight border color
 
	// Enabled
	{
		Text Color
		Edge Color
		Fill Color
		Progress Color
	}
 
	// Disabled
	{
		Text Color
		Edge Color
		Fill Color
		Progress Color
	}
 
	// Pressed
	{
		Text Color
		Edge Color
		Fill Color
		Progress Color
	}
}

The real implementation of the widget styles looks like this:

/**
 * @brief	The GColorSet structure
 */
typedef struct GColorSet {
	color_t			text;				/**< The text color */
	color_t			edge;				/**< The edge color */
	color_t			fill;				/**< The fill color */
	color_t			progress;			/**< The color of progress bars */
} GColorSet;
 
/**
 * @brief	The GWidgetStyle structure
 * @details	A GWidgetStyle is a set of colors that together form a "style".
 * 		These colors should not be confused with the GWindow foreground
 * 		and background colors which are used for drawing operations.
 */
typedef struct GWidgetStyle {
	color_t			background;			/**< The window background color */
	color_t			focus;				/**< The color when a widget is focused */
	GColorSet		enabled;			/**< The colors when enabled */
	GColorSet		disabled;			/**< The colors when disabled */
	GColorSet		pressed;			/**< The colors when pressed */
} GWidgetStyle;

Custom render interface

Every widget provides a custom render interface. This simple and easy to use interface allows to overwrite the default rendering of the widget and render each widget as want. This is what you're looking for if you want to improve the look of your GUI. See Creating a custom rendering routine.

API reference

The generic widget API reference can be found here.

Widget implementations

These are the currently implemented widgets:

• Label
• PushButton
• RadioButton
• CheckBox
• Slider
• Progressbar
• ImageBox