Head office Germany
US office
                   


Embedded Software
emWin
Window Objects (Widgets)

Window Objects (Widgets)

Widgets are windows with object-type properties. They are called controls in the Windows environments 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 have properties which may be changed at any time during their existence. They are typically deleted as soon as they are not used any longer. Similar to windows, widgets are referenced by handles which are returned by the respective 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) whenever necessary. The use of widgets is not mandatory for applications or user interfaces, but they decrease development time.

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.
IMAGE     Image widget. Displays several image formats automatically.
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.
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.
RADIO 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.
SPINBOX     Spinning box to display and adjust a specific value
TEXT   Static text controls typically used in dialogs.
TREEVIEW   Static text controls typically used in dialogs.

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 once WM_Exec() is called the next time, what may happen 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 its member functions. These functions take the handle of the widget as their first argument. In order to make the progress bar created above show 45% and to change the bar colors from their defaults (dark gray/light gray) to green/red, the following section of code may be used:

PROGBAR_SetBarColor(hProgBar, 0,   GUI_GREEN);
PROGBAR_SetBarColor(hProgBar, 1,   GUI_RED);
PROGBAR_SetValue   (hProgBar, 45);

Default configuration

All widgets also have one or more configuration macros which define various default settings such as fonts and colors used. The available configuration options are listed for each widget in their respective sections below.

How widgets communicate

Widgets are often created as child windows. The parent window may be any type of window, even another widget. A parent window usually needs to be informed whenever something occurs with one of its children in order to ensure synchronization. Child window widgets communicate with their parent window by sending a WM_NOTIFY_PARENT message whenever an event occurs. The notification code sent as part of the message depends on the event.

Most widgets have one or more notification codes defining different types of events. The available notification codes for each widget (if any) are listed under their respective sections.

Skinning

The appearance of a widget can be modified by using the member functions of the respective widget. Some of the widgets support skinning. If skinning is used for a widget the ’skin’ determines the appearance of the widget and some of the member functions have no effect. For details please refer to the emWin documentation.

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 run-time) are stored in memory areas referenced by a handle. This makes it possible to relocate the allocated memory areas at run-time, thus avoiding the long-term allocation problems which occur when using pointers. All widgets are thus referenced by handles.

Determine the type of a widget

The type of a widget can be determined by comparing the callback function of a specific widget with the public callback functions of the widget API. The following shows a short example how to determine the type of a widget. In case of overwritten callback functions the method should be adapted:

WM_CALLBACK * pCb;

pCb = WM_GetCallback(hWidget);
if        (pCb == BUTTON_Callback) {
  // Widget is a button
} else if (pCb == DROPDOWN_Callback) {
  // Widget is a dropdown
} else if (pCb == LISTBOX_Callback) {
  // Widget is a listbox
} else if (...) {
  ...
}

Please note that this code needs to be adapted, if callback functions have been overwritten.

Configuration options

Type Macro Default Description
B WIDGET_USE_PARENT_EFFECT 0 If set to 1, each ’child widget’ of a widget, has the same effect as the parent widget. If for example a listbox needs to create a scrollbar, the new scrollbar has the same effect as the listbox.
B WIDGET_USE_SCHEME_LARGE 0 If set to 1, the default appearance of the widgets is large sized. That means that all widgets which show text are configured to use large sized default fonts.
B WIDGET_USE_SCHEME_MEDIUM 0 If set to 1, the default appearance of the widgets is medium sized. That means that all widgets which show text are configured to use medium sized default fonts.
B WIDGET_USE_SCHEME_SMALL 1 If set to 1, the default appearance of the widgets is small sized. That means that all widgets which show text are configured to use small sized default fonts.
B WIDGET_USE_FLEX_SKIN 0 If set to 1, widgets are drawn using the Flex Skin by default. For more information about Skinning, please refer to the chapter ’Skinning’.

WIDGET_USE_SCHEME...

The table below shows the default appearance of the widget schemes:

WIDGET_USE_SCHEME_LARGE
WIDGET_USE_SCHEME_MEDIUM
WIDGET_USE_SCHEME_SMALL

General widget API

WM routines used for widgets

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 Description
WM_DeleteWindow() Deletes a window.
WM_DisableMemdev() Disables usage of memory devices for redrawing.
WM_EnableMemdev() Enables usage of memory devices for redrawing.
WM_InvalidateWindow() Invalidates a window.
WM_Paint() Draws or redraws a window immediately.

A complete list of WM-related functions, can be found in the emWin documentation

Common routines

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 Description
<WIDGET>_Callback() Default callback function.
<WIDGET>_CreateIndirect() Used for automatic creation in dialog boxes.
<WIDGET>_CreateUser() Creates a widget using extra bytes as user data.
<WIDGET>_GetUserData() Retrieves the data set with <WIDGET>_SetUserData.
<WIDGET>_SetUserData() Sets the extra data of a widget.
WIDGET_GetDefaultEffect() Returns the default effect used for widgets.
WIDGET_SetDefaultEffect() Sets the default effect used for widgets.
WIDGET_SetEffect() Sets the effect used for a given widget.

User drawn widgets

Some widgets supports owner drawing, for example the LISTBOX widget. If the user draw mode of a widget has been activated a application-defined function of type WIDGET_DRAW_ITEM_FUNC will be called to draw the widget (item).

Reaction to commands

The function has to react to the command given in the WIDGET_ITEM_DRAW_INFO structure. This can be done in one of 2 ways:

  • By calling the appropriate default function supplied by the particular widget (for example, LISTBOX_OwnerDraw())
  • By supplying code that reacts accordingly.

Commands

The commands listed below are supported and should be reacted to by the function. As explained above, the default owner draw function should be called for all not handled functions. This can save code size (for example if the height is the same as the default height) and makes sure that your code stays compatible if additional commands are introduced in future versions of the software.

WIDGET_ITEM_GET_XSIZE

The X-size in pixels of the given item has to be returned.

WIDGET_ITEM_GET_YSIZE

The Y-size (height) in pixels of the given item has to be returned.

WIDGET_ITEM_DRAW

The given item has to be drawn. x0 and y0 of the WIDGET_ITEM_DRAW_INFO structure specify the position of the item in window coordinates. The item has to fill its entire rectangle; the rectangle is defined by the starting position x0, y0 supplied to the function and the sizes returned by the function as reaction to the commands WIDGET_ITEM_GET_YSIZE, WIDGET_ITEM_GET_XSIZE. It may NOT leave a part of this rectangular area unpainted. It can not paint outside of this rectangular area because the clip rectangle has been set before the function call.

 

BUTTON: Button widget

Button widgets are commonly used as the primary user interface element for touch-screens. If the button has the input focus, it also reacts on the keys GUI_KEY_SPACE and GUI_KEY_ENTER. 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.

Skinning...

...is available for this widget. The screenshot above shows the widget using the default skin. For details please refer to the chapter ’Skinning’.

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_ALIGN_DEFAULT GUI_TA_HCENTER | GUI_TA_VCENTER Alignment used to display the button text.
N BUTTON_BKCOLOR0_DEFAULT 0xAAAAAA Background color, unpressed state.
N BUTTON_BKCOLOR1_DEFAULT GUI_WHITE Background color, pressed state.
N BUTTON_FOCUSCOLOR_DEFAULT GUI_BLACK Default color for rendering the focus rectangle.
S BUTTON_FONT_DEFAULT &GUI_Font13_1 Font used for button text.
B BUTTON_REACT_ON_LEVEL 0 See description below.
N BUTTON_TEXTCOLOR0_DEFAULT GUI_BLACK Text color, unpressed state.
N BUTTON_TEXTCOLOR1_DEFAULT GUI_BLACK Text color, pressed state.

BUTTON_REACT_ON_LEVEL

A button per default reacts on each touch message. For example if touching a dialog with a pointer input device (PID) not exactly on the button and then move the PID in pressed state over the button, the button changes from unpressed to pressed state. This behavior can be useful if using a touch panel.

If a button should only react on level changes, BUTTON_REACT_ON_LEVEL should be set to 1. Then a button changes the state only if the PID is pressed and released on the button. If then moving a PID in pressed state over the button it does not react. This behavior can be useful if dialogs should react on WM_NOTIFICATION_CLICKED.

Example (BUTTON_REACT_ON_LEVEL = 0): One dialog (dialog 2) is shown over an other dialog (dialog 1). The close button of dialog 2 is on the same position as a button of dialog 1. Now the close button of dialog 2 is pressed, which removes dialog 2. The PID now is in pressed state. If now moving the button before releasing it the button of dialog 1 would change from unpressed to pressed state.

This unwanted behavior can be avoided by setting BUTTON_REACT_ON_LEVEL to 1.

Alternatively to this configuration option the function BUTTON_SetReactOnLevel() can be used.

BUTTON_BKCOLOR0_DEFAULT, BUTTON_BKCOLOR1_DEFAULT

The default for the button is to use a white background in the 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.

Notification codes

The following events are sent from a button widget to its parent window as part of a WM_NOTIFY_PARENT message:

Message Description
WM_NOTIFICATION_CLICKED Button has been clicked.
WM_NOTIFICATION_RELEASED Button has been released.
WM_NOTIFICATION_MOVED_OUT Button has been clicked and pointer has been moved out of the button without releasing.

Keyboard reaction

The widget reacts to the following keys if it has the input focus:

Key Reaction
GUI_KEY_ENTER If the keys is pressed, the button reacts as it has been pressed and immediately released.
GUI_KEY_SPACE If the keys is pressed, the button state changes to pressed. If the keys is released, the button state changes to unpressed.

 

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

 

ICONVIEW: Icon view widget

The icon view widget can be used for icon based menus often required in hand held devices like mobile telephones or pocket organizers. It shows a list of icons where each icon can be labeled with optional text. Icon view widgets support transparency and alpha blending. So any content can be shown in the background. The currently selected icon can be highlighted by a solid color or with an alpha blending effect, which lets the background shine through. If required a scrollbar can be shown.

ICONVIEW with transparency ICONVIEW without transparency

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

Configuration options

Type Macro Default Description
N ICONVIEW_BKCOLOR0_DEFAULT GUI_WHITE Background color, unselected state.
N ICONVIEW_BKCOLOR1_DEFAULT GUI_BLUE Background color, selected state.
N ICONVIEW_TEXTCOLOR0_DEFAULT GUI_WHITE Text color, unselected state.
N ICONVIEW_TEXTCOLOR1_DEFAULT GUI_WHITE Text color, selected state.
S ICONVIEW_FONT_DEFAULT GUI_Font13_1 Font to be used for drawing the labels.
N ICONVIEW_FRAMEX_DEFAULT 5 Free space between the icons and the left and right border of the widget.
N ICONVIEW_FRAMEY_DEFAULT 5 Free space between the icons and the top and bottom border of the widget.
N ICONVIEW_SPACEX_DEFAULT 5 Free horizontal space between the icons.
N ICONVIEW_SPACEY_DEFAULT 5 Free vertical space between the icons.
N ICONVIEW_ALIGN_DEFAULT GUI_TA_HCENTER | GUI_TA_BOTTOM Default alignment to be used for drawing the labels.

Notification codes

The following events are sent from an ICONVIEW widget to its parent window as part of a WM_NOTIFY_PARENT message:

Message Description
WM_NOTIFICATION_CLICKED Widget has been clicked.
WM_NOTIFICATION_RELEASED Widget has been released.
WM_NOTIFICATION_MOVED_OUT Widget has been clicked and pointer has been moved out of the widget area without releasing.
WM_NOTIFICATION_SCROLL_CHANGED The scroll position of the optional scrollbar has been changed.
WM_NOTIFICATION_SEL_CHANGED The selection of the widget has been changed.

Keyboard reaction

The widget reacts to the following keys if it has the input focus:

Key Reaction
GUI_KEY_RIGHT Moves the selection to the next icon.
GUI_KEY_LEFT Moves the selection to the previous icon.
GUI_KEY_DOWN Moves the selection down.
GUI_KEY_UP Moves the selection up.
GUI_KEY_HOME Moves the selection to the first icon.
GUI_KEY_END Moves the selection to the last icon.

 

IMAGE: Image widget

Image widgets are used to display images of different formats from internal as well as from external memory.

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

Configuration options

The IMAGE widget can be configured using an or-combination of the following symbols as ’ExFlags’-parameter at creation.

Configuration flag Default Description
IMAGE_CF_MEMDEV not set Use an internal memory device to display compressed images (GIF, JPEG, PNG).
IMAGE_CF_TILE not set Use tiling to fill the whole widget area.
IMAGE_CF_ALPHA not set Support PNG images using alpha blending.
IMAGE_CF_ATTACHED not set Fix the widget size to the borders of the parent window.
IMAGE_CF_AUTOSIZE not set Set the widget size to the size of the image.

 

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

 

LISTWHEEL: Listwheel widget

This widget is similar to the LISTBOX widget described above. Whereas the data of a LISTBOX is selected by moving the cursor with the keyboard or by using a SCROLLBAR the LISTWHEEL works completely different: The whole data area can be moved via pointer input device (PID). Striking over the widget from top to bottom or vice versa moves the data up or downwards. When releasing the PID during the data area is moving it slows down its motion and stops by snapping in a new item at the snap position. Further the data is shown in a loop. After the last data item it continues with the first item like in a chain. So the data can be ’rotated’ like a wheel:

Description LISTWHEEL widget
Application example showing three wheels for selecting a date. The example uses the owner draw mechanism to overlay the widget with a customized alpha mask for the shading effect.

The table above shows a screenshot of the example WIDGET_ListWheel.c located in the example folder Sample\Tutorial\ of the emWin package.

Configuration options

Type Macro Default Description
S LISTWHEEL_FONT_DEFAULT GUI_Font13_1 Font used.
N LISTWHEEL_BKCOLOR0_DEFAULT GUI_WHITE Background color of normal text.
N LISTWHEEL_BKCOLOR1_DEFAULT GUI_WHITE Background color of selected text.
N LISTWHEEL_TEXTCOLOR0_DEFAULT GUI_BLACK Text color of normal text.
N LISTWHEEL_TEXTCOLOR1_DEFAULT GUI_BLUE Text color of selected text.
N LISTWHEEL_TEXTALIGN_DEFAULT GUI_TA_LEFT Default text alignment

Notification codes

The following events are sent from the widget to its parent window as part of a WM_NOTIFY_PARENT message:

Message Description
WM_NOTIFICATION_CLICKED Widget has been clicked.
WM_NOTIFICATION_RELEASED Widget has been released.
WM_NOTIFICATION_MOVED_OUT Widget has been clicked and pointer has been moved out of the widget without releasing.
WM_NOTIFICATION_SEL_CHANGED An item has been snapped at the snap position.

Keyboard reaction

This widget currently does not react on keyboard input.

 

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

 

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.

 

SPINBOX: Spinning box widget

SPINBOX widgets are used to manage values which need to be adjustable in a fast but still precise manner. A SPINBOX consists of 2 buttons and an embedded EDIT widget.

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

Skinning...

...is available for this widget. The screenshot above shows the widget using the default skin. For details please refer to the chapter ’Skinning’.

Configuration options

Type Macro Default Description
N SPINBOX_DEFAULT_BUTTON_BKCOLOR0 0xAAAAAA Background color for the button state disabled.
N SPINBOX_DEFAULT_BUTTON_BKCOLOR1 GUI_WHITE Background color for the button state pressed.
N SPINBOX_DEFAULT_BUTTON_BKCOLOR2 GUI_LIGHTGRAY Background color for the button state unpressed.
N SPINBOX_DEFAULT_BUTTON_UCOLOR0 0xAAAAAA Background color for the button state disabled.
N SPINBOX_DEFAULT_BUTTON_UCOLOR1 GUI_WHITE Background color for the button state pressed.
N SPINBOX_DEFAULT_BUTTON_UCOLOR2 GUI_LIGHTGRAY Background color for the button state unpressed.
N SPINBOX_DEFAULT_BUTTON_LCOLOR0 0xAAAAAA Background color for the button state disabled.
N SPINBOX_DEFAULT_BUTTON_LCOLOR1 GUI_WHITE Background color for the button state pressed.
N SPINBOX_DEFAULT_BUTTON_LCOLOR2 GUI_LIGHTGRAY Background color for the button state unpressed.
N SPINBOX_DEFAULT_BUTTON_OCOLOR0 0xAAAAAA Background color for the button state disabled.
N SPINBOX_DEFAULT_BUTTON_OCOLOR1 GUI_WHITE Background color for the button state pressed.
N SPINBOX_DEFAULT_BUTTON_OCOLOR2 GUI_LIGHTGRAY Background color for the button state unpressed.
N SPINBOX_DEFAULT_BKCOLOR0 0xC0C0C0 Background color for the edit state enabled.
N SPINBOX_DEFAULT_BKCOLOR1 GUI_WHITE Background color for the edit state disabled.
N SPINBOX_DEFAULT_TEXTCOLOR0 0xC0C0C0 Background color for the edit state enabled.
N SPINBOX_DEFAULT_TEXTCOLOR1 GUI_WHITE Background color for the edit state disabled.
N SPINBOX_DEFAULT_TRIANGLE_COLOR0 0xAAAAAA Background color for the button state disabled.
N SPINBOX_DEFAULT_TRIANGLE_COLOR1 GUI_WHITE Background color for the button state pressed.
N SPINBOX_DEFAULT_TRIANGLE_COLOR2 GUI_LIGHTGRAY Background color for the button state unpressed.
N SPINBOX_DEFAULT_STEP 1 Value will be increased/decreased by this amount when a button is clicked.
N SPINBOX_DEFAULT_BUTTON_SIZE 0 X-Size of the buttons.
N SPINBOX_DEFAULT_EDGE SPINBOX_EDGE_RIGHT Determines the position of the buttons. See table below.
N SPINBOX_TIMER_PERIOD_START 400 Once a button is pressed for this amount of time, a timer is created to increase/decrease the value continuously.
N SPINBOX_TIMER_PERIOD 50 Once the timer is created values are adjusted at intervals of this amount of time.

 

Possible values to be defined as SPINBOX_DEFAULT_EDGE
SPINBOX_EDGE_LEFT Buttons are displayed on the left edge of the widget.
SPINBOX_EDGE_RIGHT Buttons are displayed on the right edge of the widget.

 

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.

 

TREEVIEW: Treeview widget

A treeview widget can be used to show a hierarchical view of information like files in a directory or items of an index, whereas each item can be a node or a leaf. Each node can have a number of sub items and can be closed or opened.

A node consists of a button image, which shows a plus sign in closed state or a minus sign in open state, two item images (one for closed and one for open state) and the item text. Pressing the button image or double clicking the item image toggles the state (open or closed) of the node.

A leaf consists of an item image and the item text.

The current selection can be marked by highlighting the item text or by highlighting the whole row. All items of a tree are joined by lines per default.

All TREEVIEW-related routines are located in the file(s) TREEVIEW*.c, TREEVIEW*.h. All identifiers are prefixed TREEVIEW. The table below shows the appearances of the TREEVIEW widget:

Description TREEVIEW widget
Treeview widget with row selection enabled.
Treeview widget with text selection enabled.
Treeview widget with some application defined bitmaps and lines off.

Description of terms

Item

This means a treeview item which can be a leaf or a node.

Leaf

A leaf is a treeview item which is not able to have any children. It is represented by the leaf bitmap and the item text.

Node

A node is a treeview item which is able to have children. It is represented by the button bitmap, the node bitmap and the item text. The state of the node can be toggled by pressing the button bitmap or by double clicking the node bitmap or the selected area of the item. In open state the children are visible below the node at the next level of indentation.

Button bitmap

This means the bitmap visible at nodes which can be pressed to toggle the state of the node.

Item bitmap

Left beside the item text the item bitmap is shown. Which bitmap is shown depends in the item (leaf or node) and in case of a node it also depends on the state, collapsed or expanded.

Expanded state

In expanded state the children of a node are visible and the minus sign is shown in the button bitmap.

Collapsed state

In collapsed state the children of a node are hidden and the plus sign is shown in the button bitmap.

Joining lines

Lines which are used to connect the items of a tree. The lines connect the button bitmaps of the nodes and the item bitmaps of the leafs according to the hierarchy of the tree.

Configuration options

Type Macro Default Description
  TREEVIEW_FONT_DEFAULT &GUI_Font13_1 Default font used to draw the text.
  TREEVIEW_BKCOLOR0_DEFAULT GUI_WHITE Background color for unselected state.
  TREEVIEW_BKCOLOR1_DEFAULT GUI_BLUE Background color for selected state.
  TREEVIEW_BKCOLOR2_DEFAULT 0xC0C0C0 Background color for disabled state.
  TREEVIEW_TEXTCOLOR0_DEFAULT GUI_BLACK Text color for unselected state.
  TREEVIEW_TEXTCOLOR1_DEFAULT GUI_WHITE Text color for selected state.
  TREEVIEW_TEXTCOLOR2_DEFAULT GUI_GRAY Text color for disabled state.
  TREEVIEW_LINECOLOR0_DEFAULT GUI_BLACK Line color for unselected state.
  TREEVIEW_LINECOLOR1_DEFAULT GUI_WHITE Line color for selected state.
  TREEVIEW_LINECOLOR2_DEFAULT GUI_GRAY Line color for disabled state.
  TREEVIEW_IMAGE_CLOSED_DEFAULT Item image for node in closed state.
  TREEVIEW_IMAGE_OPEN_DEFAULT Item image for node in open state.
  TREEVIEW_IMAGE_LEAF_DEFAULT Item image for leaf.
  TREEVIEW_IMAGE_PLUS_DEFAULT Plus sign.
  TREEVIEW_IMAGE_MINUS_DEFAULT Minus sign.
  TREEVIEW_INDENT_DEFAULT 16 Number of pixels for indenting.
  TREEVIEW_TEXT_INDENT_DEFAULT 20 Number of pixels for indenting text.

Notification codes

The following events are sent from a treeview widget to its parent window as part of a WM_NOTIFY_PARENT message:

Message Description
WM_NOTIFICATION_CLICKED Treeview has been clicked.
WM_NOTIFICATION_RELEASED Treeview has been released.
WM_NOTIFICATION_MOVED_OUT Treeview has been clicked and pointer has been moved out of the widget area without releasing.
WM_NOTIFICATION_SEL_CHANGED Value (selection) of the treeview widget has changed.

Keyboard reaction

The widget reacts to the following keys if it has the input focus:

Key Reaction
GUI_KEY_RIGHT If the cursor is at a closed node, the node is opened. If the cursor is at an open node the cursor moves to the first child of the node.
GUI_KEY_DOWN The cursor moves to the next visible item below the current position.
GUI_KEY_LEFT If the cursor is at a leaf the cursor moves to the parent node of the item.
If the cursor is at an open node, the node will be closed.
If the cursor is at a closed node, the cursor moves to the next parent node.
GUI_KEY_UP The cursor moves to the previous visible item above the current position.

 

back to top

© 2012, www.segger.com, All rights reserved.