Widgets

windows with object type properties; they are called controls in the windows world and make up the elements of the user interface. They can react automatically to certain events; for example, a button can appear in a different state if it is pressed. Widgets need to be created, have properties which may be changed at any time during their existence and are then typically deleted when they are no longer needed. Just like a window, a widget is referenced by a handle which is returned by its create function. Widgets require the window manager. Once a widget is created, it is treated just like any other window; the WM ensures that it is properly displayed (and redrawn) when ever necessary. Widgets are not required when writing an application or a user interface, but they can make programming much easier

Some basics

Available widgets The following widgets are currently available: Name Description
BUTTON Button which can be pressed. Text or bitmaps may be displayed on a button.
CHECKBOX Check box which may be checked or unchecked.
DROPDOWN Dropdown listbox, opens a listbox when pressed
EDIT Single-line edit field which prompts the user to type a number or text.
FRAMEWIN Frame window. Creates the typical GUI look.
GRAPH Graph widgets can be used to visualize data.
HEADER Header control, used to manage columns
LISTBOX Listbox which highlights items as they are selected by the user.
LISTVIEW Listview widgets are used to creates tables.
MENU Menu widget can be used to create several kinds of menus.
MESSAGEBOX A MESSAGEBOX widget is used to show a message in a frame window with a title ba and an "OK" button.
MULTIEDIT MULTIEDIT widget enables you to edit text with multiple lines.
MULTIPAGE By using a MULTIPAGE widget, an application can define multiple pages for the same area of a window or dialog box.
PROGBAR Progress bar used for visualization.
RADIOBUTTON Radio button which may be selected. Only one button may be selected at a time.
SCROLLBAR Scrollbar which may be horizontal or vertical.
SLIDER Slider bar used for changing values.
TEXT Static text controls typically used in dialogs.

Understanding the redrawing mechanism


A widget draws itself according to its properties. This is done when WM_ExecIdle() is called. If you do not call WM_ExecIdle() from within your program, WM_Paint() must be called for the widget. In a multitasking environment, a background task is normally used to call WM_ExecIdle() and update the widgets (and all other windows with callback functions). It is then not necessary to manually call WM_Paint(); however, it is still legal to do so and may also make sense if you want to ensure that the widget is redrawn immediately. When a property of a widget is changed, the window of the widget (or part of it) is marked as invalid, but it is not immediately redrawn. Therefore, the section of code executes very fast. The redrawal is done by the WM at a later time or it can be forced by calling WM_Paint() for the widget (or WM_ExecIdle() until all windows are redrawn).

How to use widgets

Suppose we would like to display a progress bar. All that is needed is the following code:
PROGBAR_Handle hProgBar;
GUI_DispStringAt("Progress bar", 100, 20);
hProgBar = PROGBAR_Create(100, 40, 100, 20, WM_CF_SHOW);

The first line reserves memory for the handle of the widget. The last line actually creates the widget. The widget will then automatically be drawn by the window manager if WM_ExecIdle() is called at a later point or in a separate task. Member functions are available for each type of widget which allow modifications to their appearance. Once the widget has been created, its properties can be changed by calling one of its member functions. These functions take the handle of the widget as their first argument.In order to make the progress bar show 45% and to change the colors from their defaults to green/red for the bar, the following code section may be used:
PROGBAR_SetBarColor(hProgBar, 0, GUI_GREEN);
PROGBAR_SetBarColor(hProgBar, 1, GUI_RED);
PROGBAR_SetValue(hProgBar, 45);

Dynamic memory usage for widgets

In embedded applications it is usually not very desirable to use dynamic memory at all because of fragmentation effects. There are a number of different strategies that can be used to avoid this, but they all work in a limited way whenever memory areas are referenced by a pointer in the application program. For this reason, µC/GUI uses a different approach: all objects (and all data stored at runtime) are stored in memory areas referenced by a handle. This makes it possible to relocate the allocated memory areas at runtime, thus avoiding the long term allocation problems which occur when using pointers. All widgets are thus referenced by handles.

3D support

Many widgets may be displayed with or without 3D effects. 3D support is enabled by default, but may be disabled by setting the configuration macro (WIDGET)_USE_3D to 0. A widget will function exactly the same way whether it uses three dimensional effects or not; the only difference will be in its appearance. This is demonstrated below with a slider widget:
3D effects enabled (default) 3D effects disabled

API reference: widgets (general)

Since widgets are essentially windows, they are compatible with any of the window manager API functions. The handle of the widget is used as the hWin parameter and the widget is treated like any other window. The WM functions most commonly used with widgets are listed as follows:
Function Description
WM_DeleteWindow Delete a window.
WM_DisableMemdev Disable usage of memory devices for redrawing. WM_EnableMemdev Enable usage of memory devices for redrawing.
WM_InvalidateWindow Invalidate a window.
WM_Paint Draw or redraw a window immediately.

API reference: functions common to all widgets

The table below lists available widget-related functions in alphabetical order. These functions are common to all widgets, and are listed here in order to avoid repetition. Descriptions of the functions follow. The additional member functions available for each widget may be found in later sections.
Function Description
_CreateIndirect Used for automatic creation in dialog boxes.
WM_EnableWindow Set the widget state to enabled (default).
WM_DisableWindow Set the widget state to disabled.


BUTTON: Button widget

Button widgets are commonly used as the primary user interface element for touch- screens. Buttons may be displayed with text, as shown below, or with a bitmap.

All BUTTON-related functions are located in the file(s) BUTTON*.c, BUTTON.h. All identifiers are prefixed BUTTON.

Configuration options
Type Macro Default Description
N BUTTON_3D_MOVE_X 1
Number of pixels that text/bitmap moves in horizontal direction in pressed state.
N BUTTON_3D_MOVE_Y 1
Number of pixels that text/bitmap moves in vertical direction in pressed state.
N BUTTON_BKCOLOR0_DEFAULT 0xAAAAAA
Background color, unpressed state.
N BUTTON_BKCOLOR1_DEFAULT
GUI_WHITE
Background color, pressed state.
S BUTTON_FONT_DEFAULT
&GUI_Font13_1
Font used for button text.
N BUTTON_TEXTCOLOR0_DEFAULT
GUI_BLACK
Text color, unpressed state.
N BUTTON_TEXTCOLOR1_DEFAULT
GUI_BLACK
Text color, pressed state.
B BUTTON_USE_3D 1
Enable support for 3D effects.

The default for the button is to use a white background in pressed state. This has been done purposely because it makes it very obvious that the button is pressed, on any kind of display. If you want the background color of the button to be the same in both its pressed and unpressed states, change BUTTON_BKCOLOR1_DEFAULT to BUTTON_BKCOLOR0_DEFAULT.

API reference

The table below lists the available µC/GUI BUTTON-related functions in alphabetical order. Descriptions of the functions follow.
Function Description

BUTTON_Create Create the button.
BUTTON_CreateAsChild Create the button as a child window.
BUTTON_CreateIndirect Create the button from resource table entry.
BUTTON_SetBitmap Set the bitmap used when displaying the button.
BUTTON_SetBitmapEx Set the bitmap used when displaying the button.
BUTTON_SetBkColor Set the background color of the button.
BUTTON_SetFont Select the font for the text.
BUTTON_SetState Set the button state (handled automatically by touch module).
BUTTON_SetStreamedBitmap Set the bitmap used when displaying the button.
BUTTON_SetText Set the text.
BUTTON_SetTextColor Set the color(s) for the text.

CHECKBOX: Check box widget

One of the most familiar widgets for selecting various choices is the check box. A check box may be checked or unchecked by the user, and any number of boxes may be checked at one time. A box will appear gray if it is disabled, as seen in the table below where each of the four possible check box appearances are illustrated:
Checked Unchecked
Enabled
Disabled

All CHECKBOX-related functions are located in the file(s) CHECKBOX*.c, CHECKBOX.h. All identifiers are prefixed CHECKBOX.

Configuration options
Type Macro Default Description
N CHECKBOX_BKCOLOR0_DEFAULT
0x808080
Background color, disabled state.
N CHECKBOX_BKCOLOR1_DEFAULT
GUI_WHITE
Background color, enabled state.
N CHECKBOX_FGCOLOR0_DEFAULT
0x101010
Foreground color, disabled state.
N CHECKBOX_FGCOLOR1_DEFAULT
GUI_BLACK
Foreground color, enabled state.
S CHECKBOX_FONT_DEFAULT
&GUI_Font13_1
Font used for check mark.
B CHECKBOX_USE_3D
1
Enable support for 3D effects.

CHECKBOX API reference

The table below lists the available µC/GUI CHECKBOX-related functions in alphabetical order. Descriptions of the functions follow.
Function Description
CHECKBOX_Check Set the check box state to checked.
CHECKBOX_Create Create the check box.
CHECKBOX_CreateIndirect Create the check box from resource table entry.
CHECKBOX_IsChecked Return the current state (checked or not checked) of the check box.
CHECKBOX_Uncheck Set the check box state to unchecked (default).

DROPDOWN: Dropdown widget

DROPDOWN widgets are used to select one element of a list with several columns. It shows the currently selected item in non open state. If the user opens a DROPDOWN widget a LISTBOX appears to select a new item.
Dropdown closed Dropdown opened
Configuration options
Type Macro Default Description
N DROPDOWN_ALIGN_DEFAULT GUI_TA_LEFT Text alignment used to display dropdown text in closed state.
S DROPDOWN_FONT_DEFAULT &GUI_Font13_1 Default font
N DROPDOWN_BKCOLOR0_DEFAULT GUI_WHITE Background color, unselected state.
N DROPDOWN_BKCOLOR1_DEFAULT GUI_GRAY Background color, selected state without focus.
N DROPDOWN_BKCOLOR2_DEFAULT GUI_BLUE Background color, selected state with focus.
N DROPDOWN_KEY_EXPAND GUI_KEY_SPACE Key which can be used to expand the dropdown list.
N DROPDOWN_KEY_SELECT GUI_KEY_ENTER Key which can be used to select an item from the open dropdown list.
N DROPDOWN_TEXTCOLOR0_DEFAULT GUI_BLACK Text color, unselected state.
N DROPDOWN_TEXTCOLOR1_DEFAULT GUI_BLACK Text color, selected state without focus.
N DROPDOWN_TEXTCOLOR2_DEFAULT GUI_WHITE Enable 3D support.

More informations:

» further information on german

Members Login
username
password
New MemberRegister Here
Newsletter Signup