Direct Insight Ltd embedded platform solutions
  Latest News :  Date:  | Bookmark  
         
 
 
# Menu Links more

get in touch by phone or email email the team

windows embedded CE partner

 

Segger logoSegger - emWin - Widgets


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....

 


buy online
ask a technical question
PDF datasheet
Trial Software

 


Abatron | EMA TimingDesigner | Embedded Planet | Entrek | EnSilica | FlatOak | IntervalZero
Microcross | Microsoft Embedded | Segger | Sophia | SwiftModule | Tasking | TRITON Modules
Products by Processor | Products by Supplier | Boards & Modules

 

# 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 #
#

FREE evaluation kitbulletRequest the Segger 30-day free evaluation kit.

#

# Literature Centre #
#

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

#

more
         
 
<< 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