Difference between revisions of "Widgets"

Revision as of 09:02, 8 August 2014

Note: Make sure you read the window article 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.

Custom render interface

Every widget comes with a custom render interface. The default style in which a widget is drawn is very basic and minimalistic in order to make it run on the even lowest performance systems smoothly. However, the custom render interface allows you to submit your own rendering routines. This does not only provide a very flexible way to render a widget matching to your systems performance, but it gives you also the possibility to render a widget matching your applications style.

Every widget provides an API call like the the following:

void gwinSetCustomDraw(GHandle gh, CustomWidgetDrawFunction fn, void *param);

The CustomWidgetDrawFunction is a typedef'ed function pointer:

typedef void (*CustomWidgetDrawFunction)(struct GWidgetObject *gw, void *param);

The param parameter can be used to pass a custom parameter such as a file pointer. However, in most of the cases, this parameter will be NULL.

All the information required to write a custom render function for a widget, such as the position, size, state, text, fonts etc. can be obtained from the GHandle.

Note: The pointer to the custom rendering routine can also be passed through the initialization struct. See above. Note: Do never use the gwinDrawXxx() calls inside a rendering routine as this would lock the widget again. Use gdispDrawXxx() instead

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
• Tabs
• ImageBox