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. |
| GRAPH | Graph widget, used to show curves or measured values. |
| HEADER | Header control, used to manage columns |
| LISTBOX | Listbox which highlights items as they are selected by the user. |
| LISTVIEW | Listview widgets are used to creates tables |
| MENU | Menu widgets are used to create horizontal and vertical menus. |
| MESSAGEBOX | 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. |
| 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. |
| 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_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> Callback | Default callback function. |
| <WIDGET>_CreateIndirect | Used for automatic creation in dialog boxes. |
| WIDGET_GetDefaultEffect | Returns the default effect used for new widgets. |
| WIDGET_SetDefaultEffect | Sets the default effect used for new widgets. |
| WIDGET_SetEffect | Sets the effect used for a given widget. |
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_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. |
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.
| Routine | Explanation |
| BUTTON_Create | Create the button. (Obsolete) |
| BUTTON_CreateAsChild | Create the button as a child window. (Obsolete) |
| BUTTON_CreateEx | Creates the button. |
| BUTTON_CreateIndirect | Create the button from resource table entry. |
| BUTTON_GetBitmap | Returns a pointer to the BUTTON bitmap. |
| BUTTON_GetBkColor | Returns the background color of the BUTTON. |
| BUTTON_GetDefaultBkColor | Returns the default background color for new BUTTON widgets. |
| BUTTON_GetDefaultFont | Returns the default font for new BUTTON widgets. |
| BUTTON_GetDefaultTextAlign | Returns the default text alignment for new BUTTON widgets. |
| BUTTON_GetDefaultTextColor | Returns the default text color for new BUTTON widgets. |
| BUTTON_GetFont | Returns a pointer to the font of the BUTTON. |
| BUTTON_GetText | Retrieves the text of a specified BUTTON. |
| BUTTON_GetTextColor | Returns the text color of the specified BUTTON. |
| BUTTON_IsPressed | Returns if a button is pressed or not. |
| 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_SetBMP | Set the bitmap used when displaying the BUTTON. |
| BUTTON_SetBMPEx | Set the bitmap used when displaying the BUTTON. |
| BUTTON_SetDefaultBkColor | Sets the default background color for new BUTTON widgets. |
| BUTTON_SetDefaultFont | Sets the default font for new BUTTON widgets. |
| BUTTON_SetDefaultTextAlign | Sets the default text alignment for new BUTTON widgets. |
| BUTTON_SetDefaultTextColor | Sets the default text color for new BUTTON widgets. |
| BUTTON_SetFocussable | Sets the ability to receive the input focus. |
| BUTTON_SetFont | Select the font for the text. |
| BUTTON_SetPressed | Sets the state of the button to pressed or 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 |
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_BKCOLOR_DEFAULT | 0xC0C0C0 | Default background color. |
| N | CHECKBOX_BKCOLOR0_DEFAULT | 0x808080 | Background color of the default image, disabled state. |
| N | CHECKBOX_BKCOLOR1_DEFAULT | GUI_WHITE | Background color of the default image, enabled state. |
| N | CHECKBOX_FGCOLOR0_DEFAULT | 0x101010 | Foreground color of the default image, disabled state. |
| N | CHECKBOX_FGCOLOR1_DEFAULT | GUI_BLACK | Foreground color of the default image, enabled state. |
| N | CHECKBOX_FOCUSCOLOR_DEFAULT | GUI_BLACK | Color used to render the focus rectangle. |
| S | CHECKBOX_FONT_DEFAULT | &GUI_Font13_1 | Default font used to display the optional checkbox text. |
| S | CHECKBOX_IMAGE0_DEFAULT | (see table above) | Pointer to bitmap used to draw the widget if checked, disabled state. |
| S | CHECKBOX_IMAGE1_DEFAULT | (see table above) | Pointer to bitmap used to draw the widget if checked, enabled state. |
| N | CHECKBOX_SPACING_DEFAULT | 4 | Spacing used to display the optional checkbox text beside the box. |
| N | CHECKBOX_TEXTALIGN_DEFAULT | GUI_TA_LEFT | GUI_TA_VCENTER | Default alignment of the optional checkbox text. |
| N | CHECKBOX_TEXTCOLOR_DEFAULT | GUI_BLACK | Default color used to display the optional checkbox text. |
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. (Obsolete) |
| CHECKBOX_Create | Create the check box. (Obsolete) |
| CHECKBOX_CreateEx | Creates the check box. |
| CHECKBOX_CreateIndirect | Create the check box from resource table entry. |
| CHECKBOX_GetDefaultBkColor | Returns the default background color of new check box widgets. |
| CHECKBOX_GetDefaultFont | Returns the default font used to display the text of new check box widgets. |
| CHECKBOX_GetDefaultSpacing | Returns the default spacing between the box and the text of new check box widgets. |
| CHECKBOX_GetDefaultTextAlign | Returns the default alignment used to display the check box text of new check box widgets. |
| CHECKBOX_GetDefaultTextColor | Returns the default text color used to display the text of new check box widgets. |
| CHECKBOX_GetState | Returns the current state of the check box. |
| CHECKBOX_GetText | Returns the text of the check box. |
| CHECKBOX_IsChecked | Return the current state (checked or not checked) of the check box. |
| CHECKBOX_SetBkColor | Sets the background color of new check box widgets. |
| CHECKBOX_SetBoxBkColor | Sets the background color of the check box widget. |
| CHECKBOX_SetDefaultBkColor | Sets the default background color of new check box widgets. |
| CHECKBOX_SetDefaultFocusColor | Sets the default focus rectangle color for new check box widgets. |
| CHECKBOX_SetDefaultFont | Sets the default font used to display the text of new check box widgets. |
| CHECKBOX_SetDefaultImage | Sets the default image to be shown when a new box has been checked. |
| CHECKBOX_SetDefaultSpacing | Sets the default spacing between the box and the text of new check box widgets. |
| CHECKBOX_SetDefaultTextAlign | Sets the default alignment used to display the check box text. |
| CHECKBOX_SetDefaultTextColor | Sets the default text color used to display the text of new check box widgets. |
| CHECKBOX_SetFocusColor | Sets the color of the focus rectangle. |
| CHECKBOX_SetImage | Sets the image to be shown when box has been checked. |
| CHECKBOX_SetNumStates | Sets the number of possible states of the check box (2 or 3). |
| CHECKBOX_SetSpacing | Sets the spacing between the box and the check box text. |
| CHECKBOX_SetState | Sets the state of the check box. |
| CHECKBOX_SetText | Sets the text of the check box. |
| CHECKBOX_SetTextAlign | Sets the alignment used to display the check box text. |
| CHECKBOX_SetTextColor | Sets the color used to display the text of the check box. |
| CHECKBOX_Uncheck | Set the check box state to unchecked (default). |
DROPDOWN: Dropdown widget
DROPDOWN widgets are used to select one element of a list with several columns. It shows the currently selected item in non open state. If the user opens a DROPDOWN widget, a LISTBOX appears to select a new item.
| Dropdown closed | Dropdown opened |
![]() |
![]() |
If mouse support is enabled, the open list reacts on moving the mouse over it.
Configuration options
| Type | Macro | Default | Explanation |
| N | DROPDOWN_ALIGN_DEFAULT | GUI_TA_LEFT | Text alignment used to display the dropdown text in closed state. |
| S | DROPDOWN_FONT_DEFAULT | GUI_Font13_1 | Default font. |
| N | DROPDOWN_BKCOLOR0_DEFAULT | GUI_WHITE | Background color, unselected state. |
| N | DROPDOWN_BKCOLOR1_DEFAULT | GUI_GRAY | Background color, selected state without focus. |
| N | DROPDOWN_BKCOLOR2_DEFAULT | GUI_BLUE | Background color, selected state with focus. |
| N | DROPDOWN_KEY_EXPAND | GUI_KEY_SPACE | Key which can be used to expand the dropdown list. |
| N | DROPDOWN_KEY_SELECT | GUI_KEY_ENTER | Key which can be used to select an item from the open dropdown list. |
| N | DROPDOWN_TEXTCOLOR0_DEFAULT | GUI_BLACK | Text color, unselected state. |
| N | DROPDOWN_TEXTCOLOR1_DEFAULT | GUI_BLACK | Text color, selected state without focus. |
| N | DROPDOWN_TEXTCOLOR2_DEFAULT | GUI_WHITE | Enable 3D support. |
DROPDOWN API reference
| Routine | Explanation |
| DROPDOWN_AddString | Adds an element to the DROPDOWN list. |
| DROPDOWN_Collapse | Closes the dropdown list. |
| DROPDOWN_Create | Creates a DROPDOWN widget. (Obsolete) |
| DROPDOWN_CreateEx | Creates a DROPDOWN widget. |
| DROPDOWN_CreateIndirect | Creates a DROPDOWN widget from a resource table entry. |
| DROPDOWN_DecSel | Decrements selection. |
| DROPDOWN_DeleteItem | Deletes an item of the DROPDOWN list. |
| DROPDOWN_Expand | Opens the dropdown list. |
| DROPDOWN_GetDefaultFont | Returns the default font used to create DROPDOWN widgets. |
| DROPDOWN_GetItemDisabled | Returns the state of the given item. |
| DROPDOWN_GetNumItems | Returns the number of items in the dropdown list. |
| DROPDOWN_GetSel | Returns the number of the currently selected element. |
| DROPDOWN_IncSel | Increments selection. |
| DROPDOWN_InsertString | Inserts a string to the dropdown list. |
| DROPDOWN_SetAutoScroll | Enables the automatic use of a scrollbar in the dropdown list. |
| DROPDOWN_SetBkColor | Sets the background color. |
| DROPDOWN_SetColor | Sets the color of the arrow and the button of the widget. |
| DROPDOWN_SetDefaultColor | Sets the default color of the arrow and the button for new DROPDOWN widgets. |
| DROPDOWN_SetDefaultFont | Sets the default font used to create DROPDOWN widgets. |
| DROPDOWN_SetDefaultScrollbarColor | Sets the default colors of the optional scrollbar in the dropdown list. |
| DROPDOWN_SetFont | Sets the font of the given DROPDOWN widget |
| DROPDOWN_SetItemDisabled | Sets the state of the given item. |
| DROPDOWN_SetItemSpacing | Sets an additional spacing between the items of the dropdown list. |
| DROPDOWN_SetScrollbarColor | Sets the colors of the scrollbar in the dropdown list. |
| DROPDOWN_SetSel | Sets the current selection. |
| DROPDOWN_SetTextAlign | Sets the text alignment used to display the dropdown text in closed state. |
| DROPDOWN_SetTextColor | Sets the text color of the given DROPDOWN widget. |
| DROPDOWN_SetTextHeight | Sets the height of the rectangle used to display the dropdown text in closed state. |
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.
| Routine | Explanation |
| EDIT_AddKey | Key input routine. |
| EDIT_Create | Create the edit field. (Obsolete) |
| EDIT_CreateAsChild | Create the edit field as a child window. (Obsolete) |
| EDIT_CreateEx | Create the edit field. |
| EDIT_CreateIndirect | Create the edit field from resource table entry. |
| EDIT_EnableBlink | Enables/disables a blinking cursor |
| EDIT_GetCursorCharPos | Returns the number of the character at the cursor position. |
| EDIT_GetCursorPixelPos | Returns the pixel position of the cursor. |
| EDIT_GetDefaultBkColor | Returns the default background color. |
| EDIT_GetDefaultFont | Returns the default font. |
| EDIT_GetDefaultTextAlign | Returns the default texe alignment. |
| EDIT_GetDefaultTextColor | Returns the default text color. |
| EDIT_GetFloatValue | Returns the current value as floating point value. |
| EDIT_GetNumChars | Returns the number of characters of the given edit widget. |
| EDIT_GetText | Get user input. |
| EDIT_GetValue | Returns the current value. |
| EDIT_SetBinMode | Enables the binary edit mode. |
| EDIT_SetBkColor | Sets the background color of the edit field. |
| EDIT_SetCursorAtChar | Sets the edit widget cursor to a specified character position. |
| EDIT_SetCursorAtPixel | Sets the edit widget cursor to a specified pixel position. |
| EDIT_SetDecMode | Enables the decimal edit mode. |
| EDIT_SetDefaultBkColor | Sets the default background color. |
| EDIT_SetDefaultFont | Sets the default font used for edit fields. |
| EDIT_SetDefaultTextAlign | Sets the default text alignment for edit fields. |
| EDIT_SetDefaultTextColor | Sets the default text color. |
| EDIT_SetFloatMode | Enables the floating point edit mode. |
| EDIT_SetFloatValue | Sets the floating point value if using the floating point edit mode. |
| EDIT_SetFont | Select the font for the text. |
| EDIT_SetHexMode | Enables the hexadecimal edit mode. |
| EDIT_SetInsertMode | Enables or disables the insert mode. |
| EDIT_SetMaxLen | Sets the maximum number of characters of the edit field. |
| EDIT_SetpfAddKeyEx | Sets a function which is called to add a character. |
| EDIT_SetSel | Sets the current selection. |
| EDIT_SetText | Sets the text. |
| EDIT_SetTextAlign | Sets the text alignment for the edit field. |
| EDIT_SetTextColor | Sets the color(s) for the text. |
| EDIT_SetTextMode | Sets the edit mode of the widget back to text mode. |
| EDIT_SetValue | Sets the current value. |
| EDIT_SetUlongMode | Enables the unsigned long decimal edit mode. |
| 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 |
| B | FRAMEWIN_ALLOW_DRAG_ON_FRAME | 1 | Allows dragging the widget on the surrounding frame. |
| 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. |
| N | FRAMEWIN_TITLEHEIGHT_DEFAULT | 0 | Default height of title bar. |
FRAMEWIN API reference
The table below lists the available emWin EDIT-related routines in alphabetical order.
| Routine | Explanation |
| FRAMEWIN_AddButton | Adds a button in the title bar. |
| FRAMEWIN_AddCloseButton | Adds a close button in the title bar. |
| FRAMEWIN_AddMaxButton | Adds a maximize button in the title bar. |
| FRAMEWIN_AddMenu | Adds a menu widget to the frame window. |
| FRAMEWIN_AddMinButton | Adds a minimize button in the title bar. |
| FRAMEWIN_Create | Creates the frame window. (Obsolete) |
| FRAMEWIN_CreateAsChild | Creates the frame window as a child window. (Obsolete) |
| FRAMEWIN_CreateEx | Creates the frame window. |
| FRAMEWIN_GetActive | Returns if the frame window is in avtive state. |
| FRAMEWIN_GetBarColor | Returns the color of the title bar. |
| FRAMEWIN_GetBorderSize | Returns the size of the border. |
| FRAMEWIN_GetDefaultBarColor | Returns the default color of the title bar. |
| FRAMEWIN_GetDefaultBorderSize | Returns the default border size. |
| FRAMEWIN_GetDefaultClientColor | Returns the default color of the client area. |
| FRAMEWIN_GetDefaultFont | Returns the default font used for the title bar. |
| FRAMEWIN_GetDefaultTextColor | Returns the default text color of the title. |
| FRAMEWIN_GetDefaultTitleHeight | Returns the default size of the title bar. |
| FRAMEWIN_GetFont | Returns the font used for the title text. |
| FRAMEWIN_GetText | Returns the title text. |
| FRAMEWIN_GetTextAlign | Returns the alignment of the title text. |
| FRAMEWIN_GetTitleHeight | Returns the height of the title bar. |
| FRAMEWIN_IsMinimized | Returns if the framewin is minimized or not. |
| FRAMEWIN_IsMaximized | Returns if the framewin is maximized or not. |
| FRAMEWIN_Maximize | Enlarges the frame window to the size of its parent. |
| FRAMEWIN_Minimize | Hides the client area of the frame window. |
| FRAMEWIN_OwnerDraw | Default function for drawing the title bar. |
| FRAMEWIN_Restore | Restores a minimized or maximized frame window. |
| FRAMEWIN_SetActive | Sets the state of the frame window. (Obsolete) |
| FRAMEWIN_SetBarColor | Sets the color of the title bar. |
| FRAMEWIN_SetBorderSize | Sets the border size of the frame window. |
| FRAMEWIN_SetClientColor | Sets the color of the client area. |
| FRAMEWIN_SetDefaultBarColor | Sets the default color of the title bar. |
| FRAMEWIN_SetDefaultBorderSize | Sets the default border size. |
| FRAMEWIN_SetDefaultClientColor | Sets the default color of the client area. |
| FRAMEWIN_SetDefaultFont | Sets the default font used for the title bar. |
| FRAMEWIN_SetDefaultTextColor | Sets the default text color of the title. |
| FRAMEWIN_SetDefaultTitleHeight | Sets the default height of the title bar. |
| FRAMEWIN_SetFont | Selects the font used for the title text. |
| FRAMEWIN_SetMoveable | Sets the frame window to a moveable/non-moveable state. |
| FRAMEWIN_SetOwnerDraw | Enables the frame window to be owner drawn. |
| FRAMEWIN_SetResizeable | Sets the frame window to resizable state. |
| 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_SetTextColorEx | Sets the color(s) for the title text. |
| FRAMEWIN_SetTitleHeight | Sets the height of the title bar. |
| FRAMEWIN_SetTitleVis | Sets the visibility flag of the title bar. |
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 |
![]() |
![]() |
Configuration options
| Type | Macro | Default | Explanation |
| N | GRAPH_BKCOLOR_DEFAULT | GUI_BLACK | Default background color of the data area. |
| N | GRAPH_BORDERCOLOR_DEFAULT | 0xC0C0C0 | Default background color of the border. |
| N | GRAPH_FRAMECOLOR_DEFAULT | GUI_WHITE | Default color of the thin frame line. |
| N | GRAPH_GRIDCOLOR_DEFAULT | GUI_DARKGRAY | Default color used to draw the grid. |
| N | GRAPH_GRIDSPACING_X_DEFAULT | 50 | Default horizontal spacing of the grid. |
| N | GRAPH_GRIDSPACING_Y_DEFAULT | 50 | Default vertical spacing of the grid. |
| N | GRAPH_BORDER_L_DEFAULT | 0 | Default size of the left border. |
| N | GRAPH_BORDER_T_DEFAULT | 0 | Default size of the top border. |
| N | GRAPH_BORDER_R_DEFAULT | 0 | Default size of the right border. |
| N | GRAPH_BORDER_B_DEFAULT | 0 | Default size of the bottom border. |
GRAPH API reference
The table below lists the available emWin GRAPH-related routines in alphabetical order.
| Routine | Explanation |
| Common routines | |
| GRAPH_AttachData | Attaches a data object to a graph widget. |
| GRAPH_AttachScale | Attaches a scale object to a graph widget. |
| GRAPH_CreateEx | Creates a graph widget. |
| GRAPH_DetachData | Detaches a data object from a graph widget. |
| GRAPH_DetachScale | Detaches a scale object from a graph widget. |
| GRAPH_SetBorder | Sets the size (right, left, top and bottom) of the border. |
| GRAPH_SetColor | Sets the color of the graph widget. |
| GRAPH_SetGridDistX | Sets the horizontal grid spacing. |
| GRAPH_SetGridDistY | Sets the vertical grid spacing. |
| GRAPH_SetGridFixedX | Fixes the grid in X-axis. |
| GRAPH_SetGridVis | Enables the drawing of a grid. |
| GRAPH_SetLineStyleH | Sets the line style for the horizontal grid lines. |
| GRAPH_SetLineStyleV | Sets the line style for the vertical grid lines. |
| GRAPH_SetVSizeX | Sets the horizontal range of the graph widget. |
| GRAPH_SetVSizeY | Sets the vertical range of the graph widget. |
| GRAPH_SetUserDraw | Sets the user callback function. |
| GRAPH_DATA_YT related routines | |
| GRAPH_DATA_YT_AddValue | Adds one data item to the data object. |
| GRAPH_DATA_YT_Create | Creates a GRAPH_DATA_YT object. |
| GRAPH_DATA_YT_SetOffY | Sets a vertical offset for drawing the data. |
| GRAPH_DATA_XY related routines | |
| GRAPH_DATA_XY_AddPoint | Adds one point to the data object. |
| GRAPH_DATA_XY_Create | Creates a GRAPH_DATA_YT object. |
| GRAPH_DATA_XY_SetLineStyle | Sets the line style used to draw the data. |
| GRAPH_DATA_XY_SetOffX | Sets a horizontal offset for drawing the data. |
| GRAPH_DATA_XY_SetOffY | Sets a vertical offset for drawing the data. |
| GRAPH_DATA_XY_SetPenSize | Sets the pen size used to draw the data. |
| Scale related routines | |
| GRAPH_SCALE_Create | Creates a scale object. |
| GRAPH_SCALE_SetFactor | Sets a calculation factor used to calculate from pixels to the desired unit. |
| GRAPH_SCALE_SetFixed | Avoids scrolling of the scale. |
| GRAPH_SCALE_SetFont | Sets the font used to draw the numbers. |
| GRAPH_SCALE_SetNumDecs | Sets the number of digits of the fractional portion. |
| GRAPH_SCALE_SetOff | Sets an optional offset which is added to the numbers. |
| GRAPH_SCALE_SetPos | Sets the horizontal or vertical position of the scale. |
| GRAPH_SCALE_SetTextColor | Sets the text color of the scale. |
| GRAPH_SCALE_SetTickDist | Sets the distance in pixels between the tick marks. |
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 |
Configuration options
| Type | Macro | Default | Explanation |
| N | HEADER_BKCOLOR_DEFAULT | 0xAAAAAA | Default value of background color |
| S | HEADER_CURSOR_DEFAULT | &GUI_CursorHeaderM | Default cursor |
| S | HEADER_FONT_DEFAULT | &GUI_Font13_1 | Default font |
| N | HEADER_BORDER_H_DEFAULT | 2 | Horizontal space between text and border |
| N | HEADER_BORDER_V_DEFAULT | 0 | Vertical space between text and border |
| B | HEADER_SUPPORT_DRAG | 1 | Enable/disable dragging support |
| N | HEADER_TEXTCOLOR_DEFAULT | GUI_BLACK | Default value of text color |
HEADER API reference
The table below lists the available emWin HEADER-related routines in alphabetical order.
| Routine | Explanation |
| HEADER_AddItem | Adds one item at the right side |
| HEADER_Create | Creates a HEADER widget. (Obsolete) |
| HEADER_CreateAttached | Creates a HEADER widget attached to a window |
| HEADER_CreateEx | Creates a HEADER widget. |
| HEADER_CreateIndirect | Creates a HEADER widget from a resource table entry |
| HEADER_GetDefaultBkColor | Returns the default background color |
| HEADER_GetDefaultBorderH | Returns the value of the horizontal spacing. |
| HEADER_GetDefaultBorderV | Returns the value of the vertical spacing. |
| HEADER_GetDefaultCursor | Returns the a pointer to the default cursor. |
| HEADER_GetDefaultFont | Returns a pointer to the default font. |
| HEADER_GetDefaultTextColor | Returns the default text color. |
| HEADER_GetHeight | Returns the height of the widget. |
| HEADER_GetItemWidth | Returns the item width. |
| HEADER_GetNumItems | Returns the number of items. |
| HEADER_SetBitmap | Sets the bitmap used when displaying the given item. |
| HEADER_SetBitmapEx | Sets the bitmap used when displaying the given item. |
| HEADER_SetBkColor | Sets the background color of the widget. |
| HEADER_SetBMP | Sets the bitmap used when displaying the given item. |
| HEADER_SetBMPEx | Sets the bitmap used when displaying the given item. |
| HEADER_SetDefaultBkColor | Sets the default background color. |
| HEADER_SetDefaultBorderH | Sets the default value for the horizontal spacing. |
| HEADER_SetDefaultBorderV | Sets the default value for the vertical spacing. |
| HEADER_SetDefaultCursor | Sets the default cursor. |
| HEADER_SetDefaultFont | Sets the default font. |
| HEADER_SetDefaultTextColor | Sets the default text color. |
| HEADER_SetDragLimit | Sets the limit for dragging the items on or off. |
| HEADER_SetFont | Sets the font of the widget. |
| HEADER_SetHeight | Sets the height of the widget. |
| HEADER_SetTextAlign | Sets the alignment of the given item. |
| HEADER_SetItemText | Sets the text of a given item. |
| HEADER_SetItemWidth | Sets the width of a given item. |
| HEADER_SetStreamedBitmap | Sets the bitmap used when displaying the given item. |
| HEADER_SetStreamedBitmapEx | Sets the bitmap used when displaying the given item. |
| HEADER_SetTextColor | Sets the Text color of the widget. |
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_BLUE | 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_WHITE | Text color, selected state without focus. |
| N | LISTBOX_TEXTCOLOR2_DEFAULT | GUI_WHITE | Text color, selected state with focus. |
LISTBOX API reference
The table below lists the available emWin LISTBOX-related routines in alphabetical order.
| Routine | Explanation |
| LISTBOX_AddString | Adds an item to a list box. |
| LISTBOX_Create | Creates the list box. (Obsolete) |
| LISTBOX_CreateAsChild | Creates the list box as a child window. (Obsolete) |
| LISTBOX_CreateEx | Creates the list box. |
| LISTBOX_CreateIndirect | Creates the list box from resource table entry. |
| LISTBOX_DecSel | Decrements selection. |
| LISTBOX_DeleteItem | Deletes an element. |
| LISTBOX_GetDefaultBkColor | Returns the default background color for LISTBOX widgets. |
| LISTBOX_GetDefaultFont | Returns the default font for LISTBOX widgets. |
| LISTBOX_GetDefaultScrollStepH | Returns the default number of pixels to be scrolled horizontal. |
| LISTBOX_GetDefaultTextAlign | Returns the default text alignment for new list boxes. |
| LISTBOX_GetDefaultTextColor | Returns the default text color for new list boxes. |
| LISTBOX_GetFont | Returns the font of the list box. |
| LISTBOX_GetItemDisabled | Returns the disabled state of the given item. |
| LISTBOX_GetItemSel | Returns the selection state of a LISTBOX entry. |
| LISTBOX_GetItemText | Returns the text of a list box entry. |
| LISTBOX_GetMulti | Returns if the multi select mode is active. |
| LISTBOX_GetNumItems | Returns the number of items in a list box. |
| LISTBOX_GetScrollStepH | Returns the number of pixels to be scrolled horizontal. |
| LISTBOX_GetSel | Returns the number of the selected item. |
| LISTBOX_GetTextAlign | Returns the text alignment of the LISTBOX. |
| LISTBOX_IncSel | Increments selection. |
| LISTBOX_InsertString | Inserts an element. |
| LISTBOX_InvalidateItem | Invalidates an item of an owner drawn LISTBOX. |
| LISTBOX_OwnerDraw | Default function for drawing a LISTBOX entry. |
| LISTBOX_SetAutoScrollH | Activates automatic use of a horizontal scrollbar. |
| LISTBOX_SetAutoScrollV | Activates automatic use of a vertical scrollbar. |
| LISTBOX_SetBkColor | Sets the background color. |
| LISTBOX_SetDefaultBkColor | Sets the default background color for LISTBOX widgets. |
| LISTBOX_SetDefaultFont | Changes the default font for LISTBOX widgets. |
| LISTBOX_SetDefaultScrollStepH | Sets the default number of pixels to be scrolled horizontal. |
| LISTBOX_SetDefaultTextAlign | Sets the default text alignment for new LISTBOX widgets. |
| LISTBOX_SetDefaultTextColor | Sets the default text color for LISTBOX widgets. |
| LISTBOX_SetFont | Selects the font. |
| LISTBOX_SetItemDisabled | Sets the disabled state of the given item. |
| LISTBOX_SetItemSel | Sets the selection state of the given item. |
| LISTBOX_SetItemSpacing | Sets a spacing between the items. |
| LISTBOX_SetMulti | Sets the multi selection mode on or off. |
| LISTBOX_SetOwnerDraw | Enables the list box to be owner drawn. |
| LISTBOX_SetScrollbarColor | Sets the colors of the optional scrollbar. |
| LISTBOX_SetScrollbarWidth | Sets the width of the scrollbars used by the LISTBOX. |
| LISTBOX_SetScrollStepH | Sets the number of pixels to be scrolled horizontal. |
| LISTBOX_SetSel | Sets the selected item. |
| LISTBOX_SetString | Sets the text of an element. |
| LISTBOX_SetTextAlign | Sets the text alignment of the LISTBOX. |
| LISTBOX_SetTextColor | Sets the foreground color. |
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 |
![]() |
Configuration options
| Type | Macro | Default | Explanation |
| S | LISTVIEW_FONT_DEFAULT | &GUI_Font13_1 | Default font |
| N | LISTVIEW_BKCOLOR0_DEFAULT | GUI_WHITE | Background color, unselected state. |
| N | LISTVIEW_BKCOLOR1_DEFAULT | GUI_GRAY | Background color, selected state without focus. |
| N | LISTVIEW_BKCOLOR2_DEFAULT | GUI_BLUE | Background color, selected state with focus. |
| N | LISTVIEW_SCROLLSTEP_H_DEFAULT | 10 | the number of pixels to be scrolled if needed. |
| N | LISTVIEW_TEXTCOLOR0_DEFAULT | GUI_BLACK | Text color, unselected state. |
| N | LISTVIEW_TEXTCOLOR1_DEFAULT | GUI_WHITE | Text color, selected state without focus. |
| N | LISTVIEW_TEXTCOLOR2_DEFAULT | GUI_WHITE | Text color, selected state with focus. |
| N | LISTVIEW_GRIDCOLOR_DEFAULT | GUI_LIGHTGRAY | Color of grid lines (if shown) |
| N | LISTVIEW_ALIGN_DEFAULT | GUI_TA_VCENTER | GUI_TA_HCENTER | Default text alignment |
LISTVIEW API reference
The table below lists the available emWin LISTVIEW-related routines in alphabetical order.
| Routine | Explanation |
| LISTVIEW_AddColumn | Adds a column to a LISTVIEW. |
| LISTVIEW_AddRow | Adds a row to a LISTVIEW. |
| LISTVIEW_CompareDec | Compare function for comparing 2 integer values. |
| LISTVIEW_CompareText | Compare function for comparing 2 strings. |
| LISTVIEW_Create | Creates a LISTVIEW widget. (Obsolete) |
| LISTVIEW_CreateAttached | Creates a LISTVIEW widget attached to a window. |
| LISTVIEW_CreateEx | Creates a LISTVIEW widget. |
| LISTVIEW_CreateIndirect | Creates a LISTVIEW widget from a resource table entry. |
| LISTVIEW_DecSel | Decrements selection. |
| LISTVIEW_DeleteColumn | Deletes the given column. |
| LISTVIEW_DeleteRow | Deletes the given row. |
| LISTVIEW_DisableRow | Sets the state of the given row to disabled. |
| LISTVIEW_DisableSort | Disables sorting of the LISTVIEW. |
| LISTVIEW_EnableRow | Sets the state of the given row to enabled. |
| LISTVIEW_EnableSort | Enables sorting of the LISTVIEW. |
| LISTVIEW_GetBkColor | Returns the background color of the LISTVIEW. |
| LISTVIEW_GetFont | Returns the font of the LISTVIEW. |
| LISTVIEW_GetHeader | Returns the handle of the attached HEADER widget. |
| LISTVIEW_GetItemText | Returns the text of the given cell. |
| LISTVIEW_GetNumColumns | Returns the number of columns. |
| LISTVIEW_GetNumRows | Returns the number of rows. |
| LISTVIEW_GetSel | Returns the number of the selected item. |
| LISTVIEW_GetSelUnsorted | Returns the number of the selected item in unsorted state. |
| LISTVIEW_GetTextColor | Returns the text color of the LISTVIEW. |
| LISTVIEW_GetUserData | Returns the user data of the given row. |
| LISTVIEW_IncSel | Increments selection. |
| LISTVIEW_InsertRow | Inserts a new row at the given position. |
| LISTVIEW_SetAutoScrollH | Enables the automatic use of a horizontal scrollbar. |
| LISTVIEW_SetAutoScrollV | Enables the automatic use of a vertical scrollbar. |
| LISTVIEW_SetBkColor | Sets the background color. |
| LISTVIEW_SetColumnWidth | Sets the column width. |
| LISTVIEW_SetCompareFunc | Sets the compare function for the given column. |
| LISTVIEW_SetDefaultBkColor | Sets the default background color for HEADER widgets. |
| LISTVIEW_SetDefaultFont | Sets the default font for HEADER widgets. |
| LISTVIEW_SetDefaultGridColor | Sets the default text color for HEADER widgets. |
| LISTVIEW_SetDefaultTextColor | Sets the default color of the grid lines for HEADER widgets. |
| LISTVIEW_SetFixed | Fixes the given number of columns. |
| LISTVIEW_SetFont | Sets the font of the LISTVIEW. |
| LISTVIEW_SetGridVis | Sets the visibility flag of the grid lines. |
| LISTVIEW_SetItemBkColor | Sets the background color of a LISTVIEW cell |
| LISTVIEW_SetItemText | Sets the text of a LISTVIEW cell. |
| LISTVIEW_SetItemTextColor | Sets the text color of a LISTVIEW cell |
| LISTVIEW_SetLBorder | Sets the number of pixels used for the left border. |
| LISTVIEW_SetRBorder | Sets the number of pixels used for the right border. |
| LISTVIEW_SetRowHeight | Sets the row height of the LISTVIEW |
| LISTVIEW_SetSel | Sets the current selection. |
| LISTVIEW_SetSelUnsorted | Sets the current selection in unsorted state. |
| LISTVIEW_SetSort | Sets the column and sorting order to be sorted by. |
| LISTVIEW_SetTextAlign | Sets the text alignment of a column. |
| LISTVIEW_SetTextColor | Sets the text color. |
| LISTVIEW_SetUserData | Sets the user data of the given row. |
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.
Configuration options
| Type | Macro | Default | Explanation |
| N | MENU_BKCOLOR0_DEFAULT | GUI_LIGHTGRAY | Background color for enabled and unselected items. |
| N | MENU_BKCOLOR1_DEFAULT | 0x980000 | Background color for enabled and selected items. |
| N | MENU_BKCOLOR2_DEFAULT | GUI_LIGHTGRAY | Background color for disabled items. |
| N | MENU_BKCOLOR3_DEFAULT | 0x980000 | Background color for disabled and selected items. |
| N | MENU_BKCOLOR4_DEFAULT | 0x7C7C7C | Background color for active sub- menu items. |
| N | MENU_BORDER_BOTTOM_DEFAULT | 2 | Border between item text and item bottom. |
| N | MENU_BORDER_LEFT_DEFAULT | 4 | Border between item text and left edge of item. |
| N | MENU_BORDER_RIGHT_DEFAULT | 4 | Border between item text and right edge of item. |
| N | MENU_BORDER_TOP_DEFAULT | 2 | Border between item text and item top. |
| S | MENU_EFFECT_DEFAULT | WIDGET_Effect_3D1L | Default effect. |
| S | MENU_FONT_DEFAULT | GUI_Font13_1 | Font used. |
| N | MENU_TEXTCOLOR0_DEFAULT | GUI_BLACK | Text color for enabled and unselected items. |
| N | MENU_TEXTCOLOR1_DEFAULT | GUI_WHITE | Text color for enabled and selected items. |
| N | MENU_TEXTCOLOR2_DEFAULT | 0x7C7C7C | Text color for disabled items. |
| N | MENU_TEXTCOLOR3_DEFAULT | GUI_LIGHTGRAY | Text color for disabled and selected items. |
| N | MENU_TEXTCOLOR4_DEFAULT | GUI_WHITE | Text color for active submenu items. |
MENU API reference
The table below lists the available emWin MENU-related routines in alphabetical order.
| Routine | Explanation |
| MENU_AddItem | Adds an item to an existing menu. |
| MENU_Attach | Attaches a menu with the given size at the given position to a specified window. |
| MENU_CreateEx | Creates a menu widget. |
| MENU_DeleteItem | Deletes the specified menu item. |
| MENU_DisableItem | Disables the specified menu item. |
| MENU_EnableItem | Enables the specified menu item. |
| MENU_GetDefaultBkColor | Returns the default background color for new menus. |
| MENU_GetDefaultBorderSize | Returns the default border size for new menus. |
| MENU_GetDefaultEffect | Returns the default effect for new menus. |
| MENU_GetDefaultFont | Returns a pointer to the default font used to display the menu item text of new menus. |
| MENU_GetDefaultTextColor | Returns the default text color for new menus. |
| MENU_GetItem | Retrieves information about the given menu item. |
| MENU_GetItemText | Returns the text of the given menu item. |
| MENU_GetNumItems | Returns the number of items of the given menu. |
| MENU_GetOwner | Returns the owner window of the given menu. |
| MENU_InsertItem | Inserts a menu item. |
| MENU_Popup | Opens a popup menu at the given position. |
| MENU_SetBkColor | Sets the background color of the given menu. |
| MENU_SetBorderSize | Sets the border size of the given menu. |
| MENU_SetDefaultBkColor | Sets the default background color for new menus. |
| MENU_SetDefaultBorderSize | Sets the default border size for new menus. |
| MENU_SetDefaultEffect | Sets the default effect for new menus. |
| MENU_SetDefaultFont | Sets a pointer to the default font used to display the menu item text of new menus. |
| MENU_SetDefaultTextColor | Sets the default text color for new menus. |
| MENU_SetFont | Sets the font used to display the menu item text of the given menu. |
| MENU_SetItem | Changes the information about the given menu item. |
| MENU_SetOwner | Sets the window to be informed by the menu. |
| MENU_SetTextColor | Sets the text color of the given menu. |
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.

Configuration options
| Type | Macro | Default | Explanation |
| MESSAGEBOX_BORDER | 4 | Distance between the elements of a message box and the elements of the client window frame. | |
| N | MESSAGEBOX_XSIZEOK | 50 | X-size of the "OK" button. |
| N | MESSAGEBOX_YSIZEOK | 20 | Y-size of the "OK" button. |
| S | MESSAGEBOX_BKCOLOR | GUI_WHITE | Color of the client window background. |
MESSAGEBOX API reference
The table below lists the available emWin MESSAGEBOX-related routines in alphabetical order.
| Routine | Explanation |
| GUI_MessageBox() | Creates and displaysa message box. |
| MESSAGEBOX_Create() | Creates a message box. |
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 |
![]() |
Configuration options
| Type | Macro | Default | Explanation |
| S | MULTIEDIT_FONT_DEFAULT | GUI_Font13_1 | Font used. |
| N | MULTIEDIT_BKCOLOR0_DEFAULT | GUI_WHITE | Background color. |
| N | MULTIEDIT_BKCOLOR2_DEFAULT | 0xC0C0C0 | Background color read only mode. |
| N | MULTIEDIT_TEXTCOLOR0_DEFAULT | GUI_BLACK | Text color. |
| N | MULTIEDIT_TEXTCOLOR2_DEFAULT | GUI_BLACK | Text color read only mode. |
MULTIEDIT API reference
The table below lists the available emWin MULTIEDIT-related routines in alphabetical order.
| Routine | Explanation |
| MULTIEDIT_AddKey | Key input routine. |
| MULTIEDIT_AddText | Adds additional text at the current cursor position. |
| MULTIEDIT_Create | Creates a multiedit widget. (Obsolete) |
| MULTIEDIT_CreateEx | Creates a multiedit widget. |
| MULTIEDIT_EnableBlink | Enables/disables a blinking cursor. |
| MULTIEDIT_GetCursorCharPos | Returns the number of the character at the cursor position. |
| MULTIEDIT_GetCursorPixelPos | Returns the pixel position of the cursor. |
| MULTIEDIT_GetPrompt | Returns the text of the prompt. |
| MULTIEDIT_GetText | Returns the text. |
| MULTIEDIT_GetTextSize | Returns the buffer size used by the current text. |
| MULTIEDIT_SetAutoScrollH | Activates automatic use of a horizontal scrollbar. |
| MULTIEDIT_SetAutoScrollV | Activates automatic use of a vertical scrollbar. |
| MULTIEDIT_SetBkColor | Sets the background color. |
| MULTIEDIT_SetBufferSize | Sets the buffer size used for text and prompt. |
| MULTIEDIT_SetCursorOffset | Sets the cursor to the given character. |
| MULTIEDIT_SetFont | Sets the font. |
| MULTIEDIT_SetInsertMode | Enables/disables the insert mode. |
| MULTIEDIT_SetMaxNumChars | Sets the maximum number of characters including the prompt. |
| MULTIEDIT_SetPasswordMode | Enables/disables password mode. |
| MULTIEDIT_SetPrompt | Sets the prompt text. |
| MULTIEDIT_SetReadOnly | Enables/disables the read only mode. |
| MULTIEDIT_SetText | Sets the text. |
| MULTIEDIT_SetTextAlign | Sets the text alignment. |
| MULTIEDIT_SetTextColor | Sets the text color. |
| MULTIEDIT_SetWrapWord | Enables/disables word wrapping. |
| MULTIEDIT_SetWrapNone | Enables/disables the non 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. |
![]() |
Configuration options
| Type | Macro | Default | Explanation |
| N | MULTIPAGE_ALIGN_DEFAULT | MULTIPAGE_ALIGN_LEFT | MULTIPAGE_ALIGN_TOP | Default alignment. |
| N | MULTIPAGE_BKCOLOR0_DEFAULT | 0xD0D0D0 | Default background color of pages in disabled state. |
| N | MULTIPAGE_BKCOLOR1_DEFAULT | 0xC0C0C0 | Default background color of pages in enabled state. |
| S | MULTIPAGE_FONT_DEFAULT | &GUI_Font13_1 | Default font used by the widget. |
| N | MULTIPAGE_TEXTCOLOR0_DEFAULT | 0x808080 | Default text color of pages in disabled state. |
| N | MULTIPAGE_TEXTCOLOR1_DEFAULT | 0x000000 | Default text color of pages in enabled state. |
MULTIPAGE API reference
The table below lists the available emWin MULTIPAGE-related routines in alphabetical order.
| Routine | Explanation |
| MULTIPAGE_AddPage | Adds a page to a MULTIPAGE widget. |
| MULTIPAGE_CreateEx | Creates a new MULTIPAGE widget. |
| MULTIPAGE_CreateIndirect | Creates the MULTIPAGE widget from a resource table entry. |
| MULTIPAGE_DeletePage | Deletes a page from a MULTIPAGE widget. |
| MULTIPAGE_DisablePage | Disables a page from a MULTIPAGE widget. |
| MULTIPAGE_EnablePage | Enables a page from a MULTIPAGE widget. |
| MULTIPAGE_GetDefaultAlign | Returns the default alignment for new MULTIPAGE widgets. |
| MULTIPAGE_GetDefaultBkColor | Returns the default background color for new MULTIPAGE widgets. |
| MULTIPAGE_GetDefaultFont | Returns the default font used for new MULTIPAGE widgets. |
| MULTIPAGE_GetDefaultTextColor | Returns the default text color used for new MULTIPAGE widgets. |
| MULTIPAGE_GetSelection | Returns the current selection. |
| MULTIPAGE_GetWindow | Returns the window handle of a given page. |
| MULTIPAGE_IsPageEnabled | Returns if a given page is enabled or not. |
| MULTIPAGE_SelectPage | Selects the given page. |
| MULTIPAGE_SetAlign | Sets the alignment for the tabs. |
| MULTIPAGE_SetBkColor | Sets the background color. |
| MULTIPAGE_SetDefaultAlign | Sets the default alignment for new MULTIPAGE widgets. |
| MULTIPAGE_SetDefaultBkColor | Sets the default background color for new MULTIPAGE widgets. |
| MULTIPAGE_SetDefaultFont | Sets the default font used by new MULTIPAGE widgets. |
| MULTIPAGE_SetDefaultTextColor | Sets the default text color used by new MULTIPAGE widgets. |
| MULTIPAGE_SetFont | Selects the font for the widget. |
| MULTIPAGE_SetRotation | Sets the rotation mode for the widget. |
| MULTIPAGE_SetText | Sets the text displayed in a tab of a MULTIPAGE widget. |
| MULTIPAGE_SetTextColor | Sets the text 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 |
| PORGBAR_Create | Create the progress bar. (Obsolete) |
| PORGBAR_CreateAsChild | Create the progress bar as a child window. (Obsolete) |
| PORGBAR_CreateEx | Create the progress bar. |
| PORGBAR_CreateIndirect | Create the progress bar from resource table entry. |
| PORGBAR_SetBarColor | Sets the color(s) for the bar. |
| PORGBAR_SetFont | Select the font for the text. |
| PORGBAR_SetMinMax | Set the minimum and maximum values used for the bar. |
| PORGBAR_SetText | Set the (optional) text for the bar graph. |
| PORGBAR_SetTextAlign | Set text alignment (default is centered). |
| PORGBAR_SetTextColor | Set the color(s) for the text. |
| PORGBAR_SetTextPos | Set the text position (default 0,0). |
| PORGBAR_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 |
| S | RADIO_IMAGE0_DEFAULT | Default outer image used to show a disabled radio button. | |
| S | RADIO_IMAGE1_DEFAULT | Default outer image used to show a enabled radio button. | |
| S | RADIO_IMAGE_CHECK_DEFAULT | Default inner image used to mark the selected item. | |
| N | RADIO_FONT_DEFAULT | &GUI_Font13_1 | Default font used to render the radio button text. |
| N | RADIO_DEFAULT_TEXT_COLOR | GUI_BLACK | Default text color of radio button text. |
| N | RADIO_DEFAULT_BKCOLOR | 0xC0C0C0 | Default background color of radio buttons if no transparency is used. |
| N | RADIO_FOCUSCOLOR_DEFAULT | GUI_BLACK | Default color for rendering the focus rectangle. |
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. (Obsolete) |
| RADIO_CreateEx | 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_GetDefaultFont | Returns the default font used to show the text of new radio buttons. |
| RADIO_GetDefaultTextColor | Returns the default text color used to show the text of new radio buttons. |
| RADIO_GetText | Returns the text of a radio button item. |
| RADIO_GetValue | Return the current button selection. |
| RADIO_Inc | Increment the button selection by a value of 1. |
| RADIO_SetBkColor | Sets the background color of the radio button. |
| RADIO_SetDefaultFocusColor | Sets the default focus rectangle color for new radio buttons. |
| RADIO_SetDefaultFont | Sets the default font used to show the text of new radio buttons. |
| RADIO_SetDefaultImage | Sets the images to be used for new radio buttons. |
| RADIO_SetDefaultTextColor | Sets the default text color used to show the text of new radio buttons. |
| RADIO_SetFocusColor | Sets the color of the focus rectangle. |
| RADIO_SetFont | Sets the font used to show the text of the radio button. |
| RADIO_SetGroupId | Sets the group Id of the given radio widget. |
| RADIO_SetImage | Sets the images used to display the radio button. |
| RADIO_SetText | Sets the text |
| RADIO_SetTextColor | Sets the text color used to show the text of radio button. |
| 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, SCROLLBAR. h. All identifiers are prefixed SCROLLBAR.
Configuration options
| Type | Macro | Default | Explanation |
| N | SCROLLBAR_COLOR_SHAFT_DEFAULT | 0x808080 | Color of the shaft. |
| N | SCROLLBAR_COLOR_ARROW_DEFAULT | GUI_BLACK | Color of the arrows. |
| N | SCROLLBAR_COLOR_THUMB_DEFAULT | 0xc0c0c0 | Color of the thumb area. |
| N | SCROLLBAR_THUMB_SIZE_MIN_DEFAULT | 4 | Minimum thumb size. |
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. (Obsolete) |
| SCROLLBAR_CreateAttached | Create a scroll bar attached to a window. |
| SCROLLBAR_CreateEx | Create the scroll bar. |
| SCROLLBAR_CreateIndirect | Creates the scroll bar from resource table entry. |
| SCROLLBAR_Dec | Decrements the value of the scroll bar by a value of 1. |
| SCROLLBAR_GetDefaultWidth | Returns the default width of a scroll bar. |
| SCROLLBAR_GetValue | Returns the current item value. |
| SCROLLBAR_Inc | Increments the value of the scroll bar by a value of 1. |
| SCROLLBAR_SetColor | Sets the color of a scroll bar. |
| SCROLLBAR_SetDefaultColor | Sets the default colors for new scroll bars. |
| SCROLLBAR_SetDefaultWidth | Sets the default width of a scroll bar. |
| SCROLLBAR_SetNumItems | Sets the number of items for scrolling. |
| SCROLLBAR_SetPageSize | Sets the page size (in number of items). |
| SCROLLBAR_SetState | Sets the state of a scroll bar. |
| SCROLLBAR_SetValue | Sets the current value of the scroll bar. |
| SCROLLBAR_SetWidth | Sets the width of the scroll bar. |
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.
Configuration options
| Type | Macro | Default | Explanation |
| N | SLIDER_BKCOLOR0_DEFAULT | 0xc0c0c0 | Background color. |
| N | SLIDER_COLOR0_DEFAULT | 0xc0c0c0 | Slider (thumb) color. |
| N | SLIDER_FOCUS_COLOR_DEFAULT | GUI_BLACK | Default color for rendering the focus rectangle. |
SLIDER API reference
The table below lists the available emWin SLIDER-related routines in alphabetical order.
| Routine | Explanation |
| SLIDER_Create | Create the slider. (Obsolete) |
| SLIDER_CreateEx | 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_SetBkColor | Sets the background color of the slider bar. |
| SLIDER_SetDefaultFocusColor | Sets the default focus rectangle color for new slider bars. |
| SLIDER_SetFocusColor | Sets the color of the focus rectangle. |
| SLIDER_SetNumTicks | Sets the number of tick marks 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 |
| N | TEXT_DEFAULT_BK_COLOR | GUI_INVALID_COLOR | Transparent background per default |
| N | TEXT_DEFAULT_TEXT_COLOR | GUI_BLACK | Default text color. |
| N | TEXT_DEFAULT_WRAPMODE | GUI_WRAPMODE_NONE | Default wrapping mode. |
| 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 | Creates the text widget. (Obsolete) |
| TEXT_CreateAsChild | Creates the text widget as a child window. (Obsolete) |
| TEXT_CreateEx | Creates the text widget. |
| TEXT_CreateIndirect | Creates the text widget from resource table entry. |
| TEXT_GetDefaultFont | Returns the default font used for text. |
| TEXT_SetBkColor | Sets the background color for the text. |
| TEXT_SetDefaultFont | Sets the default font used for text. |
| TEXT_SetDefaultTextColor | Sets the default text color used for text. |
| TEXT_SetDefaultWrapMode | Sets the default wrap mode for new text widgets. |
| TEXT_SetFont | Sets the font used for a specified text widget. |
| TEXT_SetText | Sets the text for a specified text widget. |
| TEXT_SetTextAlign | Sets the text alignment of a specified text widget. |
| TEXT_SetTextColor | Sets the text color of the given widget. |
| TEXT_SetWrapMode | Sets the wrap mode of a specified text widget. |
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.
Configuration options
| Type | Macro | Default | Explanation |
| S | WINDOW_BKCOLOR_DEFAULT | 0xC0C0C0 | Default background color for new WINDOW widgets |
WINDOW API reference
The table below lists the available emWin WINDOW-related routines in alphabetical order.
| Routine | Explanation |
| WINDOW_CreateIndirect | Creates the window widget from a resource table entry. |
| WINDOW_SetDefaultBkColor | Sets the default background color for new WINDOW widgets. |
Widgets
Head office Germany
US office 





























