emWin User Guide & Reference Manual

Graphic Library with Graphic User Interface
Document: UM03001
Software Version: 6.46
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.

Requirements

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.

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.

Limitation

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.

Features

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 multi-task 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:

General

• 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.
• Virtual display support; the virtual display can be larger than the actual display.

Graphic library

• Bitmaps of different color depths supported.
• Bitmap Converter available.
• Fast line/point drawing (without floating-point usage).
• Very fast drawing of rectangles, circles, polygons and many more shapes.
• Anti-aliased drawing of shapes in different qualities.
• Sub-pixel anti-aliased rendering.
• Different drawing modes.

Fonts

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

Widgets for PC-like or smartphone-like look and feel

• Widgets (window objects, also known as controls) are available. They manage their appearance and their user input themselves and are easy to use through their API.

Touch-screen & mouse support

• For window objects such as the button widget, emWin offers touch-screen and mouse support.

PC tools

• AppWizard for building complete applications in a WYSIWYG editor without having to write C code.
• Simulation library for Win32 environments. The source code may be purchased additionally.
• emWinView, tool for viewing the framebuffer content while debugging with the simulation.
• Bitmap Converter, for converting common image formats into formats that are optimized for emWin.
• Font Converter, for converting common font formats into formats that are optimized for emWin.
• emWinSPY, tool for viewing runtime information about an emWin application (memory status, widgets, etc).
• emWin4Web, command line tool for building emWin applications to WebAssembly which can be run in any web browser.

Complete emWin system

The diagram below shows the individual components of a complete emWin system.