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 widgets are currently available:

Name	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.
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
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);

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

API reference: widgets (general)

Since widgets are essentially windows, they are compatible with any of the window manager API routines. 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:

Routine	Explanation
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: routines common to all widgets

The table below lists available widget-related routines in alphabetical order. These functions are common to all widgets, and are listed here in order to avoid repetition. Detailed descriptions of the routines follow. The additional member functions available for each widget may be found in later sections.

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

Configuration options

Type	Macro	Default	Explanation
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 emWin BUTTON-related routines in alphabetical order. Detailed descriptions of the routines follow.

Routine	Explanation
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

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

Configuration options

Type	Macro	Default	Explanation
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 emWin CHECKBOX-related routines in alphabetical order. Detailed descriptions of the routines follow.

Routine	Explanation
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).

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

Configuration options

Type	Macro	Default	Explanation
S	EDIT_ALIGN_DEFAULT	GUI_TA_RIGHT\| GUI_TA_VCENTER	Alignment for edit field text.
N	EDIT_BKCOLOR0_DEFAULT	0xc0c0c0	Background color, disabled state.
N	EDIT_BKCOLOR1_DEFAULT	GUI_WHITE	Background color, enabled state.
N	EDIT_BORDER_DEFAULT	1	Width of border, in pixels.
S	EDIT_FONT_DEFAULT	&GUI_Font13_1	Font used for edit field text.
N	EDIT_TEXTCOLOR0_DEFAULT	GUI_BLACK	Text color, disabled state.
N	EDIT_TEXTCOLOR1_DEFAULT	GUI_BLACK	Text color, enabled state.
N	EDIT_XOFF	2	Distance in X to offset text from left border of edit field.

Available alignment flags are:
GUI_TA_LEFT, GUI_TA_RIGHT, GUI_TA_HCENTER for horizontal alignment.
GUI_TA_TOP, GUI_TA_BOTTOM, GUI_TA_VCENTER for vertical alignment.

EDIT API reference

The table below lists the available emWin EDIT-related routines in alphabetical order. Detailed descriptions of the routines follow.

Routine	Explanation
EDIT_AddKey	Key input routine.
EDIT_Create	Create the edit field.
EDIT_CreateIndirect	Create the edit field from resource table entry.
EDIT_GetDefaultFont	Returns the default font
EDIT_GetText	Get user input.
EDIT_GetValue	Returns the current value
EDIT_SetBinMode	Enables the binary edit mode
EDIT_SetBkColor	Set the background color of the edit field.
EDIT_SetDecMode	Enables the decimal edit mode
EDIT_SetDefaultFont	Sets the default font used for edit fields.
EDIT_SetDefaultTextAlign	Sets the default text alignment for edit fields.
EDIT_SetFont	Select the font for the text.
EDIT_SetHexMode	Enables the hexadecimal edit mode
EDIT_SetMaxLen	Sets the maximum number of characters of the edit field.
EDIT_SetText	Set the text.
EDIT_SetTextAlign	Sets the text alignment for the edit field.
EDIT_SetTextColor	Set the color(s) for the text.
EDIT_SetValue	Sets the current value
GUI_EditBin	Edits a binary value at the current cursor position
GUI_EditDec	Edits a decimal value at the current cursor position
GUI_EditHex	Edits a hexadecimal value at the current cursor position
GUI_EditString	Edits a string at the current cursor position

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.

Configuration options

Type	Macro	Default	Explanation
N	FRAMEWIN_BARCOLOR_ACTIVE_DEFAULT	0xff0000	Title bar color, active state.
N	FRAMEWIN_BARCOLOR_INACTIVE_DEFAULT	0x404040	Title bar color, inactive state.
N	FRAMEWIN_BORDER_DEFAULT	3	Outer border width, in pixels.
N	FRAMEWIN_CLIENTCOLOR_DEFAULT	0xc0c0c0	Color of client window area.
S	FRAMEWIN_DEFAULT_FONT	&GUI_Font8_1	Font used for title bar text.
N	FRAMEWIN_FRAMECOLOR_DEFAULT	0xaaaaaa	Frame color.
N	FRAMEWIN_IBORDER_DEFAULT	1	Inner border width, in pixels.
B	FRAMEWIN_USE_3D	1	Enable support for 3D effects.

FRAMEWIN API reference

The table below lists the available emWin EDIT-related routines in alphabetical order. Detailed descriptions of the routines follow.

Routine	Explanation
FRAMEWIN_Create	Creates the frame window.
FRAMEWIN_CreateAsChild	Create the frame window as a child window.
FRAMEWIN_CreateIndirect	Create the frame window from resource table entry.
FRAMEWIN_GetDefaultBorderSize	Returns the default border size
FRAMEWIN_GetDefaultCaptionSize	Returns the default size of the title bar
FRAMEWIN_GetDefaultFont	Returns the default font used for the title bar
FRAMEWIN_SetActive	Sets the state of the frame window
FRAMEWIN_SetBarColor	Sets the background color of the title bar.
FRAMEWIN_SetClientColor	Sets the background color of the client area
FRAMEWIN_SetDefaultBarColor	Sets the default color of the title bar
FRAMEWIN_SetDefaultBorderSize	Sets the default border size
FRAMEWIN_SetDefaultCaptionSize	Sets the default height of the title bar
FRAMEWIN_SetDefaultFont	FRAMEWIN_SetDefaultFont Sets the default font of the title bar.
FRAMEWIN_SetFont	Selects the font for the title text.
FRAMEWIN_SetText	Sets the title text.
FRAMEWIN_SetTextAlign	Sets the alignment of the title text.
FRAMEWIN_SetTextColor	Sets the color(s) for the title text.
FRAMEWIN_SetTextPos	Sets the position of the title text.

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.

Configuration options

Type	Macro	Default	Explanation
N	LISTBOX_BKCOLOR0_DEFAULT	GUI_WHITE	Background color, unselected state.
N	LISTBOX_BKCOLOR1_DEFAULT	GUI_GRAY	Background color, selected state without focus.
N	LISTBOX_BKCOLOR2_DEFAULT	GUI_WHITE	Background color, selected state with focus.
S	LISTBOX_FONT_DEFAULT	&GUI_Font13_1	Font used.
N	LISTBOX_TEXTCOLOR0_DEFAULT	GUI_BLACK	Text color, unselected state.
N	LISTBOX_TEXTCOLOR1_DEFAULT	GUI_BLACK	Text color, selected state without focus.
N	LISTBOX_TEXTCOLOR2_DEFAULT	GUI_BLACK	Text color, selected state with focus.
B	LISTBOX_USE_3D	1	Enable 3D support.

LISTBOX API reference

The table below lists the available emWin LISTBOX-related routines in alphabetical order. Detailed descriptions of the routines follow.

Routine	Explanation
LISTBOX_Create	Create the list box.
LISTBOX_CreateAsChild	Create the list box as a child window.
LISTBOX_CreateIndirect	Create the list box from resource table entry.
LISTBOX_DecSel	Decrement selection.
LISTBOX_GetDefaultFont	Return the default font for LISTBOX widgets.
LISTBOX_GetSel	Return the number of the selected row.
LISTBOX_IncSel	Increment selection.
LISTBOX_SetBackColor	Set the background color.
LISTBOX_SetDefaultFont	Change the default font for LISTBOX widgets.
LISTBOX_SetFont	Select the font.
LISTBOX_SetSel	Set the selected row.
LISTBOX_SetTextColor	Set the foreground color.

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.

Configuration options

Type	Macro	Default	Explanation
S	PROGBAR_DEFAULT_FONT	GUI_DEFAULT_FONT	Font used.
N	PROGBAR_DEFAULT_BARCOLOR0	0x555555 (dark gray)	Left bar color.
N	PROGBAR_DEFAULT_BARCOLOR1	0xAAAAAA (light gray)	Right bar color.
N	PROGBAR_DEFAULT_TEXTCOLOR0	0xFFFFFF	Text color, left bar.
N	PROGBAR_DEFAULT_TEXTCOLOR1	0x000000	Text color, right bar.

PROGBAR API reference

The table below lists the available emWin PROGBAR-related routines in alphabetical order.

Routine	Explanation
PROGBAR_Create	Create the progress bar.
PROGBAR_CreateIndirect	Create the progress bar from resource table entry.
PROGBAR_SetBarColor	Sets the color(s) for the bar.
PROGBAR_SetFont	Select the font for the text.
PROGBAR_SetMinMax	Set the minimum and maximum values used for the bar.
PROGBAR_SetText	Set the (optional) text for the paragraph.
PROGBAR_SetTextAlign	Set text alignment (default is centered).
PROGBAR_SetTextColor	Set the color(s) for the text.
PROGBAR_SetTextPos	Set the text position (default 0,0).
PROGBAR_SetValue	Set the value for the bar graph (and percentage if no text has been assigned).

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.

Configuration options

Type	Macro	Default	Explanation
	RADIO_BKCOLOR0_DEFAULT	0xc0c0c0	Background color of button, inactive state.
	RADIO_BKCOLOR1_DEFAULT	GUI_WHITE	Background color of button, active state.

RADIO API reference

The table below lists the available emWin RADIO-related routines in alphabetical order.

Routine	Explanation
RADIO_Create	Create a group of radio buttons.
RADIO_CreateIndirect	Create a group of radio buttons from resource table entry.
RADIO_Dec	Decrement the button selection by a value of 1.
RADIO_GetValue	Return the current button selection.
RADIO_Inc	Increment the button selection by a value of 1.
RADIO_SetValue	Set the button selection.

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, SCROLL-BAR. h. All identifiers are prefixed SCROLLBAR.

Configuration options

Type	Macro	Default	Explanation
N	SCROLLBAR_BKCOLOR0_DEFAULT	0x808080	Background (thumb area) color.
N	SCROLLBAR_BKCOLOR1_DEFAULT	GUI_BLACK	Scroll bar (thumb) color.
N	SCROLLBAR_COLOR0_DEFAULT	0xc0c0c0	Arrow button colors.
B	SCROLLBAR_USE_3D	1	Enable 3D support.

SCROLLBAR API reference

The table below lists the available emWin SCROLLBAR-related routines in alphabetical order.

Routine	Explanation
SCROLLBAR_AddValue	Increment or decrement the value of the scroll bar by a specified value.
SCROLLBAR_Create	Create the scroll bar.
SCROLLBAR_CreateAttached	Create a scroll bar attached to a window.
SCROLLBAR_CreateIndirect	Create the scroll bar from resource table entry.
SCROLLBAR_Dec	Decrement the value of the scroll bar by a value of 1.
SCROLLBAR_GetValue	Return the current item value.
SCROLLBAR_Inc	Increment the value of the scroll bar by a value of 1.
SCROLLBAR_SetNumItems	Set the number of items for scrolling.
SCROLLBAR_SetPageSize	Set the page size (in number of items).
SCROLLBAR_SetValue	Set the current value of the scroll bar.
SCROLLBAR_SetWidth	Set the width of the scroll bar.

SLIDER: Slider widget

Slider widgets are commonly used for modifying values through the use of a slider bar.

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

Configuration options

Type	Macro	Default	Explanation
N	SLIDER_BKCOLOR0_DEFAULT	0xc0c0c0	Background color.
N	SLIDER_COLOR0_DEFAULT	0xc0c0c0	Slider (thumb) color.
B	SLIDER_USE_3D	1	Enable 3D support.

SLIDER API reference

The table below lists the available emWin SLIDER-related routines in alphabetical order.

Routine	Explanation
SLIDER_Create	Create the slider.
SLIDER_CreateIndirect	Create the slider from resource table entry.
SLIDER_Dec	Decrement the value of the slider bar.
SLIDER_GetValue	Return the current value of the slider bar.
SLIDER_Inc	Increment the value of the slider bar.
SLIDER_SetRange	Set the range of the slider value.
SLIDER_SetValue	Set the current value of the slider bar.
SLIDER_SetWidth	Set the width of the slider bar.

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.

Configuration options

Type	Macro	Default	Explanation
S	TEXT_FONT_DEFAULT	&GUI_Font13_1	Font used.

TEXT API reference

The table below lists the available emWin TEXT-related routines in alphabetical order.

Routine	Explanation
TEXT_Create	Create the text.
TEXT_CreateIndirect	Create the text from resource table entry.
TEXT_GetDefaultFont	Return the default font used for text.
TEXT_SetDefaultFont	Set the default font used for text.
TEXT_SetFont	Set the font used for a specified text widget.
TEXT_SetText	Set the text for a specified text widget.
TEXT_SetTextAlign	Set the text alignment of a specified text widget.
TEXT_SetTextPos	Set the position of the text in a specified text widget.

Return to main emWin page...
You can download an evaluation version of emWin from our Literature/Download section....

Segger News

Tiny RTOS supports STR7 more...

Other News

NEWS: Tools

NEW RTX2011 Real-Time Extension for Windows Updated. more...
New 8-Core processor AMC board reduces system cost and power consumption . more...
Direct Insight Launches Technology Blog. more...
IntervalZero RTX 2009 adds SMP support
TimingDesigner 9.1 adds SDC and Integration with Altera Quartus II
Embedded Linux and FPGAs Accelerate Embedded Software Development more...

30-day free evaluation

Request the Segger 30-day free evaluation kit.

Literature Centre

See our Literature Centre for documents and other associated files for this product group.

<< Backward | Forward >> | Top of Page

Copyright © 2001 - Direct Insight Ltd
All trademarks on www.directinsight.co.uk are recognised and are the property of their respective owners.
For enquiries or problems encountered on the website, please contact webmaster@directinsight.co.uk