Widgets are 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 table shows the appearance of the currently available widgets. Some of the widgets support skinning. This method of changing the appearance is explained in detail in chapter ’Skinning’. The second screenshot shows the appearance when skinning is enabled for the widget:

Name	Screenshot (classic)	Screenshot (skinned)	Explanation
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 widget, used to show curves or measured values.
HEADER			Header control, used to manage columns.
ICONVIEW			Icon view widget. Useful for icon based platforms as found in common hand held devices.
LISTBOX			Listbox which highlights items as they are selected by the user.
LISTVIEW			Listview widgets are used to creates tables or calculation sheets.
LISTWHEEL			Listwheel widget. The data can be moved and accelerated via pointer input device.
MENU			Menu widgets are used to create horizontal and vertical menus.
MESSAGEBOX			A message box widget is actually a "ready-to-use" combination of a simple frame window with a title bar and an "OK" button which must be pressed in order to close the window.
MULTIEDIT			Multiedit widgets are used to edit multiple lines of text.
MULTIPAGE			Multipage widgets are used to create dialogs with multiple pages.
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.
TREEVIEW			Static text controls typically used in dialogs.
WINDOW			The WINDOW widget is used to create a dialog window from a resource table.

Understanding the redrawing mechanism

A widget draws itself according to its properties. This is done when WM_Exec(), GUI_Exec() or GUI_Delay() is called. In a multitasking environment, a background task is normally used to call WM_Exec() and update the widgets (and all other windows with callback functions).

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 redrawing is done by the WM at a later time or it can be forced by calling WM_Paint() for the widget (or WM_Exec() 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);

All widgets also have one or more configuration macros which define various default settings such as fonts and colors used.

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, emWin 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

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 routines are located in the file(s) BUTTON*.c, BUTTON.h. All identifiers are prefixed BUTTON.

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

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

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

If mouse support is enabled, the open list reacts on moving the mouse over it.

EDIT: Edit widget

Edit fields are commonly used as the primary user interface for text input:

Blank edit field	Edit field with user input

You can also use edit fields for entering values in binary, decimal, or hexadecimal modes. A decimal-mode edit field might appear similar to those in the following table. Like a check box, an edit field will appear gray if disabled:

Edit field with user input (decimal)	Disabled edit field

FRAMEWIN: Frame window widget

Frame windows give your application a PC application-window appearance. They consist of a surrounding frame, a title bar and a user area. The color of the title bar changes to show whether the window is active or inactive, as seen below:

Active frame window	Inactive frame window

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

GRAPH: Graph widget

Graph widgets can be used to visualize data. Typical applications for graph widgets are showing measurement values or the curve of a function graph. Multiple curves can be shown simultaneously. Horizontal and vertical scales can be used to label the curves. A grid with different horizontal and vertical spacing can be shown on the background. If the data array does not fit into the visible area of the graph, the widget can automatically show scrollbars which allow scrolling through large data arrays.

GRAPH_DATA_XY	GRAPH_DATA_YT

HEADER: Header widget

HEADER widgets are used to label columns of a table:

If a pointer input device (PID) is used, the width of the header items can be managed by dragging the dividers by the PID.

Behavior with mouse

If mouse support is enabled, the cursor is on and the PID is moved nearby a divider the cursor will change to signal, that the divider can be dragged at the current position.

Behavior with touch screen

If the widget is pressed nearby a divider and the cursor is on the cursor will change to signal, that the divider can now be dragged.

Predefined cursors

There are 2 predefined cursors as shown below:

GUI_CursorHeaderM (default)	GUI_CursorHeaderMI

LISTBOX: List box widget

List boxes are used to select one element of a list. A list box can be created without a surrounding frame window, as shown below, or as a child window of a FRAMEWIN widget (see the additional screen shots at the end of the section). As items in a list box are selected, they appear highlighted. Note that the background color of a selected item depends on whether the list box window has input focus.

List box with focus	List box without focus

 

All LISTBOX-related routines are in the file(s) LISTBOX*.c, LISTBOX.h. All identifiers are prefixed LISTBOX.

LISTVIEW: Listview widget

LISTVIEW widgets are used to select one element of a list with several columns. To manage the columns a LISTWIEW widget contains a HEADER widget. A LISTVIEW can be created without a surrounding frame window or as a child window of a FRAMEWIN widget. As items in a listview are selected, they appear highlighted. Note that the background color of a selected item depends on whether the LISTVIEW window has input focus. The table below shows the appearance of the LISTVIEW widget:

Explanation	LISTVIEW widget
No focus No surrounding FRAMEWIN No SCROLLBAR attached Grid lines not visible
Has input focus No surrounding FRAMEWIN No SCROLLBAR attached Grid lines not visible
Has input focus With surrounding FRAMEWIN No SCROLLBAR attached Grid lines not visible
Has input focus With surrounding FRAMEWIN SCROLLBAR attached Grid lines not visible
Has input focus With surrounding FRAMEWIN SCROLLBAR attached Grid lines visible

MENU: Menu widget

The MENU widget can be used to create several kinds of menus. Each menu item represents an application command or a submenu. MENUs can be shown horizontally and/or vertically. Menu items can be grouped using separators. Separators are supported for horizontal and vertical menus. Selecting a menu item sends a WM_MENU message to the owner of the menu or opens a submenu. If mouse support is enabled the MENU widget reacts on moving the mouse over the items of a menu. The shipment of emWin contains a application sample which shows how to use the MENU widget. It can be found under SampleApplicationReversi.c. The table below shows the appearance of a horizontal MENU widget with a vertical submenu:

Explanation	Menu using WIDGET_Effect_3D1L	Menu using WIDGET_Effect_Simple
Color display (8666 mode)
Monochrome display (16 gray scales)
Black/white display

The table above shows the appearance of the menu widget using its default effect WIDGET_Effect_3D1L and using WIDGET_Effect_Simple. It also works with all other effects.

MESSAGEBOX: Message Box widget

A MESSAGEBOX widget is used to show a message in a frame window with a title bar, as well as an "OK" button which must be pressed in order to close the window. It requires only one line of code to create or to create and execute a message box. All MESSAGEBOX-related routines are in the file(s) MESSAGEBOX*.c, MESSAGEBOX.h and GUI.h.

MULTIEDIT: Multi line text widget

The MULTIEDIT widget enables you to edit text with multiple lines. You can use it as a simple text editor or to display static text. The widget supports scrolling with and without scrollbars. All MULTIEDIT-related routines are in the file(s) MULTIEDIT*.c, MULTIEDIT.h. All identifiers are prefixed MULTIEDIT. The table below shows the appearance of the MULTIEDIT widget:

Explanation	Frame window
edit mode, automatic horizontal scrollbar, non wrapping mode, insert mode,
edit mode, automatic vertical scrollbar, word wrapping mode, overwrite mode,
read only mode, word wrapping mode

MULTIPAGE: Multiple page widget

A MULTIPAGE widget is analogous to the dividers in a notebook or the labels in a file cabinet. By using a MULTIPAGE widget, an application can define multiple pages for the same area of a window or dialog box. Each page consists of a certain type of information or a group of widgets that the application displays when the user selects the corresponding page. To select a page the tab of the page has to be clicked. If not all tabs can be displayed, the MULTIPAGE widget automatically shows a small scrollbar at the edge to scroll the pages. The sample folder contains the file WIDGET_Multipage.c which shows how to create and use the MULTIPAGE widget. The table below shows the appearance of the MULTIPAGE widget:

Explanation	MULTIPAGE widget
MULTIPAGE widget with 3 pages, alignment top/left.
MULTIPAGE widget with 6 pages, alignment bottom/right.

PROGBAR: Progress bar widget

Progress bars are commonly used in applications for visualization; for example, a tank fill-level indicator or an oil-pressure indicator. Sample screenshots can be found at the beginning of the chapter and at end of this section. All PROGBAR-related routines are in the file(s) PROGBAR*.c, PROGBAR.h. All identifiers are prefixed PROGBAR.

RADIO: Radio button widget

Radio buttons, like check boxes, are used for selecting choices. A dot appears when a radio button is turned on or selected. The difference from check boxes is that the user can only select one radio button at a time. When a button is selected, the other buttons in the widget are turned off, as shown to the right. One radio button widget may contain any number of buttons, which are always arranged vertically.

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

SCROLLBAR: Scroll bar widget

Scroll bars are used for scrolling through list boxes or any windows which do not fit entirely into their frames. They may be created horizontally, as shown below, or vertically.

A scroll bar is typically used with an existing window, for example the list box shown below:

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

SLIDER: Slider widget

Slider widgets are commonly used for modifying values through the use of a sliderbar. The widget consists of a slider bar and tick marks beside the bar. These tick marks can be used to snap the slider bar while dragging it.

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

TEXT: Text widget

Text widgets are typically used in order to display fields of text in dialog boxes, as shown in the message box below:

Of course, text fields may also be used for labeling other widgets, as follows:

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

WINDOW: Window widget

The WINDOW widget is used to create a dialog window from a resource table. It should be used if the dialog should not look like a frame window. The window widget acts as background and as a container for child windows: It can contain child windows and fills the background, typically with gray. It behaves much like a frame-window without frame and title bar and is used for dialogs.