emWin User Guide & Reference Manual
Graphic Library with Graphic User Interface
Software Version: 6.34
Document revision: 0
Introduction to emWin
This introduction gives some information about this document. It also gives an overview of what features
emWin consists of and what it requires.
Purpose of this document
This guide describes how to install, configure and use the emWin graphical user
interface for embedded applications. It also explains the internal structure of the
software and all the functions which are offered by emWin and intended for direct
use (API, Application Programming Interface). Before actually using emWin, you
should read or at least glance through this manual in order to become familiar with
the software. The following steps are recommended:
- Copy the emWin files to your computer.
- Go through the chapter Getting Started
- Use the simulator in order to become more familiar with what the software can do (refer to the chapter Simulation).
- Expand your program using the rest of the manual for reference.
A target system is not required in order to develop software with emWin; most of the
software can be developed using the simulator. However, the final purpose is usually
to be able to run the software on a target system.
Target system (hardware)
Your target system must:
- Have a CPU (16/32 bits)
- Have a CPU with 64 bits (LP64 and LLP64 data model)
- Have a minimum of RAM and ROM
- Have a full graphic display (any type and any resolution)
The RAM needs to be 8-, 16- and 32-bit accessible. Memory requirements vary
depending on which parts of the software are used and how efficient your target
compiler is. It is therefore not possible to specify precise values, but the following
applies to typical systems.
Small systems (no Window Manager)
- RAM: 2 KBytes *
- Stack: 600 Bytes *
- ROM: 10-25 KBytes *
Big systems (including Window Manager and widgets)
- RAM: 20 KBytes *
- Stack: 1200 Bytes *
- ROM: 30-120 KBytes *
* Depending on the functionality used.
The numbers above are only a rough estimation and can not reflect the exact requirements of an application.
RAM requirement can be increased significantly when using large memory devices or when drawing PNG images.
ROM requirements increase according to the number of fonts and/or images used in the application.
All values are rough estimates and cannot be guaranteed.
More details can be found in the chapter Performance and Resource Usage.
emWin can also be compiled for 64 bit architectures using a LP64 or LLP64 data model. Within the source code of emWin 64 bit data types are defined to ensure memory is accessed properly. Depending on which compiler is used to compile emWin it can be necessary to adapt the definition of PTR_ADDR to access addresses beyond the 32 bit range.
The definition of the 64 bit data models can be found in the file Global.h which is located in the GUI\Core directory of the emWin source code. If your architecture is not covered by the defines in Global.h please make sure to define PTR_ADDR in GUIConf.h according to your architecture.
Development environment (compiler)
The CPU used is of no importance; only an ANSI-compliant C compiler complying with
at least one of the following international standard is required:
- ISO/IEC/ANSI 9899:1990 (C90) with support for C++ style comments (//)
- ISO/IEC 9899:1999 (C99)
- ISO/IEC 14882:1998 (C++)
If your compiler has some limitations, let us know and we will inform you if these will
be a problem when compiling the software. Any compiler for 16/32-bit CPUs or DSPs
that we know of can be used. A C++ compiler is not required, but can be used. The
application program can therefore also be programmed in C++ if desired.
The code of emWin requires a ’char’ type of 8 bits. If a ’char’ is 16 bits the code of
emWin does not work right.
emWin is designed to provide an efficient, processor- and display controller-independent
graphical user interface for any application that operates with a graphical
display. It is compatible with single-task and multitask environments, with a proprietary
operating system or with any commercial RTOS. emWin is shipped as C source code.
It may be adapted to any size physical and virtual display with any display controller
and CPU. Its features include the following:
- Any (monochrome, grayscale or color) display with any controller supported (if the right driver is available).
- Any interface supported using configuration macros.
- May work without display controller on smaller displays.
- Display-size configurable.
- Characters and bitmaps may be written at any point on the display, not just on even-numbered byte addresses.
- Routines are optimized for both size and speed.
- Compile time switches allow for different optimizations.
- For slower display controllers, display can be cached in memory, reducing access to a minimum and resulting in very high speed.
- Clear structure.
- Virtual display support; the virtual display can be larger than the actual display.
- Bitmaps of different color depths supported.
- Bitmap Converter available.
- Absolutely no floating-point usage.
- Fast line/point drawing (without floating-point usage).
- Very fast drawing of circles/polygons.
- Different drawing modes.
- A variety of different fonts are shipped with the basic software: 4×6, 6×8, 6×9,
8×8, 8×9, 8×16, 8×17, 8×18, 24×32, and proportional fonts with pixel-heights of
8, 10, 13, 16. For more information, see chapter Fonts.
- New fonts can be defined and simply linked in.
- Only the fonts used by the application are actually linked to the resulting executable,
resulting in minimum ROM usage.
- Using the Font Converter, any font available on the host system (that is,
Microsoft Windows) can be converted for use in emWin.
- Scalable iType and TTF fonts are supported.
String/value output routines
- Routines to show values in decimal, binary, hexadecimal, any font.
- Routines to edit values in decimal, binary, hexadecimal, any font.
Window Manager (WM)
- Complete window management including clipping. Overwriting of areas outside a window’s client area is impossible.
- Windows can be moved and resized.
- Callback routines supported (usage optional).
- WM uses minimum RAM (approx. 50 bytes per window).
Optional widgets for PC look and feel
- Widgets (window objects, also known as controls) are available. They generally
operate automatically and are simple to use.
Touch-screen & mouse support
- For window objects such as the button widget, emWin offers touch-screen and
- Simulation library for WIN32-Environments. The source code may be purchased additionally.
- Bitmap Converter.
- Font Converter.
Complete emWin system
The diagram below shows the individual components of a complete emWin system.
The touch controller components are marked as optional since they are not necessary for running emWin.