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.