Graphic Library with Graphical User Interface Version 5.12 Manual

Graphic Library with Graphical User Interface Version 5.12 Manual
emWin
Graphic Library with
Graphical User Interface
Version 5.12
Manual Rev. 0
www.segger.com
solutions for embedded software
2
CHAPTER
Disclaimer
Specifications written in this document are believed to be accurate, but are not guaranteed to be entirely free of error. The information in this manual is subject to
change for functional or performance improvements without notice. Please make sure
your manual is the latest edition. While the information herein is assumed to be
accurate, SEGGER Microcontroller GmbH & Co. KG (the manufacturer) assumes no
responsibility for any errors or omissions. The manufacturer makes and you receive
no warranties or conditions, express, implied, statutory or in any communication with
you. The manufacturer specifically disclaims any implied warranty of merchantability
or fitness for a particular purpose.
Copyright notice
You may not extract portions of this manual or modify the PDF file in any way without
the prior written permission of the manufacturer. The software described in this document is furnished under a license and may only be used or copied in accordance
with the terms of such a license.
© 2011 SEGGER Microcontroller GmbH & Co. KG, Hilden / Germany
Trademarks
Names mentioned in this manual may be trademarks of their respective companies.
Brand and product names are trademarks or registered trademarks of their respective holders.
Registration
Please register the software via email. This way we can make sure you will receive
updates or notifications of updates as soon as they become available.
For registration, provide the following:
•
•
•
•
•
Company name and address
Your name
Your job title
Your email address and telephone number
Name and version of the product
Please send this information to: [email protected]
Contact address
SEGGER Microcontroller GmbH & Co. KG
In den Weiden 11
D-40721 Hilden
Germany
Tel.:+49 2103-2878-0
Fax.:+49 2103-2878-28
E-Mail: [email protected]
Internet: http://www.segger.com
Manual versions
This manual describes the latest software version. The version number of the software can be found in the table ’Software versions’ later in this chapter. If any error
occurs, inform us and we will try to assist you as soon as possible.
For further information on topics or routines not yet specified, contact us.
Print date: 6/28/11
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
3
Version
Date
By
Description
5.12R0
110621
AS
JE
Chapter 17 ’Window Objects (Widgets)’
- New function LISTVIEW_SetHeaderHeight() added.
- New function ICONVIEW_AddStreamedBitmapItem() added.
- New function ICONVIEW_GetItemText() added.
- New function ICONVIEW_GetItemUserData() added.
- New function ICONVIEW_GetNumItems() added.
- New function ICONVIEW_InsertBitmapItem() added.
- New function ICONVIEW_InsertStreamedBitmapItem() added.
- New function ICONVIEW_SetBitmapItem() added.
- New function ICONVIEW_SetFrame() added.
- New function ICONVIEW_SetItemText() added.
- New function ICONVIEW_SetItemUserData() added.
- New function ICONVIEW_SetSpace() added.
- New function ICONVIEW_SetStreamedBitmapItem() added.
- New function ICONVIEW_SetTextAlign() added.
- New function TEXT_GetNumLines() added.
Chapter 30 ’Display Drivers’
- New display driver added:
GUIDRV_Dist
GUIDRV_SPage
- New display controller supported by GUIDRV_CompactColor_16:
66709: Solomon SSD1961
- LCD_SetDevFunc(): LCD_DEVFUNC_COPYRECT added.
- GUIDRV_Lin: Support for LCD_DEVFUNC_COPYRECT added.
5.10R1
110531
AS
JE
Chapter 30 ’Display Drivers
- New display driver: GUIDRV_FlexColor
AS
JE
Chapter 14 ’Memory Devices’
- Default for GUI_USE_MEMDEV_1BPP_FOR_SCREEN is 1.
- New function GUI_MEMDEV_MarkDirty() added.
Chapter 19 ’GUIBuilder’ added.
Chapter 30 ’Display Drivers’
- New display controllers supporter by GUIDRV_CompactColor_16:
66708: Ilitek ILI9328
66709: Sitronix ST7715
66772: Ilitek ILI9221
- New function GUIDRV_BitPlains_Config() added.
5.10R0
110329
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
4
CHAPTER
Version
5.08R0
5.06R0
5.04R2
Date
110112
100907
100526
By
Description
AS
JE
Chapter 9 ’2D Graphic Library’
- New function GUI_CreateBitmapFromStreamRLEAlpha() added.
- New function GUI_CreateBitmapFromStreamRLE32() added.
- Function GUI_CreateBitmapFromStream() supports additional formats.
- New function GUI_UC_EnableBIDI() added.
Chapter 12 ’Bitmap Converter’
- New format 'Alpha channel, compressed' added.
- New format 'True color with alpha channel, compressed' added.
- New function 'Image/Convert Into/Best Palette + transparency' added.
Chapter 14 ’Memory Devices’
- New function GUI_MEMDEV_SetAnimationCallback() added.
- New function GUI_MEMDEV_ShiftInWindow() added.
- New function GUI_MEMDEV_ShiftOutWindow() added.
Chapter 15 ’Execution Model’
- New function GUI_SetSignalEventFunc() added.
- New function GUI_SetWaitEventFunc() added.
- New function GUI_SetWaitEventTimedFunc() added.
- Definitions of compile time configuration macros changed.
Chapter 16 ’Window manager’
- New function WM_MULTIBUF_Enable() added.
- New messages WM_PRE_PAINT and WM_POST_PAINT added.
Chapter 17 ’Widgets’
- LISTVIEW_SetUserData() renamed o LISTVIEW_SetUserDataRow().
- LISTVIEW_GetUserData() renamed o LISTVIEW_GetUserDataRow().
- New function <WIDGET>_SetUserData added for all widgets.
- New function <WIDGET>_GetUserData added for all widgets.
- New function <WIDGET>_CreateUser added for all widgets.
- New function BUTTON_GetTextAlign() added.
- New function BUTTON_SetReactOnLevel() added.
- New function ICONVIEW_CreateIndirect() added.
- New function ICONVIEW_DeleteItem() added.
- New function LISTWHEEL_CreateIndirect() added.
- New function SCROLLBAR_SetThumbSizeMin() added.
- New function SCROLLBAR_GetThumbSizeMin() added.
- New function TREEVIEW_ITEM_CollapseAll() added.
- New function TREEVIEW_ITEM_ExpandAll() added.
Chapter 19 ’Skinning’
- New compile time configuration macro WIDGET_USE_FLEX_SKIN added.
- New message WIDGET_ITEM_GET_RADIUS added to frame window skin.
Chapter 20 ’Multiple buffering’.
- New function GUI_MULTIBUF_Begin() added.
- New function GUI_MULTIBUF_End() added.
- New function GUI_MULTIBUF_Config() added.
JE
Chapter 9 ’Fonts’:
- New function GUI_SetDefaultFont() added.
Chapter 12 ’Memory Devices’:
- New function GUI_MEMDEV_FadeDevices() added.
Chapter 15 ’Widgets’:
- New function SCROLLBAR_GetNumItems() added.
- New function SCROLLBAR_GetPageSize() added.
- New function BUTTON_SetReactOnLevel() added.
- New function LISTWHEEL_SetPos() added.
- New function GRAPH_DATA_XY_SetOwnerDraw() added.
- New function LISTVIEW_SetItemBitmap() added.
New chapter 17 ’Skinning’:
- Skinning for the most common widgets added.
Chapter 26 ’Display Driver’:
- New function GUI_SetOrientation() added (rotation device).
- New OXY-orientations for 16, 24 and 32 bpp added to GUIDRV_Lin.
AS
-
New function LISTVIEW_SetItemBitmap() in Chapter ’Widgets’
New function GRAPH_DATA_XY_SetOwnerDraw() in Chapter ’Widgets’
New function GUI_SetDefaultFont() in Chapter ’Fonts’
New function GUI_GetPixelIndex() in Chapter ’2-D Graphic Library’
New function GUITASK_SetMaxTask() in Chapter ’Execution Model’
GUIDRV_CompactColor_16:
Support for the following display controllers added:
Himax HX8353, LGDP4551, Orisetech SPFD54124C, Renesas R61505,
Sitronix ST7735 and ST7787, Solomon SSD1284 and SSD2119.
- Added driver macros to each driver which uses them.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
5
Version
5.04R1
5.04R0
Date
100505
100104
By
Description
AS
Drivers ’GUIDRV_S1D15G00’ and ’GUIDRV_SLin’ added
Various corrections
Chapter ’2-D Graphic Library’:
- New function GUI_DrawGradientRoundedV()
- New function GUI_DrawGradientRoundedH()
- New function GUI_DrawRoundedFrame()
Chapter ’Memory Devices’:
- New function GUI_MEMDEV_MoveInWindow()
- New function GUI_MEMDEV_MoveOutWindow()
- New function GUI_MEMDEV_FadeInWindow()
- New function GUI_MEMDEV_FadeOutWindow()
Chapter ’Simulation’
- New function SIM_GUI_SetCallback()
- New function SIM_GUI_ShowDevice()
JE
Chapter 26 ’VNC Server’:
- New function GUI_VNC_EnableKeyboardInput() added.
- New function GUI_VNC_GetNumConnections() added.
- New function GUI_VNC_SetPassword() added.
- New function GUI_VNC_SetProgName() added.
- New function GUI_VNC_SetSize() added.
- New function GUI_VNC_RingBell() added.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
6
CHAPTER
Version
5.04R0
Date
100104
By
Description
JE
Chapter 5 ’Displaying Text’:
- New function GUI_DispStringInRectWrap() added.
- New function GUI_WrapGetNumLines() added.
Chapter 7 ’2-D Graphic Library’:
- New function GUI_EnableAlpha() added.
- New function GUI_RestoreUserAlpha() added.
- New function GUI_SetUserAlpha() added.
- New function GUI_CreateBitmapFromStream() added.
- New function GUI_DrawStreamedBitmapEx() added.
- New function GUI_GetStreamedBitmapInfo() added.
- New function GUI_GetStreamedBitmapInfoEx() added.
- New function GUI_SetStreamedBitmapHook() added.
- New function GUI_CreateBitmapFromStreamIDX() added.
- New function GUI_CreateBitmapFromStreamRLE4() added.
- New function GUI_CreateBitmapFromStreamRLE8() added.
- New function GUI_CreateBitmapFromStream565() added.
- New function GUI_CreateBitmapFromStreamM565() added.
- New function GUI_CreateBitmapFromStream555() added.
- New function GUI_CreateBitmapFromStreamM555() added.
- New function GUI_CreateBitmapFromStreamRLE16() added.
- New function GUI_CreateBitmapFromStreamRLEM16() added.
- New function GUI_CreateBitmapFromStream24() added.
- New function GUI_CreateBitmapFromStreamAlpha() added.
Chapter 9 ’Fonts’:
- New font F20F_ASCII (framed) added.
- New fonts F6x8_ASCII and F6x8_1 added.
- New fonts F8x8_ASCII and F8x8_1 added.
- New fonts F8x16_ASCII and F8x16_1 added.
- Support for new font formats extended AA2 and extended AA4 added.
Chapter 12 ’Memory Devices’:
- Considerations for multiple layers/displays added.
Chapter 14 ’Window Manager’:
- WM_DeleteWindow() now also deletes any associated timer.
Chapter 15 ’Widgets’:
- New function WINDOW_SetBkColor() added.
Chapter 19 ’Pointer Input Devices’:
- PID buffer added.
- Explanation of touch calibration revised.
Chapter 20 ’Keyboard’:
- Keyboard buffer added.
Chapter 25 ’Display Driver’:
- New driver GUIDRV_BitPlains added.
- New driver GUIDRV_SLin added.
- New driver GUIDRV_SSD1926 added.
- Driver GUIDRV_1611 added.
- Driver GUIDRV_6331 added.
- Driver GUIDRV_7529 added.
- Driver GUIDRV_Page1bpp added.
- GUIDRV_CompactColor_16: Support for the following display controllers
added: Himax HX8340 and HX8352, Solomon SSD1298, SSD1355 and
SSD1963, Epson S1D19122, Orisetech SPFD5414D, Ilitek ILI9320 and
ILI9326
5.00R1
090409
JE
Chapter 3 ’Simulator’:
- Completely revised.
Chapter 8 ’Displaying bitmap files’
- PNG support added.
5.00R0
090326
JE
Software has been completely revised. For the version history of earlier versions, refer to older documents.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
7
SEGGER Microcontroller GmbH & Co. KG develops
and distributes software development tools and ANSI
C software components (middleware) for embedded
systems in several industries such as telecom, medical technology, consumer electronics, automotive
industry and industrial automation.
SEGGER’s intention is to cut software development
time for embedded applications by offering compact flexible and easy to use middleware, allowing developers to concentrate on their
application.
Our most popular products are emWin, a universal graphic software package for embedded applications, and embOS, a small yet efficient real-time kernel. emWin, written
entirely in ANSI C, can easily be used on any CPU and most any display. It is complemented by the available PC tools: Bitmap Converter, Font Converter, Simulator and
Viewer. embOS supports most 8/16/32-bit CPUs. Its small memory footprint makes it
suitable for single-chip applications.
Apart from its main focus on software tools, SEGGER develops and produces programming
tools for flash micro controllers, as well as J-Link, a JTAG emulator to assist in development, debugging and production, which has rapidly become the industry standard for
debug access to ARM cores.
Corporate Office:
http://www.segger.com
EMBEDDED SOFTWARE
(Middleware)
United States Office:
http://www.segger-us.com
SEGGER TOOLS
emWin
Flasher
Graphics software and GUI
emWin is designed to provide an efficient, processor- and display controller-independent graphical user
interface (GUI) for any application that
operates with a graphical display.
Starter kits, eval- and trial-versions
are available.
Flash programmer
Flash Programming tool primarily for microcontrollers.
J-Link
embOS
JTAG emulator with trace
USB driven JTAG interface for ARM cores with
Trace memory. supporting the ARM ETM (Embedded Trace Macrocell).
Real Time Operating System
embOS is an RTOS designed to offer
the benefits of a complete multitasking
system for hard real time applications
with minimal resources. The profiling
PC tool embOSView is included.
emFile
JTAG emulator for ARM cores
USB driven JTAG interface for ARM cores.
J-Trace
J-Link / J-Trace Related Software
Add-on software to be used with SEGGER’s industry standard JTAG emulator, this includes flash
programming software and flash breakpoints.
File system
emFile is an embedded file system with
FAT12, FAT16 and FAT32 support.
emFile has been optimized for minimum memory consumption in RAM and
ROM while maintaining high speed.
Various Device drivers, for example for
NAND and NOR flashes, SD/MMC and
CompactFlash cards, are available.
USB-Stack
USB device stack
A USB stack designed to work on any
embedded system with a USB client
controller. Bulk communication and
most standard device classes are supported.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
8
User's & reference manual for emWin V5.10
CHAPTER
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
9
Table of Contents
1 Introduction to emWin ....................................................................................................23
1.1
1.2
1.3
1.4
1.5
1.5.1
1.5.2
1.6
1.7
1.8
1.9
1.10
1.11
Purpose of this document ......................................................................... 24
Assumptions ........................................................................................... 24
How to use this manual ............................................................................ 24
Typographic conventions for syntax ........................................................... 24
Requirements.......................................................................................... 25
Target system (hardware) ........................................................................ 25
Development environment (compiler)......................................................... 25
Features................................................................................................. 26
Examples and demos ............................................................................... 27
Starter kits ............................................................................................. 27
Screen and coordinates ............................................................................ 27
How to connect the display to the micro controller ....................................... 28
Data types.............................................................................................. 29
2 Getting Started...............................................................................................................31
2.1
2.1.1
2.1.2
2.2
2.3
2.3.1
2.4
2.5
2.6
2.7
2.8
Recommended directory structure.............................................................. 32
Subdirectories ......................................................................................... 32
Include directories ................................................................................... 32
Adding emWin to the target program ......................................................... 32
Creating a library..................................................................................... 33
Adapting the library batch files to a different system .................................... 33
C files to include in the project .................................................................. 35
Configuring emWin .................................................................................. 35
Initializing emWin .................................................................................... 36
Using emWin with target hardware ............................................................ 37
The "Hello world" example program ........................................................... 37
3 Simulation ......................................................................................................................39
3.1
3.1.1
3.1.1.1
3.1.1.2
3.1.1.3
3.1.1.4
3.1.2
3.1.2.1
3.1.2.2
3.1.2.3
3.1.3
3.1.3.1
3.1.3.2
3.1.3.3
3.2
3.2.1
3.2.2
3.2.3
3.3
3.4
3.4.1
Using the simulation ................................................................................ 40
Using the simulation with the trial version of emWin..................................... 40
Directory structure................................................................................... 40
Visual C++ workspace.............................................................................. 40
Compiling the demo program .................................................................... 41
Compiling the examples ........................................................................... 41
Using the simulation with the emWin source................................................ 42
Directory structure................................................................................... 42
Visual C++ workspace.............................................................................. 42
Compiling the application.......................................................................... 43
Advanced features of the simulation........................................................... 43
Pause and Resume .................................................................................. 43
View system info ..................................................................................... 43
Copy to clipboard .................................................................................... 43
Device simulation .................................................................................... 44
Generated frame view .............................................................................. 45
Custom bitmap view ................................................................................ 45
Window view........................................................................................... 46
Device simulation API............................................................................... 47
Hardkey simulation .................................................................................. 52
Hardkey simulation API ............................................................................ 53
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
10
3.5
3.5.1
3.5.2
3.5.2.1
3.5.2.2
3.5.3
3.5.3.1
3.5.3.2
3.5.4
Integrating the emWin simulation into an existing simulation ........................ 56
Directory structure .................................................................................. 56
Using the simulation library ...................................................................... 56
Modifying WinMain .................................................................................. 56
Example application................................................................................. 57
Integration into the embOS Simulation....................................................... 58
WinMain................................................................................................. 58
Target program (main) ............................................................................ 59
GUI simulation API .................................................................................. 60
4 Viewer ............................................................................................................................63
4.1
4.1.1
4.1.2
4.1.3
4.1.4
4.1.5
4.1.6
4.1.7
4.1.8
Using the viewer ..................................................................................... 64
Using the simulation and the viewer .......................................................... 64
Using the viewer with virtual pages ........................................................... 65
Always on top ......................................................................................... 65
Open further windows of the display output ................................................ 65
Zooming ................................................................................................ 66
Copy the output to the clipboard ............................................................... 66
Using the viewer with multiple displays ...................................................... 67
Using the viewer with multiple layers ......................................................... 67
5 Displaying Text ..............................................................................................................69
5.1
5.2
5.3
5.4
5.5
5.6
5.7
5.8
Basic routines ......................................................................................... 70
Text API................................................................................................. 71
Routines to display text............................................................................ 72
Selecting text drawing modes ................................................................... 79
Selecting text alignment........................................................................... 81
Setting the current text position ................................................................ 83
Retrieving the current text position............................................................ 84
Routines to clear a window or parts of it..................................................... 84
6 Displaying Values ..........................................................................................................85
6.1
6.2
6.3
6.4
6.5
6.6
Value API ............................................................................................... 86
Displaying decimal values......................................................................... 87
Displaying floating point values ................................................................. 91
Displaying binary values........................................................................... 94
Displaying hexadecimal values .................................................................. 95
Version of emWin .................................................................................... 96
7 2-D Graphic Library........................................................................................................97
7.1
7.2
7.3
7.4
7.5
7.6
7.7
7.8
7.9
7.10
7.11
7.12
7.13
7.14
7.15
7.16
7.17
Graphic API ............................................................................................ 98
Drawing modes......................................................................................100
Query current client rectangle ..................................................................102
Pen size ................................................................................................102
Basic drawing routines ............................................................................103
Alpha blending.......................................................................................110
Drawing bitmaps ....................................................................................113
Drawing streamed bitmaps ......................................................................116
Drawing lines.........................................................................................122
Drawing polygons...................................................................................126
Drawing circles ......................................................................................131
Drawing ellipses.....................................................................................133
Drawing arcs .........................................................................................135
Drawing graphs .....................................................................................137
Drawing pie charts .................................................................................138
Saving and restoring the GUI-context .......................................................139
Clipping ................................................................................................140
8 Displaying bitmap files .................................................................................................141
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
11
8.1
8.1.1
8.1.2
8.2
8.2.1
8.2.2
8.2.3
8.2.4
8.2.5
8.2.6
8.3
8.3.1
8.3.2
8.3.3
8.3.4
8.4
8.4.1
8.4.2
8.4.3
8.4.4
8.5
BMP file support .................................................................................... 142
Supported formats................................................................................. 142
BMP file API .......................................................................................... 142
JPEG file support ................................................................................... 148
Supported JPEG compression methods ..................................................... 148
Converting a JPEG file to C source............................................................ 148
Displaying JPEG files .............................................................................. 148
Memory usage ...................................................................................... 149
Progressive JPEG files ............................................................................ 149
JPEG file API ......................................................................................... 149
GIF file support ..................................................................................... 154
Converting a GIF file to C source ............................................................. 154
Displaying GIF files ................................................................................ 154
Memory usage ...................................................................................... 154
GIF file API ........................................................................................... 155
PNG file support .................................................................................... 163
Converting a PNG file to C source ............................................................ 163
Displaying PNG files ............................................................................... 163
Memory usage ...................................................................................... 163
PNG file API .......................................................................................... 163
Getting data with the ...Ex() functions ...................................................... 167
9 Fonts ............................................................................................................................169
9.1
9.2
9.3
9.3.1
9.3.2
9.3.3
9.3.4
9.4
9.5
9.6
9.7
9.8
9.9
9.10
9.11
9.12
9.13
9.13.1
9.13.2
9.13.3
9.14
9.14.1
9.15
9.15.1
9.15.2
9.15.3
9.15.4
9.15.4.1
9.15.4.2
9.15.4.3
9.15.5
9.15.5.1
9.15.5.2
9.15.5.3
9.15.6
9.15.6.1
9.15.6.2
9.15.6.3
Introduction.......................................................................................... 170
Font types ............................................................................................ 170
Font formats ......................................................................................... 172
C file format ......................................................................................... 172
System Independent Font (SIF) format..................................................... 172
External Bitmap Font (XBF) format .......................................................... 173
TrueType Font (TTF) format .................................................................... 174
Converting a TTF file to C source ............................................................. 174
Declaring custom fonts ........................................................................... 175
Selecting a font ..................................................................................... 175
Font API ............................................................................................... 176
C file related font functions ..................................................................... 177
’SIF’ file related font functions ................................................................. 178
’TTF’ file related font functions................................................................. 179
’XBF’ file related font functions ................................................................ 183
Common font-related functions ............................................................... 184
Character sets....................................................................................... 188
ASCII................................................................................................... 188
ISO 8859-1 Western Latin character set ................................................... 189
Unicode................................................................................................ 190
Font converter ...................................................................................... 191
Adding fonts ......................................................................................... 191
Standard fonts ...................................................................................... 192
Font identifier naming convention ............................................................ 192
Font file naming convention .................................................................... 193
Measurement, ROM-size and character set of fonts .................................... 193
Proportional fonts .................................................................................. 194
Overview .............................................................................................. 194
Measurement, ROM size and used files ..................................................... 194
Characters............................................................................................ 196
Proportional fonts, framed ...................................................................... 202
Overview .............................................................................................. 202
Measurement, ROM size and used files ..................................................... 202
Characters............................................................................................ 202
Monospaced fonts .................................................................................. 203
Overview .............................................................................................. 203
Measurement, ROM size and used files ..................................................... 204
Characters............................................................................................ 205
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
12
9.15.7
9.15.7.1
9.15.7.2
9.15.7.3
9.15.8
9.15.8.1
9.15.8.2
9.15.8.3
Digit fonts (proportional).........................................................................209
Overview ..............................................................................................209
Measurement, ROM size and used files ......................................................209
Characters ............................................................................................209
Digit fonts (monospaced) ........................................................................210
Overview ..............................................................................................210
Measurement, ROM size and used files ......................................................211
Characters ............................................................................................211
10 Bitmap Converter .......................................................................................................213
10.1
10.2
10.2.1
10.2.2
10.2.3
10.3
10.3.1
10.3.2
10.3.3
10.3.4
10.3.5
10.3.6
10.4
10.5
10.6
10.7
10.7.1
10.7.2
10.7.3
10.7.4
10.8
10.8.1
10.8.2
10.9
What it does ..........................................................................................214
Loading a bitmap ...................................................................................214
Supported input file formats ....................................................................214
Loading from a file .................................................................................214
Using the clipboard.................................................................................215
Generating C files from bitmaps ...............................................................215
Supported bitmap formats.......................................................................215
Palette information .................................................................................215
Transparency.........................................................................................216
Alpha blending.......................................................................................216
Selecting the best format ........................................................................217
Saving the file .......................................................................................218
Color conversion ....................................................................................219
Generating C stream files ........................................................................220
Compressed bitmaps ..............................................................................220
Using a custom palette ...........................................................................221
Saving a palette file................................................................................221
Palette file format ..................................................................................221
Palette files for fixed palette modes ..........................................................221
Converting a bitmap ...............................................................................222
Command line usage ..............................................................................222
Format for commands.............................................................................222
Valid command line options .....................................................................222
Example of a converted bitmap ................................................................224
11 Colors.........................................................................................................................227
11.1
11.2
11.3
11.4
11.5
11.6
11.7
11.8
11.9
Predefined colors....................................................................................228
The color bar test routine ........................................................................228
Fixed palette modes ...............................................................................229
Detailed fixed palette mode description .....................................................230
Application defined color conversion .........................................................240
Custom palette mode..............................................................................241
Color API ..............................................................................................241
Basic color functions ...............................................................................242
Index & color conversion .........................................................................244
12 Memory Devices ........................................................................................................247
12.1
12.2
12.3
12.4
12.5
12.6
12.7
12.8
12.9
12.10
12.10.1
12.11
12.12
Using memory devices: an illustration .......................................................248
Supported color depth (bpp) ....................................................................248
Memory devices and the window manager .................................................249
Memory devices and multiple layers..........................................................249
Memory requirements.............................................................................249
Performance ..........................................................................................250
Basic functions.......................................................................................251
In order to be able to use memory devices... .............................................251
Multi layer / multi display configurations....................................................251
Configuration options..............................................................................251
GUI_USE_MEMDEV_1BPP_FOR_SCREEN....................................................251
Memory device API.................................................................................251
Basic functions.......................................................................................253
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
13
12.13
12.14
12.15
12.16
12.17
Banding memory device ......................................................................... 266
Auto device object ................................................................................. 267
Measurement device object..................................................................... 269
Animation functions ............................................................................... 271
Animation functions (Window Manager required)........................................ 272
13 Execution Model: Single Task / Multitask ..................................................................277
13.1
Supported execution models ................................................................... 278
13.2
Single task system (superloop)................................................................ 278
13.2.1
Description ........................................................................................... 278
13.2.2
Superloop example (without emWin) ........................................................ 278
13.2.3
Advantages........................................................................................... 278
13.2.4
Disadvantages ...................................................................................... 278
13.2.5
Using emWin......................................................................................... 278
13.2.6
Superloop example (with emWin) ............................................................ 279
13.3
Multitask system: one task calling emWin ................................................. 279
13.3.1
Description ........................................................................................... 279
13.3.2
Advantages........................................................................................... 279
13.3.3
Disadvantages ...................................................................................... 279
13.3.4
Using emWin......................................................................................... 279
13.4
Multitask system: multiple tasks calling emWin.......................................... 280
13.4.1
Description ........................................................................................... 280
13.4.2
Advantages........................................................................................... 280
13.4.3
Disadvantages ...................................................................................... 280
13.4.4
Using emWin......................................................................................... 280
13.4.5
Recommendations ................................................................................. 280
13.4.6
Example ............................................................................................... 280
13.5
GUI configuration functions for
multitasking support281
13.6
GUI configuration macros for multitasking support ..................................... 283
13.7
Kernel interface API ............................................................................... 284
13.7.1
Examples ............................................................................................. 287
14 The Window Manager (WM) ......................................................................................289
14.1
14.2
14.2.1
14.2.2
14.2.3
14.2.4
14.2.5
14.2.6
14.2.7
14.2.8
14.3
14.3.1
14.3.2
14.3.3
14.3.4
14.3.5
14.3.6
14.4
14.5
14.5.1
14.6
14.7
14.8
14.9
14.10
Description of terms............................................................................... 290
Callback mechanism, invalidation and rendering ........................................ 291
Rendering without callbacks .................................................................... 291
Rendering using callbacks ....................................................................... 292
Background window redrawing and callback .............................................. 292
Invalidation .......................................................................................... 293
Rendering of transparent windows ........................................................... 293
Automatic use of memory devices............................................................ 293
Automatic use of multiple frame buffers.................................................... 294
Automatic use of display driver cache ....................................................... 294
Messages ............................................................................................. 295
Message structure ................................................................................. 295
List of messages.................................................................................... 295
System-defined messages ...................................................................... 296
Pointer input device (PID) messages ........................................................ 300
System-defined notification codes ............................................................ 303
Application-defined messages.................................................................. 303
Configuration options ............................................................................. 304
WM API ................................................................................................ 305
Using the WM API functions .................................................................... 307
Basic functions ...................................................................................... 307
Memory device support (optional) ............................................................ 336
Timer related functions........................................................................... 336
Widget related functions ......................................................................... 339
Example ............................................................................................... 342
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
14
15 Window Objects (Widgets).........................................................................................345
15.1
15.1.1
15.1.2
15.1.3
15.2
15.3
15.3.1
15.3.2
15.3.3
15.4
15.4.1
15.4.2
15.4.3
15.4.4
15.4.5
15.5
15.5.1
15.5.2
15.5.3
15.5.4
15.5.5
15.6
15.6.1
15.6.2
15.6.3
15.6.4
15.6.5
15.7
15.7.1
15.7.2
15.7.3
15.7.4
15.7.5
15.8
15.8.1
15.8.2
15.8.3
15.8.4
15.8.5
15.9
15.9.1
15.9.2
15.9.3
15.9.4
15.9.4.1
15.9.4.2
15.9.5
15.9.5.1
15.9.5.2
15.9.6
15.9.7
15.9.7.1
15.9.7.2
15.9.7.3
15.9.7.4
15.9.8
15.10
15.10.1
15.10.2
15.10.3
Some basics ..........................................................................................346
Available widgets ...................................................................................346
Understanding the redrawing mechanism ..................................................347
How to use widgets ................................................................................347
Configuration options..............................................................................349
General widget API.................................................................................350
WM routines used for widgets ..................................................................350
Common routines...................................................................................350
User drawn widgets ................................................................................354
BUTTON: Button widget ..........................................................................356
Configuration options..............................................................................356
Notification codes...................................................................................357
Keyboard reaction ..................................................................................357
BUTTON API ..........................................................................................357
Examples ..............................................................................................370
CHECKBOX: Checkbox widget ..................................................................371
Configuration options..............................................................................372
Notification codes...................................................................................372
Keyboard reaction ..................................................................................372
CHECKBOX API ......................................................................................372
Example ...............................................................................................386
DROPDOWN: Dropdown widget ................................................................387
Configuration options..............................................................................388
Notification codes...................................................................................388
Keyboard reaction ..................................................................................388
DROPDOWN API.....................................................................................388
Example ...............................................................................................400
EDIT: Edit widget ...................................................................................402
Configuration options..............................................................................402
Notification codes...................................................................................402
Keyboard reaction ..................................................................................403
EDIT API ...............................................................................................403
Examples ..............................................................................................418
FRAMEWIN: Frame window widget............................................................419
Structure of the frame window .................................................................420
Configuration options..............................................................................421
Keyboard reaction ..................................................................................421
FRAMEWIN API ......................................................................................421
Example ...............................................................................................442
GRAPH: Graph widget .............................................................................443
Structure of the graph widget ..................................................................443
Creating and deleting a graph widget ........................................................444
Drawing process ....................................................................................444
Supported types of curves .......................................................................444
GRAPH_DATA_XY ...................................................................................445
GRAPH_DATA_YT ...................................................................................445
Configuration options..............................................................................445
Graph widget.........................................................................................445
Scale object ..........................................................................................445
Keyboard reaction ..................................................................................445
GRAPH API ............................................................................................445
Common routines...................................................................................447
GRAPH_DATA_YT related routines ............................................................455
GRAPH_DATA_XY related routines ............................................................459
Scale related routines .............................................................................463
Examples ..............................................................................................467
HEADER: Header widget..........................................................................469
Configuration options..............................................................................470
Notification codes...................................................................................470
Keyboard reaction ..................................................................................470
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
15
15.10.4
15.10.5
15.11
15.11.1
15.11.2
15.11.3
15.11.4
15.11.5
15.12
15.12.1
15.12.2
15.12.3
15.12.4
15.12.5
15.13
15.13.1
15.13.2
15.13.3
15.13.4
15.13.5
15.14
15.14.1
15.14.2
15.14.3
15.14.4
15.15
15.15.1
15.15.2
15.15.3
15.15.4
15.15.5
15.15.6
15.16
15.16.1
15.16.2
15.16.3
15.17
15.17.1
15.17.2
15.17.3
15.17.4
15.17.5
15.18
15.18.1
15.18.2
15.18.3
15.18.4
15.18.5
15.19
15.19.1
15.19.2
15.19.3
15.19.4
15.20
15.20.1
15.20.2
15.20.3
15.20.4
15.20.5
15.21
15.21.1
HEADER API.......................................................................................... 470
Example ............................................................................................... 482
ICONVIEW: Icon view widget .................................................................. 483
Configuration options ............................................................................. 483
Notification codes .................................................................................. 484
Keyboard reaction ................................................................................. 484
ICONVIEW API ...................................................................................... 484
Example ............................................................................................... 494
LISTBOX: List box widget ....................................................................... 496
Configuration options ............................................................................. 496
Notification codes .................................................................................. 496
Keyboard reaction ................................................................................. 496
LISTBOX API ......................................................................................... 497
Examples ............................................................................................. 513
LISTVIEW: Listview widget...................................................................... 514
Configuration options ............................................................................. 515
Notification codes .................................................................................. 515
Keyboard reaction ................................................................................. 515
LISTVIEW API ....................................................................................... 516
Example ............................................................................................... 537
LISTWHEEL: Listwheel widget ................................................................. 539
Configuration options ............................................................................. 539
Notification codes .................................................................................. 539
Keyboard reaction ................................................................................. 539
LISTWHEEL API ..................................................................................... 540
MENU: Menu widget............................................................................... 553
Menu messages..................................................................................... 554
Data structures ..................................................................................... 555
Configuration options ............................................................................. 555
Keyboard reaction ................................................................................. 556
MENU API ............................................................................................. 556
Example ............................................................................................... 570
MESSAGEBOX: Message box widget ......................................................... 571
Configuration options ............................................................................. 571
Keyboard reaction ................................................................................. 571
MESSAGEBOX API.................................................................................. 571
MULTIEDIT: Multi line text widget ............................................................ 573
Configuration options ............................................................................. 574
Notification codes .................................................................................. 574
Keyboard reaction ................................................................................. 574
MULTIEDIT API...................................................................................... 574
Example ............................................................................................... 584
MULTIPAGE: Multiple page widget............................................................ 586
Configuration options ............................................................................. 587
Notification codes .................................................................................. 587
Keyboard reaction ................................................................................. 587
MULTIPAGE API ..................................................................................... 587
Example ............................................................................................... 598
PROGBAR: Progress bar widget ............................................................... 599
Configuration options ............................................................................. 599
Keyboard reaction ................................................................................. 599
PROGBAR API ....................................................................................... 599
Examples ............................................................................................. 604
RADIO: Radio button widget ................................................................... 605
Configuration options ............................................................................. 605
Notification codes .................................................................................. 605
Keyboard reaction ................................................................................. 606
RADIO API............................................................................................ 606
Examples ............................................................................................. 615
SCROLLBAR: Scroll bar widget................................................................. 617
Configuration options ............................................................................. 617
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
16
15.21.2
15.21.3
15.21.4
15.21.5
15.22
15.22.1
15.22.2
15.22.3
15.22.4
15.22.5
15.23
15.23.1
15.23.2
15.23.3
15.23.4
15.24
15.24.1
15.24.2
15.24.3
15.24.4
15.24.5
15.24.5.1
15.24.5.2
15.24.6
15.25
15.25.1
15.25.2
15.25.3
Notification codes...................................................................................617
Keyboard reaction ..................................................................................617
SCROLLBAR API .....................................................................................618
Example ...............................................................................................625
SLIDER: Slider widget.............................................................................626
Configuration options..............................................................................626
Notification codes...................................................................................626
Keyboard reaction ..................................................................................626
SLIDER API ...........................................................................................626
Example ...............................................................................................632
TEXT: Text widget ..................................................................................633
Configuration options..............................................................................633
Keyboard reaction ..................................................................................633
TEXT API...............................................................................................633
Examples ..............................................................................................639
TREEVIEW: Treeview widget ....................................................................640
Description of terms ...............................................................................641
Configuration options..............................................................................642
Notification codes...................................................................................642
Keyboard reaction ..................................................................................642
TREEVIEW API .......................................................................................643
Common routines...................................................................................644
Item related routines ..............................................................................657
Example ...............................................................................................662
WINDOW: Window widget .......................................................................663
Configuration options..............................................................................663
Keyboard reaction ..................................................................................663
WINDOW API.........................................................................................663
16 Dialogs .......................................................................................................................665
16.1
16.2
16.2.1
16.2.2
16.2.2.1
16.2.2.2
16.3
16.4
Dialog basics .........................................................................................666
Creating a dialog....................................................................................666
Resource table .......................................................................................666
Dialog procedure....................................................................................667
Initializing the dialog ..............................................................................668
Defining dialog behavior..........................................................................669
Dialog API .............................................................................................670
Dialog boxes..........................................................................................670
17 GUIBuilder .................................................................................................................673
17.1
17.2
17.3
17.3.1
17.3.2
17.3.3
17.3.4
17.3.5
17.3.6
17.4
17.5
17.6
17.7
Introduction ..........................................................................................674
Getting started ......................................................................................675
Creating a dialog....................................................................................676
Selecting a parent widget ........................................................................676
Resizing and positioning in the editor ........................................................676
Modifying the widget properties................................................................676
Adding additional functions to a widget .....................................................676
Deleting a widget property ......................................................................677
Deleting a widget ...................................................................................677
Saving the current dialog(s) ....................................................................678
Output of the GUIBuilder.........................................................................679
Modifying the C files ...............................................................................681
How to use the C files .............................................................................681
18 Skinning .....................................................................................................................683
18.1
18.2
18.3
18.4
18.4.1
What is a ’skin’?.....................................................................................684
From using API functions to skinning ........................................................684
Skinnable widgets ..................................................................................685
Using a skin ..........................................................................................685
Runtime configuration.............................................................................686
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
17
18.4.2
18.5
18.6
18.6.1
18.6.2
18.6.3
18.7
18.8
18.8.1
18.8.2
18.8.3
18.8.4
18.9
18.9.1
18.9.2
18.9.3
18.9.4
18.10
18.10.1
18.10.2
18.10.3
18.10.4
18.11
18.11.1
18.11.2
18.11.3
18.11.4
18.12
18.12.1
18.12.2
18.12.3
18.12.4
18.13
18.13.1
18.13.2
18.13.3
18.13.4
18.14
18.14.1
18.14.2
18.14.3
18.14.4
18.15
18.15.1
18.15.2
18.15.3
18.15.4
18.16
18.16.1
18.16.2
18.16.3
18.16.4
Compile time configuration ..................................................................... 686
Simple changes to the look of the ’Flex’ skin.............................................. 686
Major changes to the look of the ’Flex’ skin ............................................... 687
The skinning callback mechanism ............................................................ 687
Changing the look of the default skin........................................................ 687
List of commands .................................................................................. 688
General skinning API .............................................................................. 690
BUTTON_SKIN_FLEX .............................................................................. 693
Configuration structure........................................................................... 693
Configuration options ............................................................................. 693
Skinning API ......................................................................................... 694
List of commands .................................................................................. 695
CHECKBOX_SKIN_FLEX .......................................................................... 696
Configuration structure........................................................................... 696
Configuration options ............................................................................. 696
Skinning API ......................................................................................... 697
List of commands .................................................................................. 698
DROPDOWN_SKIN_FLEX......................................................................... 700
Configuration structure........................................................................... 700
Configuration options ............................................................................. 701
Skinning API ......................................................................................... 701
List of commands .................................................................................. 702
FRAMEWIN_SKIN_FLEX .......................................................................... 703
Configuration structure........................................................................... 703
Configuration options ............................................................................. 704
Skinning API ......................................................................................... 704
List of commands .................................................................................. 705
HEADER_SKIN_FLEX .............................................................................. 708
Configuration structure........................................................................... 708
Configuration options ............................................................................. 708
Skinning API ......................................................................................... 709
List of commands .................................................................................. 709
PROGBAR_SKIN_FLEX ............................................................................ 711
Configuration structure........................................................................... 711
Configuration options ............................................................................. 711
Skinning API ......................................................................................... 712
List of commands .................................................................................. 712
RADIO_SKIN_FLEX ................................................................................ 715
Configuration structure........................................................................... 715
Configuration options ............................................................................. 716
Skinning API ......................................................................................... 716
List of commands .................................................................................. 717
SCROLLBAR_SKIN_FLEX ......................................................................... 719
Configuration structure........................................................................... 719
Configuration options ............................................................................. 720
Skinning API ......................................................................................... 720
List of commands .................................................................................. 721
SLIDER_SKIN_FLEX ............................................................................... 724
Configuration structure........................................................................... 724
Configuration options ............................................................................. 725
Skinning API ......................................................................................... 725
List of commands .................................................................................. 726
19 Multiple buffering........................................................................................................729
19.1
19.1.1
19.1.2
19.2
19.3
19.4
19.4.1
How it works......................................................................................... 730
Double buffering.................................................................................... 730
Triple buffering...................................................................................... 730
Requirements........................................................................................ 731
Limitations............................................................................................ 731
Configuration ........................................................................................ 731
LCD_X_Config() .................................................................................... 731
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
18
19.4.2
19.5
19.6
LCD_X_DisplayDriver() ...........................................................................732
Automatic use of multiple buffers with the WM ...........................................733
Multiple buffer API..................................................................................734
20 Virtual screen / Virtual pages .....................................................................................739
20.1
20.2
20.3
20.4
20.4.1
20.4.2
20.4.3
20.5
Introduction ..........................................................................................740
Requirements ........................................................................................740
Configuration.........................................................................................741
Examples .............................................................................................741
Basic example .......................................................................................741
Real time example using the window manager ...........................................743
Dialog example using the window manager................................................744
Virtual screen API...................................................................................746
21 Multi layer / multi display support...............................................................................747
21.1
21.1.1
21.1.2
21.1.2.1
21.2
21.2.1
21.2.2
21.2.3
21.2.4
21.3
21.3.1
21.3.2
21.3.3
21.4
21.5
21.6
Introduction ..........................................................................................748
Selecting a layer for drawing operations ....................................................748
Selecting a layer for a window .................................................................748
Moving a window from one layer to an other ..............................................749
Using multi layer support ........................................................................751
Transparency.........................................................................................751
Alpha blending.......................................................................................752
Hardware cursors ...................................................................................753
Multi layer example ................................................................................753
Using multi display support......................................................................753
Enabling multi display support .................................................................753
Run-time screen rotation.........................................................................754
Multi display example .............................................................................754
Configuring multi layer support ................................................................754
Configuring multi display support .............................................................755
Multi layer API .......................................................................................755
22 Pointer Input Devices.................................................................................................759
22.1
22.2
22.3
22.3.1
22.3.2
22.3.2.1
22.3.2.2
22.4
22.4.1
22.4.2
22.4.2.1
22.4.2.2
22.4.2.3
22.4.2.4
22.4.2.5
22.5
Description............................................................................................760
Pointer input device API ..........................................................................760
Mouse driver .........................................................................................761
Generic mouse API .................................................................................761
PS2 mouse driver ...................................................................................762
Using the PS2 mouse driver.....................................................................762
PS2 mouse driver API .............................................................................762
Touch screen driver ................................................................................763
Generic touch screen API ........................................................................763
The analog touch screen driver ................................................................764
Setting up the analog touch screen...........................................................765
Runtime calibration ................................................................................767
Hardware routines..................................................................................767
Driver API for analog touch screens ..........................................................769
Configuring the analog touch-screen driver ................................................770
Joystick input example............................................................................771
23 Keyboard Input...........................................................................................................773
23.1
23.1.1
23.1.2
Description............................................................................................774
Driver layer API .....................................................................................775
Application layer API...............................................................................776
24 Sprites........................................................................................................................777
24.1
24.2
Introduction ..........................................................................................778
Sprite API .............................................................................................778
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
19
25 Cursors ......................................................................................................................783
25.1
25.2
Available cursors ................................................................................... 784
Cursor API ............................................................................................ 784
26 Antialiasing.................................................................................................................787
26.1
26.1.1
26.1.2
26.1.3
26.2
26.3
26.4
26.5
Introduction.......................................................................................... 788
Quality of antialiasing............................................................................. 788
Antialiased Fonts ................................................................................... 788
High-resolution coordinates..................................................................... 789
Antialiasing API ..................................................................................... 790
Control functions ................................................................................... 790
Drawing functions.................................................................................. 791
Examples ............................................................................................. 795
27 Foreign Language Support ........................................................................................801
27.1
27.1.1
27.1.2
27.1.3
27.1.3.1
27.1.4
27.1.4.1
27.1.4.2
27.2
27.2.1
27.2.2
27.2.3
27.2.4
27.2.5
27.2.6
27.2.7
27.3
27.3.1
27.3.2
27.3.3
27.3.4
27.4
27.4.1
Unicode................................................................................................ 802
UTF-8 encoding ..................................................................................... 802
Unicode characters ................................................................................ 802
UTF-8 strings ........................................................................................ 803
Using U2C.exe to convert UTF-8 text into C-code ....................................... 803
Unicode API .......................................................................................... 804
UTF-8 functions ..................................................................................... 804
Double byte functions ............................................................................ 807
Arabic language support ......................................................................... 808
Notation forms ...................................................................................... 808
Ligatures .............................................................................................. 809
Bidirectional text alignment..................................................................... 809
Requirements........................................................................................ 810
How to enable Arabic support .................................................................. 810
Example ............................................................................................... 810
Font files used with Arabic text ................................................................ 810
Thai language support............................................................................ 811
Requirements........................................................................................ 811
How to enable Thai support..................................................................... 811
Example ............................................................................................... 811
Font files used with Thai text................................................................... 811
Shift JIS support ................................................................................... 812
Creating Shift JIS fonts .......................................................................... 812
28 Display drivers ...........................................................................................................813
28.1
28.1.1
28.1.2
28.1.3
28.1.4
28.1.5
28.2
28.2.1
28.2.2
28.2.2.1
28.2.3
28.2.3.1
28.2.4
28.2.4.1
28.2.5
28.2.5.1
28.3
28.3.1
28.3.2
Available display drivers ......................................................................... 814
Driver file naming convention .................................................................. 814
Run-time configurable drivers ................................................................. 814
Compile-time configurable drivers............................................................ 815
Available, but not yet migrated drivers ..................................................... 816
Special purpose drivers .......................................................................... 816
CPU / Display controller interface............................................................. 816
Direct interface ..................................................................................... 817
Indirect interface - Parallel bus ................................................................ 817
Example routines for connection to I/O pins .............................................. 818
Indirect interface - 4 pin SPI ................................................................... 818
Example routines for connection to I/O pins .............................................. 818
Indirect interface - 3 pin SPI ................................................................... 818
Example routines for connection to I/O pins .............................................. 819
Indirect interface - I2C bus ..................................................................... 819
Example routines for connection to I/O pins .............................................. 819
Hardware interface configuration ............................................................. 819
Direct interface ..................................................................................... 819
Indirect interface ................................................................................... 819
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
20
28.3.2.1
28.3.2.2
28.4
28.5
28.5.1
28.5.1.1
28.5.1.2
28.5.2
28.6
28.6.1
28.7
28.7.1
28.7.2
28.7.3
28.7.4
28.7.5
28.7.6
28.7.7
28.7.8
28.7.9
28.7.10
28.7.11
28.7.12
28.7.13
28.7.14
28.7.15
28.7.16
28.7.17
28.7.18
28.8
28.8.1
28.8.2
28.8.3
28.8.3.1
28.8.3.2
28.8.3.3
Run-time configuration ...........................................................................820
Compile-time configuration......................................................................821
Non readable displays .............................................................................824
Display orientation .................................................................................824
Driver based configuration of display orientation ........................................824
Run-time configuration ...........................................................................825
Compile-time configuration......................................................................825
Function based configuration of display orientation .....................................825
Display driver callback function ................................................................827
Commands passed to the callback function ................................................827
Detailed display driver descriptions...........................................................829
GUIDRV_BitPlains...................................................................................829
GUIDRV_Dist .........................................................................................832
GUIDRV_FlexColor..................................................................................834
GUIDRV_IST3088...................................................................................839
GUIDRV_Lin ..........................................................................................841
GUIDRV_S1D13748 ................................................................................845
GUIDRV_S1D15G00 ...............................................................................847
GUIDRV_SLin ........................................................................................850
GUIDRV_SPage......................................................................................854
GUIDRV_SSD1926 .................................................................................858
GUIDRV_CompactColor_16......................................................................861
GUIDRV_Fujitsu_16................................................................................866
GUIDRV_Page1bpp.................................................................................868
GUIDRV_07X1 .......................................................................................871
GUIDRV_1611 .......................................................................................874
GUIDRV_6331 .......................................................................................877
GUIDRV_7529 .......................................................................................879
GUIDRV_Template - Template for a new driver ..........................................882
LCD layer and display driver API ..............................................................883
Display driver API ..................................................................................883
User defined routines..............................................................................884
LCD layer routines..................................................................................885
"Get" group ...........................................................................................885
Configuration group................................................................................888
Cache group ..........................................................................................891
29 VNC Server................................................................................................................893
29.1
29.1.1
29.1.2
29.2
29.2.1
29.3
29.3.1
29.3.2
29.3.3
29.4
29.5
29.6
Introduction ..........................................................................................894
Requirements ........................................................................................894
Notes on this implementation ..................................................................894
The VNC viewer .....................................................................................895
Starting the VNC viewer ..........................................................................895
emWin VNC server .................................................................................896
Starting the emWin VNC server................................................................896
How the server starts ... .........................................................................896
Integration of the VNC server on the target ...............................................896
Requirements ........................................................................................897
Configuration options..............................................................................897
VNC API................................................................................................897
30 Timing- and execution-related functions ....................................................................901
30.1
Timing and execution API ........................................................................902
31 Configuration..............................................................................................................905
31.1
31.2
31.3
31.4
31.4.1
What needs to be configured? ..................................................................906
Run-time- and compile-time configuration .................................................906
Initialization process of emWin.................................................................906
Run-time configuration ...........................................................................907
Customizing GUIConf.c ...........................................................................907
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
21
31.4.1.1
31.4.2
31.4.2.1
31.4.3
31.4.3.1
31.4.3.2
31.4.3.3
31.5
31.5.1
31.5.1.1
31.5.1.2
31.5.1.3
31.5.2
31.6
API functions to be used in GUI_X_Config()............................................... 907
Customizing LCDConf.c .......................................................................... 909
API functions to be used in LCD_X_Config() .............................................. 910
Customizing GUI_X.c ............................................................................. 911
Timing routines ..................................................................................... 911
Debugging routines................................................................................ 912
Kernel interface routines......................................................................... 912
Compile time configuration ..................................................................... 913
Customizing GUIConf.h .......................................................................... 913
Configuring the available features of emWin .............................................. 913
Default font and default color configuration ............................................... 913
Advanced GUI configuration options ......................................................... 914
Customizing LCDConf.h .......................................................................... 915
Request available memory ...................................................................... 915
32 Performance and Resource Usage............................................................................917
32.1
32.1.1
32.1.2
32.2
32.2.1
32.2.2
32.3
Performance ......................................................................................... 918
Driver benchmark .................................................................................. 918
Image drawing performance ................................................................... 919
Memory requirements ............................................................................ 920
Memory requirements of the GUI components ........................................... 920
Stack requirements................................................................................ 921
Memory requirements of example applications........................................... 921
33 Support ......................................................................................................................923
33.1
33.1.1
33.1.2
33.1.3
33.1.4
33.2
33.3
33.4
33.5
33.6
Problems with tool chain (compiler, linker) ................................................ 924
Compiler crash ...................................................................................... 924
Compiler warnings ................................................................................. 924
Compiler errors ..................................................................................... 924
Linker problems .................................................................................... 925
Problems with hardware/driver ................................................................ 925
Problems with API functions .................................................................... 926
Problems with the performance ............................................................... 926
Contacting support ................................................................................ 927
FAQ’s ................................................................................................... 928
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
22
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
23
Chapter 3
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.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
24
CHAPTER
3.1
Introduction to emWin
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.
3.2
Assumptions
This guide assumes that you already possess a solid knowledge of the C programming language. If you feel that your knowledge of C is not sufficient, we recommend
The "C" Programming Language by Kernighan and Richie, which describes the programming standard and, in newer editions, it also covers the ANSI C standard.
Knowledge of assembly programming is not required.
3.3
How to use this manual
This manual explains how to install, configure and use emWin. It describes the internal structure of the software and all the functions that emWin offers (the Application
Program Interface, or API). 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 then recommended:
•
•
•
•
3.4
Copy the emWin files to your computer.
Go through the chapter “Getting Started” on page 31.
Use the simulator in order to become more familiar with what the software can
do (refer to the chapter “Simulation” on page 39).
Expand your program using the rest of the manual for reference.
Typographic conventions for syntax
This manual uses the following typographic conventions:
Style
Used for
Body
Body text.
Keyword
Text that you enter at the command-prompt or that appears on the display (that is,
system functions, file- or pathnames).
Parameter
Parameters in API functions.
Example
Example code in program examples.
New Example
Example code that has been added to an existing program example.
Warning
Important cautions or reminders.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
25
3.5
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.
3.5.1
Target system (hardware)
Your target system must:
•
•
•
Have a CPU (8/16/32/64 bits)
Have a minimum of RAM and ROM
Have a full graphic display (any type and any resolution)
The 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 apply to typical systems.
Small systems (no window manager)
•
•
•
RAM: 100 bytes
Stack: 600 bytes
ROM: 10-25 kb (depending on the functionality used)
Big systems (including window manager and widgets)
•
•
•
RAM: 2-6 kb (depending on number of windows required)
Stack: 1200-1800 bytes (depending on the functionality used)
ROM: 30-60 kb (depending on the functionality used)
Note that ROM requirements will increase if your application uses many fonts. All values are rough estimates and cannot be guaranteed.
3.5.2
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/64-bit CPUs or
DSPs that we know of can be used; most 8-bit compilers can be used as well. A C++
compiler is not required, but can be used. The application program can therefore also
be programmed in C++ if desired.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
26
CHAPTER
3.6
Introduction to emWin
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 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:
General
•
•
•
•
•
•
•
•
•
•
Any (monochrome, grayscale or color) display with any controller supported (if
the right driver is available).
May work without display controller on smaller displays.
Any interface supported using configuration macros.
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.
Graphic library
•
•
•
•
•
•
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.
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.
Fonts are fully scalable, separately in X and Y.
Font converter available; any font available on your host system (that is,
Microsoft Windows) can be converted.
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 (app. 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
mouse support.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
27
PC tools
•
•
•
3.7
Simulation plus viewer.
Bitmap converter.
Font converter.
Examples and demos
To give you a better idea of what emWin can do, we have different demos available
as "ready-to-use" simulation executables under Sample\EXE. The source of the
example programs is located in the folder Sample. The folder Sample\GUIDemo contains an application program showing many features of emWin. All examples are also
available at www.segger.com.
3.8
Starter kits
Complete starter kits including a demo board with a display, a C compiler and an
example project are available. For more details, take a look at our website at
www.segger.com.
3.9
Screen and coordinates
(0,0)
X
The screen consists of many dots that can
be controlled individually. These dots are
called pixels. Most of the text and drawing
functions that emWin offers in its API to the
user program can write or draw on any
specified pixel.
The horizontal scale is called the X-axis,
whereas the vertical scale is called the Yaxis. Coordinates are denoted as a pair
consisting of an X- and a Y-value (X, Y).
The X-coordinate is always first in routines
that require X and Y coordinates. The upper
left corner of the display (or a window) has
per default the coordinates (0,0). Positive
X-values are always to the right; positive Y-values are always down. The above graph
illustrates the coordinate system and directions of the X- and Y- axes. All coordinates
passed to an API function are always specified in pixels.
Y
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
28
CHAPTER
Introduction to emWin
3.10 How to connect the display to the micro controller
emWin handles all access to the display. Virtually any display controller can be supported, independently of how it is accessed. For details, refer to the chapter “Configuration” on page 905. Also, get in contact with us if your display controller is not
supported. We are currently writing drivers for all display controllers available on the
market and may already have a proven driver for the display controller that you
intend to use. It is usually very simple to write the routines (or macros) used to
access the display in your application SEGGER Microcontroller GmbH & Co. KG offers
the service of making these customizations for you, if necessary with your target
hardware.
It does not really matter how the display is connected to the system as long as it is
somehow accessible by software, which may be accomplished in a variety of ways.
Most of these interfaces are supported by a driver which is supplied in source code
form. This driver does not normally require modifications, but is configured for your
hardware by making changes in the file LCDConf.h. Details about how to customize a
driver to your hardware as necessary are provided in the chapter “Display drivers” on
page 813. The most common ways to access the display are described as follows. If
you simply want to understand how to use emWin, you may skip this section.
Display with memory-mapped display controller:
The display controller is connected directly to the data bus of the system, which
means the controller can be accessed just like a RAM. This is a very efficient way of
accessing the display controller and is most recommended. The display addresses are
defined to the segment LCDSEG, and in order to be able to access the display the
linker/locator simply needs to be told where to locate this segment. The location
must be identical to the access address in physical address space. Drivers are available for this type of interface and for different display controllers.
Display with display controller connected to port / buffer
For slower display controllers used on fast processors, the use of port-lines may be
the only solution. This method of accessing the display has the disadvantage of being
somewhat slower than direct bus-interface but, particularly with a cache that minimizes the accesses to the display, the display update is not slowed down significantly.
All that needs to be done is to define routines or macros which set or read the hardware ports/buffers that the display is connected to. This type of interface is also supported by different drivers for the different display controllers.
Proprietary solutions: display without display controller
The display can also be connected without an display controller. In this case, the display data is usually supplied directly by the controller via a 4- or 8-bit shift register.
These proprietary hardware solutions have the advantage of being inexpensive, but
the disadvantage of using up much of the available computation time. Depending on
the CPU, this can be anything between 20 and almost 100 percent; with slower CPUs,
it is really not possible at all. This type of interface does not require a specific display
driver because emWin simply places all the display data into the display cache. You
yourself must write the hardware-dependent portion that periodically transfers the
data in the cache memory to your display.
Example code for transferring the video image into the display is available in both C
and optimized assembler for M16C and M16C/80.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
29
3.11 Data types
Since C does not provide data types of fixed lengths which are identical on all platforms, emWin uses, in most cases, its own data types as shown in the table below:
Data type
Definition
Explanation
I8
signed char
8-bit signed value
U8
unsigned char
8-bit unsigned value
I16
signed short
16-bit signed value
U16
unsigned short
16-bit unsigned value
I32
signed long
32-bit signed value
U32
unsigned long
32-bit unsigned value
I16P
signed short
16-bit (or more) signed value
U16P
unsigned short
16-bit (or more) unsigned value
For most 16/32-bit controllers, the settings will work fine. However, if you have similar defines in other sections of your program, you might want to change or relocate
them. A recommended place is in the file Global.h.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
30
User's & reference manual for emWin V5.10
CHAPTER
Introduction to emWin
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
31
Chapter 4
Getting Started
The following chapter provides an overview of the basic procedures for setting up and
configuring emWin on your target system. It also includes a simple program example.
If you find yourself unsure about certain areas, keep in mind that most topics are
treated in greater detail in later chapters. You will most likely need to refer to other
parts of the manual before you begin more complicated programming.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
32
CHAPTER
4.1
Getting Started
Recommended directory structure
We recommend keeping emWin separate from your application
files. It is good practice to keep all the program files (including
the header files) together in the GUI subdirectories of your
project’s root directory. The directory structure should be similar to the one pictured on the right. This practice has the advantage of being very easy to update to newer versions of emWin
by simply replacing the GUI\ directories. Your application files
can be stored anywhere.
4.1.1
Subdirectories
The following table shows the contents of all GUI subdirectories:
Directory
Contents
Config
Configuration files
GUI\AntiAlias
Antialiasing support *
GUI\ConvertMono
Color conversion routines used for grayscale displays *
GUI\ConvertColor
Color conversion routines used for color displays *
GUI\Core
emWin core files
GUI\Font
Font files
GUI\DisplayDriver
Display driver
GUI\MemDev
Memory device support *
GUI\VNC
VNC support *
GUI\Widget
Widget library *
GUI\WM
Window manager *
(* = optional)
4.1.2
Include directories
You should make sure that the include path contains the following directories (the
order of inclusion is of no importance):
•
•
•
•
•
Config
GUI\Core
GUI\DisplayDriver
GUI\Widget (if using the widget library)
GUI\WM (if using window manager)
Warning: Always make sure that you have only one version of each file!
It is frequently a major problem when updating to a new version of emWin if you
have old files included and therefore mix different versions. If you keep emWin in the
directories as suggested (and only in these), this type of problem cannot occur. When
updating to a newer version, you should be able to keep your configuration files and
leave them unchanged. For safety reasons, we recommend backing up (or at least
renaming) the GUI\ directories prior to updating.
4.2
Adding emWin to the target program
You basically have a choice between including only the source files that you are actually going to use in your project, which will then be compiled and linked, or creating
a library and linking the library file. If your tool chain supports "smart" linking (link-
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
33
ing in only the modules that are referenced and not those that are not referenced),
there is no real need to create a library at all, since only the functions and data structures which are required will be linked. If your tool chain does not support "smart"
linking, a library makes sense, because otherwise everything will be linked in and the
program size will be excessively large. For some CPUs, we have example projects
available to help you get started.
4.3
Creating a library
Building a library from the sources is a simple procedure. The
Makelib.bat
first step is to copy the batch files (located under SampleExample\Makelib) into your root directory. Then, make any necessary changes. There are a total of four batch files which need to
be copied, described in the table below. The main file,
Prep.bat
Makelib.bat, will be the same for all systems and requires no
changes. To build a library for your target system, you will normally need to make slight modifications to the other three
CC.bat
smaller files. Finally, start the file Makelib.bat to create the
library. The batch files assume that your GUI and Config subdiNo
rectories are set up as recommended.
The procedure for creating a library is illustrated in the flow
All files
chart to the right. The Makelib.bat file first calls Prep.bat to
in library?
prepare the environment for the tool chain. Then it calls CC.bat
for every file to be included in the library. It does this as many
times as necessary. CC.bat adds each object file to a list that
Yes
will be used by lib.bat. When all files to be added to the
library have been listed, Makelib.bat then calls lib.bat,
lib.bat
which uses a librarian to put the listed object files into the
actual library. Of course you are free to create libraries in
another way.
It is not recommended to create an emWin library including a compile-time configurable display driver. For further information about the configurability of display drivers, please refer to “Available display drivers” on page 814.
File
Explanation
Makelib.bat
Main batch file. No modification required.
Prep.bat
Called by Makelib.bat to prepare environment for the tool chain to be used,
CC.bat
Called by Makelib.bat for every file to be added to the library; creates a list of these
object files which will then be used in the next step by the librarian in the lib.bat
file.
lib.bat
Called by Makelib.bat to put the object files listed by CC.bat into a library.
The files as shipped assume that a Microsoft compiler is installed in its default location. If all batch files are copied to the root directory (directly above GUI) and no
changes are made at all, a simulation library will be generated for the emWin simulation. In order to create a target library, however, it will be necessary to modify
Prep.bat, CC.bat, and lib.bat.
4.3.1
Adapting the library batch files to a different system
The following will show how to adapt the files by an example adaptation for a Mitsubishi M32C CPU.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
34
CHAPTER
Getting Started
Adapting Prep.bat
Prep.bat is called at the beginning of Makelib.bat. As described above its job is to
set the environment variables for the used tools and the environment variable PATH,
so that the batch files can call the tools without specifying an absolute path. Assuming the compiler is installed in the folder C:\MTOOL the file Prep.bat could look as follows:
@ECHO OFF
SET TOOLPATH=C:\MTOOL
REM ******************************************************************
REM
Set the variable PATH to be able to call the tools
SET PATH=%TOOLPATH%\BIN;%TOOLPATH%\LIB308;%PATH%
REM ******************************************************************
REM
Set the tool internal used variables
SET BIN308=%TOOLPATH%\BIN
SET INC308=%TOOLPATH%\INC308
SET LIB308=%TOOLPATH%\LIB308
SET TMP308=%TOOLPATH%\TMP
Adapting CC.bat
The job of CC.bat is to compile the passed source file and adding the file name of the
object file to a link list. When starting MakeLib.bat it creates the following subdirectories relative to its position:
Directory
Contents
Lib
This folder should contain the library file after the build process.
Temp\Output
Should contain all the compiler output and the link list file. Will be deleted after
the build process.
Temp\Source
MakeLib.bat uses this folder to copy all source and header files used for the
build process. Will be deleted after the build process.
The object file should be created (or moved) to Temp\Output. This makes sure all the
output will be deleted after the build process. Also the link list should be located in
the output folder. The following shows an example for the Mitsubishi compiler:
@ECHO OFF
GOTO START
REM ******************************************************************
REM
Explanation of the used compiler options:
-silent : Suppresses the copyright message display at startup
-M82
: Generates object code for M32C/80 Series (Remove this switch
for M16C80 targets)
-c
: Creates a relocatable file (extension .r30) and ends processing
-I
: Specifies the directory containing the file(s) specified in #include
-dir
: Specifies the destination directory
-OS
: Maximum optimization of speed followed by ROM size
-fFRAM : Changes the default attribute of RAM data to far
-fETI
: Performs operation after extending char-type data to the int type
(Extended according to ANSI standards)
:START
REM ******************************************************************
REM
Compile the passed source file with the Mitsubishi NC308 compiler
NC308 -silent -M82 -c -IInc -dir Temp\Output -OS -fFRAM -fETI Temp\Source\%1.c
REM ******************************************************************
REM
Pause if any problem occurs
IF ERRORLEVEL 1 PAUSE
REM ******************************************************************
REM
Add the file name of the object file to the link list
ECHO Temp\Output\%1.R30>>Temp\Output\Lib.dat
Adapting Lib.bat
After all source files have been compiled Lib.bat will be called from MakeLib.bat.
The job is to create a library file using the link list created by CC.bat. The destination
folder of the library file should be the Lib folder created by MakeLib.bat. The following shows an example for the Mitsubishi librarian:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
35
@ECHO OFF
GOTO START
REM ******************************************************************
REM
Explanation of the used options:
-C : Creates new library file
@ : Specifies command file
:START
REM ******************************************************************
REM
Create the first part of the linker command file
ECHO -C Lib\GUI>Temp\Output\PARA.DAT
REM ******************************************************************
REM
Merge the first part with the link list to the linker command file
COPY Temp\Output\PARA.DAT+Temp\Output\Lib.dat Temp\Output\LINK.DAT
REM ******************************************************************
REM
Call the Mitsubishi librarian
LB308 @Temp\Output\LINK.DAT
REM ******************************************************************
REM
Pause if any problem occurs
IF ERRORLEVEL 1 PAUSE
4.4
C files to include in the project
Generally speaking, you need to include the core C files of emWin, the display driver,
all font files you plan to use and any optional modules you have ordered with emWin:
•
•
•
•
All C files of the folder Config
All C files of the folder GUI\Core
The fonts you plan to use (located in GUI\Font)
Display driver: All C files of the folder GUI\DisplayDriver.
Additional software packages
If you plan to use additional, optional modules you must also include their C files:
•
•
•
•
•
•
•
Gray scale converting functions: all C files located in GUI\ConvertMono
Color conversion functions: all C files located in GUI\ConvertColor
Antialiasing: all C files located in GUI\AntiAlias
Memory devices: all C files located in GUI\MemDev
VNC support: all C files located in GUI\VNC
Widget library: all C files located in GUI\Widget
Window Manager: all C files located in GUI\WM
Target specifics
•
For port/buffer-accessed displays, interface routines must be defined. Examples
of the required routines are available under Samples\LCD_X.
•
Either GUI_X_embOS.c or GUI_X.c has to be included in order to use embOS or
another RTOS for timing and multitasking related functions.
Be sure that you include GUI.h in all of your source files that access emWin.
4.5
Configuring emWin
The Config folder should contain all configuration files. The chapter ’Configuration’
explains in detail how emWin should be configured.
The following types of configuration macros are available:
Binary switches "B"
Switches can have a value of either 0 or 1, where 0 means deactivated and 1 means
activated (actually anything other than 0 would work, but using 1 makes it easier to
read a config file). These switches can enable or disable a certain functionality or
behavior. Switches are the simplest form of configuration macro.
Numerical values "N"
Numerical values are used somewhere in the code in place of a numerical constant.
Typical examples are in the configuration of the resolution of a display.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
36
CHAPTER
Getting Started
Selection switches "S"
Selection switches are used to select one out of multiple options where only one of
those options can be selected. A typical example might be the selection of the type of
display controller used, where the number selected denotes which source code (in
which display driver) is used to generate object code.
Alias "A"
A macro which operates like a simple text substitute. An example would be the define
U8, in which the preprocessor would replace with unsigned char.
Function replacements "F"
Macros can basically be treated like regular functions although certain limitations
apply, as a macro is still put into the code as simple text replacement. Function
replacements are mainly used to add specific functionality to a module (such as the
access to an display) which is highly hardware-dependent. This type of macro is
always declared using brackets (and optional parameters).
4.6
Initializing emWin
The following functions should be used to initialize and ’deinitialize’ emWin in order
to start the configuration process (see chapter “Configuration” on page 905) or clear
internal data from memory again.
Routine
GUI_Init()
GUI_Exit()
Explanation
Initializes emWin internal data structures and variables.
Clears emWin internal data from memory.
GUI_Init()
Description
Initializes emWin internal data structures and variables.
Prototype
int GUI_Init(void);
Return value
0, if successful; another value if the initialization of the display driver fails.
Additional information
Executing this function is mandatory before using any emWin functions. The only
exception is setting create flags for windows (see “WM_SetCreateFlags()” on
page 329). If the window manager is used, the background window is created from
within GUI_Init(). So if create flags are set up before GUI_Init() is called, the background window is created according to them.
GUI_Exit()
Description
Clears emWin internal data from memory to make further calls of GUI_Init() possible.
Prototype
void GUI_Exit(void);
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
37
Additional information
This function should be used if emWin represents a part of the application which is
not used continuosly and therefore has to be able to be turned on and off again.
Please note that after GUI_Exit was called emWin will not work properly until
GUI_Init() is called again.
4.7
Using emWin with target hardware
The following is just a basic outline of the general steps that should be taken when
starting to program with emWin. All steps are explained further in subsequent chapters.
Step 1: Configuring emWin
The first step is usually to customize emWin. For details about the configuration,
refer to the chapter “Configuration” on page 905".
Step 2: Defining access addresses or access routines
For memory-mapped display controllers, the access addresses of the display simply
need to be defined in the configuration file of the display controller. For port/bufferaccessed display controllers, interface routines must be defined. Examples of the
required routines are available under Samples\LCD_X.
Step 3: Compiling, linking and testing the example code
emWin comes with example code for both single- and multitask environments. Compile, link and test these little example programs until you feel comfortable doing so.
Step 4: Modifying the example program
Make simple modifications to the example programs. Add additional commands such
as displaying text in different sizes on the display, showing lines and so on.
Step 5: In multitask applications: adapt to your OS (if necessary)
If multiple tasks should be able to access the display simultaneously, the macros
GUI_MAXTASK and GUI_OS come into play, as well as the file GUITask.c. For details
and example adaptations, refer to the chapter “Configuration” on page 905".
Step 6: Write your own application using emWin
By now you should have a clearer understanding of how to use emWin. Think about
how to structure the program your application requires and use emWin by calling the
appropriate routines. Consult the reference chapters later in this manual, as they discuss the specific emWin functions and configuration macros that are available.
4.8
The "Hello world" example program
In the following we will show the "Hellow world" example program. If you like to see
a wide range of emWin based sample applications as well as further simple tutorial
applications, please have a look in the Sample folder of your emWin shipment or visit
the "emWin Samples" section on www.segger.com.
A "Hello world" program has been used as a starting point for C programming since
the early days, because it is essentially the smallest program that can be written. An
emWin
"Hello
world"
program
is
shown
below
and
is
available
as
BASIC_HelloWorld.c in the Sample\Tutorial folder shipped with emWin.
The whole purpose of the program is to write "Hello world" in the upper left corner of
the display. In order to be able to do this, the hardware of the application, the display controller and the GUI must be initialized first. emWin is initialized by a simple
call of GUI_Init() in the beginning of the program. In this example, we assume that
the hardware of your application is already initialized.
The “Hello world” program looks as follows:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
38
CHAPTER
Getting Started
#include "GUI.h"
void MainTask(void) {
GUI_Init();
GUI_DispString("Hello world!");
while(1);
}
Adding functionality to the "Hello world" program
Our little program has not been doing too much so far. We can now extend the functionality a bit: after displaying "Hello world", we would like the program to start
counting on the display in order to be able to estimate how fast outputs to the display can be made. We can simply add a bit of code to the loop at the end of the main
program, which is essentially a call to the function that displays a value in decimal
form.
The example is available as BASIC_Hello1.c in the Sample folder.
#include "GUI.h"
void MainTask(void) {
int i=0;
GUI_Init();
GUI_DispString("Hello world!");
while(1) {
GUI_DispDecAt( i++, 20,20,4);
if (i > 9999) {
i = 0;
}
}
}
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
39
Chapter 5
Simulation
The PC simulation of emWin allows you to compile the same C source on your Windows PC using a native (typically Microsoft) compiler and create an executable for
your own application. Doing so allows the following:
•
•
•
Design of the user interface on your PC (no need for hardware!).
Debugging of your user interface program.
Creation of demos of your application, which can be used to discuss the user
interface.
The resulting executable can be easily sent via e-mail.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
40
CHAPTER
5.1
Simulation
Using the simulation
The emWin simulation requires Microsoft Visual C++ (version 6.00 or higher) and the
integrated development environment (IDE) which comes with it. You will see a simulation of your LCD on your PC screen, which has the same resolution in X and Y and
can display the exact same colors as your LCD once it has been properly configured.
The entire graphic library API and window manager API of the simulation are identical
to those on your target system; all functions will behave in the very same way as on
the target hardware since the simulation uses the same C source code as the target
system. The difference lies only in the lower level of the software: the LCD driver.
Instead of using the actual LCD driver, the PC simulation uses a simulation driver
which writes into a bitmap. The bitmap is then displayed on your screen using a second thread of the simulation. This second thread is invisible to the application; it
behaves just as if the LCD routines were writing directly to the display.
5.1.1
Using the simulation with the trial version of emWin
The trial version of emWin contains a full library which allows you to evaluate all
available features of emWin. It also includes the emWin viewer (used for debugging
applications), as well as demo versions of the font converter and the bitmap converter. Keep in mind that, being a trial version, you will not be able to view the
source code of emWin or the simulation, but you will still be able to become familiar
with what emWin can do.
5.1.1.1 Directory structure
The directory structure of the simulation in the trial version is
shown at the right side. The table below explains the contents of
the folders:
Directory
Contents
Application
Source of the demo program.
Config
Configuration files used to build the library. Note that
changes at the header files do not have any effect on the
precompiled library!
Exe
Ready-to-use demo program.
GUI
Library files and include files needed to use the library.
Sample
Simulation examples.
Simulation
Files needed for the simulation.
Tool
The emWin viewer, a demo version of the bitmap converter and a demo version of the font converter.
5.1.1.2 Visual C++ workspace
The root directory shown above includes the
Microsoft Visual C++ workspace (SimulationTrial.dsw) and project file (SimulationTrial.dsp).
Double-click
the
workspace file to open the Microsoft IDE.
The directory structure of the Visual C++
workspace will look like the one shown to
the right.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
41
5.1.1.3 Compiling the demo program
The source files for the demo program are located in the Application directory as a
ready-to-go simulation, meaning that you need only to rebuild and start it. Note that
to rebuild the executable, you will need to have Microsoft Visual C++ (version 6.00
or later) installed.
•
•
•
Step 1: Open the Visual C++ workspace by double-clicking on SimulationTrial.dsw.
Step 2: Rebuild the project by choosing Build/Rebuild All from the menu (or
by pressing F7).
Step 3: Start the simulation by choosing Build/Start Debug/Go from the menu
(or by pressing F5).
The demo project will begin to run and may be closed at any time by right-clicking on
it and selecting Exit.
5.1.1.4 Compiling the examples
The Sample directory contains ready-to-go examples that demonstrate different features of emWin and provide examples of some of their typical uses. In order to build
any of these executables, their C source must be ’activated’ in the project. This is
easily done with the following procedure:
•
•
•
•
•
Step 1: Exclude the Application folder from the build process by right-clicking
the Application folder of the workspace and selecting ’Settings\General\Exclude
from build’.
Step 2: Open the Sample folder of the workspace by double-clicking on it. Include
the example which should be used by right-clicking on it and deselecting ’Settings\General\Exclude’ from build.
Step 3: If the example contains its own configuration files (LCDConf.c and/or
SIMConf.c) the default configuration files located in the config folder need to be
excluded from the build process.
Step 4: Rebuild the example by choosing Build/Rebuild All from the menu (or
by pressing F7).
Step 5: Start the simulation by choosing Build/Start Debug/Go from the menu
(or by pressing F5). The result of the example selected above is pictured below:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
42
CHAPTER
5.1.2
Simulation
Using the simulation with the emWin source
5.1.2.1 Directory structure
The root directory of the simulation can be anywhere on your PC, for
example C:\Work\emWinSim. The directory structure will appear as
shown to the right. This structure is very similar to that which we recommend for your target application (see Chapter 3: "Getting Started"
for more information).
The following table shows the contents of the folders:
Directory
Contents
Doc
Contains emWin-Documentation.
Sample
Code examples, described later in this documentation.
Start
All you need to create a new project with emWin
Tool
Tools shipped with emWin
A new project can be started by making a copy of the Startfolder. It contains all required files for a new project. Subdirectories containing the emWin sources are in the Start\GUI folder
and should contain the exact same files as the directories of the
same names which are used for your target (cross) compiler.
The files of the GUI subdirectories should not be changed, as
this would make updating to a newer version of emWin more
difficult.
The Start\Config directory contains configuration files which
need to be modified in order to reflect your target hardware settings (mainly LCD-size and colors which can be displayed).
5.1.2.2 Visual C++ workspace
The root directory shown above includes the
Microsoft Visual C++ workspace (Simulation.dsw)
and project files (Simulation.dsp). The workspace
allows you to modify an application program and
debug it before compiling it on your target system.
The directory structure of the Visual C++ workspace will appear similar to that shown to the right.
Here, the GUI folder is open to display the emWin
subdirectories. Note that your GUI directory may
not look exactly like the one pictured, depending
on which additional features of emWin you have.
The folders Core, Font and LCDDriver are part of
the basic emWin package and will always appear in
the workspace directory.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
43
5.1.2.3 Compiling the application
The simulation contains one or more application C files (located in the Application
directory), which can be modified or removed and additional files can be added to the
project. You should then rebuild the program within the Visual C++ workspace in
order to test/debug it. Once you have reached a point where you are satisfied with
the result and want to use the program in your application, you should be able to
compile these same files on your target system and get the same result on the target
display. The general procedure for using the simulation would be as follows:
•
•
•
•
•
•
•
5.1.3
Step 1: Open the Visual C++ workspace by double-clicking on Simulation.dsw.
Step 2: Compile the project by choosing Build/Rebuild All from the menu (or
by pressing F7).
Step 3: Run the simulation by choosing Build/Start Debug/Go from the menu
(or by pressing F5).
Step 4: Replace the bitmap with your own logo or image.
Step 5: Make further modifications to the application program as you wish, by
editing the source code or adding/deleting files.
Step 6: Compile and run the application program within Visual C++ to test the
results. Continue to modify and debug as needed.
Step 7: Compile and run the application program on your target system.
Advanced features of the simulation
Clicking the right mouse button shows a context
menu with several advanced functions:
5.1.3.1 Pause and Resume
These menu items allows to pause and to resume
the application currently running in the simulation.
The same can be done by pressing <F4> or <F5>.
Trying to pause an already paused application or
trying to resume an already running application
causes an error message.
5.1.3.2 View system info
This menu item opens a further window
with information of the memory currently
used by the application. The window continuously shows the current status of
memory consumption by showing the free
and used bytes and the free and used
number of memory blocks. For details about the memory manager, refer to the chapter “Configuration” on page 905.
5.1.3.3 Copy to clipboard
This menu item copies the current contents of the display into the clipboard. This
makes it easy to use it for documentation purpose with other applications.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
44
CHAPTER
5.2
Simulation
Device simulation
The device simulation supports 3 views:
•
•
•
Generated frame view
Custom bitmap view
Window view
The table below shows the different views:
Generated frame view
Custom bitmap view
Window view
The following will explain in detail how each option can be used.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
45
5.2.1
Generated frame view
The simulation shows the display inside an automatically generated frame surrounding the display. The
frame contains a small button which per default closes
the application. This is the default behavior of the simulation for single layer systems. ’Single layer system’
means that only the first layer is initialized.
5.2.2
Custom bitmap view
The simulation can show the simulated display in a bitmap of your choice, typically
your target device. The bitmap can be used to simulate the behavior of the entire
target device. In order to simulate the appearance of the device, bitmaps are
required.
Device bitmap
The first bitmap is usually a photo (top
view) of the device, and needs to be named
Device.bmp. It may be a separate file (in
the same directory as the executable), or it
may be included as a resource in the application. How to do this is explained later in
this chapter.
The file should provide an area for the simulated display of the same size in pixels as
the physical display resolution.
If there are any hardkeys to be simulated
the bitmap should also show all of them in
unpressed state.
Transparent areas need to be colored with exact the same color as defined with the
function SIM_GUI_SetTransColor(), typically bright red (0xFF0000). These areas do
not have to be rectangular; they can have an arbitrary shape (up to a certain complexity which is limited by your operating system, but is normally sufficient). Bright
red is the default color for transparent areas, mainly because it is not usually contained in most bitmaps. To use a bitmap with bright red, the default transparency
color may be changed with the function SIM_GUI_SetTransColor().
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
46
CHAPTER
Simulation
Hardkey bitmap
The second bitmap file is required for defining the hardkeys and must be named
Device1.bmp. It contains the buttons in
pressed state. The non hardkey area has to
be filled with the transparent color. This is
only a short description. For more details
about how to simulate hardkeys, see “Hardkey simulation” on page 52.
Using separate files
When starting the simulation, it checks if
the directory of the executable contains the
bitmap files Device.bmp and Device1.bmp. If these files are available, they are used
automatically and the resource bitmaps are ignored. Note that this is only valid with
single layer systems.
Adding the bitmap to the application resources
The resource file of the simulation can be found under System\Simulation\Res\Simulation.rc. It contains the following section:
/////////////////////////////////////////////////////////////////////////////
//
// Customizable bitmaps
//
IDB_DEVICE
BITMAP DISCARDABLE
"Device.bmp"
IDB_DEVICE1
BITMAP DISCARDABLE
"Device1.bmp"
This section can be used to set custom device files. For more information, refer to the
Win32 documentation.
5.2.3
Window view
Default for simulating a multiple layer system is showing each layer in a separate
window without using bitmaps or a generated frames.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
47
5.3
Device simulation API
All of the device simulation API functions should be called in the setup phase. The
calls should be done from within the routine SIM_X_Config(), which is located in the
file SIMConf.c in the configuration folder. The example below calls SIM_SetLCDPos()
in the setup:
#include "LCD_SIM.h"
void SIM_X_Config() {
SIM_GUI_SetLCDPos(50, 20); // Define the position of the LCD in the bitmap}
}
The table below lists the available device-simulation-related routines in alphabetical
order. Detailed descriptions of the routines follow:
Routine
Explanation
SIM_GUI_ShowDevice()
Manages the visibility of the device bitmap.
SIM_GUI_SetCallback()
Sets a callback function for receiving the handles of
the simulation windows.
SIM_GUI_SetCompositeColor()
Sets the background color of the composite window.
(Only used with multi layer systems)
SIM_GUI_SetCompositeSize()
Sets the size of the composite window. (Only used with
multi layer systems)
SIM_GUI_SetLCDColorBlack()
Set the color to be used as black (color monochrome
displays).
SIM_GUI_SetLCDColorWhite()
Set the color to be used as white (color monochrome
displays).
SIM_GUI_SetLCDPos()
Set the position for the simulated LCD within the target
device bitmap.
SIM_GUI_SetMag()
Set magnification factors for X and/or Y axis.
SIM_GUI_SetTransColor()
Set the color to be used for transparent areas (default:
0xFF0000).
SIM_GUI_UseCustomBitmaps()
Tells the simulation to use the custom bitmaps from
the application resource file.
SIM_GUI_ShowDevice()
Description
This function can be used to manage the visibility of the surrounding device bitmap
of the simulation.
Prototype
void SIM_GUI_ShowDevice(int OnOff);
Parameter
OnOff
Description
1 for showing the bitmap, 0 for hiding it.
Additional information
On systems with multiple layers the device bitmap is not shown per default and on
single layer systems the bitmap is visible. If a different behavior is required this
function can be used to set up the visibility of the device bitmap.
SIM_GUI_SetCallback()
Description
If it is required to simulate more than the display window or hardkeys, you can set a
callback function to receive the window handles of the simulation. This opens up the
possibility e.g. to add additional controls outside of the display window like leds or
sliders. Please note that the emWin functions can not be used there.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
48
CHAPTER
Simulation
Prototype
void SIM_GUI_SetCallback(int (* _pfInfoCallback)(SIM_GUI_INFO * pInfo));
Parameter
Description
_pfInfoCallback
Pointer to the callback function. The function has to expect a pointer to a
SIM_GUI_INFO structure as a parameter
Content of the SIM_GUI_INFO structure
Type
HWND
Name
Description
hWndMain
Handle to the main window
HWND
ahWndLCD[16]
Array of handles to the display layers
HWND
ahWndColor[16]
Array of handles to the palette layers
SIM_GUI_SetCompositeColor()
Description
When simulating a multiple layer system each layer can be shown in its own window.
However, the physical display has only one area. It shows the result of the blended
layers. The simulation shows the result in the composite window which can have its
own size independent of the layers. Each layer can have its own position and its own
size within the composite window. This means that not necessarily the complete area
is covered by the layers. For this case (and also for transparency effects) this function sets the default background color of the composite window.
Prototype
void SIM_GUI_SetCompositeColor(U32 Color);
Parameter
Color
Description
Background color to be used.
SIM_GUI_SetCompositeSize()
Description
As described above under SIM_GUI_SetCompositeColor() the size of the composite
window is independent of the size of the layers. This function is used to set the size
of the composite window.
Prototype
void SIM_GUI_SetCompositeSize(int xSize, int ySize);
Parameter
xSize
ySize
Description
Horizontal size in pixels.
Vertical size in pixels.
Example
The following shows a typical use (with a multi layer system):
void SIM_X_Config() {
SIM_GUI_SetCompositeSize(240, 320); // Set size of composite window
SIM_GUI_SetCompositeColor(0x800000); // Define background color of composite window
}
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
49
SIM_GUI_SetLCDColorBlack(), SIM_GUI_SetLCDColorWhite()
Description
Set the colors to be used as black or white, respectively, on color monochrome displays.
Prototypes
int SIM_GUI_SetLCDColorBlack(int DisplayIndex, int Color);
int SIM_GUI_SetLCDColorWhite(int DisplayIndex, int Color);
Parameter
DisplayIndex
Color
Description
Reserved for future use; must be 0.
RGB value of the color.
Additional information
These functions can be used to simulate the true background color of your display.
The default color values are black and white, or 0x000000 and 0xFFFFFF.
Example using default settings
void SIM_X_Config() {
SIM_GUI_SetLCDPos(14,84);
SIM_GUI_SetLCDColorBlack (0, 0x000000);
SIM_GUI_SetLCDColorWhite (0, 0xFFFFFF);
(used for colored monochrome displays)
//
//
//
//
Define
in the
Define
Define
the position of the LCD
bitmap
the color used as black
the color used as white
//
//
//
//
Define
in the
Define
Define
the position of the LCD
bitmap
the color used as black
the color used as white
}
Example using yellow instead of white
void SIM_X_Config() {
SIM_GUI_SetLCDPos(14,84);
SIM_GUI_SetLCDColorBlack (0, 0x000000);
SIM_GUI_SetLCDColorWhite (0, 0x00FFFF);
(used for colored monochrome displays)
}
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
50
CHAPTER
Simulation
SIM_GUI_SetLCDPos()
Description
Sets the position for the simulated LCD within the target device bitmap.
Prototype
void SIM_GUI_SetLCDPos(int x, int y);
Parameter
Description
X-position of the upper left corner for the simulated LCD (in pixels).
x
y
Y-position of the upper left corner for the simulated LCD (in pixels).
Additional information
The X- and Y-positions are relative to the target device bitmap, therefore position
(0,0) refers to the upper left corner (origin) of the bitmap and not your actual LCD.
Only the origin of the simulated screen needs to be specified; the resolution of your
display should already be reflected in the configuration files in the Config directory.
The use of this function enables the use of the bitmaps Device.bmp and
Device1.bmp. Note that the values need to be >= 0 for enabling the use of the bitmaps. If the use of the device bitmaps should be disabled, omit the call of this function in SIM_X_Init().
SIM_GUI_SetMag()
Description
Sets magnification factors for X and/or Y axis.
Prototype
void SIM_GUI_SetMag(int MagX, int MagY);
Parameter
MagX
MagY
Description
Magnification factor for X axis.
Magnification factor for Y axis.
Additional information
Per default the simulation uses one pixel on the PC for each pixel of the simulated
display. The use of this function makes sense for small displays. If using a device bitmap together with a magnification > 1 the device bitmap needs to be adapted to the
magnification. The device bitmap is not magnified automatically.
SIM_GUI_SetTransColor()
Description
Sets the color to be used for transparent areas of device or hardkey bitmaps.
Prototype
I32 SIM_GUI_SetTransColor(I32 Color);
Parameter
Color
Description
RGB value of the color in the format 00000000RRRRRRRRGGGGGGGGBBBBBBBB.
Additional information
The default setting for transparency is bright red (0xFF0000).
You would typically only need to change this setting if your bitmap contains the same
shade of red.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
51
SIM_GUI_UseCustomBitmaps()
Description
As described earlier in this chapter it is possible to use device bitmaps from the
application resources. This function tells the simulation to use the device- and hardkey bitmaps from the application resources and not to generate the default frame bitmap.
Prototype
void SIM_GUI_UseCustomBitmaps(void);
Additional information
The emWin shipment contains per default 2 bitmaps, Device.bmp and Device1.bmp,
located in Start\System\Simulation\Res which can be used as a starting point for
your own bitmaps.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
52
5.4
CHAPTER
Simulation
Hardkey simulation
The hardkey simulation can only be used in the custom bitmap view. Hardkeys may
also be simulated as part of the device, and may be selected with the mouse pointer.
The idea is to be able to distinguish whether a key or button on the simulated device
is pressed or unpressed. A hardkey is considered "pressed" as long as the mouse
button is held down; releasing the mouse button or moving the pointer off of the
hardkey "unpresses" the key. A toggle behavior between pressed and unpressed may
also be specified with the routine SIM_HARDKEY_SetMode().
In order to simulate hardkeys, you need a second bitmap of the device which is
transparent except for the keys themselves (in their pressed state). As described
earlier in this chapter, this bitmap can be in a separate file in the directory, or
included as a resource in the executable. Hardkeys may be any shape, as long as
they are exactly the same size in pixels in both Device.bmp and Device1.bmp. The
following example illustrates this:
Device bitmap: unpressed hardkey
state (Device.bmp)
Device hardkey bitmap: pressed
hardkey state (Device1.bmp)
When a key is "pressed" with the mouse, the corresponding section of the hardkey
bitmap (Device1.bmp) will overlay the device bitmap in order to display the key in its
pressed state.
The keys may be polled periodically to determine if their states (pressed/unpressed)
have changed and whether they need to be updated. Alternatively, a callback routine
may be set to trigger a particular action to be carried out when the state of a hardkey
changes.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
53
5.4.1
Hardkey simulation API
The hardkey simulation functions are part of the standard simulation program
shipped with emWin. If using a user defined emWin simulation these functions may
not be available. The table below lists the available hardkey-simulation-related routines in alphabetical order within their respective categories. Detailed descriptions of
the routines follow:
Routine
Explanation
SIM_HARDKEY_GetNum()
Return the number of available hardkeys.
SIM_HARDKEY_GetState()
Return the state of a specified hardkey (0: unpressed,
1: pressed).
SIM_HARDKEY_SetCallback()
Set a callback routine to be executed when the state of
a specified hardkey changes.
SIM_HARDKEY_SetMode()
Set the behavior for a specified hardkey (default = 0:
no toggle).
SIM_HARDKEY_SetState()
Set the state for a specified hardkey (0: unpressed, 1:
pressed).
SIM_HARDKEY_GetNum()
Description
Returns the number of available hardkeys.
Prototype
int SIM_HARDKEY_GetNum(void);
Return value
The number of available hardkeys found in the bitmap.
Additional information
The numbering order for hardkeys is standard reading order (left to right, then top to
bottom). The topmost pixel of a hardkey is therefore found first, regardless of its
horizontal position. In the bitmap below, for example, the hardkeys are labeled as
they would be referenced by the KeyIndex parameter in other functions:
It is recommended to call this function in order to verify that a bitmap is properly
loaded.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
54
CHAPTER
Simulation
SIM_HARDKEY_GetState()
Description
Returns the state of a specified hardkey.
Prototype
int SIM_HARDKEY_GetState(unsigned int KeyIndex);
Parameter
KeyIndex
Description
Index of hardkey (0 = index of first key).
Return value
State of the specified hardkey:
0: unpressed
1: pressed
SIM_HARDKEY_SetCallback()
Description
Sets a callback routine to be executed when the state of a specified hardkey changes.
Prototype
SIM_HARDKEY_CB * SIM_HARDKEY_SetCallback(unsigned int KeyIndex,
SIM_HARDKEY_CB * pfCallback);
Parameter
KeyIndex
pfCallback
Description
Index of hardkey (0 = index of first key).
Pointer to callback routine.
Return value
Pointer to the previous callback routine.
Additional information
Note that multi tasking support has to be enabled if GUI functions need to be called
within the callback functions. Without multi tasking support only the GUI functions
which are allowed to be called within an interrupt routine should be used.
The callback routine must have the following prototype:
Prototype
typedef void SIM_HARDKEY_CB(int KeyIndex, int State);
Parameter
KeyIndex
State
Description
Index of hardkey (0 = index of first key).
State of the specified hardkey (see table below).
Permitted values for parameter State
0
1
User's & reference manual for emWin V5.10
Unpressed.
Pressed.
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
55
SIM_HARDKEY_SetMode()
Description
Sets the behavior for a specified hardkey.
Prototype
int SIM_HARDKEY_SetMode(unsigned int KeyIndex, int Mode);
Parameter
KeyIndex
Mode
Description
Index of hardkey (0 = index of first key).
Behavior mode (see table below).
Permitted values for parameter Mode
0
1
Normal behavior (default).
Toggle behavior.
Additional information
Normal (default) hardkey behavior means that a key is considered pressed only as
long as the mouse button is held down on it. When the mouse is released or moved
off of the hardkey, the key is considered unpressed.
With toggle behavior, each click of the mouse toggles the state of a hardkey to
pressed or unpressed. That means if you click the mouse on a hardkey and it
becomes pressed, it will remain pressed until you click the mouse on it again.
SIM_HARDKEY_SetState()
Description
Sets the state for a specified hardkey.
Prototype
int SIM_HARDKEY_SetState(unsigned int KeyIndex, int State);
Parameter
KeyIndex
State
Description
Index of hardkey (0 = index of first key).
State of the specified hardkey (see table below).
Permitted values for parameter State
0
1
Unpressed.
Pressed.
Additional information
This function is only usable when SIM_HARDKEY_SetMode() is set to 1 (toggle mode).
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
56
CHAPTER
Simulation
5.5 Integrating the emWin simulation into an existing
simulation
In order to integrate the emWin simulation into an existing simulation, the source
code of the simulation is not required. The source code of the simulation is not normally shipped with emWin. It is a separate (optional) software item and is not
included in the emWin basic package.
Normally the source code of the emWin simulation is not needed but available as an
optional software item. As described earlier in this chapter the basic package and the
trial version contains a simulation library. The API functions of this library can be
used if for example the emWin simulation should be added to an existing hardware or
real time kernel (RTOS) simulation.
To add the emWin simulation to an existing simulation (written in C or C++, using
the Win32 API), only a few lines of code need to be added.
5.5.1
Directory structure
The subfolder Simulation of the System folder contains the
emWin simulation. The directory structure is shown on the
right. The table below explains the contents of the subfolders:
Directory
Contents
Simulation
Simulation source and header files to be used with and without the simulation
source code. The folder also contains a ready to use simulation library.
Res
Resource files.
SIM_GUI
GUI simulation source code (optional).
WinMain
Contains the WinMain routine.
5.5.2
Using the simulation library
The following steps will show how to use the simulation library to integrate the
emWin simulation into an existing simulation:
•
•
•
•
Step 1: Add the simulation library GUISim.lib to the project.
Step 2: Add all GUI files to the project as described in the chapter 2.1.1, "Subdirectories".
Step 3: Add the include directories to the project as described in the chapter
2.1.2, "Include Directories".
Step 4: Modify WinMain.
5.5.2.1 Modifying WinMain
Every windows Win32 program starts with WinMain() (contrary to a normal C program from the command line, which starts with main(). All that needs to be done is
to add a few lines of code to this routine.
The following function calls need to be added (normally in the order as it’s shown in
the following application code example):
•
•
•
•
SIM_GUI_Init
SIM_GUI_CreateLCDWindow
CreateThread
SIM_GUI_Exit
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
57
5.5.2.2 Example application
The following application is available under Sample\WinMain\SampleApp.c and shows
how to integrate the emWin simulation into an existing application:
#include <windows.h>
#include "GUI_SIM_Win32.h"
void MainTask(void);
/*********************************************************************
*
*
_Thread
*/
static DWORD __stdcall _Thread(void* Parameter) {
MainTask();
return 0;
}
/*********************************************************************
*
*
_WndProcMain
*/
static LRESULT CALLBACK _WndProcMain(HWND
hWnd,
UINT
message,
WPARAM wParam, LPARAM lParam) {
SIM_GUI_HandleKeyEvents(message, wParam);
switch (message) {
case WM_DESTROY:
PostQuitMessage(0);
break;
}
return DefWindowProc(hWnd, message, wParam, lParam);
}
/*********************************************************************
*
*
_RegisterClass
*/
static void _RegisterClass(HINSTANCE hInstance) {
WNDCLASSEX wcex;
memset(&wcex, 0, sizeof(wcex));
wcex.cbSize
= sizeof(WNDCLASSEX);
wcex.hInstance
= hInstance;
wcex.style
= CS_HREDRAW | CS_VREDRAW;
wcex.lpfnWndProc
= (WNDPROC)_WndProcMain;
wcex.hIcon
= 0;
wcex.hCursor
= LoadCursor(NULL, IDC_ARROW);
wcex.hbrBackground = (HBRUSH)(COLOR_APPWORKSPACE + 1);
wcex.lpszMenuName = 0;
wcex.lpszClassName = "GUIApplication";
RegisterClassEx(&wcex);
}
/*********************************************************************
*
*
WinMain
*/
int APIENTRY WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
LPSTR lpCmdLine, int nCmdShow) {
DWORD ThreadID;
MSG
Msg;
HWND hWndMain;
/* Register window class */
_RegisterClass(hInstance);
/* Create main window
*/
hWndMain = CreateWindow("GUIApplication", "Application window",
WS_OVERLAPPEDWINDOW | WS_CLIPCHILDREN | WS_VISIBLE,
0, 0, 328, 267, NULL, NULL, hInstance, NULL);
/* Initialize the emWin simulation and create a LCD window */
SIM_GUI_Init(hInstance, hWndMain, lpCmdLine, "embOSIAR - emWin Simulation");
SIM_GUI_CreateLCDWindow(hWndMain, 0, 0, 320, 240, 0);
/* Create a thread which executes the code to be simulated */
CreateThread(NULL, 0, (LPTHREAD_START_ROUTINE)_Thread, NULL, 0, &ThreadID);
/* Main message loop */
while (GetMessage(&Msg, NULL, 0, 0)) {
TranslateMessage(&Msg);
DispatchMessage(&Msg);
}
SIM_GUI_Exit();
}
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
58
CHAPTER
5.5.3
Simulation
Integration into the embOS Simulation
5.5.3.1 WinMain
The following code example shows how to modify the existing WinMain of the embOS
simulation in order to integrate the emWin simulation. The red colored lines should
be added to WinMain to initialize the emWin simulation, to create a simulation window and to exit the emWin simulation:
...
#include "GUI_SIM_Win32.h"
...
int APIENTRY WinMain(HINSTANCE hInstance,
HINSTANCE hPrevInstance,
LPSTR lpCmdLine, int nCmdShow) {
MSG
Msg;
HACCEL hAccelTable;
HWND
hWndMain;
BITMAP BmpDevice;
DWORD ThreadID;
/* Init global data */
_StopHyperThreading();
_hInst = hInstance;
/* Register main window class */
_RegisterClass();
/* Load bitmap */
_hBmpDevice = (HBITMAP)LoadImage(_hInst,
(LPCTSTR) IDB_DEVICE,
IMAGE_BITMAP, 0, 0, 0);
_hMenuPopup = LoadMenu(_hInst, (LPCSTR)IDC_CONTEXTMENU);
_hMenuPopup = GetSubMenu(_hMenuPopup, 0);
/* Create main window */
GetObject(_hBmpDevice, sizeof(BmpDevice), &BmpDevice);
hWndMain = CreateWindowEx(WS_EX_TOPMOST, _sWindowClass,
"embOSIAR Simulation",
WS_SYSMENU | WS_CLIPCHILDREN | WS_POPUP | WS_VISIBLE,
10, 20, BmpDevice.bmWidth, BmpDevice.bmHeight,
NULL, NULL, _hInst, NULL);
if (!hWndMain) {
return 1;
/* Error */
}
/* Init emWin simulation and create window */
SIM_GUI_Init(hInstance, hWndMain, lpCmdLine, "embOSIAR - emWin Simulation");
SIM_GUI_CreateLCDWindow(hWndMain, 80, 50, 128, 64, 0);
/* Show main window */
ShowWindow(hWndMain, nCmdShow);
/* Load accelerator table */
hAccelTable = LoadAccelerators(_hInst, (LPCTSTR)IDC_WINMAIN);
/* application initialization: */
CreateThread(NULL, 0, (LPTHREAD_START_ROUTINE)Thread, NULL, 0, &ThreadID);
/* main message loop */
if (SIM_Init(hWndMain) == 0) {
while (GetMessage(&Msg, NULL, 0, 0)) {
if (!TranslateAccelerator(Msg.hwnd, hAccelTable, &Msg)) {
TranslateMessage(&Msg);
DispatchMessage(&Msg);
}
}
}
/* Exit emWin simulation */
SIM_GUI_Exit();
return 0;
}
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
59
5.5.3.2 Target program (main)
The emWin API can be called from one or more target threads. Without RTOS, the
WIN32 API function CreateThread is normally used to create a target thread which
calls the emWin API; within an RTOS simulation, a target task/thread (Created by the
simulated RTOS) is used to call the emWin API. In other words: Use OS_CreateTask
to create a task for the user interface. Below a modified embOS start application:
#include "RTOS.H"
#include "HW_LED.h"
#include "GUI.h"
OS_STACKPTR int Stack0[128], Stack1[128], Stack2[2000]; /* Task stacks */
OS_TASK
TCB0,
TCB1,
TCB2;
/* Task-control-blocks */
void Task0(void) {
while (1) {
HW_LED_Toggle0();
OS_Delay(100);
}
}
void Task1(void) {
while (1) {
HW_LED_Toggle1();
OS_Delay(500);
}
}
void MainTask(void) {
GUI_COLOR aColor[] = {GUI_RED, GUI_YELLOW};
GUI_Init();
while (1) {
int i;
for (i = 0; i < 2; i++) {
GUI_Clear();
GUI_SetColor(aColor[i]);
GUI_SetFont(&GUI_FontComic24B_ASCII);
GUI_DispStringAt("Hello world!", 1, 1);
OS_Delay(200);
}
}
}
/**********************************************************
*
*
main
*/
#include <windows.h>
void main(void) {
OS_IncDI();
/* Initially disable interrupts */
OS_InitKern();
/* initialize OS
*/
OS_InitHW();
/* initialize Hardware for OS
*/
/* You need to create at least one task here !
*/
OS_CREATETASK(&TCB0, "HP Task", Task0,
100, Stack0);
OS_CREATETASK(&TCB1, "LP Task", Task1,
50, Stack1);
OS_CREATETASK(&TCB2, "GUI Task", MainTask, 80, Stack2);
OS_Start();
/* Start multitasking
*/
}
The following table shows the simulation before and after integrating the emWin simulation:
Before
User's & reference manual for emWin V5.10
After
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
60
CHAPTER
5.5.4
Simulation
GUI simulation API
The table below lists the available routines for user defined simulation programs in
alphabetical order within their respective categories. The functions are only available
with the source code of the emWin simulation. Detailed descriptions of the routines
follow:
Routine
SIM_GUI_CreateLCDInfoWindow()
SIM_GUI_CreateLCDWindow()
SIM_GUI_Exit()
SIM_GUI_Init()
SIM_GUI_SetLCDWindowHook()
Explanation
Creates a window which shows the available colors of
the given layer with the given size and position.
Creates a LCD window with the given size and position.
Stops the GUI simulation.
Initializes the GUI simulation.
Sets a hook function to be called if the LCD window
receives a message.
SIM_GUI_CreateLCDInfoWindow()
Description
Creates a window which shows the available colors for the given layer.
Prototype
HWND SIM_GUI_CreateLCDInfoWindow(HWND hParent,
int x, int y, int xSize, int ySize
int LayerIndex);
Parameter
hParent
x
y
Description
Handle of the parent window.
X position in parent coordinates.
Y position in parent coordinates.
xSize
X size in pixel of the new window. Should be 160 if using a color depth between 1 and
8 or 128 if working in high color mode.
ySize
Y size in pixel of the new window. Should be 160 if using a color depth between 1 and
8 or 128 if working in high color mode.
LayerIndex
Index of layer to be shown.
Additional information
The created color window has no frame, no title bar and no buttons.
Example
SIM_GUI_CreateLCDInfoWindow(hWnd, 0, 0, 160, 160, 0);
Screenshot
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
61
SIM_GUI_CreateLCDWindow()
Description
Creates a window which simulates a LCD display with the given size at the given
position.
Prototype
HWND SIM_GUI_CreateLCDWindow(HWND hParent,
int x, int y, int xSize, int ySize
int LayerIndex);
Parameter
hParent
x
y
xSize
ySize
LayerIndex
Description
Handle of the parent window.
X position in parent coordinates.
Y position in parent coordinates.
X size in pixel of the new window.
Y size in pixel of the new window.
Index of layer to be shown.
Additional information
All display output to the given layer will be shown in this window. The size of the window should be the same as configured in LCDConf.c.
The created simulation window has no frame, no title bar and no buttons.
SIM_GUI_Exit()
Description
The function should be called before the simulation returns to the calling process.
Prototype
void SIM_GUI_Exit(void);
SIM_GUI_Init()
Description
This function initializes the emWin simulation and should be called before any other
SIM_GUI... function call.
Prototype
int SIM_GUI_Init(HINSTANCE hInst, HWND hWndMain,
char * pCmdLine, const char * sAppName);
Parameter
hInst
hWndMain
pCmdLine
sAppName
Description
Handle to current instance passed to
WinMain .
Handle of the simulations main window.
Pointer to command line passed to
WinMain
Pointer to a string that contains the application name.
Additional information
The parameters hWndMain and sAppName are used if a message box should be displayed.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
62
CHAPTER
Simulation
SIM_GUI_SetLCDWindowHook()
Description
Sets a hook function to be called from the simulation if the LCD window receives a
message.
Prototype
void SIM_GUI_SetLCDWindowHook(SIM_GUI_tfHook * pfHook);
Parameter
pfHook
Description
Pointer to hook function.
Prototype of hook function
int Hook(HWND hWnd, UINT Message, WPARAM wParam, LPARAM lParam,
int * pResult);
Parameter
hWnd
Message
wParam
lParam
pResult
Description
Handle of LCD window.
Message received from the operating system.
wParam message parameter passed by the system.
lParam message parameter passed by the system.
Pointer to an integer which should be used as return code if the message has been
processed by the hook function.
Return value
The hook function should return 0 if the message has been processed. In this case
the GUI simulation ignores the message.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
63
Chapter 6
Viewer
If you use the simulation when debugging your application, you cannot see the display output when stepping through the source code. The primary purpose of the
viewer is to solve this problem. It shows the contents of the simulated display(s)
while debugging in the simulation.
The viewer gives you the following additional capabilities:
•
•
•
•
Multiple windows for each layer
Watching the whole virtual layer in one window
Magnification of each layer window
Composite view if using multiple layers
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
64
CHAPTER
6.1
Viewer
Using the viewer
The viewer allows you to:
•
Open multiple windows for any
layer/display
•
Zoom in on any area of a layer/
display
•
See the contents of the individual layers/displays as well as
the composite view in multilayer configurations
•
See the contents of the virtual
screen and the visible display
when using the virtual screen
support.
The screenshot shows the viewer
displaying the output of a single
layer configuration. The upper left
corner shows the simulated display.
In the upper right corner is a window, which shows the available colors of the display configuration. At
the bottom of the viewer a second
display window shows a magnified
area of the simulated display. If you
start to debug your application, the
viewer shows one display window per layer and one color window per layer. In a multi
layer configuration, a composite view window will also be visible.
6.1.1
Using the simulation and the viewer
If you use the simulation when debugging your application, you cannot see the display output when stepping through the source code. This is due to a limitation of
Win32: If one thread (the one being debugged) is halted, all other threads of the
process are also halted. This includes the thread which outputs the simulated display
on the screen.
The emWin viewer solves this problem by showing the display window and the color
window of your simulation in a separate process. It is your choice if you want to start
the viewer before debugging your application or while you are debugging. Our suggestion:
•
•
•
•
Step 1: Start the viewer. No display- or color window is shown until the simulation has been started.
Step 2: Open the Visual C++ workspace.
Step 3: Compile and run the application program.
Step 4: Debug the application as described previously.
The advantage is that you can now follow all drawing operations step by step in the
LCD window.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
65
6.1.2
Using the viewer with virtual pages
By default the viewer opens one window per layer which shows the visible part of the
video RAM, normally the display. If the configured virtual video RAM is larger than
the display, the command View/Virtual Layer/Layer (0...4) can be used to show
the whole video RAM in one window. When using the function GUI_SetOrg(), the contents of the visible screen will change, but the virtual layer window remains
unchanged:
Page 0
Visible screen
always
"Main screen"
Page 1
always
"Setup" screen
Page 2
used for different screens
For more information about virtual screens, refer to chapter “Virtual screen / Virtual
pages” on page 739.
6.1.3
Always on top
Per default the viewer window is always on top. You can change this behavior by
selecting Options\Always on top from the menu.
6.1.4
Open further windows of the display output
If you want to show a magnified area of the LCD output or the composite view of a
multi layer configuration it could be useful to open more than one output window.
You can do this by View/Visible Layer/Layer (1...4), View/Virtual Layer/
Layer (1...4) or View/Composite.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
66
CHAPTER
6.1.5
Viewer
Zooming
Zooming in or out is easy:
Right-click on a layer or composite window opens the Zoom popup menu.
Choose one of the zoom options:
Using the grid
If you magnify the LCD output >= 300%, you have the choice between showing the
output with or without a grid. It is possible to change the color of the grid. This can
be done choosing the Menu point Options/Grid color.
Adapting the size of the window
If you want to adapt the size of the window to the magnification choose Fit window
to size from the first popup menu.
6.1.6
Copy the output to the clipboard
Click onto a LCD window or a composite view with the right mouse key and choose
Copy to clipboard. Now you can paste the contents of the clipboard for example
into the mspaint application.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
67
6.1.7
Using the viewer with multiple displays
If you are working with multiple displays you should set the viewer into ’Multi display
mode’ by using the command Options/Multi layer/display.
When starting the debugger the viewer will open one display window and one color
window for each display:
6.1.8
Using the viewer with multiple layers
If you are working with multiple layers you should set the viewer into ’Multi layer
mode’ by using the command Options/Multi layer/display.
When starting the debugger the viewer will open one LCD window and one color window for each layer and one composite window for the result.
Example
The example below shows a screenshot of the viewer with 2 layers. Layer 0 shows
color bars with a high color configuration. Layer 1 shows a transparent circle on a
white background with colored rectangles. The composite window shows the result
which is actually visible on the display
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
68
CHAPTER
Viewer
Transparency
The composite window of the viewer shows all layers; layers with higher index are on
top of layers with lower index and can have transparent pixels:
Layer 0
Layer 1
No transparency
...
Layer n
Pixels can be transparent
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
69
Chapter 7
Displaying Text
It is very easy to display text with emWin. Knowledge of only a few routines already
allows you to write any text, in any available font, at any point on the display. We
first provide a short introduction to displaying text, followed by more detailed explanations of the individual routines that are available.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
70
CHAPTER
7.1
Displaying Text
Basic routines
In order to display text on the LCD, simply call the routine GUI_DispString() with
the text you want to display as parameters. For example:
GUI_DispString("Hello world!");
The above code will display the text "Hello world" at the current text position. However, as you will see, there are routines to display text in a different font or in a certain position. In addition, it is possible to write not only strings but also decimal,
hexadecimal and binary values to the display. Even though the graphic displays are
usually byte-oriented, the text can be positioned at any pixel of the display, not only
at byte positions.
Control characters
Control characters are characters with a character code of less than 32. The control
characters are defined as part of ASCII. emWin ignores all control characters except
for the following:
Char.
Code
ASCII
code
C
Description
10
LF
\n
Line feed.
The current text position is changed to the beginning of the next line. Per
default, this is: X = 0.
Y + =font-distance in pixels (as delivered by GUI_GetFontDistY() ).
13
CR
\r
Carriage return.
The current text position is changed to the beginning of the current line. Per
default, this is: X = 0.
Usage of the control character LF can be very convenient in strings. A line feed can
be made part of a string so that a string spanning multiple lines can be displayed
with a single routine call.
Positioning text at a selected position
This may be done by using the routine GUI_GotoXY() as shown in the following
example:
GUI_GotoXY(10,10);// Set text position (in pixels)
GUI_DispString("Hello world!");// Show text
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
71
7.2
Text API
The table below lists the available text-related routines in alphabetical order within
their respective categories. Detailed descriptions of the routines can be found in the
sections that follow.
Routine
Explanation
Routines to display text
GUI_DispChar()
GUI_DispCharAt()
GUI_DispChars()
GUI_DispNextLine()
GUI_DispString()
GUI_DispStringAt()
GUI_DispStringAtCEOL()
GUI_DispStringHCenterAt()
GUI_DispStringInRect()
GUI_DispStringInRectEx()
GUI_DispStringInRectWrap()
Displays single character at current position.
Displays single character at specified position.
Displays character a specified number of times.
Moves the cursor to the beginning of the next line.
Displays string at current position.
Displays string at specified position.
Displays string at specified position, then clear to end of line.
Displays string centered horizontally at the given position.
Displays string in specified rectangle.
Displays string in specified rectangle and optionally rotates it.
Displays string in specified rectangle with optional wrapping.
GUI_DispStringLen()
Display string at current position with specified number of characters.
GUI_WrapGetNumLines()
Get the number of text lines for the given wrap mode.
Selecting text drawing modes
GUI_GetTextMode()
GUI_SetTextMode()
GUI_SetTextStyle()
Returns the current text mode
GUI_GetTextAlign()
GUI_SetLBorder()
GUI_SetTextAlign()
Return current text alignment mode.
Sets text drawing mode.
Sets the text style to be used.
Selecting text alignment
Set left border after line feed.
Set text alignment mode.
Setting the current text position
Set current X-position.
GUI_GotoX()
GUI_GotoXY()
GUI_GotoY()
Set current (X,Y) position.
Set current Y-position.
Retrieving the current text position
Return current X-position.
GUI_GetDispPosX()
GUI_GetDispPosY()
Return current Y-position.
Routines to clear a window or parts of it
GUI_Clear()
Clear active window (or entire display if background is the active
window).
GUI_DispCEOL()
Clear display from current text position to end of line.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
72
CHAPTER
7.3
Displaying Text
Routines to display text
GUI_DispChar()
Description
Displays a single character at the current text position in the current window using
the current font.
Prototype
void GUI_DispChar(U16 c);
Parameter
Description
Character to display.
c
Additional information
This is the basic routine for displaying a single character. All other display routines
(GUI_DispCharAt(), GUI_DispString(), etc.) call this routine to output the individual characters.
Which characters are available depends on the selected font. If the character is not
available in the current font, nothing is displayed.
Example
Shows a capital A on the display:
GUI_DispChar('A');
Related topics
GUI_DispChars(), GUI_DispCharAt()
GUI_DispCharAt()
Description
Displays a single character at a specified position in the current window using the
current font.
Prototype
void GUI_DispCharAt(U16 c, I16P x, I16P y);
Parameter
c
x
y
Description
Character to display.
X-position to write to in pixels of the client window.
Y-position to write to in pixels of the client window.
Add information
Displays the character with its upper left corner at the specified (X,Y) position.
Writes the character using the routine GUI_DispChar().
If the character is not available in the current font, nothing is displayed.
Example
Shows a capital A on the display in the upper left corner:
GUI_DispCharAt('A',0,0);
Related topics
GUI_DispChar(), GUI_DispChars()
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
73
GUI_DispChars()
Description
Displays a character a specified number of times at the current text position in the
current window using the current font.
Prototype
void GUI_DispChars(U16 c, int Cnt);
Parameter
Description
Character to display.
c
Cnt
Number of repetitions (0 <= Cnt <= 32767).
Additional information
Writes the character using the routine GUI_DispChar().
If the character is not available in the current font, nothing is displayed.
Example
Shows the line "******************************" on the display:
GUI_DispChars('*', 30);
Related topics
GUI_DispChar(), GUI_DispCharAt()
GUI_DispNextLine()
Description
Moves the cursor to the beginning of the next line.
Prototype
void GUI_DispNextLine(void);
Related topics
GUI_SetLBorder()
GUI_DispString()
Description
Displays the string passed as parameter at the current text position in the current
window using the current font.
Prototype
void GUI_DispString(const char GUI_FAR * s);
Parameter
s
Description
String to display.
Additional information
The string can contain the control character \n. This control character moves the current text position to the beginning of the next line.
Example
Shows "Hello world" on the display and "Next line" on the next line:
GUI_DispString("Hello world");
GUI_DispString("\nNext line");
//Disp text
//Disp text
Related topics
GUI_DispStringAt(), GUI_DispStringAtCEOL(), GUI_DispStringLen()
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
74
CHAPTER
Displaying Text
GUI_DispStringAt()
Description
Displays the string passed as parameter at a specified position in the current window
using the current font.
Prototype
void GUI_DispStringAt(const char GUI_FAR * s, int x, int y);
Parameter
s
x
y
Description
String to display.
X-position to write to in pixels of the client window.
Y-position to write to in pixels of the client window.
Example
Shows "Position 50,20" at position 50,20 on the display:
GUI_DispStringAt("Position 50,20", 50, 20);
// Disp text
Related topics
GUI_DispString(), GUI_DispStringAtCEOL(), GUI_DispStringLen(),
GUI_DispStringAtCEOL()
Description
This routine uses the exact same parameters as GUI_DispStringAt(). It does the
same thing: displays a given string at a specified position. However, after doing so, it
clears the remaining part of the line to the end by calling the routine
GUI_DispCEOL(). This routine can be handy if one string is to overwrite another, and
the overwriting string is or may be shorter than the previous one.
GUI_DispStringHCenterAt()
Description
Displays the string passed as parameter horizontally centered at a specified position
in the current window using the current font.
Prototype
void GUI_DispStringHCenterAt(const char GUI_FAR * s, int x, int y);
Parameter
s
x
y
Description
String to display.
X-position to write to in pixels of the client window.
Y-position to write to in pixels of the client window.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
75
GUI_DispStringInRect()
Description
Displays the string passed as parameter at a specified position within a specified
rectangle, in the current window using the current font.
Prototype
void GUI_DispStringInRect(const char GUI_FAR * s,
GUI_RECT *
pRect,
int
Align);
Parameter
s
pRect
Align
Description
String to display.
Rectangle to write to in pixels of the client window.
Alignment flags; "OR " combinable. A flag for horizontal and a flag for vertical alignment
should be combined. Available flags are:
GUI_TA_TOP, GUI_TA_BOTTOM, GUI_TA_VCENTER for vertical alignment.
GUI_TA_LEFT, GUI_TA_RIGHT, GUI_TA_HCENTER for horizontal alignment.
Example
Shows the word "Text" centered horizontally and vertically in the current window:
GUI_RECT rClient;
GUI_GetClientRect(&rClient);
GUI_DispStringInRect("Text", &rClient, GUI_TA_HCENTER | GUI_TA_VCENTER);
Additional information
If the specified rectangle is too small, the text will be clipped.
Related topics
GUI_DispString(), GUI_DispStringAtCEOL(), GUI_DispStringLen(),
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
76
CHAPTER
Displaying Text
GUI_DispStringInRectEx()
Description
Displays the string passed as parameter at a specified position within a specified
rectangle, in the current window using the current font and (optionally) rotates it.
Prototype
void GUI_DispStringInRectEx(const char *
GUI_RECT *
int
int
const GUI_ROTATION *
Parameter
s
pRect
TextAlign
MaxLen
pLCD_Api
s,
pRect,
TextAlign,
MaxLen,
pLCD_Api);
Description
String to display.
Rectangle to write to in pixels of the client window.
Alignment flags; " OR " combinable. A flag for horizontal and a flag for vertical alignment should be combined. Available flags are:
GUI_TA_TOP, GUI_TA_BOTTOM, GUI_TA_VCENTER for vertical alignment.
GUI_TA_LEFT, GUI_TA_RIGHT, GUI_TA_HCENTER for horizontal alignment.
Maximum number of characters to be shown.
(see table below)
Permitted values for parameter pLCD_Api
GUI_ROTATE_0
GUI_ROTATE_180
GUI_ROTATE_CCW
GUI_ROTATE_CW
Does not rotate the text. Shows it from left to right.
Rotates the text by 180 degrees.
Rotates the text counter clockwise.
Rotates the text clockwise.
Example
Shows the word "Text" centered horizontally and vertically in the given rectangle:
GUI_RECT Rect = {10, 10, 40, 80};
char acText[] = "Rotated\ntext";
GUI_SetTextMode(GUI_TM_XOR);
GUI_FillRectEx(&Rect);
GUI_DispStringInRectEx(acText,
&Rect,
GUI_TA_HCENTER | GUI_TA_VCENTER,
strlen(acText),
GUI_ROTATE_CCW);
Screenshot of above example
Additional information
If the specified rectangle is too small, the text will be clipped.
To make the function available the configuration switch GUI_SUPPORT_ROTATION must
be activated (default).
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
77
GUI_DispStringInRectWrap()
Description
Displays a string at a specified position within a specified rectangle, in the current
window using the current font and (optionally) wraps the text.
Prototype
void GUI_DispStringInRectWrap(const char GUI_UNI_PTR * s,
GUI_RECT *
pRect,
int
TextAlign,
GUI_WRAPMODE
WrapMode);
Parameter
s
pRect
Description
String to display.
Rectangle to write to in pixels of the client window.
TextAlign
Alignment flags; " OR " combinable. A flag for horizontal and a flag for vertical alignment should be combined. Available flags are:
GUI_TA_TOP, GUI_TA_BOTTOM, GUI_TA_VCENTER for vertical alignment.
GUI_TA_LEFT, GUI_TA_RIGHT, GUI_TA_HCENTER for horizontal alignment.
WrapMode
(see table below)
Permitted values for parameter WrapMode
GUI_WRAPMODE_NONE
GUI_WRAPMODE_WORD
GUI_WRAPMODE_CHAR
No wrapping will be performed.
Text is wrapped word wise.
Text is wrapped char wise.
Additional information
If word wrapping should be performed and the given rectangle is too small for a word
char wrapping is executed at this word.
Example
Shows a text centered horizontally and vertically in the given rectangle with word
wrapping:
int i;
char acText[]
= "This example demonstrates text wrapping";
GUI_RECT Rect
= {10, 10, 59, 59};
GUI_WRAPMODE aWm[] = {GUI_WRAPMODE_NONE,
GUI_WRAPMODE_CHAR,
GUI_WRAPMODE_WORD};
GUI_SetTextMode(GUI_TM_TRANS);
for (i = 0; i < 3; i++) {
GUI_SetColor(GUI_BLUE);
GUI_FillRectEx(&Rect);
GUI_SetColor(GUI_WHITE);
GUI_DispStringInRectWrap(acText, &Rect, GUI_TA_LEFT, aWm[i]);
Rect.x0 += 60;
Rect.x1 += 60;
}
Screenshot of above example
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
78
CHAPTER
Displaying Text
GUI_DispStringLen()
Description
Displays the string passed as parameter with a specified number of characters at the
current text position, in the current window using the current font.
Prototype
void GUI_DispStringLen(const char GUI_FAR * s, int Len);
Parameter
Description
s
String to display. Should be a \0 terminated array of 8-bit character. Passing NULL as
parameter is permitted.
Len
Number of characters to display.
Additional information
If the string has less characters than specified (is shorter), it is padded with spaces.
If the string has more characters than specified (is longer), then only the given number of characters is actually displayed.
This function is especially useful if text messages can be displayed in different languages (and will naturally differ in length), but only a certain number of characters
can be displayed.
Related topics
GUI_DispString(), GUI_DispStringAt(), GUI_DispStringAtCEOL(),
GUI_WrapGetNumLines()
Description
Returns the number of lines used to show the given text with the given wrap mode.
Prototype
int GUI_WrapGetNumLines(const char GUI_UNI_PTR * pText,
int
xSize,
GUI_WRAPMODE
WrapMode);
Parameter
pText
xSize
WrapMode
Description
String to display. Should be a \0 terminated array of 8-bit character. Passing NULL as
parameter is permitted.
X-size to be used to draw the text.
(see table below)
Permitted values for parameter WrapMode
GUI_WRAPMODE_NONE
GUI_WRAPMODE_WORD
GUI_WRAPMODE_CHAR
No wrapping will be performed.
Text is wrapped word wise.
Text is wrapped char wise.
Additional information
Please remember that the number of lines required to draw text depends on the currently selected font.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
79
7.4
Selecting text drawing modes
Normally, text is written into the selected window at the current text position using
the selected font in normal text. Normal text means that the text overwrites whatever is already displayed where the bits set in the character mask are set on the display. In this mode, active bits are written using the foreground color, while inactive
bits are written with the background color. However, in some situations it may be
desirable to change this default behavior. emWin offers four flags for this purpose
(one default plus three modifiers), which may be combined:
Normal text
Text can be displayed normally by specifying GUI_TEXTMODE_NORMAL or 0.
Reverse text
Text can be displayed reverse by specifying GUI_TEXTMODE_REV. What is usually displayed as white on black will be displayed as black on white.
Transparent text
Text can be displayed transparently by specifying GUI_TEXTMODE_TRANS. Transparent
text means that the text is written on top of whatever is already visible on the display. The difference is that whatever was previously on the screen can still be seen,
whereas with normal text the background is replaced with the currently selected
background color.
XOR text
Text can be displayed using the XOR mode by specifying GUI_TEXTMODE_XOR. What
usually is drawn white (the actual character) is inverted. The effect is identical to
that of the default mode (normal text) if the background is black. If the background
is white, the output is identical to reverse text. If you use colors, an inverted pixel is
calculated as follows:
New pixel color = number of colors - actual pixel color - 1.
Transparent reversed text
Text can be displayed in reverse transparently by specifying GUI_TEXTMODE_TRANS |
GUI_TEXTMODE_REV. As with transparent text, it does not overwrite the background,
and as with reverse text, the text is displayed in reverse.
Additional information
Please note that you can also use the abbreviated form: e.g. GUI_TM_NORMAL
Example
Displays normal, reverse, transparent, XOR, and transparent reversed text:
GUI_SetFont(&GUI_Font8x16);
GUI_SetBkColor(GUI_BLUE);
GUI_Clear();
GUI_SetPenSize(10);
GUI_SetColor(GUI_RED);
GUI_DrawLine(80, 10, 240, 90);
GUI_DrawLine(80, 90, 240, 10);
GUI_SetBkColor(GUI_BLACK);
GUI_SetColor(GUI_WHITE);
GUI_SetTextMode(GUI_TM_NORMAL);
GUI_DispStringHCenterAt("GUI_TM_NORMAL"
,
GUI_SetTextMode(GUI_TM_REV);
GUI_DispStringHCenterAt("GUI_TM_REV"
,
GUI_SetTextMode(GUI_TM_TRANS);
GUI_DispStringHCenterAt("GUI_TM_TRANS"
,
GUI_SetTextMode(GUI_TM_XOR);
GUI_DispStringHCenterAt("GUI_TM_XOR"
,
GUI_SetTextMode(GUI_TM_TRANS | GUI_TM_REV);
GUI_DispStringHCenterAt("GUI_TM_TRANS | GUI_TM_REV",
User's & reference manual for emWin V5.10
160, 10);
160, 26);
160, 42);
160, 58);
160, 74);
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
80
CHAPTER
Displaying Text
Screen shot of above example
GUI_GetTextMode()
Description
Returns the currently selected text mode.
Prototype
int GUI_GetTextMode(void);
Return value
The currently selected text mode.
GUI_SetTextMode()
Description
Sets the text mode to the parameter specified.
Prototype
int GUI_SetTextMode(int TextMode);
Parameter
TextMode
Description
Text mode to set. May be any combination of the TEXTMODE flags.
Permitted values for parameter TextMode (OR-combinable)
GUI_TEXTMODE_NORMAL
GUI_TEXTMODE_REV
GUI_TEXTMODE_TRANS
GUI_TEXTMODE_XOR
Causes text to be displayed normally. This is the
default setting; the value is identical to 0.
Causes text to be displayed reverse.
Causes text to be displayed transparent.
Causes text to invert the background.
Return value
The previous selected text mode.
Example
Shows "The value is" at position 0,0 on the display, shows a value in reverse text,
then sets the text mode back to normal:
int i = 20;
GUI_DispStringAt("The value is", 0, 0);
GUI_SetTextMode(GUI_TEXTMODE_REV);
GUI_DispDec(20, 3);
GUI_SetTextMode(GUI_TEXTMODE_NORMAL);
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
81
GUI_SetTextStyle()
Description
Sets the text style to the parameter specified.
Prototype
char GUI_SetTextStyle(char Style);
Parameter
Style
Description
Text style to set (see table below).
Permitted values for parameter Style
Renders text normal (default).
GUI_TS_NORMAL
GUI_TS_UNDERLINE
GUI_TS_STRIKETHRU
GUI_TS_OVERLINE
Renders text underlined.
Renders text in strike through type.
Renders text in overline type.
Return value
The previous selected text style.
7.5
Selecting text alignment
GUI_GetTextAlign()
Description
Returns the current text alignment mode.
Prototype
int GUI_GetTextAlign(void);
GUI_SetLBorder()
Description
Sets the left border for line feeds in the current window.
Prototype
void GUI_SetLBorder(int x)
Parameter
x
Description
New left border (in pixels, 0 is left border).
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
82
CHAPTER
Displaying Text
GUI_SetTextAlign()
Description
Sets the text alignment mode for string output in the current window.
Prototype
int GUI_SetTextAlign(int TextAlign);
Parameter
TextAlign
Description
Text alignment mode to set. May be a combination of a horizontal and a vertical
alignment flag.
Permitted values for parameter TextAlign
(horizontal and vertical flags are OR-combinable)
Horizontal alignment
GUI_TA_LEFT
GUI_TA_HCENTER
GUI_TA_RIGHT
Align X-position left (default).
GUI_TA_TOP
GUI_TA_VCENTER
GUI_TA_BOTTOM
Align Y-position with top of characters (default).
Center X-position.
Align X-position right.
Vertical alignment
Center Y-position.
Align Y-position with bottom pixel line of font.
Return value
The selected text alignment mode.
Additional information
GUI_SetTextAllign() does not affect the character output routines beginning with
GUI_DispChar(). Note that the settings made with this function are valid only for
one string.
Example
Displays the value 1234 with the center of the text at x=100, y=100:
GUI_SetTextAlign(GUI_TA_HCENTER | GUI_TA_VCENTER);
GUI_DispDecAt(1234,100,100,4);
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
83
7.6
Setting the current text position
Every task has a current text position. This is the position relative to the origin of the
window (usually (0,0)) where the next character will be written if a text output routine is called. Initially, this position is (0,0), which is the upper left corner of the current window. There are 3 functions which can be used to set the current text
position.
GUI_GotoXY(), GUI_GotoX(), GUI_GotoY()
Description
Set the current text write position.
Prototypes
char GUI_GotoXY(int x, int y);
char GUI_GotoX(int x);
char GUI_GotoY(int y);
Parameter
x
y
Description
New X-position (in pixels, 0 is left border).
New Y-position (in pixels, 0 is top border).
Return value
Usually 0.
If a value != 0 is returned, then the current text position is outside of the window (to
the right or below), so a following write operation can be omitted.
Additional information
GUI_GotoXY() sets both the X- and Y-components of the current text position.
GUI_GotoX() sets the X-component of the current text position; the Y-component
remains unchanged.
GUI_GotoY() sets the Y-component of the current text position; the X-component
remains unchanged.
Example
Shows "(20,20)" at position 20,20 on the display:
GUI_GotoXY(20,20)
GUI_DispString("The value is");
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
84
7.7
CHAPTER
Displaying Text
Retrieving the current text position
GUI_GetDispPosX()
Description
Returns the current X-position.
Prototype
int GUI_GetDispPosX(void);
GUI_GetDispPosY()
Description
Returns the current Y-position.
Prototype
int GUI_GetDispPosY(void);
7.8
Routines to clear a window or parts of it
GUI_Clear()
Description
Clears the current window.
Prototype
void GUI_Clear(void);
Additional information
If no window has been defined, the current window is the entire display. In this case,
the entire display is cleared.
Example
Shows "Hello world" on the display, waits 1 second and then clears the display:
GUI_DispStringAt("Hello world", 0, 0); // Disp text
GUI_Delay(1000);
// Wait 1 second (not part of emWin)
GUI_Clear();
// Clear screen
GUI_DispCEOL()
Description
Clears the current window (or the display) from the current text position to the end
of the line using the height of the current font.
Prototype
void GUI_DispCEOL(void);
Example
Shows "Hello world" on the display, waits 1 second and then displays "Hi" in the same
place, replacing the old string:
GUI_DispStringAt("Hello world", 0, 0);// Disp text
Delay (1000);
GUI_DispStringAt("Hi", 0, 0);
GUI_DispCEOL();
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
85
Chapter 8
Displaying Values
The preceding chapter explained how to show strings on the display. Of course you
may use strings and the functions of the standard C library to display values. However, this can sometimes be a difficult task. It is usually much easier (and much more
efficient) to call a routine that displays the value in the form that you want. emWin
supports different decimal, hexadecimal and binary outputs. The individual routines
are explained in this chapter.
All functions work without the usage of a floating-point library and are optimized for
both speed and size. Of course sprintf may also be used on any system. Using the
routines in this chapter can sometimes simplify things and save both ROM space and
execution time.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
86
8.1
CHAPTER
Displaying Values
Value API
The table below lists the available value-related routines in alphabetical order within
their respective categories. Detailed descriptions of the routines can be found in the
sections that follow.
Routine
Explanation
Displaying decimal values
GUI_DispDec()
Display value in decimal form at current position with specified number
of characters.
GUI_DispDecAt()
Display value in decimal form at specified position with specified number of characters.
GUI_DispDecMin()
Display value in decimal form at current position with minimum number
of characters.
GUI_DispDecShift()
Display long value in decimal form with decimal point at current position with specified number of characters.
GUI_DispDecSpace()
Display value in decimal form at current position with specified number
of characters, replace leading zeros with spaces.
GUI_DispSDec()
Display value in decimal form at current position with specified number
of characters and sign.
GUI_DispSDecShift()
Display long value in decimal form with decimal point at current position with specified number of characters and sign.
GUI_DispFloat()
Display floating-point value with specified number of characters.
GUI_DispFloatFix()
Display floating-point value with fixed no. of digits to the right of decimal point.
GUI_DispFloatMin()
Display floating-point value with minimum number of characters.
GUI_DispSFloatFix()
Display floating-point value with fixed no. of digits to the right of decimal point and sign.
GUI_DispSFloatMin()
Display floating-point value with minimum number of characters and
sign.
Displaying floating-point values
Displaying binary values
GUI_DispBin()
GUI_DispBinAt()
Display value in binary form at current position.
Display value in binary form at specified position.
Displaying hexadecimal values
GUI_DispHex()
GUI_DispHexAt()
Display value in hexadecimal form at current position.
Display value in hexadecimal form at specified position.
Version of emWin
GUI_GetVersionString() Return the current version of emWin.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
87
8.2
Displaying decimal values
GUI_DispDec()
Description
Displays a value in decimal form with a specified number of characters at the current
text position, in the current window using the current font.
Prototype
void GUI_DispDec(I32 v, U8 Len);
Parameter
Description
v
Value to display.
Minimum -2147483648 (= -2^31).
Maximum 2147483647 (= 2^31 -1).
Len
No. of digits to display (max. 10).
Additional information
Leading zeros are not suppressed (are shown as 0).
If the value is negative, a minus sign is shown.
Example
// Display time as minutes and seconds
GUI_DispString("Min:");
GUI_DispDec(Min,2);
GUI_DispString(" Sec:");
GUI_DispDec(Sec,2);
Related topics
GUI_DispSDec(), GUI_DispDecAt(), GUI_DispDecMin(), GUI_DispDecSpace()
GUI_DispDecAt()
Description
Displays a value in decimal form with a specified number of characters at a specified
position, in the current window using the current font.
Prototype
void GUI_DispDecAt(I32 v, I16P x, I16P y, U8 Len);
Parameter
v
x
y
Len
Description
Value to display.
Minimum -2147483648 (= -2^31).
Maximum 2147483647 (= 2^31 -1).
X-position to write to in pixels of the client window.
Y-position to write to in pixels of the client window.
No. of digits to display (max. 10).
Additional information
Leading zeros are not suppressed.
If the value is negative, a minus sign is shown.
Example
// Update seconds in upper right corner
GUI_DispDecAT(Sec, 200, 0, 2);
Related topics
GUI_DispDec(), GUI_DispSDec(), GUI_DispDecMin(), GUI_DispDecSpace()
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
88
CHAPTER
Displaying Values
GUI_DispDecMin()
Description
Displays a value in decimal form at the current text position in the current window
using the current font. The length of the value does not require to be specified. The
minimum length will automatically be used.
Prototype
void GUI_DispDecMin(I32 v);
Parameter
Description
Value to display.
Minimum: -2147483648 (= -2^31); maximum 2147483647 (= 2^31 -1).
v
Additional information
The maximum number of displayed digits is 10. This function should not be used if
values have to be aligned but differ in the number of digits. Try one of the functions
which require specification of the number of digits to use in this case.
Example
// Show result
GUI_DispString("The result is :");
GUI_DispDecMin(Result);
Related topics
GUI_DispDec(), GUI_DispDecAt(), GUI_DispSDec(), GUI_DispDecSpace()
GUI_DispDecShift()
Description
Displays a long value in decimal form with a specified number of characters and with
decimal point at the current text position, in the current window using the current
font.
Prototype
void GUI_DispDecShift(I32 v, U8 Len, U8 Shift);
Parameter
v
Len
Shift
Description
Value to display.
Minimum: -2147483648 (= -2^31); maximum: 2147483647 (= 2^31 -1).
No. of digits to display (max. 10).
No. of digits to show to right of decimal point.
Additional information
Watch the maximum number of 9 characters (including sign and decimal point).
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
89
GUI_DispDecSpace()
Description
Displays a value in decimal form at the current text position in the current window
using the current font. Leading zeros are suppressed (replaced by spaces).
Prototype
void DispDecSpace(I32 v, U8 MaxDigits);
Parameter
Description
v
Value to display.
Minimum: -2147483648 (= -2^31); maximum: 2147483647 (= 2^31 -1).
MaxDigits
No. of digits to display, including leading spaces.
Maximum no. of digits displayed is 10 (excluding leading spaces).
Additional information
If values have to be aligned but differ in the number of digits, this function is a good
choice.
Example
// Show result
GUI_DispString("The result is :");
GUI_DispDecSpace(Result, 200);
Related topics
GUI_DispDec(), GUI_DispDecAt(), GUI_DispSDec(), GUI_DispDecMin()
GUI_DispSDec()
Description
Displays a value in decimal form (with sign) with a specified number of characters at
the current text position, in the current window using the current font.
Prototype
void GUI_DispSDec(I32 v, U8 Len);
Parameter
Description
v
Value to display.
Minimum: -2147483648 (= -2^31); maximum: 2147483647 (= 2^31 -1).
Len
No. of digits to display (max. 10).
Additional information
Leading zeros are not suppressed.
This function is similar to GUI_DispDec, but a sign is always shown in front of the
value, even if the value is positive.
Related topics
GUI_DispDec(), GUI_DispDecAt(), GUI_DispDecMin(), GUI_DispDecSpace()
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
90
CHAPTER
Displaying Values
GUI_DispSDecShift()
Description
Displays a long value in decimal form (with sign) with a specified number of characters and with decimal point at the current text position, in the current window using
the current font.
Prototype
void GUI_DispSDecShift(I32 v, U8 Len, U8 Shift);
Parameter
v
Len
Shift
Description
Value to display.
Minimum: -2147483648 (= -2^31); maximum: 2147483647 (= 2^31 -1).
No. of digits to display (max. 10).
No. of digits to show to right of decimal point.
Additional information
A sign is always shown in front of the value.
Watch the maximum number of 9 characters (including sign and decimal point).
Example
void DemoDec(void) {
long l = 12345;
GUI_Clear();
GUI_SetFont(&GUI_Font8x8);
GUI_DispStringAt("GUI_DispDecShift:\n",0,0);
GUI_DispSDecShift(l, 7, 3);
GUI_SetFont(&GUI_Font6x8);
GUI_DispStringAt("Press any key",0,GUI_VYSIZE-8);
WaitKey();
}
Screen shot of above example
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
91
8.3
Displaying floating point values
GUI_DispFloat()
Description
Displays a floating point value with a specified number of characters at the current
text position in the current window using the current font.
Prototype
void GUI_DispFloat(float v, char Len);
Parameter
Description
v
Value to display.
Minimum 1.2 E-38; maximum 3.4 E38.
Len
No. of digits to display (max. 10).
Additional information
Leading zeros are suppressed. The decimal point counts as one character.
If the value is negative, a minus sign is shown.
Example
/* Shows all features for displaying floating point values */
void DemoFloat(void) {
float f = 123.45678;
GUI_Clear();
GUI_SetFont(&GUI_Font8x8);
GUI_DispStringAt("GUI_DispFloat:\n",0,0);
GUI_DispFloat (f,9);
GUI_GotoX(100);
GUI_DispFloat (-f,9);
GUI_DispStringAt("GUI_DispFloatFix:\n",0,20);
GUI_DispFloatFix (f,9,2);
GUI_GotoX(100);
GUI_DispFloatFix (-f,9,2);
GUI_DispStringAt("GUI_DispSFloatFix:\n",0,40);
GUI_DispSFloatFix (f,9,2);
GUI_GotoX(100);
GUI_DispSFloatFix (-f,9,2);
GUI_DispStringAt("GUI_DispFloatMin:\n",0,60);
GUI_DispFloatMin (f,3);
GUI_GotoX(100);
GUI_DispFloatMin (-f,3);
GUI_DispStringAt("GUI_DispSFloatMin:\n",0,80);
GUI_DispSFloatMin (f,3);
GUI_GotoX(100);
GUI_DispSFloatMin (-f,3);
GUI_SetFont(&GUI_Font6x8);
GUI_DispStringAt("Press any key",0,GUI_VYSIZE-8);
WaitKey();
}
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
92
CHAPTER
Displaying Values
Screen shot of above example
GUI_DispFloatFix()
Description
Displays a floating-point value with specified number of total characters and a specified number of characters to the right of the decimal point, at the current text position in the current window using the current font.
Prototype
void GUI_DispFloatFix (float v, char Len, char Decs);
Parameter
v
Len
Decs
Description
Value to display.
Minimum 1.2 E-38; maximum 3.4 E38.
No. of digits to display (max. 10).
No. of digits to show to right of decimal point.
Additional information
Leading zeros are not suppressed.
If the value is negative, a minus sign is shown.
GUI_DispFloatMin()
Description
Displays a floating-point value with a minimum number of decimals to the right of the
decimal point, at the current text position in the current window using the current
font.
Prototype
void GUI_DispFloatMin(float f, char Fract);
Parameter
Description
v
Value to display.
Minimum 1.2 E-38; maximum 3.4 E38.
Fract
Minimum no. of characters to display.
Additional information
Leading zeros are suppressed.
If the value is negative, a minus sign is shown.
The length need not be specified; the minimum length will automatically be used. If
values have to be aligned but differ in the number of digits, this function is not a
good choice. Try one of the functions that specify the number of digits.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
93
GUI_DispSFloatFix()
Description
Displays a floating-point value (with sign) with a specified number of total characters
and a specified number of characters to the right of the decimal point, in the current
window using the current font.
Prototype
void GUI_DispSFloatFix(float v, char Len, char Decs);
Parameter
v
Len
Decs
Description
Value to display.
Minimum 1.2 E-38; maximum 3.4 E38.
No. of digits to display (max. 10).
No. of digits to show to right of decimal point.
Additional information
Leading zeros are not suppressed.
A sign is always shown in front of the value.
GUI_DispSFloatMin()
Description
Displays a floating-point value (with sign) with a minimum number of decimals to the
right of the decimal point, at the current text position in the current window using
the current font.
Prototype
void GUI_DispSFloatMin(float f, char Fract);
Parameter
Description
v
Value to display.
Minimum 1.2 E-38; maximum 3.4 E38.
Fract
Minimum no. of digits to display.
Additional information
Leading zeros are suppressed.
A sign is always shown in front of the value.
The length need not be specified; the minimum length will automatically be used. If
values have to be aligned but differ in the number of digits, this function is not a
good choice. Try one of the functions that specify the number of digits.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
94
8.4
CHAPTER
Displaying Values
Displaying binary values
GUI_DispBin()
Description
Displays a value in binary form at the current text position in the current window
using the current font.
Prototype
void GUI_DispBin(U32 v, U8 Len);
Parameter
v
Len
Description
Value to display, 32-bit.
No. of digits to display (including leading zeros).
Additional information
As with decimal and hexadecimal values, the least significant bit is rightmost.
Example
//
// Show binary value 7, result: 000111
//
U32 Input = 0x7;
GUI_DispBin(Input, 6);
Related topics
GUI_DispBinAt()
GUI_DispBinAt()
Description
Displays a value in binary form at a specified position in the current window using the
current font.
Prototype
void DispBinAt(U32
v, I16P y, I16P x, U8 Len);
Parameter
v
x
y
Len
Description
Value to display, 16-bit.
X-position to write to in pixels of the client window.
Y-position to write to in pixels of the client window.
No. of digits to display (including leading zeroes).
Additional information
As with decimal and hexadecimal values, the least significant bit is rightmost.
Example
//
// Show binary input status
//
GUI_DispBinAt(Input, 0,0, 8);
Related topics
GUI_DispBin(), GUI_DispHex()
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
95
8.5
Displaying hexadecimal values
GUI_DispHex()
Description
Displays a value in hexadecimal form at the current text position in the current window using the current font.
Prototype
void GUI_DispHex(U32 v, U8 Len);
Parameter
v
Len
Description
Value to display, 16-bit.
No. of digits to display.
Additional information
As with decimal and binary values, the least significant bit is rightmost.
Example
/* Show value of AD-converter */
GUI_DispHex(Input, 4);
Related topics
GUI_DispDec(), GUI_DispBin(), GUI_DispHexAt()
GUI_DispHexAt()
Description
Displays a value in hexadecimal form at a specified position in the current window
using the current font.
Prototype
void GUI_DispHexAt(U32 v, I16P x, I16P y, U8 Len);
Parameter
v
x
y
Len
Description
Value to display, 16-bit.
X-position to write to in pixels of the client window.
Y-position to write to in pixels of the client window.
No. of digits to display.
Additional information
As with decimal and binary values, the least significant bit is rightmost.
Example
//
// Show value of AD-converter at specified position
//
GUI_DispHexAt(Input, 0, 0, 4);
Related topics
GUI_DispDec(), GUI_DispBin(), GUI_DispHex()
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
96
8.6
CHAPTER
Displaying Values
Version of emWin
GUI_GetVersionString()
Description
Returns a string containing the current version of emWin.
Prototype
const char * GUI_GetVersionString(void);
Example
//
// Displays the current version at the current cursor position
//
GUI_DispString(GUI_GetVersionString());
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
97
Chapter 9
2-D Graphic Library
emWin contains a complete 2-D graphic library which should be sufficient for most
applications. The routines supplied with emWin can be used with or without clipping
(refer to the chapter “The Window Manager (WM)” on page 289) and are based on
fast and efficient algorithms. Currently, only the GUI_DrawArc() function requires
floating-point calculations.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
98
9.1
CHAPTER
2-D Graphic Library
Graphic API
The table below lists the available graphic-related routines in alphabetical order
within their respective categories. Detailed descriptions can be found in the sections
that follow.
Routine
Description
Returns the color index of a given position.
GUI_GetPixelIndex()
Drawing modes
Returns the current drawing mode.
GUI_GetDrawMode()
GUI_SetDrawMode()
Sets the drawing mode.
Pen size
Returns the current pen size in pixels.
GUI_GetPenSize()
GUI_SetPenSize()
Sets the pen size in pixels.
Query current client rectangle
Returns the current available drawing area.
GUI_GetClientRect()
Basic drawing routines
GUI_ClearRect()
Fills a rectangular area with the background
color.
GUI_CopyRect()
Copies a rectangle area on the display
GUI_DrawGradientH()
Draws a rectangle filled with a horizontal color
gradient.
GUI_DrawGradientV()
Draws a rectangle filled with a vertical color gradient.
GUI_DrawGradientRoundedH()
Draws a rectangle with rounded corners filled
with a horizontal color gradient.
GUI_DrawGradientRoundedV()
Draws a rectangle with rounded corners filled
with a vertical color gradient.
Draws a single pixel.
GUI_DrawPixel()
GUI_DrawPoint()
GUI_DrawRect()
GUI_DrawRectEx()
GUI_DrawRoundedFrame()
GUI_DrawRoundedRect()
GUI_FillRect()
GUI_FillRectEx()
GUI_FillRoundedRect()
GUI_InvertRect()
Draws a point.
Draws a rectangle.
Draws a rectangle.
Draws a frame with rounded corners.
Draws a rectangle with rounded corners.
Draws a filled rectangle.
Draws a filled rectangle.
Draws a filled rectangle with rounded corners.
Invert a rectangular area.
Alpha blending
GUI_EnableAlpha()
Enables/disables automatic alpha blending
GUI_RestoreUserAlpha()
Restores the previous state of user alpha blending
GUI_SetAlpha()
Sets the current alpha blending value. (Obsolete)
GUI_SetUserAlpha()
Sets an additional value which is used to calculate the actual alpha blending value to be used.
Drawing bitmaps
Draws a bitmap.
GUI_DrawBitmap()
GUI_DrawBitmapEx()
Draws a scaled bitmap.
Draws a bitmap with alpha blending information
on a system with hardware alpha blending support.
GUI_DrawBitmapHWAlpha()
Draws a magnified bitmap.
GUI_DrawBitmapMag()
Drawing streamed bitmaps
GUI_CreateBitmapFromStream()
Creates a bitmap from a given stream of any
type.
GUI_CreateBitmapFromStreamIDX()
Creates a bitmap from an index based bitmap
stream.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
99
Routine
Description
Creates a bitmap from an RLE4 bitmap stream.
GUI_CreateBitmapFromStreamRLE4()
GUI_CreateBitmapFromStreamRLE8()
GUI_CreateBitmapFromStream565()
Creates a bitmap from an RLE8 bitmap stream.
Creates a bitmap from a 16 bit bitmap stream.
GUI_CreateBitmapFromStreamM565()
Creates a bitmap from a 16 bit bitmap stream
with red and blue swapped.
GUI_CreateBitmapFromStream555()
Creates a bitmap from a 15 bit bitmap stream.
GUI_CreateBitmapFromStreamM555()
Creates a bitmap from a 15 bit bitmap stream
with red and blue swapped.
GUI_CreateBitmapFromStreamRLE16()
Creates a bitmap from an RLE16 bitmap stream.
GUI_CreateBitmapFromStreamRLEM16()
Creates a bitmap from an RLE16 bitmap stream
with red and blue swapped.
Creates a bitmap from a 24 bit bitmap stream.
GUI_CreateBitmapFromStream24()
GUI_CreateBitmapFromStreamAlpha()
Creates a bitmap from a 32 bit bitmap stream.
GUI_CreateBitmapFromStreamRLEAlpha()
GUI_CreateBitmapFromStreamRLE32()
GUI_DrawStreamedBitmap()
Creates a bitmap from an RLE compressed 8 bit
alpha bitmap stream.
Creates a bitmap from an RLE32 bitmap stream.
Draws a bitmap stream.
GUI_DrawStreamedBitmapEx()
Draws a bitmap stream without loading the
complete image.
GUI_GetStreamedBitmapInfo()
Returns information about the given stream.
GUI_GetStreamedBitmapInfoEx()
Returns information about the given stream
which can be located on any kind of media.
GUI_SetStreamedBitmapHook()
Sets a hook function for
GUI_DrawStreamedBitmapEx().
Drawing lines
GUI_DrawHLine()
Draws a horizontal line.
GUI_DrawLine()
Draws a line from a specified start point to a
specified end point (absolute coordinates).
GUI_DrawLineRel()
Draws a line from the current position to an
endpoint specified by X- and Y-distances (relative coordinates).
GUI_DrawLineTo()
Draws a line from the current position to a specified endpoint.
GUI_DrawPolyLine()
GUI_DrawVLine()
GUI_GetLineStyle()
GUI_MoveRel()
GUI_MoveTo()
GUI_SetLineStyle()
Draws a polyline.
Draws a vertical line.
Returns the current line style.
Moves the line pointer relative to its current
position.
Moves the line pointer to the given position.
Sets the current line style.
Drawing polygons
GUI_DrawPolygon()
GUI_EnlargePolygon()
GUI_FillPolygon()
GUI_MagnifyPolygon()
GUI_RotatePolygon()
Draws the outline of a polygon.
Enlarges a polygon.
Draws a filled polygon.
Magnifies a polygon.
Rotates a polygon by a specified angle.
Drawing circles
GUI_DrawCircle()
GUI_FillCircle()
Draws the outline of a circle.
Draws a filled circle.
Drawing ellipses
GUI_DrawEllipse()
GUI_FillEllipse()
Draws the outline of an ellipse.
Draws a filled ellipse.
Drawing arcs
GUI_DrawArc()
Draws an arc.
Drawing a graph
GUI_DrawGraph()
User's & reference manual for emWin V5.10
Draws a graph.
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
100
CHAPTER
2-D Graphic Library
Routine
Description
Drawing a pie chart
Draws a circle sector.
GUI_DrawPie()
Saving and restoring the GUI-context
Restores the GUI-context.
GUI_RestoreContext()
GUI_SaveContext()
Saves the GUI-context.
Clipping
Sets the rectangle used for clipping.
GUI_SetClipRect()
GUI_GetPixelIndex()
Description
Returns the color index of a given position.
Prototype
unsigned GUI_GetPixelIndex(int x, int y);
Parameter
absolute x-position of the pixel
x
y
9.2
Description
absolute y-position of the pixel
Drawing modes
emWin can draw in NORMAL mode or in XOR mode. The default is NORMAL mode, in
which the content of the display is overdrawn by the graphic. In XOR mode, the content of the display is inverted when it is overdrawn.
Restrictions associated with GUI_DRAWMODE_XOR
•
•
•
•
XOR mode is only useful when using two displayed colors inside the active window or screen.
Some drawing functions of emWin do not work precisely with this drawing mode.
Generally, this mode works only with a pen size of one pixel. That means before
using functions like GUI_DrawLine(), GUI_DrawCircle(), GUI_DrawRect() and
so on, you must make sure that the pen size is set to 1 when you are working in
XOR mode.
When drawing bitmaps with a color depth greater than 1 bit per pixel (bpp) this
drawing mode takes no effect.
When using drawing functions such as GUI_DrawPolyLine() or multiple calls of
GUI_DrawLineTo(), the fulcrums are inverted twice. The result is that these pixels remain in the background color.
GUI_GetDrawMode()
Description
Returns the current drawing mode.
Prototype
GUI_DRAWMODE GUI_GetDrawMode(void);
Return value
The currently selected drawing mode.
Additional information
For details about drawing modes, refer to the function “GUI_GetDrawMode()”
page 100.
User's & reference manual for emWin V5.10
on
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
101
GUI_SetDrawMode()
Description
Selects the specified drawing mode.
Prototype
GUI_DRAWMODE GUI_SetDrawMode(GUI_DRAWMODE mode);
Parameter
mode
Description
Drawing mode to set. May be a value returned by any routine which sets the drawing
mode or one of the constants below.
Permitted values for parameter mode
GUI_DM_NORMAL
Default: Draws points, lines, areas, bitmaps.
GUI_DM_XOR
Inverts points, lines, areas when overwriting the
color of another object on the display.
Return value
The selected drawing mode.
Additional information
In addition to setting the drawing mode, this routine may also be used to restore a
drawing mode that has previously been changed.
If using colors, an inverted pixel is calculated as follows:
New pixel color = number of colors - actual pixel color - 1.
Example
//
// Showing two circles, the second one XOR-combined with the first:
//
GUI_Clear();
GUI_SetDrawMode(GUI_DRAWMODE_NORMAL);
GUI_FillCircle(120, 64, 40);
GUI_SetDrawMode(GUI_DRAWMODE_XOR);
GUI_FillCircle(140, 84, 40);
Screen shot of above example
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
102
9.3
CHAPTER
2-D Graphic Library
Query current client rectangle
GUI_GetClientRect()
Description
The current client rectangle depends on using the window manager or not. If using
the window manager the function uses WM_GetClientRect to retrieve the client rectangle. If not using the window manager the client rectangle corresponds to the complete LCD display.
Prototype
void GUI_GetClientRect(GUI_RECT * pRect);
Parameter
pRect
9.4
Description
Pointer to GUI_RECT-structure to store result.
Pen size
The pen size determines the thickness of the following vector drawing operations:
•
GUI_DrawPoint()
•
GUI_DrawLine()
•
GUI_DrawLineRel()
•
GUI_DrawLineTo()
•
GUI_DrawPolyLine()
•
GUI_DrawPolygon()
•
GUI_DrawEllipse()
•
GUI_DrawArc()
Please note that it is not possible to combine line styles with a pen size > 1.
GUI_GetPenSize()
Description
Returns the current pen size.
Prototype
U8 GUI_GetPenSize(void);
GUI_SetPenSize()
Description
Sets the pen size to be used for further drawing operations.
Prototype
U8 GUI_SetPenSize(U8 PenSize);
Parameter
PenSize
Description
Pen size in pixels to be used.
Return value
Previous pen size.
Add information
The pen size should be >= 1.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
103
9.5
Basic drawing routines
The basic drawing routines allow drawing of individual points, horizontal and vertical
lines and shapes at any position on the display. Any available drawing mode can be
used. Since these routines are called frequently in most applications, they are optimized for speed as much as possible. For example, the horizontal and vertical line
functions do not require the use of single-dot routines.
GUI_ClearRect()
Description
Clears a rectangular area at a specified position in the current window by filling it
with the background color.
Prototype
void GUI_ClearRect(int x0, int y0, int x1, int y1);
Parameter
x0
y0
x1
y1
Description
Upper left X-position.
Upper left Y-position.
Lower right X-position.
Lower right Y-position.
Related topics
GUI_InvertRect(), GUI_FillRect()
GUI_CopyRect()
Description
Copies the content of the given rectangular area to the specified position.
Prototype
void GUI_CopyRect(int x0, int y0, int x1, int y1, int xSize, int ySize);
Parameter
x0
y0
x1
y1
xSize
ySize
Description
Upper left X-position of the source rectangle.
Upper left Y-position of the source rectangle.
Upper left X-position of the destination rectangle.
Upper left Y-position of the destination rectangle.
X-size of the rectangle.
Y-size of the rectangle.
Additional information
The source and destination rectangle may overlap each other.
GUI_DrawGradientH()
Description
Draws a rectangle filled with a horizontal color gradient.
Prototype
void GUI_DrawGradientH(int x0, int y0, int x1, int y1,
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
104
CHAPTER
2-D Graphic Library
GUI_COLOR Color0, GUI_COLOR Color1);
Parameter
x0
y0
x1
y1
Color0
Color1
Description
Upper left X-position.
Upper left Y-position.
Lower right X-position.
Lower right Y-position.
Color to be drawn on the leftmost side of the rectangle.
Color to be drawn on the rightmost side of the rectangle.
Example
GUI_DrawGradientH(0, 0, 99, 99, 0x0000FF, 0x00FFFF);
Screenshot of above example
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
105
GUI_DrawGradientV()
Description
Draws a rectangle filled with a vertical color gradient.
Prototype
void GUI_DrawGradientV(int x0, int y0, int x1, int y1,
GUI_COLOR Color0, GUI_COLOR Color1);
Parameter
x0
y0
x1
y1
Color0
Color1
Description
Upper left X-position.
Upper left Y-position.
Lower right X-position.
Lower right Y-position.
Color to be drawn on the topmost side of the rectangle.
Color to be drawn on the bottommost side of the rectangle.
Example
GUI_DrawGradientV(0, 0, 99, 99, 0x0000FF, 0x00FFFF);
Screenshot of above example
GUI_DrawGradientRoundedH()
Description
Draws a rectangle with rounded corners filled with a horizontal color gradient.
Prototype
void GUI_DrawGradientRoundedH(int x0, int y0, int x1, int y1, int rd
GUI_COLOR Color0, GUI_COLOR Color1);
Parameter
x0
y0
x1
y1
rd
Color0
Color1
Description
Upper left X-position.
Upper left Y-position.
Lower right X-position.
Lower right Y-position.
Color to be drawn on the leftmost side of the rectangle.
Color to be drawn on the rightmost side of the rectangle.
Example
GUI_DrawGradientRoundedH(0, 0,
99, 99, 25, 0x0000FF, 0x00FFFF);
Screenshot of above example
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
106
CHAPTER
2-D Graphic Library
GUI_DrawGradientRoundedV()
Description
Draws a rectangle with rounded corners filled with a vertical color gradient.
Prototype
void GUI_DrawGradientRoundedV(int x0,
int y0, int x1,
int y1,
GUI_COLOR Color0, GUI_COLOR Color1);
Parameter
x0
y0
x1
y1
Color0
Color1
Description
Upper left X-position.
Upper left Y-position.
Lower right X-position.
Lower right Y-position.
Color to be drawn on the leftmost side of the rectangle.
Color to be drawn on the rightmost side of the rectangle.
Example
GUI_DrawGradientRoundedV(0, 0, 99, 99, 25, 0x0000FF, 0x00FFFF);
Screenshot of above example
GUI_DrawPixel()
Description
Draws a pixel at a specified position in the current window.
Prototype
void GUI_DrawPixel(int x, int y);
Parameter
x
y
Description
X-position of pixel.
Y-position of pixel.
Related topics
GUI_DrawPoint()
GUI_DrawPoint()
Description
Draws a point with the current pen size at a specified position in the current window.
Prototype
void GUI_DrawPoint(int x, int y);
Parameter
x
y
Description
X-position of point.
Y-position of point.
Related topics
GUI_DrawPixel()
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
107
GUI_DrawRect()
Description
Draws a rectangle at a specified position in the current window.
Prototype
void GUI_DrawRect(int x0, int y0, int x1, int y1);
Parameter
x0
y0
x1
y1
Description
Upper left X-position.
Upper left Y-position.
Lower right X-position.
Lower right Y-position.
GUI_DrawRectEx()
Description
Draws a rectangle at a specified position in the current window.
Prototype
void GUI_DrawRectEx(const GUI_RECT * pRect);
Parameter
pRect
Description
Pointer to a GUI_RECT-structure containing the coordinates of the rectangle
GUI_DrawRoundedFrame()
Description
Draws a frame at a specified position in the current window with rounded corners an
a specified width.
Prototype
void GUI_DrawRoundedFrame(int x0, int y0, int x1, int y1, int r, int w);
Parameter
x0
y0
x1
y1
r
w
Description
Upper left X-position.
Upper left Y-position.
Lower right X-position.
Lower right Y-position.
Radius to be used for the rounded corners.
Width in which the frame is drawn.
GUI_DrawRoundedRect()
Description
Draws a rectangle at a specified position in the current window with rounded corners.
Prototype
void GUI_DrawRoundedRect(int x0, int y0, int x1, int y1, int r);
Parameter
x0
y0
x1
y1
r
Description
Upper left X-position.
Upper left Y-position.
Lower right X-position.
Lower right Y-position.
Radius to be used for the rounded corners.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
108
CHAPTER
2-D Graphic Library
GUI_FillRect()
Description
Draws a filled rectangular area at a specified position in the current window.
Prototype
void GUI_FillRect(int x0, int y0, int x1, int y1);
Parameter
x0
y0
x1
y1
Description
Upper left X-position.
Upper left Y-position.
Lower right X-position.
Lower right Y-position.
Additional information
Uses the current drawing mode, which normally means all pixels inside the rectangle
are set.
Related topics
GUI_InvertRect(), GUI_ClearRect()
GUI_FillRectEx()
Description
Draws a filled rectangle at a specified position in the current window.
Prototype
void GUI_FillRectEx(const GUI_RECT * pRect);
Parameter
pRect
Description
Pointer to a GUI_RECT-structure containing the coordinates of the rectangle
GUI_FillRoundedRect()
Description
Draws a filled rectangle at a specified position in the current window with rounded
corners.
Prototype
void GUI_FillRoundedRect(int x0, int y0, int x1, int y1, int r);
Parameter
x0
y0
x1
y1
r
Description
Upper left X-position.
Upper left Y-position.
Lower right X-position.
Lower right Y-position.
Radius to be used for the rounded corners.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
109
GUI_InvertRect()
Description
Draws an inverted rectangular area at a specified position in the current window.
Prototype
void GUI_InvertRect(int x0, int y0, int x1, int y1);
Parameter
x0
y0
x1
y1
Description
Upper left X-position.
Upper left Y-position.
Lower right X-position.
Lower right Y-position.
Related topics
GUI_FillRect(), GUI_ClearRect()
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
110
CHAPTER
9.6
2-D Graphic Library
Alpha blending
Alpha blending is a method of combining a foreground image with the background to
create the appearance of semi transparency. An alpha value determines how much of
a pixel should be visible and how much of the background should show through.
Color information
emWin internally works with 32 bits of color information:
•
•
•
•
Bits
Bits
Bits
Bits
0-7: Red
8-15: Green
16-23: Blue
24-31: Alpha information
An alpha value of 0 means opaque and a value of 255 means completely transparent.
How it works
The alpha blending is done completely automatically. The only thing which needs to
be done is enabling alpha blending with GUI_EnableAlpha(). From there on the
upper 8 bits of the color information are managed as alpha values.
Example
The following small example shows how it works:
GUI_EnableAlpha(1);
GUI_SetBkColor(GUI_WHITE);
GUI_Clear();
GUI_SetColor(GUI_BLACK);
GUI_DispStringHCenterAt("Alphablending", 45, 41);
GUI_SetColor((0x40uL << 24) | GUI_RED);
GUI_FillRect(0, 0, 49, 49);
GUI_SetColor((0x80uL << 24) | GUI_GREEN);
GUI_FillRect(20, 20, 69, 69);
GUI_SetColor((0xC0uL << 24) | GUI_BLUE);
GUI_FillRect(40, 40, 89, 89);
Older versions
In older versions it was required to use the function GUI_SetAlpha() for blending the
foreground with the current background color information. This also works but is no
longer required.
GUI_EnableAlpha()
Description
Enables or disables automatic alpha blending.
Prototype
unsigned GUI_EnableAlpha(unsigned OnOff);
Parameter
OnOff
Description
1 enables automatic alpha blending, 0 disables it.
Return value
Old state.
Additional information
After enabling automatic alpha blending the color information of each object automatically determines its transparency.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
111
GUI_SetAlpha()
(Obsolete)
Description
Enables software alpha blending for all subsequent drawing operations.
Prototype
unsigned GUI_SetAlpha(U8 Value);
Parameter
Alpha
Description
Alpha value to be used for all subsequent drawing operations. Default is 0 which means
no alpha blending.
Return value
Previous value used for alpha blending.
Additional information
The function sets the alpha value to be used for all subsequent drawing operations. A
value of 0 for parameter Alpha means opaque (alpha blending disabled) and a value
of 255 means completely transparent (invisible).
Note that software alpha blending increases the CPU load. Further it is strongly recommended to set the alpha value back to the default value after finishing the drawing operations.
Example
extern const GUI_BITMAP _LogoBitmap;
GUI_SetColor(GUI_BLUE);
GUI_FillCircle(100, 50, 49);
GUI_SetColor(GUI_YELLOW);
for (i = 0; i < 100; i++) {
U8 Alpha;
Alpha = (i * 255 / 100);
GUI_SetAlpha(Alpha);
GUI_DrawHLine(i, 100 - i, 100 + i);
}
GUI_SetAlpha(0x80);
GUI_DrawBitmap(&_LogoBitmap, 30, 30);
GUI_SetColor(GUI_MAGENTA);
GUI_SetFont(&GUI_Font24B_ASCII);
GUI_SetTextMode(GUI_TM_TRANS);
GUI_DispStringHCenterAt("Alphablending", 100, 3);
GUI_SetAlpha(0);
/* Set back to default (opaque) */
Screen shot of above example
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
112
CHAPTER
2-D Graphic Library
GUI_SetUserAlpha()
Description
Sets an additional value which is used to calculate the actual alpha value to be used.
The actual alpha value is calculated as follows:
Alpha = AlphaFromObject + ((255 - AlphaFromObject) * UserAlpha) / 255
Prototype
U32 GUI_SetUserAlpha(GUI_ALPHA_STATE * pAlphaState, U32 UserAlpha);
Parameter
pAlphaState
UserAlpha
Description
Pointer to an GUI_ALPHA_STATE structure to be used to save the current state.
Value to be used.
Return value
Previous user alpha value.
Additional information
The following function GUI_RestoreUserAlpha() can be used to restore the previous
state of the function.
GUI_RestoreUserAlpha()
Description
Restores the previous state of user alpha blending. saved in the structure pointed by.
Prototype
U32 GUI_RestoreUserAlpha(GUI_ALPHA_STATE * pAlphaState);
Parameter
pAlphaState
Description
Pointer to an GUI_ALPHA_STATE structure containing information of the previous
state to be restored.
Return value
Current user alpha value.
Example
{
GUI_ALPHA_STATE AlphaState;
}
GUI_EnableAlpha(1);
GUI_SetBkColor(GUI_WHITE);
GUI_Clear();
GUI_SetColor(GUI_BLACK);
GUI_DispStringHCenterAt("Alphablending", 45, 41);
GUI_SetUserAlpha(&AlphaState, 0xC0);
GUI_SetColor(GUI_RED);
GUI_FillRect(0, 0, 49, 49);
GUI_SetColor(GUI_GREEN);
GUI_FillRect(20, 20, 69, 69);
GUI_SetColor(GUI_BLUE);
GUI_FillRect(40, 40, 89, 89);
GUI_RestoreUserAlpha(&AlphaState);
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
113
9.7
Drawing bitmaps
Generally emWin is able to display any bitmap image at any display position. On 16
bit CPUs (sizeof(int) == 2), the size of one bitmap per default is limited to 64 kb. If
larger bitmaps should be displayed with a 16 bit CPU, refer to the chapter “Configuration” on page 905.
GUI_DrawBitmap()
Description
Draws a bitmap image at a specified position in the current window.
Prototype
void GUI_DrawBitmap(const GUI_BITMAP * pBM, int x, int y);
Parameter
pBM
x
y
Description
Pointer to the bitmap to display.
X-position of the upper left corner of the bitmap in the display.
Y-position of the upper left corner of the bitmap in the display.
Additional information
The picture data is interpreted as bit stream starting with the most significant bit
(msb) of the first byte.
A new line always starts at an even byte address, as the nth line of the bitmap starts
at offset n*BytesPerLine. The bitmap can be shown at any point in the client area.
Usually, the bitmap converter is used to generate bitmaps. For more information,
refer to the chapter “Bitmap Converter” on page 213.
Example
extern const GUI_BITMAP bmSeggerLogoBlue;
/* declare external Bitmap */
void main() {
GUI_Init();
GUI_DrawBitmap(&bmSeggerLogoBlue, 45, 20);
}
Screen shot of above example
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
114
CHAPTER
2-D Graphic Library
GUI_DrawBitmapEx()
Description
This routine makes it possible to scale and/or to mirror a bitmap on the display.
Prototype
void GUI_DrawBitmapEx(const GUI_BITMAP
int x0,
int
int xCenter, int
int xMag,
int
Parameter
pBM
x0
y0
xCenter
yCenter
xMag
yMag
* pBitmap,
y0,
yCenter,
yMag);
Description
Pointer to the bitmap to display.
X-position of the anchor point in the display.
Y-position of the anchor point in the display.
X-position of the anchor point in the bitmap.
Y-position of the anchor point in the bitmap.
Scale factor of X-direction.
Scale factor of Y-direction.
Additional information
A negative value of the xMag-parameter would mirror the bitmap in the X-axis and a
negative value of the yMag-parameter would mirror the bitmap in the Y-axis. The unit
of xMag- and yMag are thousandth. The position given by the parameter xCenter and
yCenter specifies the pixel of the bitmap which should be displayed at the display at
position x0/y0 independent of scaling or mirroring.
This function can not be used to draw RLE-compressed bitmaps.
GUI_DrawBitmapHWAlpha()
Description
Draws a bitmap with alpha information on a multi layer system with hardware alpha
blending support.
Prototype
void GUI_DrawBitmapHWAlpha(const GUI_BITMAP GUI_UNI_PTR * pBM,
int x0, int y0);
Parameter
pBM
x0
y0
Description
Pointer to the bitmap to display.
X-position of the upper left corner of the bitmap in the display.
Y-position of the upper left corner of the bitmap in the display.
Additional information
In emWin logical colors are handled as 32 bit values. The lower 24 bits are used for
the color information and the upper 8 bits are used to manage the alpha value. An
alpha value of 0 means the image is opaque and a value of 0xFF means completely
transparent (invisible).
On systems with hardware support for alpha blending the alpha values need to be
written to the display controller which does the alpha blending.
Normally the alpha format of the hardware is not the same as the alpha definition in
emWin described above. Mostly a value of 0 means fully transparent and higher values means the pixel becomes more visible.
Because of this in the most cases custom color conversion routines are required to
translate a logical color to the required hardware format. The Sample folder contains
the example ALPHA_DrawBitmapHWAlpha which shows how to consider the requirement of custom color conversion.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
115
GUI_DrawBitmapMag()
Description
This routine makes it possible to magnify a bitmap on the display.
Prototype
void GUI_DrawBitmapMag(const GUI_BITMAP * pBM,
int x0,
int y0,
int XMul, int YMul);
Parameter
pBM
x0
y0
XMul
YMul
Description
Pointer to the bitmap to display.
X-position of the upper left corner of the bitmap in the display.
Y-position of the upper left corner of the bitmap in the display.
Magnification factor of X-direction.
Magnification factor of Y-direction.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
116
CHAPTER
9.8
2-D Graphic Library
Drawing streamed bitmaps
Contrary to bitmaps in C file format a streamed bitmap can be located anywhere. Bitmap streams can be used to create bitmaps. These bitmaps can be used in the same
manner as bitmaps in C file format. Further emWin supports direct drawing of palette
based bitmap streams without having the complete image in the addressable area
(RAM or ROM).
GUI_CreateBitmapFromStream()
Description
The function creates a bitmap structure by passing any type of bitmap stream.
Prototype
int
GUI_CreateBitmapFromStream(GUI_BITMAP *
pBMP,
GUI_LOGPALETTE * pPAL,
const void *
p);
Parameter
pBMP
pPAL
p
Description
Pointer to a
GUI_BITMAP structure to be initialized by the function.
Pointer to a GUI_LOGPALETTE structure to be initialized by the function.
Pointer to the data stream.
Return value
0 on success, 1 on error.
Additional information
This function should be used if the data stream can consist of several kinds of bitmap
formats or unknown. Disadvantage of using this function is that it has a significant
memory footprint. If memory usage (ROM) is a concern, it may be better to use the
format specific functions below.
GUI_CreateBitmapFromStreamIDX(),
GUI_CreateBitmapFromStreamRLE4(),
GUI_CreateBitmapFromStreamRLE8(),
GUI_CreateBitmapFromStream565(),
GUI_CreateBitmapFromStreamM565(),
GUI_CreateBitmapFromStream555(),
GUI_CreateBitmapFromStreamM555(),
GUI_CreateBitmapFromStreamRLE16(),
GUI_CreateBitmapFromStreamRLEM16(),
GUI_CreateBitmapFromStream24(),
GUI_CreateBitmapFromStreamAlpha(),
GUI_CreateBitmapFromStreamRLEAlpha(),
GUI_CreateBitmapFromStreamRLE32()
Description
These functions create bitmap structures by passing bitmap streams of a known format.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
117
Prototype
int
GUI_CreateBitmapFromStream<FORMAT>(GUI_BITMAP *
pBMP,
GUI_LOGPALETTE * pPAL,
const void *
p);
Parameter
pBMP
pPAL
p
Description
Pointer to a
Pointer to a
GUI_BITMAP structure to be initialized by the function.
GUI_LOGPALETTE structure to be initialized by the function.
Pointer to the data stream.
Supported data stream formats
The following table shows the supported data stream formats for each function:
Function
Supported stream format
GUI_CreateBitmapFromStreamIDX()
Streams of index based bitmaps.
GUI_CreateBitmapFromStreamRLE4()
Streams of RLE4 compressed bitmaps.
GUI_CreateBitmapFromStreamRLE8()
Streams of RLE8 compressed bitmaps.
GUI_CreateBitmapFromStream565()
Streams of high color bitmaps (565).
GUI_CreateBitmapFromStreamM565()
Streams of high color bitmaps (M565).
GUI_CreateBitmapFromStream555()
Streams of high color bitmaps (555).
GUI_CreateBitmapFromStreamM555()
Streams of high color bitmaps (M565).
GUI_CreateBitmapFromStreamRLE16()
Streams of RLE16 compressed bitmaps.
GUI_CreateBitmapFromStreamRLEM16()
Streams of RLE16 compressed bitmaps, red
and blue swapped.
GUI_CreateBitmapFromStream24()
Streams of 24bpp bitmaps (true color).
GUI_CreateBitmapFromStreamAlpha()
Streams of 32bpp bitmaps (true color with
alpha channel).
GUI_CreateBitmapFromStreamRLEAlpha()
Streams of RLE compressed 8bpp alpha bitmaps.
GUI_CreateBitmapFromStreamRLE32()
Streams of RLE32 compressed bitmaps (true
color with alpha channel).
Return value
0 on success, 1 on error.
Additional information
These functions should be used if the data stream consists of a known format. This
avoids linking of unused code and keeps the binary code small.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
118
CHAPTER
2-D Graphic Library
GUI_DrawStreamedBitmap()
Description
Draws a bitmap from a data bitmap data stream.
Prototype
void GUI_DrawStreamedBitmap(const void * p, int x, int y);
Parameter
p
x
y
Description
Pointer to the data stream.
X-position of the upper left corner of the bitmap in the display.
Y-position of the upper left corner of the bitmap in the display.
Additional information
You can use the bitmap converter (see “Bitmap Converter” on page 213) to create
bitmap data streams. The format of these streams is not the same as the format of a
bmp file.
GUI_DrawStreamedBitmapEx()
Description
This function is used for drawing data streams if not enough RAM or ROM is available
to keep the whole file within the addressable memory (RAM or ROM). The GUI library
calls the function pointed by the parameter pfGetData to read the data. The GetData
function needs to return the number of requested bytes. The maximum number of
bytes requested by the GUI is the number of bytes needed for drawing one line of the
image.
Prototype
int GUI_DrawStreamedBitmapEx(GUI_GET_DATA_FUNC * pfGetData,
const void
* p, int x, int y);
Parameter
pfGetData
p
x
y
Description
Pointer to a function which is called for getting data. For details about the
function, refer to “Getting data with the ...Ex() functions” on page 167.
Void pointer passed to the function pointed by
GetData
pfGetData.
X-position of the upper left corner of the bitmap in the display.
Y-position of the upper left corner of the bitmap in the display.
Return value
0 on success, 1 on error.
Additional information
Please also refer to the function GUI_SetStreamedBitmapHook().
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
119
GUI_GetStreamedBitmapInfo()
Description
Returns a structure with information about the given data stream.
Prototype
void GUI_GetStreamedBitmapInfo(const void *
p,
GUI_BITMAPSTREAM_INFO * pInfo);
Parameter
Description
Pointer to the data stream.
p
pInfo
Pointer to a
GUI_BITMAPSTREAM_INFO structure to be filled by the function.
Elements of GUI_BITMAPSTREAM_INFO
Data type
int
int
int
int
int
Element
Description
XSize
YSize
BitsPerPixel
NumColors
HasTrans
Pixel size in X of the image.
Pixel size in Y of the image.
Number of bits per pixel.
Number of colors in case of an index based image.
In case of an index based image 1 if transparency exist, 0 if not.
GUI_GetStreamedBitmapInfoEx()
Description
Returns a structure with information about the given data stream which does not
need to be located in the addressable ROM or RAM area of the CPU.
Prototype
int GUI_GetStreamedBitmapInfoEx(GUI_GET_DATA_FUNC *
pfGetData,
const void *
p,
GUI_BITMAPSTREAM_INFO * pInfo);
Parameter
pfGetData
p
pInfo
Description
Pointer to a function which is called for getting data. For details about the
function, refer to “Getting data with the ...Ex() functions” on page 167.
Void pointer passed to the function pointed by
Pointer to a
GetData
pfGetData.
GUI_BITMAPSTREAM_INFO structure to be filled by the function.
Return value
0 on success, 1 on error.
Elements of GUI_BITMAPSTREAM_INFO
Please refer to GUI_GetStreamedBitmapInfo().
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
120
CHAPTER
2-D Graphic Library
GUI_SetStreamedBitmapHook()
Description
Sets a hook function to be able to manipulate the palette of a streamed bitmap which
is not located in the addressable area of the CPU. The hook function is called when
executing GUI_DrawStreamedBitmapEx().
Prototype
void GUI_SetStreamedBitmapHook(
GUI_BITMAPSTREAM_CALLBACK pfStreamedBitmapHook);
Parameter
pfStreamedBitmapHook
Description
Hook function to be called by
GUI_DrawStreamedBitmapEx() .
Prototype of hook function
void * Hook(GUI_BITMAPSTREAM_PARAM * pParam);
Parameter
Description
Pointer to a GUI_BITMAPSTREAM_PARAM structure
pParam
Elements of GUI_BITMAPSTREAM_PARAM
Data type
int
U32
void *
Element
Cmd
v
p
Description
Command to be executed.
Depends on the command to be executed.
Depends on the command to be executed.
Supported values for parameter Cmd
GUI_BITMAPSTREAM_GET_BUFFER
When receiving this command the
application can spend a buffer for the
palette of a bitmap stream. Parameters:
p - Pointer to the buffer or NULL
v - Requested buffer size
GUI_BITMAPSTREAM_RELEASE_BUFFER
If the application has spend a buffer
for the palette here the buffer should
be released. Parameters:
p - Pointer to buffer to be released
v - not used
GUI_BITMAPSTREAM_MODIFY_PALETTE
This command is send after loading
the palette and before drawing the
image to be able to modify the palette of the streamed image. Parameters:
p - Pointer to palette data
v - Number of colors in palette
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
121
Example
static void * _cbStreamedBitmapHook(GUI_BITMAPSTREAM_PARAM * pParam) {
void * p = NULL;
int
i, NumColors;
U32
Color;
U32 * pColor;
switch (pParam->Cmd) {
case GUI_BITMAPSTREAM_GET_BUFFER:
//
// Allocate buffer for palette data
//
p = malloc(pParam->v);
break;
case GUI_BITMAPSTREAM_RELEASE_BUFFER:
//
// Release buffer
//
free(pParam->p);
break;
case GUI_BITMAPSTREAM_MODIFY_PALETTE:
//
// Do something with the palette...
//
NumColors = pParam->v;
pColor
= (U32 *)pParam->p;
Color
= *(pColor + pParam->v - 1);
for (i = NumColors - 2; i >= 0; i--) {
*(pColor + i + 1) = *(pColor + i);
}
*pColor = Color;
break;
}
return p;
}
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
122
CHAPTER
9.9
2-D Graphic Library
Drawing lines
The most frequently used drawing routines are those that draw a line from one point
to another.
GUI_DrawHLine()
Description
Draws a horizontal line one pixel thick from a specified starting point to a specified
endpoint in the current window.
Prototype
void GUI_DrawHLine(int y, int x0, int x1);
Parameter
y
x0
x1
Description
Y-position.
X-starting position.
X-end position.
Additional information
If x1 < x0, nothing will be displayed.
With most LCD controllers, this routine is executed very quickly because multiple pixels can be set at once and no calculations are needed. If it is clear that horizontal
lines are to be drawn, this routine executes faster than the GUI_DrawLine() routine.
GUI_DrawLine()
Description
Draws a line from a specified starting point to a specified endpoint in the current window (absolute coordinates).
Prototype
void GUI_DrawLine(int x0, int y0, int x1, int y1);
Parameter
x0
y0
x1
y1
Description
X-starting position.
Y-starting position.
X-end position.
Y-end position.
Additional information
If part of the line is not visible because it is not in the current window or because
part of the current window is not visible, this is due to clipping.
GUI_DrawLineRel()
Description
Draws a line from the current (X,Y) position to an endpoint specified by X-distance
and Y-distance in the current window (relative coordinates).
Prototype
void GUI_DrawLineRel(int dx, int dy);
Parameter
dx
dy
Description
Distance in X-direction to end of line to draw.
Distance in Y-direction end of line to draw.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
123
GUI_DrawLineTo()
Description
Draws a line from the current (X,Y) position to an endpoint specified by X- and Ycoordinates in the current window.
Prototype
void GUI_DrawLineTo(int x, int y);
Parameter
x
y
Description
X-end position.
Y-end position.
GUI_DrawPolyLine()
Description
Connects a predefined list of points with lines in the current window.
Prototype
void GUI_DrawPolyLine(const GUI_POINT * pPoint, int NumPoints,
int x, int y);
Parameter
pPoint
NumPoints
x
y
Description
Pointer to the polyline to display.
Number of points specified in the list of points.
X-position of origin.
Y-position of origin.
Additional information
The starting point and endpoint of the polyline need not be identical.
GUI_DrawVLine()
Description
Draws a vertical line one pixel thick from a specified starting point to a specified endpoint in the current window.
Prototype
void GUI_DrawVLine(int x, int y0, int y1);
Parameter
x
y0
y1
Description
X-position.
Y-starting position.
Y-end position.
Additional information
If y1 < y0, nothing will be displayed.
With most LCD controllers, this routine is executed very quickly because multiple pixels can be set at once and no calculations are needed. If it is clear that vertical lines
are to be drawn, this routine executes faster than the GUI_DrawLine() routine.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
124
CHAPTER
2-D Graphic Library
GUI_GetLineStyle()
Description
Returns the current line style used by the function GUI_DrawLine.
Prototype
U8 GUI_GetLineStyle(void);
Return value
Current line style used by the function GUI_DrawLine.
GUI_MoveRel()
Description
Moves the current line pointer relative to its current position.
Prototype
void GUI_MoveRel(int dx, int dy);
Parameter
dx
dy
Description
Distance to move in X.
Distance to move in Y.
Related topics
GUI_DrawLineTo(), GUI_MoveTo()
GUI_MoveTo()
Description
Moves the current line pointer to the given position.
Prototype
void GUI_MoveTo(int x, int y);
Parameter
x
y
Description
New position in X.
New position in Y.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
125
GUI_SetLineStyle()
Description
Sets the current line style used by the function GUI_DrawLine.
Prototype
U8 GUI_SetLineStyle(U8 LineStyle);
Parameter
LineStyle
Description
New line style to be used (see table below).
Permitted values for parameter LineStyle
GUI_LS_SOLID
GUI_LS_DASH
GUI_LS_DOT
Lines would be drawn solid (default).
Lines would be drawn dashed.
Lines would be drawn dotted.
GUI_LS_DASHDOT
Lines would be drawn alternating with dashes and
dots.
GUI_LS_DASHDOTDOT
Lines would be drawn alternating with dashes and
double dots.
Return value
Previous line style used by the function GUI_DrawLine.
Additional information
This function sets only the line style used by GUI_DrawLine. The style will be used
only with a pen size of 1.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
126
CHAPTER
2-D Graphic Library
9.10 Drawing polygons
The polygon drawing routines can be helpful when drawing vectorized symbols.
GUI_DrawPolygon()
Description
Draws the outline of a polygon defined by a list of points in the current window.
Prototype
void GUI_DrawPolygon(const GUI_POINT * pPoint, int NumPoints,
int x, int y);
Parameter
pPoint
NumPoints
x
y
Description
Pointer to the polygon to display.
Number of points specified in the list of points.
X-position of origin.
Y-position of origin.
Additional information
The polyline drawn is automatically closed by connecting the endpoint to the starting
point.
GUI_EnlargePolygon()
Description
Enlarges a polygon on all sides by a specified length in pixels.
Prototype
void GUI_EnlargePolygon(GUI_POINT
* pDest,
const GUI_POINT * pSrc,
int
NumPoints,
int
Len);
Parameter
pDest
pSrc
NumPoints
Len
Description
Pointer to the destination polygon.
Pointer to the source polygon.
Number of points specified in the list of points.
Length (in pixels) by which to enlarge the polygon.
Additional information
Make sure the destination array of points is equal to or larger than the source array.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
127
Example
const GUI_POINT aPoints[] = {
{ 40, 20},
{ 0, 20},
{ 20, 0}
};
GUI_POINT aEnlargedPoints[GUI_COUNTOF(aPoints)];
void Sample(void) {
int i;
GUI_Clear();
GUI_SetDrawMode(GUI_DM_XOR);
GUI_FillPolygon(aPoints, GUI_COUNTOF(aPoints), 140, 110);
for (i = 1; i < 10; i++) {
GUI_EnlargePolygon(aEnlargedPoints, aPoints, GUI_COUNTOF(aPoints), i * 5);
GUI_FillPolygon(aEnlargedPoints, GUI_COUNTOF(aPoints), 140, 110);
}
}
Screen shot of above example
GUI_FillPolygon()
Description
Draws a filled polygon defined by a list of points in the current window.
Prototype
void GUI_FillPolygon(const GUI_POINT * pPoint, int NumPoints, int x, int y);
Parameter
pPoint
NumPoints
x
y
Description
Pointer to the polygon to display and to fill.
Number of points specified in the list of points.
X-position of origin.
Y-position of origin.
Additional information
The polyline drawn is automatically closed by connecting the endpoint to the starting
point. It is not required that the endpoint touches the outline of the polygon.
Rendering a polygon is done by drawing one or more horizontal lines for each y-position of the polygon. Per default the maximum number of points used to draw the horizontal lines for one y-position is 12 (which means 6 lines per y-position). If this
value needs to be increased, the macro GUI_FP_MAXCOUNT can be used to set the
maximum number of points.
Example
#define GUI_FP_MAXCOUNT 50
GUI_MagnifyPolygon()
Description
Magnifies a polygon by a specified factor.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
128
CHAPTER
2-D Graphic Library
Prototype
void GUI_MagnifyPolygon(GUI_POINT *
pDest,
const GUI_POINT * pSrc,
int
NumPoints,
int
Mag);
Parameter
pDest
pSrc
NumPoints
Mag
Description
Pointer to the destination polygon.
Pointer to the source polygon.
Number of points specified in the list of points.
Factor used to magnify the polygon.
Additional information
Make sure the destination array of points is equal to or larger than the source array.
Note the difference between enlarging and magnifying a polygon. Calling the function
GUI_EnlargePolygon() with the parameter Len = 1 will enlarge the polygon by one
pixel on all sides, whereas the call of GUI_MagnifyPolygon() with the parameter Mag
= 1 will have no effect.
Example
const GUI_POINT aPoints[] = {
{ 0, 20},
{ 40, 20},
{ 20, 0}
};
GUI_POINT aMagnifiedPoints[GUI_COUNTOF(aPoints)];
void Sample(void) {
int Mag, y = 0, Count = 4;
GUI_Clear();
GUI_SetColor(GUI_GREEN);
for (Mag = 1; Mag <= 4; Mag *= 2, Count /= 2) {
int i, x = 0;
GUI_MagnifyPolygon(aMagnifiedPoints, aPoints, GUI_COUNTOF(aPoints), Mag);
for (i = Count; i > 0; i--, x += 40 * Mag) {
GUI_FillPolygon(aMagnifiedPoints, GUI_COUNTOF(aPoints), x, y);
}
y += 20 * Mag;
}
}
Screen shot of above example
GUI_RotatePolygon()
Description
Rotates a polygon by a specified angle.
Prototype
void GUI_RotatePolygon(GUI_POINT *
pDest,
const GUI_POINT * pSrc,
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
129
int
float
Parameter
pDest
pSrc
NumPoints
Angle
NumPoints,
Angle);
Description
Pointer to the destination polygon.
Pointer to the source polygon.
Number of points specified in the list of points.
Angle in radian used to rotate the polygon.
Additional information
Make sure the destination array of points is equal to or larger than the source array.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
130
CHAPTER
2-D Graphic Library
Example
The following example shows how to draw a polygon.
2DGL_DrawPolygon.c in the examples shipped with emWin.
It
is
available
as
#include "gui.h"
/*******************************************************************
*
*
The points of the arrow
*/
static const GUI_POINT aPointArrow[] = {
{ 0, -5},
{-40, -35},
{-10, -25},
{-10, -85},
{ 10, -85},
{ 10, -25},
{ 40, -35},
};
/*******************************************************************
*
*
Draws a polygon
*/
static void DrawPolygon(void) {
int Cnt =0;
GUI_SetBkColor(GUI_WHITE);
GUI_Clear();
GUI_SetFont(&GUI_Font8x16);
GUI_SetColor(0x0);
GUI_DispStringAt("Polygons of arbitrary shape ", 0, 0);
GUI_DispStringAt("in any color", 120, 20);
GUI_SetColor(GUI_BLUE);
/* Draw filled polygon */
GUI_FillPolygon (&aPointArrow[0],7,100,100);
}
/*******************************************************************
*
*
main
*/
void main(void) {
GUI_Init();
DrawPolygon();
while(1)
GUI_Delay(100);
}
Screen shot of above example
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
131
9.11 Drawing circles
GUI_DrawCircle()
Description
Draws the outline of a circle of specified dimensions, at a specified position in the
current window.
Prototype
void GUI_DrawCircle(int x0, int y0, int r);
Parameter
x0
y0
r
Description
X-position of the center of the circle in pixels of the client window.
Y-position of the center of the circle in pixels of the client window.
Radius of the circle (half the diameter).
Minimum: 0 (will result in a point); maximum: 180.
Additional information
This routine cannot handle a radius in excess of 180 because it uses integer calculations that would otherwise produce an overflow. However, for most embedded applications this is not a problem since a circle with diameter 360 is larger than the
display anyhow.
Example
// Draw concentric circles
void ShowCircles(void) {
int i;
for (i=10; i<50; i += 3)
GUI_DrawCircle(120, 60, i);
}
Screen shot of above example
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
132
CHAPTER
2-D Graphic Library
GUI_FillCircle()
Description
Draws a filled circle of specified dimensions at a specified position in the current window.
Prototype
void GUI_FillCircle(int x0, int y0, int r);
Parameter
x0
y0
r
Description
X-position of the center of the circle in pixels of the client window.
Y-position of the center of the circle in pixels of the client window.
Radius of the circle (half the diameter).
Minimum: 0 (will result in a point); maximum: 180.
Additional information
This routine cannot handle a radius in excess of 180.
Example
GUI_FillCircle(120,60,50);
Screen shot of above example
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
133
9.12 Drawing ellipses
GUI_DrawEllipse()
Description
Draws the outline of an ellipse of specified dimensions, at a specified position in the
current window.
Prototype
void GUI_DrawEllipse(int x0, int y0, int rx, int ry);
Parameter
x0
y0
Description
X-position of the center of the circle in pixels of the client window.
Y-position of the center of the circle in pixels of the client window.
rx
X-radius of the ellipse (half the diameter).
Minimum: 0; maximum: 180.
ry
Y-radius of the ellipse (half the diameter).
Minimum: 0; maximum: 180.
Additional information
This routine cannot handle rx/ry parameters in excess of 180 because it uses integer
calculations that would otherwise produce an overflow.
Example
See the GUI_FillEllipse() example.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
134
CHAPTER
2-D Graphic Library
GUI_FillEllipse()
Description
Draws a filled ellipse of specified dimensions at a specified position in the current
window.
Prototype
void GUI_FillEllipse(int x0, int y0, int rx, int ry);
Parameter
x0
y0
Description
X-position of the center of the circle in pixels of the client window.
Y-position of the center of the circle in pixels of the client window.
rx
X-radius of the ellipse (half the diameter).
Minimum: 0; maximum: 180.
ry
Y-radius of the ellipse (half the diameter).
Minimum: 0; maximum: 180.
Additional information
This routine cannot handle a rx/ry parameters in excess of 180.
Example
// Demo ellipses
GUI_SetColor(0xff);
GUI_FillEllipse(100, 180, 50, 70);
GUI_SetColor(0x0);
GUI_DrawEllipse(100, 180, 50, 70);
GUI_SetColor(0x000000);
GUI_FillEllipse(100, 180, 10, 50);
Screen shot of above example
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
135
9.13 Drawing arcs
GUI_DrawArc()
Description
Draws an arc of specified dimensions at a specified position in the current window. An
arc is a section of the outline of a circle.
Prototype
void GUI_DrawArc(int xCenter, int yCenter, int rx, int ry, int a0, int a1);
Parameter
xCenter
yCenter
rx
ry
a0
a1
Description
Horizontal position of the center in pixels of the client window.
Vertical position of the center in pixels of the client window.
X-radius (pixels).
Y-radius (pixels).
Starting angle (degrees).
Ending angle (degrees).
Limitations
Currently the ry parameter is not used. The rx parameter is used instead.
Additional information
GUI_DrawArc() uses the floating-point library. It cannot handle rx/ry parameters in
excess of 180 because it uses integer calculations that would otherwise produce an
overflow.
Example
void DrawArcScale(void) {
int x0 = 160;
int y0 = 180;
int i;
char ac[4];
GUI_SetBkColor(GUI_WHITE);
GUI_Clear();
GUI_SetPenSize( 5 );
GUI_SetTextMode(GUI_TM_TRANS);
GUI_SetFont(&GUI_FontComic18B_ASCII);
GUI_SetColor( GUI_BLACK );
GUI_DrawArc( x0,y0,150, 150,-30, 210 );
GUI_Delay(1000);
for (i=0; i<= 23; i++) {
float a = (-30+i*10)*3.1415926/180;
int x = -141*cos(a)+x0;
int y = -141*sin(a)+y0;
if (i%2 == 0)
GUI_SetPenSize( 5 );
else
GUI_SetPenSize( 4 );
GUI_DrawPoint(x,y);
if (i%2 == 0) {
x = -123*cos(a)+x0;
y = -130*sin(a)+y0;
sprintf(ac, "%d", 10*i);
GUI_SetTextAlign(GUI_TA_VCENTER);
GUI_DispStringHCenterAt(ac,x,y);
}
}
}
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
136
CHAPTER
2-D Graphic Library
Screen shot of above example
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
137
9.14 Drawing graphs
GUI_DrawGraph()
Description
Draws a graph at once.
Prototype
void GUI_DrawGraph(I16 * paY, int NumPoints, int x0, int y0);
Parameter
paY
NumPoints
x0
y0
Description
Pointer to an array containing the Y-values of the graph.
Number of Y-values to be displayed.
Starting point in x.
Starting point in y.
Additional information
The function first sets the line-cursor to the position specified with x0, y0 and the
first Y-value of the given array. Then it starts drawing lines to x0 + 1, y0 + *(paY +
1), x0 + 2, y0 + *(paY + 2) and so on.
Example
#include "GUI.h"
#include <stdlib.h>
I16 aY[100];
void MainTask(void) {
int i;
GUI_Init();
for (i = 0; i < GUI_COUNTOF(aY); i++) {
aY[i] = rand() % 50;
}
GUI_DrawGraph(aY, GUI_COUNTOF(aY), 0, 0);
}
Screen shot of above example
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
138
CHAPTER
2-D Graphic Library
9.15 Drawing pie charts
GUI_DrawPie()
Description
Draws a circle sector.
Prototype
void GUI_DrawPie(int x0, int y0, int r, int a0, int a1, int Type);
Parameter
x0
y0
r
a0
a1
Type
Description
X-position of the center of the circle in pixels of the client window.
Y-position of the center of the circle in pixels of the client window.
Radius of the circle (half the diameter).
Starting angle (degrees).
End angle (degrees).
(reserved for future use, should be 0)
Example
int i, a0, a1;
const unsigned aValues[] = { 100, 135, 190, 240, 340, 360};
const GUI_COLOR aColors[] = { GUI_BLUE, GUI_GREEN,
GUI_RED,
GUI_CYAN, GUI_MAGENTA, GUI_YELLOW };
for (i = 0; i < GUI_COUNTOF(aValues); i++) {
a0 = (i == 0) ? 0 : aValues[i - 1];
a1 = aValues[i];
GUI_SetColor(aColors[i]);
GUI_DrawPie(100, 100, 50, a0, a1, 0);
}
Screen shot of above example
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
139
9.16 Saving and restoring the GUI-context
GUI_RestoreContext()
Description
The function restores the GUI-context.
Prototype
void GUI_RestoreContext(const GUI_CONTEXT * pContext);
Parameter
pContext
Description
Pointer to a GUI_CONTEXT structure containing the new context.
Additional information
The GUI-context contains the current state of the GUI like the text cursor position, a
pointer to the current font and so on. Sometimes it could be useful to save the current state ant to restore it later. For this you can use these functions.
GUI_SaveContext()
Description
The function saves the current GUI-context. (See also GUI_RestoreContext)
Prototype
void GUI_SaveContext(GUI_CONTEXT * pContext);
Parameter
pContext
Description
Pointer to a GUI_CONTEXT structure for saving the current context.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
140
CHAPTER
2-D Graphic Library
9.17 Clipping
GUI_SetClipRect()
Description
Sets the clipping rectangle used for limiting the output.
Prototype
void GUI_SetClipRect(const GUI_RECT * pRect);
Parameter
pRect
Description
Pointer to the rectangle which should be used for clipping. A NULL pointer should be
used to restore the default value.
Additional information
The clipping area is per default limited to the configured (virtual) display size.
Under some circumstances it can be useful to use a smaller clipping rectangle, which
can be set using this function.
The rectangle referred to should remain unchanged until the function is called again
with a NULL pointer.
Example
The following example shows how to use the function:
GUI_RECT Rect = {10, 10, 100, 100};
GUI_SetClipRect(&Rect);
.
. /* Use the clipping area ... */
.
GUI_SetClipRect(NULL);
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
141
Chapter 10
Displaying bitmap files
The recommended and most efficient way to display a bitmap known at compile time
is to use the bitmap converter to convert it into a C file and add it to the project /
makefile. For details about the bitmap converter, refer to the chapter “Bitmap Converter” on page 213.
If the application needs to display images not known at compile time, the image
needs to be available in a graphic file format supported by emWin. In this case, the
image file can reside in memory or on an other storage device; it can be displayed
even if the amount of available memory is less than the size of the image file.
emWin currently supports BMP, JPEG, GIF and PNG file formats.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
142
CHAPTER
Displaying bitmap files
10.1 BMP file support
Although bitmaps which can be used with emWin are normally compiled and linked as
C files with the application, there may be situations when using these types of structures is not desirable. A typical example would be an application that continuously
references new images, such as bitmaps downloaded by the user. The following functions support bmp files which have been loaded into memory.
For images that you plan to re-use (that is, a company logo) it is much more efficient
to compile and link it as C file which can be used directly by emWin. This may be easily done with the Bitmap Converter.
10.1.1 Supported formats
The BMP file format has been defined by Microsoft. There are a number of different
formats as shown in the table below:
Bits per pixel
1
4
4
8
8
16
24
32
Indexed
yes
yes
yes
yes
yes
no
no
no
Compression
no
no
yes
no
yes
no
no
no
Supported
yes
yes
yes
yes
yes
yes
yes
yes
10.1.2 BMP file API
The table below lists the available BMP file related routines in alphabetical order.
Detailed descriptions follows:
Routine
GUI_BMP_Draw()
GUI_BMP_DrawEx()
GUI_BMP_DrawScaled()
Explanation
Draws a BMP file which has been loaded into memory.
Draws a BMP file which needs not to be loaded into memory.
Draws a BMP file with scaling which has been loaded into memory.
GUI_BMP_DrawScaledEx()
Draws a BMP file with scaling which needs not to be loaded into
memory.
GUI_BMP_GetXSize()
Returns the X-size of a BMP file loaded into memory.
GUI_BMP_GetXSizeEx()
Returns the X-size of a BMP file which needs not to be loaded into
memory.
GUI_BMP_GetYSize()
Returns the Y-size of a bitmap loaded into memory.
GUI_BMP_GetYSizeEx()
Returns the Y-size of a BMP file which needs not to be loaded into
memory.
GUI_BMP_Serialize()
GUI_BMP_SerializeEx()
User's & reference manual for emWin V5.10
Creates a BMP-file.
Creates a BMP-file from the given rectangle.
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
143
GUI_BMP_Draw()
Description
Draws a Windows bmp file, which has been loaded into memory, at a specified position in the current window.
Prototype
int GUI_BMP_Draw(const void * pFileData, int x0, int y0);
Parameter
pFileData
x0
y0
Description
Pointer to the start of the memory area in which the bmp file resides.
X-position of the upper left corner of the bitmap in the display.
Y-position of the upper left corner of the bitmap in the display.
Additional information
The table at the beginning of the chapter shows the supported BMP file formats. The
example 2DGL_DrawBMP.c shows how to use the function.
GUI_BMP_DrawEx()
Description
Draws a bmp file, which does not have to be loaded into memory, at a specified position in the current window.
Prototype
int GUI_BMP_DrawEx(GUI_GET_DATA_FUNC * pfGetData, void * p, int x0, int y0);
Parameter
pfGetData
p
x0
y0
Description
Pointer to a function which is called for getting data. For details about the
function, refer to “Getting data with the ...Ex() functions” on page 167.
Void pointer passed to the function pointed by
GetData
pfGetData.
X-position of the upper left corner of the bitmap in the display.
Y-position of the upper left corner of the bitmap in the display.
Return value
Zero on success, nonzero if the function fails.
Additional information
This function is used for drawing bmp files if not enough RAM is available to load the
whole file into memory. The GUI library then calls the function pointed by the parameter pfGetData to read the data. The GetData function needs to return the number
of requested bytes. The maximum number of bytes requested by the GUI is the number of bytes needed for drawing one line of the image.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
144
CHAPTER
Displaying bitmap files
GUI_BMP_DrawScaled()
Description
Draws a bmp file, which has been loaded into memory, at a specified position in the
current window using scaling.
Prototype
int GUI_BMP_DrawScaled(const void * pFileData,
int x0, int y0, int Num, int Denom);
Parameter
pFileData
x0
y0
Num
Denom
Description
Pointer to the start of the memory area in which the bmp file resides.
X-position of the upper left corner of the bitmap in the display.
Y-position of the upper left corner of the bitmap in the display.
Numerator to be used for scaling.
Denominator used for scaling.
Return value
Zero on success, nonzero if the function fails.
Additional information
The function scales the image by building a fraction with the given numerator and
denominator. If for example an image should be shrunk to 2/3 of size the parameter
Num should be 2 and Denom should be 3.
GUI_BMP_DrawScaledEx()
Description
Draws a bmp file, which does not have to be loaded into memory, at a specified position in the current window using scaling.
Prototype
int
GUI_BMP_DrawScaledEx(GUI_GET_DATA_FUNC * pfGetData, void * p,
int
x0,
int
y0,
int
Num,
int
Denom);
Parameter
pfGetData
p
x0
y0
Num
Denom
Description
Pointer to a function which is called for getting data. For details about the
function, refer to “Getting data with the ...Ex() functions” on page 167.
Void pointer passed to the function pointed by
GetData
pfGetData.
X-position of the upper left corner of the bitmap in the display.
Y-position of the upper left corner of the bitmap in the display.
Numerator to be used for scaling.
Denominator used for scaling.
Return value
Zero on success, nonzero if the function fails.
Additional information
The function scales the image by building a fraction with the given numerator and
denominator. If for example an image should be shrunk to 2/3 of size the parameter
Num should be 2 and Denom should be 3.
For more details, refer to “GUI_BMP_DrawEx()” on page 143.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
145
GUI_BMP_GetXSize()
Description
Returns the X-size of a specified bitmap which has been loaded into memory.
Prototype
int GUI_BMP_GetXSize(const void * pFileData);
Parameter
pFileData
Description
Pointer to the start of the memory area in which the bmp file resides.
Return value
X-size of the bitmap.
GUI_BMP_GetXSizeEx()
Description
Returns the X-size of a specified bmp file which does not have to be loaded into memory.
Prototype
int GUI_BMP_GetXSizeEx(GUI_GET_DATA_FUNC * pfGetData, void * p);
Parameter
Description
pfGetData
Pointer to a function which is called for getting data. For details about the
function, refer to “Getting data with the ...Ex() functions” on page 167.
p
Void pointer passed to the function pointed by
GetData
pfGetData.
Return value
X-size of the bitmap.
GUI_BMP_GetYSize()
Description
Returns the Y-size of a specified bitmap which has been loaded into memory.
Prototype
int GUI_BMP_GetYSize(const void * pFileData);;
Parameter
pFileData
Description
Pointer to the start of the memory area in which the bmp file resides.
Return value
Y-size of the bitmap.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
146
CHAPTER
Displaying bitmap files
GUI_BMP_GetYSizeEx()
Description
Returns the Y-size of a specified bmp file which does not have to be loaded into memory.
Prototype
int GUI_BMP_GetYSizeEx(GUI_GET_DATA_FUNC * pfGetData, void * p);
Parameter
Description
pfGetData
Pointer to a function which is called for getting data. For details about the
function, refer to “Getting data with the ...Ex() functions” on page 167.
p
Void pointer passed to the function pointed by
GetData
pfGetData.
Return value
Y-size of the bitmap.
GUI_BMP_Serialize()
Description
The function creates a BMP-file containing the complete contents of the LCD.
Prototype
void GUI_BMP_Serialize(GUI_CALLBACK_VOID_U8_P * pfSerialize, void * p);
Parameter
pfSerialize
p
Description
Pointer to serialization function
Pointer to user defined data passed to serialization function
Additional information
The following example will show how to create a BMP-file under windows.
static void _DrawSomething(void) {
/* Draw something */
GUI_DrawLine(10, 10, 100, 100);
}
static void _WriteByte2File(U8 Data, void * p) {
U32 nWritten;
WriteFile(*((HANDLE *)p), &Data, 1, &nWritten, NULL);
}
static void _ExportToFile(void) {
HANDLE hFile = CreateFile("C:\\GUI_BMP_Serialize.bmp",
GENERIC_WRITE, 0, 0,
CREATE_ALWAYS, FILE_ATTRIBUTE_NORMAL, 0);
GUI_BMP_Serialize(_WriteByte2File, &hFile);
CloseHandle(hFile);
}
void MainTask(void) {
GUI_Init();
_DrawSomething();
_ExportToFile();
}
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
147
GUI_BMP_SerializeEx()
Description
The function creates a BMP-file containing the given area.
Prototype
void GUI_BMP_SerializeEx(GUI_CALLBACK_VOID_U8_P * pfSerialize,
int
x0, int y0, int xSize, int ySize,
void * p);
Parameter
pfSerialize
x0
y0
xSize
ySize
p
Description
Pointer to serialization function.
Start position in X to create the BMP-file.
Start position in Y to create the BMP-file.
Size in X.
Size in Y.
Pointer to user defined data passed to serialization function.
Additional information
Refer to “GUI_BMP_Serialize()” on page 146.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
148
CHAPTER
Displaying bitmap files
10.2 JPEG file support
JPEG (pronounced "jay-peg") is a standardized compression method for full-color and
gray-scale images. JPEG is intended for compressing "real-world" scenes; line drawings, cartoons and other non-realistic images are not its strong suit. JPEG is lossy,
meaning that the output image is not exactly identical to the input image. Hence you
must not use JPEG if you have to have identical output bits. However, on typical photographic images, very good compression levels can be obtained with no visible
change, and remarkably high compression levels are possible if you can tolerate a
low-quality image.
10.2.1 Supported JPEG compression methods
This software implements JPEG baseline, extended-sequential and progressive compression processes. Provision is made for supporting all variants of these processes,
although some uncommon parameter settings aren't implemented yet. For legal reasons, code for the arithmetic-coding variants of JPEG is not distributed. It appears
that the arithmetic coding option of the JPEG spec is covered by patents owned by
IBM, AT&T, and Mitsubishi. Hence arithmetic coding cannot legally be used without
obtaining one or more licenses. For this reason, support for arithmetic coding has not
been included. (Since arithmetic coding provides only a marginal gain over the
unpatented Huffman mode, it is unlikely that very many implementations will support
it.)
The JPEG file support does not contain provision for the hierarchical or lossless processes defined in the standard.
10.2.2 Converting a JPEG file to C source
Under some circumstances it can be useful to add a JPEG file as C file to the project.
In this case the JPEG file first needs to be converted to a C file. This can be done
using the tool Bin2C.exe shipped with emWin. It can be found in the Tools subfolder. It converts the given binary file (in this case the JPEG file) to a C file. The filename of the C file is the same as the binary file name with the file extension ’.c’.
The following steps will show how to embed a JPEG file using Bin2C:
•
Start Bin2C.exe and select the JPEG file to be converted to a C file, for example
’Image.jpeg’ and convert it to a C file.
•
Add the C file to the project.
Example
The following example shows how to display the converted JPEG file:
#include "GUI.h"
#include "Image.c" /* Include the converted C file */
void MainTask(void) {
GUI_Init();
GUI_JPEG_Draw(acImage, sizeof(acImage), 0, 0);
...
}
10.2.3 Displaying JPEG files
The graphic library first decodes the graphic information. If the image has to be
drawn the decoding process takes considerable time. If a JPEG file is used in a frequently called callback routine of the window manager, the decoding process can
take a considerable amount of time. The calculation time can be reduced by the use
of memory devices. The best way would be to draw the image first into a memory
device. In this case the decompression would be executed only one time. For more
information about memory devices, refer to chapter “Memory Devices” on page 247.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
149
10.2.4 Memory usage
The JPEG decompression uses app. 33Kb RAM for decompression independent of the
image size and a size dependent amount of bytes. The RAM requirement can be calculated as follows:
App. RAM requirement = X-Size of image * 80 bytes + 33 Kbytes
The X-size dependent amount depends on the compression type of the JPEG file. The
following table shows some examples:
Size of image in
pixels
Compression
RAM usage
[Kbyte]
RAM usage, size
dependent [Kbyte]
H1V1
160x120
45
12
H2V2
GRAY
160x120
160x120
46
38
13
4
The memory required for the decompression is allocated dynamically by the emWin
memory management system. After drawing the JPEG image the complete RAM will
be released.
10.2.5 Progressive JPEG files
Contrary to baseline and extended-sequential JPEG files progressive JPEGs consist of
multiple scans. Each of these scans is based on the previous scan(s) and refines the
appearance of the JPEG image. This requires scanning the whole file even if only one
line needs to be decompressed.
If enough RAM is configured for the whole image data, the decompression needs only
be done one time. If less RAM is configured, the JPEG decoder uses ’banding’ for
drawing the image. The more bands required the more times the image needs to be
decompressed and the slower the performance. With other words: The more RAM the
better the performance.
10.2.6 JPEG file API
The table below lists the available JPEG file related routines in alphabetical order.
Detailed descriptions follows:
Routine
GUI_JPEG_Draw()
GUI_JPEG_DrawEx()
GUI_JPEG_DrawScaled()
Explanation
Draws a JPEG file which has been loaded into memory.
Draws a JPEG file which needs not to be loaded into memory.
Draws a JPEG file with scaling which has been loaded into memory.
GUI_JPEG_DrawScaledEx()
Draws a JPEG file with scaling which needs not to be loaded into
memory.
GUI_JPEG_GetInfo()
Fills a GUI_JPEG_INFO structure from a JPEG file which has been
loaded into memory.
GUI_JPEG_GetInfoEx()
Fills a GUI_JPEG_INFO structure from a JPEG file which needs not to
be loaded into memory.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
150
CHAPTER
Displaying bitmap files
GUI_JPEG_Draw()
Description
Draws a jpeg file, which has been loaded into memory, at a specified position in the
current window.
Prototype
int GUI_JPEG_Draw(const void * pFileData, int DataSize, int x0, int y0);
Parameter
pFileData
DataSize
x0
y0
Description
Pointer to the start of the memory area in which the jpeg file resides.
Number of bytes of the jpeg file.
X-position of the upper left corner of the bitmap in the display.
Y-position of the upper left corner of the bitmap in the display.
Return value
Zero on success, nonzero if the function fails. (The current implementation always
returns 0)
Additional information
The Sample folder contains the example 2DGL_DrawJPG.c which shows how to use the
function.
GUI_JPEG_DrawEx()
Description
Draws a jpeg file, which does not have to be loaded into memory, at a specified position in the current window.
Prototype
int GUI_JPEG_DrawEx(GUI_GET_DATA_FUNC * pfGetData, void * p,
int
x0,
int
y0);
Parameter
pfGetData
p
x0
y0
Description
Pointer to a function which is called for getting data. For details about the
function, refer to “Getting data with the ...Ex() functions” on page 167.
Void pointer passed to the function pointed by
GetData
pfGetData.
X-position of the upper left corner of the bitmap in the display.
Y-position of the upper left corner of the bitmap in the display.
Return value
Zero on success, nonzero if the function fails. (The current implementation always
returns 0)
Additional information
This function is used for drawing jpegs if not enough RAM is available to load the
whole file into memory. The JPEG library then calls the function pointed by the
parameter pfGetData to read the data.
The GetData function should return the number of available bytes. This could be less
or equal the number of requested bytes. The function needs at least to return 1 new
byte. The Sample folder contains the example 2DGL_DrawJPGScaled.c which shows
how to use a GetData function.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
151
GUI_JPEG_DrawScaled()
Description
Draws a jpeg file, which has been loaded into memory, at a specified position in the
current window using scaling.
Prototype
int
GUI_JPEG_DrawScaled(const void * pFileData, int DataSize,
int x0, int y0, int Num, int Denom);
Parameter
pFileData
DataSize
x0
y0
Num
Denom
Description
Pointer to the start of the memory area in which the jpeg file resides.
Number of bytes of the jpeg file.
X-position of the upper left corner of the bitmap in the display.
Y-position of the upper left corner of the bitmap in the display.
Numerator to be used for scaling.
Denominator used for scaling.
Return value
Zero on success, nonzero if the function fails. (The current implementation always
returns 0)
Additional information
The function scales the image by building a fraction with the given numerator and
denominator. If for example an image should be shrunk to 2/3 of size the parameter
Num should be 2 and Denom should be 3.
The Sample folder contains the example 2DGL_DrawJPGScaled.c which shows how to
draw scaled JPEGs.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
152
CHAPTER
Displaying bitmap files
GUI_JPEG_DrawScaledEx()
Description
Draws a jpeg file, which does not have to be loaded into memory, at a specified position in the current window using scaling.
Prototype
int
GUI_JPEG_DrawScaledEx(GUI_GET_DATA_FUNC * pfGetData, void * p,
int x0, int y0, int Num, int Denom);
Parameter
pfGetData
p
x0
y0
Num
Denom
Description
Pointer to a function which is called for getting data. For details about the
function, refer to “Getting data with the ...Ex() functions” on page 167.
Void pointer passed to the function pointed by
GetData
pfGetData.
X-position of the upper left corner of the bitmap in the display.
Y-position of the upper left corner of the bitmap in the display.
Numerator to be used for scaling.
Denominator used for scaling.
Return value
Zero on success, nonzero if the function fails. (The current implementation always
returns 0)
Additional information
The function scales the image by building a fraction with the given numerator and
denominator. If for example an image should be shrunk to 2/3 of size the parameter
Num should be 2 and Denom should be 3.
For more details, refer to “GUI_JPEG_DrawEx()” on page 150.
The Sample folder contains the example 2DGL_DrawJPGScaled.c which shows how to
use the function.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
153
GUI_JPEG_GetInfo()
Description
Fills a GUI_JPEG_INFO structure with information about a jpeg file, which has been
loaded into memory.
Prototype
int GUI_JPEG_GetInfo(const void * pFileData,
int DataSize,
GUI_JPEG_INFO * pInfo);
Parameter
Description
Pointer to the start of the memory area in which the jpeg file resides.
pFileData
DataSize
pInfo
Number of bytes of the jpeg file.
Pointer to a GUI_JPEG_INFO structure to be filled by the function.
Return value
Zero on success, nonzero if the function fails.
Elements of GUI_JPEG_INFO
Data type
int
int
Element
XSize
YSize
Description
Pixel size in X of the image.
Pixel size in Y of the image.
Additional information
The Sample folder contains the example 2DGL_DrawJPG.c which shows how to use the
function.
GUI_JPEG_GetInfoEx()
Description
Fills a GUI_JPEG_INFO structure with information about a jpeg file, which does not
have to be loaded into memory.
Prototype
int GUI_JPEG_GetInfoEx(GUI_GET_DATA_FUNC * pfGetData, void * p,
GUI_JPEG_INFO
* pInfo);
Parameter
pfGetData
p
pInfo
Description
Pointer to a function which is called for getting data. For details about the
function, refer to “Getting data with the ...Ex() functions” on page 167.
Void pointer passed to the function pointed by
GetData
pfGetData.
Pointer to a GUI_JPEG_INFO structure to be filled by the function.
Return value
Zero on success, nonzero if the function fails.
Additional information
For more details about the function and the parameters pfGetData and p, refer to
“GUI_JPEG_GetInfo()” on page 153 and “GUI_JPEG_DrawEx()” on page 150.
The Sample folder contains the example 2DGL_DrawJPGScaled.c which shows how to
use the function.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
154
CHAPTER
Displaying bitmap files
10.3 GIF file support
The GIF file format (Graphic Interchange Format) has been developed by the CompuServe Information Service in the 1980s. It has been designed to transmit images
across data networks.
The GIF standard supports interlacing, transparency, application defined data, animations and rendering of raw text. Unsupported data like raw text or application specific data will be ignored by emWin.
GIF files uses the LZW (Lempel-Zif-Welch) file compression method for compressing
the image data. This compression method works without loosing data. The output
image is exactly identical to the input image.
10.3.1 Converting a GIF file to C source
Under some circumstances it can be useful to add a GIF file as C file to the project.
This can be done by exactly the same way as described before under ’JPEG file support’.
10.3.2 Displaying GIF files
The graphic library first decodes the graphic information. If the image has to be
drawn the decoding process takes considerable time. If a GIF file is used in a frequently called callback routine of the window manager, the decoding process can
take a considerable amount of time. The calculation time can be reduced by the use
of memory devices. The best way would be to draw the image first into a memory
device. In this case the decompression would be executed only one time. For more
information about memory devices, refer to the chapter “Memory Devices” on
page 247.
10.3.3 Memory usage
The GIF decompression routine of emWin needs about 16Kbytes of dynamically allocated RAM for decompression. After drawing an image the RAM used for decompressing will be released.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
155
10.3.4 GIF file API
The table below lists the available GIF file related routines in alphabetical order.
Detailed descriptions follows:
Routine
Explanation
GUI_GIF_Draw()
Draws the first image of a GIF file which has been loaded into
memory.
GUI_GIF_DrawEx()
Draws the first image of a GIF file which needs not to be loaded
into memory.
GUI_GIF_DrawSub()
Draws the given sub image of a GIF file which has been loaded
into memory.
GUI_GIF_DrawSubEx()
Draws the given sub image of a GIF file which needs not to be
loaded into memory.
GUI_GIF_DrawSubScaled()
Draws the given sub image of a GIF file with scaling which has
been loaded into memory.
GUI_GIF_DrawSubScaledEx()
Draws the given sub image of a GIF file with scaling which needs
not to be loaded into memory.
GUI_GIF_GetComment()
Returns the given comment of a GIF file which has been loaded
into memory.
GUI_GIF_GetCommentEx()
Returns the given comment of a GIF file which needs not to be
loaded into memory.
GUI_GIF_GetImageInfo()
Returns information about the given sub image of a GIF file
which has been loaded into memory.
GUI_GIF_GetImageInfoEx()
Returns information about the given sub image of a GIF file
which needs not to be loaded into memory.
GUI_GIF_GetInfo()
Returns information about a GIF file which has been loaded into
memory.
GUI_GIF_GetInfoEx()
Returns information about a GIF file which needs not to be
loaded into memory.
GUI_GIF_GetXSize()
Returns the X-size of a bitmap loaded into memory.
GUI_GIF_GetXSizeEx()
Returns the X-size of a bitmap which needs not to be loaded into
memory.
GUI_GIF_GetYSize()
Returns the Y-size of a bitmap loaded into memory.
GUI_GIF_GetYSizeEx()
Returns the Y-size of a bitmap which needs not to be loaded into
memory.
GUI_GIF_Draw()
Description
Draws the first image of a gif file, which has been loaded into memory, at a specified
position in the current window.
Prototype
int GUI_GIF_Draw(const void * pGIF, U32 NumBytes, int x0, int y0);
Parameter
pGIF
NumBytes
x0
y0
Description
Pointer to the start of the memory area in which the gif file resides.
Number of bytes of the gif file.
X-position of the upper left corner of the bitmap in the display.
Y-position of the upper left corner of the bitmap in the display.
Return value
0 on success, != 0 on error.
Additional information
If the file contains more than one image, the function shows only the first image of
the file. Transparency and interlaced images are supported.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
156
CHAPTER
Displaying bitmap files
GUI_GIF_DrawEx()
Description
Draws a gif file, which does not have to be loaded into memory, at a specified position in the current window.
Prototype
int GUI_GIF_DrawEx(GUI_GET_DATA_FUNC * pfGetData, void * p, int x0, int y0);
Parameter
pfGetData
p
x0
y0
Description
Pointer to a function which is called for getting data. For details about the
function, refer to “Getting data with the ...Ex() functions” on page 167.
Void pointer passed to the function pointed by
GetData
pfGetData.
X-position of the upper left corner of the bitmap in the display.
Y-position of the upper left corner of the bitmap in the display.
Return value
Zero on success, nonzero if the function fails.
Additional information
This function is used for drawing gif files if not enough RAM is available to load the
whole file into memory. The library calls the function pointed by the parameter
pfGetData to read the data.
The GetData function should return the number of available bytes. This could be less
or equal the number of requested bytes. The function needs at least to return 1 new
byte.
GUI_GIF_DrawSub()
Description
Draws the given sub image of a gif file, which has been loaded into memory, at a
specified position in the current window.
Prototype
int GUI_GIF_DrawSub(const void * pGIF, U32 NumBytes,
int x0, int y0, int Index);
Parameter
pGIF
NumBytes
x0
y0
Index
Description
Pointer to the start of the memory area in which the gif file resides.
Number of bytes of the gif file.
X-position of the upper left corner of the bitmap in the display.
Y-position of the upper left corner of the bitmap in the display.
Zero-based index of sub image to be shown.
Return value
0 on success, != 0 on error.
Additional information
The function manages the background pixels between the current and the previous
image. If for example sub image #3 should be drawn at offset x20/y20 with a size of
w10/h10 and the previous sub image was shown at x15/y15 with a size of w20/h20
and the background needs to be redrawn, the function fills the pixels between the
images with the background color.
The file 2DGL_DrawGIF.c of the Sample folder shows how to use the function.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
157
GUI_GIF_DrawSubEx()
Description
Draws the given sub image of a gif file, which does not have to be loaded into memory, at a specified position in the current window.
Prototype
int GUI_GIF_DrawSubEx(GUI_GET_DATA_FUNC * pfGetData,
void * p, int x0, int y0, int Index);
Parameter
pfGetData
p
x0
y0
Index
Description
Pointer to a function which is called for getting data. For details about the
function, refer to “Getting data with the ...Ex() functions” on page 167.
Void pointer passed to the function pointed by
GetData
pfGetData.
X-position of the upper left corner of the bitmap in the display.
Y-position of the upper left corner of the bitmap in the display.
Zero-based index of sub image to be shown.
Return value
Zero on success, nonzero if the function fails.
Additional information
This function is used for drawing gif images if not enough RAM is available to load
the whole file into memory. The GUI library then calls the function pointed by the
parameter pfGetData to read the data.
For more details, refer to the “GUI_GIF_DrawEx()” on page 156.
GUI_GIF_DrawSubScaled()
Description
Draws the given sub image of a gif file, which has been loaded into memory, at a
specified position in the current window using scaling.
Prototype
int GUI_GIF_DrawSubScaled(const void * pGIF, U32 NumBytes, int x0, int y0,
int Index, int Num, int Denom);
Parameter
pGif
NumBytes
x0
y0
Index
Num
Denom
Description
Pointer to the start of the memory area in which the gif file resides.
Number of bytes of the gif file.
X-position of the upper left corner of the bitmap in the display.
Y-position of the upper left corner of the bitmap in the display.
Zero-based index of sub image to be shown.
Numerator to be used for scaling.
Denominator used for scaling.
Return value
Zero on success, nonzero if the function fails.
Additional information
The function scales the image by building a fraction with the given numerator and
denominator. If for example an image should be shrunk to 2/3 of size the parameter
Num should be 2 and Denom should be 3.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
158
CHAPTER
Displaying bitmap files
GUI_GIF_DrawSubScaledEx()
Description
Draws the given sub image of a gif file, which does not have to be loaded into memory, at a specified position in the current window using scaling.
Prototype
int GUI_GIF_DrawSubScaledEx(GUI_GET_DATA_FUNC * pfGetData,
void * p,
int x0, int y0,
int
Index, int Num, int Denom);
Parameter
pfGetData
p
x0
y0
Index
Num
Denom
Description
Pointer to a function which is called for getting data. For details about the
function, refer to “Getting data with the ...Ex() functions” on page 167.
Void pointer passed to the function pointed by
GetData
pfGetData.
X-position of the upper left corner of the bitmap in the display.
Y-position of the upper left corner of the bitmap in the display.
Zero-based index of sub image to be shown.
Numerator to be used for scaling.
Denominator used for scaling.
Return value
Zero on success, nonzero if the function fails.
Additional information
The function scales the image by building a fraction with the given numerator and
denominator. If for example an image should be shrunk to 2/3 of size the parameter
Num should be 2 and Denom should be 3.
GUI_GIF_GetComment()
Description
Returns the given comment from a GIF image, which has been loaded into memory.
Prototype
int GUI_GIF_GetComment(const void * pGIF, U32 NumBytes,
U8 * pBuffer, int MaxSize, int Index);
Parameter
pGIF
NumBytes
pBuffer
MaxSize
Index
Description
Pointer to the start of the memory area in which the
gif file resides.
Number of bytes of the gif file.
Pointer to a buffer to be filled with the comment.
Size of the buffer.
Zero based index of comment to be returned.
Return value
0 on success, != 0 on error.
Additional information
A GIF file can contain 1 or more comments. The function copies the comment into the
given buffer. If the comment is larger than the given buffer only the bytes which fit
into the buffer will be copied.
The file 2DGL_DrawGIF.c of the Sample folder shows how to use the function.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
159
GUI_GIF_GetCommentEx()
Description
Returns the given comment from a GIF image, which does not have to be loaded into
memory.
Prototype
int GUI_GIF_GetCommentEx(GUI_GET_DATA_FUNC * pfGetData, void * p,
U8 * pBuffer, int MaxSize, int Index);
Parameter
pfGetData
p
pBuffer
MaxSize
Index
Description
Pointer to a function which is called for getting data. For details about the
function, refer to “Getting data with the ...Ex() functions” on page 167.
Void pointer passed to the function pointed by
GetData
pfGetData.
Pointer to a buffer to be filled with the comment.
Size of the buffer.
Zero based index of comment to be returned.
Return value
0 on success, != 0 on error.
Additional information
For details, refer to “GUI_GIF_GetComment()” on page 158.
GUI_GIF_GetImageInfo()
Description
Returns information about the given sub image of a GIF file, which has been loaded
into memory.
Prototype
int GUI_GIF_GetImageInfo(const void * pGIF, U32 NumBytes,
GUI_GIF_IMAGE_INFO * pInfo, int Index);
Parameter
pGIF
NumBytes
pInfo
Index
Description
Pointer to the start of the memory area in which the
gif file resides.
Number of bytes of the gif file.
Pointer to a
GUI_GIF_IMAGE_INFO structure which will be filled by the function.
Zero based index of sub image.
Return value
0 on success, != 0 on error.
Elements of GUI_GIF_IMAGE_INFO
Data type
int
int
int
int
int
Element
xPos
yPos
xSize
ySize
Delay
Description
X position of the last drawn image.
Y position of the last drawn image.
X size of the last drawn image.
Y size of the last drawn image.
Time in 1/100 seconds the image should be shown in a movie.
Additional information
If an image needs be shown as a movie this function should be used to get the time
the sub image should be visible and the next sub image should be shown.
If the delay member is 0 the image should be visible for 1/10 second.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
160
CHAPTER
Displaying bitmap files
GUI_GIF_GetImageInfoEx()
Description
Returns information about the given sub image of a GIF file, which needs not to be
loaded into memory.
Prototype
int GUI_GIF_GetImageInfoEx(GUI_GET_DATA_FUNC * pfGetData, void * p,
GUI_GIF_IMAGE_INFO * pInfo, int Index);
Parameter
pfGetData
p
pInfo
Index
Description
Pointer to a function which is called for getting data. For details about the
function, refer to “Getting data with the ...Ex() functions” on page 167.
GetData
Void pointer passed to the function pointed by
Pointer to a
pfGetData.
GUI_GIF_IMAGE_INFO structure which will be filled by the function.
Zero based index of sub image.
Return value
0 on success, != 0 on error.
Additional information
For more details, refer to “GUI_GIF_GetImageInfo()” on page 159.
GUI_GIF_GetInfo()
Description
Returns an information structure with information about the size and the number of
sub images within the given GIF file, which has been loaded into memory.
Prototype
int GUI_GIF_GetInfo(const void * pGIF, U32 NumBytes, GUI_GIF_INFO * pInfo);
Parameter
pGIF
NumBytes
pInfo
Description
Pointer to the start of the memory area in which the
gif file resides.
Number of bytes of the gif file.
Pointer to a
GUI_GIF_INFO structure which will be filled by this function.
Return value
0 on success, != 0 on error.
Elements of GUI_GIF_INFO
Data type
int
int
int
Element
XSize
YSize
NumImages
Description
Pixel size in X of the image.
Pixel size in Y of the image.
Number of sub images in the file.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
161
GUI_GIF_GetInfoEx()
Description
Returns an information structure with information about the size and the number of
sub images within the given GIF file, which needs not to be loaded into memory.
Prototype
int GUI_GIF_GetInfoEx(GUI_GET_DATA_FUNC * pfGetData, void * p,
GUI_GIF_INFO * pInfo);;
Parameter
pfGetData
p
pInfo
Description
Pointer to a function which is called for getting data. For details about the
function, refer to “Getting data with the ...Ex() functions” on page 167.
GetData
Void pointer passed to the function pointed by
Pointer to a
pfGetData.
GUI_GIF_INFO structure which will be filled by this function.
Return value
0 on success, != 0 on error.
Elements of GUI_GIF_INFO
Data type
int
int
int
Element
XSize
YSize
NumImages
Description
Pixel size in X of the image.
Pixel size in Y of the image.
Number of sub images in the file.
GUI_GIF_GetXSize()
Description
Returns the X-size of a specified GIF image, which has been loaded into memory.
Prototype
int GUI_GIF_GetXSize(const void * pGIF);
Parameter
pGIF
Description
Pointer to the start of the memory area in which the
gif file resides.
Return value
X-size of the GIF image.
GUI_GIF_GetXSizeEx()
Description
Returns the X-size of a specified GIF image, which needs not to be loaded into memory.
Prototype
int GUI_GIF_GetXSizeEx(GUI_GET_DATA_FUNC * pfGetData, void * p);
Parameter
Description
pfGetData
Pointer to a function which is called for getting data. For details about the
function, refer to “Getting data with the ...Ex() functions” on page 167.
p
Void pointer passed to the function pointed by
GetData
pfGetData.
Return value
X-size of the GIF image.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
162
CHAPTER
Displaying bitmap files
GUI_GIF_GetYSize()
Description
Returns the Y-size of a specified GIF image, which has been loaded into memory.
Prototype
int GUI_GIF_GetYSize(const void * pGIF);;
Parameter
pGIF
Description
Pointer to the start of the memory area in which the
bmp file resides.
Return value
Y-size of the GIF image.
GUI_GIF_GetYSizeEx()
Description
Returns the Y-size of a specified GIF image, which needs not to be loaded into memory.
Prototype
int GUI_GIF_GetYSizeEx(GUI_GET_DATA_FUNC * pfGetData, void * p);
Parameter
Description
pfGetData
Pointer to a function which is called for getting data. For details about the GetData
function, please refer to “Getting data with the ...Ex() functions” on page 167.
p
Void pointer passed to the function pointed by
pfGetData.
Return value
Y-size of the GIF image.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
163
10.4 PNG file support
The PNG (Portable Network Graphics) format is an image format which offers lossless
data compression and alpha blending by using a non-patented data compression
method. Version 1.0 of the PNG specification has been released in 1996. Since the
end of 2003 PNG is an international standard (ISO/IEC 15948).
The emWin implementation of PNG support is based on the ’libpng’ library from Glenn
Randers-Pehrson, Guy Eric Schalnat and Andreas Dilger which is freely available
under www.libpng.org. It is used in emWin under the copyright notice in
GUI\PNG\png.h which allows using the library without any limitation.
The PNG library of emWin is available under www.segger.com/link/emwin_png.zip.
10.4.1 Converting a PNG file to C source
Under some circumstances it can be useful to add a PNG file as C file to the project.
This can be done by exactly the same way as described before under ’JPEG file support’. Further the bitmap converter is able to load PNG files and can convert them
into C bitmap files.
10.4.2 Displaying PNG files
The graphic library first decodes the graphic information. If the image has to be
drawn the decoding process takes considerable time. If a PNG file is used in a frequently called callback routine of the window manager, the decoding process can
take a considerable amount of time. The calculation time can be reduced by the use
of memory devices. The best way would be to draw the image first into a memory
device. In this case the decompression would be executed only one time. For more
information about memory devices, refer to the chapter “Memory Devices” on
page 247.
10.4.3 Memory usage
The PNG decompression uses app. 21Kbytes of RAM for decompression independent
of the image size and a size dependent amount of bytes. The RAM requirement can
be calculated as follows:
App. RAM requirement = (X-Size + 1) * Y-Size * 4 + 21Kbytes
10.4.4 PNG file API
The table below lists the available PNG file related routines in alphabetical order.
Detailed descriptions follows:#
Routine
GUI_PNG_Draw()
GUI_PNG_DrawEx()
GUI_PNG_GetXSize()
Explanation
Draws the PNG file which has been loaded into memory.
Draws the PNG file which needs not to be loaded into memory.
Returns the X-size of a bitmap loaded into memory.
GUI_PNG_GetXSizeEx()
Returns the X-size of a bitmap which needs not to be loaded into
memory.
GUI_PNG_GetYSize()
Returns the Y-size of a bitmap loaded into memory.
GUI_PNG_GetYSizeEx()
Returns the Y-size of a bitmap which needs not to be loaded into
memory.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
164
CHAPTER
Displaying bitmap files
GUI_PNG_Draw()
Description
Draws a png file, which has been loaded into memory, at a specified position in the
current window.
Prototype
int GUI_PNG_Draw(const void * pFileData, int FileSize, int x0, int y0);
Parameter
pFileData
FileSize
x0
y0
Description
Pointer to the start of the memory area in which the png file resides.
Number of bytes of the jpeg file.
X-position of the upper left corner of the bitmap in the display.
Y-position of the upper left corner of the bitmap in the display.
Return value
Zero on success, nonzero if the function fails. (The current implementation always
returns 0)
Additional information
The Sample folder contains the example 2DGL_DrawPNG.c which shows how to use the
function.
GUI_PNG_DrawEx()
Description
Draws a png file, which does not have to be loaded into memory, at a specified position in the current window.
Prototype
int GUI_PNG_DrawEx(GUI_GET_DATA_FUNC * pfGetData, void * p, int x0, int y0);
Parameter
pfGetData
p
x0
y0
Description
Pointer to a function which is called for getting data. For details about the
function, refer to “Getting data with the ...Ex() functions” on page 167.
Void pointer passed to the function pointed by
GetData
pfGetData.
X-position of the upper left corner of the bitmap in the display.
Y-position of the upper left corner of the bitmap in the display.
Return value
Zero on success, nonzero if the function fails.
Additional information
This function is used for drawing png if not enough RAM is available to load the whole
file into memory. The PNG library then calls the function pointed by the parameter
pfGetData to read the data.
The GetData function should return the number of available bytes. This could be less
or equal the number of requested bytes. The function needs at least to return 1 new
byte. Note that the PNG library internally allocates a buffer for the complete image.
This can not be avoided by using this function.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
165
GUI_PNG_GetXSize()
Description
Returns the X-size of a specified PNG image, which has been loaded into memory.
Prototype
int GUI_PNG_GetXSize(const void * pFileData, int FileSize);
Parameter
pFileData
FileSize
Description
Pointer to the start of the memory area in which the
png file resides.
Size of the file in bytes.
Return value
X-size of the PNG image.
GUI_PNG_GetXSizeEx()
Description
Returns the X-size of a specified PNG image, which needs not to be loaded into memory.
Prototype
int GUI_PNG_GetXSizeEx(GUI_GET_DATA_FUNC * pfGetData, void * p);
Parameter
Description
pfGetData
Pointer to a function which is called for getting data. For details about the
function, refer to “Getting data with the ...Ex() functions” on page 167.
p
Void pointer passed to the function pointed by
GetData
pfGetData.
Return value
X-size of the PNG image.
GUI_PNG_GetYSize()
Description
Returns the Y-size of a specified PNG image, which has been loaded into memory.
Prototype
int GUI_PNG_GetYSize(const void * pFileData, int FileSize);
Parameter
pFileData
FileSize
Description
Pointer to the start of the memory area in which the
png file resides.
Size of the file in bytes.
Return value
Y-size of the PNG image.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
166
CHAPTER
Displaying bitmap files
GUI_PNG_GetYSizeEx()
Description
Returns the X-size of a specified PNG image, which needs not to be loaded into memory.
Prototype
int GUI_PNG_GetYSizeEx(GUI_GET_DATA_FUNC * pfGetData, void * p);
Parameter
Description
pfGetData
Pointer to a function which is called for getting data. For details about the
function, refer to “Getting data with the ...Ex() functions” on page 167.
p
Void pointer passed to the function pointed by
GetData
pfGetData.
Return value
Y-size of the PNG image.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
167
10.5 Getting data with the ...Ex() functions
As well as streamed bitmaps, using BMP, GIF, JPEG and PNG files also works without
loading the whole image into RAM. For this case the ...Ex() functions can be used.
Common for all of these functions is the use of a ’GetData’ function. Please note that
the ’GetData’ function has to work slightly different depending on the actual task it is
used for. See table of parameters and examples below.
Prototype of the ’GetData’ function
int GUI_GET_DATA_FUNC(void
* p,
const U8 * * ppData,
unsigned
NumBytes, U32
Off)
Parameter
Description
Application defined void pointer.
p
BMP, GIF & JPEG:
Pointer to a pointer to U8. The ’GetData’ function has to set the pointer to the location the requested data resides in.
ppData
Streamed bitmaps & PNG:
Pointer to U8. The location the pointer points to has to be filled by the ’GetData’
function.
NumBytesReq
StartOfFile
Number of requested bytes.
If this flag is 1, the data pointer should be set to the beginning of the data stream.
Example (BMP, GIF and JPEG)
The following code excerpt shows how to implement a ’GetData’ function for usage
with BMP, GIF and JPEG data:
static char _acBuffer[0x200];
int APP_GetData(void * p, const U8 * * ppData, unsigned NumBytesReq, U32 Off) {
HANDLE * phFile;
DWORD
NumBytesRead;
phFile = (HANDLE *)p;
//
// Check buffer size
//
if (NumBytesReq > sizeof(_acBuffer)) {
NumBytesReq = sizeof(_acBuffer);
}
//
// Set file pointer to the required position
//
SetFilePointer(*phFile, Off, 0, FILE_BEGIN);
//
// Read data into buffer
//
ReadFile(*phFile, _acBuffer, NumBytesReq, &NumBytesRead, NULL);
//
// Set data pointer to the beginning of the buffer
//
*ppData = _acBuffer;
//
// Return number of available bytes
//
return NumBytesRead;
}
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
168
CHAPTER
Displaying bitmap files
Example (PNG and streamed bitmap)
The following code excerpt shows how to implement a ’GetData’ function for usage
with PNG and streamed bitmap data:
static char acBuffer[0x200];
int APP_GetData(void * p, const U8 * * ppData, unsigned NumBytesReq, U32 Off) {
HANDLE * phFile;
DWORD
NumBytesRead;
U8
* pData;
pData = (U8 *)*ppData;
phFile = (HANDLE *)p;
//
// Set file pointer to the required position
//
SetFilePointer(*phFile, Off, 0, FILE_BEGIN);
//
// Read data into buffer
//
ReadFile(*phFile, pData, NumBytesReq, &NumBytesRead, NULL);
//
// Return number of available bytes
//
return NumBytesRead;
}
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
169
Chapter 11
Fonts
This chapter describes the various methods of font support in emWin. The most common fonts are shipped with emWin as C font files. All of them contain the ASCII character set and most of them also the characters of ISO 8859-1. In fact, you will
probably find that these fonts are fully sufficient for your application. For detailed
information about the individual fonts, refer to “Standard fonts” on page 192.
emWin is compiled for 8-bit characters, allowing for a maximum of 256 different
character codes out of which the first 32 are reserved as control characters. The
characters that are available depends on the selected font.
For accessing the full Unicode area of 65536 possible characters emWin supports
UTF8 decoding which is described in the chapter “Foreign Language Support” on
page 801.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
170
CHAPTER
Fonts
11.1 Introduction
The first way of font support was the possibility to use C files with font definitions
containing bitmaps with 1bpp pixel information for each character. This kind of font
support was limited to use only the fonts which are compiled with the application.
Over time, the font support has been improved regarding font quality, ROM requirement, performance, scalability and the ability to add further fonts at run time.
In the meantime emWin fonts cover antialiasing, drawing of compound characters
like required in Thai language, fonts located on external non addressable media and
TrueType support. Except the TrueType font format, which is a vector font, all other
kinds of fonts are bitmap fonts.
11.2 Font types
emWin supports different internal types of fonts defined by emWin and the common
used TrueType fonts.
Monospaced bitmap fonts
Each character of a monospaced bitmap font has the same size. In a proportional
font each character has its own width, whereas in a monospaced font the width is
defined only one time. The pixel information is saved with 1bpp and covers the whole
character area.
Proportional bitmap fonts
Each character of a proportional bitmap font has the same height and its own width.
The pixel information is saved with 1bpp and covers the whole character area.
Antialiased fonts with 2 bpp antialiasing information
Each character has the same height and its own width. The pixel information is saved
with 2bpp antialiasing information and covers the whole character area.
Antialiased fonts with 4 bpp antialiasing information
Each character has the same height and its own width. The pixel information is saved
with 4bpp antialiasing information and covers the whole character area.
Extended proportional bitmap fonts
Each character of an extended proportional bitmap font has its own height and its
own width. The pixel information is saved with 1bpp and covers only the areas of the
glyph bitmaps.
Extended proportional bitmap fonts with 2 bpp antialiasing information
Each character has the same height and its own width. The pixel information is saved
with 2bpp antialiasing information and covers only the areas of the glyph bitmaps.
Extended proportional bitmap fonts with 4 bpp antialiasing information
Each character has the same height and its own width. The pixel information is saved
with 4bpp antialiasing information and covers only the areas of the glyph bitmaps.
Extended proportional bitmap fonts, framed
In some cases, for example in situations, where the background color is unknown at
compile time, it can make sense to use a framed font. A framed font is always drawn
in transparent mode regardless of the current settings. The character pixels are
drawn in the currently selected foreground color and the frame is drawn in background color. A good contrast between foreground and background color makes sure,
that the text can be read regardless of the background.
Note that this type of font is not suitable for compound characters like in Thai language. It is also not suitable for Arabic fonts. The picture below shows some framed
text in front of a photo:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
171
Table of font types
The following table shows the difference between the font types. The pictures only
show the pixel information saved in the font file:
Prop. bitmap
font
Prop. bitmap
font, AA2
Ext. prop.
bitmap font,
AA2
Ext. prop.
bitmap font,
AA4
Prop. bitmap
font, AA2
Ext. prop.
bitmap font
Ext. prop.
bitmap font,
framed
TrueType vector fonts
The TrueType font support of emWin means support for the TrueType font file format
described later in this chapter.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
172
CHAPTER
Fonts
11.3 Font formats
The following explains the differences between the supported font formats, when to
use them and what is required to be able to use them.
11.3.1 C file format
This is the most common way of using fonts. When using fonts in form of C files, we
recommend compiling all available fonts and linking them as library modules or putting all of the font object files in a library which you can link with your application.
This way you can be sure that only the fonts which are needed by your application
are actually linked. The font converter (described in a separate manual) may be used
to create additional fonts.
When to use
This format should be used if the fonts are known at compile time and if there is
enough addressable memory available for the font data.
Requirements
In order to be able to use a font C file in your application, the following requirements
must be met:
•
•
•
The font file is in a form compatible with emWin as C file, object file or library.
The font file is linked with your application.
The font declaration is contained in the application.
Format description
A font C file contains at first the pixel information of all characters included by the
font. It is followed by a character information table with size information about each
character. This table is followed by range information structures for each contiguous
area of characters contained in the font file, whereas each structure points to the
next one. Note that this method can enlarge a font file a lot if using many separate
characters. After the range information structures a GUI_FONT structure follows with
the main information like type, pixel size and so on of the font.
11.3.2 System Independent Font (SIF) format
System independent fonts are binary data blocks containing the font information. The
font converter can be used to create system independent fonts. This tool is not part
of the basic package. A short description follows later in this chapter.
When to use
This format should be used if the fonts are not known at compile time and if there is
enough addressable memory available for the font data.
Requirements
In order to be able to use a SIF font file in your application, it is required that the
whole file reside in addressable memory (ROM or RAM).
Format description
The structure of a SIF file is nearly the same as of a C file. It contains the same information in binary format. The sequence of the file components is vice versa: General
font information followed by range information structures, character information
table and at least pixel information of all characters.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
173
11.3.3 External Bitmap Font (XBF) format
As well as SIF fonts XBF fonts are binary data blocks containing the font information
and the font converter can be used to create XBF files. The Font converter is not part
of the emWin basic package. For details about how to create external binary fonts,
please refer to the font converter documentation.
Contrary to other fonts, XBF fonts do not have to reside in memory when they are
used, whereas all other kinds of emWin fonts need to reside completely in memory.
The XBF font file can remain on any external media while it is used. Data access is
done by a ’GetData’ callback function whereas all other fonts need to reside in
addressable memory (RAM or ROM). The advantage of XBF fonts is that it is possible
to use very large fonts on systems with little memory.
When to use
This format should be used if there is not enough addressable memory available for
the font data and if there is any kind of external media available for storing the fonts.
Requirements
In order to be able to use a XBF font in your application, a ’GetData’ callback function
is required which is responsible for getting font data.
Format description
This format differs in general from SIF and C file format. At first it contains a small
block of general font information including the lowest character code and the highest
character code. It is followed by an access table containing offset and data size information for each character between lowest and highest character code. If a character
does not exist, this information is zero for the according character. The access table
is followed by the character information of all characters containing pixel data and
character size information.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
174
CHAPTER
Fonts
11.3.4 TrueType Font (TTF) format
TrueType is an outline font standard developed by Apple Computer. It offers font
developers a high degree of control over how their fonts are displayed at various font
heights. Contrary to bitmap fonts which are based on bitmaps for each character,
TrueType fonts are based on vector graphics. The advantage of the vector representation is the loss-free scalability.
This implies that each character first needs to be rasterized into a bitmap before it is
drawn. To avoid rasterization each time a character is drawn the bitmap data normally is cached by the font engine. This requires a fast CPU and enough RAM.
The emWin TTF package is not part of the shipment. It is freely available under
www.segger.com/link/emwin_freetype.zip.
Licensing
The emWin implementation of the TTF support is based on the FreeType font library
from David Turner, Robert Wilhelm and Werner Lemberg which is freely available
under www.freetype.org. It is used in emWin under the FreeType license which can
be found under GUI\TrueType\FTL.txt. It has been slightly adapted and a ’glue’ layer
with GUI-functions has been added.
When to use
This format should be used if fonts need to be scaleable at run-time.
Requirements
•
•
•
CPU: TTF support works only on 32 bit CPUs. Our definition of a 32bit CPU:
sizeof(int) = 4.
ROM: The ROM requirement of the TTF engine is app. 250K. The exact size
depends on the CPU, the compiler and the optimization level of the compiler.
RAM: The RAM requirement of the library depends a lot on the used fonts. The
basic RAM requirement of the TTF engine is app. 50K. When creating a GUI font
with GUI_TTF_CreateFont() the font engine loads all font tables defined in the
TTF file required to generate the characters. The table sizes varies a lot between
the fonts. The additional required amount of RAM for creating a font can be
between a few KB up to more than 1MB. For typical fonts 80-300 Kbytes are
required. It depends on the used font file how much RAM is required. At least the
TTF engine requires a bitmap cache. Per default the engine uses 200K for the
cache. This should be enough for most applications.
The TTF engine allocates its memory via the non emWin functions malloc() and
free(). It must be made sure that these functions work before using the TTF
engine.
Format description
For details about the TTF format, refer to the information available under
www.apple.com.
11.4 Converting a TTF file to C source
Under some circumstances it can be useful to add a TTF file as 'C' file to the project,
for example if no file system is available. This can be done by using the tool
Bin2C.exe shipped with emWin. It can be found in the Tools subfolder. It converts
the given binary file (in this case the TTF file) to a 'C' file.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
175
11.5 Declaring custom fonts
The most recommended way of declaring the prototypes of custom fonts is to put
them into an application defined header file. This should be included from each application source file which uses these fonts. It could look like the following example:
#include "GUI.h"
extern GUI_CONST_STORAGE GUI_FONT GUI_FontApp1;
extern GUI_CONST_STORAGE GUI_FONT GUI_FontApp2;
Note that this kind of declaring prototypes does not work if the fonts should be used
with emWin configuration macros like BUTTON_FONT_DEFAULT or similar. In this case
the fonts need to be declared in the configuration file GUIConf.h. The declaration in
this case can look like the following example:
typedef struct GUI_FONT GUI_FONT;
extern const GUI_FONT GUI_FontApp1;
#define BUTTON_FONT_DEFAULT &GUI_FontApp1
#define EDIT_FONT_DEFAULT
&GUI_FontApp1
The typedef is required because the structure GUI_FONT has not been defined at the
early point where GUIConf.h is included by emWin.
11.6 Selecting a font
emWin offers different fonts, one of which is always selected. This selection can be
changed by calling the function GUI_SetFont() or one of the GUI_XXX_CreateFont()
functions, which select the font to use for all text output to follow for the current
task.
If no font has been selected by your application, the default font is used. This default
is configured in GUIConf.h and can be changed. You should make sure that the
default font is one that you are actually using in your application because the default
font will be linked with your application and will therefore use up ROM memory.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
176
CHAPTER
Fonts
11.7 Font API
The table below lists the available font-related routines in alphabetical order within
their respective categories. Detailed descriptions can be found in the sections that
follow.
Routine
Explanation
C file related font functions
Sets the default font
GUI_SetDefaultFont()
GUI_SetFont()
Sets the current font
’SIF’ file related font functions
GUI_SIF_CreateFont()
Creates and selects a font by passing a pointer to system independent font data.
GUI_SIF_DeleteFont()
Deletes a font created by
GUI_SIF_CreateFont()
’TTF’ file related font functions
Creates a GUI font from a TTF font file.
GUI_TTF_CreateFont()
GUI_TTF_DestroyCache()
GUI_TTF_Done()
GUI_TTF_GetFamilyName()
GUI_TTF_GetStyleName()
GUI_TTF_SetCacheSize()
Destroys the cache of the TTF engine.
Frees all dynamically allocated memory of the TTF engine.
Returns the family name of the font.
Returns the style name of the font.
Can be used to set the default size of the TTF cache.
’XBF’ file related font functions
Creates and selects a font by passing a pointer to a callback
function, which is responsible for getting data from the XBF font
file.
GUI_XBF_CreateFont()
GUI_XBF_DeleteFont()
Deletes a font created by GUI_XBF_CreateFont()
Common font-related functions
GUI_GetCharDistX()
GUI_GetFont()
GUI_GetFontDistY()
GUI_GetFontInfo()
GUI_GetFontSizeY()
GUI_GetLeadingBlankCols()
GUI_GetStringDistX()
GUI_GetTextExtend()
Returns the width in pixels (X-size) of a specified character in the
current font.
Returns a pointer to the currently selected font.
Returns the Y-spacing of the current font.
Returns a structure containing font information.
Returns the height in pixels (Y-size) of the current font.
Returns the number of leading blank pixel columns of the given
character.
Returns the X-size of a text using the current font.
Evaluates the size of a text using the current font
Returns the number of trailing blank pixel columns of the given
GUI_GetTrailingBlankCols() character.
Returns the Y-spacing of a particular font.
GUI_GetYDistOfFont()
Returns the Y-size of a particular font.
GUI_GetYSizeOfFont()
Evaluates whether a specified character is in a particular font.
GUI_IsInFont()
Sets the default font to be used after GUI_Init().
GUI_SetDefaultFont()
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
177
11.8 C file related font functions
GUI_SetDefaultFont()
Description
Sets the font to be used by default for text output.
Prototype
void GUI_SetDefaultFont(const GUI_FONT GUI_UNI_PTR * pFont);
Parameter
pFont
Description
Pointer to the font to be selected as default
Additional information
This function is intended to be used in GUI_X_Config(). Defining GUI_DEFAULT_FONT
is not mandatory anymore. If there is neither defined GUI_DEFAULT_FONT nor
GUI_SetDefaultFont is called, GUI_Font6x8 will be set as the default Font. If none of
the emWin fonts shall be used, GUI_DEFAULT_FONT has to be defined by NULL and a
custom font needs to be set as default with this function.
GUI_SetFont()
Description
Sets the font to be used for text output.
Prototype
const GUI_FONT * GUI_SetFont(const GUI_FONT * pNewFont);
Parameter
pFont
Description
Pointer to the font to be selected and used.
Return value
Returns a pointer to the previously selected font so that it may be buffered.
Examples
Displays example text in 3 different sizes, restoring the former font afterwards:
const GUI_FONT GUI_FLASH * OldFont;
OldFont = GUI_SetFont(&GUI_Font8x16);
// Buffer old font
GUI_DispStringAt("This text is 8 by 16 pixels",0,0);
GUI_SetFont(&GUI_Font6x8);
GUI_DispStringAt("This text is 6 by 8 pixels",0,20);
GUI_SetFont(&GUI_Font8);
GUI_DispStringAt("This text is proportional",0,40);
GUI_SetFont(OldFont);
// Restore old font
Screen shot of above example:
Displays text and value in different fonts:
GUI_SetFont(&GUI_Font6x8);
GUI_DispString("The result is: "); // Disp text
GUI_SetFont(&GUI_Font8x8);
GUI_DispDec(42,2);
// Disp value
Screen shot of above example:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
178
CHAPTER
Fonts
11.9 ’SIF’ file related font functions
GUI_SIF_CreateFont()
Description
Sets the font to be used by passing a pointer to system independent font data.
Prototype
void GUI_SIF_CreateFont(void
* pFontData,
GUI_FONT
* pFont,
const GUI_SIF_TYPE * pFontType);
Parameter
pFontData
pFont
pFontType
Description
Pointer to the system independent font data.
Pointer to a
GUI_FONT structure in RAM filled by the function.
See table below.
Permitted values for element pFontType
GUI_SIF_TYPE_PROP
Should be used if the parameter
points to a proportional font.
GUI_SIF_TYPE_PROP_EXT
Should be used if the parameter pFont
points to an extended proportional font.
GUI_SIF_TYPE_PROP_FRM
Should be used if the parameter pFont
points to an extended proportional framed
font.
GUI_SIF_TYPE_PROP_AA2
Should be used if the parameter pFont
points to a proportional font, which uses
2bpp antialiasing.
GUI_SIF_TYPE_PROP_AA4
Should be used if the parameter pFont
points to a proportional font, which uses
4bpp antialiasing.
GUI_SIF_TYPE_PROP_AA2_EXT
Should be used if the parameter pFont
points to an extended proportional font,
which uses 2bpp antialiasing.
GUI_SIF_TYPE_PROP_AA4_EXT
Should be used if the parameter pFont
points to an extended proportional font,
which uses 4bpp antialiasing.
pFont
Additional information
Contrary to the emWin standard fonts which must be compiled and linked with the
application program, system independent fonts (SIF) are binary data blocks containing the font information. The font converter can be used to create system independent fonts. This tool is not part of the basic package. A short description follows later
in this chapter. For details about how to create system independent fonts, refer to
the font converter documentation.
When using this function emWin needs to fill a GUI_FONT structure with the font
information. The user needs to pass a pointer to this structure in the parameter
pFont. The contents of this structure must remain valid during the use of the font.
The function does not know what kind of font should be created. To tell the function
the type of the font to be created it must be passed in the parameter pFontType.
This has been done to avoid linkage of code which is not required.
Example
static GUI_FONT _Font; /* Font structure in RAM */
void MainTask(void) {
GUI_Init();
GUI_SIF_CreateFont(_DownloadedFont, &_Font, GUI_SIF_TYPE_PROP);
GUI_DispString("Hello World!");
while (1) {
GUI_Exec();
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
179
}
}
GUI_SIF_DeleteFont()
Description
Deletes a font pointed by the parameter pFont.
Prototype
void GUI_SIF_DeleteFont(GUI_FONT * pFont);
Parameter
pFont
Description
Pointer to the font to be deleted.
Additional information
After using a font created with GUI_SIF_CreateFont() the font should be deleted if
not used anymore.
Example
GUI_FONT _Font; /* Font structure in RAM */
GUI_SIF_CreateFont(_DownloadedFont, &_Font, GUI_SIF_TYPE_PROP);
/*
Use the font
*/
GUI_SIF_DeleteFont(&_Font);
11.10 ’TTF’ file related font functions
The emWin implementation of TTF file support is based on the FreeType font library
from David Turner, Robert Wilhelm and Werner Lemberg. For details, refer to “TrueType Font (TTF) format” on page 174.
GUI_TTF_CreateFont()
Description
Creates and selects an emWin font by using a TTF font file.
Prototype
int GUI_TTF_CreateFont(GUI_FONT * pFont, GUI_TTF_CS * pCS);
Parameter
pFont
pCS
Description
Pointer to a
Pointer to a
GUI_FONT structure in RAM filled by the function.
GUI_TTF_CS structure containing the creation parameters.
Return value
0 on success, 1 on error.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
180
CHAPTER
Fonts
Elements of GUI_TTF_CS
Data type
Element
Description
pTTF
Pointer to GUI_TTF_DATA structure which contains location
and size of the font file to be used.
PixelHeight
PixelHeight
Pixel height of new font. It means the height of the surrounding rectangle between the glyphs 'g' and 'f'. Note that it is not
the distance between two lines of text. With other words the
value returned by GUI_GetFontSizeY() is not identical
with this value.
FaceIndex
FaceIndex
Some font files can contain more than one font face. In case
of more than one face this index specifies the zero based face
index to be used to create the font. Usually 0.
GUI_TTF_DATA *
Elements of GUI_TTF_DATA
Data type
const void *
NumBytes
Element
pData
NumBytes
Description
Pointer to TTF font file in addressable memory area.
Size of file in bytes.
Additional information
When using the function the first time it initializes the TTF engine and the internal
cache system. If the cache should use other values as defined per default it needs to
be configured before the first call of this function. For details how to configure the
cache, refer to “GUI_TTF_SetCacheSize()” on page 182.
The internal data cache manages the complete mechanism of creating fonts and
caching bitmap data. Font faces are uniquely identified from the cache by the
address given in parameter pTTF and the parameter FaceIndex, which normally is 0.
If the same font file for example should be used for creating fonts of different sizes
the parameter pTTF should point to the same location of a GUI_TTF_DATA structure.
The parameter PixelHeight specifies the height of the surrounding rectangle
between the glyphs ’g’ and ’f’. Note that the value of PixelHeight this is not the
same as the offset from one line of text to the next line.
Example
GUI_TTF_CS
Cs0, Cs1;
GUI_TTF_DATA Data;
GUI_FONT
Font0, Font1;
/* Set parameters for accessing the font file */
Data.pData
= aTTF;
/* Address */
Data.NumBytes
= sizeof(aTTF); /* Size */
/* Set creation parameters of first font */
Cs0.pTTF
= &Data;
/* Use address of GUI_TTF_DATA */
Cs0.PixelHeight = 24;
/* Pixel height */
Cs0.FaceIndex
= 0;
/* Initialize to 0 */
/* Set creation parameters of second font */
Cs1.pTTF
= &Data;
/* Use address of GUI_TTF_DATA */
Cs1.PixelHeight = 48;
/* Pixel height */
Cs1.FaceIndex
= 0;
/* Initialize to 0 */
/* Create 2 fonts */
GUI_TTF_CreateFont(&Font0, &Cs0);
GUI_TTF_CreateFont(&Font1, &Cs1);
/* Draw something using the fonts */
GUI_SetFont(&Font0);
GUI_DispString("Hello world\n");
GUI_SetFont(&Font1);
GUI_DispString("Hello world");
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
181
GUI_TTF_DestroyCache()
Description
This function frees all memory allocated by the TTF cache system and destroys the
cache.
Prototype
void GUI_TTF_DestroyCache(void);
Additional information
The next time GUI_TTF_CreateFont() is used emWin automatically creates and initializes a new cache.
GUI_TTF_Done()
Description
This function frees all memory allocated by the TTF engine and its internal cache system.
Prototype
void GUI_TTF_Done(void);
Additional information
The next time GUI_TTF_CreateFont() is used emWin automatically initializes the TTF
engine and creates and initializes a new cache.
GUI_TTF_GetFamilyName()
Description
The function returns the font family name defined in the font file.
Prototype
int GUI_TTF_GetFamilyName(GUI_FONT * pFont, char * pBuffer, int NumBytes);
Parameter
pFont
pBuffer
NumBytes
Description
Pointer to a GUI_FONT structure which has been created using
GUI_TTF_CreateFont().
Buffer to be filled with the family name.
Size of buffer in bytes.
Return value
0 on success, 1 on error.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
182
CHAPTER
Fonts
GUI_TTF_GetStyleName()
Description
The function returns the style name (bold, regular, ...) defined in the font file.
Prototype
int GUI_TTF_GetStyleName(GUI_FONT * pFont, char * pBuffer, int NumBytes);
Parameter
pFont
pBuffer
NumBytes
Description
Pointer to a GUI_FONT structure which has been created using
GUI_TTF_CreateFont().
Buffer to be filled with the style name.
Size of buffer in bytes.
Return value
0 on success, 1 on error.
GUI_TTF_SetCacheSize()
Description
Sets the size parameters
GUI_TTF_CreateFont().
used
to
create
the
cache
on
the
first
call
of
Prototype
void GUI_TTF_SetCacheSize(unsigned MaxFaces,
unsigned MaxSizes, U32 MaxBytes);
Parameter
Description
MaxFaces
Maximum number of font faces the cache should be able to handle simultaneously. 0
selects default value.
MaxSizes
Maximum number of size objects the cache should be able to handle simultaneously.
0 selects default value.
MaxBytes
Maximum number of bytes used for the bitmap cache. 0 selects default value.
Additional information
If for example 3 font faces should be used, each with 2 sizes, the cache should be
able to manage 6 size objects.
The default values used by the TTF engine are: 2 faces, 4 size objects and 200K of
bitmap data cache.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
183
11.11 ’XBF’ file related font functions
GUI_XBF_CreateFont()
Description
Creates and selects a font by passing a pointer to a callback function, which is
responsible for getting data from the XBF font file.
Prototype
int GUI_XBF_CreateFont(GUI_FONT
GUI_XBF_DATA
const GUI_XBF_TYPE
GUI_XBF_GET_DATA_FUNC
void
Parameter
pFont
pXBF_Data
pFontType
*
*
*
*
*
pFont,
pXBF_Data,
pFontType,
pfGetData,
pVoid);
Description
Pointer to a
GUI_FONT structure in RAM filled by the function.
Pointer to a GUI_XBF_DATA structure in RAM filled by the function.
See table below.
pfGetData
Pointer to a callback function which is responsible for getting data from the font file.
See prototype below.
pVoid
Application defined pointer passed to the ’GetData’ callback function.
Permitted values for element pFontType
GUI_XBF_TYPE_PROP
Should be used if the parameter
points to a proportional font.
GUI_XBF_TYPE_PROP_EXT
Should be used if the parameter pFont
points to an extended proportional font.
GUI_XBF_TYPE_PROP_FRM
Should be used if the parameter pFont
points to an extended framed proportional
font.
GUI_XBF_TYPE_PROP_AA2_EXT
Should be used if the parameter pFont
points to an extended proportional font,
which uses 2bpp antialiasing.
GUI_XBF_TYPE_PROP_AA4_EXT
Should be used if the parameter pFont
points to an extended framed proportional
font, which uses 4bpp antialiasing.
pFont
GUI_XBF_GET_DATA_FUNC - Description
int GUI_XBF_GET_DATA_FUNC(U32
Off,
U16
NumBytes,
void * pVoid, void * pBuffer);
The function has to set pBuffer to point to the location the requested data
resides in. For an example of a ’GetData’ function, please refer to “Getting
data with the ...Ex() functions” on page 167.
Additional information
The parameter pfGetData should point to an application defined callback routine,
which is responsible for getting data from the font. Parameter pVoid is passed to the
callback function when requesting font data. It can be used for example to pass a file
handle to the callback function.
The function requires pointers to a GUI_FONT structure and a GUI_XBF_DATA structure. The function will fill these structures with font information. It is required, that
the contents of these structures remain valid during the usage of the font. The function does not know what kind of XBF font has to be created, so the parameter pFontType has to be used to tell the function the type of the font to be created. This has
been done to avoid unnecessary linkage of code.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
184
CHAPTER
Fonts
The maximum number of data bytes per character is limited to 200 per default. This
should cover the most requirements. If loading a character with more bytes a warning will be generated in the debug version. The default value can be increased by
adding the following define to the file GUIConf.h:
#define GUI_MAX_XBF_BYTES 500 // Sets the maximum number of bytes/chars to 500
Example
static
static
GUI_FONT
Font;
/* GUI_FONT structure in RAM */
GUI_XBF_DATA XBF_Data; /* GUI_XBF_DATA structure in RAM */
static int _cbGetData(U32 Off, U16 NumBytes, void * pVoid, void * pBuffer) {
/* The pVoid pointer may be used to get a file handle */
.../* TBD */
/* Set file pointer to the given position */
.../* TBD */
/* Read the required number of bytes into the given buffer */
.../* TBD */
}
void CreateXBF_Font(void * pVoid) {
GUI_XBF_CreateFont(&Font,
&XBF_Data,
GUI_XBF_TYPE_PROP,
_cbGetData,
pVoid);
/*
/*
/*
/*
/*
Pointer to GUI_FONT structure */
Pointer to GUI_XBF_DATA structure */
Font type to be created */
Pointer to callback function */
Pointer to be passed to callback */
}
GUI_XBF_DeleteFont()
Description
Deletes a XBF font pointed by the parameter pFont.
Prototype
void GUI_XBF_DeleteFont(GUI_FONT * pFont);
Parameter
pFont
Description
Pointer to the font to be deleted.
Additional information
After using a font created with GUI_XBF_CreateFont() the font should be deleted if
not used anymore.
11.12 Common font-related functions
GUI_GetFont()
Description
Returns a pointer to the currently selected font.
Prototype
const GUI_FONT * GUI_GetFont(void)
GUI_GetCharDistX()
Description
Returns the width in pixels (X-size) used to display a specified character in the currently selected font.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
185
Prototype
int
GUI_GetCharDistX(U16 c);
Parameter
Description
Character to calculate width from.
c
GUI_GetFontDistY()
Description
Returns the Y-spacing of the currently selected font.
Prototype
int GUI_GetFontDistY(void);
Additional information
The Y-spacing is the vertical distance in pixels between two adjacent lines of text.
The returned value is the YDist value of the entry for the currently selected font.
The returned value is valid for both proportional and monospaced fonts.
GUI_GetFontInfo()
Description
Calculates a pointer to a GUI_FONTINFO structure of a particular font.
Prototype
void GUI_GetFontInfo(const GUI_FONT*pFont, GUI_FONTINFO* pfi);
Parameter
pFont
pfi
Description
Pointer to the font.
Pointer to a GUI_FONTINFO structure.
Additional information
The definition of the GUI_FONTINFO structure is as follows:
typedef struct {
U16 Flags;
} GUI_FONTINFO;
The member variable flags can take the following values:
GUI_FONTINFO_FLAG_PROP
GUI_FONTINFO_FLAG_MONO
GUI_FONTINFO_FLAG_AA
GUI_FONTINFO_FLAG_AA2
GUI_FONTINFO_FLAG_AA4
Example
Gets the info of GUI_Font6x8. After the calculation, FontInfo.Flags contains the
flag GUI_FONTINFO_FLAG_MONO.
GUI_FONTINFO FontInfo;
GUI_GetFontInfo(&GUI_Font6x8, &FontInfo);
GUI_GetFontSizeY()
Description
Returns the height in pixels (Y-size) of the currently selected font.
Prototype
int GUI_GetFontSizeY(void);
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
186
CHAPTER
Fonts
Additional information
The returned value is the YSize value of the entry for the currently selected font.
This value is less than or equal to the Y-spacing returned by the function
GUI_GetFontDistY().
The returned value is valid for both proportional and monospaced fonts.
GUI_GetLeadingBlankCols()
Description
Returns the number of leading blank pixel columns in the currently selected font for
the given character.
Prototype
int GUI_GetLeadingBlankCols(U16 c);
Parameter
Description
Character to be used.
c
Example
The result for the character ’B’ shown in the screenshot above should be 2.
GUI_GetStringDistX()
Description
Returns the X-size used to display a specified string in the currently selected font.
Prototype
int
GUI_GetStringDistX(const char GUI_FAR *s);
Parameter
Description
Pointer to the string.
s
GUI_GetTextExtend()
Description
Calculates the size of a given string using the current font.
Prototype
void GUI_GetTextExtend(GUI_RECT* pRect, const char* s, int Len);
Parameter
pRect
s
Len
Description
Pointer to GUI_RECT-structure to store result.
Pointer to the string.
Number of characters of the string.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
187
GUI_GetTrailingBlankCols()
Description
Returns the number of trailing blank pixel columns in the currently selected font for
the given character.
Prototype
int GUI_GetTrailingBlankCols(U16 c);
Parameter
Description
Character to be used.
c
Example
The result for the character ’B’ shown in the screenshot above should be 1.
GUI_GetYDistOfFont()
Description
Returns the Y-spacing of a particular font.
Prototype
int
GUI_GetYDistOfFont(const GUI_FONT* pFont);
Parameter
pFont
Description
Pointer to the font.
Additional information
(see GUI_GetFontDistY())
GUI_GetYSizeOfFont()
Description
Returns the Y-size of a particular font.
Prototype
int
GUI_GetYSizeOfFont(const GUI_FONT* pFont);
Parameter
pFont
Description
Pointer to the font.
Additional information
(see GUI_GetFontSizeY())
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
188
CHAPTER
Fonts
GUI_IsInFont()
Description
Evaluates whether a particular font contains a specified character or not.
Prototype
char GUI_IsInFont(const GUI_FONT * pFont, U16 c);
Parameter
Description
Pointer to the font.
pFont
c
Character to be searched for.
Additional information
If the pointer pFont is set to 0, the currently selected font is used.
Example
Evaluates whether the font GUI_FontD32 contains an "X":
if (GUI_IsInFont(&GUI_FontD32, 'X') == 0) {
GUI_DispString("GUI_FontD32 does not contains 'X'");
}
GUI_SetDefaultFont()
Description
Sets the default font to be used after GUI_Init().
Prototype
void GUI_SetDefaultFont(const GUI_FONT GUI_UNI_PTR * pFont);
Parameter
Description
Pointer to the font to be used.
pFont
11.13 Character sets
11.13.1 ASCII
emWin supports the full set of ASCII characters. These are the following 96 characters from 32 to 127:
Hex
0
1
2
!
2x
3
4
5
6
"#
$
%
&
7
8
9
A
B
C
D
E
F
'(
)
*
+
,
-
.
/
3x
0
1
2
3
4
5
6
7
8
9
:
;
<
=
>
?
4x
@
A
B
C
D
E
F
G
H
I
J
K
L
M
N
O
5x
P
Q
R
S
T
U
V
W
X
Y
Z
[
\
]
^
_
`a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
q
r
s
t
u
v
w
x
y
z
{
|
}
~
6x
7x
p
Unfortunately, as ASCII stands for American Standard Code for Information Interchange, it is designed for American needs. It does not include any of the special
characters used in European languages, such as Ä, Ö, Ü, á, à, and others. There is no
single standard for these "European extensions" of the ASCII set of characters; several different ones exist. The one used on the Internet and by most Windows programs is ISO 8859-1, a superset of the ASCII set of characters.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
189
11.13.2 ISO 8859-1 Western Latin character set
emWin supports the ISO 8859-1, which defines characters as listed below:
Code
Description
Char
160
non-breaking space
161
inverted exclamation
162
cent sign
¢
163
pound sterling
£
¡
164
general currency sign
¤
165
yen sign
¥
166
broken vertical bar
¦
167
section sign
§
168
umlaut (dieresis)
¨
169
copyright
©
170
feminine ordinal
ª
171
left angle quote, guillemotleft
«
¬
172
not sign
173
soft hyphen
174
registered trademark
®
175
macron accent
¯
176
degree sign
°
177
178
plus or minus
superscript two
±
²
179
180
superscript three
acute accent
³
´
181
182
micro sign
paragraph sign
µ
¶
183
184
middle dot
cedilla
·
¸
185
186
superscript one
masculine ordinal
¹
º
187
188
right angle quote, guillemot right
fraction one-fourth
»
¼
189
190
fraction one-half
fraction three-fourth
½
¾
191
192
inverted question mark
capital A, grave accent
¿
À
193
194
capital A, acute accent
capital A, circumflex accent
Á
Â
195
196
capital A, tilde
capital A, dieresis or umlaut mark
Ã
Ä
197
198
capital A, ring
capital A, diphthong (ligature)
Å
Æ
199
200
capital C, cedilla
capital E, grave accent
Ç
È
201
202
capital E, acute accent
capital E, circumflex accent
É
Ê
203
204
capital E, dieresis or umlaut mark
capital I, grave accent
Ë
Ì
205
206
capital I, acute accent
capital I, circumflex accent
Í
Î
207
208
capital I, dieresis or umlaut mark
Eth, Icelandic
Ï
Ð
209
210
N, tilde
capital O, grave accent
Ñ
Ò
211
212
capital O, acute accent
capital O, circumflex accent
Ó
Ô
213
214
capital O, tilde
capital O, dieresis or umlaut mark
Õ
Ö
215
multiply sign
×
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
190
CHAPTER
Code
Description
Fonts
Char
216
capital O, slash
Ø
217
capital U, grave accent
Ù
218
capital U, acute accent
Ú
219
capital U, circumflex accent
Û
220
capital U, dieresis or umlaut mark
Ü
221
capital Y, acute accent
Ý
222
THORN, Icelandic
Þ
223
sharp s, German (s-z ligature)
ß
224
small a, grave accent
à
225
small a, acute accent
á
226
small a, circumflex accent
â
227
small a, tilde
ã
228
small a, dieresis or umlaut mark
ä
229
small a, ring
å
230
small ae diphthong (ligature)
æ
231
cedilla
ç
232
small e, grave accent
è
233
small e, acute accent
é
234
small e, circumflex accent
ê
235
small e, dieresis or umlaut mark
ë
236
small i, grave accent
ì
237
238
small i, acute accent
small i, circumflex accent
í
î
239
240
small i, dieresis or umlaut mark
small eth, Icelandic
ï
ð
241
242
small n, tilde
small o, grave accent
ñ
ò
243
244
small o, acute accent
small o, circumflex accent
ó
õ
245
246
small o, tilde
small o, dieresis or umlaut mark
õ
ö
247
248
division sign
small o, slash
÷
ø
249
250
small u, grave accent
small u, acute accent
ù
ú
251
252
small u, circumflex accent
small u, dieresis or umlaut mark
û
ü
253
254
small y, acute accent
small thorn, Icelandic
ý
þ
255
small y, dieresis or umlaut mark
ÿ
11.13.3 Unicode
Unicode is the ultimate in character coding. It is an international standard based on
ASCII and ISO 8859-1. Contrary to ASCII, UNICODE requires 16-bit characters
because all characters have their own code. Currently, more than 30,000 different
characters are defined. However, not all of the character images are defined in
emWin. It is the responsibility of the user to define these additional characters. Contact SEGGER Microcontroller GmbH & Co. KG or your distributor, as we may already
have the character set that you need.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
191
11.14 Font converter
Fonts which can be used with emWin must be defined as GUI_FONT structures in C.
The structures -- or rather the font data which is referenced by these structures -can be rather large. It is very time-consuming and inefficient to generate these fonts
manually. We therefore recommend using the font converter, which automatically
generates C files from fonts.
The font converter is a simple Windows program. You need only to load an installed
Windows font into the program, edit it if you want or have to, and save it as a C file.
The C file may then be compiled, allowing the font to be shown on your display with
emWin on demand.
The character codes 0x00 - 0x1F and 0x80 - 0x9F are disabled by default. The following is a example screen shot of the font converter with a font loaded:
The font converter is described in a separate documentation which can be obtained
by request from SEGGER Microcontroller GmbH & Co. KG ([email protected]).
11.14.1 Adding fonts
Once you have created a font file and linked it to the project, declare the linked font
as extern const GUI_FONT, as shown in the example below.
Example
extern const GUI_FONT GUI_FontNew;
int main(void) {
GUI_Init();
GUI_Clear();
GUI_SetFont(&GUI_FontNew);
GUI_DispString("Hello world\n");
return 0;
}
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
192
CHAPTER
Fonts
11.15 Standard fonts
emWin is shipped with a selection of fonts which should cover most of your needs.
The standard font package contains monospaced and proportional fonts in different
sizes and styles. Monospaced fonts are fonts with a fixed character width, in which
all characters have the same width in pixels. Proportional fonts are fonts in which
each character has its own individual pixel-width.
This chapter provides an overview of the standard emWin fonts.
11.15.1 Font identifier naming convention
All standard fonts are named as follows. The elements of the naming convention are
then explained in the table:
GUI_Font[<style>][<width>x]<height>[x<MagX>x<MagY>][H][B][_<characterset>]
Element
Description
GUI_Font
Standard prefix for all fonts shipped with emWin.
<style>
Specifies a non-standard font style. Example: Comic style in
GUI_FontComic18B_ASCII.
Width of characters, contained only in monospaced fonts.
<width>
<height>
<MagX>
<MagY>
Height of the font in pixels.
Factor of magnification in X, contained only in magnified fonts.
Factor of magnification in Y, contained only in magnified fonts.
H
Abbreviation for "high". Only used if there is more than one font with the same
height. It means that the font appears "higher" than other fonts.
B
Abbreviation for "bold". Used in bold fonts.
<characterset>
Specifies the contents of characters:
ASCII: Only ASCII characters 0x20-0x7E (0x7F).
1: ASCII characters and European extensions 0xA0 - 0xFF.
HK: Hiragana and Katakana.
1HK: ASCII, European extensions, Hiragana and Katakana.
D: Digit fonts, character set: +-.0123456789.
Example 1
GUI_Font16_ASCII
Element
GUI_Font
16
ASCII
Description
Standard font prefix.
Height in pixels.
Font contains ASCII characters only.
Example 2
GUI_Font8x15B_ASCII
Element
GUI_Font
8
x15
B
ASCII
Description
Standard font prefix.
Width of characters.
Height in pixels.
Bold font.
Font contains ASCII characters only.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
193
Example 3
GUI_Font8x16x1x2
Element
GUI_Font
8
x16
x1
x2
Description
Standard font prefix.
Width of characters.
Height in pixels.
Magnification factor in X.
Magnification factor in Y.
11.15.2 Font file naming convention
The names for the font files are similar to the names of the fonts themselves. The
files are named as follows:
F[<width>]<height>[H][B][<characterset>]
Element
F
<width>
<height>
Description
Standard prefix for all fonts files shipped with emWin.
Width of characters, contained only in monospaced fonts.
Height of the font in pixels.
H
Abbreviation for "high". Only used if there is more than one font with the same
height. It means that the font appears "higher" than other fonts.
B
Abbreviation for "bold". Used in bold fonts.
<characterset>
Specifies the contents of characters:
ASCII: Only ASCII characters 0x20-0x7E (0x7F).
1: ASCII characters and European extensions 0xA0 - 0xFF.
HK: Hiragana and Katakana.
1HK: ASCII, European extensions, Hiragana and Katakana.
D: Digit fonts.
11.15.3 Measurement, ROM-size and character set of fonts
The following pages describe the standard fonts shipped with emWin. For each font
there is a measurement diagram, an overview of all characters included and a table
containing the ROM size in bytes and the font files required for use.
The following parameters are used in the measurement diagrams:
Element
F
B
C
L
U
Description
Size of font in Y.
Distance of base line from the top of the font.
Height of capital characters.
Height of lowercase characters.
Size of underlength used by letters such as "g", "j" or "y".
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
194
CHAPTER
Fonts
11.15.4 Proportional fonts
11.15.4.1Overview
The following screenshot gives an overview of all available proportional fonts:
11.15.4.2Measurement, ROM size and used files
The following table shows the measurement, ROM size and used files of the fonts:
Font name
Measurement
ROM
size in
bytes
Used files
GUI_Font8_ASCII
F: 8, B: 7, C: 7, L: 5, U: 1
1562
F08_ASCII.c
GUI_Font8_1
F: 8, B: 7, C: 7, L: 5, U: 1
1562+
1586
F08_ASCII.c
F08_1.c
GUI_Font10S_ASCII
F: 10, B: 8, C: 6, L: 4, U: 2
1760
F10S_ASCII.c
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
195
Font name
Measurement
ROM
size in
bytes
Used files
GUI_Font10S_1
F: 10, B: 8, C: 6, L: 4, U: 2
1760+
1770
F10_ASCII.c
F10_1.c
GUI_Font10_ASCII
F: 10, B: 9, C: 8, L: 6, U: 1
1800
F10_ASCII
GUI_Font10_1
F: 10, B: 9, C: 8, L: 6, U: 1
1800+
2456
F10_ASCII.c
F10_1.c
GUI_Font13_ASCII
F: 13, B: 11, C: 8, L: 6, U: 2
2076
F13_ASCII.c
GUI_Font13_1
F: 13, B: 11, C: 8, L: 6, U: 2
2076+
2149
F13_ASCII.c
F13_1.c
GUI_Font13B_ASCII
F: 13, B: 11, C: 8, L: 6, U: 2
2222
F13B_ASCII.c
GUI_Font13B_1
F: 13, B: 11, C: 8, L: 6, U: 2
2222+
2216
F13B_ASCII.c
F13B_1.c
GUI_Font13H_ASCII
F: 13, B: 11, C: 9, L: 7, U: 2
2232
F13H_ASCII.c
GUI_Font13H_1
F: 13, B: 11, C: 9, L: 7, U: 2
2232+
2291
F13H_ASCII.c
F13H_1.c
GUI_Font13HB_ASCII
F: 13, B: 11, C: 9, L: 7, U: 2
2690
F13HB_ASCII.c
GUI_Font13HB_1
F: 13, B: 11, C: 9, L: 7, U: 2
2690+
2806
F13HB_ASCII.c
F13HB_1.c
GUI_Font16_ASCII
F: 16, B: 13, C: 10, L: 7, U: 3
2714
F16_ASCII.c
GUI_Font16_1
F: 16, B: 13, C: 10, L: 7, U: 3
2714+
3850
F16_ASCII.c
F16_1.c
GUI_Font16_HK
F: 16, B: 13, C: 10, L: 7, U: 3
6950
F16_HK.c
GUI_Font16_1HK
F: 16, B: 13, C: 10, L: 7, U: 3
120+
6950+
2714+
3850
F16_1HK.c
F16_HK.c
F16_ASCII.c
F16_1.c
GUI_Font16B_ASCII
F: 16, B: 13, C: 10, L: 7, U: 3
2690
F16B_ASCII.c
GUI_Font16B_1
F: 16, B: 13, C: 10, L: 7, U: 3
2690+
2790
F16B_ASCII.c
F16B_1.c
GUI_FontComic18B_ASCII
F: 18, B: 15, C: 12, L: 9, U: 3
3572
FComic18B_ASCII.c
GUI_FontComic18B_1
F: 18, B: 15, C: 12, L: 9, U: 3
3572+
4334
FComic18B_ASCII.c
FComic18B_1.c
GUI_Font20_ASCII
F: 20, B: 16, C: 13, L: 10, U: 4
4044
F20_ASCII.c
GUI_Font20_1
F: 20, B: 16, C: 13, L: 10, U: 4
4044+
4244
F20_ASCII.c
F20_1.c
GUI_Font20B_ASCII
F: 20, B: 16, C: 13, L: 10, U: 4
4164
F20B_ASCII.c
GUI_Font20B_1
F: 20, B: 16, C: 13, L: 10, U: 4
4164+
4244
F20B_ASCII.c
F20B_1.c
GUI_Font24_ASCII
F: 24, B: 20, C: 17, L: 13, U: 4
4786
F24_ASCII.c
GUI_Font24_1
F: 24, B: 20, C: 17, L: 13, U: 4
4786+
5022
F24_ASCII.c
F24_1.c
GUI_Font24B_ASCII
F: 24, B: 19, C: 15, L: 11, U: 5
4858
F24B_ASCII.c
GUI_Font24B_1
F: 24, B: 19, C: 15, L: 11, U: 5
4858+
5022
F24B_ASCII.c
F24B_1.c
GUI_FontComic24B_ASCII
F: 24, B: 20, C: 17, L: 13, U: 4
6146
FComic24B_ASCII
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
196
CHAPTER
Font name
Measurement
Fonts
ROM
size in
bytes
Used files
GUI_FontComic24B_1
F: 24, B: 20, C: 17, L: 13, U: 4
6146+
5598
FComic24B_ASCII
FComic24B_1
GUI_Font32_ASCII
F: 32, B: 26, C: 20, L: 15, U: 6
7234
F32_ASCII.c
GUI_Font32_1
F: 32, B: 26, C: 20, L: 15, U: 6
7234+
7734
F32_ASCII.c
F32_1.c
GUI_Font32B_ASCII
F: 32, B: 25, C: 20, L: 15, U: 7
7842
F32B_ASCII.c
GUI_Font32B_1
F: 32, B: 25, C: 20, L: 15, U: 7
7842+
8118
F32B_ASCII.c
F32B_1.c
11.15.4.3Characters
The following shows all characters of all proportional standard fonts:
GUI_Font8_ASCII
GUI_Font8_1
GUI_Font10S_ASCII
GUI_Font10S_1
GUI_Font10_ASCII
GUI_Font10_1
GUI_Font13_ASCII
GUI_Font13_1
GUI_Font13B_ASCII
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
197
GUI_Font13B_1
GUI_Font13H_ASCII
GUI_Font13H_1
GUI_Font13HB_ASCII
GUI_Font13HB_1
GUI_Font16_ASCII
GUI_Font16_1
GUI_Font16_HK
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
198
CHAPTER
Fonts
GUI_Font16_1HK
GUI_Font16B_ASCII
GUI_Font16B_1
GUI_FontComic18B_ASCII
GUI_FontComic18B_1
GUI_Font20_ASCII
GUI_Font20_1
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
199
GUI_Font20B_ASCII
GUI_Font20B_1
GUI_Font24_ASCII
GUI_Font24_1
GUI_Font24B_ASCII
GUI_Font24B_1
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
200
CHAPTER
Fonts
GUI_FontComic24B_ASCII
GUI_FontComic24B_1
GUI_Font32_ASCII
GUI_Font32_1
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
201
GUI_Font32B_ASCII
GUI_Font32B_1
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
202
CHAPTER
Fonts
11.15.5 Proportional fonts, framed
11.15.5.1Overview
The following screenshot gives an overview of all available framed proportional fonts:
11.15.5.2Measurement, ROM size and used files
The following table shows the measurement, ROM size and used files of the fonts:
Font name
GUI_Font20F_ASCII
Measurement
F: 20, B: 19, C: 19, L: 19, U: 1
ROM
size in
bytes
5248
Used files
F20F_ASCII.c
11.15.5.3Characters
The following shows all characters of all framed proportional fonts:
GUI_Font20F_ASCII
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
203
11.15.6 Monospaced fonts
11.15.6.1Overview
The following screenshot gives an overview of all available monospaced fonts:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
204
CHAPTER
Fonts
11.15.6.2Measurement, ROM size and used files
The following table shows the measurement, ROM size and used files of the fonts:
Font name
Measurement
ROM size in
bytes
Used files
GUI_Font4x6
F: 6, B: 5, C: 5, L: 4, U: 1
620
F4x6.c
GUI_Font6x8
F: 8, B: 7, C: 7, L: 5, U: 1
1840
F6x8.c
GUI_Font6x8_ASCII
F: 8, B: 7, C: 7, L: 5, U: 1
1568
F6x8_ASCII.c
GUI_Font6x8_1
F: 8, B: 7, C: 7, L: 5, U: 1
1568+
1584
F6x8_ASCII.c
F6x8_1.c
GUI_Font6x9
F: 9, B: 7, C: 7, L: 5, U: 2
1840
(same ROM location
as GUI_Font6x8)
F6x8.c
GUI_Font8x8
F: 8, B: 7, C: 7, L: 5, U: 1
1840
F8x8.c
GUI_Font8x8_ASCII
F: 8, B: 7, C: 7, L: 5, U: 1
1568
F8x8_ASCII.c
GUI_Font8x8_1
F: 8, B: 7, C: 7, L: 5, U: 1
1568+
1584
F8x8_ASCII.c
F8x8_1.c
GUI_Font8x9
F: 9, B: 7, C: 7, L: 5, U: 2
1840
(same ROM location
as GUI_Font8x8)
F8x8.c
GUI_Font8x10_ASCII
F: 10, B: 9, C: 9, L: 7, U: 1
1770
F8x10_ASCII.c
GUI_Font8x12_ASCII
F: 12, B: 10, C: 9, L: 6, U: 2
1962
F8x12_ASCII.c
GUI_Font8x13_ASCII
F: 13, B: 11, C: 9, L: 6, U: 2
2058
F8x13_ASCII.c
GUI_Font8x13_1
F: 13, B: 11, C: 9, L: 6, U: 2
2058+
2070
F8x13_ASCII.c
F8x13_1.c
GUI_Font8x15B_ASCII
F: 15, B: 12, C: 9, L: 7, U: 3
2250
F8x15_ASCII.c
GUI_Font8x15B_1
F: 15, B: 12, C: 9, L: 7, U: 3
2250+
2262
F8x15B_ASCII.c
F8x15B_1.c
GUI_Font8x16
F: 16, B: 12, C: 10, L: 7, U: 4
3304
F8x16.c
GUI_Font8x17
F: 17, B: 12, C: 10, L: 7, U: 5
3304
(same ROM location
as GUI_Font8x16)
F8x16.c
GUI_Font8x18
F: 18, B: 12, C: 10, L: 7, U: 6
3304
(same ROM location
as GUI_Font8x16)
F8x16.c
GUI_Font8x16x1x2
F: 32, B: 24, C: 20, L: 14, U: 8
3304
(same ROM location
as GUI_Font8x16)
F8x16.c
GUI_Font8x16x2x2
F: 32, B: 24, C: 20, L: 14, U: 8
3304
(same ROM location
as GUI_Font8x16)
F8x16.c
GUI_Font8x16x3x3
F: 48, B: 36, C: 30, L: 21, U: 12
3304
(same ROM location
as GUI_Font8x16)
F8x16.c
GUI_Font8x16_ASCII
F: 16, B: 12, C: 10, L: 7, U: 4
2328
F8x16_ASCII.c
GUI_Font8x16_1
F: 16, B: 12, C: 10, L: 7, U: 4
2328+
2352
F8x16_ASCII.c
F8x16_1.c
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
205
11.15.6.3Characters
The following shows all characters of all monospaced standard fonts:
GUI_Font4x6
GUI_Font6x8
GUI_Font6x8_ASCII
GUI_Font6x8_1
GUI_Font6x9
GUI_Font8x8
GUI_Font8x8_ASCII
GUI_Font8x8_1
GUI_Font8x9
GUI_Font8x10_ASCII
GUI_Font8x12_ASCII
GUI_Font8x13_ASCII
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
206
CHAPTER
Fonts
GUI_Font8x13_1
GUI_Font8x15B_ASCII
GUI_Font8x15B_1
GUI_Font8x16
GUI_Font8x17
GUI_Font8x18
GUI_Font8x16x1x2
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
207
GUI_Font8x16x2x2
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
208
CHAPTER
Fonts
GUI_Font8x16x3x3
GUI_Font8x16_ASCII
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
209
GUI_Font8x16_1
11.15.7 Digit fonts (proportional)
11.15.7.1Overview
The following screenshot gives an overview of all available proportional digit fonts:
11.15.7.2Measurement, ROM size and used files
The following table shows the measurement, ROM size and used files of the fonts:
Font name
Measurement
ROM size in
bytes
Used files
GUI_FontD32
F: 32, C: 31
1574
FD32.c
GUI_FontD48
F: 48, C: 47
3512
FD48.c
GUI_FontD64
F: 64, C: 63
5384
FD64.c
GUI_FontD80
F: 80, C: 79
8840
FD80.c
11.15.7.3Characters
The following shows all characters of all proportional digit fonts:
GUI_FontD32
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
210
CHAPTER
Fonts
GUI_FontD48
GUI_FontD64
GUI_FontD80
11.15.8 Digit fonts (monospaced)
11.15.8.1Overview
The following screenshot gives an overview of all available monospaced digit fonts:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
211
11.15.8.2Measurement, ROM size and used files
The following table shows the measurement, ROM size and used files of the fonts:
Font name
Measurement
ROM size in
bytes
Used files
GUI_FontD24x32
F: 32, C: 31
1606
FD24x32.c
GUI_FontD36x48
F: 48, C: 47
3800
FD36x48.c
GUI_FontD48x64
F: 64, C: 63
5960
FD48x60.c
GUI_FontD60x80
F: 80, C: 79
9800
FD60x80.c
11.15.8.3Characters
The following shows all characters of all monospaced digit fonts:
GUI_FontD24x32
GUI_FontD36x48
GUI_FontD48x64
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
212
CHAPTER
Fonts
GUI_FontD60x80
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
213
Chapter 12
Bitmap Converter
The bitmap converter is a Windows program which is easy to use. Simply load a bitmap (in the form of a bmp or a gif file) into the application. Convert the color format
if you want or have to, and convert it into a C file by saving it in the appropriate format. The C file may then be compiled, allowing the image to be shown on your display with emWin.
Screenshot of the Bitmap Converter
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
214
CHAPTER
Bitmap Converter
12.1 What it does
The bitmap converter is primarily intended as a tool to convert bitmaps from a PC
format to a C file. Bitmaps which can be used with emWin are normally defined as
GUI_BITMAP structures in C. The structures -- or rather the picture data which is referenced by these structures -- can be quite large. It is time-consuming and inefficient to generate these bitmaps manually. We therefore recommend using the bitmap
converter, which automatically generates C files from bitmaps.
An other useful feature is the ability to save images as C stream files. The advantage
against a normal C file is, that these data streams can be located anywhere on any
media whereas C files need to be located in the addressable CPU area.
It also features color conversion, so that the resulting C code is not unnecessarily
large. You would typically reduce the number of bits per pixel in order to reduce
memory consumption. The bitmap converter displays the converted image.
A number of simple functions can be performed with the bitmap converter, including
scaling the size, flipping the bitmap horizontally or vertically, rotating it, and inverting the bitmap indices or colors (these features can be found under the Image menu).
Any further modifications to an image must be made in a bitmap manipulation program such as Adobe Photoshop or Corel Photopaint. It usually makes the most sense
to perform any image modifications in such a program, using the bitmap converter
for converting purposes only.
12.2 Loading a bitmap
12.2.1 Supported input file formats
The bitmap converter basically supports Windows bitmap files (*.bmp), "Graphic
Interchange Format" (*.gif) and "Portable Network Graphics" (*.png):
Windows Bitmap Files (BMP)
The bitmap converter supports the most common bitmap file formats. Bitmap files of
the following formats can be opened by the bitmap converter:
•
•
•
1, 4 or 8 bits per pixel (bpp) with palette;
16, 24 or 32 bpp without palette (full-color mode, in which each color is assigned
an RGB value);
RLE4 and RLE8.
Trying to read bitmap files of other formats will cause an error message of the bitmap
converter.
Graphic Interchange Format (GIF)
The bitmap converter supports reading of one image per GIF file. If the file for example contains a movie consisting of more than one image, the converter reads only the
first image.
Transparency and interlaced GIF images are supported by the converter.
Portable Network Graphic (PNG)
The PNG format is the most recommended format to create images with alpha blending. The bitmap converter supports reading PNG images with alpha channel.
12.2.2 Loading from a file
An image file of one of the supported formats may be opened directly in the bitmap
converter by selecting File/Open.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
215
12.2.3 Using the clipboard
Any other type of bitmap (that is, .jpg, .jpeg, .png, .tif) may be opened with
another program, copied to the clipboard, and pasted into the bitmap converter. This
process will achieve the same effect as loading directly from a file.
12.3 Generating C files from bitmaps
The main function of the bitmap converter is to convert PC-formatted bitmaps into C
files which can be used by emWin. Before doing so, however, it is often desirable to
modify the color palette of an image so that the generated C file is not excessively
large.
The bitmap may be saved as a bmp or a gif file (which can be reloaded and used or
loaded into other bitmap manipulation programs) or as a C file. A C file will serve as
an input file for your C compiler. It may contain a palette (device-independent bitmap, or DIB) or be saved without (device-dependent bitmap, or DDB). DIBs are recommended, as they will display correctly on any display; a DDB will only display
correctly on a display which uses the same palette as the bitmap.
C files may be generated as "C with palette", "C without palette", "C with palette,
compressed" or "C without palette, compressed". For more information on compressed files, see the section "Compressed bitmaps" as well as the example at the
end of the chapter.
12.3.1 Supported bitmap formats
The following table shows the currently available output formats for C files:
Format
Color
depth
Compression
Transparency
Palette
1 bit per pixel
1bpp
no
yes
yes
2 bits per pixel
4 bits per pixel
2bpp
4bpp
no
no
yes
yes
yes
yes
8 bits per pixel
Compressed, RLE4
8bpp
4bpp
no
yes
yes
yes
yes
yes
Compressed, RLE8
High color 555
8bpp
15bpp
yes
no
yes
no
yes
no
High color 555, red and blue swapped
High color 565
15bpp
16bpp
no
no
no
no
no
no
High color 565, red and blue swapped
High color 565, compressed
16bpp
16bpp
no
yes
no
no
no
no
High color 565, red and blue swapped, compressed
True color 888
16bpp
24bpp
yes
no
no
no
no
no
True color 8888 with alpha channel
Alpha channel, compressed
32bpp
8bpp
no
yes
yes
yes
no
no
True color with alpha channel, compressed
32bpp
yes
yes
no
12.3.2 Palette information
A bitmap palette is an array of 24 bit RGB color entries. Bitmaps with a color depth
from 1 - 8 bpp can be saved with (device independent bitmap, DIB) or without palette information (device dependent bitmap DDB).
Device independent bitmaps (DIB)
The color information is stored in the form of an index into the color array. Before
emWin draws a DIB, it converts the 24 bit RGB colors of the bitmap palette into color
indices of the hardware palette. The advantage of using DIBs is that they are hardware independent and can be drawn correctly on systems with different color configurations. The disadvantages are the additional ROM requirement for the palette and
the slower performance because of the color conversion.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
216
CHAPTER
Bitmap Converter
Device dependent bitmaps (DDB)
The pixel information of a DDB is the index of the displays hardware palette. No conversion needs to be done before drawing a DDB. The advantages are less ROM
requirement and a better performance. The disadvantage is that these bitmaps can
not be displayed correctly on systems with other color configurations.
12.3.3 Transparency
A palette based bitmap can be converted to a transparent bitmap. Transparency
means each pixel with index 0 will not produce any output. The command Image/
Transparency can be used to select the color which should be used for transparency.
After selecting the transparent color, the pixel indices of the image will be recalculated, so that the selected color is on position 0 of the bitmap palette. When saving
the bitmap file as C file, it will be saved with the transparency attribute.
12.3.4 Alpha blending
Alpha blending is a method of combining an image with the background to create the
effect of semi transparency. The alpha value of a pixel determines its transparency.
The color of a pixel after drawing the bitmap is a blend of the former color and the
color value in the bitmap. In emWin, logical colors are handled as 32 bit values. The
lower 24 bits are used for the color information and the upper 8 bits are used to
manage the alpha value. An alpha value of 0 means the image is opaque and a value
of 0xFF means completely transparent. Whereas BMP and GIF files do not support
alpha blending PNG files support alpha blending. So the easiest way to create bitmap
files with alpha blending is to load a PNG file. When working with BMP and/or GIF
files the bitmap converter initially has no information about the alpha values.
Loading a PNG file
This is the most recommended way for creating bitmaps with an alpha mask:
After loading
The PNG file contains all required information.
Loading the alpha values from an alpha mask bitmap
This method loads the alpha values from a separate file. Black pixels of the alpha
mask file means opaque and white means transparent. The following table shows an
example:
Starting point
User's & reference manual for emWin V5.10
Alpha mask
Result
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
217
The command File/Load Alpha Mask can be used for loading an alpha mask.
Creating the alpha values from two bitmaps
This method uses the difference between the pixels of two pictures to calculate the
alpha values. The first image should show the item on a black background. The second image should show the same on a white background. The following table shows
an example of how to create the alpha values using the command File/Create
Alpha:
Starting point
Black background
White background
Result
The command File/Create Alpha can be used tor creating the alpha values.
12.3.5 Selecting the best format
emWin supports various formats for the generated C file. It depends on several conditions which will be the ’best’ format and there is no general rule to be used. Color
depth, compression, palette and transparency affect the drawing performance and/or
ROM requirement of the bitmap.
Color depth
In general the lower the color depth the smaller the ROM requirement of the bitmap.
Each display driver has been optimized for drawing 1bpp bitmaps (text) and bitmaps
with the same color depth as the display.
Compression
The supported RLE compression method has the best effect on bitmaps with many
horizontal sequences of equal-colored pixels. Details later in this chapter. The performance is typically slightly slower than drawing uncompressed bitmaps.
Palette
The ROM requirement of a palette is 4 bytes for each color. So a palette of 256 colors
uses 1 Kbyte. Furthermore emWin needs to convert the colors of the palette before
drawing the bitmap. Advantage: Bitmaps are device independent meaning they can
be displayed on any display, independent of its color depth and format.
Transparency
The ROM requirement of transparent bitmaps is the same as without transparency.
The performance is with transparency slightly slower than without.
High color and true color bitmaps
Special consideration is required for bitmaps in these formats. Generally the use of
these formats only make sense on displays with a color depth of 15 bits and above.
Further it is strongly recommended to save the C files in the exact same format used
by the hardware. Note that using the right format will have a positive effect on the
drawing performance. If a high color bitmap for example should be shown on a system with a color depth of 16bpp which has the red and blue components swapped,
the best format is ’High color 565, red and blue swapped’. Already a slightly other
format has the effect, that each pixel needs color conversion, whereas a bitmap in
the right format can be rendered very fast without color conversion. The difference of
drawing performance in this case can be factor 10 and more.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
218
CHAPTER
Bitmap Converter
12.3.6 Saving the file
The basic procedure for using the bitmap converter is illustrated below:
Step 1: Start the application.
The bitmap converter is opened showing an empty
window.
Step 2: Load a bitmap into the bitmap converter.
Choose File/Open .
Locate the document you want to open and click
Open (must be a bmp file).
In this example, the file Logo200.bmp is chosen.
The bitmap converter displays the loaded bitmap.
In this example, the loaded bitmap is in full-color
mode. It must be converted to a palette format
before a C file can be generated.
Step 3: Convert the image if necessary.
Choose Image/Convert
Select the desired palette.
In this example, the option
chosen.
Into.
Best palette is
The bitmap converter displays the converted bitmap.
User's & reference manual for emWin V5.10
The image is unchanged in terms of appearance,
but uses less memory since a palette of only 15
colors is used instead of the full-color mode.
These 15 colors are the only ones actually
required to display this particular image.
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
219
Step 4: Save the bitmap as a C file.
Choose File/Save As .
Select a destination and a name for the C file.
Select the file type. In this example, the file is
saved as C bitmap file."
Click Save .
Step 5: Specify bitmap format.
If the bitmap should be saved as C file the format
should now be specified. Use one of the available
formats shown in the dialog. If the bitmap should
be saved without palette, activate the check box
"Without palette"
The bitmap converter will create a separate file in
the specified destination, containing the C source
code for the bitmap.
12.4 Color conversion
The primary reason for converting the color format of a bitmap is to reduce memory
consumption. The most common way of doing this is by using the option Best palette as in the above example, which customizes the palette of a particular bitmap to
include only the colors which are used in the image. It is especially useful with fullcolor bitmaps in order to make the palette as small as possible while still fully supporting the image. Once a bitmap file has been opened in the bitmap converter, simply select Image/Convert Into/Best palette from the menu. If it is necessary to
keep transparency select Image/Convert Into/Best palette + transparency.
For certain applications, it may be more efficient to use a fixed color palette, chosen
from the menu under Image/Convert Into. For example, suppose a bitmap in fullcolor mode is to be shown on a display which supports only four grayscales. It would
be a waste of memory to keep the image in the original format, since it would only
appear as four grayscales on the display. The full-color bitmap can be converted into
a four-grayscale, 2bpp bitmap for maximum efficiency.
The procedure for conversion would be as follows:
The bitmap converter is opened and the same file
is loaded as in steps 1 and 2 of the previous
example.
The bitmap converter displays the loaded bitmap.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
220
CHAPTER
Choose
Bitmap Converter
Image/Convert Into/Gray4 .
The bitmap converter displays the converted bitmap.
In this example, the image uses less memory
since a palette of only 4 grayscales is used instead
of the full-color mode. If the target display supports only 4 grayscales, there is no use in having
a higher pixel depth as it would only waste memory.
12.5 Generating C stream files
A C stream file consists of the same information as a C file. Contrary to a C file a data
stream can be located anywhere and does not need to be compiled or linked with the
project. All supported output formats described for C files are also available for C
stream files. emWin supports creating bitmaps from data streams and drawing data
streams directly. For details about C stream file support please refer to “Drawing bitmaps” on page 113.
12.6 Compressed bitmaps
The bitmap converter and emWin support run-length encoding (RLE) compression of
bitmaps in the resulting source code files. The RLE compression method works most
efficiently if your bitmap contains many horizontal sequences of equal-colored pixels.
An efficiently compressed bitmap will save a significant amount of space. However,
compression is not recommended for photographic images since they do not normally
have sequences of identical pixels. It should also be noted that a compressed image
may take slightly longer to display.
If you want to save a bitmap using RLE compression, you can do so by selecting one
of the compressed output formats when saving as a C file: "C with palette, compressed" or "C without palette, compressed". There are no special functions needed
for displaying compressed bitmaps; it works in the same way as displaying uncompressed bitmaps.
Compression ratios
The ratio of compression achieved will vary depending on the bitmap used. The more
horizontal uniformity in the image, the better the ratio will be. A higher number of
bits per pixel will also result in a higher degree of compression.
In the bitmap used in the previous examples, the total number of pixels in the image
is (200*94) = 18,800.
Since 2 pixels are stored in 1 byte, the total uncompressed size of the image is
18,800/2 = 9,400 bytes.
The total compressed size for this particular bitmap is 3,803 bytes for 18,800 pixels
(see the example at the end of the chapter).
The ratio of compression can therefore be calculated as 9,400/3,803 = 2.47.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
221
12.7 Using a custom palette
Converting bitmaps to a custom palette and saving them without palette information
can save memory and can increase the performance of bitmap drawing operations.
More efficient memory utilization
Per default each bitmap contains its own palette. Even the smallest bitmaps can contain a large palette with up to 256 colors. In many cases only a small fraction of the
palette is used by the bitmap. If using many of these bitmaps the amount of memory
used by the palettes can grow rapidly.
So it can save much ROM if converting the bitmaps used by emWin to the available
hardware palette and saving them as (D)evice (D)ependent (B)itmaps without palette information.
Better bitmap drawing performance
Before emWin draws a bitmap, it needs to convert each device independent bitmap
palette to the available hardware palette. This is required because the pixel indices of
the bitmap file are indices into the device independent bitmap palette and not to the
available hardware palette.
Converting the bitmap to a DDB means that color conversion at run time is not
required and speeds up the drawing.
12.7.1 Saving a palette file
The bitmap converter can save the palette of the currently loaded bitmap into a palette file which can be used for converting other bitmaps with the command Image/
Convert Into/Custom palette. This requires that the current file is a palette based
file and not a RGB file. To save the palette the command File/Save palette... can
be used.
12.7.2 Palette file format
Custom palette files are simple files defining the available colors for conversion. They
contain the following:
•
•
•
•
Header (8 bytes).
NumColors (U32, 4 bytes).
0 (4 bytes).
U32 Colors[NumColors] (NumColors*4 bytes, type GUI_COLOR).
Total file size is therefore: 16+(NumColors*4) bytes. A custom palette file with 8 colors would be 16+(8*4) = 48 bytes. At this point, a binary editor must be used in
order to create such a file.
The maximum number of colors supported is 256; the minimum is 2.
Example
This example file would define a palette containing 2 colors -- red and white:
0000: 65 6d 57 69 6e 50 61 6c 02 00 00 00 00 00 00 00
0010: ff 00 00 00 ff ff ff 00
The 8 headers make up the first eight bytes of the first line. The U32 is stored lsb
first (big endian) and represents the next four bytes, followed by the four 0 bytes.
Colors are stored 1 byte per color, where the 4th byte is 0 as follows: RRGGBB00.
The second line of code defines the two colors used in this example.
12.7.3 Palette files for fixed palette modes
Using the custom palette feature can even make sense with the most common used
fixed palette modes, not only with custom hardware palettes. For the most palette
based fixed palette modes a palette file can be found in the folder Sample\Palette.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
222
CHAPTER
Bitmap Converter
12.7.4 Converting a bitmap
The command Image/Convert Into/Custom palette should be used for converting
the currently loaded bitmap to a custom palette. The bitmap converter tries to find
the nearest color of the palette file for each pixel of the currently loaded bitmap.
12.8 Command line usage
It is also possible to work with the bitmap converter using the command prompt. All
conversion functions available in the bitmap converter menu are available as commands, and any number of functions may be performed on a bitmap in one command
line.
12.8.1 Format for commands
Commands are entered using the following format:
BmpCvt <filename>.bmp <-command>
(If more than one command is used, one space is typed between each.)
For example, a bitmap with the name logo.bmp is converted into Best palette format and saved as a C file named logo.bmp all at once by entering the following at the
command prompt:
BmpCvt logo.bmp -convertintobestpalette -saveaslogo,1 -exit
Note that while the file to be loaded into the bitmap converter always includes its bmp
extension, no file extension is written in the -saveas command. An integer is used
instead to specify the desired file type. The number 1 in the -saveas command
above designates "C with palette". The -exit command automatically closes the program upon completion. See the table below for more information.
12.8.2 Valid command line options
The following table lists all permitted bitmap converter commands. It can also be
viewed at any time by entering BmpCvt -? at the command prompt.
Command
-convertintobw
-convertintogray4
-convertintogray16
-convertintogray64
-convertintogray256
-convertinto111
-convertinto222
-convertinto233
-convertinto323
-convertinto332
-convertinto8666
-convertintorgb
-convertintobestpalette
-convertintotranspalette
Explanation
Convert to BW.
Convert to Gray4.
Convert to Gray16.
Convert to Gray64.
Convert to Gray256.
Convert to 111.
Convert to 222.
Convert to 233.
Convert to 323.
Convert to 332.
Convert to 8666.
Convert to RGB.
Convert to best palette.
Convert to best palette with
transparency.
Convert to a custom palette.
-convertintocustompalette<filename>
<filename> User-specified filename of desired custom
palette.
-exit
-fliph
User's & reference manual for emWin V5.10
Terminate PC program automatically.
Flip image horizontally.
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
223
Command
Explanation
Flip image vertically.
-flipv
-help
-invertindices
-rotate90cw
Display this box.
Invert indices.
Rotate image by 90 degrees clockwise.
Rotate image by 90 degrees counterclockwise.
-rotate90cc
-rotate180
-saveas<filename>,<type>[,<fmt>[,<noplt>]]
<filename>
Rotate image by 180 degrees.
Save file as
filename .
User-specified file name including the file
extension.
Must be an integer from 1 to 4 as follows:
1 : C with palette (.c file)
<type> 2 : Windows Bitmap file (bmp file)
3 : C stream (.dta file)
4: GIF format (gif file)
<fmt>
Specifies the bitmap format (only if type
== 1):
1: 1 bit per pixel
2: 2 bits per pixel
4: 4 bits per pixel
5: 8 bits per pixel
6: RLE4 compression
7: RLE8 compression
8: High color 565
9: High color 565, red and blue swapped
10: High color 555
11: High color 555, red and blue swapped
12: RLE16 compression
13: RLE16 compression, red and blue
swapped
15: True color 32bpp, compressed
16: True color 32bpp
17: True color 24bpp
18: Alpha channel 8bpp, compressed
If this parameter is not given, the bitmap
converter uses the following default formats in dependence of the number of colors of the bitmap:
Number of colors <= 2: 1 bit per pixel
Number of colors <= 4: 2 bits per pixel
Number of colors <= 16: 4 bits per pixel
Number of colors <= 256: 8 bits per pixel
RGB: High color 565
<noplt> Saves the bitmap with or without palette
(only if type == 1)
0: Save bitmap with palette (default)
1: Save bitmap without palette
-transparency<RGB-Color>
Sets the transparent color.
RGB color which should be used as trans-
<RGB-Color> parent color.
-?
User's & reference manual for emWin V5.10
Display this box.
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
224
CHAPTER
Bitmap Converter
12.9 Example of a converted bitmap
A typical example for the use of the bitmap converter would be the conversion of
your company logo into a C bitmap. Take another look at the example bitmap pictured below:
The bitmap is loaded into the bitmap converter, converted to Best palette, and
saved as "C with palette". The resulting C source code is displayed below (some data
is not shown to conserve space).
Resulting C code (generated by bitmap converter)
/*********************************************************************
*
SEGGER MICROCONTROLLER SYSTEME GmbH
*
*
Solutions for real time microcontroller applications
*
*
www.segger.com
*
**********************************************************************
*
* C-file generated by
*
*
Bitmap converter for emWin V5.05.
*
Compiled Feb 26 2010, 14:49:28
*
(C) 1998 - 2005 Segger Microcontroller Systeme GmbH
*
**********************************************************************
*
* Source file: SeggerLogo200
* Dimensions: 200 * 100
* NumColors:
33
*
**********************************************************************
*/
#include <stdlib.h>
#include "GUI.h"
#ifndef GUI_CONST_STORAGE
#define GUI_CONST_STORAGE const
#endif
/*
Palette
The following are the entries of the palette table.
Every entry is a 32-bit value (of which 24 bits are actually used)
the lower
8 bits represent the Red component,
the middle 8 bits represent the Green component,
the highest 8 bits (of the 24 bits used) represent the Blue component
as follows:
0xBBGGRR
*/
static GUI_CONST_STORAGE GUI_COLOR ColorsSeggerLogo200[] = {
0xFFFFFF,0x353537,0x9C4B37,0xCDCDCD
,0x9A9A9B,0xE6D2CD,0xB57869,0x686869
,0xA25644,0xCEA59B,0xF9F4F3,0x424244
,0xECDDDA,0xF2F2F3,0xAF6D5D,0xD9D9DA
,0x818182,0x5B5B5D,0xB3B3B4,0x4E4E50
,0xD4B0A8,0x747476,0xA7A7A8,0xF3E9E6
,0xC79A8F,0xBB8376,0xDABCB4,0xE0C7C1
,0x8D8D8F,0xE6E6E6,0xA86250,0xC18F82
,0xC0C0C1
};
static GUI_CONST_STORAGE GUI_LOGPALETTE PalSeggerLogo200 = {
33,/* number of entries */
0, /* No transparency */
&ColorsSeggerLogo200[0]
};
static GUI_CONST_STORAGE unsigned char acSeggerLogo200[] = {
0x00, 0x00,
/* Not all data is shown in this example */
0x00, 0x92,
.
.
.
0xC6, 0x22
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
225
0x0A, 0x22
};
extern GUI_CONST_STORAGE GUI_BITMAP bmSeggerLogo200;
GUI_CONST_STORAGE GUI_BITMAP bmSeggerLogo200 = {
200, /* XSize */
100, /* YSize */
200, /* BytesPerLine */
8, /* BitsPerPixel */
acSeggerLogo200, /* Pointer to picture data (indices) */
&PalSeggerLogo200 /* Pointer to palette */
};
/* *** End of file *** */
Compressing the file
We can use the same bitmap image to create a compressed C file, which is done simply by loading and converting the bitmap as before, and saving it as "C with palette,
compressed". The source code is displayed below (some data is not shown to conserve space).
The compressed image size can be seen towards the end of the file as 3,730 bytes for
18,800 pixels.
Resulting compressed C code (generated by bitmap converter)
/*********************************************************************
*
SEGGER MICROCONTROLLER SYSTEME GmbH
*
*
Solutions for real time microcontroller applications
*
*
www.segger.com
*
**********************************************************************
*
* C-file generated by
*
*
Bitmap converter for emWin V5.05.
*
Compiled Feb 26 2010, 14:49:28
*
(C) 1998 - 2005 Segger Microcontroller Systeme GmbH
*
**********************************************************************
*
* Source file: SeggerLogo200_comp
* Dimensions: 200 * 100
* NumColors:
33
*
**********************************************************************
*/
#include <stdlib.h>
#include "GUI.h"
#ifndef GUI_CONST_STORAGE
#define GUI_CONST_STORAGE const
#endif
/*
Palette
The following are the entries of the palette table.
Every entry is a 32-bit value (of which 24 bits are actually used)
the lower
8 bits represent the Red component,
the middle 8 bits represent the Green component,
the highest 8 bits (of the 24 bits used) represent the Blue component
as follows:
0xBBGGRR
*/
static GUI_CONST_STORAGE GUI_COLOR ColorsSeggerLogo200_comp[] = {
0xFFFFFF,0x353537,0x9C4B37,0xCDCDCD
,0x9A9A9B,0xE6D2CD,0xB57869,0x686869
,0xA25644,0xCEA59B,0xF9F4F3,0x424244
,0xECDDDA,0xF2F2F3,0xAF6D5D,0xD9D9DA
,0x818182,0x5B5B5D,0xB3B3B4,0x4E4E50
,0xD4B0A8,0x747476,0xA7A7A8,0xF3E9E6
,0xC79A8F,0xBB8376,0xDABCB4,0xE0C7C1
,0x8D8D8F,0xE6E6E6,0xA86250,0xC18F82
,0xC0C0C1
};
static GUI_CONST_STORAGE GUI_LOGPALETTE PalSeggerLogo200_comp = {
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
226
CHAPTER
Bitmap Converter
33,/* number of entries */
0, /* No transparency */
&ColorsSeggerLogo200_comp[0]
};
static GUI_CONST_STORAGE unsigned char acSeggerLogo200_comp[] = {
/* RLE: 006 Pixels @ 000,000*/ 6, 0x00,
/* RLE: 188 Pixels @ 006,000*/ 188, 0x01,
.
.
.
/* RLE: 188 Pixels @ 006,099*/ 188, 0x01,
/* RLE: 006 Pixels @ 194,099*/ 6, 0x00,
0};
/* 3730 for 20000 pixels */
extern GUI_CONST_STORAGE GUI_BITMAP bmSeggerLogo200_comp;
GUI_CONST_STORAGE GUI_BITMAP bmSeggerLogo200_comp = {
200, /* XSize */
100, /* YSize */
200, /* BytesPerLine */
GUI_COMPRESS_RLE8, /* BitsPerPixel */
acSeggerLogo200_comp, /* Pointer to picture data (indices) */
&PalSeggerLogo200_comp /* Pointer to palette */
,GUI_DRAW_RLE8
};
/* *** End of file *** */
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
227
Chapter 13
Colors
emWin supports black/white, grayscale (monochrome with different intensities) and
color displays. The same user program can be used with any display; only the LCDconfiguration needs to be changed. The color management tries to find the closest
match for any color that should be displayed.
Logical colors are the colors the application deals with. A logical colors is always
defined as an RGB value. This is a 24-bit value containing 8 bits per color as follows:
0xBBGGRR. Therefore, white would be 0xFFFFFF, black would be 0x000000, bright
red 0xFF.
Physical colors are the colors which can actually be displayed by the display. They
are specified in the same 24-bit RGB format as logical colors. At run-time, logical colors are mapped to physical colors.
For displays with few colors (such as monochrome displays or 8/16-color LCDs),
emWin converts them by using an optimized version of the "least-square deviation
search". It compares the color to display (the logical color) with all the available colors that the LCD can actually show (the physical colors) and uses the one that the
LCD-metric considers closest.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
228
CHAPTER
Colors
13.1 Predefined colors
In addition to self-defined colors, some standard colors are predefined in emWin, as
shown in the following table:
Example
/* Set background color to magenta */
GUI_SetBkColor(GUI_MAGENTA);
GUI_Clear();
13.2 The color bar test routine
The color bar example program is used to show 13 color bars as follows:
Black -> Red, White -> Red, Black -> Green, White -> Green, Black -> Blue, White > Blue, Black -> White, Black -> Yellow, White -> Yellow, Black -> Cyan, White ->
Cyan, Black -> Magenta and White -> Magenta.
This little routine may be used on all displays in any color format. Of course, the
results vary depending on the colors that can be displayed; the routine requires a
display size of 320*240 in order to show all colors. The routine is used to demonstrate the effect of the different color settings for displays. It may also be used by a
test program to verify the functionality of the display, to check available colors and
grayscales, as well as to correct color conversion. The screen shots are taken from
the windows simulation and will look exactly like the actual output on your display if
your settings and hardware are working properly. The routine is available as
COLOR_ShowColorBar.c in the examples shipped with emWin.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
229
13.3 Fixed palette modes
The following table lists the available fixed palette color modes and the necessary
identifiers which need to be used when creating a driver- or a memory device.
Detailed descriptions follow.
Identifier
No. available colors
Mask
GUICC_1
2 (black and white)
0x01
GUICC_2
4 (grayscales)
0x03
GUICC_4
16 (grayscales)
0x0F
GUICC_5
32 (grayscales)
0x1F
GUICC_111
8
BGR
GUICC_M111
8
RGB
GUICC_222
64
BBGGRR
GUICC_M222
64
RRGGBB
GUICC_233
256
BBGGGRRR
GUICC_M233
256
RRGGGBBB
GUICC_323
256
BBBGGRRR
GUICC_M323
256
RRRGGBBB
GUICC_332
256
BBBGGGRR
GUICC_M332
256
RRRGGGBB
GUICC_44412
4096
0000BBBBGGGGRRRR
GUICC_M444_12
4096
0000RRRRGGGGBBBB
GUICC_444121
4096
BBBBGGGGRRRR0000
GUICC_44416
4096
0BBBB0GGGG0RRRR0
GUICC_M44416
4096
0RRRR0GGGG0BBBB0
GUICC_555
32768
0BBBBBGGGGGRRRRR
GUICC_M555
32768
0RRRRRGGGGGBBBBB
GUICC_556
65536
BBBBBGGGGGRRRRRR
GUICC_M556
65536
RRRRRGGGGGBBBBBB
GUICC_565
65536
BBBBBGGGGGGRRRRR
GUICC_M565
65536
RRRRRGGGGGGBBBBB
GUICC_655
65536
BBBBBBGGGGGRRRRR
GUICC_M655
65536
RRRRRRGGGGGBBBBB
GUICC_666
262144
BBBBBBGGGGGGRRRRRR
GUICC_M666
262144
RRRRRRGGGGGGBBBBBB
GUICC_666_9
262144
0000000BBBBBBGGG0000000GGGRRRRRR
GUICC_M666_9
262144
0000000RRRRRRGGG0000000GGGBBBBBB
GUICC_822216
256
0xFF
GUICC_84444
240
0xFF
GUICC_8666
232
0xFF
GUICC_86661
233 (232 + transparency)
0xFF
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
230
CHAPTER
Identifier
Colors
No. available colors
Mask
GUICC_888
16777216
BBBBBBBBGGGGGGGGRRRRRRRR
GUICC_M888
16777216
RRRRRRRRGGGGGGGGBBBBBBBB
GUICC_8888
16777216 + 8 bit alpha blending
AAAAAAAABBBBBBBBGGGGGGGGRRRRRRRR
GUICC_M8888
16777216 + 8 bit alpha blending
AAAAAAAARRRRRRRRGGGGGGGGBBBBBBBB
GUICC_0
x
x
13.4 Detailed fixed palette mode description
The following gives a detailed description of the available colors in each predefined
fixed palette mode.
GUICC_1: 1 bpp (black and white)
Use of this mode is necessary for monochrome displays with 1 bit per pixel.
Available colors: 2:
GUICC_2: 2 bpp (4 grayscales)
Use of this mode is necessary for monochrome displays with 2 bits per pixel.
Available colors: 2 x 2 = 4:
GUICC_4: 4 bpp (16 grayscales)
Use of this mode is necessary for monochrome displays with 4 bits per pixel.
Available colors: 2 x 2 x 2 x 2 = 16:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
231
GUICC_5: 5 bpp (32 grayscales)
Use of this mode is necessary for monochrome displays with 5 bits per pixel.
Available colors: 2 x 2 x 2 x 2 x 2 = 32:
GUICC_111: 3 bpp (2 levels per color)
Use this mode if the basic 8 colors are enough, if
your hardware supports only one bit per pixel and
color or if you do not have sufficient video memory
for a higher color depth.
Color mask: BGR
Available colors: 2 x 2 x 2 = 8:
GUICC_M111: 3 bpp (2 levels per color), red and blue swapped
Use this mode if the basic 8 colors are enough, if your hardware supports only one bit
per pixel and color or if you do not have sufficient video memory for a higher color
depth. The available colors are the same as those in 111 mode.
Color mask: RGB
Available colors: 2 x 2 x 2 = 8:
GUICC_222: 6 bpp (4 levels per color)
This mode is a good choice if your hardware does not
have a palette for every individual color. 2 bits per
pixel and color are reserved; usually 1 byte is used
to store one pixel.
Color mask: BBGGRR
Available colors: 4 x 4 x 4 = 64:
GUICC_M222: 6 bpp (4 levels per color), red and blue swapped
This mode is a good choice if your hardware does not have a palette for every individual color. 2 bits per pixel and color are reserved; usually 1 byte is used to store
one pixel. The available colors are the same as those in 222 mode.
Color mask: RRGGBB
Available colors: 4 x 4 x 4 = 64:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
232
CHAPTER
Colors
GUICC_233: 8 bpp
This mode supports 256 colors. 3 bits are used for
the red and green components of the color and 2 bits
for the blue component. As shown in the picture, the
result is 8 grades for green and red and 4 grades for
blue. We discourage the use of this mode because it
do not contain real shades of gray.
Color mask: BBGGGRRR
Available colors: 4 x 8 x 8 = 256:
GUICC_M233: 8 bpp, red and blue swapped
This mode supports 256 colors. 3 bits are used for
the red and green components of the color and 2 bits
for the blue component. The result is 8 grades for
green and blue and 4 grades for red. We discourage
the use of this mode because it do not contain real
shades of gray.
Color mask: RRGGGBBB
Available colors: 4 x 8 x 8 = 256:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
233
GUICC_323: 8 bpp
This mode supports 256 colors. 3 bits are used for
the red and blue components of the color and 2 bits
for the green component. As shown in the picture,
the result is 8 grades for blue and red and 4 grades
for green. We discourage the use of this mode
because it do not contain real shades of gray.
Color mask: BBBGGRRR
Available colors: 8 x 4 x 8 = 256:
GUICC_M323: 8 bpp, red and blue swapped
This mode supports 256 colors. 3 bits are used for the red and blue components of
the color and 2 bits for the green component. The available colors are the same as
those in 323 mode. The result is 8 grades for red and blue and 4 grades for green.
We discourage the use of this mode because it do not contain real shades of gray.
Color mask: RRRGGBBB
Available colors: 8 x 4 x 8 = 256:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
234
CHAPTER
Colors
332 mode: 8 bpp
This mode supports 256 colors. 3 bits are used for
the blue and green components of the color and 2
bits for the red component. As shown in the picture,
the result is 8 grades for green and blue and 4
grades for red. We discourage the use of this mode
because it do not contain real shades of gray.
Color mask: BBBGGGRR
Available colors: 8 x 8 x 4 = 256:
GUICC_332: 8 bpp, red and blue swapped
This mode supports 256 colors. 3 bits are used for
the red and green components of the color and 2 bits
for the blue component. The result is 8 grades for
red and green and only 4 grades for blue. We discourage the use of this mode because it do not contain real shades of gray.
Color mask: RRRGGGBB
Available colors: 8 x 8 x 4 = 256:
GUICC_44412:
The red, green and blue components are each 4 bits.
Color mask: 0000BBBBGGGGRRRR
Available colors: 16 x 16 x 16 = 4096.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
235
GUICC_44416:
The red, green and blue components are each 4 bits. One bit between the color components is not used. The available colors are the same as those in 44412 mode.
Color mask: 0BBBB0GGGG0RRRR0
Available colors: 16 x 16 x 16 = 4096.
GUICC_44412: red and blue swapped
The red, green and blue components are each 4 bits. The available colors are the
same as those in 44412 mode.
Available colors: 16 x 16 x 16 = 4096.
Color mask: RRRRGGGGBBBB
GUICC_44416: red and blue swapped
The red, green and blue components are each 4 bits. One bit between the color components is not used. The available colors are the same as those in 44412 mode.
Color mask: 0RRRR0GGGG0BBBB0
Available colors: 16 x 16 x 16 = 4096.
GUICC_444121:
The red, green and blue components are each 4 bits. The lower 4 bits of the color
mask are not used. The available colors are the same as those in 44412 mode.
Color mask: BBBBGGGGRRRR0000
Available colors: 16 x 16 x 16 = 4096.
GUICC_555: 15 bpp
Use of this mode is necessary for a display controller
that supports RGB colors with a color-depth of 15
bpp. The red, green and blue components are each 5
bits.
Color mask: BBBBBGGGGGRRRRR
Available colors: 32 x 32 x 32 = 32768.
GUICC_M555: 15 bpp, red and blue swapped
Use of this mode is necessary for a display controller that supports RGB colors with a
color-depth of 15 bpp. The red, green and blue components are each 5 bits. The
available colors are the same as those in 555 mode.
Color mask: RRRRRGGGGGBBBBB
Available colors: 32 x 32 x 32 = 32768.
GUICC_565: 16 bpp
Use of this mode is necessary for a display controller
that supports RGB colors with a color-depth of 16
bpp. The red and the blue component is 5 bits and
the green component is 6 bit.
Color mask: BBBBBGGGGGGRRRRR
Available colors: 32 x 64 x 32 = 65536.
GUICC_M565: 16 bpp, red and blue swapped
Use of this mode is necessary for a display controller that supports RGB colors with a
color-depth of 16 bpp. The available colors are the same as those in 565 mode.
Color sequence: RRRRRGGGGGGBBBBB
Available colors: 32 x 64 x 32 = 65536.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
236
CHAPTER
Colors
GUICC_556: 16 bpp
Use of this mode is necessary for a display controller that supports RGB colors with a
color-depth of 16 bpp. The blue and the green component is 5 bit and the red component is 6 bit.
Color mask: BBBBBGGGGGRRRRRR
Available colors: 32 x 32 x 64 = 65536.
GUICC_M556: 16 bpp, red and blue swapped
Use of this mode is necessary for a display controller that supports RGB colors with a
color-depth of 16 bpp. The red and the green component is 5 bit and the blue component is 6 bit.
Color mask: RRRRRGGGGGBBBBBB
Available colors: 32 x 32 x 64 = 65536.
GUICC_655: 16 bpp
Use of this mode is necessary for a display controller that supports RGB colors with a
color-depth of 16 bpp. The red and green component is 5 bit and the blue component
is 6 bit.
Color mask: BBBBBBGGGGGRRRRR
Available colors: 64 x 32 x 32 = 65536.
GUICC_M655: 16 bpp, red and blue swapped
Use of this mode is necessary for a display controller that supports RGB colors with a
color-depth of 16 bpp. The blue and green component is 5 bit and the red component
is 6 bit.
Color mask: RRRRRRGGGGGBBBBB
Available colors: 64 x 32 x 32 = 65536.
GUICC_666: 18 bpp
Use of this mode is necessary for a display controller that supports RGB colors with a
color-depth of 18 bpp. The red, green and blue component is 6 bit.
Color mask: BBBBBBGGGGGGRRRRRR
Available colors: 64 x 64 x 64 = 262144.
GUICC_M666: 18 bpp, red and blue swapped
Use of this mode is necessary for a display controller that supports RGB colors with a
color-depth of 18 bpp. The red, green and the blue component is 6 bit.
Color mask: RRRRRRGGGGGGBBBBBB
Available colors: 64 x 64 x 64 = 262144.
GUICC_666_9: 18 bpp
Use of this mode is necessary for a display controller that supports RGB colors with a
color-depth of 18 bpp. The red, green and blue component is 6 bit.
Color mask: 0000000BBBBBBGGG0000000GGGRRRRRR
Available colors: 64 x 64 x 64 = 262144.
GUICC_M666_9: 18 bpp, red and blue swapped
Use of this mode is necessary for a display controller that supports RGB colors with a
color-depth of 18 bpp. The red, green and blue component is 6 bit.
Color mask: RRRRRRGGGGGGBBBBBB
Available colors: 64 x 64 x 64 = 262144.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
237
GUICC_822216: 8 bpp, 2 levels per color + 8
grayscales + 16 levels of alpha blending
This mode can be used with a programmable color
lookup table (LUT), supporting a total of 256 possible colors and alpha blending support. It supports
the 8 basic colors, 8 grayscales and 16 levels of
alpha blending for each color / grayscale. With other
words it can be used if only a few colors are required
but more levels of alpha blending.
Available colors: (2 x 2 x 2 + 8) * 16 = 256
GUICC_84444: 8 bpp, 4 levels per color + 16
grayscales + 4(3) levels of alpha blending
This mode can be used with a programmable color
lookup table (LUT), supporting a total of 256 possible colors and alpha blending support. 4 levels of
intensity are available for each color, in addition to
16 grayscales and 4 levels of alpha blending for each
color / grayscale. With other words it can be used if
only a few levels of alpha blending are required and
different shades of colors.
Available colors: (4 x 4 x 4 + 16) * 3 = 240
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
238
CHAPTER
Colors
GUICC_8666: 8bpp, 6 levels per color + 16
grayscales
This mode is most frequently used with a programmable color lookup table (LUT), supporting a total of
256 possible colors using a palette. The screen shot
gives an idea of the available colors; this mode contains the best choice for general purpose applications. Six levels of intensity are available for each
color, in addition to 16 grayscales.
Available colors: 6 x 6 x 6 + 16 = 232:
GUICC_86661: 8bpp, 6 levels per color + 16 grayscales + transparency
This mode is most frequently used with multi layer configurations and a programmable color lookup table (LUT), supporting a total of 256 possible colors using a palette.
The difference between 8666 and 86661 is, that the first color indices of the 86661
mode are not used. So the color conversion routine GUI_Color2Index does never
return 0 which is used for transparency.
Available colors: 6 x 6 x 6 + 16 = 232.
GUICC_888: 24 bpp
Use of this mode is necessary for a display controller
that supports RGB colors with a color depth of 24
bpp. The red, green and blue components are each 8
bits.
Color mask: BBBBBBBBGGGGGGGGRRRRRRRR
Available colors: 256 x 256 x 256 = 16777216.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
239
GUICC_M888: 24 bpp, red and blue swapped
Use of this mode is necessary for a display controller that supports RGB colors with a
color depth of 24 bpp. The red, green and blue components are each 8 bits.
Color mask: RRRRRRRRGGGGGGGGBBBBBBBB
Available colors: 256 x 256 x 256 = 16777216.
GUICC_8888: 32 bpp
Use of this mode is necessary for a display controller that supports RGB colors with a
color depth of 32 bpp, where the lower 3 bytes are used for the color components
and the upper byte is used for alpha blending. The red, green, blue and alpha blending components are each 8 bits.
Color mask: AAAAAAAABBBBBBBBGGGGGGGGRRRRRRRR
Available colors: 256 x 256 x 256 = 16777216.
GUICC_M8888: 32 bpp, red and blue swapped
Use of this mode is necessary for a display controller that supports RGB colors with a
color depth of 32 bpp, where the lower 3 bytes are used for the color components
and the upper byte is used for alpha blending. The red, green, blue and alpha blending components are each 8 bits.
Color mask: AAAAAAAARRRRRRRRGGGGGGGGBBBBBBBB
Available colors: 256 x 256 x 256 = 16777216.
GUICC_0: Custom palette mode
(explained later in this chapter)
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
240
CHAPTER
Colors
13.5 Application defined color conversion
If none of the fixed palette modes matches the need of color conversion this mode
makes it possible to use application defined color conversion routines. The purpose of
these routines is converting an RGB value into an index value for the hardware and
vice versa.
Example of defining custom color conversion routines
The following example should explain how it works:
static unsigned _Color2Index_User(LCD_COLOR Color) {
unsigned Index;
/* Add code for converting the RGB value to an index value for the hardware */
return Index;
}
static LCD_COLOR _Index2Color_User(unsigned Index) {
LCD_COLOR Color;
/* Add code for converting the index value into an RGB value */
return Color;
}
static unsigned _GetIndexMask_User(void) {
return 0xffff; /* Example for using 16 bits */
}
const LCD_API_COLOR_CONV LCD_API_ColorConv_User = {
_Color2Index_User,
_Index2Color_User,
_GetIndexMask_User
};
The function LCD_Color2Index_User() is called by emWin if a RGB value should be
converted into an index value for the display controller whereas the function
LCD_Index2Color_User() is called if an index value should be converted into a RGB
value.
LCD_GetIndexMask_User() should return a bit mask value, which has each bit set to
1 which is used by the display controller and unused bits should be set to 0. For
example the index mask of GUICC_44416 mode is 0BBBB0GGGG0RRRR0, where 0
stands for unused bits. The bit mask for this mode is 0x7BDE.
Example of using custom color conversion routines
As described in the chapter ’Configuration’ a pointer to an API table is required for
creating the display driver device. As shown in the example above the API table consists of function pointers to the color conversion routines.
A good location for the API table and the color conversion routines is the configuration file LCDConf.c located in the Config folder. The routines can be used as follow in
the function LCD_X_Config() which is responsible to create the display driver device:
void LCD_X_Config(void) {
//
// Set display driver and color conversion for 1st layer
//
GUI_DEVICE_CreateAndLink(GUIDRV_LIN_16, &LCD_API_ColorConv_User, 0, 0);
.
.
.
}
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
241
13.6 Custom palette mode
If none of the fixed palette modes fulfils the requirements of the application emWin is
able to use a custom palette. A custom palette simply lists all the available colors in
the same order as they are used by the hardware. This means that no matter what
colors your LCD controller/display combination is able to display, emWin will be able
to simulate them in the PC simulation and handle these colors correctly in your target
system. Working with a custom palette requires a color depth <= 8 bpp.
A custom palette is typically used during the initialization in the function
LCD_X_Config() which is responsible for creating and configuring the display driver
device.
Example
The following example should show how a custom palette can be used. It passes the
palette to the function:
static const
0x000000,
0xFF0000,
0x000000,
0x800000,
};
LCD_COLOR _aColors_16[] = {
0x0000FF, 0x00FF00, 0x00FFFF,
0xFF00FF, 0xFFFF00, 0xFFFFFF,
0x000080, 0x008000, 0x008080,
0x800080, 0x808000, 0x808080,
static const LCD_PHYSPALETTE _aPalette_16 = {
COUNTOF(_aColors_16), _aColors_16
};
void LCD_X_Config(void) {
//
// Set display driver and color conversion for 1st layer
//
.
.
.
//
// Set user palette data (only required if no fixed palette is used)
//
LCD_SetLUTEx(0, _aPalette_16);
}
13.7 Color API
The following table lists the available color-related functions in alphabetical order
within their respective categories. Detailed description of the routines can be found
in the sections that follow.
Routine
Description
Basic color functions
GUI_GetBkColor()
GUI_GetBkColorIndex()
GUI_GetColor()
GUI_GetColorIndex()
GUI_SetBkColor()
GUI_SetBkColorIndex()
GUI_SetColor()
GUI_SetColorIndex()
Return the current background color.
GUI_CalcColorDist()
GUI_CalcVisColorError()
GUI_Color2Index()
GUI_Color2VisColor()
GUI_ColorIsAvailable()
GUI_Index2Color()
Returns the difference between 2 colors
Return the index of the current background color.
Return the current foreground color.
Return the index of the current foreground color.
Set the current background color.
Set the index of the current background color.
Set the current foreground color.
Set the index of the current foreground color.
Index & color conversion
User's & reference manual for emWin V5.10
Returns the difference to the next available color
Convert color into color index.
Returns the nearest available color
Checks if given color is available
Convert color index into color.
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
242
CHAPTER
Colors
13.8 Basic color functions
GUI_GetBkColor()
Description
Returns the current background color.
Prototype
GUI_COLOR GUI_GetBkColor(void);
Return value
The current background color.
GUI_GetBkColorIndex()
Description
Returns the index of the current background color.
Prototype
int GUI_GetBkColorIndex(void);
Return value
The current background color index.
GUI_GetColor()
Description
Returns the current foreground color.
Prototype
GUI_COLOR GUI_GetColor(void);
Return value
The current foreground color.
GUI_GetColorIndex()
Description
Returns the index of the current foreground color.
Prototype
int GUI_GetColorIndex(void);
Return value
The current foreground color index.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
243
GUI_SetBkColor()
Description
Sets the current background color.
Prototype
GUI_COLOR GUI_SetBkColor(GUI_COLOR Color);
Parameter
Color
Description
Color for background, 24-bit RGB value.
Return value
The selected background color.
GUI_SetBkColorIndex()
Description
Sets the index of the current background color.
Prototype
int GUI_SetBkColorIndex(int Index);
Parameter
Index
Description
Index of the color to be used.
Return value
The selected background color index.
GUI_SetColor()
Description
Sets the current foreground color.
Prototype
void GUI_SetColor(GUI_COLOR Color);
Parameter
Color
Description
Color for foreground, 24-bit RGB value.
Return value
The selected foreground color.
GUI_SetColorIndex()
Description
Sets the index of the current foreground color.
Prototype
void GUI_SetColorIndex(int Index);
Parameter
Index
Description
Index of the color to be used.
Return value
The selected foreground color index.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
244
CHAPTER
Colors
13.9 Index & color conversion
GUI_CalcColorDist()
Calculates the distance between 2 colors. The distance will be calculated by the sum
of the square value from the distances of the red, green and the blue component:
Difference = (Red1 - Red0) ² + (Green1 - Green0)² + (Blue1 - Blue0)²
Prototype
U32 GUI_CalcColorDist(GUI_COLOR Color0, GUI_COLOR Color1))
Parameter
Color0
Color1
Description
RGB value of the first color.
RGB value of the second color.
Return value
The distance as described above.
GUI_CalcVisColorError()
Calculates the distance to the next available color. For details about the calculation,
refer to “GUI_CalcColorDist()” on page 244.
Prototype
U32 GUI_CalcVisColorError(GUI_COLOR color)
Parameter
Color
Description
RGB value of the color to be calculated.
Return value
The distance to the next available color.
GUI_Color2Index()
Returns the index of a specified RGB color value.
Prototype
int GUI_Color2Index(GUI_COLOR Color)
Parameter
Color
Description
RGB value of the color to be converted.
Return value
The color index.
GUI_Color2VisColor()
Returns the next available color of the system as an RGB color value.
Prototype
GUI_COLOR GUI_Color2VisColor(GUI_COLOR color)
Parameter
Color
Description
RGB value of the color.
Return value
The RGB color value of the nearest available color.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
245
GUI_ColorIsAvailable()
Checks if the given color is available.
Prototype
char GUI_ColorIsAvailable(GUI_COLOR color)
Parameter
Color
Description
RGB value of the color.
Return value
1 if color is available, 0 if not.
GUI_Index2Color()
Returns the RGB color value of a specified index.
Prototype
int GUI_Index2Color(int Index)
Parameter
Index
Description
Index of the color. to be converted
Return value
The RGB color value.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
246
User's & reference manual for emWin V5.10
CHAPTER
Colors
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
247
Chapter 14
Memory Devices
Memory devices can be used in a variety of situations, mainly to prevent the display
from flickering when using drawing operations for overlapping items. The basic idea
is quite simple. Without the use of a memory device, drawing operations write
directly to the display. The screen is updated as drawing operations are executed,
which gives it a flickering appearance as the various updates are made. For example,
if you want to draw a bitmap in the background and some transparent text in the
foreground, you would first have to draw the bitmap and then the text. The effect
would be a flickering of the text.
If a memory device is used for such a procedure, however, all drawing operations are
executed in memory. The final result is displayed on the screen only when all operations have been carried out, with the advantage of no flickering. This difference can
be seen in the example in the following section, which illustrates a sequence of drawing operations both with and without the use of a memory device.
The distinction may be summarized as follows: If no memory device is used, the
effects of drawing operations can be seen step by step, with the disadvantage of a
flickering display. With a memory device, the effects of all routines are made visible
as a single operation. No intermediate steps can actually be seen. The advantage, as
explained above, is that display flickering is completely eliminated, and this is often
desirable.
Memory devices are an additional (optional) software item and are not shipped with
the emWin basic package. The software for memory devices is located in the subdirectory GUI\Memdev.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
248
CHAPTER
Memory Devices
14.1 Using memory devices: an illustration
The following table shows screen shots of the same operations handled with and
without a memory device. The objective in both cases is identical: a work piece is to
be rotated and labeled with the respective angle of rotation (here, 10 degrees). In
the first case (without a memory device) the screen must be cleared, then the polygon is redrawn in the new position and a string with the new label is written. In the
second case (with a memory device) the same operations are performed in memory,
but the screen is not updated during this time. The only update occurs when the routine GUI_MEMDEV_CopyToLCD() is called, and this update reflects all the operations at
once. Note that the initial states and final outputs of both procedures are identical.
API function
Without memory device
With memory device
Step 0: Initial state
Step 1:
GUI_Clear()
Step 2:
GUI_DrawPolygon()
Step 3:
GUI_DispString()
Step 4:
GUI_MEMDEV_CopyToLCD()
(only when using memory device)
14.2 Supported color depth (bpp)
Memory devices are available in 4 different color depth:
1 bpp, 8 bpp, 16 bpp and 32 bpp.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
249
Creating memory devices "compatible" to the display
There are two ways to create memory devices. If they are use to avoid flickering, a
memory device compatible to the display is created. This "compatible" memory
device needs to have the same or a higher color depth as the display. emWin automatically selects the "right" type of memory device for the display if the functions
GUI_MEMDEV_Create(), GUI_MEMDEV_CreateEx() are used.
The Window manager, which also has the ability to use memory devices for some or
all windows in the system, also uses these functions.
This way, the memory device with the lowest color depth (using the least memory) is
automatically used.
Creating memory devices for other purposes
Memory devices of any type can be created using GUI_MEMDEV_CreateFixed(). A
typical application would be the use of a memory device for printing as described
later in this chapter.
14.3 Memory devices and the window manager
The window manager works seamlessly with memory devices. Every window has a
flag which tells the window manager if a memory device should be used for rendering. This flag can be specified when creating the window or set/reset at any time.
If the memory device flag is set for a particular window, the WM automatically uses a
memory device when drawing the window. It creates a memory device before drawing a window and deletes it after the drawing operation. If enough memory is available, the whole window fits into the size of the memory device created by the WM. If
not enough memory is available for the complete window in one memory device, the
WM uses 'banding' for drawing the window. Details about 'banding' are described in
the documentation, chapter 'Memory Devices \ Banding memory device'. The memory used for the drawing operation is only allocated during the drawing operation. If
there is not enough memory available when (re-)drawing the window, the window is
redrawn without memory device.
14.4 Memory devices and multiple layers
The memory device API functions do not have any option to specify a layer. Please
note that when creating a memory device the memory device is associated with the
currently selected layer. The memory devices also use automatically the color conversion settings of the currently selected layer.
Example
//
// Create a memory device associated with layer 1
//
GUI_SelectLayer(1);
hMem = GUI_MEMDEV_Create(0, 0, 100, 100);
GUI_MEMDEV_Select(hMem);
GUI_DrawLine(0, 0, 99, 99);
GUI_MEMDEV_Select(0);
//
// Select layer 0
//
GUI_SelectLayer(0);
//
// The following line copies the memory device to layer 1 and not to layer 0
//
GUI_MEMDEV_CopyToLCD(hMem);
14.5 Memory requirements
If creating a memory device the required number of bytes depends on the color
depth of the memory device and whether transparency support is needed or not.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
250
CHAPTER
Memory Devices
Memory usage without transparency support
The following table shows the memory requirement in dependence of the system
color depth for memory devices without transparency support.
Color depth of
memory device
System color depth
(LCD_BITSPERPIXEL)
Memory usage
1 bpp
1 bpp
1 byte / 8 pixels:
(XSIZE + 7) / 8 * YSIZE
8 bpp
2, 4 and 8 bpp
XSIZE * YSIZE
16 bpp
12 and 16 bpp
2 bytes / pixel:
XSIZE * YSIZE * 2
32 bpp
18, 24 and 32 bpp
4 bytes / pixel:
XSIZE * YSIZE * 4
Example:
A memory device of 111 pixels in X and 33 pixels in Y should be created. It should be
compatible to a display with a color depth of 12 bpp and should support transparency. The required number of bytes can be calculated as follows:
Number of required bytes = (111 * 2 + (111 + 7) / 8) * 33 = 7788 bytes
Memory usage with transparency support
If a memory device should support transparency it needs one additional byte / 8 pixels for internal management.
Color depth of
memory device
System color depth
(LCD_BITSPERPIXEL)
Memory usage
1 bpp
1 bpp
2 byte / 8 pixels:
(XSIZE + 7) / 8 * YSIZE * 2
8 bpp
2, 4 and 8 bpp
1 bytes / pixel + 1 byte / 8 pixels:
(XSIZE + (XSIZE + 7) / 8) * YSIZE
16 bpp
12 and 16 bpp
2 bytes / pixel + 1 byte / 8 pixels:
(XSIZE * 2 + (XSIZE + 7) / 8) * YSIZE
32 bpp
18, 24 and 32 bpp
4 bytes / pixel + 1 byte / 8 pixels:
(XSIZE * 4 + (XSIZE + 7) / 8) * YSIZE
Example:
A memory device of 200 pixels in X and 50 pixels in Y should be created. It should be
compatible to a display with a color depth of 4bpp and should support transparency.
The required number of bytes can be calculated as follows:
Number of required bytes = (200 + (200 + 7) / 8) * 50 = 11250 bytes
14.6 Performance
Using memory devices typically does not significantly affect performance. When
memory devices are used, the work of the driver is easier: It simply transfers bitmaps to the display controller. On systems with slow drivers (for example displays
connected via serial interface), the performance is better if memory devices are
used; on systems with a fast driver (such as memory mapped display memory,
GUIDRV_Lin and others) the use of memory devices costs some performance.
If 'banding' is needed, the used time to draw a window increases with the number of
bands. The more memory available for memory devices, the better the performance.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
251
14.7 Basic functions
The following routines are those that are normally called when using memory
devices. Basic usage is rather simple:
1.
2.
3.
4.
5.
Create the memory device (using GUI_MEMDEV_Create()).
Activate it (using GUI_MEMDEV_Select()).
Execute drawing operations.
Copy the result into the display (using GUI_MEMDEV_CopyToLCD()).
Delete
the
memory
device
if
you
no
longer
need
GUI_MEMDEV_Delete()).
it
(using
14.8 In order to be able to use memory devices...
Memory devices are enabled by default. In order to optimize performance of the software, support for memory devices can be switched off in the configuration file
GUIConf.h by including the following line:
#define GUI_SUPPORT_MEMDEV
0
If this line is in the configuration file and you want to use memory devices, either
delete the line or change the define to 1.
14.9 Multi layer / multi display configurations
As explained earlier in this chapter memory devices "compatible" to the display
needs to have the same or a higher color depth as the display. When creating a memory device compatible to the display emWin "knows" the color depth of the currently
selected layer/display and automatically uses the lowest color depth.
14.10 Configuration options
Type
B
Macro
Default
GUI_USE_MEMDEV_1BPP_FOR_SCREEN
1
Description
Enables the use of 1bpp memory
devices with displays of 1bpp color
depth.
14.10.1 GUI_USE_MEMDEV_1BPP_FOR_SCREEN
On systems with a display color depth <= 8bpp the default color depth of memory
devices compatible to the display is 8bpp. To enable the use of 1bpp memory devices
with displays of 1bpp color depth the following line should be added to the configuration file GUIConf.h:
#define GUI_USE_MEMDEV_1BPP_FOR_SCREEN 0
14.11 Memory device API
The table below lists the available routines of the emWin memory device API.
All functions are listed in alphabetical order within their respective categories.
Detailed descriptions of the routines can be found in the sections that follow.
Routine
Description
Basic functions
GUI_MEMDEV_Clear()
GUI_MEMDEV_CopyFromLCD()
GUI_MEMDEV_CopyToLCD()
User's & reference manual for emWin V5.10
Marks the memory device contents as unchanged
Copies contents of LCD to memory device
Copies contents of memory device to LCD
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
252
CHAPTER
Routine
Memory Devices
Description
GUI_MEMDEV_CopyToLCDAA()
Copies the contents of memory device antialiased
GUI_MEMDEV_CopyToLCDAt()
Copies contents of memory device to LCD at the given
position
GUI_MEMDEV_Create()
Creates the memory device (first step)
GUI_MEMDEV_CreateEx()
Creates the memory device with additional creation
flags
Creates a memory device with a given color depth
GUI_MEMDEV_CreateFixed()
GUI_MEMDEV_Delete()
Frees the memory used by the memory device
GUI_MEMDEV_DrawPerspectiveX()
Draws the given memory device perspectively distorted into the current selected device
GUI_MEMDEV_GetDataPtr()
Returns a pointer to the data area for direct manipulation
GUI_MEMDEV_GetXSize()
GUI_MEMDEV_GetYSize()
GUI_MEMDEV_MarkDirty()
GUI_MEMDEV_ReduceYSize()
Returns the X-size (width) of memory device
Returns the Y-size (height) of memory device
Marks a rectangle area as dirty.
Reduces Y-size of memory device
GUI_MEMDEV_Rotate()
Rotates and scales a memory device and writes the
result into a memory device using the ’nearest neighbor’ method
GUI_MEMDEV_RotateHQ()
Rotates and scales a memory device and writes the
result into a memory device using the ’high quality’
method
GUI_MEMDEV_Select()
Selects a memory device as target for drawing operations
GUI_MEMDEV_SetOrg()
Changes the origin of the memory device on the LCD
GUI_MEMDEV_Write()
Writes the contents of a memory device into a memory device
GUI_MEMDEV_WriteAlpha()
Writes the contents of a memory device into a memory device using alpha blending
GUI_MEMDEV_WriteAlphaAt()
Writes the contents of a memory device into a memory device using the given position and alpha blending
GUI_MEMDEV_WriteAt()
Writes the contents of a memory device into a memory device to the given position
GUI_MEMEDV_WriteEx()
Writes the contents of a memory device into a memory device using alpha blending and scaling
GUI_MEMDEV_WriteExAt()
Writes the contents of a memory device into a memory device to the given position using alpha blending
and scaling
GUI_SelectLCD()
Selects the LCD as target for drawing operations
Banding memory device
GUI_MEMDEV_Draw()
Use a memory device for drawing
Auto device object functions
Creates an auto device object
GUI_MEMDEV_CreateAuto()
Deletes an auto device object
GUI_MEMDEV_DeleteAuto()
Uses a GUI_AUTODEV object for drawing
GUI_MEMDEV_DrawAuto()
Measurement device object functions
Clears the measurement rectangle
GUI_MEASDEV_ClearRect()
Creates a measurement device
GUI_MEASDEV_Create()
Deletes a measurement device
GUI_MEASDEV_Delete()
Retrieves the measurement result
GUI_MEASDEV_GetRect()
GUI_MEASDEV_Select()
Selects a measurement device as target for drawing
operations
Animation functions
GUI_MEMDEV_FadeDevices()
Performs fading from one to another memory device.
Sets a user defined function to be called while anima-
GUI_MEMDEV_SetAnimationCallback() tions are processed.
Animation functions (Window Manager required)
Fades in a window by decreasing the alpha value
GUI_MEMDEV_FadeInWindow()
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
253
Routine
Description
GUI_MEMDEV_FadeOutWindow()
Fades out a window by increasing the alpha value
GUI_MEMDEV_MoveInWindow()
Moves in a Window from a specified to its actual position by magnification (optionally with rotation)
GUI_MEMDEV_MoveOutWindow()
Moves out a Window from its actual to a specified
position by demagnification (optionally with rotation)
GUI_MEMDEV_ShiftInWindow()
Shifts a Window in a specified direction into the screen
to its actual position.
GUI_MEMDEV_ShiftOutWindow()
Shifts a Window in a specified direction from its actual
position out of the screen.
GUI_MEMDEV_ShiftWindow()
Shifts a window in a specified direction into the screen
to its actual position and shifts out the old content of
the window area.
14.12 Basic functions
GUI_MEMDEV_Clear()
Description
Marks the entire contents of a memory device as "unchanged".
Prototype
void GUI_MEMDEV_Clear(GUI_MEMDEV_Handle hMem);
Parameter
hMem
Description
Handle to memory device.
Additional information
The next drawing operation with GUI_MEMDEV_CopyToLCD() will then write only the
bytes modified between GUI_MEMDEV_Clear() and GUI_MEMDEV_CopyToLCD().
GUI_MEMDEV_CopyFromLCD()
Description
Copies the contents of a memory device from LCD data (video memory) to the memory device. In other words: read back the contents of the LCD to the memory device.
Prototype
void GUI_MEMDEV_CopyFromLCD(GUI_MEMDEV_Handle hMem);
Parameter
hMem
Description
Handle to memory device.
GUI_MEMDEV_CopyToLCD()
Description
Copies the contents of a memory device from memory to the LCD.
Prototype
void GUI_MEMDEV_CopyToLCD(GUI_MEMDEV_Handle hMem);
Parameter
hMem
Description
Handle to memory device.
Additional information
Do not use this function within a paint callback function called by the window manUser's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
254
CHAPTER
Memory Devices
ager, because it deactivates the clipping area of the window manager. The function
GUI_MEMDEV_WriteAt should be used instead.
GUI_MEMDEV_CopyToLCDAA()
Description
Copies the contents of a memory device (antialiased) from memory to the LCD.
Prototype
void GUI_MEMDEV_CopyToLCDAA(GUI_MEMDEV_Handle MemDev);
Parameter
hMem
Description
Handle to memory device.
Additional information
The device data is handled as antialiased data. A matrix of 2x2 pixels is converted to
1 pixel. The intensity of the resulting pixel depends on how many pixels are set in the
matrix.
Example
Creates a memory device and selects it for output. A large font is then set and a text
is written to the memory device:
GUI_MEMDEV_Handle hMem = GUI_MEMDEV_Create(0,0,60,32);
GUI_MEMDEV_Select(hMem);
GUI_SetFont(&GUI_Font32B_ASCII);
GUI_DispString("Text");
GUI_MEMDEV_CopyToLCDAA(hMem);
Screen shot of above example
GUI_MEMDEV_CopyToLCDAt()
Description
Copies the contents of a memory device from memory to the LCD at the given position.
Prototype
void GUI_MEMDEV_CopyToLCDAt(GUI_MEMDEV_Handle hMem, int x, int y)
Parameter
hMem
x
y
Description
Handle to memory device.
Position in X
Position in Y
GUI_MEMDEV_Create()
Description
Creates a memory device.
Prototype
GUI_MEMDEV_Handle GUI_MEMDEV_Create(int x0, int y0, int XSize, int YSize)
Parameter
x0
y0
xsize
ysize
Description
X-position of memory device.
Y-position of memory device.
X-size of memory device.
Y-size of memory device.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
255
Return value
Handle for created memory device. If the routine fails the return value is 0.
GUI_MEMDEV_CreateEx()
Description
Creates a memory device.
Prototype
GUI_MEMDEV_Handle GUI_MEMDEV_CreateEx(int x0, int y0,
int XSize, int YSize
int Flags)
Parameter
x0
y0
xsize
ysize
Flags
Description
X-position of memory device.
Y-position of memory device.
X-size of memory device.
Y-size of memory device.
(see table below).
Permitted values for parameter Flags
Default: The memory device is created with a
transparency flag which ensures that the background will be drawn correctly.
GUI_MEMDEV_HASTRANS
(recommended)
Creates a memory device without transparency. The
user must make sure that the background is drawn
correctly.
This way the memory device can be used for nonrectangular areas. An other advantage is the higher
speed: Using this flag accelerates the memory
device app. 30 - 50%.
GUI_MEMDEV_NOTRANS
Return value
Handle for created memory device. If the routine fails the return value is 0.
GUI_MEMDEV_CreateFixed()
Description
Creates a memory device of fixed size, color depth (bpp) and specified color conversion.
Prototype
GUI_MEMDEV_Handle GUI_MEMDEV_CreateFixed(
int x0, int y0, int xsize, int ysize,
int Flags,
const tLCDDEV_APIList
* pMemDevAPI,
const LCD_API_COLOR_CONV * pColorConvAPI)
Parameter
x0
y0
xsize
ysize
Flags
pMemDevAPI
pColorConvAPI
Description
X-position of memory device.
Y-position of memory device.
X-size of memory device.
Y-size of memory device.
(see table below).
(see table below).
(see table below).
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
256
CHAPTER
Memory Devices
Permitted values for parameter Flags
Default: The memory device is created with a
transparency flag which ensures that the background will be drawn correctly.
GUI_MEMDEV_HASTRANS
(recommended)
Creates a memory device without transparency.
The user must make sure that the background is
drawn correctly.
This way the memory device can be used for
non-rectangular areas. An other advantage is
the higher speed: Using this flag accelerates the
memory device app. 30 - 50%.
GUI_MEMDEV_NOTRANS
Parameter pMemDevAPI
Defines the color depth of the memory device in bpp. The color depth of the
memory device should be equal or greater than the required bits for the color
conversion routines.
A memory device with a 1bpp color conversion (GUI_COLOR_CONV_1 ) for
example requires at least a memory device with 1bpp color depth. The available
memory devices are 1bpp, 8bpp, 16bpp and 32bpp memory devices. So an 1bpp
memory device should be used.
If using a 4 bit per pixel color conversion (GUI_COLOR_CONV_4 ) at least 4bpp
are needed for the memory device. In this case an 8bpp memory device should be
used.
Permitted values
GUI_MEMDEV_APILIST_1
Create memory device with 1bpp color depth
(1 byte per 8 pixels)
Use if the specified color conversion requires
1bpp.
GUI_MEMDEV_APILIST_8
Create memory device with 8bpp color depth
(1 byte per pixel)
Use if the specified color conversion requires
8bpp or less.
GUI_MEMDEV_APILIST_16
Create memory device with 16bpp color depth
(1 U16 per pixel)
Use if the specified color conversion requires
more than 8 bpp. (High color modes)
Create memory device with 32bpp color depth
(1 U32 per pixel)
GUI_MEMDEV_APILIST_32 Use if the specified color conversion requires
more than 16 bpp. (True color modes)
Parameter pColorConvAPI
This parameter defines the desired color conversion. For more details about the
used bits per pixel and the color conversion, refer to the chapter “Colors” on
page 227.
Permitted values
GUI_COLOR_CONV_1
Same color conversion like the fixed palette
mode 1. (black/white)
GUI_COLOR_CONV_2
Same color conversion like the fixed palette
mode 2. (4 gray scales)
GUI_COLOR_CONV_4
Same color conversion like the fixed palette
mode 4. (16 gray scales)
GUI_COLOR_CONV_565
Same color conversion like the fixed palette
mode 565.
GUI_COLOR_CONV_M565
Same color conversion like the fixed palette
mode M565.
GUI_COLOR_CONV_8666
Same color conversion like the fixed palette
mode 8666.
GUI_COLOR_CONV_888
Same color conversion like the fixed palette
mode 888.
GUI_COLOR_CONV_8888
Same color conversion like the fixed palette
mode 8888.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
257
Return value
Handle for created memory device. If the routine fails the return value is 0.
Additional information
This function can be used if a memory device with a specified color conversion should
be created. This could make sense if for example some items should be printed on a
printer device. The Sample folder contains the code example MEMDEV_Printing.c
which shows how to use the function to print something in 1bpp color conversion
mode.
Example
The following example shows how to create a memory device with 1bpp color depth:
GUI_MEMDEV_Handle hMem;
hMem = GUI_MEMDEV_CreateFixed(0, 0, 128, 128, 0,
GUI_MEMDEV_APILIST_1, /* Used API list */
GUI_COLOR_CONV_1);
/* Black/white color conversion */
GUI_MEMDEV_Select(hMem);
GUI_MEMDEV_Delete()
Description
Deletes a memory device.
Prototype
void GUI_MEMDEV_Delete(GUI_MEMDEV_Handle MemDev);
Parameter
hMem
Description
Handle to memory device.
Return value
Handle for deleted memory device.
GUI_MEMDEV_DrawPerspectiveX()
Description
Draws the given memory device perspectively distorted into the currently selected
device.
Prototype
void GUI_MEMDEV_DrawPerspectiveX(GUI_MEMDEV_Handle hMem, int x, int y,
int h0, int h1, int dx, int dy);
Parameter
hMem
x
y
h0
h1
dx
dy
Description
Handle to source memory device with the image to be drawn.
Horizontal start position in pixels.
Vertical start position in pixels.
Height of the leftmost edge of the image to be drawn.
Height of the rightmost edge of the image to be drawn.
Width of the image to be drawn.
Position in y from the topmost pixel at the right relative to the topmost pixel at the left.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
258
CHAPTER
Memory Devices
The picture below explains the parameters more detailed:
dx
h1
h0
dy
y
x
Image to be drawn
Destination device
Additional information
The function draws the contents of the given memory device into the currently
selected device. The origin of the source device should be (0, 0). Size and distortion
of the new image is defined by the parameters dx, dy, h0 and h1.
Note that the function currently only works with memory devices with 32-bpp color
depth and a system color depth of 32 bpp.
Example
The following example shows how to use the function:
GUI_MEMDEV_Handle hMem0, hMem1, hMem2;
hMem0 = GUI_MEMDEV_CreateFixed(0, 0, 150, 150, GUI_MEMDEV_NOTRANS,
GUI_MEMDEV_APILIST_32,
GUI_COLOR_CONV_888);
hMem1 = GUI_MEMDEV_CreateFixed(0, 0, 75, 150, GUI_MEMDEV_HASTRANS,
GUI_MEMDEV_APILIST_32,
GUI_COLOR_CONV_888);
hMem2 = GUI_MEMDEV_CreateFixed(0, 0, 75, 150, GUI_MEMDEV_HASTRANS,
GUI_MEMDEV_APILIST_32,
GUI_COLOR_CONV_888);
GUI_MEMDEV_Select(hMem0);
GUI_JPEG_Draw(_aJPEG, sizeof(_aJPEG), 0, 0);
GUI_MEMDEV_Select(hMem1);
GUI_MEMDEV_DrawPerspectiveX(hMem0, 0, 0, 150, 110, 75, 20);
GUI_MEMDEV_Select(hMem2);
GUI_MEMDEV_DrawPerspectiveX(hMem0, 0, 20, 110, 150, 75, -20);
GUI_MEMDEV_CopyToLCDAt(hMem0,
0, 10);
GUI_MEMDEV_CopyToLCDAt(hMem1, 160, 10);
GUI_MEMDEV_CopyToLCDAt(hMem2, 245, 10);
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
259
Screenshot of the above example
GUI_MEMDEV_GetDataPtr()
Description
Returns a pointer to the data area (image area) of a memory device. This data area
can then be manipulated without the use of GUI functions; it can for example be used
as output buffer for a JPEG or video decompression routine.
Prototype
void* GUI_MEMDEV_GetDataPtr(GUI_MEMDEV_Handle hMem);
Parameter
hMem
Description
Handle to memory device.
Additional information
The device data is stored from the returned address onwards. An application modifying this data has to take extreme caution that it does not overwrite memory outside
of this data area. If this data area is used with emWins default memory management, the memory area must remain locked as long as the pointer is in use.
Organization of the data area:
The pixels are stored in the mode "native" to the display (or layer) for which they are
intended. For layers with 8 bpp or less, 8 bits (1 byte) are used per pixel; for layers
with more than 8 and less or equal 16 bpp, a 16 bit value (U16) is used for one pixel.
The memory is organized in reading order which means: First byte (or U16), stored
at the start address, represents the color index of the pixel in the upper left corner
(y=0, x=0); the next pixel, stored right after the first one, is the one to the left at
(y=0, x=1). (Unless the memory device area is only 1 pixel wide). The next line is
stored right after the first line in memory, without any kind of padding. Endian mode
is irrelevant, it is assumed that 16 bit units are accessed as 16 bit units and not as 2
separate bytes. The data area is comprised of (xSize * ySize) pixels, so
xSize * ySize bytes for 8bpp or lower memory devices,
2 * xSize * ySize bytes (accessed as xSize * ySize units of 16 bits) for 16 bpp memory devices.
GUI_MEMDEV_GetXSize()
Description
Returns the X-size (width) of a memory device.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
260
CHAPTER
Memory Devices
Prototype
int
GUI_MEMDEV_GetXSize(GUI_MEMDEV_Handle hMem);
Parameter
Description
Handle to memory device.
hMem
GUI_MEMDEV_GetYSize()
Description
Returns the Y-size (height) of a memory device in pixels.
Prototype
int
GUI_MEMDEV_GetYSize(GUI_MEMDEV_Handle hMem);
Parameter
hMem
Description
Handle to memory device.
GUI_MEMDEV_MarkDirty()
Description
Marks a rectangle area as dirty.
Prototype
void GUI_MEMDEV_MarkDirty(GUI_MEMDEV_Handle hMem,
int x0, int y0, int x1, int y1);
Parameter
hMem
x0
y0
x1
y1
Description
Handle to the memory device.
x-coordinate of the upper left corner.
y-coordinate of the upper left corner.
x-coordinate of the lower right corner.
y-coordinate of the lower right corner.
GUI_MEMDEV_ReduceYSize()
Description
Reduces the Y-size of a memory device.
Prototype
void GUI_MEMDEV_ReduceYSize(GUI_MEMDEV_Handle hMem, int YSize);
Parameter
hMem
YSize
Description
Handle to memory device.
New Y-size of the memory device.
Additional information
Changing the size of the memory device is more efficient than deleting and then recreating it.
GUI_MEMDEV_Rotate(), GUI_MEMDEV_RotateHQ()
Description
The functions rotate and scale the given source memory device. The source device
will be rotated and scaled around its center and then shifted by the given amount of
pixels. The result is saved into the given destination memory device.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
261
The difference between both functions is the algorithm for calculating the destination
pixel data. GUI_MEMDEV_Rotate() uses the ’nearest neighbor’ method which is fast
but less accurate. GUI_MEMDEV_RotateHQ() uses a more complex method which is
quite accurate but not as fast as the ’nearest neighbor’ method.
For a more detailed impression of the difference between the functions there are two
screenshots at the end of this function description.
Prototypes
void GUI_MEMDEV_RotateHQ(GUI_MEMDEV_Handle hSrc, GUI_MEMDEV_Handle hDst,
int dx, int dy, int a, int Mag);
void GUI_MEMDEV_Rotate(GUI_MEMDEV_Handle hSrc, GUI_MEMDEV_Handle hDst,
int dx, int dy, int a, int Mag);
Parameter
hSrc
hDst
dx
dy
a
Mag
Description
Handle of memory device to be rotated and scaled.
Handle of destination device.
Distance in pixels for shifting the image in X.
Distance in pixels for shifting the image in Y.
Angle to be used for rotation in degrees * 1000.
Magnification factor * 1000
The following picture gives a more detailed impression of the parameters:
Image to be drawn
@
dx
dy
Destination device
a
Additional information
Both memory devices, source and destination, need to be 32 bit memory devices. In
any other case the function will return immediately.
The Sample folder also contains the example MEMDEV_ZoomAndRotate.c which shows
in detail how the function can be used.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
262
CHAPTER
Memory Devices
Example
GUI_MEMDEV_Handle hMemSource;
GUI_MEMDEV_Handle hMemDest;
GUI_RECT RectSource = {0, 0, 69, 39};
GUI_RECT RectDest
= {0, 0, 79, 79};
hMemSource = GUI_MEMDEV_CreateFixed(RectSource.x0, RectSource.y0,
RectSource.x1 - RectSource.x0 + 1,
RectSource.y1 - RectSource.y0 + 1,
GUI_MEMDEV_NOTRANS,
GUI_MEMDEV_APILIST_32, GUI_COLOR_CONV_888);
hMemDest
= GUI_MEMDEV_CreateFixed(RectDest.x0,
RectDest.y0,
RectDest.x1
- RectDest.x0
+ 1,
RectDest.y1
- RectDest.y0
+ 1,
GUI_MEMDEV_NOTRANS,
GUI_MEMDEV_APILIST_32, GUI_COLOR_CONV_888);
GUI_MEMDEV_Select(hMemSource);
GUI_DrawGradientV(RectSource.x0, RectSource.y0,
RectSource.x1, RectSource.y1,
GUI_WHITE, GUI_DARKGREEN);
GUI_SetColor(GUI_BLUE);
GUI_SetFont(&GUI_Font20B_ASCII);
GUI_SetTextMode(GUI_TM_TRANS);
GUI_DispStringInRect("emWin", &RectSource, GUI_TA_HCENTER | GUI_TA_VCENTER);
GUI_DrawRect(0, 0, RectSource.x1, RectSource.y1);
GUI_MEMDEV_RotateHQ(hMemSource, hMemDest,
(RectDest.x1 - RectSource.x1) / 2,
(RectDest.y1 - RectSource.y1) / 2,
30 * 1000,
1000);
GUI_MEMDEV_CopyToLCDAt(hMemSource, 10, (RectDest.y1 - RectSource.y1) / 2);
GUI_MEMDEV_CopyToLCDAt(hMemDest,
100, 0);
Screenshot of the above example using GUI_MEMDEV_RotateHQ()
Screenshot of the above example using GUI_MEMDEV_Rotate()
GUI_MEMDEV_Select()
Description
Activates a memory device (or activates LCD if handle is 0)
Prototype
void GUI_MEMDEV_Select(GUI_MEMDEV_Handle hMem)
Parameter
hMem
Description
Handle to memory device.
GUI_MEMDEV_SetOrg()
Description
Changes the origin of the memory device on the LCD.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
263
Prototype
void GUI_MEMDEV_SetOrg(GUI_MEMDEV_Handle hMem, int x0, int y0);
Parameter
hMem
x0
y0
Description
Handle to memory device.
Horizontal position (of the upper left pixel).
Vertical position (of the upper left pixel).
Additional information
This routine can be helpful when the same device is used for different areas of the
screen or when the contents of the memory device are to be copied into different
areas.
Changing the origin of the memory device is more efficient than deleting and then
recreating it.
GUI_MEMDEV_Write()
Description
Writes the contents of the given memory device into the currently selected memory
device.
Prototype
void GUI_MEMDEV_Write(GUI_MEMDEV_Handle hMem);
Parameter
hMem
Description
Handle to memory device.
GUI_MEMDEV_WriteAlpha()
Description
Writes the contents of the given memory device into the currently selected memory
device using alpha blending.
Prototype
void GUI_MEMDEV_WriteAlpha(GUI_MEMDEV_Handle hMem, int Alpha);
Parameter
hMem
Alpha
Description
Handle to memory device.
Alpha blending factor, 0 - 255
Additional information
Alpha blending means mixing 2 colors with a given intensity. This function makes it
possible to write semi-transparent from one memory device into an other memory
device. The Alpha-parameter specifies the intensity used when writing to the currently selected memory device.
GUI_MEMDEV_WriteAlphaAt()
Description
Writes the contents of the given memory device into the currently selected memory
device at the specified position using alpha blending.
Prototype
void GUI_MEMDEV_WriteAlphaAt(GUI_MEMDEV_Handle hMem,
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
264
CHAPTER
Memory Devices
int Alpha, int x, int y);
Parameter
hMem
Alpha
x
y
Description
Handle to memory device.
Alpha blending factor, 0 - 255
Position in X
Position in Y
Additional information
(See GUI_MEMDEV_WriteAlpha)
GUI_MEMDEV_WriteAt()
Description
Writes the contents of the given memory device into the currently selected memory
device at the specified position.
Prototype
void GUI_MEMDEV_WriteAt(GUI_MEMDEV_Handle hMem, int x, int y);
Parameter
hMem
x
y
Description
Handle to memory device.
Position in X
Position in Y
GUI_MEMDEV_WriteEx()
Description
Writes the contents of the given memory device into the currently selected memory
device at position (0, 0) using alpha blending and scaling.
Prototype
void GUI_MEMDEV_WriteEx(GUI_MEMDEV_Handle hMem,
int xMag, int yMag, int Alpha);
Parameter
hMem
xMag
yMag
Alpha
Description
Handle to memory device.
Scaling factor for X-axis * 1000.
Scaling factor for Y-axis * 1000.
Alpha blending factor, 0 - 255.
Additional information
A
negative
scaling
factor
mirrors
“GUI_MEMDEV_WriteExAt()” on page 264.
the
output.
Refer
also
to
GUI_MEMDEV_WriteExAt()
Description
Writes the contents of the given memory device into the currently selected memory
device at the specified position using alpha blending and scaling.
Prototype
void GUI_MEMDEV_WriteExAt(GUI_MEMDEV_Handle hMem,
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
265
int x, int y, int xMag, int yMag, int Alpha);
Parameter
hMem
x
y
xMag
yMag
Alpha
Description
Handle to memory device.
Position in X.
Position in Y.
Scaling factor for X-axis * 1000.
Scaling factor for Y-axis * 1000.
Alpha blending factor, 0 - 255.
Additional information
A negative scaling factor mirrors the output.
Example
The following example creates 2 memory devices: hMem0 (40x10) and hMem1
(80x20). A small white text is drawn at the upper left position of hMem0 and hMem1.
Then the function GUI_MEMDEV_WriteEx() writes the contents of hMem0 to hMem1
using mirroring and magnifying:
GUI_MEMDEV_Handle hMem0, hMem1;
GUI_Init();
hMem0 = GUI_MEMDEV_Create(0, 0, 40, 10);
hMem1 = GUI_MEMDEV_Create(0, 0, 80, 20);
GUI_MEMDEV_Select(hMem0);
GUI_SetTextMode(GUI_TM_TRANS);
GUI_DispString("Text");
GUI_MEMDEV_Select(hMem1);
GUI_SetBkColor(GUI_RED);
GUI_Clear();
GUI_DispStringAt("Text", 0, 0);
GUI_MEMDEV_WriteExAt(hMem0, 0, 0, -2000, -2000, 160);
GUI_MEMDEV_CopyToLCD(hMem1);
Screenshot of the above example
GUI_SelectLCD()
Description
Selects the LCD as target for drawing operations.
Prototype
void GUI_SelectLCD(void))
Example for using a memory device
The Sample folder contains the following example which
can be used:
•
MEMDEV_MemDev.c
This example demonstrates the use of a memory device.
memory device and then copied to the display. Note that
make use of memory devices and may also be helpful to
User's & reference manual for emWin V5.10
shows how memory devices
Some items are written to a
several other examples also
get familiar with them.
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
266
CHAPTER
Memory Devices
Screenshot of the above example:
14.13 Banding memory device
A memory device is first filled by executing the specified drawing functions. After filling the device, the contents are drawn to the LCD. There may not be enough memory
available to store the complete output area at once, depending on your configuration
(see the GUI_ALLOC_SIZE configuration macro in the chapter “Configuration” on
page 905. A banding memory device divides the drawing area into bands, in which
each band covers as many lines as possible with the currently available memory.
GUI_MEMDEV_Draw()
Description
Basic drawing function that prevents flickering of the display.
Prototype
int GUI_MEMDEV_Draw(GUI_RECT* pRect,
GUI_CALLBACK_VOID_P* pfDraw,
void* pData,
int NumLines,
int Flags)
Parameter
pRect
pfDraw
pData
NumLines
Flags
Description
Pointer to a GUI_RECT structure for the used LCD area.
Pointer to a callback function for executing the drawing.
Pointer to a data structure used as parameter for the callback function.
0 (recommended) or number of lines for the memory device.
(see table below).
Permitted values for parameter Flags
GUI_MEMDEV_HASTRANS
(recommended)
GUI_MEMDEV_NOTRANS
User's & reference manual for emWin V5.10
Default: The memory device is created with a
transparency flag which ensures that the background will be drawn correctly.
Creates a memory device without transparency. The
user must make sure that the background is drawn
correctly. Should be used for optimization purposes
only.
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
267
Return value
0 if successful, 1 if the routine fails.
Additional information
If the parameter NumLines is 0, the number of lines in each band is calculated automatically by the function. The function then iterates over the output area band by
band by moving the origin of the memory device.
Example for using a banding memory device
The Sample folder contains the following example which shows how the function can
be used:
•
MEMDEV_Banding.c
Screen shot of above example
14.14 Auto device object
Memory devices are useful when the display must be updated to reflect the movement or changing of items, since it is important in such applications to prevent the
LCD from flickering. An auto device object is based on the banding memory device,
and may be more efficient for applications such as moving indicators, in which only a
small part of the display is updated at a time.
The device automatically distinguishes which areas of the display consist of fixed
objects and which areas consist of moving or changing objects that must be updated.
When the drawing function is called for the first time, all items are drawn. Each further call updates only the space used by the moving or changing objects. The actual
drawing operation uses the banding memory device, but only within the necessary
space. The main advantage of using an auto device object (versus direct usage of a
banding memory device) is that it saves computation time, since it does not keep
updating the entire display.
GUI_MEMDEV_CreateAuto()
Description
Creates an auto device object.
Prototype
int GUI_MEMDEV_CreateAuto(GUI_AUTODEV * pAutoDev);
Parameter
pAutoDev
Description
Pointer to a GUI_AUTODEV object.
Return value
Currently 0, reserved for later use.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
268
CHAPTER
Memory Devices
GUI_MEMDEV_DeleteAuto()
Description
Deletes an auto device object.
Prototype
void GUI_MEMDEV_DeleteAuto(GUI_AUTODEV * pAutoDev);
Parameter
pAutoDev
Description
Pointer to a GUI_AUTODEV object.
GUI_MEMDEV_DrawAuto()
Description
Executes a specified drawing routine using a banding memory device.
Prototype
int GUI_MEMDEV_DrawAuto(GUI_AUTODEV
GUI_AUTODEV_INFO
GUI_CALLBACK_VOID_P
void
Parameter
pAutoDev
pAutoDevInfo
pfDraw
pData
*
*
*
*
pAutoDev,
pAutoDevInfo,
pfDraw,
pData);
Description
Pointer to a GUI_AUTODEV object.
Pointer to a GUI_AUTODEV_INFO object.
Pointer to the user-defined drawing function which is to be executed.
Pointer to a data structure passed to the drawing function.
Return value
0 if successful, 1 if the routine fails.
Additional information
The GUI_AUTODEV_INFO structure contains the information about what items must be
drawn by the user function:
typedef struct {
char DrawFixed;
} GUI_AUTODEV_INFO;
DrawFixed is set to 1 if all items have to be drawn. It is set to 0 when only the moving or changing objects have to be drawn. We recommend the following procedure
when using this feature:
typedef struct {
GUI_AUTODEV_INFO AutoDevInfo; /* Information about what has to be drawn */
/* Additional data used by the user function */
...
} PARAM;
static void Draw(void * p) {
PARAM * pParam = (PARAM *)p;
if (pParam->AutoDevInfo.DrawFixed) {
/* Draw fixed background */
...
}
/* Draw moving objects */
...
if (pParam->AutoDevInfo.DrawFixed) {
/* Draw fixed foreground (if needed) */
...
}
}
void main(void) {
PARAM Param;
User's & reference manual for emWin V5.10
/* Parameters for drawing routine */
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
269
GUI_AUTODEV AutoDev;
/* Object for banding memory device */
/* Set/modify informations for drawing routine */
...
GUI_MEMDEV_CreateAuto(&AutoDev); /* Create GUI_AUTODEV-object */
GUI_MEMDEV_DrawAuto(&AutoDev,
/* Use GUI_AUTODEV-object for drawing */
&Param.AutoDevInfo,
&Draw,
&Param);
GUI_MEMDEV_DeleteAuto(&AutoDev); /* Delete GUI_AUTODEV-object */
}
Example for using an auto device object
The example MEMDEV_AutoDev.c demonstrates the use of an auto device object. It
can be found as MEMDEV_AutoDev.c. A scale with a moving needle is drawn in the
background and a small text is written in the foreground. The needle is drawn with
the antialiasing feature of emWin. High-resolution antialiasing is used here to
improve the appearance of the moving needle. For more information, see the chapter
“Antialiasing” on page 787.
Screen shot of above example
14.15 Measurement device object
Measurement devices are useful when you need to know the area used to draw
something. Creating and selecting a measurement device as target for drawing operations makes it possible to retrieve the rectangle used for drawing operations.
GUI_MEASDEV_Create()
Description
Creates a measurement device.
Prototype
GUI_MEASDEV_Handle GUI_MEASDEV_Create(void);
Return value
The handle of the measurement device.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
270
CHAPTER
Memory Devices
GUI_MEASDEV_ClearRect()
Description
Call this function to clear the measurement rectangle of the given measurement
device.
Prototype
void GUI_MEASDEV_ClearRect(GUI_MEASDEV_Handle hMem);
Parameter
hMem
Description
Handle to measurement device.
GUI_MEASDEV_Delete()
Description
Deletes a measurement device.
Prototype
void GUI_MEASDEV_Delete (GUI_MEASDEV_Handle hMem);
Parameter
hMem
Description
Handle to measurement device.
GUI_MEASDEV_GetRect()
Description
Retrieves the result of the drawing operations.
Prototype
void GUI_MEASDEV_GetRect(GUI_MEASDEV_Handle hMem, GUI_RECT *pRect);
Parameter
hMem
pRect
Description
Handle to measurement device.
Pointer to GUI_RECT-structure to store result.
GUI_MEASDEV_Select()
Description
Selects a measurement device as target for drawing operations.
Prototype
void GUI_MEASDEV_Select (GUI_MEASDEV_Handle hMem);
Parameter
hMem
Description
Handle to measurement device.
Example
The following example shows the use of a measurement device. It creates a measurement device, draws a line and displays the result of the measurement device:
void MainTask(void) {
GUI_MEASDEV_Handle hMeasdev;
GUI_RECT Rect;
GUI_Init();
hMeasdev = GUI_MEASDEV_Create();
GUI_MEASDEV_Select(hMeasdev);
GUI_DrawLine(10, 20, 30, 40);
GUI_SelectLCD();
GUI_MEASDEV_GetRect(hMeasdev, &Rect);
GUI_MEASDEV_Delete(hMeasdev);
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
271
GUI_DispString("X0:");
GUI_DispDec(Rect.x0, 3);
GUI_DispString(" Y0:");
GUI_DispDec(Rect.y0, 3);
GUI_DispString(" X1:");
GUI_DispDec(Rect.x1, 3);
GUI_DispString(" Y1:");
GUI_DispDec(Rect.y1, 3);
}
Screenshot of the above example:
14.16 Animation functions
Animations can be used to inject some life into the application. They will always help
to let the user’s eye smoothly capture what happens in the application.
GUI_MEMDEV_FadeDevices()
Description
Performs fading from one to another memory device.
Prototype
int GUI_MEMDEV_FadeDevices(GUI_MEMDEV_Handle hMem0,
GUI_MEMDEV_Handle hMem1,
int
Period);
Parameter
hMem0
hMem1
Period
Description
Handle to the memory device which has to be faded out.
Handle to the memory device which has to be faded in.
Time period in which the fading is processed.
Return value
0 if successful, 1 if the function fails.
Additional Information
Please note that this function only processes if hMem0 and hMem1 are of the same
size and are located at the same position on the screen.
Example
For
an
example
on
using
the
fading
functions,
please
refer
to
"MEMDEV_FadingPerformance.c" which can be found in "emWin\Sample\Tutorial".
Screenshots
GUI_MEMDEV_SetAnimationCallback()
Description
Sets a user defined callback function to be called while animations are processed.
The function should contain code to determine whether processing of the current animation shall go on or abort.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
272
CHAPTER
Memory Devices
Prototype
void GUI_MEMDEV_SetAnimationCallback(
GUI_ANIMATION_CALLBACK_FUNC * pCbAnimation,
void
* pVoid);
Parameter
Description
pCbAnimation Pointer to the user defined callback function.
Data pointer.
pVoid
Additional Information
The callback function is called every time an animation function has just copied the
actual step to the screen.
Example
The following example shows the use of a GUI_ANIMATION_CALLBACK_FUNC, which
gives the possibility to react on PID events:
static int _cbAnimation(int TimeRem, void * pVoid) {
int
Pressed;
if (TimeRem /* Insert Condition */) {
/* ... React on remaining Time ... */
}
Pressed = _GetButtonState();
if (Pressed) {
return 1;
// Button was
pressed, stop
animation
} else {
return 0;
// Button was not pressed, continue animation
}
}
void main(void) {
GUI_Init();
GUI_MEMDEV_SetAnimationCallback(_cbAnimation, (void *)&_Pressed);
while (1) {
/* Do animations... */
}
}
14.17 Animation functions (Window Manager required)
The following animation functions require usage of the window manager.
GUI_MEMDEV_FadeInWindow()
GUI_MEMDEV_FadeOutWindow()
Description
Fades in/out a window by decreasing/increasing the alpha value
Prototype
int GUI_MEMDEV_FadeInWindow (WM_HWIN hWin, int Period);
int GUI_MEMDEV_FadeOutWindow(WM_HWIN hWin, int Period);
Parameter
hWin
Period
Description
Handle to the window which has to be faded in/out
Time period in which the fading is processed
Return value
0 if successful, 1 if the function fails.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
273
Additional Information
Please note that the state of the current desktop and its child windows is ’valid’ after
calling this function.
Example
For
an
example
on
using
the
fading
functions,
please
refer
"SKINNING_NestedModal.c" which can be found in your "emWin\Sample" folder.
to
Screenshots
GUI_MEMDEV_MoveInWindow()
GUI_MEMDEV_MoveOutWindow()
Description
Moves a window into/out of the screen. First the window is drawn minimized/maximized at the specified position/its actual position and then moved to its actual position/the specified position while magnifying to its actual size/demagnifying. The
window can be spun clockwise as well as counterclockwise while it is moving.
Prototype
int GUI_MEMDEV_MoveInWindow (WM_HWIN hWin, int
int
int GUI_MEMDEV_MoveOutWindow(WM_HWIN hWin, int
int
Parameter
hWin
x
y
x,
a180,
x,
a180,
int
int
int
int
y,
Period);
y,
Period);
Description
Handle to the window which has to be moved
Position in x from/to where the window is moved
Position in y from/to where the window is moved
a180
Count of degrees the window will be spun for:
a180 = 0 -> no spinning
a180 > 0 -> clockwise
a180 < 0 -> counterclockwise
Period
Time period in which the moving is processed
Return value
0 if successful, 1 if the function fails.
Additional Information
Please note that the state of the current desktop and its child windows is ’valid’ after
calling this function. GUI_MEMDEV_MoveInWindow() / GUI_MEMDEV_MoveOutWindow()
requires approximately 1 MB of dynamic memory to run properly in QVGA mode.
Example
For
an
example
on
using
GUI_MEMDEV_MoveInWindow()
and
GUI_MEMDEV_MoveOutWindow(), please refer to "SKINNING_NestedModal.c" which
can be found in your "emWin\Sample" folder.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
274
CHAPTER
Memory Devices
Screenshots
GUI_MEMDEV_ShiftInWindow()
GUI_MEMDEV_ShiftOutWindow()
Description
Shifts a Window in a specified direction into/out of the screen to/from its actual position.
Prototype
int GUI_MEMDEV_ShiftInWindow (WM_HWIN hWin, int Period, int Direction);
int GUI_MEMDEV_ShiftOutWindow(WM_HWIN hWin, int Period, int Direction);
Parameter
hWin
Period
Direction
Description
Handle to the window which has to be shifted
Time period in which the shifting is processed
Direction the window is shifted from/to.
Return value
0 if successful, 1 if the function fails.
Additional Information
Please note that the state of the current desktop and its child windows is ’valid’ after
a
window
has
been
shifted.
GUI_MEMDEV_ShiftInWindow()
and
GUI_MEMDEV_ShiftOutWindow() require approximately 1 MB of dynamic memory to
run properly in QVGA mode.
Example
For
an
example
on
using
GUI_MEMDEV_ShiftInWindow()
and
GUI_MEMDEV_ShiftOutWindow(), please refer to "SKINNING_Notepad.c" which can
be found in your "emWin\Sample" folder.
Screenshots
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
275
GUI_MEMDEV_ShiftWindow()
Description
Shifts a window in a specified direction into the screen to its actual position and
shifts out the old content of the window area.
Prototype
int GUI_MEMDEV_ShiftWindow(WM_HWIN hWin, int Period, int Edge);
Parameter
hWin
Period
Edge
Description
Handle to the window which has to be shifted
Time period in which the shifting is processed
Direction the window is shifted from/to.
Return value
0 if successful, 1 if the function fails.
Additional Information
Please note that the state of the current desktop and its child windows is ’valid’ after
a window has been swapped. GUI_MEMDEV_ShiftWindow() requires approximately 1
MB of dynamic memory to run properly in QVGA mode.
Screenshots
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
276
User's & reference manual for emWin V5.10
CHAPTER
Memory Devices
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
277
Chapter 15
Execution Model: Single Task /
Multitask
emWin has been designed from the beginning to be compatible with different types of
environments. It works in single task and in multitask applications, with a proprietary
operating system or with any commercial RTOS such as embOS or uC/OS.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
278
CHAPTER
Execution Model: Single Task / Multitask
15.1 Supported execution models
We have to basically distinguish between 3 different execution models:
Single task system (superloop)
The entire program runs in one superloop. Normally, all software components are
periodically called. Interrupts must be used for real time parts of the software since
no real time kernel is used.
Multitask system: one task calling emWin
A real time kernel (RTOS) is used, but only one task calls emWin functions. From the
graphic software’s point of view, it is the same as being used in a single task system.
Multitask system: multiple tasks calling emWin
A real time kernel (RTOS) is used, and multiple tasks call emWin functions. This
works without a problem as long as the software is made thread-safe, which is done
by enabling multitask support in the configuration and adapting the kernel interface
routines. For popular kernels, the kernel interface routines are readily available.
15.2 Single task system (superloop)
15.2.1 Description
The entire program runs in one superloop. Normally, all components of the software
are periodically called. No real time kernel is used, so interrupts must be used for
real time parts of the software. This type of system is primarily used in smaller systems or if real time behavior is not critical.
15.2.2 Superloop example (without emWin)
void main (void) {
HARDWARE_Init();
/* Init software components */
XXX_Init();
YYY_Init();
/* Superloop: call all software components regularily */
while (1) {
/* Exec all compontents of the software */
XXX_Exec();
YYY_Exec();
}
}
15.2.3 Advantages
No real time kernel is used (-> smaller ROM size, just one stack -> less RAM for
stacks), no preemption/synchronization problems.
15.2.4 Disadvantages
The superloop type of program can become hard to maintain if it exceeds a certain
program size. Real time behavior is poor, since one software component cannot be
interrupted by any other component (only by interrupts). This means that the reaction time of one software component depends on the execution time of all other components in the system.
15.2.5 Using emWin
There are no real restrictions regarding the use of emWin. As always, GUI_Init()
has to be called before you can use the software. From there on, any API function
can be used. If the window manager’s callback mechanism is used, then an emWin
update function has to be called regularly. This is typically done by calling the
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
279
GUI_Exec() from within the superloop. Blocking functions such as GUI_Delay() and
GUI_ExecDialog() should not be used in the loop since they would block the other
software modules.
The default configuration, which does not support multitasking (#define GUI_OS 0)
can be used; kernel interface routines are not required.
15.2.6 Superloop example (with emWin)
void main (void) {
HARDWARE_Init();
/* Init software components */
XXX_Init();
YYY_Init();
GUI_Init();
/* Init emWin */
/* Superloop: call all software components regularily */
while (1) {
/* Exec all compontents of the software */
XXX_Exec();
YYY_Exec();
GUI_Exec();
/* Exec emWin for functionality like updating windows */
}
}
15.3 Multitask system: one task calling emWin
15.3.1 Description
A real time kernel (RTOS) is used. The user program is split into different parts,
which execute in different tasks and typically have different priorities. Normally the
real time critical tasks (which require a certain reaction time) will have the highest
priorities. One single task is used for the user interface, which calls emWin functions. This task usually has the lowest priority in the system or at least one of the
lowest (some statistical tasks or simple idle processing may have even lower priorities).
Interrupts can, but do not have to be used for real time parts of the software.
15.3.2 Advantages
The real time behavior of the system is excellent. The real time behavior of a task is
affected only by tasks running at higher priority. This means that changes to a program component running in a low priority task do not affect the real time behavior at
all. If the user interface is executed from a low priority task, this means that changes
to the user interface do not affect the real time behavior. This kind of system makes
it easy to assign different components of the software to different members of the
development team, which can work to a high degree independently from each other.
15.3.3 Disadvantages
You need to have a real time kernel (RTOS), which costs money and uses up ROM and
RAM (for stacks). In addition, you will have to think about task synchronization and
how to transfer information from one task to another.
15.3.4 Using emWin
If the window manager’s callback mechanism is used, then an emWin update function
(typically GUI_Exec(), GUI_Delay()) has to be called regularly from the task calling
emWin. Since emWin is only called by one task, to emWin it is the same as being
used in a single task system.
The default configuration, which does not support multitasking (#define GUI_OS 0)
can be used; kernel interface routines are not required. You can use any real time
kernel, commercial or proprietary.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
280
CHAPTER
Execution Model: Single Task / Multitask
15.4 Multitask system: multiple tasks calling emWin
15.4.1 Description
A real time kernel (RTOS) is used. The user program is split into different parts,
which execute in different tasks with typically different priorities. Normally the real
time critical tasks (which require a certain reaction time) will have the highest priorities. Multiple tasks are used for the user interface, calling emWin functions. These
tasks typically have low priorities in the system, so they do not affect the real time
behavior of the system.
Interrupts can, but do not have to be used for real time parts of the software.
15.4.2 Advantages
The real time behavior of the system is excellent. The real time behavior of a task is
affected only by tasks running at higher priority. This means that changes of a program component running in a low priority task do not affect the real time behavior at
all. If the user interface is executed from a low priority task, this means that changes
on the user interface do not affect the real time behavior. This kind of system makes
it easy to assign different components of the software to different members of the
development team, which can work to a high degree independently from each other.
15.4.3 Disadvantages
You have to have a real time kernel (RTOS), which costs money and uses up some
ROM and RAM (for stacks). In addition, you will have to think about task synchronization and how to transfer information from one task to another.
15.4.4 Using emWin
If the window manager’s callback mechanism is used, then an emWin update function
(typically GUI_Exec(), GUI_Delay()) has to be called regularly from one or more
tasks calling emWin.
The default configuration, which does not support multitasking (#define GUI_OS 0)
can NOT be used. The configuration needs to enable multitasking support and define
a maximum number of tasks from which emWin is called (excerpt from GUIConf.h):
#define GUI_OS 1
#define GUI_MAX_TASK 5
// Enable multitasking support
// Max. number of tasks that may call emWin
Kernel interface routines are required, and need to match the kernel being used. You
can use any real time kernel, commercial or proprietary. Both the macros and the
routines are discussed in the following chapter sections.
15.4.5 Recommendations
•
•
•
Call the emWin update functions (that is, GUI_Exec(), GUI_Delay()) from just
one task. It will help to keep the program structure clear. If you have sufficient
RAM in your system, dedicate one task (with the lowest priority) to updating
emWin. This task will continuously call GUI_Exec() as shown in the example
below and will do nothing else.
Keep your real time tasks (which determine the behavior of your system with
respect to I/O, interface, network, etc.) separate from tasks that call emWin.
This will help to assure best real time performance.
If possible, use only one task for your user interface. This helps to keep the program structure simple and simplifies debugging. (However, this is not required
and may not be suitable in some systems.)
15.4.6 Example
This excerpt shows the dedicated emWin update task. It is taken from the example
MT_Multitasking, which is included in the examples shipped with emWin:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
281
/*******************************************************************
*
*
GUI background processing
*
* This task does the background processing.
* The main job is to update invalid windows, but other things such as
* evaluating mouse or touch input may also be done.
*/
void GUI_Task(void) {
while(1) {
GUI_Exec();
/* Do the background work ... Update windows etc.) */
GUI_X_ExecIdle();
/* Nothing left to do for the moment ... Idle processing */
}
}
15.5 GUI configuration functions for
multitasking support
The following table shows the configuration functions available for a multitask system
with multiple tasks calling emWin:
Routine
Description
Sets a function that signals an event.
GUI_SetSignalEventFunc()
Sets a function that waits for an event.
GUI_SetWaitEventFunc()
GUI_SetWaitEventTimedFunc() Sets a function that waits for an event for a given period of time.
GUI_SetSignalEventFunc()
Description
Sets a function that signals an event.
Prototype
void GUI_SetSignalEventFunc(GUI_SIGNAL_EVENT_FUNC pfSignalEvent);
Parameter
pfSignalEvent
Description
Pointer to a function that signals an event.
Definition of GUI_SIGNAL_EVENT_FUNC
typedef void (* GUI_SIGNAL_EVENT_FUNC)(void);
Additional information
Per default the GUI needs to periodically check for events unless a function is defined
which waits and one that triggers an event. This function sets the function which triggers an event. It makes only sense in combination with GUI_SetWaitEventFunc().
and GUI_SetWaitEventTimedFunc(). The advantage of using these functions instead
of polling is the reduction of CPU load of the waiting task to 0% while it waits for
input. If the function has been specified as recommended and the user gives the system any input (keyboard or pointer input device) the specified function should signal
an event.
It is recommended to specify the function GUI_X_SignalEvent() for the job.
Example
GUI_SetSignalEventFunc(GUI_X_SignalEvent);
GUI_SetWaitEventFunc()
Description
Sets a function which waits for an event.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
282
CHAPTER
Execution Model: Single Task / Multitask
Prototype
void GUI_SetWaitEventFunc(GUI_WAIT_EVENT_FUNC pfWaitEvent);
Parameter
pfWaitEvent
Description
Pointer to a function that waits for an event.
Definition of GUI_SIGNAL_EVENT_FUNC
typedef void (* GUI_WAIT_EVENT_FUNC)(void);
Additional information
Per default the GUI needs to periodically check for events unless a function is defined
which waits and one that triggers an event. This function sets the function which
waits
for
an
event.
Makes
only
sense
in
combination
with
GUI_SetSignalEventFunc() and GUI_SetWaitEventTimedFunc(). The advantage of
using these functions instead of polling is the reduction of CPU load of the waiting
task to 0% while it waits for input. If the function has been specified as recommended and the system waits for user input the defined function should wait for an
event signaled from the function specified by GUI_SetSignalEventFunc().
It is recommended to specify the function GUI_X_WaitEvent() for the job.
Example
GUI_SetWaitEventFunc(GUI_X_WaitEvent);
GUI_SetWaitEventTimedFunc()
Description
Defines a function which waits for an event for a dedicated period of time.
Prototype
void GUI_SetWaitEventTimedFunc(GUI_WAIT_EVENT_TIMED_FUNC pfWaitEventTimed);
Parameter
pfWaitEventTimed
Description
Pointer to a function that waits for an event.
Definition of GUI_WAIT_EVENT_TIMED_FUNC
typedef void (* GUI_WAIT_EVENT_TIMED_FUNC)(int Period);
Parameter
Period
Description
Period in ms to wait for an event.
Additional information
Per default the GUI needs to periodically check for events unless a function is defined
which waits and one that triggers an event. This function sets the function which
waits for an event if a timer is active. Makes only sense in combination with
GUI_SetSignalEventFunc() and GUI_SetWaitEventFunc(). If the function has been
specified as recommended and the system waits for user input during a timer is
active the defined function should wait until the timer expires or an event signaled
from the function set by GUI_SetSignalEventFunc().
It is recommended to specify the function GUI_X_WaitEventTimed() for the job.
Example
GUI_SetWaitEventTimedFunc(GUI_X_WaitEventTimed);
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
283
15.6 GUI configuration macros for multitasking support
The following table shows the configuration macros used for a multitask system with
multiple tasks calling emWin:
Type
Macro
Default
Explanation
Defines the maximum number of tasks
from which emWin is called when multitasking support is enabled.
N
GUI_MAXTASK
4
B
GUI_OS
0
Activate to enable multitasking support.
F
GUI_X_SIGNAL_EVENT
-
Defines a function that signals an event.
(Obsolete)
F
GUI_X_WAIT_EVENT
GUI_X_ExecIdle
Defines a function that waits for an event.
(Obsolete)
F
GUI_X_WAIT_EVENT_TIMED -
Defines a function that waits for an event
for a dedicated period of time. (Obsolete)
GUI_MAXTASK
Description
Defines the maximum number of tasks from which emWin is called to access the display.
Type
Numerical value.
Additional information
This symbol is only relevant when GUI_OS is activated. If working with a pre-compiled
library the function GUITASK_SetMaxTask() should be used instead. For further information, please refer to “GUITASK_SetMaxTask()” on page 908.
GUI_OS
Description
Enables multitasking support by activating the module GUITask.
Type
Binary switch
0: inactive, multitask support disabled (default)
1: active, multitask support enabled
GUI_X_SIGNAL_EVENT
Description
Defines a function that signals an event.
Type
Function replacement
Additional information
Per default the GUI needs to periodically check for events unless a function is defined
which waits and one that triggers an event. This macro defines the function which
triggers an event. It makes only sense in combination with GUI_X_WAIT_EVENT. The
advantage of using the macros GUI_X_SIGNAL_EVENT and GUI_X_WAIT_EVENT instead
of polling is the reduction of CPU load of the waiting task to 0% while it waits for
input. If the macro has been defined as recommended and the user gives the system
any input (keyboard or pointer input device) the defined function should signal an
event.
It is recommended to specify the function GUI_X_SignalEvent() for the job.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
284
CHAPTER
Execution Model: Single Task / Multitask
Example
#define GUI_X_SIGNAL_EVENT GUI_X_SignalEvent
GUI_X_WAIT_EVENT
Description
Defines a function which waits for an event.
Type
Function replacement
Additional information
Per default the GUI needs to periodically check for events unless a function is defined
which waits and one that triggers an event. This macro defines the function which
waits for an event. Makes only sense in combination with GUI_X_SIGNAL_EVENT. The
advantage of using the macros GUI_X_SIGNAL_EVENT and GUI_X_WAIT_EVENT instead
of polling is the reduction of CPU load of the waiting task to 0% while it waits for
input. If the macro has been defined as recommended and the system waits for user
input the defined function should wait for an event signaled from the function defined
by the macro GUI_X_SIGNAL_EVENT.
It is recommended to specify the function GUI_X_WaitEvent() for the job.
Example
#define GUI_X_WAIT_EVENT GUI_X_WaitEvent
GUI_X_WAIT_EVENT_TIMED
Description
Defines a function which waits for an event for a dedicated period of time.
Type
Function replacement
Additional information
Per default the GUI needs to periodically check for events unless a function is defined
which waits and one that triggers an event. This macro defines the function which
waits for an event if a timer is active. Makes only sense in combination with
GUI_X_SIGNAL_EVENT. If the macro has been defined as recommended and the system waits for user input during a timer is active the defined function should wait until
the timer expires or an event signaled from the function defined by the macro
GUI_X_SIGNAL_EVENT.
It is recommended to specify the function GUI_X_WaitEventTimed() for the job.
Example
#define GUI_X_WAIT_EVENT_TIMED GUI_X_WaitEventTimed
15.7 Kernel interface API
An RTOS usually offers a mechanism called a resource semaphore, in which a task
using a particular resource claims that resource before actually using it. The display
is an example of a resource that needs to be protected with a resource semaphore.
emWin uses the macro GUI_USE to call the function GUI_Use() before it accesses the
display or before it uses a critical internal data structure. In a similar way, it calls
GUI_Unuse() after accessing the display or using the data structure. This is done in
the module GUITask.c.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
285
GUITask.c in turn uses the GUI kernel interface routines shown in the table below.
These routines are prefixed GUI_X_ since they are high-level (hardware-dependent)
functions. They must be adapted to the real time kernel used in order to make the
emWin task (or thread) safe. Detailed descriptions of the routines follow, as well as
examples of how they are adapted for different kernels.
Routine
Explanation
GUI_X_GetTaskId()
Return a unique, 32-bit identifier for the current task/thread.
GUI_X_InitOS()
Initialize the kernel interface module (create a resource semaphore/
mutex).
GUI_X_Lock()
GUI_X_SignalEvent()
GUI_X_Unlock()
GUI_X_WaitEvent()
Lock the GUI (block resource semaphore/mutex).
Signals an event.
Unlock the GUI (unblock resource semaphore/mutex).
Waits for an event.
GUI_X_GetTaskID()
Description
Returns a unique ID for the current task.
Prototype
U32 GUI_X_GetTaskID(void);
Return value
ID of the current task as a 32-bit integer.
Additional information
Used with a real-time operating system.
It does not matter which value is returned, as long as it is unique for each task/
thread using the emWin API and as long as the value is always the same for each
particular thread.
GUI_X_InitOS()
Description
Creates the resource semaphore or mutex typically used by GUI_X_Lock() and
GUI_X_Unlock().
Prototype
void GUI_X_InitOS(void)
GUI_X_Lock()
Description
Locks the GUI.
Prototype
void GUI_X_Lock(void);
Additional information
This routine is called by the GUI before it accesses the display or before using a critical internal data structure. It blocks other threads from entering the same critical
section using a resource semaphore/mutex until GUI_X_Unlock() has been called.
When using a real time operating system, you normally have to increment a counting
resource semaphore.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
286
CHAPTER
Execution Model: Single Task / Multitask
GUI_X_SignalEvent()
Description
Signals an event.
Prototype
void GUI_X_SignalEvent(void);
Additional information
This function is optional, it is used only via the macro GUI_X_SIGNAL_EVENT or the
function GUI_SetSignalEventFunc().
GUI_X_Unlock()
Description
Unlocks the GUI.
Prototype
void GUI_X_Unlock(void);
Additional information
This routine is called by the GUI after accessing the display or after using a critical
internal data structure.
When using a real time operating system, you normally have to decrement a counting resource semaphore.
GUI_X_WaitEvent()
Description
Waits for an event.
Prototype
void GUI_X_WaitEvent(void);
Additional information
This function is optional, it is used only via the macro GUI_X_WAIT_EVENT or the function GUI_SetWaitEventFunc().
GUI_X_WaitEventTimed()
Description
Waits for an event for the given period.
Prototype
void GUI_X_WaitEventTimed(int Period);
Parameter
Period
Description
Period in ms to be used.
Additional information
This function is optional, it is used only via the macro GUI_X_WAIT_EVENT_TIMED or
the function GUI_SetWaitEventTimedFunc().
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
287
15.7.1 Examples
Kernel interface routines for embOS
The following example shows an adaption for
GUI_X_embOS.c located in the folder Sample\GUI_X):
embOS
(excerpt
from
file
#include "RTOS.H"
static OS_TASK* _pGUITask;
static OS_RSEMA _RSema;
void
void
void
U32
GUI_X_InitOS(void)
GUI_X_Unlock(void)
GUI_X_Lock(void)
GUI_X_GetTaskId(void)
{
{
{
{
OS_CreateRSema(&_RSema);
OS_Unuse(&_RSema);
OS_Use(&_RSema);
return (U32)OS_GetTaskID();
}
}
}
}
void GUI_X_WaitEvent(void) {
_pGUITask = OS_GetpCurrentTask();
OS_WaitEvent(1);
}
void GUI_X_SignalEvent(void) {
if (_pGUITask) {
OS_SignalEvent(1, _pGUITask);
}
}
void GUI_X_WaitEventTimed(int Period) {
static OS_TIMER Timer;
static int Initialized;
if (Period > 0) {
if (Initialized != 0) {
OS_DeleteTimer(&Timer);
}
Initialized = 1;
OS_CreateTimer(&Timer, GUI_X_SignalEvent, Period);
OS_StartTimer(&Timer);
GUI_X_WaitEvent();
}
}
Kernel interface routines for uC/OS
The following example shows an adaption for uC/OS (excerpt from file GUI_X_uCOS.c
located in the folder Sample\GUI_X):
#include "INCLUDES.H"
static OS_EVENT * pDispSem;
static OS_EVENT * pGUITask;
U32
void
GUI_X_GetTaskId(void) { return ((U32)(OSTCBCur->OSTCBPrio)); }
GUI_X_Unlock(void)
{ OSSemPost(pDispSem);
}
void GUI_X_InitOS(void)
{
pDispSem = OSSemCreate(1);
pGUITask = OSSemCreate(0);
}
void GUI_X_Lock(void)
{
INT8U err;
OSSemPend(pDispSem, 0, &err);
}
Kernel interface routines for Win32
The following is an excerpt from the Win32 simulation for emWin. (When using the
emWin simulation, there is no need to add these routines, as they are already in the
library.)
Note: cleanup code has been omitted for clarity.
/*********************************************************************
*
*
emWin - Multitask interface for Win32
*
**********************************************************************
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
288
CHAPTER
Execution Model: Single Task / Multitask
The following section consisting of 4 routines is used to make
emWin thread safe with WIN32
*/
static HANDLE hMutex;
void GUI_X_InitOS(void) {
hMutex = CreateMutex(NULL, 0, "emWinSim - Mutex");
}
unsigned int GUI_X_GetTaskId(void) {
return GetCurrentThreadId();
}
void GUI_X_Lock(void) {
WaitForSingleObject(hMutex, INFINITE);
}
void GUI_X_Unlock(void) {
ReleaseMutex(hMutex);
}
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
289
Chapter 16
The Window Manager (WM)
When using the emWin window manager (WM), everything which appears on the display is contained in a window -- a rectangular area on the screen. A window can be
any size, and you can display multiple windows on the screen at once, even partially
or entirely in front of other windows.
The window manager supplies a set of routines which allow you to easily create,
move, resize, and otherwise manipulate any number of windows. It also provides
lower-level support by managing the layering of windows on the display and by alerting your application to display changes that affect its windows.
The emWin window manager is a separate (optional) software item and is not
included in the emWin basic package. The software for the window manager is
located in the subdirectory GUI\WM.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
290
CHAPTER
The Window Manager (WM)
16.1 Description of terms
Windows are rectangular in shape, defined by their origin (the X- and Y-coordinates
of the upper left corner) as well as their X- and Y-sizes (width and height, respectively). A window in emWin:
•
•
•
•
•
•
is rectangular.
has a Z-position.
may be hidden or shown.
may have valid and/or invalid areas.
may or may not have transparency.
may or may not have a callback routine.
Active window
The window which is currently being used for drawing operations is referred to as the
active window. It is not necessarily the same as the topmost window.
Callback routines
Callback routines are defined by the user program, instructing the graphic system to
call a specific function when a specific event occurs. Normally they are used to automatically redraw a window when its content has changed.
Child/parent windows, siblings
A child window is one that is defined relative to another window, called the parent.
Whenever a parent window moves, its child or children move correspondingly. A child
window is always completely contained within its parent, and will be clipped if necessary. Multiple child windows with the same parent are considered "siblings" to one
another.
Client area
The client area of a window is simply its usable area. If a window contains a frame or
title bar, then the client area is the rectangular inner area. If there is no such frame,
then the coordinates of the client area are identical to those of the window itself.
Clipping, clip area
Clipping is the process of limiting output to a window or part of it.
The clip area of a window is its visible area. This is the window area minus the area
obstructed by siblings of higher Z-order, minus any part that does not fit into the visible area of the parent window.
Coordinates
Coordinates are usually 2 dimensional coordinates, expressed in units of pixels. A
coordinate consists of 2 values. The first value specifies the horizontal component
(also called the x-coordinate), the second value specifies the vertical component
(also called the y-coordinate).
Desktop coordinates
Desktop coordinates are coordinates of the desktop window. The upper left position
(the origin) of the display is (0,0).
Desktop window
The desktop window is automatically created by the window manager, and always
covers the entire display area. It is always the bottommost window, and when no
other window has been defined, it is the default (active) window. All windows are
descendants (children, grandchildren, etc.) of the desktop window.
Handle
When a new window is created, the WM assigns it a unique identifier called a handle.
The handle is used in any further operations performed on that particular window.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
291
Hiding/showing windows
A hidden window is not visible, although it still exists (has a handle). When a window
is created, it is hidden by default if no create flag is specified. Showing a window
makes it visible; hiding it makes it invisible.
Parent coordinates
Parent coordinates are window coordinates relative to the parent window. The upper
left position (the origin) of the window is (0,0).
Transparency
A window that has transparency contains areas that are not redrawn with the rest of
the window. These areas operate as though the window behind "shows through"
them. In this case, it is important that the window behind is redrawn before the window with transparency. The WM automatically handles redrawing in the correct order.
Validation/invalidation
A valid window is a fully updated window which does not need redrawing.
An invalid window does not yet reflect all updates and therefore needs to be redrawn,
either completely or partially. When changes are made that affect a particular window, the WM marks that window as invalid. The next time the window is redrawn
(either manually or by a callback routine) it will be validated.
Window coordinates
Window coordinates are coordinates of a window. The upper left position (the origin)
of the window is (0,0).
Z-position, bottom/top
Although a window is displayed on a two-dimensional screen in terms of X and Y, the
WM also manages what is known as a Z-position, or depth coordinate -- a position in
a virtual third dimension which determines its placement from background to foreground. Windows can therefore appear on top of or beneath one another.
Setting a window to the bottom will place it "underneath" all of its sibling windows (if
any); setting it to the top will place it "on top of" its siblings. When a window is created, it is set to the top by default if no create flag is specified.
16.2 Callback mechanism, invalidation and rendering
The WM may be used with or without callback routines. In most cases, using callbacks is preferable.
The idea behind the callback mechanism that emWin offers for windows and window
objects (widgets) is that of an event-driven system. As in most windowing systems,
the principle is that the flow of control is not just from the user program to the
graphic system, but also from the user program to the graphic system and back up to
the user program by means of the callback routines provided by the user program.
This mechanism -- often characterized as the Hollywood principle ("Don't call us,
we’ll call you!") -- is needed by the window manager mainly in order to trigger the
redrawing of windows. This contrasts with classical programming, but it makes it
possible to exploit the invalidation logic of the window manager.
16.2.1 Rendering without callbacks
You do not have to use callback routines, but in doing so, the WM loses the ability to
manage redrawing (updating) of the windows. It is also possible to mix; for example,
having some windows use callbacks and others not. However, if a window does not
use the callback mechanism, your application is responsible for updating its contents.
Warning: When not using the callback mechanism, it is your responsibility to
manage screen updates!
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
292
CHAPTER
The Window Manager (WM)
16.2.2 Rendering using callbacks
In order to create a window with a callback, you must have a callback routine. The
routine is used as part of the WM_CreateWindow() function when creating the window
(the cb parameter).
All callback routines must have the following prototype:
Prototype
void callback(WM_MESSAGE * pMsg);
Parameter
pMsg
Description
Pointer to a data structure of type WM_MESSAGE.
The action performed by the callback routine depends on the type of message it
receives. The prototype above is usually followed by a switch statement, which
defines different behaviors for different messages using one or more case statements (typically at least WM_PAINT).
Processing the WM_PAINT message
When a window receives a WM_PAINT message, it should repaint itself. Before sending
this message to the window, the WM makes sure it is selected.
A non transparent window (default!) has to repaint its entire invalid area.
The easiest way is to repaint the entire area of the window. The clipping mechanism
of the WM makes sure that only the invalid area will be redrawn. In order to accelerate the drawing process, it can make sense to only repaint the invalid area. How to
get the invalid area is described later in this chapter (Information is part of the message).
A transparent window on the other hand does not have to redraw the entire invalid
area; it can leave the window area partially untouched. This untouched area will then
be transparent.
Before the WM sends a WM_PAINT message to a transparent window, the area below
has been redrawn (by sending a WM_PAINT message to the window(s) below).
Warning: Certain things should not be done when processing WM_PAINT
When processing the WM_PAINT message, the callback routine should do nothing but
redrawing the contents of the window. When processing the WM_PAINT event, the following
functions
may
not
be
called:
WM_SelectWindow(),
WM_Paint(),
WM_DeleteWindow() and WM_CreateWindow(). Also any other functions which
changes the properties of a window may not be called: WM_Move(), WM_Resize(), ...
Example
Creates a callback routine to automatically redraw a window:
void WinHandler(WM_MESSAGE * pMsg) {
switch (pMsg->MsgId) {
case WM_PAINT:
GUI_SetBkColor(0xFF00);
GUI_Clear();
GUI_DispStringAt("Hello world",0,0);
break;
default:
WM_DefaultProc(pMsg);
}
}
Please note that a WM_PRE_PAINT and a WM_POST_PAINT message is processed directly
before and after WM_PAINT messages are sent.
16.2.3 Background window redrawing and callback
During initialization of the window manager, a window containing the whole LCD area
is created as a background window. The handle of this window is WM_HBKWIN. The WM
does not redraw areas of the background window automatically, because there is no
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
293
default background color. That means if you create a further window and then delete
it, the deleted window will still be visible. The routine WM_SetDesktopColor() needs
to be specified in order to set a color for redrawing the background window.
You can also set a callback function to take care of this problem. If a window is created and then deleted as before, the callback routine will trigger the WM to recognize
that the background window is no longer valid and redraw it automatically. For more
information on using a callback routine to redraw the background, see the example
at the end of the chapter.
16.2.4 Invalidation
Invalidation of a window or a part of it tells the WM that the invalid area of the window should be redrawn the next time GUI_Exec() or GUI_Delay() is called. The
invalidation routines of emWin do not redraw the invalid part of a window. They only
manage the invalid areas of the windows.
The invalid area of a window
The WM uses just one rectangle per window to store the smallest rectangle containing the entire invalid area. If for example a small part in the upper left corner and a
small part in the lower right corner becomes invalid, the complete window is invalidated.
Why using invalidation
The advantage of using window invalidation in opposite of drawing each window
immediately is that the window will be drawn only one time even if it is invalidated
more than one time. If for example several properties of a window need to be
changed (for example the background color, the font and the size of the window) it
takes more time to draw the window immediately after each property has been
changed than drawing the window only one time after all properties have been
changed.
Redrawing of invalid windows
The function GUI_Exec() redraws all invalid windows. This is done by sending one or
more WM_PAINT messages to each invalid window.
16.2.5 Rendering of transparent windows
If a transparent window needs to be drawn, the WM automatically makes sure, that
the background of the window is drawn before the transparent window receives a
WM_PAINT message. This is done by redrawing all window areas below the invalid area
of the transparent window first before sending a WM_PAINT message to the transparent window.
To make sure the window manager can handle the redrawing of transparent windows
it is necessary to redraw the window in reaction to the WM_PAINT message. Otherwise
it can not be guaranteed that the appearance of a transparent window will be correctly.
The use of transparent windows is more CPU-intensive than the use of non transparent windows. If performance is a problem, trying to avoid transparent windows may
be an option.
16.2.6 Automatic use of memory devices
The default behavior of the window manager is sending a WM_PAINT to each window
which needs to be redrawn. This can cause flickering effects. To suppress these ’per
window’ flickering effects memory devices can be used automatically for the drawing
operation. This can be achieved by setting the flag WM_CF_MEMDEV when creating the
window, by setting the default creation flags with WM_SetCreateFlags() or by using
the function WM_EnableMemdev(). The WM then redirects the output of the WM_PAINT
message into a memory device which is then copied to the display. If not enough
memory for the whole window is available banding is used automatically. The memory device is only used temporarily and will be removed after the drawing operation.
For more information please also refer to chapter “Memory Devices” on page 247.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
294
CHAPTER
The Window Manager (WM)
16.2.7 Automatic use of multiple frame buffers
The WM is able to use automatically multiple frame buffers if they are available. This
can be achieved by the function WM_MULTIBUF_Enable(). If enabled the window manager redirects the output of all drawing functions to the invisible back buffer before it
draws the invalid windows. After the last invalid window has been drawn the WM
makes the back buffer visible. Please note that feature is only available if the display
driver supports multiple buffers and if there is enough RAM for at least 2 frame buffers. For more information please also refer to chapter “Multiple buffering” on
page 729.
16.2.8 Automatic use of display driver cache
The WM automatically uses the display driver cache if available. If available it locks
the buffer before it starts to draw the invalid windows. After the last window has
been drawn the WM unlocks the cache.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
295
16.3 Messages
The following section shows which system messages are used by emWin, how to use
the message data and how to use application defined messages.
16.3.1 Message structure
When a callback routine is called, it receives the message specified as its pMsg
parameter. This message is actually a WM_MESSAGE data structure, with elements
defined as follows.
Elements of WM_MESSAGE
Data type Element
int
WM_HWIN
WM_HWIN
void*
int
MsgId
hWin
hWinSrc
Data.p
Data.v
Description
Type of message (see table below).
Destination window.
Source window.
Data pointer.
Data value.
16.3.2 List of messages
The following messages are defined by emWin.
Message Id
(MsgId)
Description
System defined messages
WM_CREATE
Sent immediately after a window has been created, giving
the window the chance to initialize and create any child
windows.
WM_DELETE
Sent just before a window is deleted, telling the window to
free its data structures (if any).
WM_GET_ID
Sent to a window to request the Id of the window.
WM_INIT_DIALOG
Sent to a dialog window immediately after the creation of
the dialog.
WM_KEY
Sent to the window currently containing the focus if a key
has been pressed.
WM_MOVE
Sent to a window immediately after it has been moved.
WM_NOTIFY_PARENT
Informs a parent window that something has occurred in
one of its child windows.
WM_NOTIFY_VIS_CHANGED
Sent to a window if its visibility has been changed.
WM_PAINT
Sent to a window after it has become invalid and it should
be redrawn.
WM_POST_PAINT
Sent to a window after the last WM_PAINT message was
processed.
WM_PRE_PAINT
Sent to a window before the first WM_PAINT message is
sent.
WM_SET_FOCUS
WM_SET_ID
WM_SIZE
WM_TIMER
Sent to a window if it gains or looses the input focus.
Sent to a window to change the window Id.
Sent to a window after its size has changed.
Sent to a window after a timer has expired.
Pointer input device (PID) messages
WM_MOUSEOVER
Sent to a window if a pointer input device touches the outline of a window. Only send if mouse support is enabled.
WM_MOUSEOVER_END
Sent to a window if a pointer input device has been moved
out of the outline of a window. Only sent if mouse support
is enabled.
WM_PID_STATE_CHANGED
Sent to the window pointed by the pointer input device
when the pressed state has been changed.
WM_TOUCH
Sent to a window if a pointer input device touches the outline of a window in pressed state.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
296
CHAPTER
Message Id
(MsgId)
The Window Manager (WM)
Description
Sent to a parent window if a child window has been
touched by the pointer input device.
WM_TOUCH_CHILD
Notification codes
WM_NOTIFICATION_CHILD_DELETED
This notification message will be sent from a window to its
parent before it is deleted.
WM_NOTIFICATION_CLICKED
This notification message will be sent when the window
has been clicked.
WM_NOTIFICATION_LOST_FOCUS
This notification message will be sent when the window
has lost the focus.
WM_NOTIFICATION_MOVED_OUT
This notification message will be sent when the pointer
was moved out of the window while it is clicked.
WM_NOTIFICATION_RELEASED
This notification message will be sent when a clicked widget has been released.
WM_NOTIFICATION_SCROLL_CHANGED
This notification message will be sent when the scroll position of an attached SCROLLBAR widget has changed.
WM_NOTIFICATION_SCROLLBAR_ADDED
This notification message will be sent when a SCROLLBAR widget has been added to the window.
WM_NOTIFICATION_SEL_CHANGED
This notification message will be sent when the selection
of a widget has changed.
WM_NOTIFICATION_VALUE_CHANGED
This notification message will be sent when a widget specific value has changed.
User defined messages
WM_USER
The WM_USER constant could be used by applications to
define private messages, usually of the form
WM_USER+X, where X is an integer value.
16.3.3 System-defined messages
These kind of messages are send by the GUI library. Do not send system defined
messages from the user application to a window or a widget.
WM_CREATE
Description
This message is sent immediately after a window has been created, giving the window the chance to initialize and create any child windows.
Data
This message contains no data.
WM_DELETE
Description
This message is sent just before a window is deleted, telling the window to free its
data structures (if any).
Data
This message contains no data.
WM_GET_ID
Description
This message is sent to a window to request it’s Id. All emWin widgets handle this
message. Application defined windows should handle this message in their callback
routine. Otherwise this message will be ignored.
Data
The callback routine of the window should store the Id in the Data.v value.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
297
WM_INIT_DIALOG
Description
This message is sent to a window immediately after the creation of the dialog and
before the dialog is displayed. Dialog procedures typically use this message to initialize widgets and carry out any other initialization tasks that affect the appearance of
the dialog box.
Data
This message contains no data.
WM_KEY
Description
Sent to the window currently containing the focus if a key has been pressed.
Data
The Data.p pointer of the message points to a WM_KEY_INFO structure.
Elements of WM_KEY_INFO
Data type
int
int
Element
Key
PressedCount
Description
The key which has been pressed.
> 0 if the key has been pressed, 0 if the key has been released.
WM_MOVE
Description
This message is sent to a window immediately after it has been moved.
If the window has any child windows, they will be moved first. Also each child window
will receive this message after it has been moved.
The message is sent regardless if the window is visible or not.
Data
This message contains no data.
WM_NOTIFY_PARENT
Description
Informs a parent window that something has occurred in one of its child window.
These messages are typically send by widgets to their parent windows to give them a
chance to react on the event.
Data
The Data.v value of the message contains the notification code of the message. For
more information about the notification codes, refer to the appropriate widget.
WM_NOTIFY_VIS_CHANGED
Description
This message is sent to a window if its visibility is changed and the configuration
switch WM_SUPPORT_NOTIFY_VIS_CHANGED is set to 1. The visibility of a window
changes if
•
obstruction changes: The window is partially or totally covered or uncovered by a
higher level window (a window which is displayed on top of the window),
•
the window is deleted or
•
the window changes from not hidden to hidden or reverse.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
298
CHAPTER
The Window Manager (WM)
Typical application
Applications which show a video in a window using a hardware decoder. The hardware
decoder can write directly into the display, bypassing emWin, if the window containing the video is completely visible. If the visibility changes, the hardware decoder
needs to be reprogrammed.
Example
The following shows a typical reaction on this message:
case WM_NOTIFY_VIS_CHANGED:
if (WM_IsCompletelyVisible(WM_GetClientWindow(pMsg->hWin))) {
...
}
The Sample folder of emWin contains the example WM_Video.c which shows how to
use the message.
Data
This message contains no data.
WM_PAINT
Description
The WM sends this message to a window if it has become invalid (partially or complete) and needs to be drawn. When a window receives a WM_PAINT message, it
should repaint itself. Before sending this message to the window, the WM makes sure
it is selected. More details about how to react on the WM_PAINT message is described
earlier in this chapter under "Using callback routines".
Data
The Data.p pointer of the message points to a GUI_RECT structure containing the
invalid rectangle of the window in screen coordinates. This information could be used
to optimize the paint function.
WM_POST_PAINT
Description
The WM sends this message to a window right after the last WM_PAINT message was
processed.
Data
This message contains no data.
WM_PRE_PAINT
Description
The WM sends this message to a window before the first WM_PAINT is sent.
Data
This message contains no data.
WM_SET_FOCUS
Description
Send to a window if it gains or looses the input focus.
Data
If the window gains the input focus, the Data.v value is set to 1. If the window
’accepts’ the input focus, it should set the Data.v value to 0 in reaction on this message.
If the window looses the input focus, the Data.v value is set to 0.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
299
WM_SET_ID
Description
Send to a window to change the Id. All emWin widgets handle this message. Application defined windows should handle this message in their callback routine. Otherwise
this message will be ignored.
Data
The Data.v value contains the new Id of the window.
WM_SIZE
Description
Sent to a window after its size has changed. Gives the window the chance to reposition its child windows (if any).
Data
This message contains no data.
WM_TIMER
Description
This message will be send to a window when a timer created by WM_CreateTimer()
has expired.
Data
The Data.v value contains the handle of the expired timer.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
300
CHAPTER
The Window Manager (WM)
16.3.4 Pointer input device (PID) messages
These kind of messages are send by the GUI library in reaction of PID input. Do not
send this messages from the user application to a window or a widget.
WM_MOUSEOVER
Description
A WM_MOUSEOVER message is send to a window if a pointer input device touches the
outline of a window. It is send only if mouse support is enabled. This message is not
sent to disabled windows.
To enable mouse support, add the following line to the file GUIConf.h:
#define GUI_SUPPORT_MOUSE 1
Data
The Data.p pointer of the message points to a GUI_PID_STATE structure.
Elements of GUI_PID_STATE
Data type
int
int
U8
Element
x
y
Pressed
Description
Horizontal position of the PID in window coordinates.
Vertical position of the PID in window coordinates.
Is always set to 0 when receiving a WM_MOUSEOVER message.
WM_MOUSEOVER_END
Description
A WM_MOUSEOVER_END message is sent to a window if the mouse pointer has been
moved out of the window. It is send only if mouse support is enabled. This message
is not sent to disabled windows.
Data
The Data.p pointer of the message points to a GUI_PID_STATE structure. For details
about this structure, refer to the message WM_MOUSEOVER.
WM_PID_STATE_CHANGED
Description
Sent to the window affected by the pointer input device when the pressed state has
changed. The affected window is the visible window at the input position. With other
words: If the user releases for example the touch screen over a window, the pressed
state changes from 1 (pressed) to 0 (unpressed). In this case a
WM_PID_STATE_CHANGED message is send to the window. This message is send before
the touch message is send. An invisible window does not receive this message.
Transparent windows are handled the same way as visible windows.
This message is not sent to disabled windows.
Data
The Data.p pointer of the message points to a WM_PID_STATE_CHANGED_INFO structure.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
301
Elements of WM_PID_STATE_CHANGED_INFO
Data type
int
int
U8
U8
Element
x
y
State
StatePrev
Description
Horizontal position of the PID in window coordinates.
Vertical position of the PID in window coordinates.
Pressed state (> 0 if PID is pressed).
Previous pressed state
WM_TOUCH
Description
A WM_TOUCH message is send to a window if
•
the PID is in pressed state and the pointer is over the visible part of the window
•
or the PID just has been released.
This message is not sent to disabled windows.
Data
The Data.p pointer of the message points to a GUI_PID_STATE structure. For details
about the structure please refer to the message WM_MOUSEOVER.
Elements of GUI_PID_STATE
Data type
int
int
U8
Element
x
y
Pressed
Description
Horizontal position of the PID in window coordinates.
Vertical position of the PID in window coordinates.
If the message is originated by a touch screen this value can be 0
(unpressed) or 1 (pressed).
If the message is originated by a mouse each bit represents a mouse
button (0 for unpressed and 1 for pressed state):
- Bit 0 represents the first button (normally the left button)
- Bit 1 represents the second button (normally the right button)
- Bit 2 represents the third button (normally the middle button)
The remaining bits can be used for further buttons.
WM_TOUCH_CHILD
Description
This message is send to the parent window if the outline of a child window has been
touched with a pointer input device in pressed or unpressed state.
This message is not sent to disabled windows.
Data
The Data.p pointer of the message points to the touch message sent to the child
window. For details about the message data, please refer to “WM_TOUCH” on
page 301.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
302
CHAPTER
The Window Manager (WM)
Example
The following example explains what happens if a pointer input device is dragged
over a dialog with a button:
1
Position
1
2
3
Description
The pointer input device (PID) is pressed at this position. This causes the WM to send
the following WM_PID_STATE_CHANGED message to the window at this position:
x = Horizontal position in desktop coordinates.
y = Vertical position in desktop coordinates.
State = 1
StatePrev = 0
The WM also sends a WM_TOUCH message with the same x and y coordinates to the
window:
x = Horizontal position in desktop coordinates.
y = Vertical position in desktop coordinates.
Pressed = 1
2
3
The PID is dragged to this position. The window below (the button) will receive no
WM_PID_STATE_CHANGED message, because the PID remains in pressed state.
The WM only sends a WM_TOUCH message to the window:
x = Horizontal position in desktop coordinates.
y = Vertical position in desktop coordinates.
Pressed = 1
The PID is released at this position. This causes the WM to send the following
WM_PID_STATE_CHANGED message to the window at this position:
x = Horizontal position in desktop coordinates.
y = Vertical position in desktop coordinates.
State = 0
StatePrev = 1
The WM also sends a WM_TOUCH message with the same x and y coordinates to the
window:
x = Horizontal position in desktop coordinates.
y = Vertical position in desktop coordinates.
Pressed = 0
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
303
16.3.5 System-defined notification codes
A message of this type is sent from a window to its parent window to notify it of a
change in the child window. This gives the parent window the chance to react on this
event. The message contains a hWinSrc element which is a handle to the widget
which caused the message. For more information on which notification messages can
be sent by the various widgets, please refer to the appropriate widget in the Chapter
"Widgets".
Note: Do not send system defined notification codes from the user application to a
window.
WM_NOTIFICATION_CHILD_DELETED
This notification message will be sent from a window to its parent before it is deleted.
WM_NOTIFICATION_CLICKED
This notification message will be sent when the window has been clicked.
WM_NOTIFICATION_LOST_FOCUS
This notification message will be sent when the window has lost the focus.
WM_NOTIFICATION_MOVED_OUT
This notification message will be sent when the pointer was moved out of the window
while it is clicked.
WM_NOTIFICATION_RELEASED
This notification message will be sent when a clicked widget has been released.
WM_NOTIFICATION_SCROLL_CHANGED
This notification message will be sent when the scroll position of an attached
SCROLLBAR widget has changed.
WM_NOTIFICATION_SCROLLBAR_ADDED
This notification message will be sent when a SCROLLBAR widget has been added to
the window.
WM_NOTIFICATION_SEL_CHANGED
This notification message will be sent when the selection of a widget has changed.
WM_NOTIFICATION_VALUE_CHANGED
This notification message will be sent when a widget specific value has changed.
16.3.6 Application-defined messages
The application program can define additional messages for its own usage. In order
to ensure that they do not use the same message Id’s as those used by emWin, userdefined messages start numbering after WM_USER. You would define your own messages as follows:
#define MY_MESSAGE_AAA WM_USER+0
#define MY_MESSAGE_BBB WM_USER+1
and so on.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
304
CHAPTER
The Window Manager (WM)
16.4 Configuration options
Type
Macro
Default
Description
Enables the WM to send a
B
WM_SUPPORT_NOTIFY_VIS_CHANGED 0
WM_NOTIFY_VIS_CHANGED message
1
Enable support for transparent windows.
If set to 0 the additional code for transparency support is not included.
to a window if its visibility is changed.
B
WM_SUPPORT_TRANSPARENCY
WM_SUPPORT_NOTIFY_VIS_CHANGED
Per default emWin does not inform windows if their visibility has changed. If enabled,
the WM sends WM_NOTIFY_VIS_CHANGED messages.
WM_SUPPORT_TRANSPARENCY
Per default emWin supports transparent windows. This means per default the additional code used to handle transparent windows is linked if the WM is used. If the
application does not use transparent windows the memory requirement of the application can be reduced if setting WM_SUPPORT_TRANSPARENCY to 0.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
305
16.5 WM API
The following table lists the available routines of the emWin window manager API.
All functions are listed in alphabetical order within their respective categories.
Detailed descriptions of the routines can be found later in the chapter.
Routine
Description
Basic functions
WM_Activate()
WM_AttachWindow()
WM_AttachWindowAt()
WM_BroadcastMessage()
WM_BringToBottom()
WM_BringToTop()
WM_ClrHasTrans()
WM_CreateWindow()
WM_CreateWindowAsChild()
WM_Deactivate()
WM_DefaultProc()
WM_DeleteWindow()
WM_DetachWindow()
WM_DisableWindow()
WM_EnableWindow()
WM_Exec()
WM_Exec1()
WM_ForEachDesc()
WM_GetActiveWindow()
WM_GetCallback()
WM_GetClientRect()
WM_GetClientRectEx()
WM_GetDesktopWindow()
WM_GetDesktopWindowEx()
WM_GetDialogItem()
WM_GetFirstChild()
WM_GetFocussedWindow()
WM_GetHasTrans()
WM_GetInvalidRect()
WM_GetNextSibling()
WM_GetOrgX()
WM_GetOrgY()
WM_GetParent()
WM_GetPrevSibling()
WM_GetStayOnTop()
WM_GetUserData()
WM_GetWindowOrgX()
WM_GetWindowOrgY()
WM_GetWindowRect()
WM_GetWindowRectEx()
WM_GetWindowSizeX()
WM_GetWindowSizeY()
Activates the window manager.
Attaches a window to a new parent window.
Attaches a window to a new parent window at the given position.
Sends a message to all existing windows.
Places a window behind its siblings.
Places a window in front of its siblings.
Clears the
has transparency flag.
Creates a window.
Creates a child window.
Deactivates the window manager.
Default routine to handle messages.
Deletes a window.
Detaches a window from its parent window.
Sets the widget state to disabled.
Sets the window state to enabled (default).
Redraws invalid windows by executing callbacks (all jobs).
Redraws one invalid window by executing one callback (one job
only).
Iterates over all descendants of a window.
Returns handle of the active window.
Returns a pointer to the callback function of a window.
Returns the size of the active window.
Returns the size of a window.
Returns the window handle of the desktop window
Returns the window handle of the specified desktop window
Returns the window handle of a dialog box item (widget).
Returns handle of a window’s first child window.
Returns the handle of the window with the input focus.
Returns current value of the
has transparency flag.
Returns the invalid rectangle of the given window.
Returns the handle of a window’s next sibling.
Returns the origin in X of the active window.
Returns the origin in Y of the active window.
Returns handle of a window’s parent window.
Returns the handle of a window’s previous sibling.
Returns current value of the
stay on top flag.
Retrieves the user data of a window
Returns the origin in X of a window.
Returns the origin in Y of a window.
Returns the screen coordinates of the active window.
Returns the screen coordinates of a window.
Returns the horizontal size (width) of a window.
Returns the vertical size (height) of a window.
WM_HasCaptured()
Checks if the given window has captured mouse- and touchscreen-input.
WM_HasFocus()
Checks if the given window has the input focus.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
306
CHAPTER
Routine
Description
Makes a window invisible.
WM_HideWindow()
WM_InvalidateArea()
WM_InvalidateRect()
WM_InvalidateWindow()
WM_IsCompletelyCovered()
WM_IsCompletelyVisible()
WM_IsEnabled()
WM_IsVisible()
WM_IsWindow()
WM_MakeModal()
WM_MoveChildTo()
WM_MoveTo()
WM_MoveWindow()
Invalidates a certain section of the display.
Invalidates a part of a window.
Invalidates a window.
Checks if a window is completely covered or not.
Checks if a window is completely visible or not.
Returns if a window is enabled or not.
Returns if a window is visible or not.
Determine whether a specified handle is a valid window handle.
Changes the window to a ’modal’ window.
Sets the position of a window in window coordinates.
Sets the position of a window in desktop coordinates.
Moves a window to another position.
Sends a WM_NOTIFY_PARENT message to the parent of the given
window.
WM_NotifyParent()
Draws or redraws a window immediately.
WM_Paint()
WM_PaintWindowAndDescs()
WM_ReleaseCapture()
WM_ResizeWindow()
WM_SelectWindow()
WM_SendMessage()
WM_SendMessageNoPara()
Draws a given window and all descendant windows immediately.
Stops capturing mouse- and touch screen-input.
Changes window size.
Sets the active window to be used for drawing operations.
Sends a message to a window.
Sends a message without parameters to a window.
Sends the given message to the parent window of the given window.
WM_SendToParent()
Sets desktop window color.
WM_SetDesktopColor()
WM_SetDesktopColorEx()
WM_SetCallback()
WM_SetCapture()
WM_SetCreateFlags()
WM_SetFocus()
WM_SetHasTrans()
WM_SetId()
WM_SetpfPollPID()
WM_SetSize()
WM_SetWindowPos()
WM_SetXSize()
WM_SetYSize()
WM_SetStayOnTop()
Sets desktop window color of the given desktop.
Sets the callback routine for a window.
Starts capturing mouse- and touch screen-input.
Sets the flags to be used as default when creating new windows
Sets input focus to a specified window.
Sets the
Sends a
has transparency flag.
WM_SET_ID message to the given window.
Sets a function to be called by the WM for polling the PID.
Sets the new size of a window.
Sets size and position of a window.
Sets the new X-size of a window.
Sets the new Y-size of a window.
Sets the
stay on top flag.
Sets or clears the WM_CF_HASTRANS and
WM_CF_CONST_OUTLINE flags.
WM_SetTransState()
Temporarily reduce the clipping area.
WM_SetUserClipRect()
WM_SetUserData()
WM_ShowWindow()
WM_Update()
Sets the user data of the given window.
Makes a window visible.
Draws the invalid part of the given window.
WM_UpdateWindowAndDescs()
WM_ValidateRect()
WM_ValidateWindow()
The Window Manager (WM)
Draws the invalid part of a given window and the invalid part of
all descendant windows.
Validates parts of a window.
Validates a window.
Memory device support (optional)
WM_DisableMemdev()
WM_EnableMemdev()
Disables usage of memory devices for redrawing.
Enables usage of memory devices for redrawing.
Timer related
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
307
Routine
Description
WM_CreateTimer()
WM_DeleteTimer()
WM_GetTimerId()
WM_RestartTimer()
Creates a timer which sends a WM_TIMER message to a window.
WM_GetClientWindow()
WM_GetId()
WM_GetInsideRect()
WM_GetInsideRectEx()
WM_GetScrollPosH()
WM_GetScrollPosV()
WM_GetScrollState()
WM_SetScrollPosH()
WM_SetScrollPosV()
WM_SetScrollState()
Returns the handle of the client window.
Deletes a timer.
Gets the Id of the given timer.
Restarts a timer.
Widget related functions
Returns the ID of a widget.
Returns the size of the active window less the border.
Returns the size of a window less the border.
Returns the scroll position of the windows horizontal scroll bar.
Returns the scroll position of the windows vertical scroll bar.
Gets the state of a scroll bar widget.
Sets the scroll position of the windows horizontal scroll bar.
Sets the scroll position of the windows vertical scroll bar.
Sets the state of a scroll bar widget.
16.5.1 Using the WM API functions
Many of the WM functions have window handles as parameters. Observe the following
rules when using handles:
•
A window handle can be 0. In this case the function returns immediately unless
the documentation of the function says otherwise.
•
If a window handle is != 0, it should be a valid handle. The WM does not check if
the given handle is valid. If an invalid handle is given to a function it fails or may
even crashes.
16.6 Basic functions
WM_Activate()
Description
Activates the window manager.
Prototype
void WM_Activate(void);
Additional information
The WM is activated by default after initialization. This function only needs to be
called if there has been a previous call of WM_Deactivate().
WM_AttachWindow()
Description
The given window will be detached from its parent window and attached to the new
parent window. The new origin in window coordinates of the new parent window will
be the same as the old origin in window coordinates of the old parent window.
Prototype
void WM_AttachWindow(WM_HWIN hWin, WM_HWIN hParent);
Parameter
hWin
hWinParent
Description
Window handle.
Window handle of the new parent.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
308
CHAPTER
The Window Manager (WM)
Additional information
If the given window handle is 0 or both handles are the same the function returns
immediately.
If only the given parent window handle is 0 the function detaches the given window
and returns; the window remains unattached.
WM_AttachWindowAt()
Description
The given window will be detached from its parent window and attached to the new
parent window. The given position will be used to set the origin of the window in window coordinates of the parent window.
Prototype
void WM_AttachWindowAt(WM_HWIN hWin, WM_HWIN hParent, int x, int y);
Parameter
hWin
hWinParent
x
y
Description
Window handle.
Window handle of the new parent.
X position of the window in window coordinates of the parent window.
Y position of the window in window coordinates of the parent window.
Additional information
If the given window handle is 0 or both handles are the same the function returns
immediately.
If only the given parent window handle is 0 the function detaches the given window,
moves it to the new position and returns; the window remains unattached.
WM_BringToBottom()
Description
Places a specified window underneath its siblings.
Prototype
void WM_BringToBottom(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Additional information
The window will be placed underneath all other sibling windows, but will remain in
front of its parent.
WM_BringToTop()
Description
Places a specified window on top of its siblings.
Prototype
void WM_BringToTop(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Additional information
The window will be placed on top of all other sibling windows and its parent.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
309
WM_BroadcastMessage()
Description
Sends the given message to all existing windows.
Prototype
int WM_BroadcastMessage(WM_MESSAGE * pMsg);
Parameter
pMsg
Description
Pointer to message to be send.
Additional information
A window should not delete itself or a parent window in reaction of a broadcasted
message.
WM_ClrHasTrans()
Description
Clears the has transparency flag (sets it to 0).
Prototype
void WM_ClrHasTrans(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Additional information
When set, this flag tells the window manager that a window contains sections which
are not redrawn and will therefore be transparent. The WM then knows that the background needs to be redrawn prior to redrawing the window in order to make sure the
transparent sections are restored correctly.
When the flag is cleared with WM_ClrHasTrans(), the WM will not automatically
redraw the background before redrawing the window.
WM_CreateWindow()
Description
Creates a window of a specified size at a specified location.
Prototype
WM_HWIN WM_CreateWindow(int
int
U8
int
x0,
width,
Style,
NumExtraBytes);
Parameter
x0
y0
width
height
Style
cb
NumExtraBytes
int
y0,
int
height,
WM_CALLBACK * cb
Description
Upper left X-position in desktop coordinates.
Upper left Y-position in desktop coordinates.
X-size of window.
Y-size of window.
Window create flags, listed below.
Pointer to callback routine, or NULL if no callback used.
Number of extra bytes to be allocated, normally 0.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
310
CHAPTER
The Window Manager (WM)
Permitted values for parameter Style (OR-combinable)
WM_CF_ANCHOR_BOTTOM
Anchors the bottom edge of the new window relative to the bottom edge of the parent window.
If the position of the parent windows bottom
edge will be adjusted due to a size change, the
position of new window will also be adjusted.
WM_CF_ANCHOR_LEFT
Anchors the left edge of the new window relative
to the left edge of the parent window (default).
If the position of the parent windows left edge
will be adjusted due to a size change, the position of new window will also be adjusted.
WM_CF_ANCHOR_RIGHT
Anchors the right edge of the new window relative to the right edge of the parent window. If
the position of the parent windows right edge
will be adjusted due to a size change, the position of new window will also be adjusted.
WM_CF_ANCHOR_TOP
Anchors the top edge of the new window relative
to the top edge of the parent window (default).
If the position of the parent windows top edge
will be adjusted due to a size change, the position of new window will also be adjusted.
WM_CF_BGND
Put window in background after creation.
WM_CF_CONST_OUTLINE
This flag is an optimization for transparent windows. It gives the window manager a chance to
optimize redraw and invalidation of a transparent window. A transparent window is normally
redrawn as part of the background, which is less
efficient than redrawing the window separately.
However, this flag may NOT be used if the window has semi transparency (alpha blending /
antialiasing with background) or the outline (the
shape) changes. Can normally be used; in case
of doubt do not use it.
WM_CF_FGND
Put window in foreground after creation
(default).
WM_CF_HASTRANS
Has transparency flag. Must be defined for
windows whose client area is not entirely filled.
WM_CF_HIDE
Hide window after creation (default).
WM_CF_LATE_CLIP
This flag can be used to tell the WM that the
clipping should be done in the drawing routines
(late clipping). The default behavior of the WM
is early clipping. That means that the clipping
rectangle will be calculated before a WM_PAINT
message will be send to a window. In dependence of other existing windows it can be necessary to send more than one WM_PAINT message
to a window. If using WM_CF_LATE_CLIP the
WM makes sure only one message will be sent
to an invalid window and the clipping will be
done by the drawing routines. The Sample
folder of emWin contains the example
WM_LateClipping.c to show the effect.
WM_CF_MEMDEV
Automatically use a memory device when
redrawing.
This will avoid flicker and also improve the output speed in most cases, as clipping is simplified. Note that the memory device package is
required (and needs to be enabled in the configuration) in order to be able to use this flag. If
memory devices are not enabled, this flag is
ignored.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
311
Permitted values for parameter Style (OR-combinable)
WM_CF_MEMDEV_ON_REDRAW
After the window is drawn the first time the WM
will automatically use a memory device for
redrawing. This flag can be used as a replacement of WM_CF_MEMDEV. It typically accelerates the initial rendering of the window, but
maintains the advantage of flicker free updates.
WM_CF_SHOW
Show window after creation.
WM_CF_STAYONTOP
Make sure window stays on top of all siblings
created without this flag.
Return value
Handle for created window.
Additional information
Several create flags can be combined by using the (OR) operator.
Negative-position coordinates may be used.
Examples
Creates a window with callback:
hWin2 = WM_CreateWindow(100, 10 ,180, 100, WM_CF_SHOW, &WinHandler, 0);
Creates a window without callback:
hWin2 = WM_CreateWindow(100, 10 ,180, 100,WM_CF_SHOW, NULL, 0);
WM_CreateWindowAsChild()
Description
Creates a window as a child window.
Prototype
WM_HWIN WM_CreateWindowAsChild(int x0, int y0,
int width, int height,
WM_HWIN hWinParent,
U8 Style,
WM_CALLBACK* cb
int NumExtraBytes);
Parameter
x0
y0
width
height
hWinParent
Style
cb
NumExtraBytes
Description
Upper left X-position in window coordinates of the parent window.
Upper left Y-position in window coordinates of the parent window.
X-size of window. If 0, X-size of client area of parent window.
Y-size of window. If 0, Y-size of client area of parent window.
Handle of parent window.
Window create flags (see
WM_CreateWindow() ).
Pointer to callback routine, or NULL if no callback used.
Number of extra bytes to be allocated, normally 0.
Return value
Handle for the child window.
Additional information
If the hWinParent parameter is set to 0, the background window is used as parent.
A child window is placed on top of its parent and any previous siblings by default, so
that if their Z-positions are not changed, the "youngest" window will always be topmost.
The Z-positions of siblings may be changed, although they will always remain on top
of their parent regardless of their order.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
312
CHAPTER
The Window Manager (WM)
WM_Deactivate()
Description
Deactivates the window manager.
Prototype
void WM_Deactivate(void);
Additional information
After calling this function, the clip area is set to the complete LCD area and the WM
will not execute window callback functions.
WM_DefaultProc()
Description
Default message handler.
Prototype
void WM_DefaultProc(WM_MESSAGE* pMsg)
Parameter
pMsg
Description
Pointer to message.
Additional information
Use this function to handle unprocessed messages as in the following example:
static WM_RESULT cbBackgroundWin(WM_MESSAGE* pMsg) {
switch (pMsg->MsgId) {
case WM_PAINT:
GUI_Clear();
default:
WM_DefaultProc(pMsg);
}
}
WM_DeleteWindow()
Description
Deletes a specified window.
Prototype
void WM_DeleteWindow(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Additional information
Before the window is deleted, it receives a WM_DELETE message. This message is typically used to delete any objects (widgets) it uses and to free memory dynamically
allocated by the window.
If the specified window has any existing child windows, these are automatically
deleted before the window itself is deleted. Child windows therefore do not need to
be separately deleted.
Before the window will be deleted it sends a WM_NOTIFICATION_CHILD_DELETED
message to its parent window.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
313
WM_DetachWindow()
Description
Detaches a window from its parent window. Detached windows will not be redrawn by
the window manager.
Prototype
void WM_DetachWindow(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
WM_DisableWindow()
Description
Set the specified window to a disabled state. The WM does not pass pointer input
device (PID) messages (touch, mouse, joystick, ...) to a disabled window.
Prototype
void WM_DisableWindow(WM_Handle hObj);
Parameter
hObj
Description
Handle of widget.
Additional information
A widget that is disabled will typically appear gray, and will not accept input from the
user. However, the actual appearance may vary (depends on widget/configuration
settings, etc.).
A disabled window will not receive the following messages: WM_TOUCH,
WM_TOUCH_CHILD, WM_PID_STATE_CHANGED and WM_MOUSEOVER.
WM_EnableWindow()
Description
Sets the specified window to enabled state. An enabled window receives pointer input
device (PID) messages (touch, mouse, joystick, ...) from the WM.
Prototype
void WM_EnableWindow(WM_Handle hObj);
Parameter
hObj
Description
Handle of window.
Additional information
This is the default setting for any widget.
WM_Exec()
Description
Redraws invalid windows by executing callback functions (all jobs).
Prototype
int WM_Exec(void);
Return value
0 if there were no jobs performed.
1 if a job was performed.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
314
CHAPTER
The Window Manager (WM)
Additional information
This function will automatically call WM_Exec1() repeatedly until it has completed all
jobs -- essentially until a 0 value is returned.
It is recommended to call the function GUI_Exec() instead.
Normally this function does not need to be called by the user application. It is called
automatically by GUI_Delay(). If you are using a multitasking system, we recommend executing this function by a separate task as seen below:
void ExecIdleTask(void) {
while(1) {
WM_Exec();
}
}
WM_Exec1()
Description
Redraws an invalid window by executing one callback function (one job only).
Prototype
int WM_Exec1(void);
Return value
0 if there were no jobs performed.
1 if a job was performed.
Additional information
This routine may be called repeatedly until 0 is returned, which means all jobs have
been completed.
It is recommended to call the function GUI_Exec1() instead.
This function is called automatically by WM_Exec().
WM_ForEachDesc()
Description
Iterates over all descendants of the given window. A descendant of a window is a
child window or a grand child window or a child of a grand child or ....
Prototype
void WM_ForEachDesc(WM_HWIN hWin, WM_tfForEach * pcb, void * pData);
Parameter
hWin
pcb
pData
Description
Window handle.
Pointer to callback function to be called by
WM_ForEachDesc .
User data to be passed to the callback function.
Additional information
This function calls the callback function given by the pointer pcb for each descendant
of the given window. The parameter pData will be passed to the user function and
can be used to point to user defined data.
Prototype of callback function
void CallbackFunction(WM_HWIN hWin, void * pData);
Example
The following example shows how the function can be used. It creates 3 windows, the
first as a child window of the desktop, the second as a child window of the first window and the third as a child window of the second window. After creating the window
it uses WM_ForEachDesc() to move each window within its parent window:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
315
#include "GUI.h"
#include "WM.h"
/*********************************************************************
*
*
_cbWin
*/
static void _cbWin(WM_MESSAGE * pMsg) {
GUI_COLOR Color;
switch (pMsg->MsgId) {
case WM_PAINT:
WM_GetUserData(pMsg->hWin, &Color, 4);
GUI_SetBkColor(Color);
GUI_Clear();
break;
default:
WM_DefaultProc(pMsg);
}
}
/*********************************************************************
*
*
_cbDoSomething
*/
static void _cbDoSomething(WM_HWIN hWin, void * p) {
int Value = *(int *)p;
WM_MoveWindow(hWin, Value, Value);
}
/*********************************************************************
*
*
MainTask
*/
void MainTask(void) {
WM_HWIN hWin_1, hWin_2, hWin_3;
int Value = 10;
GUI_COLOR aColor[] = {GUI_RED, GUI_GREEN, GUI_BLUE};
GUI_Init();
WM_SetDesktopColor(GUI_BLACK);
hWin_1 = WM_CreateWindow( 10, 10, 100, 100, WM_CF_SHOW, _cbWin, 4);
hWin_2 = WM_CreateWindowAsChild(10, 10, 80, 80, hWin_1, WM_CF_SHOW, _cbWin, 4);
hWin_3 = WM_CreateWindowAsChild(10, 10, 60, 60, hWin_2, WM_CF_SHOW, _cbWin, 4);
WM_SetUserData(hWin_1, &aColor[0], 4);
WM_SetUserData(hWin_2, &aColor[1], 4);
WM_SetUserData(hWin_3, &aColor[2], 4);
while(1) {
WM_ForEachDesc(WM_HBKWIN, _cbDoSomething, (void *)&Value);
Value *= -1;
GUI_Delay(500);
}
}
WM_GetCallback()
Description
Returns a pointer to the callback function of the given window
Prototype
WM_CALLBACK * WM_GetCallback(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Return value
Pointer of type WM_CALLBACK which points to the callback function of the given window. If the window has no callback function, NULL is returned.
WM_GetActiveWindow()
Description
Returns the handle of the active window used for drawing operations.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
316
CHAPTER
The Window Manager (WM)
Prototype
WM_HWIN WM_GetActiveWindow(void);
Return value
The handle of the active window.
WM_GetClientRect()
Description
Returns the coordinates of the client area in the active window in window coordinates. That means x0 and y0 of the GUI_RECT structure will be 0, x1 and y1 corresponds to the size - 1.
Prototype
void WM_GetClientRect(GUI_RECT* pRect);
Parameter
pRect
Description
Pointer to a GUI_RECT structure.
WM_GetClientRectEx()
Description
Returns the coordinates of the client area of a window in window coordinates. That
means x0 and y0 of the GUI_RECT structure will be 0, x1 and y1 corresponds to the
size - 1.
Prototype
void WM_GetClientRectEx(WM_HWIN hWin, GUI_RECT* pRect);
Parameter
hWin
pRect
Description
Window handle.
Pointer to a GUI_RECT structure.
WM_GetDesktopWindow()
Description
Returns the handle of the desktop window.
Prototype
WM_HWIN WM_GetDesktopWindow(void);
Return value
The handle of the desktop window.
Additional information
The desktop window is always the bottommost window and any further created windows are its descendants.
WM_GetDesktopWindowEx()
Description
Returns the handle of the specified desktop window when working in a multi layer
environment.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
317
Prototype
WM_HWIN WM_GetDesktopWindowEx(unsigned int LayerIndex);
Parameter
LayerIndex
Description
Index of layer
Return value
The handle of the specified desktop window.
WM_GetDialogItem()
Description
Returns the window handle of a dialog box item (widget).
Prototype
WM_HWIN WM_GetDialogItem(WM_HWIN hDialog, int Id);
Parameter
hDialog
Id
Description
Handle of dialog box.
Window Id of the widget.
Return value
The window handle of the widget.
Additional information
This function is always used when creating dialog boxes, since the window Id of a
widget used in a dialog must be converted to its handle before it can be used.
WM_GetFirstChild()
Description
Returns the handle of a specified window’s first child window.
Prototype
void WM_GetFirstChild(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Return value
Handle of the window’s first child window; 0 if no child window exists.
Additional information
A window’s first child window is the first child created to that particular parent. If the
Z-positions of the windows have not been changed, it will be the window directly on
top of the specified parent.
WM_GetFocussedWindow()
Description
Returns the handle of the window with the input focus.
Prototype
WM_HWIN WM_GetFocussedWindow(void);
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
318
CHAPTER
The Window Manager (WM)
Return value
Handle of the window with the input focus or 0 if no window has the input focus.
WM_GetHasTrans()
Description
Returns the current value of the has transparency flag.
Prototype
U8 WM_GetHasTrans(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Return value
0: no transparency
1: window has transparency
Additional information
When set, this flag tells the window manager that a window contains sections which
are not redrawn and will therefore be transparent. The WM then knows that the background needs to be redrawn prior to redrawing the window in order to make sure the
transparent sections are restored correctly.
WM_GetInvalidRect()
Description
Returns the invalid rectangle of a window in desktop coordinates.
Prototype
int WM_GetInvalidRect(WM_HWIN hWin, GUI_RECT * pRect);
Parameter
hWin
pRect
Description
Window handle.
Pointer to a GUI_RECT-structure for storing the invalid rectangle.
Return value
0 if nothing is invalid, otherwise 1.
WM_GetNextSibling()
Description
Returns the handle of a specified window’s next sibling.
Prototype
void WM_GetNextSibling(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Return value
Handle of the window’s next sibling; 0 if none exists.
Additional information
A window’s next sibling is the next child window that was created relative to the
same parent. If the Z-positions of the windows have not been changed, it will be the
window directly on top of the one specified.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
319
WM_GetOrgX(), WM_GetOrgY()
Description
Returns the X- or Y-position (respectively) of the origin of the active window in desktop coordinates.
Prototypes
int WM_GetOrgX(void);
int WM_GetOrgY(void);
Return value
X- or Y-position of the origin of the active window in desktop coordinates.
WM_GetParent()
Description
Returns the handle of a specified window’s parent window.
Prototype
void WM_GetParent(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Return value
Handle of the window’s parent window; 0 if none exists.
Additional information
The only case in which no parent window exists is if the handle of the desktop window is used as parameter.
WM_GetPrevSibling()
Description
Returns the handle of a specified window’s previous sibling.
Prototype
void WM_GetPrevSibling(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Return value
Handle of the window’s previous sibling; 0 if none exists.
Additional information
A window’s previous sibling is the previous child window that was created relative to
the same parent. If the Z-positions of the windows have not been changed, it will be
the window directly below of the one specified.
WM_GetStayOnTop()
Description
Returns the current value of the stay on top flag.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
320
CHAPTER
The Window Manager (WM)
Prototype
int WM_GetStayOnTop(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Return value
0: stay on top flag not set
1: stay on top flag set
WM_GetUserData()
Description
Retrieves the data set with WM_SetUserData().
Prototype
int WM_GetUserData(WM_HWIN hWin, void* pDest, int SizeoOfBuffer);
Parameter
hWin
pDest
SizeOfBuffer
Description
Window handle.
Pointer to buffer.
SIze of buffer.
Return value
Number of bytes retrieved.
Additional information
The maximum number of bytes returned by this function is the number of ExtraBytes specified when creating the window.
WM_GetWindowOrgX(), WM_GetWindowOrgY()
Description
Returns the X- or Y-position (respectively) of the origin of the specified window in
desktop coordinates.
Prototypes
int WM_GetWindowOrgX(WM_HWIN hWin);
int WM_GetWindowOrgY(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Return value
X- or Y-position of the client area in pixels.
WM_GetWindowRect()
Description
Returns the coordinates of the active window in desktop coordinates.
Prototype
void WM_GetWindowRect(GUI_RECT* pRect);
Parameter
pRect
Description
Pointer to a GUI_RECT structure.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
321
WM_GetWindowRectEx()
Description
Returns the coordinates of a window in desktop coordinates.
Prototype
void WM_GetWindowRectEx(WM_HWIN hWin, GUI_RECT* pRect);
Parameter
hWin
pRect
Description
Window handle.
Pointer to a GUI_RECT structure.
Additional information
If the given window handle is 0 or the given pointer to the GUI_RECT structure is
NULL the function returns immediately.
WM_GetWindowSizeX(), WM_GetWindowSizeY()
Description
Return the X- or Y-size (respectively) of a specified window.
Prototypes
int WM_GetWindowSizeX(WM_HWIN hWin);
int WM_GetWindowSizeY(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Return value
X- or Y-size of the window in pixels.
Defined as x1-x0+1 in horizontal direction, y1-y0+1 in vertical direction, where x0,
x1, y0, y1 are the leftmost/rightmost/topmost/bottommost positions of the window.
If the given window handle is 0 the function returns the size of the desktop window.
WM_HasCaptured()
Description
Returns 1 if the given window has captured mouse- and touchscreen-input, 0 if not.
Prototype
int WM_HasCaptured(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Return value
1 if the given window has captured mouse- and touchscreen-input, 0 if not.
Additional information
If the given window handle is invalid or 0 the function returns a wrong result.
WM_HasFocus()
Description
Checks if the given window has the input focus.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
322
CHAPTER
The Window Manager (WM)
Prototype
int WM_HasFocus(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Return value
1 if the given window has the input focus, otherwise 0.
Additional information
If the given window handle is invalid or 0 the function returns a wrong result.
WM_HideWindow()
Description
Makes a specified window invisible.
Prototype
void WM_HideWindow(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Additional information
The window will not immediately appear "invisible" after calling this function. The
invalid areas of other windows (areas which appear to lie "behind" the window which
should be hidden) will be redrawn when executing WM_Exec(). If you need to hide
(draw over) a window immediately, you should call WM_Paint() to redraw the other
windows.
WM_InvalidateArea()
Description
Invalidates a specified, rectangular area of the display.
Prototype
void WM_InvalidateArea(GUI_RECT* pRect);
Parameter
pRect
Description
Pointer to a GUI_RECT structure with desktop coordinates.
Additional information
Calling this function will tell the WM that the specified area is not updated.
This function can be used to invalidate any windows or parts of windows that overlap
or intersect the area. The coordinates of the GUI_RECT structure have to be in desktop coordinates.
WM_InvalidateRect()
Description
Invalidates a specfied, rectangular area of a window.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
323
Prototype
void WM_InvalidateRect(WM_HWIN hWin, GUI_RECT* pRect);
Parameter
hWin
pRect
Description
Window handle.
Pointer to a GUI_RECT structure with window coordinates of the parent window.
Additional information
Calling this function will tell the WM that the specified area is not updated.
The next time WM_Paint() is called to redraw the window, the area will be redrawn as
well. The coordinates of the GUI_RECT structure have to be in window coordinates.
WM_InvalidateWindow()
Description
Invalidates a specified window.
Prototype
void WM_InvalidateWindow(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Additional information
Calling this function tells the WM that the specified window is not updated.
WM_IsCompletelyCovered()
Description
Checks if the given window is completely covered or not.
Prototype
char WM_IsCompletelyCovered(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Return value
1 if the given window is completely covered, otherwise 0.
Additional information
If the given window handle is invalid or 0 the function returns a wrong result.
WM_IsCompletelyVisible()
Description
Checks if the given window is completely visible or not.
Prototype
char WM_IsCompletelyVisible(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
324
CHAPTER
The Window Manager (WM)
Return value
1 if the given window is completely visible, otherwise 0.
Additional information
If the given window handle is invalid or 0 the function returns a wrong result.
WM_IsEnabled()
Description
This function returns if a window is enabled or not.
Prototype
int WM_IsEnabled(WM_HWIN hObj);
Parameter
hObj
Description
Handle of window.
Return value
1 if the window is enabled, 0 if not.
Additional information
A widget that is disabled will typically appear gray, and will not accept input from the
user. However, the actual appearance may vary (depends on widget/configuration
settings, etc.)
WM_IsVisible()
Description
Determines whether or not a specified window is visible.
Prototype
int WM_IsVisible(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Return value
0: Window is not visible
1: Window is visible
WM_IsWindow()
Description
Determines whether or not a specified handle is a valid window handle.
Prototype
void WM_IsWindow(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Return value
0: handle is not a valid window handle
1: handle is a valid window handle
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
325
Additional information
This function should be used only if absolutely necessary. The more windows exist
the more time will be used to evaluate, if the given handle is a window.
WM_MakeModal()
Description
This function makes the window work in ’modal’ mode. This means pointer device
input will only be send to the ’modal’ window or a child window of it if the input position is within the rectangle of the modal window.
Prototype
void WM_MakeModal(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
WM_MoveChildTo()
Description
Moves a specified window to a certain position.
Prototype
void WM_MoveChildTo(WM_HWIN hWin, int x, int y);
Parameter
hWin
x
y
Description
Window handle.
New X-position in window coordinates of the parent window.
New Y-position in window coordinates of the parent window.
WM_MoveTo()
Description
Moves a specified window to a certain position.
Prototype
void WM_MoveTo(WM_HWIN hWin, int x, int y);
Parameter
hWin
x
y
Description
Window handle.
New X-position in desktop coordinates.
New Y-position in desktop coordinates.
WM_MoveWindow()
Description
Moves a specified window by a certain distance.
Prototype
void WM_MoveWindow(WM_HWIN hWin, int dx, int dy);
Parameter
hWin
dx
dy
Description
Window handle.
Horizontal distance to move.
Vertical distance to move.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
326
CHAPTER
The Window Manager (WM)
WM_NotifyParent()
Description
Sends a WM_NOTIFY_PARENT message to the given window.
Prototype
void WM_NotifyParent(WM_HWIN hWin, int Notification);
Parameter
hWin
Notification
Description
Window handle.
Value to send to the parent window.
Additional information
The Notification-parameter will be send in the Data.v element of the message. The
macro WM_NOTIFOCATION_USER can be used for defining application defined messages:
#define NOTIFICATION_1 (WM_NOTIFOCATION_USER + 0)
#define NOTIFICATION_2 (WM_NOTIFOCATION_USER + 1)
WM_Paint()
Description
Draws or redraws a specified window immediately.
Prototype
void WM_Paint(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Additional information
The window is redrawn reflecting all updates made since the last time it was drawn.
WM_PaintWindowAndDescs()
Description
Paints the given window and all its descendants.
Prototype
void WM_PaintWindowAndDescs(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Additional information
The function draws the complete window regions by invalidating them before drawing.
WM_ReleaseCapture()
Description
Releases capturing of mouse- and touchscreen-input.
Prototype
void WM_ReleaseCapture(void);
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
327
Additional information
Use WM_SetCapture() to send all mouse- and touchscreen-input to a specific window.
WM_ResizeWindow()
Description
Changes the size of a specified window by adding (or subtracting) the given differences.
Prototype
void WM_ResizeWindow(WM_HWIN hWin, int XSize, int YSize);
Parameter
hWin
dx
dy
Description
Window handle.
Difference in X.
Difference in Y.
WM_SelectWindow()
Description
Sets the active window to be used for drawing operations.
Prototype
WM_HWIN WM_SelectWindow(WM_HWIN
hWin);
Parameter
hWin
Description
Window handle.
Return value
The selected window.
Additional information
This function should not be called within a paint function called by the window manager. If the window manager sends a WM_PAINT message the target window already
has been selected.
When working with a multi layer configuration the function switches also to the layer
of the top level parent window of the given window.
If the given window handle is 0 the function selects the first created window, normally the first desktop window.
Example
Sets a window with handle hWin2 to the active window, sets the background color,
and then clears the window:
WM_SelectWindow(hWin2);
GUI_SetBkColor(0xFF00);
GUI_Clear();
WM_SendMessage()
Description
Sends a message to a specified window.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
328
CHAPTER
The Window Manager (WM)
Prototype
void WM_SendMessage(WM_HWIN hWin, WM_MESSAGE* pMsg)
Parameter
hWin
pMsg
Description
Window handle.
Pointer to message.
WM_SendMessageNoPara()
Description
Sends a message without parameters to a specified window.
Prototype
void WM_SendMessageNoPara(WM_HWIN hWin, int MsgId)
Parameter
hWin
MsgId
Description
Window handle.
Id of message to be send.
Additional information
If only a message Id should be send to a window this should be done with this function, because it does not need a pointer to a WM_MESSAGE structure. Note that the
receiving window gets no further information except the message Id.
WM_SendToParent()
Description
Sends the given message to the parent window of the given window.
Prototype
void WM_SendToParent(WM_HWIN hWin, WM_MESSAGE* pMsg);
Parameter
hWin
pMsg
Description
Window handle.
Pointer to WM_MESSAGE-structure.
WM_SetDesktopColor()
Description
Sets the color for the desktop window.
Prototype
GUI_COLOR WM_SetDesktopColor(GUI_COLOR Color);
Parameter
Color
Description
Color for desktop window, 24-bit RGB value.
Return value
The previously selected desktop window color.
Additional information
The default setting for the desktop window is not to repaint itself. If this function is
not called, the desktop window will not be redrawn at all; therefore other windows
will remain visible even after they are deleted.
Once a color is specified with this function, the desktop window will repaint itself. In
order to restore the default, call this function and specify GUI_INVALID_COLOR.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
329
WM_SetDesktopColorEx()
Description
Sets the color for the desktop window in a multi layer environment.
Prototype
GUI_COLOR WM_SetDesktopColorEx(GUI_COLOR Color, unsigned int LayerIndex);
Parameter
Color
LayerIndex
Description
Color for desktop window, 24-bit RGB value.
Index of the layer.
Return value
The previously selected desktop window color.
Additional information
(see WM_SetDesktopColor).
WM_SetCallback()
Description
Sets a callback routine to be executed by the window manager.
Prototype
WM_CALLBACK* WM_SetCallback (WM_HWIN hWin, WM_CALLBACK* cb)
Parameter
hWin
cb
Description
Window handle.
Pointer to callback routine.
Return value
Pointer to the previous callback routine.
Additional information
The given window will be invalidated. This makes sure the window will be redrawn.
WM_SetCapture()
Description
Routes all mouse- and touchscreen-messages to the given window.
Prototype
void WM_SetCapture(WM_HWIN hObj, int AutoRelease);
Parameter
hWin
AutoRelease
Description
Window handle.
1 if capturing should end when the user releases the touch.
WM_SetCreateFlags()
Description
Sets the flags to be used as default when creating a new window.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
330
CHAPTER
The Window Manager (WM)
Prototype
U8 WM_SetCreateFlags (U8 Flags)
Parameter
Flags
Description
Window create flags (see
WM_CreateWindow() ).
Return value
Former value of this parameter.
Additional information
The flags specified here are binary ORed with the flags specified in the
WM_CreateWindow() and WM_CreateWindowAsChild() routines.
The flag WM_CF_MEMDEV is frequently used to enable memory devices on all windows.
Please note that it is permitted to set create flags before GUI_Init() is called. This
causes the background window to be also affected by the create flags.
Example
WM_SetCreateFlags(WM_CF_MEMDEV);
/* Auto. use memory devices on all windows */
WM_SetFocus()
Description
Sets the input focus to a specified window.
Prototype
void WM_SetFocus(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Return value
0 if window accepted focus; value other than 0 if it could not.
Additional information
The window receives a WM_SETFOCUS message which gives it the input focus. If for
some reason the window could not accept the focus, nothing happens.
WM_SetHasTrans()
Description
Sets the has transparency flag (sets it to 1).
Prototype
void WM_SetHasTrans(WM_HWIN hWin);
Parameter
HWin
Description
Window handle.
Additional information
When set, this flag tells the window manager that a window contains sections which
are not redrawn and will therefore be transparent. The WM then knows that the background needs to be redrawn prior to redrawing the window in order to make sure the
transparent sections are restored correctly.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
331
WM_SetId()
Description
This function sends a WM_SET_ID message to the given window.
Prototype
void WM_SetId(WM_HWIN hObj, int Id);
Parameter
hObj
Id
Description
Window handle.
Id to be send to the window.
Additional information
This function can be used to change the Id of a widget. It works with every widget.
When using this function with a application defined window, the callback function of
the window should handle the message. Otherwise it will be ignored.
WM_SetpfPollPID()
Description
Sets a function which will be called by the window manager in order to poll the
pointer input device (touch-screen or mouse).
Prototype
WM_tfPollPID * WM_SetpfPollPID(WM_tfPollPID * pf);
Parameter
pf
Description
Pointer to a function of type
WM_tfPollPID.
Additional information
The function type is defined as follows:
typedef void WM_tfPollPID(void);
Example
Example of a touch-screen handled as a device:
void ReadTouch(void) {
// ...read touchscreen
}
WM_SetpfPollPID(ReadTouch);
WM_SetSize()
Description
Sets the new size of a window.
Prototype
void WM_SetSize(WM_HWIN hWin, int XSize, int YSize);
Parameter
hWin
XSize
YSize
Description
Window handle.
New size in X.
New size in Y.
WM_SetWindowPos()
Description
Sets the size and the position of a window.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
332
CHAPTER
The Window Manager (WM)
Prototype
void WM_SetWindowPos(WM_HWIN hWin,
int xPos, int yPos,
int xSize, int ySize);
Parameter
hWin
xPos
yPos
xSize
ySize
Description
Window handle.
New position in X in desktop coordinates.
New position in Y in desktop coordinates.
New size in X.
New size in Y.
WM_SetXSize()
Description
Sets the new X-size of a window.
Prototype
void WM_SetXSize(WM_HWIN hWin, int XSize);
Parameter
hWin
XSize
Description
Window handle.
New size in X.
WM_SetYSize()
Description
Sets the new Y-size of a window.
Prototype
void WM_SetYSize(WM_HWIN hWin, int YSize);
Parameter
hWin
YSize
Description
Window handle.
New size in Y.
WM_SetStayOnTop()
Description
Sets the stay on top flag.
Prototype
void WM_SetStayOnTop(WM_HWIN hWin, int OnOff);
Parameter
hWin
OnOff
Description
Window handle.
(see table below)
Permitted values for parameter OnOff
0
1
User's & reference manual for emWin V5.10
Stay on top flag would be cleared.
Stay on top flag would be set.
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
333
WM_SetTransState()
Description
This function sets or clears the flags WM_CF_HASTRANS and WM_CF_CONST_OUTLINE of
the given window.
Prototype
void WM_SetTransState(WM_HWIN hWin, unsigned State);
Parameter
hWin
State
Description
Window handle.
Combination of the flags
WM_CF_HASTRANS and WM_CF_CONST_OUTLINE.
Additional information
For details about the flag WM_CF_CONST_OUTLINE, refer to “WM_CreateWindow()” on
page 309.
WM_SetUserClipRect()
Description
Temporarily reduces the clip area of the current window to a specified rectangle.
Prototype
const GUI_RECT* WM_SetUserClipRect(const GUI_RECT* pRect);
Parameter
pRect
Description
Pointer to a GUI_RECT structure defining the clipping region in desktop coordinates.
Return value
Pointer to the previous clip rectangle.
Additional information
A NULL pointer can be passed in order to restore the default settings. The clip rectangle will automatically be reset by the WM when callbacks are used.
The specified rectangle must be relative to the current window. You cannot enlarge
the clip rectangle beyond the current window rectangle.
Your application must ensure that the specified rectangle retains its value until it is
no longer needed; that is, until a different clip rectangle is specified or until a NULL
pointer is passed. This means that the rectangle structure passed as parameter
should not be an auto variable (usually located on the stack) if the clip rectangle
remains active until after the return. In this case, a static variable should be used.
Example
This example is taken from the drawing routine of a progress indicator. The progress
indicator must write text on top of the progress bar, where the text color has to be
different on the left and right parts of the bar. This means that half of a digit could be
in one color, while the other half could be in a different color. The best way to do this
is to temporarily reduce the clip area when drawing each part of the bar as shown
below:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
334
CHAPTER
The Window Manager (WM)
/* Draw left part of the bar */
r.x0=0; r.x1=x1-1; r.y0=0; r.y1 = GUI_YMAX;
WM_SetUserClipRect(&r);
GUI_SetBkColor(pThis->ColorBar[0]);
GUI_SetColor(pThis->ColorText[0]);
GUI_Clear();
GUI_GotoXY(xText,yText); GUI_DispDecMin(pThis->v); GUI_DispChar('%');
/* Draw right part of the bar */
r.x0=r.x1; r.x1=GUI_XMAX;
WM_SetUserClipRect(&r);
GUI_SetBkColor(pThis->ColorBar[1]);
GUI_SetColor(pThis->ColorText[1]);
GUI_Clear();
GUI_GotoXY(xText,yText); GUI_DispDecMin(pThis->v); GUI_DispChar('%');
Screen shot of progress bar
WM_SetUserData()
Description
Sets the extra data of a window. Memory for extra data is reserved with the parameter NumExtraBytes when creating a window.
Prototype
int WM_SetUserData(WM_HWIN hWin, void * pSrc, int NumBytes);
Parameter
hWin
pSrc
NumBytes
Description
Window handle.
Pointer to buffer.
Size of buffer.
Return value
Number of bytes written.
Additional information
The maximum number of bytes used to store user data is the number of ExtraBytes
specified when creating a window.
WM_ShowWindow()
Description
Makes a specified window visible.
Prototype
void WM_ShowWindow(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Additional information
The window will not immediately be visible after calling this function. It will be
redrawn when executing WM_Exec(). If you need to show (draw) the window immediately, you should call WM_Paint().
WM_Update()
Description
Draws the invalid part of the specified window immediately.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
335
Prototype
void WM_Update(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Additional information
After updating a window its complete region is marked as valid.
WM_UpdateWindowAndDescs()
Description
Paints the invalid part of the given window and the invalid part of all its descendants.
Prototype
void WM_UpdateWindowAndDescs(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Additional information
The function only draws the invalid window regions.
WM_ValidateRect()
Description
Validates a specfied, rectangular area of a window.
Prototype
void WM_ValidateRect
(WM_HWIN hWin, GUI_RECT* pRect);
Parameter
hWin
pRect
Description
Window handle.
Pointer to a GUI_RECT structure with window coordinates of the parent window.
Additional information
Calling this function will tell the WM that the specified area is updated.
Normally this function is called internally and does not need to be called by the user
application. The coordinates of the GUI_RECT structure have to be in desktop coordinates.
WM_ValidateWindow()
Description
Validates a specified window.
Prototype
void WM_ValidateWindow
(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Additional information
Calling this function will tell the WM that the specified window is updated.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
336
CHAPTER
The Window Manager (WM)
Normally this function is called internally and does not need to be called by the user
application.
16.7 Memory device support (optional)
When a memory device is used for redrawing a window, all drawing operations are
automatically routed to a memory device context and are executed in memory. Only
after all drawing operations have been carried out is the window redrawn on the LCD,
reflecting all updates at once. The advantage of using memory devices is that any
flickering effects (which normally occur when the screen is continuously updated as
drawing operations are executed) are eliminated.
For more information on how memory devices operate, see the chapter “Memory
Devices” on page 247.
WM_DisableMemdev()
Description
Disables the use of memory devices for redrawing a window.
Prototype
void WM_DisableMemdev (WM_HWIN hWin)
Parameter
hWin
Description
Window handle.
WM_EnableMemdev()
Description
Enables the use of memory devices for redrawing a window.
Prototype
void WM_EnableMemdev (WM_HWIN hWin)
Parameter
hWin
Description
Window handle.
16.8 Timer related functions
WM_CreateTimer()
Description
Creates a timer which sends a message to the given window after the given time
period has expired. The timer is associated to the given window.
Prototype
WM_HTIMER WM_CreateTimer(WM_HWIN hWin, int UserId, int Period, int Mode);
Parameter
hWin
UserId
Period
Mode
Description
Handle of window to be informed.
User defined Id. Can be set to 0 if not using multiple timers for the same window.
Time period after which the given window should receive a message.
(reserved for future use, should be 0)
Return value
Handle of the timer.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
337
Additional information
The function creates a ’one shot timer’ which sends a WM_TIMER message to the given
window. After the timer period has expired the timer object remains valid and can be
restarted using the function WM_RestartTimer() or deleted with WM_DeleteTimer().
Please note that the window manager automatically deletes each associated timer of
a window when deleting the window.
Example
static void _cbWin(WM_MESSAGE * pMsg) {
switch (pMsg->MsgId) {
case WM_TIMER:
/*
... do something ...
*/
WM_RestartTimer(pMsg->Data.v, 1000);
break;
default:
WM_DefaultProc(pMsg);
}
}
static void _DemoTimer(void) {
WM_HWIN hWin;
WM_HTIMER hTimer;
hWin
= WM_CreateWindow(10, 10, 100, 100, WM_CF_SHOW, _cbWin, 0);
hTimer = WM_CreateTimer(hWin, 0, 1000, 0);
while (1) {
GUI_Exec();
}
}
WM_DeleteTimer()
Description
Deletes the given timer.
Prototype
void WM_DeleteTimer(WM_HTIMER hTimer);
Parameter
hTimer
Description
Handle of the timer to be deleted.
Additional information
After a timer has expired the timer object remains valid and will not be deleted automatically. If it is not used anymore it should be deleted using this function.
Please note that the window manager automatically deletes the timer when deleting
the window.
WM_GetTimerId()
Description
Gets the Id of the given timer.
Prototype
int WM_GetTimerId(WM_HTIMER hTimer);
Parameter
hTimer
Description
Handle of the timer to be deleted.
Return value
The Id of the timer which was previously set within the function WM_CreateTimer().
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
338
CHAPTER
The Window Manager (WM)
WM_RestartTimer()
Description
Restarts the given timer with the given period.
Prototype
void WM_RestartTimer(WM_HTIMER hTimer, int Period);
Parameter
hTimer
Period
Description
Handle of the timer to be restarted.
New period to be used.
Additional information
After the period has expired a WM_TIMER message will be send to the window
assigned to the timer. For details, refer to “WM_CreateTimer()” on page 336.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
339
16.9 Widget related functions
WM_GetClientWindow()
Description
Returns the handle of the client window. The function sends a message to the active
window to retrieve the handle of the client window. If the window does not handle
the message the handle of the current window will be returned.
Prototype
WM_HWIN WM_GetClientWindow(WM_HWIN hObj);
Parameter
hWin
Description
Handle of widget.
Return value
Handle of the client window.
Additional information
Use this function to retrieve the client window handle of a FRAMEWIN widget.
WM_GetId()
Description
Returns the ID of a specified widget window.
Prototype
int WM_GetId(WM_HWIN hObj);
Parameter
hObj
Description
Handle of widget.
Return value
The ID of the widget specified at creation.
0 will be returned if the specified window is not a widget.
WM_GetInsideRect()
Description
Returns the coordinates of the client area of the active widget less the border size.
The function sends a message to the active window to retrieve the inside rectangle.
If the widget does not handle the message (that means the widget has no border)
WM_GetClientRect will be used to calculate the rectangle. The result is given in window coordinates. That means x0 and y0 of the GUI_RECT structure corresponds to
the border size in x and y, x1 and y1 corresponds to the size of the window less the
border size - 1.
Prototype
void WM_GetInsideRect(GUI_RECT* pRect);
Parameter
pRect
Description
Pointer to a GUI_RECT structure.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
340
CHAPTER
The Window Manager (WM)
WM_GetInsideRectEx()
Description
Returns the coordinates of a window less the border size. For details, refer to
“WM_GetInsideRect()” on page 339.
Prototype
void WM_GetInsideRectEx(WM_HWIN hObj, GUI_RECT* pRect);
Parameter
hObj
pRect
Description
Handle of widget.
Pointer to a GUI_RECT structure.
WM_GetScrollPosH()
Description
If a horizontal scroll bar is attached to the window, the function returns the scroll
position of it.
Prototype
int WM_GetScrollPosH(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Return value
Scroll position of the horizontal scroll bar attached to this window.
Additional information
If no horizontal scroll bar is attached to the window, the function returns 0.
For more information, refer to “SCROLLBAR: Scroll bar widget” on page 617.
WM_GetScrollPosV()
Description
If a vertical scroll bar is attached to the window, the function returns the scroll position of it.
Prototype
int WM_GetScrollPosV(WM_HWIN hWin);
Parameter
hWin
Description
Window handle.
Return value
Scroll position of the vertical scroll bar attached to this window.
Additional information
If no vertical scroll bar is attached to the window, the function returns 0.
For more information, refer to “SCROLLBAR: Scroll bar widget” on page 617.
WM_GetScrollState()
Description
Fills a data structure with information on the current state of a specified scroll bar
widget window.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
341
Prototype
void WM_GetScrollState(WM_HWIN hObj, WM_SCROLL_STATE* pScrollState);
Parameter
Description
Handle of scroll bar widget.
hObj
pScrollState Pointer to a data structure of type WM_SCROLL_STATE.
Additional information
This function does not return since the state of a scroll bar is defined by more than
one value.
It has no effect on other types of widgets or windows.
For more information, refer to “SCROLLBAR: Scroll bar widget” on page 617.
Elements of WM_SCROLL_STATE
Data type Element
int
int
int
Description
NumItems Number of items.
Current value.
v
PageSize Number of items visible on one page.
WM_SetScrollPosH()
Description
If a horizontal scroll bar is attached to the window, the function sets the scroll position of it.
Prototype
void WM_SetScrollPosH(WM_HWIN hWin, unsigned ScrollPos);
Parameter
hWin
ScrollPos
Description
Window handle.
New scroll position of the scroll bar.
Additional information
If no horizontal scroll bar is attached to the window, the function returns.
For more information, refer to “SCROLLBAR: Scroll bar widget” on page 617.
WM_SetScrollPosV()
Description
If a vertical scroll bar is attached to the window, the function sets the scroll position
of it.
Prototype
void WM_SetScrollPosV(WM_HWIN hWin, unsigned ScrollPos);
Parameter
hWin
ScrollPos
Description
Window handle.
New scroll position of the scroll bar.
Additional information
If no vertical scroll bar is attached to the window, the function returns.
For more information, refer to “SCROLLBAR: Scroll bar widget” on page 617.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
342
CHAPTER
The Window Manager (WM)
WM_SetScrollState()
Description
Sets the state of a specified scroll bar widget.
Prototype
void WM_SetScrollState(WM_HWIN hObj, const WM_SCROLL_STATE* pState);
Parameter
hObj
Description
Handle of scroll bar widget.
16.10 Example
The following example illustrates the difference between using a callback routine for
redrawing the background and not having one. It also shows how to set your own
callback function. The example is available as WM_Redraw.c in the examples shipped
with emWin:
/*********************************************************************
*
SEGGER MICROCONTROLLER SYSTEME GmbH
*
*
Solutions for real time microcontroller applications
*
*
*
*
emWin example code
*
*
*
**********************************************************************
---------------------------------------------------------------------File
: WM_Redraw.c
Purpose
: Demonstrates the redrawing mechanism of the window manager
---------------------------------------------------------------------*/
#include "GUI.H"
/*******************************************************************
*
*
Callback routine for background window
*
********************************************************************
*/
static void cbBackgroundWin(WM_MESSAGE* pMsg) {
switch (pMsg->MsgId) {
case WM_PAINT:
GUI_Clear();
default:
WM_DefaultProc(pMsg);
}
}
/*******************************************************************
*
*
Callback routine for foreground window
*
********************************************************************
*/
static void cbForegroundWin(WM_MESSAGE* pMsg) {
switch (pMsg->MsgId) {
case WM_PAINT:
GUI_SetBkColor(GUI_GREEN);
GUI_Clear();
GUI_DispString("Foreground window");
break;
default:
WM_DefaultProc(pMsg);
}
}
/*******************************************************************
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
343
*
*
Demonstrates the redraw mechanism of emWin
*
********************************************************************
*/
static void DemoRedraw(void) {
GUI_HWIN hWnd;
while(1) {
/* Create foreground window */
hWnd = WM_CreateWindow(10, 10, 100, 100, WM_CF_SHOW, cbForegroundWin, 0);
/* Show foreground window */
GUI_Delay(1000);
/* Delete foreground window */
WM_DeleteWindow(hWnd);
GUI_DispStringAt("Background of window has not been redrawn", 10, 10);
/* Wait a while, background will not be redrawn */
GUI_Delay(1000);
GUI_Clear();
/* Set callback for Background window */
WM_SetCallback(WM_HBKWIN, cbBackgroundWin);
/* Create foreground window */
hWnd = WM_CreateWindow(10, 10, 100, 100,WM_CF_SHOW, cbForegroundWin, 0);
/* Show foreground window */
GUI_Delay(1000);
/* Delete foreground window */
WM_DeleteWindow(hWnd);
/* Wait a while, background will be redrawn */
GUI_Delay(1000);
/* Delete callback for Background window */
WM_SetCallback(WM_HBKWIN, 0);
}}
/*******************************************************************
*
*
main
*
********************************************************************
*/
void main(void) {
GUI_Init();
DemoRedraw();
}
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
344
User's & reference manual for emWin V5.10
CHAPTER
The Window Manager (WM)
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
345
Chapter 17
Window Objects (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) whenever necessary. Widgets are not required when writing an application or a user interface, but they can make programming much easier.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
346
CHAPTER
Window Objects (Widgets)
17.1 Some basics
17.1.1 Available widgets
The following table shows the appearance of the currently available widgets. Some of
the widgets support skinning. This method of changing the appearance is explained
in detail in chapter ’Skinning’. The second screenshot shows the appearance when
skinning is enabled for the widget:
Name
Screenshot
(classic)
Screenshot
(skinned)
Description
BUTTON
Button which can be pressed. Text or bitmaps
may be displayed on a button.
CHECKBOX
Check box which may be checked or
unchecked.
DROPDOWN
Dropdown listbox, opens a listbox when
pressed.
EDIT
Single-line edit field which prompts the user to
type a number or text.
FRAMEWIN
Frame window. Creates the typical GUI look.
GRAPH
Graph widget, used to show curves or measured values.
HEADER
Header control, used to manage columns.
ICONVIEW
Icon view widget. Useful for icon based platforms as found in common hand held devices.
LISTBOX
Listbox which highlights items as they are
selected by the user.
LISTVIEW
Listview widgets are used to creates tables.
LISTWHEEL
Listwheel widget. The data can be moved and
accelerated via pointer input device.
MENU
Menu widgets are used to create horizontal
and vertical menus.
MULTIEDIT
Multiedit widgets are used to edit multiple
lines of text.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
347
Name
Screenshot
(classic)
Screenshot
(skinned)
Description
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.
TREEVIEW
Treeview widget for managing hierarchical
lists.
17.1.2 Understanding the redrawing mechanism
A widget draws itself according to its properties. This is done when WM_Exec(),
GUI_Exec() or GUI_Delay() is called. In a multitasking environment, a background
task is normally used to call WM_Exec() and update the widgets (and all other windows with callback functions).
When a property of a widget is changed, the window of the widget (or part of it) is
marked as invalid, but it is not immediately redrawn. Therefore, the section of code
executes very fast. The redrawing is done by the WM at a later time or it can be
forced by calling WM_Paint() for the widget (or WM_Exec() until all windows are
redrawn).
17.1.3 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_Exec() 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 created above show 45%
and to change the bar colors from their defaults (dark gray/light gray) to green/red,
the following section of code may be used:
PROGBAR_SetBarColor(hProgBar, 0, GUI_GREEN);
PROGBAR_SetBarColor(hProgBar, 1, GUI_RED);
PROGBAR_SetValue(hProgBar, 45);
Default configuration
All widgets also have one or more configuration macros which define various default
settings such as fonts and colors used. The available configuration options are listed
for each widget in their respective sections later in the chapter.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
348
CHAPTER
Window Objects (Widgets)
How widgets communicate
Widgets are often created as child windows. The parent window may be any type of
window, even another widget. A parent window usually needs to be informed whenever something occurs with one of its children in order to ensure synchronization.
Child window widgets communicate with their parent window by sending a
WM_NOTIFY_PARENT message whenever an event occurs. The notification code sent as
part of the message depends on the event.
Most widgets have one or more notification codes defining different types of events.
The available notification codes for each widget (if any) are listed under their respective sections.
Skinning
As explained before the appearance of a widget can be modified by using the member functions of the respective widget. Some of the widgets support skinning. If skinning is used for a widget the ’skin’ determines the appearance of the widget and
some of the member functions have no effect. For details please refer to the chapter
’Skinning’.
Dynamic memory usage for widgets
In embedded applications it is usually not very desirable to use dynamic memory at
all because of fragmentation effects. There are a number of different strategies that
can be used to avoid this, but they all work in a limited way whenever memory areas
are referenced by a pointer in the application program. For this reason, emWin uses
a different approach: all objects (and all data stored at run-time) are stored in memory areas referenced by a handle. This makes it possible to relocate the allocated
memory areas at run-time, thus avoiding the long-term allocation problems which
occur when using pointers. All widgets are thus referenced by handles.
Determine the type of a widget
There is no function like WM_GetWidgetType() to determine the type of a widget. The
type can be determined only by comparing the callback function of a specific widget
with the public callback functions of the widget API. This works fine if the callback
function is not overwritten. The following shows a short example how to determine
the type of a widget. In case of overwritten callback functions the method should be
adapted:
WM_CALLBACK * pCb = WM_GetCallback(hWidget);
if
(pCb == BUTTON_Callback) {
/* Widget is a button */
} else if (pCb == DROPDOWN_Callback) {
/* Widget is a dropdown */
} else if (pCb == LISTBOX_Callback) {
/* Widget is a listbox */
} else if (...) {
...
}
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
349
17.2 Configuration options
Type
B
Macro
WIDGET_USE_PARENT_EFFECT
Default
Description
0
If set to 1, each ’child widget’ of a widget, has
the same effect as the parent widget. If for
example a listbox needs to create a scrollbar, the
new scrollbar has the same effect as the listbox.
B
WIDGET_USE_SCHEME_LARGE
0
If set to 1, the default appearance of the widgets
is large sized. That means that all widgets which
show text are configured to use large sized
default fonts.
B
WIDGET_USE_SCHEME_MEDIUM
0
If set to 1, the default appearance of the widgets
is medium sized. That means that all widgets
which show text are configured to use medium
sized default fonts.
B
WIDGET_USE_SCHEME_SMALL
1
If set to 1, the default appearance of the widgets
is small sized. That means that all widgets which
show text are configured to use small sized
default fonts.
B
WIDGET_USE_FLEX_SKIN
0
If set to 1, widgets are drawn using the Flex Skin
by default. For more information about Skinning,
please refer to the chapter ’Skinning’.
WIDGET_USE_SCHEME...
The table below shows the default appearance of the widget schemes:
WIDGET_USE_SCHEME_LARGE
WIDGET_USE_SCHEME_MEDIUM
WIDGET_USE_SCHEME_SMALL
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
350
CHAPTER
Window Objects (Widgets)
17.3 General widget API
17.3.1 WM routines used for widgets
Since widgets are essentially windows, they are compatible with any of the window
manager API routines. The handle of the widget is used as the hWin parameter and
the widget is treated like any other window. The WM functions most commonly used
with widgets are listed as follows:
Routine
WM_DeleteWindow()
WM_DisableMemdev()
WM_EnableMemdev()
WM_InvalidateWindow()
WM_Paint()
Description
Deletes a window.
Disables usage of memory devices for redrawing.
Enables usage of memory devices for redrawing.
Invalidates a window.
Draws or redraws a window immediately.
For a complete list of WM-related functions, refer to the chapter “The Window Manager (WM)” on page 289.
17.3.2 Common routines
The table below lists available widget-related routines in alphabetical order. These
functions are common to all widgets, and are listed here in order to avoid repetition.
Detailed descriptions of the routines follow. The additional member functions available for each widget may be found in later sections.
Routine
<WIDGET>_Callback()
<WIDGET>_CreateIndirect()
<WIDGET>_CreateUser()
<WIDGET>_GetUserData()
<WIDGET>_SetUserData()
WIDGET_GetDefaultEffect()
WIDGET_SetDefaultEffect()
WIDGET_SetEffect()
Description
Default callback function.
Used for automatic creation in dialog boxes.
Creates a widget using extra bytes as user data.
Retrieves the data set with <WIDGET>_SetUserData.
Sets the extra data of a widget.
Returns the default effect used for widgets.
Sets the default effect used for widgets.
Sets the effect used for a given widget.
<WIDGET>_Callback()
Description
Default callback function of the widgets to be used from within overwritten callback
function.
Prototype
void <WIDGET>_Callback(WM_MESSAGE * pMsg);
Parameter
pMsg
Description
Pointer to a data structure of type WM_MESSAGE.
Additional information
A default callback function of a widget should not be called directly. It is only to be
used from within an overwritten callback function.
For details about the WM_MESSAGE data structure, refer to “Messages” on page 295.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
351
<WIDGET>_CreateIndirect()
Description
Creates a widget to be used in dialog boxes.
Prototype
<WIDGET>_Handle <WIDGET>_CreateIndirect(
const GUI_WIDGET_CREATE_INFO * pCreateInfo,
WM_HWIN
hParent,
int
x0,
int
y0,
WM_CALLBACK
* cb
);
Parameter
pCreateInfo
hParent
x0
y0
cb
Description
Pointer to a
GUI_WIDGET_CREATE_INFO structure (see below).
Handle of parent window.
Leftmost pixel of the widget (in parent coordinates).
Topmost pixel of the widget (in parent coordinates).
Pointer to a callback function.
Additional information
Any widget may be created indirectly by using the appropriate prefix. For example:
BUTTON_CreateIndirect() to indirectly create a button widget,
CHECKBOX_CreateIndirect() to indirectly create a check box widget, and so on.
A widget only needs to be created indirectly if it is to be included in a dialog box.
Otherwise, it may be created directly by using the <WIDGET>_Create() functions.
See the chapter “Dialogs” on page 665 for more information about dialog boxes.
Resource table
The GUI_WIDGET_CREATE_INFO data structure is defined in the dialog resource table
as follows:
typedef struct {
GUI_WIDGET_CREATE_FUNC * pfCreateIndirect; // Create function
const char * pName;
// Text (not used for all widgets)
I16 Id;
// Window ID of the widget
I16 x0, y0, xSize, ySize;
// Size and position of the widget
I16 Flags;
// Widget-specific flags (or 0)
I32 Para;
// Widget-specific parameter (or 0)
U32 NumExtraBytes;
// Number of extra bytes usable
// with <WIDGET>_SetUserData &
//
<WIDGET>_GetUserData
} GUI_WIDGET_CREATE_INFO;
Widget flags and parameters are optional, and vary depending on the type of widget.
The available flags and parameters for each widget (if any) will be listed under the
appropriate section later in this chapter.
<WIDGET>_CreateUser()
Description
Creates a widget using extra bytes as user data. This function is similar to the <WIDGET>_CreateEx()-function of the appropriate widget in every case except the additional parameter NumExtraBytes.
Prototype
<WIDGET>_Handle <WIDGET>_CreateUser(int x0, int y0, ..., int Id,
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
352
CHAPTER
Window Objects (Widgets)
int NumExtraBytes);
Parameter
NumBytes
Description
Number of extra bytes to be allocated
Return value
Handle of the created widget; 0 if the function fails.
Additional information
For more information about the other parameters
GET>_CreateEx()-functions can be referred to.
the
appropriate
<WID-
<WIDGET>_GetUserData()
Description
Retrieves the data set with <WIDGET>_SetUserData.
Prototype
int <WIDGET>_GetUserData(<WIDGET>_Handle
hObj,
void
* pDest,
int
NumBytes)
Parameter
hObj
pDest
NumBytes
Description
Handle of the widget
Pointer to buffer
Number of bytes to read
Return value
Number of bytes read
Additional information
The maximum number of bytes returned by this function is the number of extra bytes
specified when creating the widget using <WIDGET>_CreateUser() or
<WIDGET>_CreateIndirect().
<WIDGET>_SetUserData()
Description
Sets the extra data of a widget.
Prototype
int <WIDGET>_GetUser(<WIDGET>_Handle
hObj,
void
* pDest,
int
NumBytes)
Parameter
hObj
pDest
NumBytes
Description
Handle of the widget
Pointer to buffer
Number of bytes to write
Return value
Number of bytes written
Additional information
The maximum number of bytes used to store user data is the number of extra bytes
specified when creating the widget using <WIDGET>_CreateUser() or
<WIDGET>_CreateIndirect().
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
353
WIDGET_GetDefaultEffect()
Description
Returns the default effect used for widgets.
Prototype
const WIDGET_EFFECT * WIDGET_GetDefaultEffect(void);
Return value
The result of the function is a pointer to a WIDGET_EFFECT structure.
Additional information
For more information, refer to “WIDGET_SetDefaultEffect()” on page 353.
WIDGET_SetDefaultEffect()
Description
Sets the default effect used for widgets.
Prototype
const WIDGET_EFFECT * WIDGET_SetDefaultEffect(const WIDGET_EFFECT* pEffect);
Parameter
Description
Pointer to a WIDGET_EFFECT structure. See table below.
pEffect
Permitted values for element pEffect
Sets the default effect to ’3D’.
&WIDGET_Effect_3D
Sets the default effect to ’None’.
&WIDGET_Effect_None
&WIDGET_Effect_Simple Sets the default effect to ’Simple’.
Return value
Previous used default effect.
Additional information
The following table shows the appearance of some widgets in dependence of the used
effect:
’3D’
User's & reference manual for emWin V5.10
’None’
’Simple’
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
354
CHAPTER
Window Objects (Widgets)
WIDGET_SetEffect()
Description
Sets the effect for the given widget.
Prototype
void WIDGET_SetEffect(WM_HWIN hObj, const WIDGET_EFFECT* pEffect);
Parameter
Description
hObj
Handle of widget.
pEffect
Pointer to a WIDGET_EFFECT structure. For details, refer to
“WIDGET_SetDefaultEffect()” on page 353.
17.3.3 User drawn widgets
Some widgets supports owner drawing, for example the LISTBOX widget. If the user
draw mode of a widget has been activated a application-defined function of type
WIDGET_DRAW_ITEM_FUNC will be called to draw the widget (item). The prototype of
an application-defined owner draw function should be defined as follows:
Prototype
int WIDGET_DRAW_ITEM_FUNC(const WIDGET_ITEM_DRAW_INFO * pDrawItemInfo)
Parameter
pDrawItemInfo
Description
Pointer to a WIDGET_ITEM_DRAW_INFO structure.
Elements of WIDGET_ITEM_DRAW_INFO
Data type
WM_HWIN
int
int
int
int
Element
hWin
Cmd
ItemIndex
x0
y0
Description
Handle to the widget.
(see table below)
Zero based index of item to be drawn.
X position in window coordinates to be used to draw the item.
Y position in window coordinates to be used to draw the item.
Permitted values for element Cmd
WIDGET_ITEM_GET_XSIZE
The function returns the x-size (width) in pixels
of the given item.
WIDGET_ITEM_GET_YSIZE
The function returns the y-size (height) in pixels
of the given item.
WIDGET_ITEM_DRAW
The function draws the given item at the given
position.
WIDGET_DRAW_BACKGROUND
The background of the widget should be drawn.
WIDGET_DRAW_OVERLAY
This command is send after all other drawing
operations have been finished and enables the
possibility to draw some overlaying items above
the widget.
Return value
Depends on the given command.
Reaction to commands
The function has to react to the command given in the WIDGET_ITEM_DRAW_INFO
structure. This can be done in one of 2 ways:
•
By calling the appropriate default function supplied by the particular widget (for
example, LISTBOX_OwnerDraw())
•
By supplying code that reacts accordingly.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
355
Commands
The commands listed below are supported and should be reacted to by the function.
As explained above, the default owner draw function should be called for all not handled functions. This is can save code size (for example if the height is the same as
the default height) and makes sure that your code stays compatible if in a future version of the software and add. command is introduced.
WIDGET_ITEM_GET_XSIZE
The X-size in pixels of the given item has to be returned.
WIDGET_ITEM_GET_YSIZE
The Y-size (height) in pixels of the given item has to be returned.
WIDGET_ITEM_DRAW
The given item has to be drawn. x0 and y0 of the WIDGET_ITEM_DRAW_INFO structure
specify the position of the item in window coordinates. The item has to fill its entire
rectangle; the rectangle is defined by the starting position x0, y0 supplied to the
function and the sizes returned by the function as reaction to the commands
WIDGET_ITEM_GET_YSIZE, WIDGET_ITEM_GET_XSIZE. It may NOT leave a part of this
rectangular area unpainted. It can not paint outside of this rectangular area because
the clip rectangle has been set before the function call.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
356
CHAPTER
Window Objects (Widgets)
17.4 BUTTON: Button widget
Button widgets are commonly used as the primary user interface element for touchscreens. If the button has the input focus, it also reacts on the keys GUI_KEY_SPACE
and GUI_KEY_ENTER. Buttons may be displayed with text, as shown below, or with a
bitmap.
All BUTTON-related routines are located in the file(s) BUTTON*.c, BUTTON.h. All identifiers are prefixed BUTTON.
Skinning...
...is available for this widget. The screenshot above shows the widget using the
default skin. For details please refer to chapter ’Skinning’.
17.4.1 Configuration options
Type
Macro
Default
Description
N
BUTTON_3D_MOVE_X
1
Number of pixels that text/bitmap moves
in horizontal direction in pressed state.
N
BUTTON_3D_MOVE_Y
1
Number of pixels that text/bitmap moves
in vertical direction in pressed state.
N
BUTTON_ALIGN_DEFAULT
GUI_TA_HCENTER
|
Alignment used to display the button text.
GUI_TA_VCENTER
N
N
BUTTON_BKCOLOR0_DEFAULT
BUTTON_BKCOLOR1_DEFAULT
N
BUTTON_FOCUSCOLOR_DEFAULT GUI_BLACK
S
BUTTON_FONT_DEFAULT
BUTTON_REACT_ON_LEVEL
BUTTON_TEXTCOLOR0_DEFAULT
BUTTON_TEXTCOLOR1_DEFAULT
B
N
N
0xAAAAAA
Background color, unpressed state.
GUI_WHITE
Background color, pressed state.
&GUI_Font13_1
Default color for rendering the focus rectangle.
Font used for button text.
0
See description below.
GUI_BLACK
Text color, unpressed state.
GUI_BLACK
Text color, pressed state.
BUTTON_REACT_ON_LEVEL
A button per default reacts on each touch message. For example if touching a dialog
with a pointer input device (PID) not exactly on the button and then move the PID in
pressed state over the button, the button changes from unpressed to pressed state.
This behavior can be useful if using a touch panel.
If a button should only react on level changes, BUTTON_REACT_ON_LEVEL should be
set to 1. Then a button changes the state only if the PID is pressed and released on
the button. If then moving a PID in pressed state over the button it does not react.
This behavior can be useful if dialogs should react on WM_NOTIFICATION_CLICKED.
Example (BUTTON_REACT_ON_LEVEL = 0): One dialog (dialog 2) is shown over an
other dialog (dialog 1). The close button of dialog 2 is on the same position as a button of dialog 1. Now the close button of dialog 2 is pressed, which removes dialog 2.
The PID now is in pressed state. If now moving the button before releasing it the button of dialog 1 would change from unpressed to pressed state.
This unwanted behavior can be avoid by setting BUTTON_REACT_ON_LEVEL to 1.
Alternatively to this configuration option the function BUTTON_SetReactOnLevel()
can be used.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
357
BUTTON_BKCOLOR0_DEFAULT, BUTTON_BKCOLOR1_DEFAULT
The default for the button is to use a white background in the pressed state. This has
been done purposely because it makes it very obvious that the button is pressed, on
any kind of display. If you want the background color of the button to be the same in
both its pressed and unpressed states, change BUTTON_BKCOLOR1_DEFAULT to
BUTTON_BKCOLOR0_DEFAULT.
17.4.2 Notification codes
The following events are sent from a button widget to its parent window as part of a
WM_NOTIFY_PARENT message:
Message
Description
WM_NOTIFICATION_CLICKED
WM_NOTIFICATION_RELEASED
WM_NOTIFICATION_MOVED_OUT
Button has been clicked.
Button has been released.
Button has been clicked and pointer has been moved out
off of the button without releasing.
17.4.3 Keyboard reaction
The widget reacts to the following keys if it has the input focus:
Key
Reaction
GUI_KEY_ENTER
If the keys is pressed, the button reacts as it has been pressed and
immediately released.
GUI_KEY_SPACE
If the keys is pressed, the button state changes to pressed. If the keys
is released, the button state changes to unpressed.
17.4.4 BUTTON API
The table below lists the available emWin BUTTON-related routines in alphabetical
order. Detailed descriptions of the routines follow.
Routine
BUTTON_Create()
BUTTON_CreateAsChild()
BUTTON_CreateEx()
BUTTON_CreateIndirect()
BUTTON_CreateUser()
BUTTON_GetBitmap()
BUTTON_GetBkColor()
BUTTON_GetDefaultBkColor()
BUTTON_GetDefaultFont()
BUTTON_GetDefaultTextAlign()
BUTTON_GetDefaultTextColor()
BUTTON_GetFont()
BUTTON_GetText()
BUTTON_GetTextAlign()
BUTTON_GetTextColor()
BUTTON_GetUserData()
BUTTON_IsPressed()
BUTTON_SetBitmap()
BUTTON_SetBitmapEx()
BUTTON_SetBkColor()
BUTTON_SetBMP()
BUTTON_SetBMPEx()
User's & reference manual for emWin V5.10
Description
Creates a BUTTON widget. (Obsolete)
Creates a BUTTON widget as a child window. (Obsolete)
Creates a BUTTON widget.
Creates a BUTTON widget from a resource table entry.
Creates a BUTTON widget using extra bytes as user data.
Returns the pointer to the BUTTON bitmap.
Returns the background color of the BUTTON
Returns the default background color for BUTTON widgets.
Returns the default font for BUTTON widgets.
Returns the default text alignment for BUTTON widgets.
Returns the default text color for BUTTON widgets.
Returns the pointer to the font of the BUTTON widget.
Retrieves the text of a specified BUTTON.
Returns the alignment of the BUTTON text.
Returns the text color of the specified BUTTON.
Retrieves the data set with BUTTON_SetUserData().
Returns if a button is pressed or not.
Sets the bitmap used when displaying the BUTTON.
Sets the bitmap used when displaying the BUTTON.
Sets the background color of the button.
Sets the bitmap used when displaying the BUTTON.
Sets the bitmap used when displaying the BUTTON.
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
358
CHAPTER
Window Objects (Widgets)
Routine
BUTTON_SetDefaultBkColor()
BUTTON_SetDefaultFont()
BUTTON_SetDefaultTextAlign()
BUTTON_SetDefaultTextColor()
BUTTON_SetFocussable()
BUTTON_SetFont()
BUTTON_SetPressed()
BUTTON_SetReactOnLevel()
BUTTON_SetStreamedBitmap()
BUTTON_SetStreamedBitmapEx()
BUTTON_SetText()
BUTTON_SetTextAlign()
BUTTON_SetTextColor()
Description
Sets the default background color for BUTTON widgets.
Sets the default font for BUTTON widgets.
Sets the default text alignment for BUTTON widgets.
Sets the default text color for BUTTON widgets.
Sets the ability to receive the input focus.
Selects the font for the text.
Sets the state of the button to pressed or unpressed.
Sets all BUTTON widgets to react on level.
Sets the bitmap used when displaying the BUTTON widget.
Sets the bitmap used when displaying the BUTTON widget.
Sets the text.
Sets the alignment of the BUTTON text.
Set the color(s) for the text.
BUTTON_SetTextOffset()
Adjusts the position of the button text considering the current
text alignment setting.
BUTTON_SetUserData()
Sets the extra data of a BUTTON widget.
BUTTON_Create()
(Obsolete, BUTTON_CreateEx() should be used instead)
Description
Creates a BUTTON widget of a specified size at a specified location.
Prototype
BUTTON_Handle BUTTON_Create(int x0,
int y0,
int xsize, int ysize,
int Id,
int Flags);
Parameter
x0
y0
xsize
ysize
Id
Flags
Description
Leftmost pixel of the button (in parent coordinates).
Topmost pixel of the button (in parent coordinates).
Horizontal size of the button (in pixels).
Vertical size of the button (in pixels).
ID to be returned when button is pressed.
Window create flags. Typically WM_CF_SHOW in order to make the widget visible
immediately (refer to WM_CreateWindow() in the chapter “The Window Manager
(WM)” on page 289 for a list of available parameter values).
Return value
Handle of the created BUTTON widget; 0 if the function fails.
BUTTON_CreateAsChild()
(Obsolete, BUTTON_CreateEx should be used instead)
Description
Creates a BUTTON widget as a child window.
Prototype
BUTTON_Handle BUTTON_CreateAsChild(int
int
WM_HWIN
int
User's & reference manual for emWin V5.10
x0,
int y0,
xsize,
int ysize,
hParent, int Id,
Flags);
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
359
Parameter
x0
y0
xsize
ysize
hParent
Id
Flags
Description
X-position of the button relative to the parent window.
Y-position of the button relative to the parent window.
Horizontal size of the button (in pixels).
Vertical size of the button (in pixels).
Handle of parent window. If 0, the BUTTON widget will be a child of the desktop (toplevel window).
ID to be returned when button is pressed.
Window create flags (see
BUTTON_Create() ).
Return value
Handle of the created BUTTON widget; 0 if the function fails.
BUTTON_CreateEx()
Description
Creates a BUTTON widget of a specified size at a specified location.
Prototype
BUTTON_Handle BUTTON_CreateEx(int
int
WM_HWIN
int
Parameter
x0
y0
xsize
ysize
x0,
xsize,
hParent,
ExFlags,
int
int
int
int
y0,
ysize,
WinFlags,
Id);
Description
Leftmost pixel of the widget (in parent coordinates).
Topmost pixel of the widget (in parent coordinates).
Horizontal size of the widget (in pixels).
Vertical size of the widget (in pixels).
hParent
Handle of parent window. If 0, the BUTTON widget will be a child of the desktop (toplevel window).
WinFlags
Window create flags. Typically WM_CF_SHOW in order to make the widget visible
immediately (refer to WM_CreateWindow() in the chapter “The Window Manager
(WM)” on page 289 for a list of available parameter values).
ExFlags
Id
Not used yet, reserved for future use.
Window ID of the widget.
Return value
Handle of the created BUTTON widget; 0 if the function fails.
Additional information
If the possibility of storing user data is a matter the function BUTTON_CreateUser()
should be used instead.
BUTTON_CreateIndirect()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateIndirect().
The elements Flags and Para of the resource passed as parameter are not used.
BUTTON_CreateUser()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateUser(). For
a detailed description of the parameters the function BUTTON_CreateEx() can be
referred to.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
360
CHAPTER
Window Objects (Widgets)
BUTTON_GetBitmap()
Description
Returns a pointer to the optional BUTTON bitmap.
Prototype
const GUI_BITMAP * BUTTON_GetBitmap(BUTTON_Handle hObj,
unsigned int Index);
Parameter
hObj
Index
Description
Handle of widget.
Index of desired bitmap (see table below).
Permitted values for parameter Index
BUTTON_BI_DISABLED Bitmap for disabled state.
Bitmap for pressed state.
BUTTON_BI_PRESSED
BUTTON_BI_UNPRESSED Bitmap for unpressed state.
Return value
Pointer to the bitmap, 0 if no bitmap exist.
Additional information
For details about how to set a button bitmap, refer to “BUTTON_SetBitmap()” on
page 363 and “BUTTON_SetBitmapEx()” on page 363.
BUTTON_GetBkColor()
Description
Returns the background color of the given BUTTON widget.
Prototype
GUI_COLOR BUTTON_GetBkColor(BUTTON_Handle hObj, unsigned int Index);
Parameter
hObj
Index
Description
Handle of widget.
Index for color (see table below).
Permitted values for parameter Index
BUTTON_CI_DISABLED Color for disabled state.
Color for pressed state.
BUTTON_CI_PRESSED
BUTTON_CI_UNPRESSED Color for unpressed state.
Return value
Background color of the given BUTTON widget
BUTTON_GetDefaultBkColor()
Description
Returns the default background color for BUTTON widgets.
Prototype
GUI_COLOR BUTTON_GetDefaultBkColor(unsigned Index);
Parameter
Index
Description
Index for color (see table below).
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
361
Permitted values for parameter Index
BUTTON_CI_DISABLED Color for disabled state.
Color for pressed state.
BUTTON_CI_PRESSED
BUTTON_CI_UNPRESSED Color for unpressed state.
Return value
Default background color for BUTTON widgets
BUTTON_GetDefaultFont()
Description
Returns the pointer to the font used to display the text of BUTTON widgets.
Prototype
const GUI_FONT * BUTTON_GetDefaultFont(void);
Return value
Pointer to the font used to display the text of BUTTON widgets.
BUTTON_GetDefaultTextAlign()
Description
Returns the default text alignment used to display the text of BUTTON widgets.
Prototype
int BUTTON_GetDefaultTextAlign(void);
Return value
Default text alignment used to display the text of BUTTON widgets.
BUTTON_GetDefaultTextColor()
Description
Returns the default text color used to display the text of BUTTON widgets.
Prototype
GUI_COLOR BUTTON_GetDefaultTextColor(unsigned Index);
Parameter
Index
Description
Index for color (see table below).
Permitted values for parameter Index
BUTTON_CI_DISABLED Color for disabled state.
Color for pressed state.
BUTTON_CI_PRESSED
BUTTON_CI_UNPRESSED Color for unpressed state.
Return value
Default text color used to display the text of BUTTON widgets.
BUTTON_GetFont()
Description
Returns a pointer to the font used to display the text of the given BUTTON widget
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
362
CHAPTER
Window Objects (Widgets)
Prototype
const GUI_FONT * BUTTON_GetFont(BUTTON_Handle hObj);
Parameter
hObj
Description
Handle of widget.
Return value
Pointer to the font used to display the text of the given BUTTON widget.
BUTTON_GetText()
Description
Retrieves the text of the specified BUTTON widget.
Prototype
void BUTTON_GetText(BUTTON_Handle hObj, char * pBuffer, int MaxLen);
Parameter
hObj
pBuffer
MaxLen
Description
Handle of widget.
Pointer to buffer.
Size of buffer.
BUTTON_GetTextAlign()
Description
Returns the alignment of the BUTTON text.
Prototype
int BUTTON_GetTextAlign(BUTTON_Handle hObj);
Parameter
hObj
Description
Handle of the BUTTON widget.
Return value
Alignment of the BUTTON text.
BUTTON_GetTextColor()
Description
Returns the text color of the given BUTTON widget.
Prototype
GUI_COLOR BUTTON_GetTextColor(BUTTON_Handle hObj, unsigned int Index);
Parameter
hObj
Index
Description
Handle of widget.
Index for color (see table below).
Permitted values for parameter Index
BUTTON_CI_DISABLED Color for disabled state.
Color for pressed state.
BUTTON_CI_PRESSED
BUTTON_CI_UNPRESSED Color for unpressed state.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
363
Return value
Text color of the given BUTTON widget.
BUTTON_GetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_GetUserData().
BUTTON_IsPressed()
Description
Returns if the BUTTON is pressed or not.
Prototype
unsigned BUTTON_IsPressed(BUTTON_Handle hObj);
Parameter
hObj
Description
Handle of widget.
Return value
1 if the button is pressed, 0 if not.
BUTTON_SetBitmap()
Description
Sets the bitmap(s) to be used when displaying a specified button.
Prototype
void BUTTON_SetBitmap(BUTTON_Handle
hObj,
unsigned int
Index,
const GUI_BITMAP * pBitmap);
Parameter
hObj
Index
pBitmap
Description
Handle of button.
Index for bitmap (see table below).
Pointer to the bitmap structure.
Permitted values for parameter Index
BUTTON_BI_DISABLED Bitmap for disabled state.
Bitmap for pressed state.
BUTTON_BI_PRESSED
BUTTON_BI_UNPRESSED Bitmap for unpressed state.
Additional information
If only a bitmap for the unpressed state is set the button will show it also when it is
pressed or disabled.
BUTTON_SetBitmapEx()
Description
Sets the bitmap(s) to be used when displaying a specified button.
Prototype
void BUTTON_SetBitmapEx(BUTTON_Handle
hObj,
unsigned int
Index,
const GUI_BITMAP * pBitmap,
int
x,
int
y);
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
364
CHAPTER
Parameter
hObj
Index
pBitmap
x
y
Window Objects (Widgets)
Description
Handle of button.
Index for bitmap (see
BUTTON_SetBitmap() ).
Pointer to the bitmap structure.
X-position for the bitmap relative to the button.
Y-position for the bitmap relative to the button.
Additional information
If only a bitmap for the unpressed state is set the button will show it also when it is
pressed or disabled.
BUTTON_SetBkColor()
Description
Sets the button background color.
Prototype
void BUTTON_SetBkColor(BUTTON_Handle hObj,
unsigned int Index,
GUI_COLOR
Color);
Parameter
hObj
Index
Color
Description
Handle of button.
Index for color (see table below).
Background color to be set.
Permitted values for parameter Index
BUTTON_CI_DISABLED Sets the color to be used when button is disabled.
Sets the color to be used when button is pressed.
BUTTON_CI_PRESSED
BUTTON_CI_UNPRESSED Sets the color to be used when button is unpressed.
BUTTON_SetBMP()
Description
Sets the bitmap(s) to be used when displaying a specified button.
Prototype
void BUTTON_SetBMP(BUTTON_Handle hObj, unsigned int Index,
const void * pBitmap);
Parameter
hObj
Index
pBitmap
Description
Handle of widget.
Index for bitmap (see table below).
Pointer to bitmap file data
Permitted values for parameter Index
BUTTON_BI_DISABLED Sets the bitmap to be used when button is disabled.
Sets the bitmap to be used when button is pressed.
BUTTON_BI_PRESSED
BUTTON_BI_UNPRESSED Sets the bitmap to be used when button is unpressed.
Additional information
If only a bitmap for the unpressed state is set the button will show it also when it is
pressed or disabled.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
365
For additional information’s regarding bitmap files, refer to “BMP file support” on
page 142.
BUTTON_SetBMPEx()
Description
Sets the bitmap(s) to be used when displaying a specified button.
Prototype
void BUTTON_SetBMPEx(BUTTON_Handle
hObj,
unsigned int Index,
const void
* pBitmap, int
x,
int
y);
Parameter
hObj
Index
pBitmap
x
y
Description
Handle of widget.
Index for bitmap (see
BUTTON_SetBitmap() ).
Pointer to bitmap file data
X-position for the bitmap relative to the button.
Y-position for the bitmap relative to the button.
Additional information
If only a bitmap for the unpressed state is set the button will show it also when it is
pressed or disabled.
For additional informations regarding bitmap files, refer to “BMP file support” on page 142.
BUTTON_SetDefaultBkColor()
Description
Sets the default background color used for BUTTON widgets.
Prototype
void BUTTON_SetDefaultBkColor(GUI_COLOR Color, unsigned Index);
Parameter
Color
Index
Description
Color to be used.
Index for color (see table below).
Permitted values for parameter Index
BUTTON_CI_DISABLED Color for disabled state.
Color for pressed state.
BUTTON_CI_PRESSED
BUTTON_CI_UNPRESSED Color for unpressed state.
BUTTON_SetDefaultFocusColor()
Description
Sets the default focus rectangle color for BUTTON widgets.
Prototype
GUI_COLOR BUTTON_SetDefaultFocusColor(GUI_COLOR Color);
Parameter
Color
Description
Default color to be used for BUTTON widgets.
Return value
Previous default focus rectangle color.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
366
CHAPTER
Window Objects (Widgets)
Additional information
For more information, refer to “BUTTON_SetFocusColor()” on page 366.
BUTTON_SetDefaultFont()
Description
Sets a pointer to a GUI_FONT structure used to display the text of BUTTON widgets.
Prototype
void BUTTON_SetDefaultFont(const GUI_FONT * pFont);
Parameter
pFont
Description
Pointer to GUI_FONT structure to be used.
BUTTON_SetDefaultTextAlign()
Description
Sets the default text alignment used to display the text of BUTTON widgets.
Prototype
void BUTTON_SetDefaultTextAlign(int Align);
Parameter
Align
Description
Text alignment to be used. For details, refer to “GUI_SetTextAlign()” on page 82.
BUTTON_SetDefaultTextColor()
Description
Sets the default text color used to display the text of BUTTON widgets.
Prototype
void BUTTON_SetDefaultTextColor(GUI_COLOR Color, unsigned Index);
Parameter
Color
Index
Description
Default text color to be used.
Index for color (see table below).
Permitted values for parameter Index
BUTTON_CI_DISABLED Color for disabled state.
Color for pressed state.
BUTTON_CI_PRESSED
BUTTON_CI_UNPRESSED Color for unpressed state.
BUTTON_SetFocusColor()
Before
After
Description
Sets the color used to render the focus rectangle of the BUTTON widget.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
367
Prototype
GUI_COLOR BUTTON_SetFocusColor(BUTTON_Handle hObj, GUI_COLOR Color);
Parameter
hObj
Color
Description
Handle of widget.
Color to be used for the focus rectangle.
Return value
Previous color of the focus rectangle.
Additional information
The focus rectangle is only visible if the widget has the input focus.
BUTTON_SetFocussable()
Description
Sets the ability to receive the input focus.
Prototype
void BUTTON_SetFocussable(BUTTON_Handle hObj, int State);
Parameter
hWin
State
Description
Window handle.
see table below
Permitted values for parameter State
1
0
Button can receive the input focus
Button can’t receive the input focus
BUTTON_SetFont()
Description
Sets the button font.
Prototype
void BUTTON_SetFont(BUTTON_Handle hObj, const GUI_FONT* pFont);
Parameter
hObj
pFont
Description
Handle of button.
Pointer to the font.
Additional information
If no font is selected, BUTTON_FONT_DEF will be used.
BUTTON_SetPressed()
Description
Sets the state of the button to pressed or unpressed.
Prototype
void BUTTON_SetPressed(BUTTON_Handle hObj, int State);
Parameter
hObj
State
Description
Handle of button.
State, 1 for pressed, 0 for unpressed
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
368
CHAPTER
Window Objects (Widgets)
BUTTON_SetReactOnLevel()
Description
Sets all BUTTON widgets to react on level.
Prototype
void BUTTON_SetReactOnLevel(void);
Additional Information
Alternatively to this function the configuration option BUTTON_REACT_ON_LEVEL can
be used.
BUTTON_SetStreamedBitmap()
Description
Sets the streamed bitmap(s) to be used when displaying a specified button object.
Prototype
void BUTTON_SetStreamedBitmap(BUTTON_Handle
hObj,
unsigned int
Index,
const GUI_BITMAP_STREAM * pBitmap);
Parameter
hObj
Index
pBitmap
Description
Handle of button.
Index for bitmap (see
BUTTON_SetBitmap() ).
Pointer to a bitmap stream.
Additional information
For details about streamed bitmaps, refer to “GUI_DrawStreamedBitmap()”
page 118.
on
BUTTON_SetStreamedBitmapEx()
Description
Sets the streamed bitmap(s) to be used when displaying a specified button object.
Prototype
void BUTTON_SetStreamedBitmapEx(BUTTON_Handle
hObj,
unsigned int
Index,
const GUI_BITMAP_STREAM * pBitmap,
int
x,
int
y);
Parameter
hObj
Index
pBitmap
x
y
Description
Handle of button.
Index for bitmap (see
BUTTON_SetBitmap() ).
Pointer to a bitmap stream.
X-position for the bitmap relative to the button.
Y-position for the bitmap relative to the button.
Additional information
For details about streamed bitmaps, refer to “GUI_DrawStreamedBitmap()”
page 118().
User's & reference manual for emWin V5.10
on
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
369
BUTTON_SetText()
Description
Sets the text to be displayed on the button.
Prototype
void BUTTON_SetText(BUTTON_Handle hObj, const char * s);
Parameter
hObj
s
Description
Handle of button.
Text to display.
BUTTON_SetTextAlign()
Description
Sets the alignment of the button text.
Prototype
void BUTTON_SetTextAlign(BUTTON_Handle hObj, int Align);
Parameter
hObj
Align
Description
Handle of button.
Text alignment to be set (see “GUI_SetTextAlign()” on page 82)
Additional information
The default value of the text alignment is GUI_TA_HCENTER | GUI_TA_VCENTER.
BUTTON_SetTextColor()
Description
Sets the button text color.
Prototype
void BUTTON_SetTextColor(BUTTON_Handle hObj, unsigned int Index,
GUI_COLOR Color);
Parameter
hObj
Index
Color
Description
Handle of button.
Index for text color (see
BUTTON_SetBkColor() ).
Text color to be set.
BUTTON_SetTextOffset()
Description
Adjusts the position of the button text considering the current text alignment setting.
Prototype
void BUTTON_SetTextOffset(BUTTON_Handle hObj, int xPos, int yPos);
Parameter
hObj
xPos
yPos
Description
Handle of button.
Offset to be used for the x-axis. Default is 0.
Offset to be used for the y-axis. Default is 0.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
370
CHAPTER
Window Objects (Widgets)
BUTTON_SetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_SetUserData().
17.4.5 Examples
The Sample folder contains the following examples which show how the widget can be
used:
•
WIDGET_ButtonSimple.c
•
WIDGET_ButtonPhone.c
•
WIDGET_ButtonRound.c
Note that several other examples also make use of this widget and may also be helpful to get familiar with the widget.
Screenshot of WIDGET_ButtonSimple.c:
Screenshot of WIDGET_ButtonPhone.c:
Screenshot of WIDGET_ButtonRound.c:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
371
17.5 CHECKBOX: Checkbox 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. If using a keyboard interface the state of a focused check
box can be toggled by the <SPACE> key. A box will appear gray if it is disabled, as
seen in the table below where each of the possible check box appearances are illustrated:
Unchecked
Checked
Third state
Enabled
Disabled
All CHECKBOX-related routines are located in the file(s) CHECKBOX*.c, CHECKBOX.h.
All identifiers are prefixed CHECKBOX.
Skinning...
...is available for this widget. The screenshot above shows the widget using the
default skin. For details please refer to chapter ’Skinning’.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
372
CHAPTER
Window Objects (Widgets)
17.5.1 Configuration options
Type
Macro
Default
Description
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.
17.5.2 Notification codes
The following events are sent from a check box widget to its parent window as part of
a WM_NOTIFY_PARENT message:
Message
Description
WM_NOTIFICATION_CLICKED
WM_NOTIFICATION_RELEASED
Check box has been clicked.
Check box has been released.
WM_NOTIFICATION_MOVED_OUT
Check box has been clicked and pointer has been moved
out off of the box without releasing.
WM_NOTIFICATION_VALUE_CHANGED
Status of check box has been changed.
17.5.3 Keyboard reaction
The widget reacts to the following keys if it has the input focus:
Key
GUI_KEY_SPACE
Reaction
Toggles the checked state of the widget.
17.5.4 CHECKBOX API
The table below lists the available emWin CHECKBOX-related routines in alphabetical
order. Detailed descriptions of the routines follow.
Routine
CHECKBOX_Check()
CHECKBOX_Create()
CHECKBOX_CreateEx()
CHECKBOX_CreateIndirect()
Description
Set the check box state to checked. (Obsolete)
Creates a CHECKBOX widget. (Obsolete)
Creates a CHECKBOX widget.
Creates a CHECKBOX widget from resource table entry.
CHECKBOX_CreateUser()
Creates a CHECKBOX widget using extra bytes as user
data.
CHECKBOX_GetDefaultBkColor()
Returns the default background color for CHECKBOX widgets.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
373
Routine
Description
CHECKBOX_GetDefaultFont()
Returns the default font used to display the text of
CHECKBOX widgets.
CHECKBOX_GetDefaultSpacing()
Returns the default spacing between the box and the text
of CHECKBOX widgets.
CHECKBOX_GetDefaultTextAlign()
Returns the default alignment used to display the text of
CHECKBOX widgets.
CHECKBOX_GetDefaultTextColor()
Returns the default text color used to display the text of
CHECKBOX widgets.
CHECKBOX_GetState()
CHECKBOX_GetText()
CHECKBOX_GetUserData()
CHECKBOX_IsChecked()
CHECKBOX_SetBkColor()
CHECKBOX_SetBoxBkColor()
CHECKBOX_SetDefaultBkColor()
Returns the current state of the check box.
Returns the text of the check box.
Retrieves the data set with CHECKBOX_SetUserData().
Return the current state (checked or not checked) of the
check box.
Sets the background color of the given CHECKBOX widget.
Sets the background color of the box area.
Sets the default background color for CHECKBOX widget.
CHECKBOX_SetDefaultFocusColor()
Sets the default focus rectangle color for CHECKBOX widgets.
CHECKBOX_SetDefaultFont()
Sets the default font used to display the text of CHECKBOX widgets.
CHECKBOX_SetDefaultImage()
Sets the default image to be shown when a box has been
checked.
CHECKBOX_SetDefaultSpacing()
Sets the default spacing between the box and the text of
CHECKBOX 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
CHECKBOX widgets.
CHECKBOX_SetFocusColor()
CHECKBOX_SetFont()
CHECKBOX_SetImage()
CHECKBOX_SetNumStates()
CHECKBOX_SetSpacing()
CHECKBOX_SetState()
CHECKBOX_SetText()
Sets the color of the focus rectangle.
Sets the checkbox font.
Sets the image to be shown when box has been checked.
Sets the number of possible states of the check box (2 or
3).
Sets the spacing between the box and the check box text.
Sets the state of the CHECKBOX widget.
Sets the text of the CHECKBOX widget.
CHECKBOX_SetTextAlign()
Sets the alignment used to display the text of the CHECKBOX widget.
CHECKBOX_SetTextColor()
Sets the color used to display the text of the CHECKBOX
widget.
CHECKBOX_SetUserData()
CHECKBOX_Uncheck()
Sets the extra data of a CHECKBOX widget.
Set the check box state to unchecked. (Obsolete)
CHECKBOX_Check()
(Obsolete, CHECKBOX_SetState() should be used instead)
Before
After
Description
Sets a specified check box to a checked state.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
374
CHAPTER
Window Objects (Widgets)
Prototype
void CHECKBOX_Check(CHECKBOX_Handle hObj);
Parameter
hObj
Description
Handle of check box.
CHECKBOX_Create()
(Obsolete, CHECKBOX_CreateEx should be used instead)
Description
Creates a CHECKBOX widget of a specified size at a specified location.
Prototype
CHECKBOX_Handle CHECKBOX_Create(int
int
WM_HWIN
int
Parameter
x0
y0
xsize
ysize
hParent
Id
Flags
x0,
int y0,
xsize,
int ysize,
hParent, int Id,
Flags);
Description
Leftmost pixel of the check box (in parent coordinates).
Topmost pixel of the check box (in parent coordinates).
Horizontal size of the check box (in pixels).
Vertical size of the check box (in pixels).
Handle of parent window.
ID to be returned.
Window create flags. Typically WM_CF_SHOW in order to make the widget visible
immediately (refer to WM_CreateWindow() in the chapter “The Window Manager
(WM)” on page 289 for a list of available parameter values).
Return value
Handle of the created CHECKBOX widget; 0 if the function fails.
Additional information
If the parameters xsize or ysize are 0 the size of the bitmap will be used as default
size of the check box.
CHECKBOX_CreateEx()
Description
Creates a CHECKBOX widget of a specified size at a specified location.
Prototype
CHECKBOX_Handle CHECKBOX_CreateEx(int
int
WM_HWIN
int
Parameter
x0
y0
xsize
ysize
hParent
x0,
xsize,
hParent,
ExFlags,
int
int
int
int
y0,
ysize,
WinFlags,
Id);
Description
Leftmost pixel of the widget (in parent coordinates).
Topmost pixel of the widget (in parent coordinates).
Horizontal size of the widget (in pixels).
Vertical size of the widget (in pixels).
Handle of parent window. If 0, the new CHECKBOX widget will be a child of the desktop (top-level window).
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
375
Parameter
Description
Window create flags. Typically
WM_CF_SHOW in order to make the widget visible
WinFlags
immediately (refer to WM_CreateWindow() in the chapter “The Window Manager
(WM)” on page 289 for a list of available parameter values).
ExFlags
Id
Not used yet, reserved for future use.
Window ID of the widget.
Return value
Handle of the created CHECKBOX widget; 0 if the function fails.
Additional information
If the parameters xsize or ysize are 0 the size of the default check mark bitmap (11 x
11 pixels) plus the effect size will be used as default size of the check box. If the
desired size of the check box is different to the default size it can be useful to set a
user defined check mark image using the function CHECKBOX_SetImage().
If check box text should be shown with the widget the size should be large enough to
show the box + text + spacing between box and text.
CHECKBOX_CreateIndirect()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateIndirect().
The elements Flags and Para of the resource passed as parameter are not used.
CHECKBOX_CreateUser()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateUser(). For
a detailed description of the parameters the function CHECKBOX_CreateEx() can be
referred to.
CHECKBOX_GetDefaultBkColor()
Description
Returns the default background color of new check box widgets.
Prototype
GUI_COLOR CHECKBOX_GetDefaultBkColor(void);
Return value
Default background color of new check box widgets.
Additional information
The background color returned by this function is not the background color shown in
the box, but the background color of the rest of the widget.
For more information, refer to “CHECKBOX_SetBoxBkColor()” on page 378.
CHECKBOX_GetDefaultFont()
Description
Returns a pointer to a GUI_FONT structure used to display the check box text of new
check box widgets.
Prototype
const GUI_FONT * CHECKBOX_GetDefaultFont(void);
Return value
Pointer to a GUI_FONT structure used to display the check box text of new check box
widgets.
Additional information
For more information, refer to “CHECKBOX_SetFont()” on page 381.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
376
CHAPTER
Window Objects (Widgets)
CHECKBOX_GetDefaultSpacing()
Description
Returns the default spacing between box and text used to display the check box text
of new check box widgets.
Prototype
int CHECKBOX_GetDefaultSpacing(void);
Return value
Default spacing between box and text used to display the check box text of new
check box widgets.
Additional information
For more information, refer to “CHECKBOX_SetSpacing()” on page 383.
CHECKBOX_GetDefaultTextAlign()
Description
Returns the default alignment used to display the check box text of new check box
widgets.
Prototype
int CHECKBOX_GetDefaultAlign(void);
Return value
Default alignment used to display the check box text.
Additional information
For more information, refer to “CHECKBOX_SetTextAlign()” on page 384.
CHECKBOX_GetDefaultTextColor()
Description
Returns the default text color used to display the check box text of new check box
widgets.
Prototype
GUI_COLOR CHECKBOX_GetDefaultTextColor(void);
Return value
Default text color used to display the check box text of new check box widgets.
Additional information
For more information, refer to “CHECKBOX_SetTextColor()” on page 384.
CHECKBOX_GetState()
Description
Returns the current state of the given check box.
Prototype
int CHECKBOX_GetState(CHECKBOX_Handle hObj);
Parameter
hObj
Description
Handle of widget.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
377
Return value
Current state of the given check box.
Additional information
Per default a check box can have 2 states, checked (1) and unchecked (0). With the
function CHECKBOX_SetNumStates() the number of possible states can be increased
to 3. If the check box is in the third state the function returns 2.
For more information, refer to “CHECKBOX_SetNumStates()” on page 382.
CHECKBOX_GetText()
Description
Returns the optional text of the given check box.
Prototype
int CHECKBOX_GetText(CHECKBOX_Handle hObj, char * pBuffer, int MaxLen);
Parameter
hObj
pBuffer
MaxLen
Description
Handle of widget.
Pointer to buffer to which the text will be copied.
Buffer size in bytes.
Return value
Length of the text copied into the buffer.
Additional information
If the check box contains no text the function returns 0 and the buffer remains
unchanged.
CHECKBOX_GetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_GetUserData().
CHECKBOX_IsChecked()
Description
Returns the current state (checked or not checked) of a specified CHECKBOX widget.
Prototype
int CHECKBOX_IsChecked(CHECKBOX_Handle hObj);
Parameter
hObj
Description
Handle of check box.
Return value
0: not checked
1: checked
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
378
CHAPTER
Window Objects (Widgets)
CHECKBOX_SetBkColor()
Before
After
Description
Sets the background color used to display the background of the check box.
Prototype
void CHECKBOX_SetBkColor(CHECKBOX_Handle hObj, GUI_COLOR Color);
Parameter
Description
hObj
Handle of widget.
Color
Color to be used to draw the background or
transparent mode.
GUI_INVALID_COLOR to work in
Additional information
If the check box should work in transparent mode GUI_INVALID_COLOR should be
used.
CHECKBOX_SetBoxBkColor()
Before
After
Description
Sets the background color of the box area.
Prototype
GUI_COLOR CHECKBOX_SetBoxBkColor(CHECKBOX_Handle hObj,
GUI_COLOR
Color,
int
Index);
Parameter
hObj
Color
Index
Description
Handle of widget.
Color to be used.
(see table below)
Permitted values for parameter Index
CHECKBOX_CI_DISABLED
CHECKBOX_CI_ENABLED
Background color used for disabled state.
Background color used for enabled state.
Return value
Previous background color.
Additional information
The color set by this function will only be visible, if the images used by the widget are
transparent or no image is used. The default images of this widget are transparent.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
379
CHECKBOX_SetDefaultBkColor()
Description
Sets the default background color used for new check box widgets.
Prototype
void CHECKBOX_SetDefaultBkColor(GUI_COLOR Color);
Parameter
Color
Description
Color to be used,
GUI_INVALID_COLOR for transparency.
Additional information
For more information, refer to “CHECKBOX_SetBkColor()” on page 378.
CHECKBOX_SetDefaultFocusColor()
Description
Sets the color used to render the focus rectangle of new check box widgets.
Prototype
GUI_COLOR CHECKBOX_SetDefaultFocusColor(GUI_COLOR Color);
Parameter
Color
Description
Color to be used.
Return value
Previous color used to render the focus rectangle.
Additional information
For mode information, refer to “CHECKBOX_SetFocusColor()” on page 381.
CHECKBOX_SetDefaultFont()
Description
Sets a pointer to a GUI_FONT structure used to display the check box text of new
check box widgets.
Prototype
void CHECKBOX_SetDefaultFont(const GUI_FONT * pFont);
Parameter
pFont
Description
Pointer to GUI_FONT structure to be used.
Additional information
For more information, refer to “CHECKBOX_SetFont()” on page 381.
CHECKBOX_SetDefaultImage()
Description
Sets the images used for new check boxes to be shown if they has been checked.
Prototype
void CHECKBOX_SetDefaultImage(const GUI_BITMAP * pBitmap,
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
380
CHAPTER
Window Objects (Widgets)
unsigned int
Parameter
pBitmap
Index
Index);
Description
Pointer to bitmap.
(see table below)
Permitted values for parameter Index
Sets the bitmap displayed when the
CHECKBOX_BI_INACTIV_UNCHECKED check box is unchecked and disabled.
CHECKBOX_BI_ACTIV_UNCHECKED
Sets the bitmap displayed when the
check box is unchecked and enabled.
CHECKBOX_BI_INACTIV_CHECKED
Sets the bitmap displayed when the
check box is checked and disabled.
CHECKBOX_BI_ACTIV_CHECKED
Sets the bitmap displayed when the
check box is checked and enabled.
CHECKBOX_BI_INACTIV_3STATE
Sets the bitmap displayed when the
check box is in the third state and disabled.
CHECKBOX_BI_ACTIV_3STATE
Sets the bitmap displayed when the
check box is in the third state and
enabled.
Additional information
The image has to fill the complete inner area of the check box.
CHECKBOX_SetDefaultSpacing()
Description
Sets the default spacing between box and text used to display the check box text of
new check box widgets.
Prototype
void CHECKBOX_SetDefaultSpacing(int Spacing);
Parameter
Spacing
Description
Number of pixels between box and text used for new check box widgets.
Additional information
For more information, refer to “CHECKBOX_SetSpacing()” on page 383.
CHECKBOX_SetDefaultTextAlign()
Description
Sets the default alignment used to display the check box text of new check box widgets.
Prototype
void CHECKBOX_SetDefaultTextAlign(int Align);
Parameter
Align
Description
Text alignment used to display the text of new check box widgets.
Additional information
For more information, refer to “CHECKBOX_SetTextAlign()” on page 384.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
381
CHECKBOX_SetDefaultTextColor()
Description
Sets the default text color used to display the check box text of new check box widgets.
Prototype
void CHECKBOX_SetDefaultTextColor(GUI_COLOR Color);
Parameter
Color
Description
Color to be used.
Additional information
For more information, refer to “CHECKBOX_SetTextColor()” on page 384.
CHECKBOX_SetFocusColor()
Before
After
Description
Sets the color used to render the focus rectangle.
Prototype
GUI_COLOR CHECKBOX_SetFocusColor(CHECKBOX_Handle hObj, GUI_COLOR Color);
Parameter
hObj
Description
Handle of widget.
Return value
Previous color of the focus rectangle.
Additional information
The focus rectangle is only visible if the widget has the input focus.
CHECKBOX_SetFont()
Description
Sets the checkbox font.
Prototype
void CHECKBOX_SetFont(CHECKBOX_Handle
hObj,
const GUI_FONT GUI_UNI_PTR * pFont);
Parameter
hObj
pFont
Description
Handle of checkbox.
Pointer to the font.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
382
CHAPTER
Window Objects (Widgets)
CHECKBOX_SetImage()
Before
After
Description
Sets the images to be shown if the check box has been checked.
Prototype
void CHECKBOX_SetImage(CHECKBOX_Handle
hObj,
const GUI_BITMAP * pBitmap,
unsigned int
Index);
Parameter
hObj
pBitmap
Index
Description
Handle of check box.
Pointer to bitmap.
(see table shown under
CHECKBOX_SetDefaultImage )
Additional information
The image has to fill the complete inner area of the check box. If using this function
make sure, the size of the check box used to create the widget is large enough to
show the bitmap and (optional) the text.
CHECKBOX_SetNumStates()
Description
This function sets the number of possible states of the given check box.
Prototype
void CHECKBOX_SetNumStates(CHECKBOX_Handle hObj, unsigned NumStates);
Parameter
Description
hObj
Handle of widget.
NumStates
Number of possible states of the given check box. Currently supported are 2 or 3
states.
Additional information
Per default a check box supports 2 states: checked (1) and unchecked (0). If the
check box should support a third state the number of possible states can be
increased to 3.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
383
CHECKBOX_SetSpacing()
Before
After
Description
Sets the number of pixels between box and text of a given check box widget.
Prototype
void CHECKBOX_SetSpacing(CHECKBOX_Handle hObj, unsigned Spacing);
Parameter
hObj
Spacing
Description
Handle of widget.
Number of pixels between box and text to be used.
Additional information
The default spacing is 4 pixels. The function CHECKBOX_SetDefaultSpacing() or the
configuration macro CHECKBOX_SPACING_DEFAULT can be used to set the default
value.
CHECKBOX_SetState()
Before
After
Description
Sets the new state of the given check box widget.
Prototype
void CHECKBOX_SetState(CHECKBOX_Handle hObj, unsigned State);
Parameter
hObj
State
Description
Handle of widget.
Zero based number of new state.
Permitted values for parameter State
0
1
2
Unchecked
Checked
Third state
Additional information
The passed state should not be greater than the number of possible states set with
CHECKBOX_SetNumStates() minus 1.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
384
CHAPTER
Window Objects (Widgets)
CHECKBOX_SetText()
Before
After
Description
Sets the optional text shown beside the box.
Prototype
void CHECKBOX_SetText(CHECKBOX_Handle hObj, const char * pText);
Parameter
hObj
pText
Description
Handle of widget.
Pointer to text to be shown beside the box.
Additional information
Clicking on the text beside the box has the same effect as clicking into the box.
CHECKBOX_SetTextAlign()
Before
After
Description
Sets the alignment used to display the check box text beside the box.
Prototype
void CHECKBOX_SetTextAlign(CHECKBOX_Handle hObj, int Align);
Parameter
hObj
Align
Description
Handle of widget.
Desired text alignment.
Additional information
Per default the text alignment is GUI_TA_LEFT | GUI_TA_VCENTER. The function
CHECKBOX_SetDefaultTextAlign()
and
the
configuration
macro
CHECKBOX_TEXTALIGN_DEFAULT can be used to set a user defined default value.
CHECKBOX_SetTextColor()
Before
After
Description
Sets the color used to display the check box text.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
385
Prototype
void CHECKBOX_SetTextColor(CHECKBOX_Handle hObj, GUI_COLOR Color);
Parameter
hObj
Color
Description
Handle of widget.
Desired color of check box text.
Additional information
Per default the text color of a check box text is GUI_BLACK. The function
CHECKBOX_SetDefaultTextColor()
and
the
configuration
macro
CHECKBOX_TEXTCOLOR_DEFAULT can be used to set a user defined default color.
CHECKBOX_SetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_SetUserData().
CHECKBOX_Uncheck()
(Obsolete, CHECKBOX_SetState() should be used instead)
Before
After
Description
Sets the state of a specified check box unchecked.
Prototype
void CHECKBOX_Uncheck(CHECKBOX_Handle hObj);
Parameter
hObj
Description
Handle of check box.
Additional information
This is the default setting for check boxes.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
386
CHAPTER
Window Objects (Widgets)
17.5.5 Example
The Sample folder contains the following example which shows how the widget can be
used:
•
WIDGET_Checkbox.c
Note that several other examples also make use of this widget and may also be helpful to get familiar with the widget.
Screenshot of WIDGET_Checkbox.c:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
387
17.6 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.
Skinning...
...is available for this widget. The screenshot above shows the widget using the
default skin. For details please refer to chapter ’Skinning’.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
388
CHAPTER
Window Objects (Widgets)
17.6.1 Configuration options
Type
Macro
Default
Description
Text alignment used to display the dropdown text in closed state.
N
DROPDOWN_ALIGN_DEFAULT
GUI_TA_LEFT
S
DROPDOWN_FONT_DEFAULT
DROPDOWN_BKCOLOR0_DEFAULT
&GUI_Font13_1
Default font
N
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
DROPDOWN_TEXTCOLOR1_DEFAULT GUI_BLACK
DROPDOWN_TEXTCOLOR2_DEFAULT GUI_WHITE
N
N
Text color, unselected state.
Text color, selected state without focus.
Enable 3D support.
17.6.2 Notification codes
The following events are sent from the widget to its parent window as part of a
WM_NOTIFY_PARENT message:
Message
Description
WM_NOTIFICATION_CLICKED
WM_NOTIFICATION_RELEASED
Widget has been clicked.
Widget has been released.
WM_NOTIFICATION_MOVED_OUT
Widget has been clicked and pointer has been moved out
off of the widget without releasing.
WM_NOTIFICATION_SCROLL_CHANGED
The scroll position of the optional scrollbar of the opened
dropdown widget has been changed.
WM_NOTIFICATION_SEL_CHANGED
The selection of the dropdown list has been changed.
17.6.3 Keyboard reaction
The widget reacts to the following keys if it has the input focus:
Key
Reaction
Selects an item from the open dropdown list and closes the list.
GUI_KEY_ENTER
GUI_KEY_SPACE
Opens the dropdown list.
17.6.4 DROPDOWN API
The table below lists the available emWin DROPDOWN-related routines in alphabetical order. Detailed descriptions of the routines follow.
Routine
DROPDOWN_AddString()
DROPDOWN_Collapse()
DROPDOWN_Create()
DROPDOWN_CreateEx()
Description
Adds an element to the DROPDOWN list.
Closes the dropdown list.
Creates a DROPDOWN widget. (Obsolete)
Creates a DROPDOWN widget.
DROPDOWN_CreateIndirect()
Creates a DROPDOWN widget from a resource table
entry.
DROPDOWN_CreateUser()
Creates a DROPDOWN widget using extra bytes as
user data.
DROPDOWN_DecSel()
DROPDOWN_DecSelExp()
User's & reference manual for emWin V5.10
Decrements selection.
Decrements selection in expanded state.
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
389
Routine
DROPROWN_DeleteItem()
DROPDOWN_Expand()
Description
Deletes an item of the DROPDOWN list.
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_GetListbox()
Returns the handle of the attached LISTBOX in
expanded state.
DROPDOWN_GetNumItems()
Returns the number of items in the dropdown list.
DROPDOWN_GetSel()
Returns the number of the currently selected element.
DROPDOWN_GetSelExp()
Returns the number of the currently selected element in expanded state.
DROPDOWN_GetUserData()
Retrieves the data set with
DROPDOWN_SetUserData().
DROPDOWN_IncSel()
DROPDOWN_IncSelExp()
DROPDOWN_InsertString()
Increments selection.
Increments selection in expanded state.
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
DROPDOWN widget.
DROPDOWN_SetDefaultColor()
Sets the default color for arrow and button of
DROPDOWN widgets.
DROPDOWN_SetDefaultFont()
Sets the default font for DROPDOWN widgets.
DROPDOWN_SetDefaultScrollbarColor()
Sets the default colors of the optional scrollbar in
the dropdown list.
DROPDOWN_SetFont()
DROPDOWN_SetItemDisabled()
DROPDOWN_SetItemSpacing()
DROPDOWN_SetScrollbarColor()
DROPDOWN_SetSel()
DROPDOWN_SetSelExp()
Sets the font of the given DROPDOWN widget
Sets the state of the given item.
Sets the spacing between the items of the dropdown list.
Sets the colors of the scrollbar in the dropdown list.
Sets the current selection.
Sets the current selection in expanded state.
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.
DROPDOWN_SetUserData()
Sets the extra data of a DROPDOWN widget.
DROPDOWN_AddString()
Description
Adds a new element to the dropdown list.
Prototype
void DROPDOWN_AddString(DROPDOWN_Handle hObj, const char * s);
Parameter
hObj
s
Description
Handle of widget
Pointer to string to be added
DROPDOWN_Collapse()
Description
Closes the dropdown list of the DROPDOWN widget.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
390
CHAPTER
Window Objects (Widgets)
Prototype
void DROPDOWN_Collapse(DROPDOWN_Handle hObj);
Parameter
hObj
Description
Handle of widget
DROPDOWN_Create()
(Obsolete, DROPDOWN_CreateEx() should be used instead)
Description
Creates a DROPDOWN widget of a specified size at a specified location.
Prototype
DROPDOWN_Handle DROPDOWN_Create(WM_HWIN
int
int
int
Parameter
hWinParent
x0
y0
xsize
ysize
Flags
hWinParent,
x0,
int y0,
xsize,
int ysize,
Flags);
Description
Handle of parent window
Leftmost pixel of the DROPDOWN widget (in parent coordinates).
Topmost pixel of the DROPDOWN widget (in parent coordinates).
Horizontal size of the DROPDOWN widget (in pixels).
Vertical size of the DROPDOWN widget in open state (in pixels).
Window create flags. Typically,
WM_CF_SHOW to make the widget visible immediately
(refer to “WM_CreateWindow()” on page 309 for a list of available parameter values).
Return value
Handle of the created DROPDOWN widget; 0 if the function fails.
Additional information
The ysize of the widget in closed state depends on the font used to create the widget.
You can not set the ysize of a closed DROPDOWN widget.
DROPDOWN_CreateEx()
Description
Creates a DROPDOWN widget of a specified size at a specified location.
Prototype
DROPDOWN_Handle DROPDOWN_CreateEx(int
int
WM_HWIN
int
Parameter
x0
y0
xsize
ysize
hParent
x0,
xsize,
hParent,
ExFlags,
int
int
int
int
y0,
ysize,
WinFlags,
Id);
Description
Leftmost pixel of the widget (in parent coordinates).
Topmost pixel of the widget (in parent coordinates).
Horizontal size of the widget (in pixels).
Vertical size of the widget in open state (in pixels).
Handle of parent window. If 0, the new DROPDOWN widget will be a child of the
desktop (top-level window).
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
391
Parameter
Description
Window create flags. Typically
WM_CF_SHOW in order to make the widget visible
WinFlags
immediately (refer to WM_CreateWindow() in the chapter “The Window Manager
(WM)” on page 289 for a list of available parameter values).
ExFlags
Id
(see table below)
Window ID of the widget.
Permitted values for parameter ExFlags
0
No function.
DROPDOWN_CF_AUTOSCROLLBAR
Enable automatic use of a scrollbar. For
details, refer to
“DROPDOWN_SetAutoScroll()” on page 394.
DROPDOWN_CF_UP
Creates a DROPDOWN widget which opens
the dropdown list above the widget. This flag
is useful if the space below the widget is not
sufficient for the dropdown list.
Return value
Handle of the created DROPDOWN widget; 0 if the function fails.
DROPDOWN_CreateIndirect()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateIndirect().
DROPDOWN_CreateUser()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateUser(). For
a detailed description of the parameters the function DROPDOWN_CreateEx() can be
referred to.
DROPDOWN_DecSel()
Description
Decrement the selection, moves the selection of a specified DROPDOWN widget up by one
item.
Prototype
void DROPDOWN_DecSel(DROPDOWN_Handle hObj);
Parameter
hObj
Description
Handle of widget
DROPDOWN_DecSelExp()
Description
Decrements the selection of the attached LISTBOX in expanded state.
Prototype
void DROPDOWN_DecSelExp(DROPDOWN_Handle hObj);
Parameter
hObj
Description
Handle of widget
DROPDOWN_DeleteItem()
Description
Deletes the given item of the dropdown list.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
392
CHAPTER
Window Objects (Widgets)
Prototype
void DROPDOWN_DeleteItem(DROPDOWN_Handle hObj, unsigned int Index);
Parameter
hObj
Index
Description
Handle of widget.
Zero based index of the item to be deleted.
Additional information
If the index is greater than the number of items < 1 the function returns immediately.
DROPDOWN_Expand()
Description
Opens the dropdown list of the widget.
Prototype
void DROPDOWN_Expand(DROPDOWN_Handle hObj);
Parameter
hObj
Description
Handle of widget.
Additional information
The dropdown list remains open until an element has been selected or the focus has
been lost.
DROPDOWN_GetItemDisabled()
Description
Returns the state of the given item.
Prototype
unsigned DROPDOWN_GetItemDisabled(DROPDOWN_Handle hObj, unsigned Index);
Parameter
hObj
Index
Description
Handle of widget
Zero-based index of the item.
Return value
1 if the given item is disabled, 0 if not.
DROPDOWN_GetListbox()
Description
Returns the handle of the attached LISTBOX widget in expanded state.
Prototype
LISTBOX_Handle DROPDOWN_GetListbox(DROPDOWN_Handle hObj);
Parameter
hObj
Description
Handle of widget
Return value
Handle of the attached LISTBOX widget in expanded state, 0 if DROPDOWN is in collapsed
state.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
393
DROPDOWN_GetNumItems()
Description
Returns the number of items in the given DROPDOWN widget.
Prototype
int DROPDOWN_GetNumItems(DROPDOWN_Handle hObj);
Parameter
hObj
Description
Handle of widget
Return value
Number of items in the given DROPDOWN widget.
DROPDOWN_GetSel()
Description
Returns the number of the currently selected item in a specified DROPDOWN widget.
Prototype
int DROPDOWN_GetSel(DROPDOWN_Handle hObj);
Parameter
hObj
Description
Handle of widget
Return value
Number of the currently selected item.
DROPDOWN_GetSelExp()
Description
Returns the number of the currently selected item of the attached LISTBOX in expanded
state.
Prototype
int DROPDOWN_GetSelExp(DROPDOWN_Handle hObj);
Parameter
hObj
Description
Handle of widget
Return value
Number of the currently selected item.
DROPDOWN_GetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_GetUserData().
DROPDOWN_IncSel()
Description
Increment the selection, moves the selection of a specified DROPDOWN widget down by
one item.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
394
CHAPTER
Window Objects (Widgets)
Prototype
void DROPDOWN_IncSel(DROPDOWN_Handle hObj);
Parameter
hObj
Description
Handle of widget
DROPDOWN_IncSelExp()
Description
Increments the selection of the attached LISTBOX in expanded state.
Prototype
void DROPDOWN_IncSelExp(DROPDOWN_Handle hObj);
Parameter
hObj
Description
Handle of widget
DROPDOWN_InsertString()
Description
Inserts a string to the dropdown list at the given position.
Prototype
void DROPDOWN_InsertString(DROPDOWN_Handle
hObj,
const char
* s,
unsigned int
Index);
Parameter
hObj
s
Index
Description
Handle of widget.
Pointer to the string to be inserted.
Zero based index of the position.
Additional information
If the given index is greater than the number of items the string will be appended to
the end of the dropdown list.
DROPDOWN_SetAutoScroll()
Description
Enables the automatic use of a vertical scrollbar in the dropdown list.
Prototype
void DROPDOWN_SetAutoScroll(DROPDOWN_Handle hObj, int OnOff);
Parameter
hObj
OnOff
Description
Handle of widget.
(see table below)
Permitted values for parameter OnOff
0
1
Disable automatic use of a scrollbar.
Enable automatic use of a scrollbar.
Additional information
If enabled the dropdown list checks if all elements fits into the listbox. If not a vertical scrollbar will be added.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
395
DROPDOWN_SetBkColor()
Before
After
Description
Sets the background color of the given DROPDOWN widget.
Prototype
void DROPDOWN_SetBkColor(DROPDOWN_Handle hObj,
unsigned int
Index,
GUI_COLOR
Color);
Parameter
hObj
Index
Color
Description
Handle of widget
Index for background color (see table below).
Color to be set.
Permitted values for parameter Index
DROPDOWN_CI_UNSEL
DROPDOWN_CI_SEL
DROPDOWN_CI_SELFOCUS
Unselected element.
Selected element, without focus.
Selected element, with focus.
DROPDOWN_SetColor()
Before
After
Description
Sets the color of the button or the arrow of the given DROPDOWN widget.
Prototype
void DROPDOWN_SetColor(DROPDOWN_Handle hObj,
unsigned int
Index,
GUI_COLOR
Color);
Parameter
hObj
Index
Color
Description
Handle of widget
Index of desired item (see table below).
Color to be used.
Permitted values for parameter Index
DROPDOWN_CI_ARROW
DROPDOWN_CI_BUTTON
User's & reference manual for emWin V5.10
Color of small arrow within the button.
Button color.
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
396
CHAPTER
Window Objects (Widgets)
DROPDOWN_SetDefaultColor()
Description
Sets the default colors for the arrow and the button of new DROPDOWN widgets.
Prototype
GUI_COLOR DROPDOWN_SetDefaultColor(int Index, GUI_COLOR Color);
Parameter
Index
Color
Description
Refer to “DROPDOWN_SetColor()” on page 395.
Color to be used.
DROPDOWN_SetDefaultFont()
Description
Sets the default font used for new DROPDOWN widgets.
Prototype
void DROPDOWN_SetDefaultFont(const GUI_FONT * pFont);
Parameter
pFont
Description
Pointer to
GUI_FONT structure.
DROPDOWN_SetDefaultScrollbarColor()
Description
Sets the default colors used for the optional scrollbar in the dropdown list.
Prototype
GUI_COLOR DROPDOWN_SetDefaultScrollbarColor(int Index, GUI_COLOR Color);
Parameter
Index
Color
Description
Refer to “DROPDOWN_SetScrollbarColor()” on page 397.
Color to be used.
DROPDOWN_SetFont()
Description
Sets the font used to display the given DROPDOWN widget.
Prototype
void DROPDOWN_SetFont(DROPDOWN_Handle hObj, const GUI_FONT * pFont);
Parameter
hObj
pFont
Description
Handle of widget
Pointer to the font.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
397
DROPDOWN_SetItemDisabled()
Before
After
Description
Sets the enabled state of the given item.
Prototype
void DROPDOWN_SetItemDisabled(DROPDOWN_Handle hObj,
unsigned
Index,
int
OnOff);
Parameter
hObj
Index
OnOff
Description
Handle of widget
Zero-based index of the item.
1 for enabled, 0 for disabled.
DROPDOWN_SetScrollbarColor()
Before
After
Description
Sets the colors of the optional scrollbar in the dropdown list.
Prototype
void DROPDOWN_SetScrollbarColor(DROPDOWN_Handle hObj,
unsigned int
Index,
GUI_COLOR
Color);
Parameter
hObj
Index
Color
Description
Handle of widget
Index of desired item (see table below).
Color to be used.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
398
CHAPTER
Window Objects (Widgets)
Permitted values for parameter Index
SCROLLBAR_CI_THUMB Color of thumb area.
SCROLLBAR_CI_SHAFT Color of shaft.
SCROLLBAR_CI_ARROW Color of arrows.
DROPDOWN_SetScrollbarWidth()
Description
Sets the width of the scrollbars used by the dropdown list of the given DROPDOWN
widget.
Prototype
void DROPDOWN_SetScrollbarWidth(DROPDOWN_Handle hObj, unsigned Width);
Parameter
hObj
Width
Description
Handle of widget.
Width of the scrollbar(s) used by the dropdown list of the given DROPDOWN widget.
DROPDOWN_SetSel()
Description
Sets the selected item of a specified DROPDOWN widget.
Prototype
void DROPDOWN_SetSel(DROPDOWN_Handle hObj, int Sel);
Parameter
hObj
Sel
Description
Handle of widget
Element to be selected.
DROPDOWN_SetSelExp()
Description
Sets the selected item of the attached LISTBOX in expanded state.
Prototype
void DROPDOWN_SetSelExp(DROPDOWN_Handle hObj, int Sel);
Parameter
hObj
Sel
Description
Handle of widget
Element to be selected.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
399
DROPDOWN_SetItemSpacing()
Before
After
Description
Sets an additional spacing below the items of the dropdown list.
Prototype
void DROPDOWN_SetItemSpacing(DROPDOWN_Handle hObj, unsigned Value);
Parameter
hObj
Value
Description
Handle of widget
Number of pixels used as additional space between the items of the dropdown list.
DROPDOWN_SetTextAlign()
Before
After
Description
Sets the alignment used to display the dropdown text in closed state.
Prototype
void DROPDOWN_SetTextAlign(DROPDOWN_Handle hObj, int Align);
Parameter
hObj
Align
Description
Handle of widget
Alignment used to display the dropdown text in closed state.
DROPDOWN_SetTextColor()
Description
Sets the background color of the given DROPDOWN widget.
Prototype
void DROPDOWN_SetTextColor(DROPDOWN_Handle hObj,
unsigned int
Index,
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
400
CHAPTER
GUI_COLOR
Parameter
hObj
Index
Color
Window Objects (Widgets)
Color);
Description
Handle of widget
Index for background color (see table below).
Color to be set.
Permitted values for parameter Index
DROPDOWN_CI_UNSEL
DROPDOWN_CI_SEL
DROPDOWN_CI_SELFOCUS
Unselected element.
Selected element, without focus.
Selected element, with focus.
DROPDOWN_SetTextHeight()
Before
After
Description
Sets the height of the rectangle used to display the DROPDOWN text in closed state.
Prototype
void DROPDOWN_SetTextHeight(DROPDOWN_Handle hObj, unsigned TextHeight);
Parameter
hObj
TextHeight
Description
Handle of widget
Height of the rectangle used to display the text in closed state.
Additional information
Per default the height of the DROPDOWN widget depends on the used font. Using this
function with TextHeight > 0 means the given value should be used. Text Height = 0
means the default behavior should be used.
DROPDOWN_SetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_SetUserData().
17.6.5 Example
The Sample folder contains the following example which shows how the widget can be
used:
•
WIDGET_Dropdown.c
Note that several other examples also make use of this widget and may also be helpful to get familiar with the widget.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
401
Screenshot of WIDGET_Dropdown.c:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
402
CHAPTER
Window Objects (Widgets)
17.7 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
All EDIT-related routines are located in the file(s) EDIT*.c, EDIT.h. All identifiers are
prefixed EDIT.
17.7.1 Configuration options
Type
Macro
Default
Description
GUI_TA_RIGHT |
Alignment for edit field text.
GUI_TA_VCENTER
S
EDIT_ALIGN_DEFAULT
N
0xc0c0c0
Background color, disabled state.
GUI_WHITE
Background color, enabled state.
N
EDIT_BKCOLOR0_DEFAULT
EDIT_BKCOLOR1_DEFAULT
EDIT_BORDER_DEFAULT
EDIT_FONT_DEFAULT
EDIT_TEXTCOLOR0_DEFAULT
EDIT_TEXTCOLOR1_DEFAULT
N
EDIT_XOFF
N
N
S
N
1
Width of border, in pixels.
&GUI_Font13_1
Font used for edit field text.
GUI_BLACK
Text color, disabled state.
GUI_BLACK
Text color, enabled state.
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.
17.7.2 Notification codes
The following events are sent from an edit widget to its parent window as part of a
WM_NOTIFY_PARENT message:
Message
WM_NOTIFICATION_CLICKED
WM_NOTIFICATION_RELEASED
Description
Widget has been clicked.
Widget has been released.
WM_NOTIFICATION_MOVED_OUT
Widget has been clicked and pointer has been moved out
off of the widget without releasing.
WM_NOTIFICATION_VALUE_CHANGED
Value (content) of the edit widget has changed.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
403
17.7.3 Keyboard reaction
The widget reacts to the following keys if it has the input focus:
Key
Reaction
GUI_KEY_UP
Increases the current character. If for example the current character
(the character below the cursor) is a ’A’ it changes to ’B’.
GUI_KEY_DOWN
Decreases the current character. If for example the current character is
a ’B’ it changes to ’A’.
GUI_KEY_RIGHT
GUI_KEY_LEFT
Moves the cursor one character to the right.
Moves the cursor one character to the left.
GUI_KEY_BACKSPACE
If the widget works in text mode, the character before the cursor is
deleted.
GUI_KEY_DELETE
If the widget works in text mode, the current is deleted.
GUI_KEY_INSERT
If the widget works in text mode, this key toggles the edit mode
between GUI_EDIT_MODE_OVERWRITE and
GUI_EDIT_MODE_INSERT. For details, refer to
“EDIT_SetInsertMode()” on page 413.
17.7.4 EDIT API
The table below lists the available emWin EDIT-related routines in alphabetical order.
Detailed descriptions of the routines follow.
Routine
EDIT_AddKey()
EDIT_Create()
EDIT_CreateAsChild()
EDIT_CreateEx()
EDIT_CreateIndirect()
EDIT_CreateUser()
EDIT_EnableBlink()
EDIT_GetCursorCharPos()
EDIT_GetCursorPixelPos()
EDIT_GetDefaultBkColor()
EDIT_GetDefaultFont()
EDIT_GetDefaultTextAlign()
EDIT_GetDefaultTextColor()
EDIT_GetFloatValue()
EDIT_GetNumChars()
EDIT_GetText()
EDIT_GetUserData()
EDIT_GetValue()
EDIT_SetBinMode()
EDIT_SetBkColor()
EDIT_SetCursorAtChar()
EDIT_SetCursorAtPixel()
EDIT_SetDecMode()
EDIT_SetDefaultBkColor()
EDIT_SetDefaultFont()
EDIT_SetDefaultTextAlign()
EDIT_SetDefaultTextColor()
EDIT_SetFloatMode()
EDIT_SetFloatValue()
EDIT_SetFont()
EDIT_SetHexMode()
User's & reference manual for emWin V5.10
Description
Key input routine.
Creates an EDIT widget. (Obsolete)
Creates an EDIT widget as a child window. (Obsolete)
Creates an EDIT widget.
Creates an EDIT widget from resource table entry.
Creates an EDIT widget using extra bytes as user data.
Enables/disables a blinking cursor
Returns the number of the character at the cursor position.
Returns the pixel position of the cursor.
Returns the default background color.
Returns the default font.
Returns the default text alignment.
Returns the default text color.
Returns the current value as floating point value.
Returns the number of characters of the given edit widget.
Get user input.
Retrieves the data set with EDIT_SetUserData().
Returns the current value.
Enables the binary edit mode.
Sets the background color of the edit field.
Sets the edit widget cursor to a specified character position.
Sets the edit widget cursor to a specified pixel position.
Enables the decimal edit mode.
Sets the default background color.
Sets the default font used for edit fields.
Sets the default text alignment for edit fields.
Sets the default text color.
Enables the floating point edit mode.
Sets the floating point value if using the floating point edit mode.
Select the font for the text.
Enables the hexadecimal edit mode.
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
404
CHAPTER
Window Objects (Widgets)
Routine
EDIT_SetInsertMode()
EDIT_SetMaxLen()
EDIT_SetpfAddKeyEx()
EDIT_SetSel()
EDIT_SetText()
EDIT_SetTextAlign()
EDIT_SetTextColor()
EDIT_SetTextMode()
EDIT_SetValue()
EDIT_SetUlongMode()
EDIT_SetUserData()
GUI_EditBin()
GUI_EditDec()
GUI_EditHex()
GUI_EditString()
Description
Enables or disables the insert mode.
Sets the maximum number of characters of the edit field.
Sets a function which is called to add a character.
Sets the current selection.
Sets the text.
Sets the text alignment for the edit field.
Sets the color(s) for the text.
Sets the edit mode of the widget back to text mode.
Sets the current value.
Enables the unsigned long decimal edit mode.
Sets the extra data of an EDIT widget.
Edits a binary value at the current cursor position.
Edits a decimal value at the current cursor position.
Edits a hexadecimal value at the current cursor position.
Edits a string at the current cursor position.
EDIT_AddKey()
Description
Adds user input to a specified edit field.
Prototype
void EDIT_AddKey(EDIT_Handle hObj, int Key);
Parameter
hObj
Key
Description
Handle of edit field.
Character to be added.
Additional information
The specified character is added to the user input of the EDIT widget. If the last character should be erased, the key GUI_KEY_BACKSPACE can be used. If the maximum
count of characters has been reached, another character will not be added.
EDIT_Create()
(Obsolete, EDIT_CreateEx() should be used instead)
Description
Creates an EDIT widget of a specified size at a specified location.
Prototype
EDIT_Handle EDIT_Create(int x0, int y0,
int xsize, int ysize,
int Id, int MaxLen, int Flags);
Parameter
x0
y0
xsize
ysize
Id
MaxLen
Flags
Description
Leftmost pixel of the edit field (in parent coordinates).
Topmost pixel of the edit field (in parent coordinates).
Horizontal size of the edit field (in pixels).
Vertical size of the edit field (in pixels.
ID to be returned.
Maximum count of characters.
Window create flags. Typically WM_CF_SHOW in order to make the widget visible
immediately (refer to WM_CreateWindow() in the chapter “The Window Manager
(WM)” on page 289 for a list of available parameter values).
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
405
Return value
Handle of the created EDIT widget; 0 if the function fails.
EDIT_CreateAsChild()
(Obsolete, EDIT_CreateEx should be used instead)
Description
Creates an EDIT widget as a child window.
Prototype
EDIT_Handle EDIT_CreateAsChild(int
int
WM_HWIN
int
x0,
xsize,
hParent,
Flags,
Parameter
x0
y0
xsize
ysize
hParent
Id
Flags
MaxLen
int
int
int
int
y0,
ysize,
Id,
MaxLen);
Description
X-position of the edit field relative to the parent window.
Y-position of the edit field relative to the parent window.
Horizontal size of the edit field (in pixels).
Vertical size of the edit field (in pixels.
Handle of parent window.
ID to be returned.
Window create flags (see
EDIT_Create() ).
Maximum count of characters.
Return value
Handle of the created EDIT widget; 0 if the function fails.
EDIT_CreateEx()
Description
Creates a EDIT widget of a specified size at a specified location.
Prototype
EDIT_Handle EDIT_CreateEx(int
int
WM_HWIN
int
int
x0,
xsize,
hParent,
ExFlags,
MaxLen);
Parameter
x0
y0
xsize
ysize
int
int
int
int
y0,
ysize,
WinFlags,
Id,
Description
Leftmost pixel of the widget (in parent coordinates).
Topmost pixel of the widget (in parent coordinates).
Horizontal size of the widget (in pixels).
Vertical size of the widget (in pixels).
hParent
Handle of parent window. If 0, the new EDIT widget will be a child of the desktop
(top-level window).
WinFlags
Window create flags. Typically WM_CF_SHOW in order to make the widget visible
immediately (refer to WM_CreateWindow() in the chapter “The Window Manager
(WM)” on page 289 for a list of available parameter values).
ExFlags
Id
MaxLen
Not used, reserved for future use.
Window ID of the widget.
Maximum count of characters.
Return value
Handle of the created EDIT widget; 0 if the function fails.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
406
CHAPTER
Window Objects (Widgets)
EDIT_CreateIndirect()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateIndirect().
The following flags may be used as the Flags element of the resource passed as
parameter:
Permitted indirect creation flags ("OR" combinable)
EDIT_CF_LEFT
EDIT_CF_RIGHT
EDIT_CF_HCENTER
EDIT_CF_TOP
EDIT_CF_BOTTOM
EDIT_CF_VCENTER
Horizontal alignment: left
Horizontal alignment: right
Horizontal alignment: center
Vertical alignment: top
Vertical alignment: bottom
Vertical alignment: center
The Para element is used as maximum length of a string to display / max. no. of digits if used in decimal, bin or hex mode.
EDIT_CreateUser()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateUser(). For
a detailed description of the parameters the function EDIT_CreateEx() can be
referred to.
EDIT_EnableBlink()
Description
Enables/disables a blinking cursor.
Prototype
void EDIT_EnableBlink(EDIT_Handle hObj, int Period, int OnOff);
Parameter
hObj
Period
OnOff
Description
Handle of edit field.
Blinking period
1 enables blinking, 0 disables blinking
Additional information
This function calls GUI_X_GetTime().
EDIT_GetCursorCharPos()
Description
Returns the number of the character at the cursor position.
Prototype
int EDIT_GetCursorCharPos(EDIT_Handle hObj);
Parameter
hObj
Description
Handle of edit field.
Return value
Number of the character at the cursor position.
Additional information
The widget returns the character position if it has the focus or not. This means the
cursor position is also returned, if the cursor is currently not visible in the widget.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
407
EDIT_GetCursorPixelPos()
Description
Returns the pixel position of the cursor in window coordinates.
Prototype
void EDIT_GetCursorPixelPos(EDIT_Handle hObj, int * pxPos, int * pyPos);
Parameter
hObj
pxPos
pyPos
Description
Handle of edit field.
Pointer to integer variable for the X-position in window coordinates.
Pointer to integer variable for the Y-position in window coordinates.
Additional information
The widget returns the pixel position if it has the focus or not. This means the cursor
position is also returned, if the cursor is currently not visible in the widget.
EDIT_GetDefaultBkColor()
Description
Returns the default background color used for EDIT widgets.
Prototype
GUI_COLOR EDIT_GetDefaultBkColor(unsigned int Index);
Parameter
Index
Description
(see table below)
Permitted values for parameter Index
0
1
Color to be used when widget is inactive.
Color to be used when widget is active.
Return value
Default background color used for EDIT widgets.
EDIT_GetDefaultFont()
Description
Returns the default font used for EDIT widgets.
Prototype
const GUI_FONT* EDIT_GetDefaultFont(void);
Return value
Default font used for EDIT widgets.
EDIT_GetDefaultTextAlign()
Description
Returns the default text alignment used for EDIT widgets.
Prototype
int EDIT_GetDefaultTextAlign(void);
Return value
Default text alignment used for EDIT widgets.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
408
CHAPTER
Window Objects (Widgets)
EDIT_GetDefaultTextColor()
Description
Returns the default text color used for EDIT widgets.
Prototype
GUI_COLOR EDIT_GetDefaultTextColor(unsigned int Index);
Parameter
Index
Description
Has to be 0, reserved for future use.
Return value
Default text color used for EDIT widgets.
EDIT_GetFloatValue()
Description
Returns the current value of the edit field as floating point value.
Prototype
float EDIT_GetFloatValue(EDIT_Handle hObj);
Parameter
hObj
Description
Handle of edit field.
Return value
The current value.
Additional information
The use of this function makes only sense if the edit field is in floating point edit
mode.
EDIT_GetNumChars
Description
Returns the number of characters of the specified edit field.
Prototype
int EDIT_GetNumChars(EDIT_Handle hObj);
Parameter
hObj
Description
Handle of edit field.
Return value
Number of characters of the specified edit field.
EDIT_GetText()
Description
Retrieves the user input of a specified edit field.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
409
Prototype
void EDIT_GetText(EDIT_Handle hObj, char * sDest, int MaxLen);
Parameter
hObj
sDest
MaxLen
Description
Handle of edit field.
Pointer to buffer.
Size of buffer.
EDIT_GetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_GetUserData().
EDIT_GetValue()
Description
Returns the current value of the edit field. The current value is only useful if the edit
field is in binary, decimal or hexadecimal mode.
Prototype
I32
EDIT_GetValue(EDIT_Handle hObj);
Parameter
hObj
Description
Handle of edit field.
Return value
The current value.
EDIT_SetBinMode()
Description
Enables the binary edit mode of the edit field. The given value can be modified in the
given range.
Prototype
void EDIT_SetBinMode(EDIT_Handle hObj, U32 Value, U32 Min, U32 Max);
Parameter
hObj
Value
Min
Max
Description
Handle of edit field.
Value to be modified.
Minimum value.
Maximum value.
EDIT_SetBkColor()
Description
Sets the edit fields background color.
Prototype
void EDIT_SetBkColor(EDIT_Handle hObj, unsigned int Index, GUI_COLOR Color);
Parameter
hObj
Index
Color
Description
Handle of edit field.
Index for background color (see table below).
Color to be set.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
410
CHAPTER
Window Objects (Widgets)
Permitted values for parameter Index
EDIT_CI_DISABLED
EDIT_CI_ENABLED
Disabled state.
Enabled state.
EDIT_SetCursorAtChar()
Description
Sets the edit widget cursor to a specified character position.
Prototype
void EDIT_SetCursorAtChar(EDIT_Handle hObj, int xPos);
Parameter
hObj
xPos
Description
Handle of edit field.
Character position to set cursor to.
Additional information
The character position works as follows:
0: left of the first (leftmost) character,
1: between the first and second characters,
2: between the second and third characters,
and so on.
EDIT_SetCursorAtPixel()
Description
Sets the edit widget cursor to a specified pixel position.
Prototype
void EDIT_SetCursorAtPixel(EDIT_Handle hObj, int Pos);
Parameter
hObj
Pos
Description
Handle of edit field.
Pixel position to set cursor to.
EDIT_SetDecMode()
Description
Enables the decimal edit mode of the edit field. The given value can be modified in
the given range.
Prototype
void EDIT_SetDecMode(EDIT_Handle hEdit, I32 Value, I32 Min,
I32
Max,
int Shift, U8 Flags);
Parameter
hObj
Value
Min
Max
Shift
Flags
Description
Handle of edit field.
Value to be modified.
Minimum value.
Maximum value.
If > 0 it specifies the position of the decimal point.
See table below.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
411
Permitted values for parameter Flags ("OR" combinable)
0 (default)
Edit in normal mode, sign is only displayed if the value is
negative
GUI_EDIT_SIGNED "+" and "-" sign is displayed.
EDIT_SetDefaultBkColor()
Description
Sets the default background color used for edit widgets.
Prototype
void EDIT_SetDefaultBkColor(unsigned int Index, GUI_COLOR Color);
Parameter
Index
Color
Description
(see table below)
Color to be used.
Permitted values for parameter Index
0
1
Color to be used when widget is inactive.
Color to be used when widget is active.
EDIT_SetDefaultFont()
Description
Sets the default font used for edit fields.
Prototype
void EDIT_SetDefaultFont(const GUI_FONT * pFont);
Parameter
pFont
Description
Pointer to the font to be set as default.
EDIT_SetDefaultTextAlign()
Description
Sets the default text alignment for edit fields.
Prototype
void EDIT_SetDefaultTextAlign(int Align);
Parameter
Align
Description
Default text alignment. For details, refer to “EDIT_SetTextAlign()” on page 415.
EDIT_SetDefaultTextColor()
Description
Sets the default text color used for edit widgets.
Prototype
void EDIT_SetDefaultTextColor(unsigned int Index, GUI_COLOR Color);
Parameter
Index
Color
Description
Has to be 0, reserved for future use.
Color to be used.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
412
CHAPTER
Window Objects (Widgets)
EDIT_SetFloatMode()
Description
Enables the floating point edit mode of the edit field. The given value can be modified
in the given range.
Prototype
void
EDIT_SetFloatMode(EDIT_Handle hObj, float Value, float Min,
float
Max, int
Shift, U8
Flags);
Parameter
hObj
Value
Min
Max
Shift
Flags
Description
Handle of edit field.
Value to be modified.
Minimum value.
Maximum value.
Number of post decimal positions.
See table below.
Permitted values for parameter Flags ("OR" combinable)
Edit in normal mode, sign is only
displayed if the value is negative
0 (default)
GUI_EDIT_SIGNED
GUI_EDIT_SUPPRESS_LEADING_ZEROES
"+" and "-" sign is displayed.
Does not show leading zeroes.
EDIT_SetFloatValue()
Description
The function can be used to set the floating point value of the edit field if working in
floating point mode.
Prototype
void EDIT_SetFloatValue(EDIT_Handle hObj, float Value);
Parameter
hObj
Value
Description
Handle of edit field.
New floating point value of the edit field.
Additional information
The use of this function makes only sense if the edit field works in floating point
mode. If working in text mode the function has no effect. If working in binary, decimal or hexadecimal mode the behavior of the edit field is undefined.
EDIT_SetFont()
Description
Sets the edit field font.
Prototype
void EDIT_SetFont(EDIT_Handle hObj, const GUI_FONT * pFont);
Parameter
hObj
pFont
Description
Handle of edit field.
Pointer to the font.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
413
EDIT_SetHexMode()
Description
Enables the hexadecimal edit mode of the edit field. The given value can be modified
in the given range.
Prototype
void EDIT_SetHexMode(EDIT_Handle hObj, U32 Value, U32 Min, U32 Max);
Parameter
hObj
Value
Min
Max
Description
Handle of edit field.
Value to be modified.
Minimum value.
Maximum value.
EDIT_SetInsertMode()
Description
Enables or disables the insert mode of the edit widget.
Prototype
int EDIT_SetInsertMode(EDIT_Handle hObj, int OnOff);
Parameter
hObj
OnOff
Description
Handle of edit field.
See table below.
Permitted values for parameter OnOff
0
1
Disable insert mode.
Enable insert mode.
Return value
Returns the previous insert mode state.
Additional information
The use of this function makes only sense if the edit widget operates in text mode or
in any user defined mode. If working in hexadecimal, binary, floating point or decimal
mode the use of this function has no effect except that it changes the appearance of
the cursor.
EDIT_SetMaxLen()
Description
Sets the maximum number of characters to be edited by the given edit field.
Prototype
void EDIT_SetMaxLen(EDIT_Handle hObj, int MaxLen);
Parameter
hObj
MaxLen
Description
Handle of edit field.
Number of characters.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
414
CHAPTER
Window Objects (Widgets)
EDIT_SetpfAddKeyEx()
Description
Sets the function pointer which is used by the EDIT widget to call the function which
is responsible for adding characters.
Prototype
void EDIT_SetpfAddKeyEx(EDIT_Handle hObj, tEDIT_AddKeyEx * pfAddKeyEx);
Parameter
hObj
pfAddKeyEx
Description
Handle of edit field.
Function pointer to the function to be used to add a character.
Additional information
If working in text mode (default) or one of the modes for editing values, the edit widget uses its own routines to add a character. The use of this function only makes
sense if the default behavior of the edit widget needs to be changed. If a function
pointer has been set with this function the application program is responsible for the
contents of the text buffer.
EDIT_SetSel()
Before
After
Description
Used to set the current selection of the edit field.
Prototype
void EDIT_SetSel(EDIT_Handle hObj, int FirstChar, int LastChar);
Parameter
Description
hObj
Handle of edit field.
FirstChar
Zero based index of the first character to be selected. -1 if no character should be
selected.
LastChar
Zero based index of the last character to be selected. -1 if all characters from the first
character until the last character should be selected.
Additional information
Selected characters are usually displayed in reverse. Setting the cursor position
deselects all characters.
Example
EDIT_SetSel(0, -1) /* Selects all characters of the widget */
EDIT_SetSel(-1, 0) /* Deselect all characters */
EDIT_SetSel(0, 2) /* Selects the first 3 characters */
EDIT_SetText()
Description
Sets the text to be displayed in the edit field.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
415
Prototype
void EDIT_SetText(EDIT_Handle hObj, const char* s)
Parameter
hObj
s
Description
Handle of edit field.
Text to display.
EDIT_SetTextAlign()
Description
Sets the text alignment of the edit field.
Prototype
void EDIT_SetTextAlign(EDIT_Handle hObj, int Align);
Parameter
hObj
Align
Description
Handle of edit field.
Text alignment to be set (see “GUI_SetTextAlign()” on page 82)
EDIT_SetTextColor()
Description
Sets the edit fields text color.
Prototype
void EDIT_SetTextColor(EDIT_Handle hObj,
unsigned int Index,
GUI_COLOR
Color);
Parameter
hObj
Index
Color
Description
Handle of edit field.
Index for text color (see table below).
Color to be set.
Permitted values for parameter OnOff
EDIT_CI_DISABLED
EDIT_CI_ENABLED
Sets the text color for disabled state.
Sets the text color for enabled state.
EDIT_SetTextMode()
Description
Sets the edit mode of the widget back to text mode.
Prototype
void EDIT_SetTextMode(EDIT_Handle hEdit);
Parameter
hObj
Description
Handle of widget.
Additional information
If
one
of
the
functions
EDIT_SetBinMode(),
EDIT_SetDecMode(),
EDIT_SetFloatMode() or EDIT_SetHexMode() has been used to set the edit field to
one of the numeric edit modes, this function sets the edit mode back to text mode. It
also clears the contents of the widget.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
416
CHAPTER
Window Objects (Widgets)
EDIT_SetUlongMode()
Description
Enables the unsigned long decimal edit mode of the edit field. The given value can be
modified in the given range.
Prototype
void EDIT_SetUlongMode(EDIT_Handle hEdit, U32 Value, U32 Min, U32 Max);
Parameter
hObj
Value
Min
Max
Description
Handle of edit field.
Value to be modified.
Minimum value.
Maximum value.
EDIT_SetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_SetUserData().
EDIT_SetValue()
Description
Sets the current value of the edit field. Only useful if binary, decimal or hexadecimal
edit mode is set.
Prototype
void EDIT_SetValue(EDIT_Handle hObj, I32 Value);
Parameter
hObj
Value
Description
Handle of edit field.
New value.
GUI_EditBin()
Description
Edits a binary value at the current cursor position.
Prototype
U32 GUI_EditBin(U32 Value, U32 Min, U32 Max, int Len, int xsize);
Parameter
Value
Min
Max
Len
xsize
Description
Value to be modified.
Minimum value.
Maximum value.
Number of digits to edit.
Pixel-size in X of the edit field.
Return value
The new value will be returned if <ENTER> is pressed. If <ESC> is pressed, the old
value is returned.
Additional information
The routine returns after pressing <ENTER> or <ESC>. The contents of the given
text will be modified only if <ENTER> is pressed.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
417
GUI_EditDec()
Description
Edits a decimal value at the current cursor position.
Prototype
U32 GUI_EditDec(I32 Value, I32 Min, I32 Max, int Len, int xsize,
int Shift, U8 Flags);
Parameter
Value
Min
Max
Len
xsize
Shift
Flags
Description
Value to be modified.
Minimum value.
Maximum value.
Number of digits to edit.
Pixel-size in X of edit field.
If > 0 it specifies the position of the decimal point.
See
EDIT_SetDecMode() .
Return value
The new value will be returned if <ENTER> is pressed. If <ESC> is pressed, the old
value is returned.
Additional information
The routine returns after pressing <ENTER> or <ESC>. The contents of the given
text will be modified only if <ENTER> is pressed.
GUI_EditHex()
Description
Edits a hexadecimal value at the current cursor position.
Prototype
U32 GUI_EditHex(U32 Value, U32 Min, U32 Max, int Len, int xsize);
Parameter
Value
Min
Max
Len
xsize
Description
Value to be modified.
Minimum value.
Maximum value.
Number of digits to edit.
Pixel-size in X of the edit field.
Return value
The new value will be returned if <ENTER> is pressed. If <ESC> is pressed, the old
value is returned.
Additional information
The routine returns after pressing <ENTER> or <ESC>. The contents of the given
text will be modified only if <ENTER> is pressed.
GUI_EditString()
Description
Edits a string at the current cursor position.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
418
CHAPTER
Window Objects (Widgets)
Prototype
void GUI_EditString(char * pString, int Len, int xsize);
Parameter
pString
Len
xsize
Description
Pointer to the string to be edited.
Maximum number of characters.
Pixel-size in X of the edit field.
Additional information
The routine returns after pressing <ENTER> or <ESC>. The contents of the given
text will be modified only if <ENTER> is pressed.
17.7.5 Examples
The Sample folder contains the following examples which show how the widget can be
used:
•
WIDGET_Edit.c
•
WIDGET_EditWinmode.c
Note that several other examples also make use of this widget and may also be helpful to get familiar with the widget.
Screen shot of WIDGET_Edit.c:
Screen shot of WIDGET_EditWinmode.c:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
419
17.8 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
You can attach predefined buttons to the title bar as seen below or you can attach
your own buttons to a title bar:
Description
Frame window
Frame window with minimize-, maximize- and
close button.
Frame window with minimize-, maximize- and
close button in maximized state.
Frame window with minimize-, maximize- and
close button in minimized state
Skinning...
...is available for this widget. The screenshot above shows the widget using the
default skin. For details please refer to chapter ’Skinning’.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
420
CHAPTER
Window Objects (Widgets)
17.8.1 Structure of the frame window
The following diagram shows the detailed structure and looks of a frame window:
x-size of frame window
x-size of client window
B
H
B
B
y-size of client window
Client window
B
y-size of frame window
D
Title bar
The frame window actually consists of 2 windows; the main window and a child window. The child window is called Client window. It is important to be aware of this
when dealing with callback functions: There are 2 windows with 2 different callback
functions. When creating child windows, these child windows are typically created as
children of the client window; their parent is therefor the client window.
Detail
B
H
D
Title bar
Client window
Description
Border size of the frame window. The default size of the border is 3 pixels.
Height of the title bar. Depends on the size of the used font for the title.
Spacing between title bar and client window. (1 pixel)
The title bar is part of the frame window and not a separate window.
The client window is a separate window created as a child window of the frame
window.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
421
17.8.2 Configuration options
Type
Macro
Default
Description
Allows dragging the widget on the
surrounding frame.
B
FRAMEWIN_ALLOW_DRAG_ON_FRAME
1
N
FRAMEWIN_BARCOLOR_ACTIVE_DEFAULT
FRAMEWIN_BARCOLOR_INACTIVE_DEFAULT
FRAMEWIN_BORDER_DEFAULT
FRAMEWIN_CLIENTCOLOR_DEFAULT
FRAMEWIN_DEFAULT_FONT
FRAMEWIN_FRAMECOLOR_DEFAULT
FRAMEWIN_IBORDER_DEFAULT
FRAMEWIN_TITLEHEIGHT_DEFAULT
0xff0000
Title bar color, active state.
0x404040
Title bar color, inactive state.
3
Outer border width, in pixels.
0xc0c0c0
Color of client window area.
N
N
N
S
N
N
N
&GUI_Font8_1 Font used for title bar text.
0xaaaaaa
Frame color.
1
Inner border width, in pixels.
0
Default height of title bar.
17.8.3 Keyboard reaction
The widget can not gain the input focus and does not react on keyboard input.
17.8.4 FRAMEWIN API
The table below lists the available emWin FRAMEWIN-related routines in alphabetical
order. Detailed descriptions of the routines follow.
Routine
FRAMEWIN_AddButton()
FRAMEWIN_AddCloseButton()
FRAMEWIN_AddMaxButton()
FRAMEWIN_AddMenu()
FRAMEWIN_AddMinButton()
FRAMEWIN_Create()
FRAMEWIN_CreateAsChild()
FRAMEWIN_CreateEx()
FRAMEWIN_CreateIndirect()
FRAMEWIN_CreateUser()
FRAMEWIN_GetActive()
FRAMEWIN_GetBarColor()
FRAMEWIN_GetBorderSize()
FRAMEWIN_GetDefaultBarColor()
FRAMEWIN_GetDefaultBorderSize()
FRAMEWIN_GetDefaultClientColor()
FRAMEWIN_GetDefaultFont()
FRAMEWIN_GetDefaultTextColor()
FRAMEWIN_GetDefaultTitleHeight()
FRAMEWIN_GetFont()
FRAMEWIN_GetText()
FRAMEWIN_GetTextAlign()
FRAMEWIN_GetTitleHeight()
FRAMEWIN_GetUserData()
FRAMEWIN_IsMinimized()
FRAMEWIN_IsMaximized()
FRAMEWIN_Maximize()
FRAMEWIN_Minimize()
FRAMEWIN_OwnerDraw()
User's & reference manual for emWin V5.10
Description
Adds a button in the title bar.
Adds a close button in the title bar.
Adds a maximize button in the title bar.
Adds a menu widget to the frame window.
Adds a minimize button in the title bar.
Creates a FRAMEWIN widget. (Obsolete)
Creates a FRAMEWIN widget as a child window. (Obsolete)
Creates a FRAMEWIN widget.
Creates a BUTTON widget from a resource table entry.
Creates a FRAMEWIN widget using extra bytes as user
data.
Returns if the frame window is in active state.
Returns the color of the title bar.
Returns the size of the border.
Returns the default color of the title bar.
Returns the default border size
Returns the default color of the client area.
Returns the default font used for the title bar
Returns the default text color of the title.
Returns the default size of the title bar
Returns the font used for the title text.
Returns the title text.
Returns the alignment of the title text.
Returns the height of the title bar.
Retrieves the data set with FRAMEWIN_SetUserData().
Returns if the frame window is minimized or not.
Returns if the frame window is maximized or not.
Enlarges the frame window to the size of its parent.
Hides the client area of the frame window.
Default function for drawing the title bar.
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
422
CHAPTER
Window Objects (Widgets)
Routine
Description
FRAMEWIN_Restore()
FRAMEWIN_SetActive()
FRAMEWIN_SetBarColor()
FRAMEWIN_SetBorderSize()
FRAMEWIN_SetClientColor()
FRAMEWIN_SetDefaultBarColor()
FRAMEWIN_SetDefaultBorderSize()
FRAMEWIN_SetDefaultClientColor()
FRAMEWIN_SetDefaultFont()
FRAMEWIN_SetDefaultTextColor()
FRAMEWIN_SetDefaultTitleHeight()
FRAMEWIN_SetFont()
Restores a minimized or maximized frame window.
Sets the state of the frame window. (Obsolete)
Sets the color of the title bar.
Sets the border size of the frame window.
Sets the color of the client area
Sets the default color of the title bar
Sets the default border size
Sets the default color of the client area.
Sets the default font used for the title bar.
Sets the default text color of the title.
Sets the default height of the title bar
Selects the font used for the title text.
Sets the frame window to a moveable/non-moveable
state.
FRAMEWIN_SetMoveable()
Enables the frame window to be owner drawn.
FRAMEWIN_SetOwnerDraw()
FRAMEWIN_SetResizeable()
FRAMEWIN_SetText()
FRAMEWIN_SetTextAlign()
FRAMEWIN_SetTextColor()
FRAMEWIN_SetTextColorEx()
FRAMEWIN_SetTitleHeight()
FRAMEWIN_SetTitleVis()
FRAMEWIN_SetUserData()
Sets the frame window to resizable state.
Sets the title text.
Sets the alignment of the title text.
Sets the color(s) for the title text.
Sets the color(s) for the title text.
Sets the height of the title bar.
Sets the visibility flag of the title bar
Sets the extra data of a FRAMEWIN widget.
FRAMEWIN_AddButton()
Before
After
Description
Adds a button to the title bar of the frame window.
Prototype
WM_HWIN FRAMEWIN_AddButton(FRAMEWIN_Handle hObj, int Flags,
int
Off, int Id);
Parameter
hObj
Flags
Off
Id
Description
Handle of frame window.
(see table below)
X-offset used to create the BUTTON widget
ID of the BUTTON widget
Permitted values for parameter Flags
The BUTTON will be created at the left side.
0
FRAMEWIN_BUTTON_RIGHT The BUTTON will be created at the right side.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
423
Return value
Handle of the BUTTON widget.
Additional information
The button will be created as a child window from the frame window. So the window
manager keeps sure it will be deleted when the frame window will be deleted.
The button can be created at the left side or at the right side of the title bar depending on the parameter Flags. The parameter Offset specifies the space between the
button and the border of the frame window or the space between the previous created button.
FRAMEWIN_AddCloseButton()
Before
After
Description
Adds a close button to the title bar of the frame window.
Prototype
WM_HWIN FRAMEWIN_AddCloseButton(FRAMEWIN_Handle hObj, int Flags, int Off);
Parameter
hObj
Flags
Off
Description
Handle of frame window.
(see table below)
X-offset used to create the BUTTON widget
Permitted values for parameter Index
The BUTTON will be created at the left side.
0
FRAMEWIN_BUTTON_RIGHT The BUTTON will be created at the right side.
Return value
Handle of the close button.
Additional information
When the user presses the close button the frame window and all its children will be
deleted.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
424
CHAPTER
Window Objects (Widgets)
FRAMEWIN_AddMaxButton()
Before
After
Maximized
Description
Adds a maximize button to the title bar of the frame window.
Prototype
WM_HWIN FRAMEWIN_AddMaxButton(FRAMEWIN_Handle hObj, int Flags, int Off);
Parameter
hObj
Flags
Off
Description
Handle of frame window.
(see table below)
X-offset used to create the BUTTON widget
Permitted values for parameter Index
The BUTTON will be created at the left side.
0
FRAMEWIN_BUTTON_RIGHT The BUTTON will be created at the right side.
Return value
Handle of the maximize button.
Additional information
When the user presses the maximize button the first time the frame window will be
enlarged to the size of its parent window. The second use of the button will reduce
the frame window to its old size and restores the old position.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
425
FRAMEWIN_AddMenu()
Before
After
Description
Adds the given menu to a frame window. The menu is shown below the title bar.
Prototype
void FRAMEWIN_AddMenu(FRAMEWIN_Handle hObj, WM_HWIN hMenu);
Parameter
Description
Handle of frame window.
hObj
hMenu
Handle of menu widget to be added.
Additional information
The added menu is attached as a child of the frame window. If the frame window has
been created with a callback routine, the function makes sure, that the WM_MENU messages are passed to the client window of the frame window.
FRAMEWIN_AddMinButton()
Before
After
Minimized window
Description
Adds a minimize button to the title bar of the frame window.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
426
CHAPTER
Window Objects (Widgets)
Prototype
WM_HWIN FRAMEWIN_AddMinButton(FRAMEWIN_Handle hObj, int Flags, int Off);
Parameter
hObj
Flags
Off
Description
Handle of frame window.
(see table below)
X-offset used to create the BUTTON widget
Permitted values for parameter Index
The BUTTON will be created at the left side.
0
FRAMEWIN_BUTTON_RIGHT The BUTTON will be created at the right side.
Return value
Handle of the minimize button.
Additional information
When the user presses the minimize button the first time the client area of the frame
window will be hidden and only the title bar remains visible. The second use of the
button will restore the frame window to its old size.
FRAMEWIN_Create()
(Obsolete, FRAMEWIN_CreateEx() should be used instead)
Description
Creates a FRAMEWIN widget of a specified size at a specified location.
Prototype
FRAMEWIN_Handle FRAMEWIN_Create(const char * pTitle, WM_CALLBACK * cb,
int
Flags,
int
x0,
int
y0,
int
xsize, int
ysize);
Parameter
pTitle
cb
Flags
x0
y0
xsize
ysize
Description
Title displayed in the title bar.
Pointer to callback routine of client area.
Window create flags. Typically WM_CF_SHOW in order to make the widget visible
immediately (refer to WM_CreateWindow() in the chapter “The Window Manager
(WM)” on page 289 for a list of available parameter values).
Leftmost pixel of the frame window (in parent coordinates).
Topmost pixel of the frame window (in parent coordinates).
Horizontal size of the frame window (in pixels).
Vertical size of the frame window (in pixels).
Return value
Handle of the created FRAMEWIN widget; 0 if the function fails.
FRAMEWIN_CreateAsChild()
(Obsolete, FRAMEWIN_CreateEx should be used instead)
Description
Creates a FRAMEWIN widget as a child window.
Prototype
FRAMEWIN_Handle FRAMEWIN_CreateAsChild(int
int
User's & reference manual for emWin V5.10
x0,
xsize,
int y0,
int ysize,
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
427
WM_HWIN
hParent,
const char * pText,
WM_CALLBACK * cb,
int Flags);
Parameter
x0
y0
xsize
ysize
hParent
pText
cb
Flags
Description
X-position of the frame window relative to the parent window.
Y-position of the frame window relative to the parent window.
Horizontal size of the frame window (in pixels).
Vertical size of the frame window (in pixels).
Handle of parent window.
Text to be displayed in the title bar.
Pointer to callback routine.
Window create flags (see
FRAMEWIN_Create() ).
Return value
Handle of the created FRAMEWIN widget; 0 if the function fails.
FRAMEWIN_CreateEx()
Description
Creates a FRAMEWIN widget of a specified size at a specified location.
Prototype
FRAMEWIN_Handle FRAMEWIN_CreateEx(int
x0,
int
xsize,
WM_HWIN
hParent,
int
ExFlags,
const char * pTitle,
WM_CALLBACK * cb);
Parameter
x0
y0
xsize
ysize
int
int
int
int
y0,
ysize,
WinFlags,
Id,
Description
Leftmost pixel of the widget (in parent coordinates).
Topmost pixel of the widget (in parent coordinates).
Horizontal size of the widget (in pixels).
Vertical size of the widget (in pixels).
hParent
Handle of parent window. If 0, the new FRAMEWIN widget will be a child of the desktop (top-level window).
WinFlags
Window create flags. Typically WM_CF_SHOW in order to make the widget visible
immediately (refer to WM_CreateWindow() in the chapter “The Window Manager
(WM)” on page 289 for a list of available parameter values).
ExFlags
Id
pTitle
cb
(see table below)
Window ID of the widget.
Title displayed in the title bar.
Pointer to user callback routine. This user callback routine is called by the window
callback routine of the client window.
Permitted values for parameter ExFlags
0
No function.
FRAMEWIN_CF_MOVEABLE
Sets the new frame window to a moveable
state. For details, refer to
“FRAMEWIN_SetMoveable()” on page 437.
Return value
Handle of the created FRAMEWIN widget; 0 if the function fails.
Additional information
The user callback routine is typically used for 2 purposes:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
428
CHAPTER
Window Objects (Widgets)
•
to paint the client window (if filling with a color is not desired)
•
to react to messages of child windows, typically dialog elements
The normal behaviour of the client window is to paint itself, filling the entire window
with the client color.
If the user callback also fills the client window (or a part of it), it can be desirable to
set the client color to GUI_INVALID_COLOR, causing the window callback to not fill the
client window.
The user callback of the client window does not receive all messages sent to the client window; some system messages are completely handled by the window callback
routine and are not passed to the user callback. All notification messages as well as
WM_PAINT and all user messages are sent to the user callback routine.
The handle received by the user callback is the handle of the frame window (the parent window of the client window), except for the WM_PAINT message, which receives
the handle of the client window.
FRAMEWIN_CreateIndirect()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateIndirect().
The elements Flags and Para of the resource passed as parameter are not used.
FRAMEWIN_CreateUser()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateUser(). For
a detailed description of the parameters the function FRAMEWIN_CreateEx() can be
referred to.
FRAMEWIN_GetActive()
Description
Returns if the given frame window is in active state or not.
Prototype
GUI_COLOR FRAMEWIN_GetBarColor(FRAMEWIN_Handle hObj, unsigned Index);
Parameter
hObj
Description
Handle of frame window.
Return value
1 if frame window is in active state, 0 if not.
FRAMEWIN_GetBarColor()
Description
Returns the color of the title bar of the given frame window.
Prototype
GUI_COLOR FRAMEWIN_GetBarColor(FRAMEWIN_Handle hObj, unsigned Index);
Parameter
hObj
Index
Description
Handle of frame window.
(see table below)
Permitted values for parameter Index
0
1
Returns the bar color used when frame window is inactive.
Returns the bar color used when frame window is active.
Return value
Color of the title bar as RGB value.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
429
FRAMEWIN_GetBorderSize()
Description
Returns the border size of the given frame window.
Prototype
int FRAMEWIN_GetBorderSize(FRAMEWIN_Handle hObj);
Parameter
hObj
Description
Handle of frame window.
Return value
The border size of the given frame window.
FRAMEWIN_GetDefaultBarColor()
Description
Returns the default color for title bars in frame windows.
Prototype
const GUI_COLOR* FRAMEWIN_GetDefaultBarColor(unsigned int Index);
Parameter
Index
Description
(see table below)
Permitted values for parameter Index
0
1
Returns the bar color used when frame window is inactive.
Returns the bar color used when frame window is active.
Return value
Pointer to the default title bar color used for frame windows in the specified state.
FRAMEWIN_GetDefaultBorderSize()
Description
Returns the default size of a frame window border.
Prototype
int FRAMEWIN_GetDefaultBorderSize(void);
Return value
Default size of a frame window border.
FRAMEWIN_GetDefaultClientColor()
Description
Returns the default color of client areas in frame windows.
Prototype
const GUI_COLOR* FRAMEWIN_GetDefaultClientColor(void);
Return value
Pointer to the default client area color.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
430
CHAPTER
Window Objects (Widgets)
FRAMEWIN_GetDefaultFont()
Description
Returns the default font used for frame window captions.
Prototype
const GUI_FONT* FRAMEWIN_GetDefaultFont(void);
Return value
Pointer to the default font used for frame window captions.
FRAMEWIN_GetDefaultTextColor()
Description
Returns the default text color of the title.
Prototype
GUI_COLOR FRAMEWIN_GetDefaultTextColor(unsigned Index);
Parameter
Index
Description
(see table below)
Permitted values for parameter Index
0
1
Color to be used when frame window is inactive.
Color to be used when frame window is active.
Return value
Default text color of the title.
FRAMEWIN_GetFont()
Description
Returns a pointer to the font used to draw the title text.
Prototype
const GUI_FONT GUI_UNI_PTR * FRAMEWIN_GetFont(FRAMEWIN_Handle hObj);
Parameter
hObj
Description
Handle of frame window.
Return value
Pointer to the font used to draw the title text.
FRAMEWIN_GetText()
Description
Returns the title text.
Prototype
void FRAMEWIN_GetText(FRAMEWIN_Handle hObj, char * pBuffer, int MaxLen);
Parameter
hObj
pBuffer
MaxLen
Description
Handle of frame window.
Pointer to buffer to be filled with the title text.
Buffer size in bytes.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
431
Additional information
If the buffer size is smaller than the title text the function copies MaxLen.
FRAMEWIN_GetTextAlign()
Description
Returns the text alignment of the title text.
Prototype
int FRAMEWIN_GetTextAlign(FRAMEWIN_Handle hObj);
Parameter
hObj
Description
Handle of frame window.
Return value
The currently used text alignment.
to“GUI_SetTextAlign()” on page 82.
For
details
about
text
alignment,
refer
FRAMEWIN_GetDefaultTitleHeight()
Description
Returns the default height of title bars in frame windows.
Prototype
int FRAMEWIN_GetDefaultCaptionSize(void);
Return value
Default title bar height. For more informations about the title height, refer to
“FRAMEWIN_SetDefaultTitleHeight()” on page 437.
FRAMEWIN_GetTitleHeight()
Description
Returns the height of title bar of the given frame window.
Prototype
int FRAMEWIN_GetTitleHeight(FRAMEWIN_Handle hObj);
Parameter
hObj
Description
Handle of frame window.
Return value
The height of title bar of the given frame window. For more informations about the
title height, refer to “FRAMEWIN_SetDefaultTitleHeight()” on page 437.
FRAMEWIN_GetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_GetUserData().
FRAMEWIN_IsMaximized()
Description
Returns if the frame window is maximized or not.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
432
CHAPTER
Window Objects (Widgets)
Prototype
int FRAMEWIN_IsMaximized(FRAMEWIN_Handle hObj);
Parameter
hObj
Description
Handle of frame window.
Return value
1 if the frame window is maximized, 0 if not.
FRAMEWIN_IsMinimized()
Description
Returns if the frame window is minimized or not.
Prototype
int FRAMEWIN_IsMinimized(FRAMEWIN_Handle hObj);
Parameter
hObj
Description
Handle of frame window.
Return value
1 if the frame window is minimized, 0 if not.
FRAMEWIN_Maximize()
Before
After
Description
Enlarges a frame window to the size of its parent window.
Prototype
void FRAMEWIN_Maximize(FRAMEWIN_Handle hObj);
Parameter
hObj
Description
Handle of frame window.
Additional information
When calling this function the frame window will show the same behavior as when
the user presses the maximize button. The frame window will be enlarged to the size
of its parent window.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
433
FRAMEWIN_Minimize()
Before
After
Description
Hides the client area of the given frame window.
Prototype
void FRAMEWIN_Minimize(FRAMEWIN_Handle hObj);
Parameter
hObj
Description
Handle of frame window.
Additional information
When calling this function the frame window will show the same behavior as when
the user presses the minimize button. The client area of the frame window will be
hidden and only the title bar remains visible.
FRAMEWIN_OwnerDraw()
Description
Default function for drawing the title bar of a frame window.
Prototypes
int FRAMEWIN_OwnerDraw(const WIDGET_ITEM_DRAW_INFO * pDrawItemInfo);
Parameter
pDrawItemInfo
Description
Pointer to a
WIDGET_ITEM_DRAW_INFO structure.
Additional information
This function is useful if FRAMEWIN_SetOwnerDraw() is used. It should be called for all
unhandled commands passed to the owner draw function. For more information, refer
to the section explaining user drawn widgets and FRAMEWIN_SetOwnerDraw().
FRAMEWIN_Restore()
Before
After
Description
Restores a minimized or maximized frame window to its old size and position.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
434
CHAPTER
Window Objects (Widgets)
Prototype
void FRAMEWIN_Restore(FRAMEWIN_Handle hObj);
Parameter
hObj
Description
Handle of frame window.
Additional information
If the given frame window is neither maximized nor minimized the function takes no
effect.
FRAMEWIN_SetActive()
Before
After
Description
Sets the state of a specified frame window. Depending on the state, the color of the
title bar will change.
Prototype
void FRAMEWIN_SetActive(FRAMEWIN_Handle hObj, int State);
Parameter
hObj
State
Description
Handle of frame window.
State of frame window (see table below).
Permitted values for parameter State
Frame window is inactive.
0
1
Frame window is active.
Additional information
This function is obsolete. If pointing with a input device to a child of a frame window
the frame window will become active automatically. It is not recommended to use
this function. If using this function to set a frame window to active state, it is not
warranted that the state becomes inactive if an other frame window becomes active.
FRAMEWIN_SetBarColor()
Before
After
Description
Sets the color of the title bar of a specified frame window.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
435
Prototype
void FRAMEWIN_SetBarColor(FRAMEWIN_Handle hObj,
unsigned int Index,
GUI_COLOR
Color);
Parameter
hObj
Index
Color
Description
Handle of frame window.
Index for state of frame window (see table below).
Color to be set.
Permitted values for parameter Index
Sets the color to be used when frame window is inactive.
0
1
Sets the color to be used when frame window is active.
FRAMEWIN_SetBorderSize()
Before
After
Description
Sets the border size of a specified frame window.
Prototype
void FRAMEWIN_SetBorderSize(FRAMEWIN_Handle hObj, unsigned Size);
Parameter
hObj
Size
Description
Handle of frame window.
New border size of the frame window.
FRAMEWIN_SetClientColor()
Before
After
Description
Sets the color of the client window area of a specified frame window.
Prototype
void FRAMEWIN_SetClientColor(FRAMEWIN_Handle hObj, GUI_COLOR Color);
Parameter
hObj
Color
Description
Handle of frame window.
Color to be set.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
436
CHAPTER
Window Objects (Widgets)
FRAMEWIN_SetDefaultBarColor()
Description
Sets the default color for title bars in frame windows.
Prototype
void FRAMEWIN_SetDefaultBarColor(unsigned int Index, GUI_COLOR Color);
Parameter
Index
Color
Description
Index for state of frame window (see table below).
Color to be set.
Permitted values for parameter Index
0
1
Sets the color to be used when frame window is inactive.
Sets the color to be used when frame window is active.
FRAMEWIN_SetDefaultBorderSize()
Description
Sets the default border size of frame windows.
Prototype
void FRAMEWIN_SetDefaultBorderSize(int BorderSize);
Parameter
BorderSize
Description
Size to be set.
FRAMEWIN_SetDefaultClientColor()
Description
Sets the default color for client areas in frame windows.
Prototype
void FRAMEWIN_SetDefaultClientColor(GUI_COLOR Color);
Parameter
Color
Description
Color to be set.
FRAMEWIN_SetDefaultFont()
Description
Sets the default font used to display the title in frame windows.
Prototype
void FRAMEWIN_SetDefaultFont(const GUI_FONT * pFont);
Parameter
pFont
Description
Pointer to font to be used as default
FRAMEWIN_SetDefaultTextColor()
Description
Sets the default text color of the title.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
437
Prototype
void FRAMEWIN_SetDefaultTextColor(unsigned Index, GUI_COLOR Color);
Parameter
Index
Color
Description
(see table below)
Color to be used.
Permitted values for parameter Index
Color to be used when frame window is inactive.
0
1
Color to be used when frame window is active.
FRAMEWIN_SetDefaultTitleHeight()
Description
Sets the size in Y for the title bar.
Prototype
void FRAMEWIN_SetDefaultTitleHeight(int Height);
Parameter
Height
Description
Size to be set
Additional information
The default value of the title height is 0. That means the height of the title depends
on the font used to display the title text. If the default value is set to a value > 0
each new frame window will use this height for the title height and not the height of
the font of the title.
FRAMEWIN_SetFont()
Before
After
Description
Sets the title font.
Prototype
void FRAMEWIN_SetFont(FRAMEWIN_Handle hObj, const GUI_FONT * pfont);
Parameter
hObj
pFont
Description
Handle of frame window.
Pointer to the font.
FRAMEWIN_SetMoveable()
Description
Sets a frame window to a moveable or fixed state.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
438
CHAPTER
Window Objects (Widgets)
Prototype
void FRAMEWIN_SetMoveable(FRAMEWIN_Handle hObj, int State);
Parameter
hObj
State
Description
Handle of frame window.
State of frame window (see table below).
Permitted values for parameter State
0
1
Frame window is fixed (non-moveable).
Frame window is moveable.
Additional information
The default state of a frame window after creation is fixed.
Moveable state means, the frame window can be dragged with a pointer input device
(PID). To move the frame window, it first needs to be touched with a PID in pressed
state in the title area. Moving the pressed PID now moves also the widget.
If the config macro FRAMEWIN_ALLOW_DRAG_ON_FRAME is 1 (default), the frame window can also be dragged on the surrounding frame. This works only if the frame window is not in resizable state.
FRAMEWIN_SetOwnerDraw()
Description
Enables the frame window to be owner drawn.
Prototype
void FRAMEWIN_SetOwnerDraw(FRAMEWIN_Handle
hObj,
WIDGET_DRAW_ITEM_FUNC * pfDrawItem);
Parameter
hObj
pfDrawItem
Description
Handle of frame window.
Pointer to owner draw function.
Additional information
This function sets a function pointer to a function which will be called by the widget if
a frame window has to be drawn. It gives you the possibility to draw a complete customized title bar, not just plain text. pfDrawItem is a pointer to an applicationdefined function of type WIDGET_DRAW_ITEM_FUNC which is explained at the beginning
of the chapter.
Example
The following shows a typical owner draw function:
int _OwnerDraw(const WIDGET_ITEM_DRAW_INFO * pDrawItemInfo) {
GUI_RECT Rect;
char acBuffer[20];
switch (pDrawItemInfo->Cmd) {
case WIDGET_ITEM_DRAW:
Rect.x0 = pDrawItemInfo->x0 + 1;
Rect.x1 = pDrawItemInfo->x1 - 1;
Rect.y0 = pDrawItemInfo->y0 + 1;
Rect.y1 = pDrawItemInfo->y1;
FRAMEWIN_GetText(pDrawItemInfo->hWin, acBuffer, sizeof(acBuffer));
GUI_DrawGradientH(pDrawItemInfo->x0, pDrawItemInfo->y0,
pDrawItemInfo->x1, pDrawItemInfo->y1,
GUI_RED, GUI_GREEN);
GUI_SetFont(FRAMEWIN_GetFont(pDrawItemInfo->hWin));
GUI_SetTextMode(GUI_TM_TRANS);
GUI_SetColor(GUI_YELLOW);
GUI_DispStringInRect(acBuffer, &Rect,
FRAMEWIN_GetTextAlign(pDrawItemInfo->hWin));
return 0;
}
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
439
return FRAMEWIN_OwnerDraw(pDrawItemInfo);
}
void CreateFrameWindow(void) {
...
FRAMEWIN_SetOwnerDraw(hWin, _OwnerDraw);
...
}
Screenshot of above example
FRAMEWIN_SetResizeable()
Before
After
Description
Sets the resizable state of the given frame window.
Prototype
void FRAMEWIN_SetResizeable(FRAMEWIN_Handle hObj, int State);
Parameter
hObj
State
Description
Handle of frame window.
1 if the frame window should be resizable, 0 if not.
Additional information
If the frame window is in resizable state its size can be changed by dragging the borders. If a pointer input device points over the border, the cursor will change to a
resize cursor (if cursor is on and if optional mouse support is enabled).
If pointing to the edge of the border, the X and Y size of the window can be changed
simultaneously.
FRAMEWIN_SetText()
Before
After
Description
Sets the title text.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
440
CHAPTER
Window Objects (Widgets)
Prototype
void FRAMEWIN_SetText(FRAMEWIN_Handle hObj, const char * s);
Parameter
hObj
s
Description
Handle of frame window.
Text to display as the title.
FRAMEWIN_SetTextAlign()
Before
After
Description
Sets the text alignment of the title bar.
Prototype
void FRAMEWIN_SetTextAlign(FRAMEWIN_Handle hObj, int Align);
Parameter
hObj
Align
Description
Handle of frame window.
Alignment attribute for the title (see table below).
Permitted values for parameter Align
GUI_TA_HCENTER Centers the title (default).
Displays the title to the left.
GUI_TA_LEFT
Displays the title to the right.
GUI_TA_RIGHT
Additional information
If this function is not called, the default behavior is to display the text centered.
FRAMEWIN_SetTextColor()
Before
After
Description
Sets the color of the title text for both states, active and inactive.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
441
Prototype
void FRAMEWIN_SetTextColor(FRAMEWIN_Handle hObj, GUI_COLOR Color);
Parameter
hObj
Color
Description
Handle of frame window.
Color to be set.
FRAMEWIN_SetTextColorEx()
Before
After
Description
Sets the text color for the given state.
Prototype
void FRAMEWIN_SetTextColorEx(FRAMEWIN_Handle hObj,
unsigned Index,
GUI_COLOR
Color);
Parameter
hObj
Index
Color
Description
Handle of frame window.
(see table below)
Color to be used.
Permitted values for parameter Index
Color to be used when frame window is inactive.
0
1
Color to be used when frame window is active.
FRAMEWIN_SetTitleHeight()
Before
After
Description
Sets the height of the title bar.
Prototype
int FRAMEWIN_SetTitleHeight(FRAMEWIN_Handle hObj, int Height);
Parameter
hObj
Height
Description
Handle of frame window.
Height of the title bar.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
442
CHAPTER
Window Objects (Widgets)
Additional information
Per default the height of the title bar depends on the size on the font used to display
the title text. When using FRAMEWIN_SetTitleHeight the height will be fixed to the
given value. Changes of the font takes no effect concerning the height of the title bar.
A value of 0 will restore the default behavior.
FRAMEWIN_SetTitleVis()
Before
After
Description
Sets the visibility flag of the title bar.
Prototype
void FRAMEWIN_SetTitleVis(FRAMEWIN_Handle hObj, int Show);
Parameter
hObj
Show
Description
Handle of frame window.
1 for visible (default), 0 for hidden
FRAMEWIN_SetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_SetUserData().
17.8.5 Example
The Sample folder contains the following example which shows how the widget can be
used:
•
WIDGET_FrameWin.c
Note that several other examples also make use of this widget and may also be helpful to get familiar with the widget.
Screen shot of WIDGET_FrameWin.c:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
443
17.9 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.
17.9.1 Structure of the graph widget
A graph widget consists of different kinds objects:
•
•
•
The graph widget itself to which data objects and scale objects can be attached.
Optionally one or more data objects.
Optionally one or more scale objects.
The following diagram shows the detailed structure of a graph widget:
Border
Frame
Grid
Data objects
Application
defined
graphics
Y-Size
X-Size
Data
area
Scrollbar(s)
Scale objects
The following table explains the details of the diagram above:
Detail
Border
Frame
Grid
Data area
Data object(s)
Application
defined graphic
Scrollbar(s)
Description
The optional border is part of the graph widget.
A thin line around the data area, part of the graph widget.
Shown in the background of the data area, part of the graph widget.
Area, in which grid and data objects are shown.
For each curve one data object should be added to the graph widget.
An application defined callback function can be used to draw any application
defined text and/or graphics.
If the range of the data object is bigger than the data area of the graph widget,
the graph widget can automatically show a horizontal and/or a vertical scrollbar.
Scale object(s) Horizontal and vertical scales can be attached to the graph widget.
X-Size of the data area.
X-Size
Y-Size of the data area.
Y-Size
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
444
CHAPTER
Window Objects (Widgets)
17.9.2 Creating and deleting a graph widget
The process of creating a graph widget should be the following:
•
•
•
•
•
Create
Create
Attach
Create
Attach
the
the
the
the
the
graph widget and set the desired attributes.
data object(s).
data object(s) to the graph widget.
optional scale object(s).
scale object(s) to the graph widget.
Once attached to the graph widget the data and scale objects need not to be deleted
by the application. This is done by the graph widget.
Example
The following shows a small example how to create and delete a graph widget:
GRAPH_DATA_Handle hData;
GRAPH_SCALE_Handle hScale;
WM_HWIN hGraph;
hGraph = GRAPH_CreateEx(10, 10, 216, 106, WM_HBKWIN, WM_CF_SHOW, 0, GUI_ID_GRAPH0);
hData = GRAPH_DATA_YT_Create(GUI_DARKGREEN, NumDataItems, aData0, MaxNumDataItems);
GRAPH_AttachData(hGraph, hData);
hScale = GRAPH_SCALE_Create(28, GUI_TA_RIGHT, GRAPH_SCALE_CF_VERTICAL, 20);
GRAPH_AttachScale(hGraph, hScale);
/*
Do something with the widget...
*/
WM_DeleteWindow(hGraph);
17.9.3 Drawing process
As explained above a graph widget consists of different parts and ’sub’ objects. The
following will explain, in which sequence the widget is drawn:
1. Filling the background with the background color.
2. Calling an optional callback routine. This makes it possible to draw for example a
user defined grid.
3. Drawing the grid (if enabled).
4. Drawing the data objects and the border area.
5. Drawing the scale objects.
6. Calling an optional callback routine. This makes it possible to draw for example a
user defined scale or some additional text and/or graphics.
17.9.4 Supported types of curves
The requirements for showing a curve with continuously updated measurement values can be different to the requirements when showing a function graph with X/Y
coordinates. For that reason the widget currently supports 2 kinds of data objects,
which are shown in the table below:
GRAPH_DATA_XY
User's & reference manual for emWin V5.10
GRAPH_DATA_YT
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
445
17.9.4.1 GRAPH_DATA_XY
This data object is used to show curves which consist of an array of points. The
object data is drawn as a polyline. A typical application for using this data object is
drawing a function graph.
17.9.4.2 GRAPH_DATA_YT
This data object is used to show curves with one Y-value for each X-position on the
graph. A typical application for using this data object is showing a curve with continuously updated measurement values.
17.9.5 Configuration options
17.9.5.1 Graph widget
Type
Macro
Default
Description
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
GRAPH_GRIDCOLOR_DEFAULT
GRAPH_GRIDSPACING_X_DEFAULT
GRAPH_GRIDSPACING_Y_DEFAULT
GRAPH_BORDER_L_DEFAULT
GRAPH_BORDER_T_DEFAULT
GRAPH_BORDER_R_DEFAULT
GRAPH_BORDER_B_DEFAULT
GUI_WHITE
Default color of the thin frame line.
N
N
N
N
N
N
N
GUI_DARKGRAY Default color used to draw the grid.
50
Default horizontal spacing of the grid.
50
Default vertical spacing of the grid.
0
Default size of the left border.
0
Default size of the top border.
0
Default size of the right border.
0
Default size of the bottom border.
17.9.5.2 Scale object
Type
N
S
Macro
Default
GRAPH_SCALE_TEXTCOLOR_DEFAULT GUI_WHITE
&GUI_Font6x8
GRAPH_SCALE_FONT_DEFAULT
Description
Default text color.
Default font used to draw the values.
17.9.6 Keyboard reaction
The widget can not gain the input focus and does not react on keyboard input.
17.9.7 GRAPH API
The table below lists the available emWin GRAPH-related routines in alphabetical
order. Detailed descriptions of the routines follow.
Routine
Description
Common routines
GRAPH_AttachData()
GRAPH_AttachScale()
GRAPH_CreateEx()
GRAPH_CreateIndirect()
GRAPH_CreateUser()
GRAPH_DetachData()
GRAPH_DetachScale()
GRAPH_GetUserData()
GRAPH_SetBorder()
User's & reference manual for emWin V5.10
Attaches a data object to a GRAPH widget.
Attaches a scale object to a GRAPH widget.
Creates a GRAPH widget.
Creates a GRAPH widget from a resource table entry
Creates a GRAPH widget using extra bytes as user data.
Detaches a data object from a GRAPH widget.
Detaches a scale object from a GRAPH widget.
Retrieves the data set with GRAPH_SetUserData().
Sets the size (right, left, top and bottom) of the border.
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
446
CHAPTER
Routine
Window Objects (Widgets)
Description
Sets the color of the GRAPH widget.
GRAPH_SetColor()
GRAPH_SetGridDistX()
GRAPH_SetGridDistY()
GRAPH_SetGridFixedX()
GRAPH_SetGridVis()
GRAPH_SetLineStyleH()
GRAPH_SetLineStyleV()
GRAPH_SetUserData()
GRAPH_SetUserDraw()
GRAPH_SetVSizeX()
GRAPH_SetVSizeY()
Sets the horizontal grid spacing.
Sets the vertical grid spacing.
Fixes the grid in X-axis.
Enables the drawing of a grid.
Sets the line style for the horizontal grid lines.
Sets the line style for the vertical grid lines.
Sets the extra data of a GRAPH widget.
Sets the user callback function.
Sets the horizontal range of the GRAPH widget.
Sets the vertical range of the GRAPH widget.
GRAPH_DATA_YT related routines
Adds one data item to the GRAPH_DATA_YT object.
GRAPH_DATA_YT_AddValue()
GRAPH_DATA_YT_Clear()
GRAPH_DATA_YT_Create()
GRAPH_DATA_YT_Delete()
GRAPH_DATA_YT_MirrorX()
GRAPH_DATA_YT_SetAlign()
GRAPH_DATA_YT_SetOffY()
Clears all data items of the GRAPH_DATA_YT object.
Creates a GRAPH_DATA_YT object.
Deletes a GRAPH_DATA_YT object.
Mirrors the x-axis.
Sets the alignment of the given GRAPH_DATA_YT object.
Sets a vertical offset for drawing the data.
GRAPH_DATA_XY related routines
GRAPH_DATA_XY_AddPoint()
GRAPH_DATA_XY_Create()
GRAPH_DATA_XY_Delete()
GRAPH_DATA_XY_SetLineStyle()
GRAPH_DATA_XY_SetOffX()
GRAPH_DATA_XY_SetOffY()
GRAPH_DATA_XY_SetOwnerDraw()
GRAPH_DATA_XY_SetPenSize()
Adds one point to the GRAPH_DATA_XY object.
Creates a GRAPH_DATA_XY object.
Deletes a GRAPH_DATA_XY object.
Sets the line style used to draw the data.
Sets a horizontal offset for drawing the data.
Sets a vertical offset for drawing the data.
Sets the owner callback function.
Sets the pen size used to draw the data.
Scale related routines
GRAPH_SCALE_Create()
GRAPH_SCALE_Delete()
GRAPH_SCALE_SetFactor()
GRAPH_SCALE_SetFixed()
GRAPH_SCALE_SetFont()
GRAPH_SCALE_SetNumDecs()
GRAPH_SCALE_SetOff()
GRAPH_SCALE_SetPos()
GRAPH_SCALE_SetTextColor()
GRAPH_SCALE_SetTickDist()
User's & reference manual for emWin V5.10
Creates a GRAPH_SCALE object.
Deletes a GRAPH_SCALE object.
Sets a calculation factor used to calculate from pixels to the
desired unit.
Avoids scrolling of the scale.
Sets the font used to draw the numbers.
Sets the number of digits of the fractional portion.
Sets an optional offset which is added to the numbers.
Sets the horizontal or vertical position of the scale.
Sets the text color of the scale.
Sets the distance in pixels between the tick marks.
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
447
17.9.7.1 Common routines
GRAPH_AttachData()
Before
After
Description
Attaches a data object to an existing graph widget.
Prototype
void GRAPH_AddGraph(GRAPH_Handle hObj, GRAPH_DATA_Handle hData);
Parameter
Description
hObj
Handle of widget
hData
Handle of the data object to be added to the widget. The data object should be created with GRAPH_DATA_YT_Create() or GRAPH_DATA_XY_Create()
Additional information
Once attached to a graph widget the application needs not to destroy the data object.
The graph widget deletes all attached data objects when it is deleted.
For details about how to create data objects, refer to “GRAPH_DATA_YT_Create()” on
page 456 and “GRAPH_DATA_XY_Create()” on page 459.
GRAPH_AttachScale()
Before
After
Description
Attaches a scale object to an existing graph widget.
Prototype
void GRAPH_AttachScale(GRAPH_Handle hObj, GRAPH_SCALE_Handle hScale);
Parameter
hObj
hScale
Description
Handle of widget
Handle of the scale to be added.
Additional information
Once attached to a graph widget the application needs not to destroy the scale
object. The graph widget deletes all attached scale objects when it is deleted.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
448
CHAPTER
Window Objects (Widgets)
For details about how to create scale objects, refer to “GRAPH_SCALE_Create()” on
page 463.
GRAPH_CreateEx()
Description
Creates a new GRAPH widget of a specified size at a specified location.
Prototype
GRAPH_Handle GRAPH_CreateEx(int
int
WM_HWIN
int
x0,
xsize,
hParent,
ExFlags,
Parameter
x0
y0
xsize
ysize
int
int
int
int
y0,
ysize,
WinFlags,
Id);
Description
Leftmost pixel of the widget (in parent coordinates).
Topmost pixel of the widget (in parent coordinates).
Horizontal size of the widget (in pixels).
Vertical size of the widget (in pixels).
hParent
Handle of parent window. If 0, the new button window will be a child of the desktop
(top-level window).
WinFlags
Window create flags. Typically WM_CF_SHOW in order to make the widget visible
immediately (refer to “WM_CreateWindow()” on page 309 for a list of available
parameter values).
ExFlags
Id
(see table below)
Window Id of the widget.
Permitted values for parameter ExFlags
This flag ’fixes’ the grid in X-axis. That means if hor-
GRAPH_CF_GRID_FIXED_X izontal scrolling is used, the grid remains on its
position.
Return value
Handle of the created GRAPH widget; 0 if the function fails.
GRAPH_CreateIndirect()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateIndirect().
GRAPH_CreateUser()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateUser(). For
a detailed description of the parameters the function GRAPH_CreateEx() can be
referred to.
GRAPH_DetachData()
Description
Detaches a data object from a graph widget.
Prototype
void GRAPH_DetachData(GRAPH_Handle hObj, GRAPH_DATA_Handle hData);
Parameter
hObj
hData
Description
Handle of widget
Handle of the data object to be detached from the widget.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
449
Additional information
Once detached from a graph widget the application needs to destroy the data object.
Detaching a data object does not delete it. For more details about deleting data
objects,
refer
to
“GRAPH_DATA_YT_Delete()”
on
page 457
and
“GRAPH_DATA_XY_Delete()” on page 460.
GRAPH_DetachScale()
Description
Detaches a scale object from a graph widget.
Prototype
void GRAPH_DetachScale(GRAPH_Handle hObj, GRAPH_SCALE_Handle hScale);
Parameter
hObj
hScale
Description
Handle of widget
Handle of the scale object to be detached from the widget.
Additional information
Once detached from a graph widget the application needs to destroy the scale object.
Detaching a scale object does not delete it. For more details about deleting scale
objects, refer to “GRAPH_SCALE_Delete()” on page 463.
GRAPH_GetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_GetUserData().
GRAPH_SetBorder()
Before
After
Description
Sets the left, top, right and bottom border of the given graph widget.
Prototype
void GRAPH_SetBorder(GRAPH_Handle hObj,
unsigned
BorderL, unsigned BorderT,
unsigned
BorderR, unsigned BorderB);
Parameter
hObj
BorderL
BorderT
BorderR
BorderB
Description
Handle of widget.
Size in pixels from the left border.
Size in pixels from the top border.
Size in pixels from the right border.
Size in pixels from the bottom border.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
450
CHAPTER
Window Objects (Widgets)
Additional information
The border size is the number of pixels between the widget effect frame and the data
area of the graph widget. The frame, the thin line around the data area, is only visible if the border size is at least one pixel. For details about how to set the color of the
border and the thin frame, refer to “GRAPH_SetColor()” on page 450.
GRAPH_SetColor()
Before
After
Description
Sets the desired color of the given graph widget.
Prototype
GUI_COLOR GRAPH_SetColor(GRAPH_Handle hObj,
GUI_COLOR Color,
unsigned
Index);
Parameter
hObj
Color
Index
Description
Handle of widget.
Color to be used for the desired item.
(see table below)
Permitted values for parameter Index
GRAPH_CI_BK
GRAPH_CI_BORDER
GRAPH_CI_FRAME
GRAPH_CI_GRID
Sets the background color.
Sets the color of the border area.
Sets the color of the thin frame line.
Sets the color of the grid.
Return value
Previous color used for the desired item.
GRAPH_SetGridDistX(), GRAPH_SetGridDistY()
Before
After
Description
These functions set the distance from one grid line to the next.
Prototypes
unsigned GRAPH_SetGridDistX(GRAPH_Handle hObj, unsigned Value);
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
451
unsigned GRAPH_SetGridDistY(GRAPH_Handle hObj, unsigned Value)
Parameter
hObj
Value
Description
Handle of widget
Distance in pixels from one grid line to the next, default is 50 pixel.
Return value
Previous grid line distance.
Additional information
The first vertical grid line is drawn at the leftmost position of the data area and the
first horizontal grid line is drawn at the bottom position of the data area, except an
offset is used.
GRAPH_SetGridFixedX()
Description
Fixes the grid in X-axis.
Prototype
unsigned GRAPH_SetGridFixedX(GRAPH_Handle hObj, unsigned OnOff);
Parameter
hObj
OnOff
Description
Handle of widget.
1 if grid should be fixed in X-axis, 0 if not (default).
Return value
Previous value used
Additional information
In some situations it can be useful to fix the grid in X-axis. A typical application
would be a YT-graph, to which continuously new values are added and horizontal
scrolling is possible. In this case it could be desirable to fix the grid in the background.
For details about how to activate scrolling for a graph widget, refer to
“GRAPH_SetVSizeX(), GRAPH_SetVSizeY()” on page 454.
GRAPH_SetGridOffY()
Before
After
Description
Adds an offset used to show the horizontal grid lines.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
452
CHAPTER
Window Objects (Widgets)
Prototype
unsigned GRAPH_SetGridOffY(GRAPH_Handle hObj, unsigned Value);
Parameter
hObj
Value
Description
Handle of widget.
Offset to be used.
Return value
Previous offset used to draw the horizontal grid lines.
Additional information
When rendering the grid the widget starts drawing the horizontal grid lines from the
bottom of the data area and uses the current spacing. In case of a zero point in the
middle of the Y-axis it could happen, that there is no grid line in the middle. In this
case the grid can be shifted in Y-axis by adding an offset with this function. A positive
value shifts the grid down and negative values shifts it up.
For details about how to set the grid spacing, refer to the functions
“GRAPH_SetGridDistX(), GRAPH_SetGridDistY()” on page 450.
GRAPH_SetGridVis()
Before
After
Description
Sets the visibility of the grid lines.
Prototype
unsigned GRAPH_SetGridVis(GRAPH_Handle hObj, unsigned OnOff);
Parameter
hObj
OnOff
Description
Handle of widget.
1 if the grid should be visible, 0 if not (default).
Return value
Previous value of the grid visibility.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
453
GRAPH_SetLineStyleH(), GRAPH_SetLineStyleV()
Before
After
Description
These functions are used to set the line style used to draw the horizontal and vertical grid
lines.
Prototypes
U8 GRAPH_SetLineStyleH(GRAPH_Handle hObj, U8 LineStyle);
U8 GRAPH_SetLineStyleV(GRAPH_Handle hObj, U8 LineStyle);
Parameter
Description
hObj
Handle of widget.
LineStyle
Line style to be used. For details about the supported line styles, refer to
“GUI_SetLineStyle()” on page 125. Default is GUI_LS_SOLID.
Return value
Previous line style used to draw the horizontal/vertical grid lines.
Additional information
Note that using other styles than GUI_LS_SOLID will need more time to show the
grid.
GRAPH_SetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_SetUserData().
GRAPH_SetUserDraw()
Before
After
Description
Sets the user draw function. This function is called by the widget during the drawing process to give the application the possibility to draw user defined data.
Prototype
void GRAPH_SetUserDraw(GRAPH_Handle hObj,
void (* pUserDraw)(WM_HWIN hObj, int Stage));
Parameter
hObj
pUserDraw
Description
Handle of widget
Pointer to application function to be called by the widget during the drawing process.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
454
CHAPTER
Window Objects (Widgets)
Permitted values for parameter Stage
GRAPH_DRAW_FIRST
Function call after filling the background of the data
area. Gives the application for example the possibility to draw a user defined grid.
GRAPH_DRAW_LAST
Function call after drawing all graph items. Gives
the application for example the possibility to label
the data with a user defined scale.
Additional information
The user draw function is called at the beginning after filling the background of the
data area and after drawing all graph items like described at the beginning of the
chapter. On the first call the clipping region is limited to the data area. On the last
call it is limited to the complete graph widget area except the effect frame.
Example
The following small example shows the use of a user draw function:
static void _UserDraw(WM_HWIN hWin, int Stage) {
switch (Stage) {
case GRAPH_DRAW_FIRST:
/* Draw for example a user defined grid... */
break;
case GRAPH_DRAW_LAST:
/* Draw for example a user defined scale or additional text... */
break;
}
}
static void _CreateGraph(void) {
WM_HWIN hGraph;
hGraph = GRAPH_CreateEx(10, 10, 216, 106, WM_HBKWIN, WM_CF_SHOW, 0, GUI_ID_GRAPH0);
GRAPH_SetUserDraw(hGraph, _UserDraw); /* Enable user draw */
...
}
GRAPH_SetVSizeX(), GRAPH_SetVSizeY()
Before
After
Description
The functions set the virtual size in X and Y-axis.
Prototypes
unsigned GRAPH_SetVSizeX(GRAPH_Handle hObj, unsigned Value);
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
455
unsigned GRAPH_SetVSizeY(GRAPH_Handle hObj, unsigned Value);
Parameter
hObj
Value
Description
Handle of widget.
Virtual size in pixels in X or Y axis.
Return value
Previous virtual size of the widgets data area in X or Y-axis.
Additional information
If the widgets virtual size is bigger than the visible size of the data area, the widget
automatically shows a scrollbar. If for example a data object, created by the function
GRAPH_DATA_YT_Create(), contains more data than can be shown in the data area,
the function GRAPH_SetVSizeX() can be used to enable scrolling. A function call like
GRAPH_SetVSizeX(NumDataItems) enables the horizontal scrollbar, provided that the
number of data items is bigger than the X-size of the visible data area.
17.9.7.2 GRAPH_DATA_YT related routines
GRAPH_DATA_YT_AddValue()
Before
After
Description
Adds a new data item to a GRAPH_DATA_YT object.
Prototype
void GRAPH_DATA_YT_AddValue(GRAPH_DATA_Handle hDataObj, I16 Value);
Parameter
hDataObj
Value
Description
Handle of data object.
Value to be added to the data object.
Additional information
The given data value is added to the data object. If the data object is ’full’, that
means it contains as many data items as specified in parameter MaxNumItems during
the creation, it first shifts the data items by one before adding the new value. So the
first data item is shifted out when adding a data item to a ’full’ object.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
456
CHAPTER
Window Objects (Widgets)
The value 0x7FFF can be used to handle invalid data values. These values are
excluded when drawing the graph. The following screenshot shows a graph with 2
gaps of invalid data:
GRAPH_DATA_YT_Clear()
Before
After
Description
Clears all data items of the data object.
Prototype
void GRAPH_DATA_YT_Clear(GRAPH_DATA_Handle hDataObj);
Parameter
hDataObj
Description
Handle of data object.
GRAPH_DATA_YT_Create()
Description
Creates a GRAPH_DATA_YT object. This kind of object requires for each point on the xaxis a value on the y-axis. Typically used for time related graphs.
Prototype
GRAPH_DATA_Handle GRAPH_DATA_YT_Create(GUI_COLOR
Color,
unsigned
MaxNumItems,
I16
* pData,
unsigned
NumItems);
Parameter
Color
MaxNumItems
Description
Color to be used to draw the data.
Maximum number of data items.
pData
Pointer to data to be added to the object. The pointer should point to an array of
values.
NumItems
Number of data items to be added.
I16
Return value
Handle of data object if creation was successful, otherwise 0.
Additional information
The last data item is shown at the rightmost column of the data area. If a data object
contains more data as can be shown in the data area of the graph widget, the function GRAPH_SetVSizeX() can be used to show a scrollbar which makes it possible to
scroll through large data objects.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
457
Once attached to a graph widget a data object needs not to be deleted by the application. This is automatically done during the deletion of the graph widget.
GRAPH_DATA_YT_Delete()
Description
Deletes the given data object.
Prototype
void GRAPH_DATA_YT_Delete(GRAPH_DATA_Handle hDataObj);
Parameter
hDataObj
Description
Data object to be deleted.
Additional information
When a graph widget is deleted it deletes all currently attached data objects. So the
application needs only to delete unattached data objects.
GRAPH_DATA_YT_MirrorX()
Before
After
Description
Mirrors the x-axis of the widget.
Prototype
void GRAPH_DATA_YT_MirrorX(GRAPH_DATA_Handle hDataObj, int Value);
Parameter
hDataObj
OnOff
Description
Handle of data object.
1 for mirroring the x-axis, 0 for default view.
Additional information
Per default the data is drawn from the right to the left. After calling this function the
data is drawn from the left to the right.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
458
CHAPTER
Window Objects (Widgets)
GRAPH_DATA_YT_SetAlign()
Before
After
Description
Sets the alignment of the data.
Prototype
void GRAPH_DATA_YT_SetAlign(GRAPH_DATA_Handle hDataObj, int Align);
Parameter
hDataObj
Align
Description
Handle of data object.
(see table below)
Permitted values for parameter Align
GRAPH_ALIGN_RIGHT The data is aligned at the right edge (default).
GRAPH_ALIGN_LEFT The data is aligned at the left edge.
GRAPH_DATA_YT_SetOffY()
Before
After
Description
Sets a vertical offset used to draw the object data.
Prototype
void GRAPH_DATA_YT_SetOffY(GRAPH_DATA_Handle hDataObj, int Off);
Parameter
hDataObj
Off
Description
Handle of data object.
Vertical offset which should be used to draw the data.
Additional information
The vertical range of data, which is shown by the data object, is the range (0) - (Ysize of data area - 1). In case of using a scroll bar the current scroll position is added
to the range.
Example
If for example the visible data range should be -200 to -100 the data needs to be
shifted in positive direction by 200 pixels:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
459
GRAPH_DATA_YT_SetOffY(hDataObj, 200);
17.9.7.3 GRAPH_DATA_XY related routines
GRAPH_DATA_XY_AddPoint()
Before
After
Description
Adds a new data item to a GRAPH_DATA_XY object.
Prototype
void GRAPH_DATA_XY_AddPoint(GRAPH_DATA_Handle hDataObj, GUI_POINT * pPoint);
Parameter
hDataObj
pPoint
Description
Handle of data object.
Pointer to a GUI_POINT structure to be added to the data object.
Additional information
The given point is added to the data object. If the data object is ’full’, that means it
contains as many points as specified in parameter MaxNumItems during the creation,
it first shifts the data items by one before adding the new point. So the first point is
shifted out when adding a new point to a ’full’ object.
GRAPH_DATA_XY_Create()
Description
Creates a GRAPH_DATA_XY object. This kind of object is able to store any pairs of values
which will be connected by adding order.
Prototype
GRAPH_DATA_Handle GRAPH_DATA_XY_Create(GUI_COLOR
Color,
unsigned
MaxNumItems,
GUI_POINT * pData,
unsigned
NumItems);
Parameter
Color
MaxNumItems
Description
Color to be used to draw the data.
Maximum number of points.
pData
Pointer to data to be added to the object. The pointer should point to a
array.
NumItems
Number of points to be added.
User's & reference manual for emWin V5.10
GUI_POINT
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
460
CHAPTER
Window Objects (Widgets)
Return value
Handle of data object if creation was successful, otherwise 0.
Additional information
Once attached to a graph widget a data object needs not to be deleted by the application. This is automatically done during the deletion of the graph widget.
GRAPH_DATA_XY_Delete()
Description
Deletes the given data object.
Prototype
void GRAPH_DATA_XY_Delete(GRAPH_DATA_Handle hDataObj);
Parameter
hDataObj
Description
Data object to be deleted.
Additional information
When a graph widget is deleted it deletes all currently attached data objects. So the
application needs only to delete unattached data objects.
GRAPH_DATA_XY_SetOffX(), GRAPH_DATA_XY_SetOffY()
Before
After
Description
Sets a vertical or horizontal offset used to draw the polyline.
Prototype
void GRAPH_DATA_XY_SetOffX(GRAPH_DATA_Handle hDataObj, int Off);
void GRAPH_DATA_XY_SetOffY(GRAPH_DATA_Handle hDataObj, int Off);
Parameter
hDataObj
Off
Description
Handle of data object.
Horizontal/vertical offset which should be used to draw the polyline.
Additional information
The range of data shown by the data object is (0, 0) - (X-size of data area - 1, Y-size
of data area - 1). In case of using scroll bars the current scroll position is added to
the respective range. To make other ranges of data visible this functions should be
used to set an offset, so that the data is in the visible area.
Example
If for example the visible data range should be (100, -1200) - (200, -1100) the following offsets need to be used:
GRAPH_DATA_XY_SetOffX(hDataObj, -100);
GRAPH_DATA_XY_SetOffY(hDataObj, 1200);
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
461
GRAPH_DATA_XY_SetOwnerDraw()
Description
Sets the owner callback function. This function is called by the widget during the drawing
process to give the application the possibility to draw additional items on top of the widget.
Prototype
void GRAPH_DATA_XY_SetOwnerDraw(GRAPH_DATA_Handle hDataObj,
void (* pOwnerDraw)(const WIDGET_ITEM_DRAW_INFO * pDrawItemInfo));
Parameter
hDataObj
pOwnerDraw
Description
Data object to be deleted.
Pointer to application function to be called by the widget during the drawing process.
Additional information
The owner draw function is called after background, scales and grid lines are drawn.
Example
The following code snippet shows an example of an user draw function:
static int _cbData(const WIDGET_ITEM_DRAW_INFO * pDrawItemInfo) {
switch (pDrawItemInfo->Cmd) {
case WIDGET_ITEM_DRAW:
GUI_DrawRect(pDrawItemInfo->x0 - 3, pDrawItemInfo->y0 - 3,
pDrawItemInfo->x0 + 3, pDrawItemInfo->y0 + 3);
break;
}
return 0;
}
void MainTask(void) {
WM_HWIN
hGraph;
GRAPH_DATA_Handle hData;
GUI_Init();
hGraph = GRAPH_CreateEx (140, 100, 171, 131, 0, WM_CF_SHOW, 0, GUI_ID_GRAPH0);
hData = GRAPH_DATA_XY_Create(USER_DEFINED_COLOR, 126, 0, 0);
GRAPH_DATA_XY_SetOwnerDraw(hData, _cbData);
}
GRAPH_DATA_XY_SetLineStyle()
Before
After
Description
Sets the line style used to draw the polyline.
Prototype
void GRAPH_DATA_XY_SetLineStyle(GRAPH_DATA_Handle hDataObj, U8 LineStyle);
Parameter
Description
hDataObj
Handle of data object.
LineStyle
New line style to be used. For details about the supported line styles, refer to
“GUI_SetLineStyle()” on page 125.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
462
CHAPTER
Window Objects (Widgets)
Limitations
Note that only curves with line style GUI_LS_SOLID (default) can be drawn with a pen
size >1.
GRAPH_DATA_XY_SetPenSize()
Before
After
Description
Sets the pen size used to draw the polyline.
Prototype
void GRAPH_DATA_XY_SetPenSize(GRAPH_DATA_Handle hDataObj, U8 PenSize);
Parameter
hDataObj
PenSize
Description
Handle of data object.
Pen size which should be used to draw the polyline.
Limitations
Note that only curves with line style GUI_LS_SOLID (default) can be drawn with a pen
size >1.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
463
17.9.7.4 Scale related routines
The graph widget supports horizontal and vertical scales for labeling purpose. The
following describes the available functions for using scales.
GRAPH_SCALE_Create()
Description
Creates a scale object.
Prototype
GRAPH_SCALE_Handle GRAPH_SCALE_Create(int
Pos,
int
Align,
unsigned Flags, unsigned TickDist);
Parameter
Description
Pos
Position relative to the left/top edge of the graph widget.
TextAlign
Text alignment used to draw the numbers. For details, refer to “GUI_GetTextAlign()”
on page 81.
Flags
TickDist
(see table below)
Distance from one tick mark to the next.
Permitted values for parameter Flags
GRAPH_SCALE_CF_HORIZONTAL
GRAPH_SCALE_CF_VERTICAL
Creates a horizontal scale object.
Creates a vertical scale object.
Return value
Handle of the scale object if creation was successful, otherwise 0.
Additional information
A horizontal scale object starts labeling from the bottom edge of the data area to the
top and a vertical scale object from the left edge (horizontal scale) to the right,
where the first position is the zero point. The parameter TickDist specifies the distance between the numbers.
The parameter Pos specifies in case of a horizontal scale the vertical distance in pixels from the top edge of the graph widget to the scale text. In case of a vertical scale
the parameter specifies the horizontal distance from the left edge of the graph widget
to the horizontal text position. Note that the actual text position also depends on the
text alignment specified with parameter TextAlign.
The scale object draws a number for each position which is within the data area. In
case of a horizontal scale there is one exception: If the first position is 0 no number
is drawn at this position.
Once attached to a graph widget a scale object needs not to be deleted by the application. This is automatically done during the deletion of the graph widget.
GRAPH_SCALE_Delete()
Description
Deletes the given scale object.
Prototype
void GRAPH_SCALE_Delete(GRAPH_SCALE_Handle hScaleObj);
Parameter
hScaleObj
Description
Scale object to be deleted.
Additional information
When a graph widget is deleted it deletes all currently attached scale objects. So the
application needs only to delete unattached scale objects.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
464
CHAPTER
Window Objects (Widgets)
GRAPH_SCALE_SetFactor()
Before
After
Description
Sets a factor used to calculate the numbers to be drawn.
Prototype
float GRAPH_SCALE_SetFactor(GRAPH_SCALE_Handle hScaleObj, float Factor);
Parameter
hScaleObj
Factor
Description
Handle of scale object.
Factor to be used to calculate the number.
Return value
Old factor used to calculate the numbers.
Additional information
Without using a factor the unit of the scale object is ’pixel’. So the given factor should
convert the pixel value to the desired unit.
GRAPH_SCALE_SetFont()
Before
After
Description
Sets the font used to draw the scale numbers.
Prototype
const GUI_FONT * GRAPH_SCALE_SetFont(GRAPH_SCALE_Handle
hScaleObj,
const GUI_FONT
* pFont);
Parameter
hScaleObj
pFont
Description
Handle of scale object.
Font to be used.
Return value
Previous used font used to draw the numbers.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
465
GRAPH_SCALE_SetNumDecs()
Before
After
Description
Sets the number of post decimal positions to be shown.
Prototype
int GRAPH_SCALE_SetNumDecs(GRAPH_SCALE_Handle hScaleObj, int NumDecs);
Parameter
hScaleObj
NumDecs
Description
Handle of scale object.
Number of post decimal positions.
Return value
Previous number of post decimal positions.
GRAPH_SCALE_SetOff()
Before
After
Description
Sets an offset used to ’shift’ the scale object in positive or negative direction.
Prototype
int GRAPH_SCALE_SetOff(GRAPH_SCALE_Handle hScaleObj, int Off);
Parameter
hScaleObj
Off
Description
Handle of scale object.
Offset used for drawing the scale.
Return value
Previous used offset.
Additional information
As described under the function GRAPH_SCALE_Create() a horizontal scale object
starts labeling from the bottom edge of the data area to the top and a vertical scale
object from the left edge (horizontal scale) to the right, where the first position is the
zero point. In many situations it is not desirable, that the first position is the zero
point. If the scale should be ’shifted’ in positive direction, a positive offset should be
added, for negative direction a negative value.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
466
CHAPTER
Window Objects (Widgets)
GRAPH_SCALE_SetPos()
Before
After
Description
Sets the position for showing the scale object within the graph widget.
Prototype
int GRAPH_SCALE_SetPos(GRAPH_SCALE_Handle hScaleObj, int Pos);
Parameter
hScaleObj
Pos
Description
Handle of scale object.
Position, at which the scale should be shown.
Return value
Previous position of the scale object.
Additional information
The parameter Pos specifies in case of a horizontal scale the vertical distance in pixels from the top edge of the graph widget to the scale text. In case of a vertical scale
the parameter specifies the horizontal distance from the left edge of the graph widget
to the horizontal text position. Note that the actual text position also depends on the
text alignment of the scale object.
GRAPH_SCALE_SetTextColor()
Before
After
Description
Sets the text color used to draw the numbers.
Prototype
GUI_COLOR GRAPH_SCALE_SetTextColor(GRAPH_SCALE_Handle hScaleObj,
GUI_COLOR
Color);
Parameter
hScaleObj
Color
Description
Handle of scale object.
Color to be used to show the numbers.
Return value
Previous color used to show the numbers.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
467
GRAPH_SCALE_SetTickDist()
Before
After
Description
Sets the distance from one number to the next.
Prototype
unsigned GRAPH_SCALE_SetTickDist(GRAPH_SCALE_Handle hScaleObj,
unsigned
Dist);
Parameter
hScaleObj
Dist
Description
Handle of scale object.
Distance in pixels between the numbers.
Return value
Previous distance between the numbers.
17.9.8 Examples
The Sample folder contains the following examples which show how the widget can be
used:
•
WIDGET_GraphXY.c
•
WIDGET_GraphYT.c
Note that several other examples also make use of this widget and may also be helpful to get familiar with the widget.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
468
CHAPTER
Window Objects (Widgets)
Screen shot of WIDGET_GraphXY.c:
Screen shot of WIDGET_GraphYT.c:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
469
17.10 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.
Screenshot of drag-able divider
Predefined cursors
There are 2 predefined cursors as shown below:
GUI_CursorHeaderM (default)
GUI_CursorHeaderMI
You can also create and use your own cursors when using a HEADER widget as
described later in this chapter.
Skinning...
...is available for this widget. The screenshot above shows the widget using the
default skin. For details please refer to chapter ’Skinning’.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
470
CHAPTER
Window Objects (Widgets)
17.10.1 Configuration options
Type
N
Macro
Default
Description
0xAAAAAA
S
HEADER_BKCOLOR_DEFAULT
HEADER_CURSOR_DEFAULT
HEADER_FONT_DEFAULT
&GUI_Font13_1
Default font
N
HEADER_BORDER_H_DEFAULT
2
Horizontal space between text and border
N
0
HEADER_BORDER_V_DEFAULT
1
HEADER_SUPPORT_DRAG
HEADER_TEXTCOLOR_DEFAULT GUI_BLACK
S
B
N
Default value of background color
&GUI_CursorHeaderM Default cursor
Vertical space between text and border
Enable/disable dragging support
Default value of text color
17.10.2 Notification codes
The following events are sent from a HEADER widget to its parent window as part of
a WM_NOTIFY_PARENT message:
Message
WM_NOTIFICATION_CLICKED
WM_NOTIFICATION_RELEASED
WM_NOTIFICATION_MOVED_OUT
Description
Widget has been clicked.
Widget has been released.
Widget has been clicked and pointer has been moved out
off of the widget without releasing.
17.10.3 Keyboard reaction
The widget can not gain the input focus and does not react on keyboard input.
17.10.4 HEADER API
The table below lists the available emWin HEADER-related routines in alphabetical
order. Detailed descriptions of the routines follow.
Routine
HEADER_AddItem()
HEADER_Create()
HEADER_CreateAttached()
HEADER_CreateEx()
HEADER_CreateIndirect()
HEADER_CreateUser()
HEADER_GetDefaultBkColor()
HEADER_GetDefaultBorderH()
HEADER_GetDefaultBorderV()
HEADER_GetDefaultCursor()
HEADER_GetDefaultFont()
HEADER_GetDefaultTextColor()
HEADER_GetHeight()
HEADER_GetItemWidth()
HEADER_GetNumItems()
HEADER_GetUserData()
HEADER_SetBitmap()
HEADER_SetBitmapEx()
HEADER_SetBkColor()
HEADER_SetBMP()
HEADER_SetBMPEx()
HEADER_SetDefaultBkColor()
User's & reference manual for emWin V5.10
Description
Adds one item at the right side
Creates a HEADER widget. (Obsolete)
Creates a HEADER widget attached to a window
Creates a HEADER widget.
Creates a HEADER widget from a resource table entry
Creates a HEADER widget using extra bytes as user data.
Returns the default background color
Returns the value of the horizontal spacing.
Returns the value of the vertical spacing.
Returns the a pointer to the default cursor.
Returns a pointer to the default font.
Returns the default text color.
Returns the height of the widget.
Returns the item width.
Returns the number of items.
Retrieves the data set with HEADER_SetUserData().
Sets the bitmap used when displaying the given item.
Sets the bitmap used when displaying the given item.
Sets the background color of the widget.
Sets the bitmap used when displaying the given item.
Sets the bitmap used when displaying the given item.
Sets the default background color.
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
471
Routine
Description
HEADER_SetDefaultBorderH()
HEADER_SetDefaultBorderV()
HEADER_SetDefaultCursor()
HEADER_SetDefaultFont()
HEADER_SetDefaultTextColor()
HEADER_SetDragLimit()
HEADER_SetFont()
HEADER_SetHeight()
HEADER_SetItemText()
HEADER_SetItemWidth()
HEADER_SetStreamedBitmap()
HEADER_SetStreamedBitmapEx()
HEADER_SetTextAlign()
HEADER_SetTextColor()
HEADER_SetUserData()
Sets the default value for the horizontal spacing.
Sets the default value for the vertical spacing.
Sets the default cursor.
Sets the default font.
Sets the default text color.
Sets the limit for dragging the items on or off.
Sets the font of the widget.
Sets the height of the widget.
Sets the text of a given item.
Sets the width of a given item.
Sets the bitmap used when displaying the given item.
Sets the bitmap used when displaying the given item.
Sets the alignment of the given item.
Sets the Text color of the widget.
Sets the extra data of a HEADER widget.
HEADER_AddItem()
Description
Adds an item to an already existing HEADER widget.
Prototype
void HEADER_AddItem(HEADER_Handle
hObj, int Width,
const char
* s,
int Align);
Parameter
hObj
Width
s
Align
Description
Handle of widget
Width of the new item
Text to be displayed
Text alignment mode to set. May be a combination of a horizontal and a vertical
alignment flag.
Permitted values for parameter Align
(horizontal and vertical flags are OR-combinable)
Horizontal alignment
GUI_TA_LEFT
GUI_TA_HCENTER
GUI_TA_RIGHT
Align X-position left (default).
GUI_TA_TOP
GUI_TA_VCENTER
GUI_TA_BOTTOM
Align Y-position with top of characters (default).
Center X-position.
Align X-position right (default).
Vertical alignment
Center Y-position.
Align Y-position with bottom pixel line of font.
Additional information
The Width-parameter can be 0. If Width = 0 the width of the new item will be calculated by the given text and by the default value of the horizontal spacing.
HEADER_Create()
(Obsolete, HEADER_CreateEx() should be used instead)
Description
Creates a HEADER widget of a specified size at a specified location.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
472
CHAPTER
Window Objects (Widgets)
Prototype
HEADER_Handle HEADER_Create(int
int
WM_HWIN
int
x0,
xsize,
hParent,
Flags,
Parameter
x0
y0
xsize
ysize
hParent
Id
y0,
ysize,
Id,
SpecialFlags);
Description
Leftmost pixel of the HEADER widget (in parent coordinates).
Topmost pixel of the HEADER widget (in parent coordinates).
Horizontal size of the HEADER widget (in pixels).
Vertical size of the HEADER widget (in pixels).
Handle of the parent window
Id of the new HEADER widget
Window create flags. Typically
Flags
int
int
int
int
WM_CF_SHOW in order to make the widget visible
immediately (refer to WM_CreateWindow() in the chapter “The Window Manager
(WM)” on page 289 for a list of available parameter values).
SpecialFlags (Reserved for later use)
Return value
Handle of the created HEADER widget; 0 if the function fails.
HEADER_CreateAttached()
Description
Creates a HEADER widget which is attached to an existing window.
Prototype
HEADER_Handle HEADER_CreateAttached(WM_HWIN hParent,
int
Id,
int
SpecialFlags);
Parameter
Description
Handle of widget
hObj
Id of the HEADER widget
Id
SpecialFlags (Not used, reserved for later use)
Return value
Handle of the created HEADER widget; 0 if the function fails.
Additional information
An attached HEADER widget is essentially a child window which will position itself on
the parent window and operate accordingly.
HEADER_CreateEx()
Description
Creates a HEADER widget of a specified size at a specified location.
Prototype
HEADER_Handle HEADER_CreateEx(int
x0,
int y0,
int
xsize,
int ysize,
WM_HWIN hParent, int WinFlags,
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
473
int
ExFlags, int Id);
Parameter
x0
y0
xsize
ysize
hParent
Description
Leftmost pixel of the widget (in parent coordinates).
Topmost pixel of the widget (in parent coordinates).
Horizontal size of the widget (in pixels).
Vertical size of the widget (in pixels).
Handle of parent window. If 0, the new HEADER widget will be a child of the desktop
(top-level window).
Window create flags. Typically
WM_CF_SHOW in order to make the widget visible
WinFlags
immediately (refer to WM_CreateWindow() in the chapter “The Window Manager
(WM)” on page 289 for a list of available parameter values).
ExFlags
Id
Not used, reserved for future use.
Window ID of the widget.
Return value
Handle of the created HEADER widget; 0 if the function fails.
HEADER_CreateIndirect()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateIndirect().
HEADER_CreateUser()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateUser(). For
a detailed description of the parameters the function HEADER_CreateEx() can be
referred to.
HEADER_GetDefaultBkColor()
Description
Returns the default background color used when creating a HEADER widget.
Prototype
GUI_COLOR HEADER_GetDefaultBkColor(void);
Return value
Default background color used when creating a HEADER widget.
HEADER_GetDefaultBorderH()
Description
Returns the value used for the horizontal spacing when creating a HEADER widget. Horizontal spacing means the horizontal distance in pixel between text and the horizontal border of the item.
Prototype
int HEADER_GetDefaultBorderH(void);
Return value
Value used for the horizontal spacing when creating a HEADER widget.
Additional information
Horizontal spacing takes effect only if the given width of a new item is 0.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
474
CHAPTER
Window Objects (Widgets)
HEADER_GetDefaultBorderV()
Description
Returns the value used for the vertical spacing when creating a HEADER widget. Vertical
spacing means the vertical distance in pixel between text and the vertical border of the
HEADER widget.
Prototype
int HEADER_GetDefaultBorderV(void);
Return value
Value used for the vertical spacing when creating a HEADER widget.
HEADER_GetDefaultCursor()
Description
Returns a pointer to the cursor displayed when dragging the width of an item.
Prototype
const GUI_CURSOR * HEADER_GetDefaultCursor(void);
Return value
pointer to the cursor displayed when dragging the width of an item.
HEADER_GetDefaultFont()
Description
Returns a pointer to the default font used when creating a HEADER widget.
Prototype
const GUI_FONT * HEADER_GetDefaultFont(void);
Return value
Pointer to the default font used when creating a HEADER widget.
HEADER_GetDefaultTextColor()
Description
Returns the default text color used when creating a HEADER widget.
Prototype
GUI_COLOR HEADER_GetDefaultTextColor(void);
Return value
Default text color used when creating a HEADER widget.
HEADER_GetHeight()
Description
Returns the height of the given HEADER widget.
Prototype
int HEADER_GetHeight(HEADER_Handle hObj);
Parameter
hObj
Description
Handle of widget
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
475
Return value
Height of the given HEADER widget.
HEADER_GetItemWidth()
Description
Returns the item width of the given HEADER widget.
Prototype
int HEADER_GetItemWidth(HEADER_Handle hObj, unsigned int Index);
Parameter
hObj
Index
Description
Handle of widget
Index of the item
Return value
Width of the item.
HEADER_GetNumItems()
Description
Returns the number of items of the given HEADER widget.
Prototype
int HEADER_GetNumItems(HEADER_Handle hObj);
Parameter
hObj
Description
Handle of widget
Return value
Number of items of the given HEADER widget.
HEADER_GetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_GetUserData().
HEADER_SetBitmap()
Description
Sets the bitmap used when displaying the specified item.
Prototype
void HEADER_SetBitmap(HEADER_Handle
hObj,
unsigned int
Index,
const GUI_BITMAP * pBitmap);
Parameter
hObj
Index
pBitmap
Description
Handle of widget
Index of the item
Pointer to a bitmap structure to be displayed
Additional information
One item of a HEADER widget can contain text and a bitmap. (look at sample under
HEADER_SetBitmapEx)
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
476
CHAPTER
Window Objects (Widgets)
HEADER_SetBitmapEx()
Description
Sets the bitmap used when displaying the specified item.
Prototype
void HEADER_SetBitmapEx(HEADER_Handle
hObj,
unsigned int Index,
const GUI_BITMAP * pBitmap,
int
x,
int
y);
Parameter
hObj
Index
pBitmap
x
y
Description
Handle of widget
Index of the item
Pointer to a bitmap structure to be displayed
Additional offset in x
Additional offset in y
Additional information
One item of a HEADER widget can contain text and a bitmap.
Example:
...
HEADER_Handle hHeader;
GUI_Init();
HEADER_SetDefaultTextColor(GUI_YELLOW);
HEADER_SetDefaultFont(&GUI_Font8x8);
hHeader = HEADER_Create(10, 10, 100, 40, WM_HBKWIN, 1234, WM_CF_SHOW, 0);
HEADER_AddItem(hHeader, 50, "Phone", GUI_TA_BOTTOM | GUI_TA_HCENTER);
HEADER_AddItem(hHeader, 50, "Code" , GUI_TA_BOTTOM | GUI_TA_HCENTER);
HEADER_SetBitmapEx(hHeader, 0, &bmPhone, 0, -15);
HEADER_SetBitmapEx(hHeader, 1, &bmCode, 0, -15);
...
Screenshot of example above:
HEADER_SetBkColor()
Description
Sets the background color of the given HEADER widget.
Prototype
void HEADER_SetBkColor(HEADER_Handle hObj, GUI_COLOR Color);
Parameter
hObj
Color
Description
Handle of widget
Background color to be set
HEADER_SetBMP()
Description
Sets the bitmap used when displaying the specified item.
Prototype
void HEADER_SetBMP(HEADER_Handle
User's & reference manual for emWin V5.10
hObj,
unsigned int Index,
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
477
const void
* pBitmap);
Parameter
hObj
Index
pBitmap
Description
Handle of widget
Index of HEADER item
Pointer to bitmap file data
Additional information
For additional informations regarding bitmap files, refer to chapter “Displaying bitmap files” on page 141.
HEADER_SetBMPEx()
Description
Sets the bitmap used when displaying the specified item.
Prototype
void HEADER_SetBMPEx(HEADER_Handle
hObj,
unsigned int Index,
const void
* pBitmap,
int
x,
int
y);
Parameter
hObj
Index
pBitmap
x
y
Description
Handle of widget
Index of the item
Pointer to bitmap file data
Additional offset in x
Additional offset in y
Additional information
For additional informations regarding bitmap files, refer to chapter “Displaying bitmap files” on page 141.
HEADER_SetDefaultBkColor()
Description
Sets the default background color used when creating a HEADER widget.
Prototype
GUI_COLOR HEADER_SetDefaultBkColor(GUI_COLOR Color);
Parameter
Color
Description
Background color to be used
Return value
Previous default background color.
HEADER_SetDefaultBorderH()
Description
Sets the value used for the horizontal spacing when creating a HEADER widget. Horizontal
spacing means the horizontal distance in pixel between text and the horizontal border of
the item.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
478
CHAPTER
Window Objects (Widgets)
Prototype
int HEADER_SetDefaultBorderH(int Spacing);
Parameter
Spacing
Description
Value to be used
Return value
Previous default value.
Additional information
Horizontal spacing takes effect only if the given width of a new item is 0.
HEADER_SetDefaultBorderV()
Description
Sets the value used for the vertical spacing when creating a HEADER widget. Vertical
spacing means the vertical distance in pixel between text and the vertical border of the
HEADER widget.
Prototype
int HEADER_SetDefaultBorderV(int Spacing);
Parameter
Spacing
Description
Value to be used
Return value
Previous default value.
HEADER_SetDefaultCursor()
Description
Sets the cursor which will be displayed when dragging the width of an HEADER item.
Prototype
const GUI_CURSOR * HEADER_SetDefaultCursor(const GUI_CURSOR * pCursor);
Parameter
pCursor
Description
Pointer to the cursor to be shown when dragging the width of an HEADER item
Return value
Pointer to the previous default cursor.
Additional information
There are 2 predefined cursors shown at the beginning of this chapter.
HEADER_SetDefaultFont()
Description
Sets the default font used when creating a HEADER widget.
Prototype
const GUI_FONT * HEADER_SetDefaultFont(const GUI_FONT * pFont);
Parameter
pFont
Description
Pointer to font to be used
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
479
Return value
Pointer to previous default font.
HEADER_SetDefaultTextColor()
Description
Returns the default text color used when creating a HEADER widget.
Prototype
GUI_COLOR HEADER_SetDefaultTextColor(GUI_COLOR Color);
Parameter
Color
Description
Color to be used
Return value
Previous default value.
HEADER_SetDragLimit()
Description
Sets the limit for dragging the dividers on or off. If the limit is on, a divider can only be
dragged within the widget area. If the limit is off, it can be dragged outside the widget.
Prototype
void HEADER_SetDragLimit(HEADER_Handle hObj, unsigned OnOff);
Parameter
hObj
OnOff
Description
Handle of widget
1 for setting the drag limit on, 0 for off.
HEADER_SetFont()
Description
Sets the font used when displaying the given HEADER widget
Prototype
void HEADER_SetFont(HEADER_Handle hObj, const GUI_FONT * pFont);
Parameter
hObj
pFont
Description
Handle of widget
Pointer to font to be used
HEADER_SetHeight()
Description
Sets the height of the given HEADER widget.
Prototype
void HEADER_SetHeight(HEADER_Handle hObj, int Height);
Parameter
hObj
Height
Description
Handle of widget
New height
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
480
CHAPTER
Window Objects (Widgets)
HEADER_SetItemText()
Description
Sets the text used when displaying the specified item.
Prototype
void HEADER_SetItemText(HEADER_Handle
hObj, unsigned int Index,
const char
* s);
Parameter
hObj
Index
s
Description
Handle of widget
Index of HEADER item
Pointer to string to be displayed
Additional information
One HEADER item can contain a string and a bitmap.
HEADER_SetItemWidth()
Description
Sets the width of the specified HEADER item.
Prototype
void HEADER_SetItemWidth(HEADER_Handle hObj, unsigned int Index, int Width);
Parameter
hObj
Index
Width
Description
Handle of widget
Index of HEADER item
New width
HEADER_SetStreamedBitmap()
Description
Sets the bitmap used when displaying the specified item.
Prototype
void HEADER_SetStreamedBitmap(HEADER_Handle
hObj,
unsigned int
Index,
const GUI_BITMAP_STREAM * pBitmap);
Parameter
hObj
Index
pBitmap
Description
Handle of widget
Index of the item
Pointer to streamed bitmap data to be displayed
Additional information
For additional informations regarding streamed bitmap files, refer to the chapter “2D Graphic Library” on page 97.
HEADER_SetStreamedBitmapEx()
Description
Sets the bitmap used when displaying the specified item.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
481
Prototype
void HEADER_SetStreamedBitmapEx(HEADER_Handle
hObj,
unsigned int
Index,
const GUI_BITMAP_STREAM * pBitmap,
int
x,
int
y);
Parameter
hObj
Index
pBitmap
x
y
Description
Handle of widget
Index of the item
Pointer to streamed bitmap data to be displayed
Additional offset in x
Additional offset in y
Additional information
For additional informations regarding streamed bitmap files, refer to the chapter “2D Graphic Library” on page 97.
HEADER_SetTextAlign()
Description
Sets the text alignment of the specified HEADER item.
Prototype
void HEADER_SetTextAlign(HEADER_Handle hObj, unsigned int Index, int Align);
Parameter
hObj
Index
Align
Description
Handle of widget
Index of header item
Text alignment mode to set. May be a combination of a horizontal and a vertical
alignment flag.
Permitted values for parameter Align
(horizontal and vertical flags are OR-combinable)
Horizontal alignment
GUI_TA_LEFT
GUI_TA_HCENTER
GUI_TA_RIGHT
Align X-position left (default).
Center X-position.
Align X-position right (default).
Vertical alignment
GUI_TA_TOP
GUI_TA_VCENTER
GUI_TA_BOTTOM
Align Y-position with top of characters (default).
Center Y-position.
Align Y-position with bottom pixel line of font.
HEADER_SetTextColor()
Description
Sets the text color used when displaying the widget.
Prototype
void HEADER_SetTextColor(HEADER_Handle hObj, GUI_COLOR Color);
Parameter
hObj
Color
Description
Handle of widget
Color to be used
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
482
CHAPTER
Window Objects (Widgets)
HEADER_SetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_SetUserData().
17.10.5 Example
The Sample folder contains the following example which shows how the widget can be
used:
•
WIDGET_Header.c
Note that several other examples also make use of this widget and may also be helpful to get familiar with the widget.
Screen shot of WIDGET_Header.c:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
483
17.11 ICONVIEW: Icon view widget
The icon view widget can be used for icon based menus often required in hand held
devices like mobile telephones or pocket organizers. It shows a list of icons where
each icon can be labeled with optional text. Icon view widgets support transparency
and alpha blending. So any content can be shown in the background. The currently
selected icon can be highlighted by a solid color or with an alpha blending effect,
which lets the background shine through. If required a scrollbar can be shown.
ICONVIEW with transparency
ICONVIEW without transparency
All ICONVIEW-related routines are in the file(s) ICONVIEW*.c, ICONVIEW*.h. All identifiers are prefixed ICONVIEW.
17.11.1 Configuration options
Type
N
Macro
Default
Description
GUI_WHITE
Background color, unselected state.
GUI_BLUE
Background color, selected state.
GUI_WHITE
Text color, unselected state.
GUI_WHITE
Text color, selected state.
S
ICONVIEW_BKCOLOR0_DEFAULT
ICONVIEW_BKCOLOR1_DEFAULT
ICONVIEW_TEXTCOLOR0_DEFAULT
ICONVIEW_TEXTCOLOR1_DEFAULT
ICONVIEW_FONT_DEFAULT
GUI_Font13_1
Font to be used for drawing the labels.
N
ICONVIEW_FRAMEX_DEFAULT
5
Free space between the icons and the
left and right border of the widget.
N
ICONVIEW_FRAMEY_DEFAULT
5
Free space between the icons and the
top and bottom border of the widget.
N
ICONVIEW_SPACEX_DEFAULT
5
Free horizontal space between the
icons.
N
ICONVIEW_SPACEY_DEFAULT
5
Free vertical space between the icons.
ICONVIEW_ALIGN_DEFAULT
GUI_TA_HCENTER Default alignment to be used for draw| GUI_TA_BOTTOM ing the labels.
N
N
N
N
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
484
CHAPTER
Window Objects (Widgets)
17.11.2 Notification codes
The following events are sent from an ICONVIEW widget to its parent window as part
of a WM_NOTIFY_PARENT message:
Message
Description
WM_NOTIFICATION_CLICKED
WM_NOTIFICATION_RELEASED
Widget has been clicked.
Widget has been released.
WM_NOTIFICATION_MOVED_OUT
Widget has been clicked and pointer has been moved out
off of the widget area without releasing.
WM_NOTIFICATION_SCROLL_CHANGED
The scroll position of the optional scrollbar has been
changed.
WM_NOTIFICATION_SEL_CHANGED
The selection of the widget has been changed.
17.11.3 Keyboard reaction
The widget reacts to the following keys if it has the input focus:
Key
Reaction
Moves the selection to the next icon.
GUI_KEY_RIGHT
GUI_KEY_LEFT
GUI_KEY_DOWN
GUI_KEY_UP
GUI_KEY_HOME
GUI_KEY_END
Moves the selection to the previous icon.
Moves the selection down.
Moves the selection up.
Moves the selection to the first icon.
Moves the selection to the last icon.
17.11.4 ICONVIEW API
The table below lists the available emWin ICONVIEW-related routines in alphabetical
order. Detailed descriptions of the routines follow.
Routine
Description
ICONVIEW_AddBitmapItem()
Adds a new icon to the ICONVIEW widget.
ICONVIEW_AddStreamedBitmapItem()
Adds a new icon to the ICONVIEW widget using a
streamed bitmap.
ICONVIEW_CreateEx()
Creates an ICONVIEW widget.
ICONVIEW_CreateIndirect()
Creates an ICONVIEW widget from a resource table
entry.
ICONVIEW_CreateUser()
Creates an ICONVIEW widget using extra bytes as
user data.
ICONVIEW_DeleteItem()
ICONVIEW_GetItemText()
ICONVIEW_GetItemUserData()
ICONVIEW_GetNumItems()
ICONVIEW_GetSel()
Deletes an existing item.
Retrieves the text of a specified icon view item.
Retrieves the previously stored user data from a
specific item.
Returns the number of items in the given icon view.
Returns the index of the currently selected icon.
ICONVIEW_GetUserData()
Retrieves the data set with
ICONVIEW_SetUserData().
ICONVIEW_InsertBitmapItem()
Inserts a new icon to the icon view widget at the
given position.
ICONVIEW_InsertStreamedBitmapItem()
Inserts a new icon to the icon view widget at the
given position using a streamed bitmap.
ICONVIEW_SetBitmapItem()
ICONVIEW_SetBkColor()
ICONVIEW_SetFont()
Sets a bitmap to be used by a specific item.
Sets the background color.
Sets the font to be used for drawing the labels.
ICONVIEW_SetFrame()
Sets the size of the frame between the border of
the widget and the icons.
ICONVIEW_SetItemText()
Sets the text of a specific item.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
485
Routine
Description
Stores user data in a specific item.
ICONVIEW_SetItemUserData()
ICONVIEW_SetSel()
ICONVIEW_SetSpace()
ICONVIEW_SetStreamedBitmapItem()
ICONVIEW_SetTextAlign()
ICONVIEW_SetTextColor()
ICONVIEW_SetUserData()
Sets the current selection.
Sets the space between icons in x- or y-direction.
Sets the current selection.
Sets the color to be used to draw the labels.
Sets the color to be used to draw the labels.
Sets the extra data of an ICONVIEW widget.
ICONVIEW_AddBitmapItem()
Before
After
Description
Adds a new bitmap icon to the widget.
Prototype
int ICONVIEW_AddBitmapItem(ICONVIEW_Handle
hObj,
const GUI_BITMAP * pBitmap,
const char
* pText);
Parameter
hObj
pBitmap
pText
Description
Handle of the widget.
Pointer to a bitmap structure used to draw the icon.
Text to be used to label the icon.
Return value
0 on success, !=0 on error.
Additional information
Note that the bitmap pointer needs to remain valid.
ICONVIEW_AddStreamedBitmapItem()
Before
After
Description
Adds a new streamed bitmap icon to the widget.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
486
CHAPTER
Window Objects (Widgets)
Prototype
int ICONVIEW_AddStreamedBitmapItem(ICONVIEW_Handle
hObj,
const void
* pStreamedBitmap,
const char
* pText);
Parameter
Description
hObj
pStreamedBitmap
pText
Handle of the widget.
Pointer to a bitmap stream used to draw the icon.
Text to be used to label the icon.
Return value
0 on success, !=0 on error.
Additional information
The pointer to the bitmap stream needs to remain valid.
ICONVIEW_CreateEx()
Description
Creates an ICONVIEW widget of a specified size at a specified location.
Prototype
ICONVIEW_Handle ICONVIEW_CreateEx(int
int
WM_HWIN
int
int
Parameter
x0
y0
xSize
ySize
x0,
xSize,
hParent,
ExFlags,
xSizeItem,
int
int
int
int
int
y0,
ySize,
WinFlags,
Id,
ySizeItem);
Description
Leftmost pixel of the widget in parent coordinates.
Topmost pixel of the widget in parent coordinates.
Horizontal size of the widget in pixels.
Vertical size of the widget in pixels.
hParent
Handle of parent window. If 0, the new widget will be a child window of the desktop
(top-level window).
WinFlags
Window create flags. Typically WM_CF_SHOW in order to make the widget visible
immediately (refer to “WM_CreateWindow()” on page 309 for a list of available
parameter values).
ExFlags
Id
xSizeItem
ySizeItem
(see table below)
Window ID of the widget.
Horizontal icon size in pixels.
Vertical icon size in pixels.
Permitted values for parameter ExFlags
0
(default)
ICONVIEW_CF_AUTOSCROLLBAR_V
A vertical scrollbar will be added if the
widget area is too small to show all icons.
Return value
Handle of the new widget, 0 if the function fails.
Additional information
If the widget should be transparent, the parameter WinFlags should be or-combined
with WM_CF_HASTRANS.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
487
ICONVIEW_CreateIndirect()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateIndirect().
ICONVIEW_CreateUser()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateUser(). For
a detailed description of the parameters the function ICONVIEW_CreateEx() can be
referred to.
ICONVIEW_DeleteItem()
Description
Deletes an existing item of the ICONVIEW widget.
Prototype
void ICONVIEW_DeleteItem(ICONVIEW_Handle hObj, unsigned Index);
Parameter
hObj
Index
Description
Handle of the widget.
Index of the item to be deleted.
ICONVIEW_GetItemText()
Description
Retrieves the text of a specified icon view item.
Prototype
int ICONVIEW_GetItemText(ICONVIEW_Handle hObj,
int Index,
char *
pBuffer, int MaxSize);
Parameter
hObj
Index
pBuffer
MaxSize
Description
Handle of the widget.
Index of the item to be deleted.
Buffer to retrieve the text.
Maximum length of text to copy to the buffer.
Return value
The length of the actually copied text is returned.
ICONVIEW_GetItemUserData()
Description
Retrieves the previously stored user data from a specific item.
Prototype
U32 ICONVIEW_GetItemUserData(ICONVIEW_Handle hObj, int Index);
Parameter
hObj
Index
Description
Handle of the widget.
Index of the item.
Return value
User data stored in the item as U32.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
488
CHAPTER
Window Objects (Widgets)
ICONVIEW_GetNumItems()
Description
Returns the number of items in the given icon view.
Prototype
int ICONVIEW_GetNumItems(ICONVIEW_Handle hObj);
Parameter
hObj
Description
Handle of the widget.
Return value
Number of items.
ICONVIEW_GetSel()
Description
Returns the zero based index of the currently selected icon.
Prototype
int ICONVIEW_GetSel(ICONVIEW_Handle hObj);
Parameter
hObj
Description
Handle of widget.
Return value
Zero based index of the currently selected icon.
ICONVIEW_GetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_GetUserData().
ICONVIEW_InsertBitmapItem()
Description
Inserts a new bitmap icon to the widget. See “ICONVIEW_AddBitmapItem()” on
page 485 for screenshots.
Prototype
int ICONVIEW_InsertBitmapItem(ICONVIEW_Handle
hObj,
const GUI_BITMAP * pBitmap,
const char
* pText
int
Index);
Parameter
hObj
pBitmap
pText
Index
Description
Handle of the widget.
Pointer to a bitmap structure used to draw the icon.
Text to be used to label the icon.
Index position to insert the item at.
Return value
0 on success, !=0 on error.
Additional information
Note that the bitmap pointer needs to remain valid.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
489
ICONVIEW_InsertStreamedBitmapItem()
Description
Inserts
a
new
streamed
bitmap
icon
to
“ICONVIEW_AddBitmapItem()” on page 485 for screenshots.
the
widget.
See
Prototype
int ICONVIEW_InsertStreamedBitmapItem(ICONVIEW_Handle
hObj,
const void
* pStreamedBitmap,
const char
* pText,
int
Index);
Parameter
Description
hObj
pStreamedBitmap
pText
Index
Handle of the widget.
Pointer to a bitmap stream used to draw the icon.
Text to be used to label the icon.
Index position to insert the item at.
Return value
0 on success, !=0 on error.
Additional information
The pointer to the bitmap stream needs to remain valid.
ICONVIEW_SetBitmapItem()
Before
After
Description
Sets a bitmap to be used by a specific item.
Prototype
void ICONVIEW_SetBitmapItem(ICONVIEW_Handle
hObj,
int
Index,
const GUI_BITMAP * pBitmap);
Parameter
hObj
Index
pBitmap
Description
Handle of widget.
Index of the item.
Pointer to the bitmap to be used.
Additional information
The pointer to the bitmap structure needs to remain valid.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
490
CHAPTER
Window Objects (Widgets)
ICONVIEW_SetBkColor()
Before
After
Description
Sets the background color of the widget.
Prototype
void ICONVIEW_SetBkColor(ICONVIEW_Handle hObj, int Index, GUI_COLOR Color);
Parameter
hObj
Index
Color
Description
Handle of widget.
(see table below)
Color to be used for drawing the background.
Permitted values for parameter Index
ICONVIEW_CI_BK
ICONVIEW_CI_SEL
Color used to draw the widget background.
Color used to highlight the currently selected item.
Additional information
The upper 8 bits of the 32 bit color value can be used for an alpha blending effect.
For more details about alpha blending, refer to “GUI_SetAlpha()” on page 111.
ICONVIEW_SetFont()
Before
After
Description
Sets the font to be used for drawing the icon labels.
Prototype
void ICONVIEW_SetFont(ICONVIEW_Handle
hObj,
const GUI_FONT GUI_UNI_PTR * pFont);
Parameter
hObj
pFont
Description
Handle of widget.
Pointer to a GUI_FONT structure to be used to draw the icon labels.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
491
ICONVIEW_SetFrame()
Before
After
Description
Sets the size of the frame between the border of the widget and the icons.
Prototype
void ICONVIEW_SetFrame(ICONVIEW_Handle hObj,
int
Coord,
int
Value);
Parameter
hObj
Coord
Value
Description
Handle of the widget.
See permitted values for this parameter below.
Distance to be set.
Permitted values for parameter Coord
GUI_COORD_X
GUI_COORD_Y
X-direction.
Y-direction.
ICONVIEW_SetItemText()
Before
After
Description
Sets the text of a specific item.
Prototype
void ICONVIEW_SetItemText(ICONVIEW_Handle
hObj,
int
Index,
const char
* pText);
Parameter
hObj
Index
pText
Description
Handle of the widget.
Index of the item.
Pointer to the text to be used.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
492
CHAPTER
Window Objects (Widgets)
ICONVIEW_SetItemUserData()
Description
Stores user data in a specific item.
Prototype
void ICONVIEW_SetItemUserData(ICONVIEW_Handle hObj,
int
Index,
U32
UserData);
Parameter
hObj
Index
UserData
Description
Handle of widget.
Index of the item.
32 bit user data to be stored.
ICONVIEW_SetSel()
Before
After
Description
Sets the current selection.
Prototype
void ICONVIEW_SetSel(ICONVIEW_Handle hObj, int Sel);
Parameter
hObj
Sel
Description
Handle of widget.
New selection.
ICONVIEW_SetSpace()
Before
After
Description
Sets the space between icons in x- or y-direction.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
493
Prototype
void ICONVIEW_SetSpace(ICONVIEW_Handle hObj, int Coord, int Value);
Parameter
hObj
Coord
Value
Description
Handle of the widget.
See permitted values for this parameter below.
Distance to be set.
Permitted values for parameter Coord
GUI_COORD_X
GUI_COORD_Y
X-direction.
Y-direction.
ICONVIEW_SetStreamedBitmapItem()
Before
After
Description
Sets a streamed bitmap to be used by a specific item.
Prototype
void ICONVIEW_SetStreamedBitmapItem(ICONVIEW_Handle
hObj,
int
Index,
const void
* pStreamedBitmap);
Parameter
Description
hObj
Index
pStreamedBitmap
Handle of widget.
Index of the item.
Pointer to the bitmap stream to be used.
Additional information
The pointer to the bitmap stream needs to remain valid.
ICONVIEW_SetTextAlign()
Before
After
Description
Sets the color to be used to draw the labels.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
494
CHAPTER
Window Objects (Widgets)
Prototype
void ICONVIEW_SetTextAlign(ICONVIEW_Handle hObj, int TextAlign);
Parameter
hObj
TextAlign
Description
Handle of widget.
See table below.
Permitted values for parameter TextAlign
(horizontal and vertical flags are OR-combinable)
Horizontal alignment
GUI_TA_LEFT
GUI_TA_HCENTER
GUI_TA_RIGHT
Align X-position left (default).
GUI_TA_TOP
GUI_TA_VCENTER
GUI_TA_BOTTOM
Align Y-position with top of characters (default).
Center X-position.
Align X-position right (default).
Vertical alignment
Center Y-position.
Align Y-position with bottom pixel line of font.
ICONVIEW_SetTextColor()
Before
After
Description
Sets the color to be used to draw the labels.
Prototype
void ICONVIEW_SetTextColor(ICONVIEW_Handle hObj,
int Index,
GUI_COLOR
Color);
Parameter
hObj
Index
Color
Description
Handle of widget.
(see table below)
Color to be used
Permitted values for parameter Index
ICONVIEW_CI_UNSEL
ICONVIEW_CI_SEL
Color used to draw the labels in unselected state.
Color used to draw the labels in selected state.
ICONVIEW_SetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_SetUserData().
17.11.5 Example
The Sample folder contains the following example which shows how the widget can be
used:
•
WIDGET_IconView
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
495
Screenshot of WIDGET_Iconview.c:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
496
CHAPTER
Window Objects (Widgets)
17.12 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.
17.12.1 Configuration options
Type
Macro
Default
Description
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
LISTBOX_TEXTCOLOR0_DEFAULT
LISTBOX_TEXTCOLOR1_DEFAULT
LISTBOX_TEXTCOLOR2_DEFAULT
&GUI_Font13_1
Font used.
GUI_BLACK
Text color, unselected state.
GUI_WHITE
Text color, selected state without focus.
GUI_WHITE
Text color, selected state with focus.
N
N
N
17.12.2 Notification codes
The following events are sent from a list box widget to its parent window as part of a
WM_NOTIFY_PARENT message:
Message
Description
WM_NOTIFICATION_CLICKED
WM_NOTIFICATION_RELEASED
List box has been clicked.
List box has been released.
WM_NOTIFICATION_MOVED_OUT
List box has been clicked and pointer has been moved out
off of the box without releasing.
WM_NOTIFICATION_SCROLL_CHANGED
The scroll position of the optional scrollbar has been
changed.
WM_NOTIFICATION_SEL_CHANGED
The selection of the list box has changed.
17.12.3 Keyboard reaction
The widget reacts to the following keys if it has the input focus:
Key
Reaction
GUI_KEY_SPACE
If the widget works in multi selection mode this key toggles the state of
the current selected item.
GUI_KEY_RIGHT
If the maximum X-size of the list box items is larger than the list box
itself this key scrolls the list box contents to the left.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
497
Key
Reaction
If the maximum X-size of the list box items is larger than the list box
itself this key scrolls the list box contents to the right.
GUI_KEY_LEFT
Moves the selection bar down.
GUI_KEY_DOWN
GUI_KEY_UP
Moves the selection bar up.
17.12.4 LISTBOX API
The table below lists the available emWin LISTBOX-related routines in alphabetical
order. Detailed descriptions of the routines follow.
Routine
LISTBOX_AddString()
LISTBOX_Create()
LISTBOX_CreateAsChild()
LISTBOX_CreateEx()
LISTBOX_CreateIndirect()
LISTBOX_CreateUser()
LISTBOX_DecSel()
LISTBOX_DeleteItem()
LISTBOX_GetDefaultBkColor()
LISTBOX_GetDefaultFont()
Description
Adds an item to a list box.
Creates a LISTBOX widget. (Obsolete)
Creates a LISTBOX widget as a child window. (Obsolete)
Creates a LISTBOX widget.
Creates a LISTBOX widget from resource table entry.
Creates a LISTBOX widget using extra bytes as user data.
Decrements selection.
Deletes an element.
Returns the default background color for LISTBOX widgets.
Returns the default font for LISTBOX widgets.
Returns the default number of pixels to be scrolled horizon-
LISTBOX_GetDefaultScrollStepH() tal.
Returns the default text alignment for new list boxes.
LISTBOX_GetDefaultTextAlign()
Returns the default text color for new list boxes.
LISTBOX_GetDefaultTextColor()
Returns the font of the list box.
LISTBOX_GetFont()
Returns the disabled state of the given item.
LISTBOX_GetItemDisabled()
Returns the selection state of a LISTBOX entry.
LISTBOX_GetItemSel()
Returns the text of a list box entry.
LISTBOX_GetItemText()
Returns if the multi select mode is active.
LISTBOX_GetMulti()
Returns the number of items in a list box.
LISTBOX_GetNumItems()
Returns the number of pixels to be scrolled horizontal.
LISTBOX_GetScrollStepH()
Returns the number of the selected item.
LISTBOX_GetSel()
Returns the text alignment of the LISTBOX.
LISTBOX_GetTextAlign()
Retrieves the data set with LISTBOX_SetUserData().
LISTBOX_GetUserData()
Increments selection.
LISTBOX_IncSel()
Inserts an element.
LISTBOX_InsertString()
Invalidates an item of an owner drawn LISTBOX.
LISTBOX_InvalidateItem()
Default function for drawing a LISTBOX entry.
LISTBOX_OwnerDraw()
Activates automatic use of a horizontal scrollbar.
LISTBOX_SetAutoScrollH()
Activates automatic use of a vertical scrollbar.
LISTBOX_SetAutoScrollV()
Sets the background color.
LISTBOX_SetBkColor()
Sets the default background color for LISTBOX widgets.
LISTBOX_SetDefaultBkColor()
Changes the default font for LISTBOX widgets.
LISTBOX_SetDefaultFont()
LISTBOX_SetDefaultScrollStepH() Sets the default number of pixels to be scrolled horizontal.
Sets the default text alignment for new LISTBOX widgets.
LISTBOX_SetDefaultTextAlign()
Sets the default text color for LISTBOX widgets.
LISTBOX_SetDefaultTextColor()
Selects the font.
LISTBOX_SetFont()
Sets the disabled state of the given item.
LISTBOX_SetItemDisabled()
Sets the selection state of the given item.
LISTBOX_SetItemSel()
Sets a spacing between the items.
LISTBOX_SetItemSpacing()
Sets the multi selection mode on or off.
LISTBOX_SetMulti()
Enables the list box to be owner drawn.
LISTBOX_SetOwnerDraw()
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
498
CHAPTER
Window Objects (Widgets)
Routine
LISTBOX_SetScrollbarColor()
LISTBOX_SetScrollbarWidth()
LISTBOX_SetScrollStepH()
LISTBOX_SetSel()
LISTBOX_SetString()
LISTBOX_SetTextAlign()
LISTBOX_SetTextColor()
LISTBOX_SetUserData()
Description
Sets the colors of the optional scrollbar.
Sets the width of the scrollbars used by the LISTBOX.
Sets the number of pixels to be scrolled horizontal.
Sets the selected item.
Sets the text of an element.
Sets the text alignment of the LISTBOX.
Sets the foreground color.
Sets the extra data of a LISTBOX widget.
LISTBOX_AddString()
Description
Adds an item to an already existing list box.
Prototype
void LISTBOX_AddString(LISTBOX_Handle hObj, const char * s);
Parameter
hObj
s
Description
Handle of list box.
Text to display.
LISTBOX_Create()
Description
Creates a LISTBOX widget of a specified size at a specified location.
Prototype
LISTBOX_Handle LISTBOX_Create(const
int
int
int
Parameter
ppText
x0
y0
xSize
ySize
Flags
GUI_ConstString * ppText,
x0, int y0,
xSize, int ySize,
Flags);
Description
Pointer to an array of string pointers containing the elements to be displayed.
Leftmost pixel of the list box (in parent coordinates).
Topmost pixel of the list box (in parent coordinates).
Horizontal size of the list box (in pixels).
Vertical size of the list box (in pixels).
Window create flags. Typically WM_CF_SHOW in order to make the widget visible
immediately (refer to WM_CreateWindow() in the chapter “The Window Manager
(WM)” on page 289 for a list of available parameter values).
Return value
Handle of the created LISTBOX widget; 0 if the function fails.
Additional information
If the parameter ySize is greater than the required space for drawing the contents of
the widget, the Y-size will be reduced to the required value. The same applies for the
Xsize parameter.
LISTBOX_CreateAsChild()
Description
Creates a LISTBOX widget as a child window.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
499
Prototype
LISTBOX_Handle LISTBOX_CreateAsChild(const
WM_HWIN
int
int
int
Parameter
ppText
hParent
x0
y0
xSize
ySize
Flags
GUI_ConstString * ppText,
hParent,
x0,
int y0,
xSize,
int ySize,
Flags);
Description
Pointer to an array of string pointers containing the elements to be displayed.
Handle of parent window.
X-position of the list box relative to the parent window.
Y-position of the list box relative to the parent window.
Horizontal size of the list box (in pixels).
Vertical size of the list box (in pixels).
Window create flags (see
LISTBOX_Create() ).
Return value
Handle of the created LISTBOX widget; 0 if the function fails.
Additional information
If the parameter ySize is greater than the space required for drawing the contents of
the widget, the Y-size will be reduced to the required value. If ySize = 0 the Y-size of
the widget will be set to the Y-size of the client area from the parent window. The
same applies for the Xsize parameter.
LISTBOX_CreateEx()
Description
Creates a LISTBOX widget of a specified size at a specified location.
Prototype
LISTBOX_Handle LISTBOX_CreateEx(int
int
WM_HWIN
int
const
Parameter
x0
y0
xsize
ysize
x0,
int y0,
xsize,
int ysize,
hParent, int WinFlags,
ExFlags, int Id,
GUI_ConstString * ppText);
Description
Leftmost pixel of the widget (in parent coordinates).
Topmost pixel of the widget (in parent coordinates).
Horizontal size of the widget (in pixels).
Vertical size of the widget (in pixels).
hParent
Handle of parent window. If 0, the new HEADER widget will be a child of the desktop
(top-level window).
WinFlags
Window create flags. Typically WM_CF_SHOW in order to make the widget visible
immediately (refer to WM_CreateWindow() in the chapter “The Window Manager
(WM)” on page 289 for a list of available parameter values).
ExFlags
Id
ppText
Not used, reserved for future use.
Window ID of the widget.
Pointer to an array of string pointers containing the elements to be displayed.
Return value
Handle of the created LISTBOX widget; 0 if the function fails.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
500
CHAPTER
Window Objects (Widgets)
LISTBOX_CreateIndirect()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateIndirect().
The elements Flags and Para of the resource passed as parameter are not used.
LISTBOX_CreateUser()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateUser(). For
a detailed description of the parameters the function LISTBOX_CreateEx() can be
referred to.
LISTBOX_DecSel()
Description
Decrement the list box selection (moves the selection bar of a specified list box up by
one item).
Prototypes
void LISTBOX_DecSel(LISTBOX_Handle hObj);
Parameter
hObj
Description
Handle of list box.
Additional information
Note that the numbering of items always starts from the top with a value of 0; therefore, decrementing the selection will actually move the selection one row up.
LISTBOX_DeleteItem()
Description
Deletes an element from a listbox.
Prototypes
void LISTBOX_DeleteItem(LISTBOX_Handle hObj, unsigned int Index);
Parameter
hObj
Index
Description
Handle of list box.
Zero based index of element to be deleted.
LISTBOX_GetDefaultBkColor()
Description
Returns the default background color for new LISTBOX widgets.
Prototype
GUI_COLOR LISTBOX_GetDefaultBkColor(unsigned Index);
Parameter
Index
Description
Zero based index for background color (see table below)
Permitted values for parameter Index
LISTBOX_CI_UNSEL
LISTBOX_CI_SEL
LISTBOX_CI_SELFOCUS
Unselected element.
Selected element, without focus.
Selected element, with focus.
Return value
Default background color for new LISTBOX widgets.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
501
LISTBOX_GetDefaultFont()
Description
Returns the default font used for creating LISTBOX widgets.
Prototype
const GUI_FONT * LISTBOX_GetDefaultFont(void);
Return value
Pointer to the default font.
LISTBOX_GetDefaultScrollStepH()
Description
Returns the default horizontal scroll step used for creating LISTBOX widgets. The
horizontal scroll step defines the number of pixels to be scrolled if needed.
Prototype
int LISTBOX_GetDefaultScrollStepH(void);
Return value
Default horizontal scroll step.
LISTBOX_GetDefaultTextAlign()
Description
Returns the default text alignment for new LISTBOX widgets.
Prototype
int LISTBOX_GetDefaultTextAlign(void);
Return value
Default text alignment for new LISTBOX widgets.
Additional information
For more information, refer to “LISTBOX_SetTextAlign()” on page 512.
LISTBOX_GetDefaultTextColor()
Description
Returns the default text color for new LISTBOX widgets.
Prototype
GUI_COLOR LISTBOX_GetDefaultTextColor(unsigned Index);
Parameter
Index
Description
Zero based index for text color (see table below)
Permitted values for parameter Index
LISTBOX_CI_UNSEL
LISTBOX_CI_SEL
LISTBOX_CI_SELFOCUS
Unselected element.
Selected element, without focus.
Selected element, with focus.
Return value
Default text color for new LISTBOX widgets.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
502
CHAPTER
Window Objects (Widgets)
LISTBOX_GetFont()
Description
Returns a pointer to the font used to display the text of the list box.
Prototype
const GUI_FONT * LISTBOX_GetFont(LISTBOX_Handle hObj);
Parameter
hObj
Description
Handle of list box.
Return value
Pointer to the font used to display the text of the list box.
LISTBOX_GetItemDisabled()
Description
Returns if the given list box item has been disabled.
Prototype
int LISTBOX_GetItemDisabled(LISTBOX_Handle hObj, unsigned Index);
Parameter
hObj
Index
Description
Handle of list box.
Zero based index of item.
Return value
1 if item has been disabled, 0 if not.
LISTBOX_GetItemSel()
Description
Returns the selection state of the given listbox item. The selection state of a LISTBOX
item can be modified in multi selection mode only.
Prototype
int LISTBOX_GetItemSel(LISTBOX_Handle hObj, unsigned int Index);
Parameter
hObj
Index
Description
Handle of list box.
Zero based index of item.
Return value
1 if item has been selected, 0 if not.
LISTBOX_GetItemText()
Description
Returns the text of the given list box item.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
503
Prototype
void LISTBOX_GetItemText(LISTBOX_Handle
hObj,
unsigned Index,
char
* pBuffer, int
MaxSize);
Parameter
hObj
Index
pBuffer
MaxSize
Description
Handle of list box.
Zero based index of item.
Pointer to buffer to store the item text.
Size of the buffer.
Additional information
The function copies the text of the given list box item into the given buffer.
LISTBOX_GetMulti()
Description
Returns if the multi selection mode of the given list box is active.
Prototype
int LISTBOX_GetMulti(LISTBOX_Handle hObj);
Parameter
hObj
Description
Handle of list box.
Return value
1 if active, 0 if not.
LISTBOX_GetNumItems()
Description
Returns the number of items in a specified list box.
Prototypes
unsigned LISTBOX_GetNumItems(LISTBOX_Handle hObj);
Parameter
hObj
Description
Handle of list box.
Return value
Number of items in the list box.
LISTBOX_GetScrollStepH()
Description
Returns the horizontal scroll step of the given list box.
Prototype
int LISTBOX_GetScrollStepH(LISTBOX_Handle hObj);
Parameter
hObj
Description
Handle of list box.
Return value
Horizontal scroll step of the given list box.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
504
CHAPTER
Window Objects (Widgets)
LISTBOX_GetSel()
Description
Returns the zero based index of the currently selected item in a specified list box. In
multi selection mode the function returns the index of the focused element.
Prototype
int LISTBOX_GetSel(LISTBOX_Handle hObj);
Parameter
hObj
Description
Handle of list box.
Return value
Zero based index of the currently selected item.
Additional information
If no element has been selected the function returns -1.
LISTBOX_GetTextAlign()
Description
Returns the text alignment of the given LISTBOX widget.
Prototype
int LISTBOX_GetTextAlign(LISTBOX_Handle hObj);
Parameter
hObj
Description
Handle of widget.
Return value
Text alignment of the given LISTBOX widget.
Additional information
For more information, refer to “LISTBOX_SetTextAlign()” on page 512.
LISTBOX_GetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_GetUserData().
LISTBOX_IncSel()
Description
Increment the list box selection (moves the selection bar of a specified list box down
by one item).
Prototypes
void LISTBOX_IncSel(LISTBOX_Handle hObj);
Parameter
hObj
Description
Handle of list box.
Additional information
Note that the numbering of items always starts from the top with a value of 0; therefore incrementing the selection will actually move the selection one row down.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
505
LISTBOX_InsertString()
Description
Inserts an element into a listbox.
Prototypes
void LISTBOX_InsertString(LISTBOX_Handle hObj,
const char * s,
unsigned int
Index);
Parameter
hObj
s
Index
Description
Handle of list box.
Pointer to string to be inserted.
Zero based index of element to be inserted.
LISTBOX_InvalidateItem()
Description
Invalidates an item of a owner drawn listbox.
Prototypes
void LISTBOX_InvalidateItem(LISTBOX_Handle hObj, int Index);
Parameter
Description
hObj
Handle of list box.
Index
Zero based index of element to be invalidated or LISTBOX_ALL_ITEMS if all items
should be invalidated.
Additional information
This function only needs to be called if an item of an owner drawn listbox has been
changed. If a listbox API function (like LISTBOX_SetString()) has been used to
modify a listbox item LISTBOX_InvalidateItem() needs not to be called. It needs to
be called if the user decides, that for example the vertical size of an item has been
changed. With other words if no listbox API function has been used to modify the
item this function needs to be called.
LISTBOX_ALL_ITEMS
If all items of a listbox should be invalidated use this define as Index parameter.
LISTBOX_OwnerDraw()
Description
Default function to handle a LISTBOX entry.
Prototypes
int LISTBOX_OwnerDraw(const WIDGET_ITEM_DRAW_INFO * pDrawItemInfo);
Parameter
pDrawItemInfo
Description
Pointer to a
WIDGET_ITEM_DRAW_INFO structure.
Additional information
This function is useful if LISTBOX_SetOwnerDraw() has been used. It can be used
from your drawing function to retrieve the original x size of a LISTBOX entry and/or
to display the text of a LISTBOX entry and should be called for all unhandled commands.
For more information, refer to the section explaining user drawn widgets,
LISTBOX_SetOwnerDraw() and to the provided example.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
506
CHAPTER
Window Objects (Widgets)
LISTBOX_SetAutoScrollH()
Description
Enables/disables the automatic use of a horizontal scrollbar.
Prototypes
void LISTBOX_SetAutoScrollH(LISTBOX_Handle hObj, int OnOff);
Parameter
hObj
OnOff
Description
Handle of list box.
(See table below)
Permitted values for parameter OnOff
0
1
Disable automatic use of a horizontal scrollbar.
Enable automatic use of a horizontal scrollbar.
Additional information
If enabled the listbox checks if all elements fits into the listbox. If not a horizontal
scrollbar will be attached to the window.
LISTBOX_SetAutoScrollV()
Description
Enables/disables the automatic use of a vertical scrollbar.
Prototypes
void LISTBOX_SetAutoScrollV(LISTBOX_Handle hObj, int OnOff);
Parameter
hObj
OnOff
Description
Handle of list box.
(See table below)
Permitted values for parameter OnOff
0
1
Disable automatic use of a vertical scrollbar.
Enable automatic use of a vertical scrollbar.
Additional information
If enabled the listbox checks if all elements fits into the listbox. If not a vertical
scrollbar will be added.
LISTBOX_SetBkColor()
Description
Sets the list box background color.
Prototype
void LISTBOX_SetBkColor(LISTBOX_Handle hObj, unsigned int Index,
GUI_COLOR Color);
Parameter
hObj
Index
Color
Description
Handle of list box.
Index for background color (see table below).
Color to be set.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
507
Permitted values for parameter Index
LISTBOX_CI_UNSEL
LISTBOX_CI_SEL
LISTBOX_CI_SELFOCUS
LISTBOX_CI_DISABLED
Unselected element.
Selected element, without focus.
Selected element, with focus.
Disabled element.
LISTBOX_SetDefaultBkColor()
Description
Sets the default background color for new LISTBOX widgets.
Prototype
void LISTBOX_SetDefaultBkColor(unsigned Index, GUI_COLOR Color);
Parameter
Index
Color
Description
Zero based index for background color (see table below)
Desired background color.
Permitted values for parameter Index
LISTBOX_CI_UNSEL
LISTBOX_CI_SEL
LISTBOX_CI_SELFOCUS
LISTBOX_CI_DISABLED
Unselected element.
Selected element, without focus.
Selected element, with focus.
Disabled element.
LISTBOX_SetDefaultFont()
Description
Sets the default font used for creating LISTBOX widgets.
Prototype
void LISTBOX_SetDefaultFont(const GUI_FONT * pFont)
Parameter
pFont
Description
Pointer to the font.
LISTBOX_SetDefaultScrollStepH()
Description
Sets the default horizontal scroll step used when creating a LISTBOX widget.
Prototype
void LISTBOX_SetDefaultScrollStepH(int Value);
Parameter
Value
Description
Number of pixels to be scrolled.
LISTBOX_SetDefaultTextAlign()
Description
Sets the default text alignment for new LISTBOX widgets.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
508
CHAPTER
Window Objects (Widgets)
Prototype
void LISTBOX_SetDefaultTextAlign(int Align);
Parameter
Align
Description
Default text alignment for new LISTBOX widgets.
Additional information
For more information, refer to “LISTBOX_SetTextAlign()” on page 512.
LISTBOX_SetDefaultTextColor()
Description
Sets the default text color for new LISTBOX widgets.
Prototype
void LISTBOX_SetDefaultTextColor(unsigned Index, GUI_COLOR Color);
Parameter
Index
Color
Description
Zero based index for text color (see table below)
Desired text color.
Permitted values for parameter Index
LISTBOX_CI_UNSEL
LISTBOX_CI_SEL
LISTBOX_CI_SELFOCUS
Unselected element.
Selected element, without focus.
Selected element, with focus.
LISTBOX_SetFont()
Description
Sets the list box font.
Prototype
void LISTBOX_SetFont(LISTBOX_Handle hObj, const GUI_FONT* pfont);
Parameter
hObj
pFont
Description
Handle of list box.
Pointer to the font.
LISTBOX_SetItemDisabled()
Description
Modifies the disable state of the given list box item.
Prototype
void LISTBOX_SetItemDisabled(LISTBOX_Handle hObj, unsigned Index,
int
OnOff);
Parameter
hObj
Index
OnOff
Description
Handle of list box.
Zero based index of the listbox item.
1 for disabled, 0 for not disabled.
Additional information
When scrolling through a list box disabled items will be skipped. You can not scroll to
a disabled list box item.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
509
LISTBOX_SetItemSel()
Description
Modifies the selection state of the given list box item.
Prototype
void LISTBOX_SetItemSel(LISTBOX_Handle hObj, unsigned Index, int OnOff);
Parameter
hObj
Index
OnOff
Description
Handle of list box.
Zero based index of the listbox item.
1 for selected, 0 for not selected.
Additional information
Setting the selection state of a list box item makes only sense when using the multi
selection mode. See also LISTBOX_SetMulti().
LISTBOX_SetItemSpacing()
Before
After
Description
Sets an additional spacing below the items of a list box.
Prototype
void LISTBOX_SetItemSpacing(LISTBOX_Handle hObj, unsigned Value);
Parameter
hObj
Value
Description
Handle of list box.
Number of pixels used as additional spacing between the items.
LISTBOX_SetMulti()
Description
Switches the multi selection mode of a LISTBOX on or off.
Prototype
void LISTBOX_SetMulti(LISTBOX_Handle hObj, int Mode);
Parameter
hObj
Mode
Description
Handle of list box.
0 for off, 1 for on.
Additional information
The multi selection mode enables the list box to have more than one selected element. Using the space key would toggle the selection state of a list box item.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
510
CHAPTER
Window Objects (Widgets)
LISTBOX_SetOwnerDraw()
Description
Sets the list box to be owner drawn.
Prototype
void LISTBOX_SetOwnerDraw(LISTBOX_Handle
hObj,
WIDGET_DRAW_ITEM_FUNC * pfDrawItem);
Parameter
hObj
pfDrawItem
Description
Handle of list box.
Pointer to owner draw function.
Additional information
This function sets a function pointer to a function which will be called by the widget if
a list box item has to be drawn and when the x or y size of a item is needed. It gives
you the possibility to draw anything as list box item, not just plain text. pfDrawItem
is a pointer to a application-defined function of type WIDGET_DRAW_ITEM_FUNC
which is explained at the beginning of the chapter.
Structure of the user defined owner draw function
The following shows the structure of a typical owner draw function. It assumes that
your LISTBOX entries are 30 pixels wider than and have the same height as the item
drawn by the default function:
static int _OwnerDraw(const WIDGET_ITEM_DRAW_INFO * pDrawItemInfo) {
switch (pDrawItemInfo->Cmd) {
case WIDGET_ITEM_GET_XSIZE:
return LISTBOX_OwnerDraw(pDrawItemInfo) + 30; /* Returns the default xsize+10 */
case WIDGET_ITEM_DRAW:
/* Your code to be added to draw the LISTBOX item */
return 0;
}
return LISTBOX_OwnerDraw(pDrawItemInfo);
/* Def. function for unhandled cmds */
}
Example
The source code of this
WIDGET_ListBoxOwnerDraw.
User's & reference manual for emWin V5.10
example
is
available
in
the
examples
as
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
511
LISTBOX_SetScrollbarColor()
Before
After
Description
Sets the colors of the optional scrollbar.
Prototype
void LISTBOX_SetScrollbarColor(LISTBOX_Handle hObj,
unsigned int
Index,
GUI_COLOR
Color);
Parameter
hObj
Index
Color
Description
Handle of widget
Index of desired item (see table below).
Color to be used.
Permitted values for parameter Index
SCROLLBAR_CI_THUMB Color of thumb area.
SCROLLBAR_CI_SHAFT Color of shaft.
SCROLLBAR_CI_ARROW Color of arrows.
LISTBOX_SetScrollbarWidth()
Description
Sets the width of the scrollbars used by the given list box.
Prototype
void LISTBOX_SetScrollbarWidth(LISTBOX_Handle hObj, unsigned Width);
Parameter
hObj
Width
Description
Handle of list box.
Width of the scrollbar(s) used by the given listbox.
LISTBOX_SetScrollStepH()
Description
Sets the horizontal scroll step of the given list box. The horizontal scroll step defines
the number of pixels to be scrolled if needed.
Prototype
void LISTBOX_SetScrollStepH(LISTBOX_Handle hObj, int Value);
Parameter
hObj
Value
Description
Handle of list box.
Number of pixels to be scrolled.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
512
CHAPTER
Window Objects (Widgets)
LISTBOX_SetSel()
Description
Sets the selected item of a specified list box.
Prototype
void LISTBOX_SetSel(LISTBOX_Handle hObj, int Sel);
Parameter
hObj
Sel
Description
Handle of list box.
Element to be selected.
LISTBOX_SetString()
Description
Sets the contents of the given item.
Prototypes
void LISTBOX_SetString(LISTBOX_Handle hObj,
const char * s,
unsigned int
Index);
Parameter
hObj
s
Index
Description
Handle of list box.
Pointer to string containing the new contents.
Zero based index of element to be changed.
LISTBOX_SetTextAlign()
Before
After
Description
The function sets the text alignment used to display each item of the list box.
Prototype
void LISTBOX_SetTextAlign(LISTBOX_Handle hObj, int Align);
Parameter
hObj
Align
Description
Handle of widget.
Text alignment to be used.
Permitted values for parameter Align
(horizontal and vertical flags are OR-combinable)
Horizontal alignment
GUI_TA_LEFT
GUI_TA_HCENTER
GUI_TA_RIGHT
Align X-position left (default).
Center X-position.
Align X-position right (default).
Vertical alignment
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
513
Permitted values for parameter Align
(horizontal and vertical flags are OR-combinable)
GUI_TA_TOP
GUI_TA_VCENTER
GUI_TA_BOTTOM
Align Y-position with top of characters (default).
Center Y-position.
Align Y-position with bottom pixel line of font.
Additional information
The default alignment of list boxes is GUI_TA_LEFT. Per default the height of each
item depends on the height of the font used to render the list box items. So vertical
text alignment makes only sense if the function LISTBOX_SetItemSpacing() is used
to set an additional spacing below the items.
LISTBOX_SetTextColor()
Description
Sets the list box text color.
Prototype
void LISTBOX_SetTextColor(LISTBOX_Handle hObj,
unsigned int Index,
GUI_COLOR
Color);
Parameter
hObj
Index
Color
Description
Handle of list box.
Index for text color (see
LISTBOX_SetBackColor()).
Color to be set.
LISTBOX_SetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_SetUserData().
17.12.5 Examples
The Sample folder contains the following examples which show how the widget can be
used:
•
WIDGET_SimpleListBox.c
•
WIDGET_ListBox.c
Note that several other examples also make use of this widget and may also be helpful to get familiar with the widget.
Screenshot of WIDGET_SimpleListBox.c:
Screenshot(s) of WIDGET_ListBox.c:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
514
CHAPTER
Window Objects (Widgets)
17.13 LISTVIEW: Listview widget
LISTVIEW widgets are used to select one element of a list with several columns. To
manage the columns a LISTVIEW 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:
Description
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
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
515
Description
LISTVIEW widget
Has input focus
With surrounding FRAMEWIN
SCROLLBAR attached
Grid lines visible
17.13.1 Configuration options
Type
S
Macro
Default
Description
LISTVIEW_FONT_DEFAULT
LISTVIEW_BKCOLOR0_DEFAULT
&GUI_Font13_1
Default font
N
GUI_WHITE
Background color, unselected state.
N
LISTVIEW_BKCOLOR1_DEFAULT
GUI_GRAY
N
LISTVIEW_BKCOLOR2_DEFAULT
GUI_BLUE
N
LISTVIEW_SCROLLSTEP_H_DEFAULT 10
N
LISTVIEW_TEXTCOLOR0_DEFAULT
Background color, selected state
without focus.
Background color, selected state with
focus.
Defines the number of pixels to be
scrolled if needed.
GUI_BLACK
Text color, unselected state.
Text color, selected state without
focus.
N
LISTVIEW_TEXTCOLOR1_DEFAULT
GUI_WHITE
N
LISTVIEW_TEXTCOLOR2_DEFAULT
LISTVIEW_GRIDCOLOR_DEFAULT
GUI_WHITE
Text color, selected state with focus.
N
GUI_LIGHTGRAY
Color of grid lines (if shown)
N
LISTVIEW_ALIGN_DEFAULT
GUI_TA_VCENTER
Default text alignment
|GUI_TA_HCENTER
17.13.2 Notification codes
The following events are sent from a LISTVIEW widget to its parent window as part of
a WM_NOTIFY_PARENT message:
Message
Description
WM_NOTIFICATION_CLICKED
WM_NOTIFICATION_RELEASED
Widget has been clicked.
Widget has been released.
WM_NOTIFICATION_MOVED_OUT
Widget has been clicked and pointer has been moved out
off of the widget without releasing.
WM_NOTIFICATION_SCROLL_CHANGED
The scroll position of the optional scrollbar has been
changed.
WM_NOTIFICATION_SEL_CHANGED
The selection of the list box has changed.
17.13.3 Keyboard reaction
The widget reacts to the following keys if it has the input focus:
Key
GUI_KEY_UP
GUI_KEY_DOWN
Reaction
Moves the selection bar up.
Moves the selection bar down.
GUI_KEY_RIGHT
If the total amount of the column width is > than the inside area of the
listview, the contents scrolls to the left.
GUI_KEY_LEFT
If the total amount of the column width is > than the inside area of the
listview, the contents scrolls to the right.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
516
CHAPTER
Window Objects (Widgets)
17.13.4 LISTVIEW API
The table below lists the available emWin LISTVIEW-related routines in alphabetical
order. Detailed descriptions of the routines follow.
Routine
LISTVIEW_AddColumn()
LISTVIEW_AddRow()
LISTVIEW_CompareDec()
LISTVIEW_CompareText()
LISTVIEW_Create()
LISTVIEW_CreateAttached()
LISTVIEW_CreateEx()
LISTVIEW_CreateIndirect()
LISTVIEW_CreateUser()
LISTVIEW_DecSel()
LISTVIEW_DeleteColumn()
LISTVIEW_DeleteRow()
LISTVIEW_DisableRow()
LISTVIEW_DisableSort()
LISTVIEW_EnableRow()
LISTVIEW_EnableSort()
LISTVIEW_GetBkColor()
LISTVIEW_GetFont()
LISTVIEW_GetHeader()
LISTVIEW_GetItemText()
LISTVIEW_GetNumColumns()
LISTVIEW_GetNumRows()
LISTVIEW_GetSel()
LISTVIEW_GetSelUnsorted()
LISTVIEW_GetTextColor()
LISTVIEW_GetUserData()
LISTVIEW_GetUserDataRow()
LISTVIEW_IncSel()
LISTVIEW_InsertRow()
LISTVIEW_SetAutoScrollH()
LISTVIEW_SetAutoScrollV()
LISTVIEW_SetBkColor()
LISTVIEW_SetColumnWidth()
LISTVIEW_SetCompareFunc()
LISTVIEW_SetDefaultBkColor()
LISTVIEW_SetDefaultFont()
LISTVIEW_SetDefaultGridColor()
LISTVIEW_SetDefaultTextColor()
LISTVIEW_SetFixed()
LISTVIEW_SetFont()
LISTVIEW_SetGridVis()
LISTVIEW_SetHeaderHeight()
LISTVIEW_SetItemBitmap()
LISTVIEW_SetItemBkColor()
LISTVIEW_SetItemText()
LISTVIEW_SetItemTextColor()
User's & reference manual for emWin V5.10
Description
Adds a column to a LISTVIEW.
Adds a row to a LISTVIEW.
Compare function for comparing 2 integer values.
Compare function for comparing 2 strings.
Creates a LISTVIEW widget. (Obsolete)
Creates a LISTVIEW widget attached to a window.
Creates a LISTVIEW widget.
Creates a LISTVIEW widget from a resource table entry.
Creates a LISTVIEW widget using extra bytes as user
data.
Decrements selection.
Deletes the given column.
Deletes the given row.
Sets the state of the given row to disabled.
Disables sorting of the LISTVIEW.
Sets the state of the given row to enabled.
Enables sorting of the LISTVIEW.
Returns the background color of the LISTVIEW.
Returns the font of the LISTVIEW.
Returns the handle of the attached HEADER widget.
Returns the text of the given cell.
Returns the number of columns.
Returns the number of rows.
Returns the number of the selected item.
Returns the number of the selected item in unsorted state.
Returns the text color of the LISTVIEW.
Retrieves the data set with LISTVIEW_SetUserData().
Returns the user data of the given row.
Increments selection.
Inserts a new row at the given position.
Enables the automatic use of a horizontal scrollbar.
Enables the automatic use of a vertical scrollbar.
Sets the background color.
Sets the column width.
Sets the compare function for the given column.
Sets the default background color for HEADER widgets.
Sets the default font for HEADER widgets.
Sets the default text color for HEADER widgets.
Sets the default color of the grid lines for HEADER widgets.
Fixes the given number of columns.
Sets the font of the LISTVIEW.
Sets the visibility flag of the grid lines.
Sets the height of the header.
Sets a bitmap as the background of a LISTVIEW cell
Sets the background color of a LISTVIEW cell
Sets the text of a LISTVIEW cell.
Sets the text color of a LISTVIEW cell
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
517
Routine
Description
Sets the number of pixels used for the left border.
LISTVIEW_SetLBorder()
LISTVIEW_SetRBorder()
LISTVIEW_SetRowHeight()
LISTVIEW_SetSel()
LISTVIEW_SetSelUnsorted()
LISTVIEW_SetSort()
LISTVIEW_SetTextAlign()
LISTVIEW_SetTextColor()
LISTVIEW_SetUserData()
LISTVIEW_SetUserDataRow()
Sets the number of pixels used for the right border.
Sets the row height of the LISTVIEW
Sets the current selection.
Sets the current selection in unsorted state.
Sets the column and sorting order to be sorted by.
Sets the text alignment of a column.
Sets the text color.
Sets the extra data of a LISTVIEW widget.
Sets the user data of the given row.
LISTVIEW_AddColumn()
Description
Adds a new column to a LISTVIEW widget.
Prototype
void LISTVIEW_AddColumn(LISTVIEW_Handle
hObj, int Width,
const char
* s,
int Align);
Parameter
hObj
Width
s
Align
Description
Handle of widget
Width of the new column
Text to be displayed in the HEADER widget
Text alignment mode to set. May be a combination of a horizontal and a vertical
alignment flag.
Permitted values for parameter Align
(horizontal and vertical flags are OR-combinable)
Horizontal alignment
GUI_TA_LEFT
GUI_TA_HCENTER
GUI_TA_RIGHT
Align X-position left.
Center X-position.
Align X-position right.
Vertical alignment
GUI_TA_TOP
GUI_TA_VCENTER
GUI_TA_BOTTOM
Align Y-position with top of characters.
Center Y-position.
Align Y-position with bottom pixel line of font.
Additional information
The Width-parameter can be 0. If Width = 0 the width of the new column will be calculated by the given text and by the default value of the horizontal spacing.
You can only add columns to an ’empty’ LISTVIEW widget. If it contains 1 or more
rows you can not add a new column.
LISTVIEW_AddRow()
Description
Adds a new row to a LISTVIEW widget.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
518
CHAPTER
Window Objects (Widgets)
Prototype
void LISTVIEW_AddRow(LISTVIEW_Handle hObj, const GUI_ConstString * ppText);
Parameter
hObj
ppText
Description
Handle of widget
Pointer to array containing the text of the LISTVIEW cells
Additional information
The ppText-array should contain one item for each column. If it contains less items
the remaining cells left blank.
LISTVIEW_CompareDec()
Description
Compare function for comparing 2 integer values.
Prototype
int LISTVIEW_CompareDec(const void * p0, const void * p1);
Parameter
p0
p1
Description
Void pointer to first value:
Void pointer to second value.
Return value
< 0 if value of cell 0 greater than value of cell 1.
0 if value of cell 0 identical to value of cell 1.
> 0 if value of cell 0 less than value of cell 1.
Additional information
The purpose of this function is to be used by the listviews sorting algorithm if the cell
text represents integer values.
For details about how to use this function for sorting, refer also to
“LISTVIEW_SetCompareFunc()” on page 528.
The Sample folder contains the example WIDGET_SortedListview.c which shows
how to use the function.
LISTVIEW_CompareText()
Description
Function for comparison of 2 strings.
Prototype
int LISTVIEW_CompareText(const void * p0, const void * p1);
Parameter
p0
p1
Description
Void pointer to first text:
Void pointer to second text.
Return value
> 0 if text of cell 0 greater than text of cell 1.
0 if text of cell 0 identical to text of cell 1.
< 0 if text of cell 0 less than text of cell 1.
Additional information
The purpose of this function is to be used by the listviews sorting algorithm.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
519
For details about how to use this function for sorting, refer also to
“LISTVIEW_SetCompareFunc()” on page 528.
The Sample folder contains the example WIDGET_SortedListview.c which shows
how to use the function.
LISTVIEW_Create()
(Obsolete, LISTVIEW_CreateEx() should be used instead)
Description
Creates a LISTVIEW widget of a specified size at a specified location.
Prototype
LISTVIEW_Handle LISTVIEW_Create(int
int
WM_HWIN
int
Parameter
x0
y0
xsize
ysize
hParent
Id
Flags
x0,
xsize,
hParent,
Flags,
int
int
int
int
y0,
ysize,
Id,
SpecialFlags);
Description
Leftmost pixel of the HEADER widget (in parent coordinates).
Topmost pixel of the HEADER widget (in parent coordinates).
Horizontal size of the HEADER widget (in pixels).
Vertical size of the HEADER widget (in pixels).
Handle of the parent window
Id of the new HEADER widget
Window create flags. Typically WM_CF_SHOW in order to make the widget visible
immediately (refer to WM_CreateWindow() in the chapter “The Window Manager
(WM)” on page 289 for a list of available parameter values).
SpecialFlags (Reserved for later use)
Return value
Handle of the created LISTVIEW widget; 0 if the function fails.
LISTVIEW_CreateAttached()
Description
Creates a LISTVIEW widget which is attached to an existing window.
Prototype
LISTVIEW_Handle LISTVIEW_CreateAttached(WM_HWIN hParent,
int Id,
int
SpecialFlags);
Parameter
Description
Handle of widget
hObj
Id of the new LISTVIEW widget
Id
SpecialFlags (Not used, reserved for later use)
Return value
Handle of the created LISTVIEW widget; 0 if the function fails.
Additional information
An attached LISTVIEW widget is essentially a child window which will position itself
on the parent window and operate accordingly.
LISTVIEW_CreateEx()
Description
Creates a LISTVIEW widget of a specified size at a specified location.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
520
CHAPTER
Window Objects (Widgets)
Prototype
LISTVIEW_Handle LISTVIEW_CreateEx(int
int
WM_HWIN
int
Parameter
x0
y0
xsize
ysize
hParent
x0,
xsize,
hParent,
ExFlags,
int
int
int
int
y0,
ysize,
WinFlags,
Id);
Description
Leftmost pixel of the widget (in parent coordinates).
Topmost pixel of the widget (in parent coordinates).
Horizontal size of the widget (in pixels).
Vertical size of the widget (in pixels).
Handle of parent window. If 0, the new LISTVIEW widget will be a child of the desktop (top-level window).
Window create flags. Typically
WM_CF_SHOW in order to make the widget visible
WinFlags
immediately (refer to WM_CreateWindow() in the chapter “The Window Manager
(WM)” on page 289 for a list of available parameter values).
ExFlags
Id
Not used, reserved for future use.
Window ID of the widget.
Return value
Handle of the created LISTVIEW widget; 0 if the function fails.
LISTVIEW_CreateIndirect()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateIndirect().
LISTVIEW_CreateUser()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateUser(). For
a detailed description of the parameters the function LISTVIEW_CreateEx() can be
referred to.
LISTVIEW_DecSel()
Description
Decrement the listview selection (moves the selection bar of a specified listview up by
one item, if possible).
Prototype
void LISTVIEW_DecSel(LISTVIEW_Handle hObj);
Parameter
hObj
Description
Handle of widget
Additional information
Note that the numbering of items always starts from the top with a value of 0; therefore, decrementing the selection will actually move the selection one row up.
LISTVIEW_DeleteColumn()
Description
Deletes the specified column of the listview.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
521
Prototype
void LISTVIEW_DeleteColumn(LISTVIEW_Handle hObj, unsigned Index);
Parameter
hObj
Index
Description
Handle of widget
Zero based index of column to be deleted.
Additional information
Note that the numbering of items always starts from the left with a value of 0.
LISTVIEW_DeleteRow()
Description
Deletes the specified row of the listview.
Prototype
void LISTVIEW_DeleteRow(LISTVIEW_Handle hObj, unsigned Index);
Parameter
hObj
Index
Description
Handle of widget
Zero based index of row to be deleted.
Additional information
Note that the numbering of items always starts from the top with a value of 0.
LISTVIEW_DisableRow()
Before
After
Description
The function sets the state of the given row to disabled.
Prototype
void LISTVIEW_DisableRow(LISTVIEW_Handle hObj, unsigned Row);
Parameter
hObj
Row
Description
Handle of widget
Zero based index of the row to be disabled.
Additional information
When scrolling through a listview disabled items will be skipped. You can not scroll to
a disabled listview item.
LISTVIEW_DisableSort()
Description
Disables sorting of the given listview. After calling this function the contents of the listview
will be shown unsorted.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
522
CHAPTER
Window Objects (Widgets)
Prototype
void LISTVIEW_DisableSort(LISTVIEW_Handle hObj);
Parameter
hObj
Description
Handle of widget
Additional information
For details about how to use sorting in listview widgets, refer to
“LISTVIEW_SetCompareFunc()” on page 528 and “LISTVIEW_SetSort()” on
page 536.
The Sample folder contains the example WIDGET_SortedListview.c which shows
how to use the function.
LISTVIEW_EnableRow()
Before
After
Description
The function sets the state of the given row to enabled.
Prototype
void LISTVIEW_EnableRow(LISTVIEW_Handle hObj, unsigned Row);
Parameter
hObj
Row
Description
Handle of widget
Zero based index of the row to be disabled.
Additional information
Refer to “LISTVIEW_DisableRow()” on page 521.
LISTVIEW_EnableSort()
Description
Enables sorting for the given listview. After calling this function the contents of the listview
can be rendered sorted after clicking on the header item of the desired column, by which
the listview should sort its data. Note that this works only after a compare function for the
desired column has been set.
Prototype
void LISTVIEW_EnableSort(LISTVIEW_Handle hObj);
Parameter
hObj
Description
Handle of widget
Additional information
For
details
about
how
to
set
a
compare
function,
refer
to
“LISTVIEW_SetCompareFunc()” on page 528.
The Sample folder contains the example WIDGET_SortedListview.c which shows
how to use the function.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
523
LISTVIEW_GetBkColor()
Description
Returns the background color of the given listview.
Prototype
GUI_COLOR LISTVIEW_GetBkColor(LISTVIEW_Handle hObj, unsigned Index);
Parameter
hObj
Index
Description
Handle of widget
Index of color (see table below)
Permitted values for parameter Index
LISTVIEW_CI_UNSEL
LISTVIEW_CI_SEL
LISTVIEW_CI_SELFOCUS
Unselected element.
Selected element, without focus.
Selected element, with focus.
Return value
Background color of the given listview.
LISTVIEW_GetFont()
Description
Returns a pointer to the font used to display the text of the listview.
Prototype
const GUI_FONT * LISTVIEW_GetFont(LISTVIEW_Handle hObj);
Parameter
hObj
Description
Handle of widget.
Return value
Pointer to the font used to display the text of the listview.
LISTVIEW_GetHeader()
Description
Returns the handle of the HEADER widget.
Prototype
HEADER_Handle LISTVIEW_GetHeader(LISTVIEW_Handle hObj);
Parameter
hObj
Description
Handle of widget
Return value
Handle of the HEADER widget.
Additional information
Each LISTVIEW widget contains a HEADER widget to manage the columns. You can
use this handle to change the properties of the LISTVIEW-HEADER, for example to
change the text color of the HEADER widget.
Example:
LISTVIEW_Handle hListView = LISTVIEW_Create(10, 80, 270, 89, 0, 1234, WM_CF_SHOW, 0);
HEADER_Handle hHeader = LISTVIEW_GetHeader(hListView);
HEADER_SetTextColor(hHeader, GUI_GREEN);
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
524
CHAPTER
Window Objects (Widgets)
LISTVIEW_GetItemText()
Description
Returns the text of the given listview cell by copying it to the given buffer.
Prototype
void LISTVIEW_GetItemText(LISTVIEW_Handle hObj,
unsigned
Column,
unsigned
Row,
char
* pBuffer,
unsigned
MaxSize);
Parameter
hObj
Column
Row
pBuffer
MaxSize
Description
Handle of widget
Zero based index of the cell’s column.
Zero based index of the cell’s row
Pointer to a buffer to be filled by the routine.
Size in bytes of the buffer.
Additional information
If the text of the cell does not fit into the buffer, the number of bytes specified by the
parameter MaxSize will be copied to the buffer.
LISTVIEW_GetNumColumns()
Description
Returns the number of columns of the given LISTVIEW widget.
Prototype
unsigned LISTVIEW_GetNumColumns(LISTVIEW_Handle hObj);
Parameter
hObj
Description
Handle of widget
Return value
Number of columns of the given LISTVIEW widget.
LISTVIEW_GetNumRows()
Description
Returns the number of rows of the given LISTVIEW widget.
Prototype
unsigned LISTVIEW_GetNumRows(LISTVIEW_Handle hObj);
Parameter
hObj
Description
Handle of widget
Return value
Number of rows of the given LISTVIEW widget.
LISTVIEW_GetSel()
Description
Returns the number of the currently selected row in a specified LISTVIEW widget.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
525
Prototype
int LISTVIEW_GetSel(LISTVIEW_Handle hObj);
Parameter
hObj
Description
Handle of widget
Return value
Number of the currently selected row.
LISTVIEW_GetSelUnsorted()
Description
Returns the index of the currently selected row in unsorted state.
Prototype
int LISTVIEW_GetSelUnsorted(LISTVIEW_Handle hObj);
Parameter
hObj
Description
Handle of widget
Return value
Index of the currently selected row in unsorted state.
Additional information
This function returns the actually index of the selected row, whereas the function
LISTVIEW_GetSel() only returns the index of the sorted row. The actual (unsorted)
row index should be used in function calls as row index.
The Sample folder contains the example WIDGET_SortedListview.c which shows
how to use the function.
LISTVIEW_GetTextColor()
Description
Returns the text color of the given listview.
Prototype
GUI_COLOR LISTVIEW_GetTextColor(LISTVIEW_Handle hObj, unsigned Index);
Parameter
hObj
Index
Description
Handle of widget
Index of color (see table below)
Permitted values for parameter Index
LISTVIEW_CI_UNSEL
LISTVIEW_CI_SEL
LISTVIEW_CI_SELFOCUS
Unselected element.
Selected element, without focus.
Selected element, with focus.
Return value
Text color of the given listview.
LISTVIEW_GetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_GetUserData().
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
526
CHAPTER
Window Objects (Widgets)
LISTVIEW_GetUserDataRow()
Description
Returns the user data of the given row.
Prototype
U32 LISTVIEW_GetUserData(LISTVIEW_Handle hObj, unsigned Row);
Parameter
hObj
Row
Description
Handle of widget
Zero based index of row.
Return value
User data of the given row.
Additional information
For details about how to set user data
“LISTVIEW_SetUserDataRow()” on page 537.
of
a
row,
please
refer
to
LISTVIEW_IncSel()
Description
Increment the list box selection (moves the selection bar of a specified LISTVIEW down by
one item).
Prototype
void LISTVIEW_IncSel(LISTVIEW_Handle hObj);
Parameter
hObj
Description
Handle of widget
LISTVIEW_InsertRow()
Description
Inserts a new row into the listview at the given position.
Prototype
int LISTVIEW_InsertRow(LISTVIEW_Handle
hObj,
unsigned Index,
const GUI_ConstString * ppText);
Parameter
hObj
Index
ppText
Description
Handle of widget
Index of the new row.
Pointer to a string array containing the cell data of the new row.
Return value
0 if function succeed, 1 if an error occurs.
Additional information
The ppText-array should contain one item for each column. If it contains less items
the remaining cells left blank.
If the given index is >= the current number of rows, the function
LISTVIEW_AddRow() will be used to add the new row.
The Sample folder contains the example WIDGET_SortedListview.c which shows
how to use the function.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
527
LISTVIEW_SetAutoScrollH()
Description
Enables/disables the automatic use of a horizontal scrollbar.
Prototype
void LISTVIEW_SetAutoScrollH(LISTVIEW_Handle hObj, int OnOff);
Parameter
hObj
OnOff
Description
Handle of widget
(see table below)
Permitted values for parameter OnOff
0
1
Disable automatic use of a horizontal scrollbar.
Enable automatic use of a horizontal scrollbar.
Additional information
If enabled the listview checks if all columns fit into the widgets area. If not a horizontal scrollbar will be added.
LISTVIEW_SetAutoScrollV()
Description
Enables/disables the automatic use of a vertical scrollbar.
Prototype
void LISTVIEW_SetAutoScrollV(LISTVIEW_Handle hObj, int OnOff);
Parameter
hObj
OnOff
Description
Handle of widget
(see table below)
Permitted values for parameter OnOff
0
1
Disable automatic use of a vertical scrollbar.
Enable automatic use of a vertical scrollbar.
Additional information
If enabled the listview checks if all rows fit into the widgets area. If not a vertical
scrollbar will be added.
LISTVIEW_SetBkColor()
Description
Sets the background color of the given LISTVIEW widget.
Prototype
void LISTVIEW_SetBkColor(LISTVIEW_Handle hObj,
unsigned int Index,
GUI_COLOR
Color);
Parameter
hObj
Index
Color
Description
Handle of widget
Index for background color (see table below).
Color to be set.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
528
CHAPTER
Window Objects (Widgets)
Permitted values for parameter Index
LISTVIEW_CI_UNSEL
LISTVIEW_CI_SEL
LISTVIEW_CI_SELFOCUS
LISTVIEW_CI_DISABLED
Unselected element.
Selected element, without focus.
Selected element, with focus.
Disabled element.
Additional information
To
set
the
background
color
for
a
single
cell
the
function
LISTVIEW_SetItemBkColor() should be used.
The Sample folder contains the example WIDGET_SortedListview.c which shows
how to use the function.
LISTVIEW_SetColumnWidth()
Description
Sets the width of the given column.
Prototype
void LISTVIEW_SetColumnWidth(LISTVIEW_Handle hObj,
unsigned int Index,
int
Width);
Parameter
hObj
Index
Width
Description
Handle of widget
Number of column
New width
LISTVIEW_SetCompareFunc()
Description
Sets the compare function for the given column. A compare function needs to be set if the
listview widget should be sorted by the given column.
Prototype
void LISTVIEW_SetCompareFunc(LISTVIEW_Handle hObj, unsigned Column,
int (* fpCompare)(const void * p0, const void * p1));
Parameter
hObj
Column
fpCompare
Description
Handle of widget
Index of the desired column for which the compare function should be set.
Function pointer to compare function.
Additional information
If the sorting feature of the listview widget is used, the widget uses a compare function to decide if the contents of one cell is greater, equal or less than the contents of
the other cell.
Per default no compare function is set for the listview columns. For each column
which should be used for sorting, a compare function needs to be set.
The cells of the listview widget contain text. But sometimes the text represents data
of other types like dates, integers or others. So different compare functions are
required for sorting. emWin provides 2 compare functions:
LISTVIEW_CompareText():
text.
Function can be used for comparing cells containing
LISTVIEW_CompareDec(): Function can be used for comparing cells which text,
where the contents represents integer values.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
529
The compare function should return a value >0, if the contents of the second cell is
greater than the contents of the first cell and <0, if the contents of the second cell is
less than the contents of the first cell or 0 if equal.
Also user defined compare functions can be used. The prototype of a applicationdefined function should be defined as follows:
Prototype
int APPLICATION_Compare(const void * p0, const void * p1);
Parameter
p0
p1
Description
Pointer to NULL terminated string data of the first cell.
Pointer to NULL terminated string data of the second cell.
Example
int APPLICATION_Compare(const void * p0, const void * p1) {
return strcmp((const char *)p1, (const char *)p0);
}
void SetAppCompareFunc(WM_HWIN hListView, int Column) {
LISTVIEW_SetCompareFunc(hListView, Column, APPLICATION_Compare);
}
The Sample folder contains the example WIDGET_SortedListview.c which shows
how to use the function.
LISTVIEW_SetDefaultBkColor()
Description
Sets the default background color for new LISTVIEW widgets.
Prototype
GUI_COLOR LISTVIEW_SetDefaultBkColor(unsigned int Index, GUI_COLOR Color);
Parameter
Index
Color
Description
Index of default background color (see table below)
Color to be set as default
Permitted values for parameter Index
LISTVIEW_CI_UNSEL
LISTVIEW_CI_SEL
LISTVIEW_CI_SELFOCUS
LISTVIEW_CI_DISABLED
Unselected element.
Selected element, without focus.
Selected element, with focus.
Disabled element.
Return value
Previous default value.
LISTVIEW_SetDefaultFont()
Description
Sets the default font for new LISTVIEW widgets.
Prototype
const GUI_FONT * LISTVIEW_SetDefaultFont(const GUI_FONT * pFont);
Parameter
pFont
Description
Pointer to font used for new LISTVIEW widgets
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
530
CHAPTER
Window Objects (Widgets)
Return value
Previous default value.
LISTVIEW_SetDefaultGridColor()
Description
Sets the default color of the grid lines for new LISTVIEW widgets.
Prototype
GUI_COLOR LISTVIEW_SetDefaultGridColor(GUI_COLOR Color);
Parameter
Color
Description
New default value
Return value
Previous default value
LISTVIEW_SetDefaultTextColor()
Description
Sets the default text color for new LISTVIEW widgets.
Prototype
GUI_COLOR LISTVIEW_SetDefaultTextColor(unsigned int Index, GUI_COLOR Color);
Parameter
Index
Color
Description
Index of default text color (see table below)
Color to be set as default
Permitted values for parameter Index
0
1
2
Unselected element.
Selected element, without focus.
Selected element, with focus.
Return value
Previous default value.
LISTVIEW_SetFixed()
Description
Fixes the given number of columns at their horizontal positions.
Prototype
unsigned LISTVIEW_SetFixed(LISTVIEW_Handle hObj, unsigned Fixed);
Parameter
hObj
Fixed
Description
Handle of listview.
Number of columns to be fixed at their horizontal positions.
Additional information
Using this function makes sense if one or more columns should remain at their horizontal positions during scrolling operations.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
531
LISTVIEW_SetFont()
Description
Sets the listview font.
Prototype
void LISTVIEW_SetFont(LISTVIEW_Handle hObj, const GUI_FONT * pFont);
Parameter
hObj
pFont
Description
Handle of listview.
Pointer to the font.
LISTVIEW_SetGridVis()
Description
Sets the visibility flag of the grid lines. When creating a LISTVIEW the grid lines are disabled per default.
Prototype
int LISTVIEW_SetGridVis(LISTVIEW_Handle hObj, int Show);
Parameter
hObj
Show
Description
Handle of widget
Sets the visibility of the grid lines
Permitted values for parameter Show
0
1
Not visible.
Visible
Return value
Previous value of the visibility flag.
LISTVIEW_SetHeaderHeight()
Description
Sets the height of the attached header widget.
Prototype
void LISTVIEW_SetHeaderHeight(LISTVIEW_Handle hObj, unsigned HeaderHeight);
Parameter
hObj
Show
Description
Handle of the LISTVIEW widget.
Height of the attached HEADER widget to be set.
Additional information
Setting the height to 0 causes the header widget not to be displayed.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
532
CHAPTER
Window Objects (Widgets)
LISTVIEW_SetItemBitmap()
Before
After
Description
Sets a bitmap as background of the given cell.
Prototype
void LISTVIEW_SetItemBitmap(LISTVIEW_Handle hObj,
unsigned
Column, unsigned Row,
int
xOff,
int
yOff,
const GUI_BITMAP GUI_UNI_PTR * pBitmap);
Parameter
hObj
Column
Row
xOff
yOff
pBitmap
Description
Handle of a listview widget
Number of column
Number of row
Offset for the leftmost pixel of the bitmap to be drawn
Offset for the topmost pixel of the bitmap to be drawn
Pointer to the bitmap
LISTVIEW_SetItemBkColor()
Before
After
Description
Sets the background color of the given cell.
Prototype
void LISTVIEW_SetItemBkColor(LISTVIEW_Handle hObj,
unsigned
Column, unsigned Row,
unsigned int
Index, GUI_COLOR Color);
Parameter
hObj
Column
Row
Index
Color
Description
Handle of widget
Number of columns.
Number of rows.
Index of background color (see table below).
Color to be used.
Permitted values for parameter Index
LISTVIEW_CI_UNSEL
User's & reference manual for emWin V5.10
Unselected element.
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
533
Permitted values for parameter Index
LISTVIEW_CI_SEL
LISTVIEW_CI_SELFOCUS
LISTVIEW_CI_DISABLED
Selected element, without focus.
Selected element, with focus.
Disabled element.
Additional information
This function overwrites the default background color for the given cell set by
LISTVIEW_SetBkColor().
LISTVIEW_SetItemText()
Description
Sets the text of one cell of the LISTVIEW widget specified by row and column.
Prototype
void LISTVIEW_SetItemText(LISTVIEW_Handle hObj, unsigned
Column,
unsigned
Row, const char * s);
Parameter
hObj
Column
Row
s
Description
Handle of widget.
Number of column.
Number of row.
Text to be displayed in the table cell.
LISTVIEW_SetItemTextColor()
Before
After
Description
Sets the text color of the given cell.
Prototype
void LISTVIEW_SetItemTextColor(LISTVIEW_Handle hObj,
unsigned
Column, unsigned Row,
unsigned int
Index, GUI_COLOR Color);
Parameter
hObj
Column
Row
Index
Color
Description
Handle of widget
Number of column.
Number of row.
Index of text color (see table below).
Color to be used.
Permitted values for parameter Index
LISTVIEW_CI_UNSEL
LISTVIEW_CI_SEL
LISTVIEW_CI_SELFOCUS
User's & reference manual for emWin V5.10
Unselected element.
Selected element, without focus.
Selected element, with focus.
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
534
CHAPTER
Window Objects (Widgets)
Additional information
This function overwrites the
LISTVIEW_SetTextColor().
default
text
color
for
the
given
cell
set
by
LISTVIEW_SetLBorder()
Before
After
Description
Sets the number of pixels used for the left border within each cell of the listview.
Prototype
void LISTVIEW_SetLBorder(LISTVIEW_Handle hObj, unsigned BorderSize);
Parameter
hObj
BorderSize
Description
Handle of widget.
Number of pixels to be used.
Additional information
Using this function has no effect to the header widget used by the listview.
LISTVIEW_SetRBorder()
Before
After
Description
Sets the number of pixels used for the right border within each cell of the listview.
Prototype
void LISTVIEW_SetRBorder(LISTVIEW_Handle hObj, unsigned BorderSize);
Parameter
hObj
BorderSize
Description
Handle of widget.
Number of pixels to be used.
Additional information
Using this function has no effect to the header widget used by the listview.
LISTVIEW_SetRowHeight()
Description
Sets the number of pixels used for the height of each row of the listview.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
535
Prototype
unsigned LISTVIEW_SetRowHeight(LISTVIEW_Handle hObj, unsigned RowHeight);
Parameter
hObj
Description
Handle of widget.
Return value
Previous value of the row height set by this function. If the return value is 0, the
height of the rows depends on the height of the font used by the widget.
Additional information
Per default the height of the rows depends on the height of the used font.
LISTVIEW_SetSel()
Description
Sets the selected row of a specified LISTVIEW widget.
Prototype
void LISTVIEW_SetSel(LISTVIEW_Handle hObj, int Sel);
Parameter
hObj
Sel
Description
Handle of widget
Element to be selected.
LISTVIEW_SetSelUnsorted()
Description
Sets the index of the currently selected row in unsorted state.
Prototype
void LISTVIEW_SetSelUnsorted(LISTVIEW_Handle hObj, int Sel);
Parameter
hObj
Sel
Description
Handle of widget.
Zero based selection index in unsorted state.
Additional information
This function sets the actually index of the selected row, whereas the function
LISTVIEW_SetSel() sets the index of the sorted row. The actual (unsorted) row
index should be used in function calls as row index.
The Sample folder contains the example WIDGET_SortedListview.c which shows
how to use the function.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
536
CHAPTER
Window Objects (Widgets)
LISTVIEW_SetSort()
Before
After
Description
This function sets the column to be sorted by and the sorting order.
Prototype
unsigned LISTVIEW_SetSort(LISTVIEW_Handle hObj,
unsigned Column,
unsigned
Reverse);
Parameter
hObj
Column
Reverse
Description
Handle of widget.
Column to be sorted by.
0 for normal sorting order (greatest element at the top), 1 for reverse order.
Return value
0 if function was successfully, 1 if not.
Additional information
Before calling this function a compare function needs to be set for the desired column.
For
details
about
how
to
set
a
compare
function,
refer
to
“LISTVIEW_SetCompareFunc()” on page 528.
The Sample folder contains the example WIDGET_SortedListview.c which shows
how to use the function.
LISTVIEW_SetTextAlign()
Description
Sets the alignment for the given column.
Prototype
void LISTVIEW_SetTextAlign(LISTVIEW_Handle hObj,
unsigned int Index,
int
Align);
Parameter
hObj
Index
Align
Description
Handle of widget
Number of column
Text alignment mode to set. May be a combination of a horizontal and a vertical
alignment flag.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
537
Permitted values for parameter Align
(horizontal and vertical flags are OR-combinable)
Horizontal alignment
GUI_TA_LEFT
GUI_TA_HCENTER
GUI_TA_RIGHT
Align X-position left (default).
GUI_TA_TOP
GUI_TA_VCENTER
GUI_TA_BOTTOM
Align Y-position with top of characters (default).
Center X-position.
Align X-position right (default).
Vertical alignment
Center Y-position.
Align Y-position with bottom pixel line of font.
LISTVIEW_SetTextColor()
Description
Sets the text color of the given LISTVIEW widget.
Prototype
void LISTVIEW_SetTextColor(LISTVIEW_Handle hObj,
unsigned int Index,
GUI_COLOR
Color);
Parameter
hObj
Index
Color
Description
Handle of widget
Index for text color (see table below).
Color to be set.
Permitted values for parameter Index
LISTVIEW_CI_UNSEL
LISTVIEW_CI_SEL
LISTVIEW_CI_SELFOCUS
Unselected element.
Selected element, without focus.
Selected element, with focus.
LISTVIEW_SetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_SetUserData().
LISTVIEW_SetUserDataRow()
Description
Sets the user data of the given row.
Prototype
void LISTVIEW_SetUserData(LISTVIEW_Handle hObj,
unsigned Row,
U32
UserData);
Parameter
hObj
Row
UserData
Description
Handle of widget
Row for which the user data should be set
Value to be associated with the row.
Additional information
Sets the 32-bit value associated with the row. Each row has a corresponding 32-bit
value intended for use by the application.
17.13.5 Example
The Sample folder contains the following example which shows how the widget can be
used:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
538
CHAPTER
•
Window Objects (Widgets)
WIDGET_ListView.c
Note that several other examples also make use of this widget and may also be helpful to get familiar with the widget.
Screenshot of WIDGET_ListView.c:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
539
17.14 LISTWHEEL: Listwheel widget
This widget is similar to the LISTBOX widget described earlier in this chapter.
Whereas the data of a LISTBOX is selected by moving the cursor with the keyboard
or by using a SRCOLLBAR the LISTWHEEL works completely different: The whole data
area can be moved via pointer input device (PID). Striking over the widget from top
to bottom or vice versa moves the data up or downwards. When releasing the PID
during the data area is moving it slows down its motion and stops by snapping in a
new item at the snap position. Further the data is shown in a loop. After the last data
item it continues with the first item like in a chain. So the data can be ’rotated’ like
on a wheel:
Description
LISTWHEEL widget
Application example showing three wheels for
selecting a date. The example uses the owner
draw mechanism to overlay the widget with a customized alpha mask for the shading effect.
The table above shows a screenshot of the example WIDGET_ListWheel.c located in
the example folder Sample\Tutorial\ of emWin.
17.14.1 Configuration options
Type
S
N
N
N
N
N
Macro
LISTWHEEL_FONT_DEFAULT
LISTWHEEL_BKCOLOR0_DEFAULT
LISTWHEEL_BKCOLOR1_DEFAULT
LISTWHEEL_TEXTCOLOR0_DEFAULT
LISTWHEEL_TEXTCOLOR1_DEFAULT
LISTWHEEL_TEXTALIGN_DEFAULT
Default
Description
GUI_Font13_1
Font used.
GUI_WHITE
Background color of normal text.
GUI_WHITE
Background color of selected text.
GUI_BLACK
Text color of normal text.
GUI_BLUE
Text color of selected text.
GUI_TA_LEFT
Default text alignment
17.14.2 Notification codes
The following events are sent from the widget to its parent window as part of a
WM_NOTIFY_PARENT message:
Message
WM_NOTIFICATION_CLICKED
WM_NOTIFICATION_RELEASED
Description
Widget has been clicked.
Widget has been released.
WM_NOTIFICATION_MOVED_OUT
Widget has been clicked and pointer has been moved out
off of the widget without releasing.
WM_NOTIFICATION_SEL_CHANGED
An item has been snapped at the snap position.
17.14.3 Keyboard reaction
This widget currently does not react on keyboard input.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
540
CHAPTER
Window Objects (Widgets)
17.14.4 LISTWHEEL API
(Subject to change)
The table below lists the available emWin LISTWHEEL-related routines in alphabetical
order. Detailed descriptions of the routines follow.
Routine
LISTWHEEL_AddString()
LISTWHEEL_CreateEx()
LISTWHEEL_CreateIndirect()
LISTWHEEL_CreateUser()
LISTWHEEL_GetFont()
LISTWHEEL_GetItemText()
LISTWHEEL_GetLBorder()
LISTWHEEL_GetLineHeight()
LISTWHEEL_GetNumItems()
LISTWHEEL_GetPos()
LISTWHEEL_GetRBorder()
LISTWHEEL_GetSel()
LISTWHEEL_GetTextAlign()
LISTWHEEL_GetUserData()
LISTWHEEL_MoveToPos()
LISTWHEEL_OwnerDraw()
LISTWHEEL_SetBkColor()
LISTWHEEL_SetFont()
LISTWHEEL_SetItemData()
LISTWHEEL_SetLBorder()
LISTWHEEL_SetLineHeight()
LISTWHEEL_SetOwnerDraw()
LISTWHEEL_SetPos()
LISTWHEEL_SetRBorder()
LISTWHEEL_SetSel()
LISTWHEEL_SetSnapPosition()
LISTWHEEL_SetText()
LISTWHEEL_SetTextAlign()
LISTWHEEL_SetTextColor()
LISTWHEEL_SetUserData()
LISTWHEEL_SetVelocity()
Description
Adds a new string.
Creates a LISTWHEEL widget.
Creates a LISTWHEEL widget from a resource table entry.
Creates a LISTWHEEL widget using extra bytes as user data.
Returns the font used to draw the data.
Returns the text of the requested item.
Returns the size in pixels of the left border.
Returns the height used for one item.
Returns the number of data items.
Returns the item index of the currently engaged item.
Returns the size in pixels of the right border.
Returns the currently selected item.
Returns the text alignment used to draw the data items.
Retrieves the data set with LISTWHEEL_SetUserData().
Moves the LISTWHEEL to the given position.
Default function for drawing the widget.
Sets the color used for the background.
Sets the font used to draw the item text.
Assigns a custom void pointer to the given data item.
Sets the size in pixels of the left border.
Sets the height used for drawing one data item.
Sets a owner draw function for drawing the widget.
Sets the LISTWHEEL to the given position.
Sets the size in pixels of the right border.
Sets the currently selected item.
Sets the snap position in pixels from the top of the widget.
Sets the contents of the widget.
Sets the alignment used to draw the data items.
Sets the color used to draw the data items.
Sets the extra data of a LISTWHEEL widget.
Starts moving the wheel with the given velocity.
LISTWHEEL_AddString()
Description
Adds a new data item (typically a string) to the widget.
Prototype
void LISTWHEEL_AddString(LISTWHEEL_Handle hObj, const char * s);
Parameter
hObj
s
Description
Handle of the widget.
Pointer to the string to be added.
Additional information
The width of the given text should fit into the horizontal widget area. Otherwise the
text will be clipped during the drawing operation.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
541
LISTWHEEL_CreateEx()
Description
Creates a LISTWHEEL widget of a specified size at a specified location.
Prototype
LISTWHEEL_Handle LISTWHEEL_CreateEx(int
x0,
int
int
xSize,
int
WM_HWIN hParent, int
int
ExFlags, int
const GUI_ConstString
Parameter
x0
y0
xsize
ysize
y0,
ySize,
WinFlags,
Id,
* ppText);
Description
Leftmost pixel of the widget (in parent coordinates).
Topmost pixel of the widget (in parent coordinates).
Horizontal size of the widget (in pixels).
Vertical size of the widget (in pixels).
hParent
Handle of parent window. If 0, the new LISTVIEW widget will be a child of the desktop (top-level window).
WinFlags
Window create flags. Typically WM_CF_SHOW in order to make the widget visible
immediately (refer to “WM_CreateWindow()” on page 309 for a list of available
parameter values).
ExFlags
Id
ppText
Not used, reserved for future use.
Window ID of the widget.
Pointer to an array of string pointers containing the elements to be displayed.
Return value
Handle of the created LISTWHEEL widget; 0 if the function fails.
Additional information
If the parameter ppText is used the last element of the array needs to be a NULL element.
Example
char * apText[] = {
"Monday",
"Tuesday",
"Wednesday",
"Thursday",
"Friday",
"Saturday",
"Sunday",
NULL
};
LISTWHEEL_CreateEx(10, 10, 100, 100, WM_HBKWIN, WM_CF_SHOW,
0, GUI_ID_LISTWHEEL0, apText);
LISTWHEEL_CreateIndirect()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateIndirect().
LISTWHEEL_CreateUser()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateUser(). For
a detailed description of the parameters the function LISTWHEEL_CreateEx() can be
referred to.
LISTWHEEL_GetFont()
Description
Returns the font which is used to draw the data items of the given widget.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
542
CHAPTER
Window Objects (Widgets)
Prototype
const GUI_FONT GUI_UNI_PTR * LISTWHEEL_GetFont(LISTWHEEL_Handle hObj);
Parameter
hObj
Description
Handle of the widget.
Return value
Pointer to a GUI_FONT structure which is used to draw the data items.
LISTWHEEL_GetItemText()
Description
Returns the text of the requested data item.
Prototype
void LISTWHEEL_GetItemText(LISTWHEEL_Handle
hObj,
unsigned Index,
char
* pBuffer, int
MaxSize);
Parameter
hObj
Index
pBuffer
MaxSize
Description
Handle of the widget.
Index of the requested item.
Buffer for storing the text.
Size in bytes of the buffer.
Additional information
The function copies the text of the given item into the given buffer. If the size of the
buffer is too small the text will be clipped.
LISTWHEEL_GetLBorder()
Description
Returns the size in pixels between the left border of the widget and the beginning of the
text.
Prototype
int LISTWHEEL_GetLBorder(LISTWHEEL_Handle hObj);
Parameter
hObj
Description
Handle of the widget.
Return value
Number of pixels between left border and text.
LISTWHEEL_GetLineHeight()
Description
Returns the height of one data item.
Prototype
unsigned LISTWHEEL_GetLineHeight(LISTWHEEL_Handle hObj);
Parameter
hObj
Description
Handle of the widget.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
543
Return value
Height of one data item.
Additional information
This function returns the value set by the function LISTWHEEL_SetLineHeight(). A
return value of zero means the height of one item depends on the size of the current
font.
For
more
details,
refer
to
“LISTWHEEL_SetLineHeight()”
on
page 547,“LISTWHEEL_GetFont()” on page 541, and “GUI_GetYSizeOfFont()” on
page 187.
LISTWHEEL_GetNumItems()
Description
Returns the number of data items of the given widget.
Prototype
int LISTWHEEL_GetNumItems(LISTWHEEL_Handle hObj);
Parameter
hObj
Description
Handle of the widget.
Return value
Number of data items of the given widget.
LISTWHEEL_GetPos()
Description
Returns the zero based index of the item which is currently snapped in.
Prototype
int LISTWHEEL_GetPos(LISTWHEEL_Handle hObj);
Parameter
hObj
Description
Handle of the widget.
Return value
Index of the item which is currently snapped in.
Additional information
The position at which the items being snapped can be set with the function
LISTWHEEL_SetSnapPosition().
For
more
details,
refer
to
“LISTWHEEL_SetSnapPosition()” on page 550.
LISTWHEEL_GetRBorder()
Description
Returns the size in pixels between the right border of the widget and the end of the text.
Prototype
int LISTWHEEL_GetRBorder(LISTWHEEL_Handle hObj);
Parameter
hObj
Description
Handle of the widget.
Return value
Number of pixels between right border and text.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
544
CHAPTER
Window Objects (Widgets)
LISTWHEEL_GetSel()
Description
Returns the zero based index of the currently selected item.
Prototype
int LISTWHEEL_GetSel(LISTWHEEL_Handle hObj);
Parameter
hObj
Description
Handle of the widget.
Return value
Index of the currently selected item.
Additional information
For more information, refer to “LISTWHEEL_SetSel()” on page 549.
LISTWHEEL_GetSnapPosition()
Description
Returns the position in pixels from the top of the widget at which the data items should be
’snapped in’.
Prototype
int LISTWHEEL_GetSnapPosition(LISTWHEEL_Handle hObj);
Parameter
hObj
Description
Handle of the widget.
Return value
Snap position in pixels from the top edge of the widget.
Additional information
The default value is 0.
LISTWHEEL_GetTextAlign()
Description
Returns the text alignment of the given widget.
Prototype
int LISTWHEEL_GetTextAlign(LISTWHEEL_Handle hObj);
Parameter
hObj
Description
Handle of the widget.
Return value
Text alignment of the given widget.
Additional information
For more information, refer to “LISTWHEEL_SetTextAlign()” on page 551.
LISTWHEEL_GetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_GetUserData().
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
545
LISTWHEEL_MoveToPos()
Description
Moves the data area of the widget to the given position.
Prototype
void LISTWHEEL_MoveToPos(LISTWHEEL_Handle hObj, unsigned int Index);
Parameter
hObj
Index
Description
Handle of the widget.
Zero based index of the item to which the ’wheel’ should move.
Additional information
The widget starts moving by choosing the shortest way. If for example 7 items are
available and item 2 is currently snapped and the widget should move to the last
item it begins moving backwards until the seventh item has been reached.
Please also refer to “LISTWHEEL_SetPos()” on page 548.
LISTWHEEL_OwnerDraw()
Description
Default function for managing drawing operations of one data item.
Prototype
int LISTWHEEL_OwnerDraw(const WIDGET_ITEM_DRAW_INFO * pDrawItemInfo);
Parameter
hObj
Description
Handle of the widget.
Return value
Depends on the command in the Cmd element of the WIDGET_ITEM_DRAW_INFO structure
pointed by pDrawItemInfo.
Additional information
This function is useful if LISTWHEEL_SetOwnerDraw() is used. It can be used to
retrieve the original size of a data item and/or to draw the text of a data item and
should be called for all commands which are not managed by the application defined
owner draw function.
The following commands are managed by the default function:
•
•
•
WIDGET_ITEM_GET_XSIZE
WIDGET_ITEM_GET_YSIZE
WIDGET_ITEM_DRAW
For
more
information,
refer
to
“User
drawn
widgets”
on
page 354,“LISTWHEEL_SetOwnerDraw()” on page 548, and to the provided example.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
546
CHAPTER
Window Objects (Widgets)
LISTWHEEL_SetBkColor()
Before
After
Description
Sets the specified background color for selected and unselected items.
Prototype
void LISTWHEEL_SetBkColor(LISTWHEEL_Handle hObj,
unsigned int Index,
GUI_COLOR
Color);
Parameter
hObj
Index
Color
Description
Handle of the widget.
See element list below.
New background color.
Permitted values for element Index
LISTWHEEL_CI_UNSEL
LISTWHEEL_CI_SEL
Changes the background color for all unselected items.
Changes the background color for the selected item.
LISTWHEEL_SetFont()
Before
After
Description
Sets the font which should be used to draw the data items.
Prototype
void LISTWHEEL_SetFont(LISTWHEEL_Handle
hObj,
const GUI_FONT GUI_UNI_PTR * pFont);
Parameter
hObj
pFont
Description
Handle of the widget.
Pointer to a GUI_FONT structure.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
547
LISTWHEEL_SetLBorder()
Before
After
Description
Sets the border size between the left edge of the widget and the beginning of the text.
Prototype
void LISTWHEEL_SetLBorder(LISTWHEEL_Handle hObj, unsigned BorderSize);
Parameter
hObj
BorderSize
Description
Handle of the widget.
Desired border size.
Additional information
The default value of the border size is 0.
LISTWHEEL_SetLineHeight()
Before
After
Description
Sets the line height used to draw a data item.
Prototype
void LISTWHEEL_SetLineHeight(LISTWHEEL_Handle hObj, unsigned LineHeight);
Parameter
hObj
LineHeight
Description
Handle of the widget.
Desired height. Default is 0 which means the font size determines the height of a line.
Additional information
Per default the height of a line depends on the used font. The value set by this function ’overwrites’ this default behavior.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
548
CHAPTER
Window Objects (Widgets)
LISTWHEEL_SetOwnerDraw()
Before
After
Description
Sets an application defined owner draw function for the widget which is responsible for
drawing the widget items.
Prototype
void LISTWHEEL_SetOwnerDraw(LISTWHEEL_Handle
hObj,
WIDGET_DRAW_ITEM_FUNC * pfOwnerDraw);
Parameter
hObj
pfOwnerDraw
Description
Handle of the widget.
Pointer to owner draw function.
Additional information
This function sets a pointer to an application defined function which will be called by
the widget when a data item has to be drawn or when the x or y size of a item is
needed. It gives you the possibility to draw anything as data item, not just plain text.
pfDrawItem
is
a
pointer
to
an
application-defined
function
of
type
WIDGET_DRAW_ITEM_FUNC which is explained at the beginning of the chapter.
The
following
commands
are
supported:
WIDGET_ITEM_GET_YSIZE,
WIDGET_ITEM_DRAW, WIDGET_DRAW_BACKGROUND and WIDGET_DRAW_OVERLAY.
Example
The following example routine draws 2 red indicator lines over the widget:
static int _OwnerDraw(const WIDGET_ITEM_DRAW_INFO * pDrawItemInfo) {
switch (pDrawItemInfo->Cmd) {
case WIDGET_DRAW_OVERLAY:
GUI_SetColor(GUI_RED);
GUI_DrawHLine(40, 0, 99);
GUI_DrawHLine(59, 0, 99);
break;
default:
return LISTWHEEL_OwnerDraw(pDrawItemInfo);
}
return 0;
}
LISTWHEEL_SetPos()
Description
Sets the data area of the widget to the given position.
Prototype
void LISTWHEEL_SetPos(LISTWHEEL_Handle hObj, unsigned int Index);
Parameter
hObj
Index
Description
Handle of the widget.
Zero based index of the item to which the ’wheel’ should be set.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
549
Additional information
Please also refer to “LISTWHEEL_MoveToPos()” on page 545.
LISTWHEEL_SetRBorder()
Before
After
Description
Sets the border size between the left edge of the widget and the beginning of the text.
Prototype
void LISTWHEEL_SetRBorder(LISTWHEEL_Handle hObj, unsigned BorderSize);
Parameter
hObj
BorderSize
Description
Handle of the widget.
Desired border size.
Additional information
The default value of the border size is 0.
LISTWHEEL_SetSel()
Before
After
Description
The function sets the selected item.
Prototype
void LISTWHEEL_SetSel(LISTWHEEL_Handle hObj, int Sel);
Parameter
hObj
Sel
Description
Handle of the widget.
Zero based index of item to be selected.
Additional information
Only one item can be selected. Per default the item with index 0 is selected.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
550
CHAPTER
Window Objects (Widgets)
LISTWHEEL_SetSnapPosition()
Before
After
Description
The function sets the relative position from the top of the widget at which the items should
snap in. Per default the snap position is 0 which means the items are snapped in at the top
of the widget.
Prototype
void LISTWHEEL_SetSnapPosition(LISTWHEEL_Handle hObj, int SnapPosition);
Parameter
hObj
Description
Handle of the widget.
Relative position in pixels from the top of the widget at which the items should be
SnapPosition snapped in.
Additional information
The function LISTWHEEL_GetPos() can be used to get the zero based index of the
current item which has been snapped in.
LISTWHEEL_SetText()
Before
After
Description
It removes any existing item and adds the given items passed by the function.
Prototype
void LISTWHEEL_SetText(LISTWHEEL_Handle
hObj,
const GUI_ConstString * ppText);
Parameter
hObj
ppText
Description
Handle of the widget.
Pointer to an array of strings. The last item needs to be a NULL pointer.
Additional information
Note that the last element pointed to by ppText needs to be a NULL pointer.
EXample
The following should show how the function should be used:
static char * _apText[] = {
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
551
"Monday",
"Tuesday",
"Wednesday",
"Thursday",
"Friday",
"Saturday",
"Sunday",
NULL
};
static void _SetContents(void) {
LISTWHEEL_SetText(hWin, _apText);
}
LISTWHEEL_SetTextAlign()
Before
After
Description
Sets the text alignment used to draw the items of the widget.
Prototype
void LISTWHEEL_SetTextAlign(LISTWHEEL_Handle hObj, int Align);
Parameter
hObj
Align
Description
Handle of the widget.
Alignment to be used to draw the items of the widget.
Additional information
For details about text alignment, refer to “GUI_SetTextAlign()” on page 82.
LISTWHEEL_SetTextColor()
Before
After
Description
Sets the color to be used to draw the text.
Prototype
void LISTWHEEL_SetTextColor(LISTWHEEL_Handle hObj,
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
552
CHAPTER
Window Objects (Widgets)
unsigned int
Parameter
hObj
Index
Color
Index, GUI_COLOR Color);
Description
Handle of the widget.
(see table below)
Color to be used.
Permitted values for parameter Index
LISTWHEEL_CI_UNSEL
LISTWHEEL_CI_SEL
Sets the color of the not selected text.
Sets the color of the selected text.
LISTWHEEL_SetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_SetUserData().
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
553
17.15 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 example which shows how to use the
MENU widget. It can be found under Sample\Application\Reversi.c.
The table below shows the appearance of a horizontal MENU widget with a vertical
submenu:
Description
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.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
554
CHAPTER
Window Objects (Widgets)
17.15.1 Menu messages
To inform its owner about selecting an item or opening a submenu the menu widget
sends a message of type WM_MENU to its owner.
WM_MENU
Description
This message is sent to inform the owner of a menu about selecting an item or opening a submenu. Disabled menu items will not send this message.
Data
The Data.p pointer of the message points to a MENU_MSG_DATA structure.
Elements of MENU_MSG_DATA
Data type
U16
U16
Element
MsgType
ItemId
Description
(see table below)
Id of menu item.
Permitted values for element MsgType
MENU_ON_INITMENU
This message is send to the owner of menu immediately before the menu opens. This gives the application the chance to modify the menu before it is
shown.
MENU_ON_ITEMACTIVATE
The owner window of a menu will receive this message after a menu item has been highlighted. The
message is not send after highlighting a sub menu.
MENU_ON_ITEMPRESSED
After pressing a menu item this message will be
send to the owner window of the widget. It will be
send also for disabled menu items.
MENU_ON_ITEMSELECT
This message is send to the owner of a menu
immediately after a menu item is selected. The
ItemId element contains the Id of the pressed
menu item.
Example
The following example shows how to react on a WM_MENU message:
void Callback(WM_MESSAGE * pMsg) {
MENU_MSG_DATA * pData;
WM_HWIN hWin = pMsg->hWin;
switch (pMsg->MsgId) {
case WM_MENU:
pData = (MENU_MSG_DATA *)pMsg->Data.p;
switch (pData->MsgType) {
case MENU_ON_ITEMACTIVATE:
_UpdateStatusbar(pData->ItemId);
break;
case MENU_ON_INITMENU:
_OnInitMenu();
break;
case MENU_ON_ITEMSELECT:
switch (pData->ItemId) {
case ID_MENU_ITEM0:
... /* React on selection of menu item 0 */
break;
case ID_MENU_ITEM1:
... /* React on selection of menu item 1 */
break;
case ...
...
}
break;
}
break;
default:
MENU_Callback(pMsg);
}
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
555
}
17.15.2 Data structures
The following shows the menu widget related data structures.
MENU_ITEM_DATA
This structure serves as a container to set or retrieve information about menu items.
Elements of MENU_ITEM_DATA
Data type
Element
const char *
U16
U16
pText
Id
Flags
MENU_Handle
hSubmenu
Description
Menu item text.
Id of the menu item.
(see table below)
If the item represents a submenu this element contains the handle of
the submenu.
Permitted values for element Flags
Item is disabled.
MENU_IF_DISABLED
MENU_IF_SEPARATOR
Item is a separator.
17.15.3 Configuration options
Type
Macro
Default
Description
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 submenu items.
N
MENU_BORDER_BOTTOM_DEFAULT 2
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
MENU_FONT_DEFAULT
WIDGET_Effect_3D1L Default effect.
S
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.
Border between item text and item
bottom.
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.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
556
CHAPTER
Window Objects (Widgets)
17.15.4 Keyboard reaction
The widget reacts to the following keys if it has the input focus:
Key
Reaction
GUI_KEY_RIGHT
- If the menu is horizontal, the selection moves one item to the right.
- If the menu is vertical and the current item is a submenu, the submenu opens and the input focus moves to the submenu.
- If the menu is vertical and the current item is not a submenu and the
top level menu is horizontal, the next item of the top level menu opens
and the input focus moves to it.
GUI_KEY_LEFT
- If the menu is horizontal the selection moves one item to the left.
- If the menu is vertical and the menu is not the top level menu, the
current menu closes and the focus moves to the previous menu. If the
previous menu is horizontal the previous submenu of it opens and the
focus moves to the previous submenu.
GUI_KEY_DOWN
- If the menu is horizontal and the current menu item is a submenu this
submenu opens.
- If the menu is vertical, the selection moves to the next item.
GUI_KEY_UP
- If the menu is vertical, the selection moves to the previous item.
GUI_KEY_ESCAPE
- If the menu is not the top level menu the current menu will be closed
and the focus moves to the previous menu.
- If the menu is the top level menu, the current menu item becomes
unselected.
GUI_KEY_ENTER
- If the current menu item is a submenu, the submenu opens and the
focus moves to the submenu.
- If the current menu item is not a submenu, all submenus of the top
level menu closes and a MENU_ON_ITEMSELECT message will be send
to the owner of the menu.
17.15.5 MENU API
The table below lists the available emWin MENU-related routines in alphabetical
order. Detailed descriptions of the routines follow.
Routine
Description
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()
MENU_CreateIndirect()
MENU_CreateUser()
MENU_DeleteItem()
MENU_DisableItem()
MENU_EnableItem()
MENU_GetDefaultBkColor()
MENU_GetDefaultBorderSize()
MENU_GetDefaultEffect()
MENU_GetDefaultFont()
MENU_GetDefaultTextColor()
MENU_GetItem()
MENU_GetItemText()
MENU_GetNumItems()
MENU_GetOwner()
MENU_GetUserData()
MENU_InsertItem()
MENU_Popup()
MENU_SetBkColor()
MENU_SetBorderSize()
User's & reference manual for emWin V5.10
Creates a MENU widget.
Creates a MENU widget from a resource table entry.
Creates a MENU widget using extra bytes as user data.
Deletes the specified menu item.
Disables the specified menu item.
Enables the specified menu item.
Returns the default background color for new menus.
Returns the default border size for new menus.
Returns the default effect for new menus.
Returns a pointer to the default font used to display the menu
item text of new menus.
Returns the default text color for new menus.
Retrieves information about the given menu item.
Returns the text of the given menu item.
Returns the number of items of the given menu.
Returns the owner window of the given menu.
Retrieves the data set with MENU_SetUserData().
Inserts a menu item.
Opens a popup menu at the given position.
Sets the background color of the given menu.
Sets the border size of the given menu.
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
557
Routine
MENU_SetDefaultBkColor()
MENU_SetDefaultBorderSize()
MENU_SetDefaultEffect()
Description
Sets the default background color for new menus.
Sets the default border size for new menus.
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()
MENU_SetOwner()
MENU_SetTextColor()
MENU_SetUserData()
Changes the information about the given menu item.
Sets the window to be informed by the menu.
Sets the text color of the given menu.
Sets the extra data of a MENU widget.
MENU_AddItem()
Before
After
Description
This function adds a new item to the end of the given menu.
Prototype
void MENU_AddItem(MENU_Handle hObj, const MENU_ITEM_DATA * pItemData);
Parameter
hObj
pItemData
Description
Handle of widget.
Pointer to a MENU_ITEM_DATA structure containing the information of the new item.
Additional information
If using a menu with several submenus the Id of the menu items should be unique.
Different submenus should not contain menu items with the same Ids.
When adding items to a menu and no fixed sizes are used the size of the menu will be
adapted.
Refer to “MENU_ITEM_DATA” on page 555.
MENU_Attach()
Description
Attaches the given menu at the given position with the given size to a specified window.
Prototype
void MENU_Attach(MENU_Handle hObj,
int
x,
int
xSize,
User's & reference manual for emWin V5.10
WM_HWIN hDestWin,
int
y,
int
ySize,
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
558
CHAPTER
int
Flags);
Parameter
hObj
hDestWin
x
y
xSize
ySize
Flags
Window Objects (Widgets)
Description
Handle of widget.
Handle to the window to which the menu should be attached.
X position in window coordinates of the menu.
Y position in window coordinates of the menu.
Fixed X size of the menu. For details, refer to “MENU_CreateEx()” on page 558.
Fixed Y size of the menu. For details, refer to “MENU_CreateEx()” on page 558.
Reserved for future use
Additional information
After creating a menu widget this function can be used to attach the menu to an
existing window.
MENU_CreateEx()
Description
Creates a MENU widget of a specified size at a specified location.
Prototype
MENU_Handle MENU_CreateEx(int
int
WM_HWIN
int
Parameter
x0
y0
xSize
ySize
x0,
xSize,
hParent,
ExFlags,
int
int
int
int
y0,
ySize,
WinFlags,
Id);
Description
Leftmost pixel of the widget (in parent coordinates).
Topmost pixel of the widget (in parent coordinates).
Fixed horizontal size of the widget (in pixels). 0 if menu should handle the xSize.
Fixed vertical size of the widget (in pixels). 0 if menu should handle the ySize.
hParent
Handle of parent window. If 0, the new widget will be a child of the desktop (toplevel window).
In some cases it can be useful to create the menu widget in ’unattached’ state and
attach it later to an existing window. For this case WM_UNATTACHED can be used as
parameter.
WinFlags
Window create flags. Typically WM_CF_SHOW in order to make the widget visible
immediately (refer to “WM_CreateWindow()” on page 309 for a list of available
parameter values).
ExFlags
Id
(see table below)
Window ID of the widget.
Permitted values for parameter ExFlags
MENU_CF_HORIZONTAL
MENU_CF_VERTICAL
Creates a horizontal menu.
Creates a vertical menu.
Return value
Handle of the created MENU widget; 0 if the function fails.
Additional information
The parameters xSize and/or ySize specifies if a fixed width and/or height should be
used for the menu.
If these parameters are > 0, fixed sizes should be used. If for example the menu
should be attached as a horizontal menu to the top of a window it can be necessary
to use a fixed X size which covers the whole top of the window. In this case the
parameter xSize can be used to set a fixed X size of the menu. When attaching or
deleting items of a menu with a fixed size the size of the widget does not change.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
559
If the values are 0, the menu handles its size itself. That means the size of the menu
depends on the size of the current menu items of a menu. If items are added or
removed the size of the widget will be adapted.
MENU_CreateIndirect()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateIndirect().
MENU_CreateUser()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateUser(). For
a detailed description of the parameters the function MENU_CreateEx() can be
referred to.
MENU_DeleteItem()
Before
After
Description
Deletes a given menu entry from a menu.
Prototype
void MENU_DeleteItem(MENU_Handle hObj, U16 ItemId);
Parameter
hObj
ItemId
Description
Handle of widget.
Id of the menu item to be deleted.
Additional information
If the item does not exist the function returns immediately.
When deleting items from a menu and no fixed sizes are used the window size will be
adapted.
MENU_DisableItem()
Before
After
Description
Disables the given menu item.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
560
CHAPTER
Window Objects (Widgets)
Prototype
void MENU_DisableItem(MENU_Handle hObj, U16 ItemId);
Parameter
hObj
ItemId
Description
Handle of widget.
Id of the menu item to be disabled.
Additional information
If a disabled menu item is selected, the menu widget sends no WM_MENU message to
the owner. A disabled submenu item can not be opened.
MENU_EnableItem()
Before
After
Description
Enables the given menu item.
Prototype
void MENU_EnableItem(MENU_Handle hObj, U16 ItemId);
Parameter
hObj
ItemId
Description
Handle of widget.
Id of the menu item to be enabled.
Additional information
For details, refer to “MENU_DisableItem()” on page 559.
MENU_GetDefaultBkColor()
Description
Returns the default background color used to draw new menu items.
Prototype
GUI_COLOR MENU_GetDefaultBkColor(unsigned ColorIndex);
Parameter
ColorIndex
Description
Index of color to be returned (see table below).
Permitted values for parameter ColorIndex
MENU_CI_ACTIVE_SUBMENU
MENU_CI_DISABLED
Background color of active submenu items.
Background color of disabled menu items.
MENU_CI_DISABLED_SEL
Background color of disabled and selected menu
items.
MENU_CI_ENABLED
Background color of enabled and not selected
menu items.
MENU_CI_SELECTED
Background color of enabled and selected menu
items.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
561
Return value
Default background color used to draw new menu items.
Additional information
For details, refer to “MENU_SetBkColor()” on page 564.
MENU_GetDefaultBorderSize()
Description
Returns the default border size used for new menu widgets.
Prototype
U8 MENU_GetDefaultBorderSize(unsigned BorderIndex);
Parameter
BorderIndex
Description
(see table below)
Permitted values for parameter BorderIndex
MENU_BI_BOTTOM
MENU_BI_LEFT
MENU_BI_RIGHT
MENU_BI_TOP
Border between item text and item bottom.
Border between item text and left edge of item.
Border between item text and right edge of item
Border between item text and item top.
Return value
Default border size used for new menu widgets.
Additional information
For details, refer to “MENU_SetBorderSize()” on page 565.
MENU_GetDefaultEffect()
Description
Returns the default effect for new menus.
Prototype
const WIDGET_EFFECT * MENU_GetDefaultEffect(void);
Return value
The result of the function is a pointer to a WIDGET_EFFECT structure.
Additional information
For more information, refer to “WIDGET_SetDefaultEffect()” on page 353.
MENU_GetDefaultFont()
Description
Returns a pointer to the default font used to display the menu item text of new menus.
Prototype
const GUI_FONT * MENU_GetDefaultFont(void);
Return value
Pointer to the default font used to display the menu item text of new menus.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
562
CHAPTER
Window Objects (Widgets)
MENU_GetDefaultTextColor()
Description
Returns the default text color for new menus.
Prototype
GUI_COLOR MENU_GetDefaultTextColor(unsigned ColorIndex);
Parameter
ColorIndex
Description
Index of color to be returned (see table below)
Permitted values for parameter ColorIndex
MENU_CI_ACTIVE_SUBMENU
MENU_CI_DISABLED
MENU_CI_DISABLED_SEL
Text color of active submenu items.
Text color of disabled menu items.
Text color of disabled and selected menu items.
MENU_CI_ENABLED
Text color of enabled and not selected menu
items.
MENU_CI_SELECTED
Text color of enabled and selected menu items.
Return value
Default text color for new menus.
Additional information
For details, refer to “MENU_SetDefaultTextColor()” on page 567.
MENU_GetItem()
Description
Retrieves information about the given menu item.
Prototype
void MENU_GetItem(MENU_Handle hObj, U16 ItemId, MENU_ITEM_DATA * pItemData);
Parameter
hObj
ItemId
pItemData
Description
Handle of widget.
Id of the requested menu item.
Pointer to a MENU_ITEM_DATA structure to be filled by the function.
Additional information
If using a menu with several submenus the handle of the widget needs to be the handle of the menu/submenu containing the requested item or the handle of a higher
menu/submenu.
The function sets the element pText of the MENU_ITEM_INFO data structure to 0. To
retrieve the menu item text the function MENU_GetItemText() should be used.
Refer to the beginning of the menu chapter for details about the MENU_ITEM_INFO
data structure.
MENU_GetItemText()
Description
Returns the text of the given menu item.
Prototype
void MENU_GetItemText(MENU_Handle
User's & reference manual for emWin V5.10
hObj,
U16
ItemId,
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
563
char
* pBuffer, unsigned BufferSize);
Parameter
hObj
ItemId
pBuffer
BufferSize
Description
Handle of widget.
Id of the requested menu item.
Buffer to be filled by the function.
Maximum number of bytes to be retrieved.
MENU_GetNumItems()
Description
Returns the number of items of the given menu.
Prototype
unsigned MENU_GetNumItems(MENU_Handle hObj);
Parameter
hObj
Description
Handle of widget.
Return value
Number of items of the given menu.
MENU_GetOwner()
Description
Returns the owner window of the given menu.
Prototype
WM_HWIN MENU_GetOwner(MENU_Handle hObj);
Parameter
hObj
Description
Handle of widget.
Return value
Owner window of the given menu.
MENU_GetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_GetUserData().
MENU_InsertItem()
Before
After
Description
Inserts a menu item at the given position.
Prototype
void MENU_InsertItem(MENU_Handle hObj, U16 ItemId,
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
564
CHAPTER
Window Objects (Widgets)
const MENU_ITEM_DATA * pItemData);
Parameter
hObj
ItemId
pItemData
Description
Handle of widget.
Id of the menu item the new item should be inserted before.
Pointer to a MENU_ITEM_DATA structure containing the information of the new item.
Additional information
Refer to the beginning of the menu chapter for details about the MENU_ITEM_INFO
data structure.
MENU_Popup()
Description
Opens the given menu at the given position. After selecting a menu item or after touching
the display outside the menu the popup menu will be closed.
Prototype
void MENU_Popup(MENU_Handle
int
int
int
hObj,
WM_HWIN hDestWin,
x,
int
y,
xSize, int
ySize,
Flags);
Parameter
hObj
hDestWin
x
y
xSize
ySize
Flags
Description
Handle of widget.
Handle to the window to which the menu should be attached.
X position in window coordinates of the menu.
Y position in window coordinates of the menu.
Fixed X size of the menu. For details, refer to “MENU_CreateEx()” on page 558.
Fixed Y size of the menu. For details, refer to “MENU_CreateEx()” on page 558.
Reserved for future use
Additional information
After selecting a menu item or after touching the display outside the popup menu the
menu will be closed. Note that the menu will not be deleted automatically.
The Sample folder contains the example WIDGET_PopupMenu.c which shows how to
use the function.
MENU_SetBkColor()
Before
After
Description
Sets the background color of the given menu.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
565
Prototype
void MENU_SetBkColor(MENU_Handle hObj,
unsigned ColorIndex,
GUI_COLOR
Color);
Parameter
hObj
ColorIndex
Color
Description
Handle of widget.
Index of color (see table below)
Color to be used.
Permitted values for parameter ColorIndex
MENU_CI_ACTIVE_SUBMENU
MENU_CI_DISABLED
Background color of active submenu items.
Background color of disabled menu items.
MENU_CI_DISABLED_SEL
Background color of disabled and selected menu
items.
MENU_CI_ENABLED
Background color of enabled and not selected
menu items.
MENU_CI_SELECTED
Background color of enabled and selected menu
items.
MENU_SetBorderSize()
Before
After
The following code is executed between the screenshots above:
MENU_SetBorderSize(hMenuGame, MENU_BI_LEFT, 20);
Before
After
The following code is executed between the screenshots above:
MENU_SetBorderSize(hMenu, MENU_BI_LEFT, 10);
MENU_SetBorderSize(hMenu, MENU_BI_RIGHT, 10);
Description
Sets the border size of the given menu.
Prototype
void MENU_SetBorderSize(MENU_Handle hObj,
unsigned BorderIndex,
U8
BorderSize);
Parameter
hObj
BorderIndex
BorderSize
Description
Handle of widget.
(see table below)
Size to be used.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
566
CHAPTER
Window Objects (Widgets)
Permitted values for parameter BorderIndex
MENU_BI_BOTTOM
MENU_BI_LEFT
MENU_BI_RIGHT
MENU_BI_TOP
Border between item text and item bottom.
Border between item text and left edge of item.
Border between item text and right edge of item
Border between item text and item top.
MENU_SetDefaultBkColor()
Description
Sets the default background color used to draw new menu items.
Prototype
void MENU_SetDefaultBkColor(unsigned ColorIndex, GUI_COLOR Color);
Parameter
ColorIndex
Color
Description
Index of color to be returned (see table below).
Color to be used.
Permitted values for parameter ColorIndex
MENU_CI_ACTIVE_SUBMENU
MENU_CI_DISABLED
Background color of active submenu items.
Background color of disabled menu items.
MENU_CI_DISABLED_SEL
Background color of disabled and selected menu
items.
MENU_CI_ENABLED
Background color of enabled and not selected
menu items.
MENU_CI_SELECTED
Background color of enabled and selected menu
items.
Additional information
For details, refer to “MENU_SetBkColor()” on page 564.
MENU_SetDefaultBorderSize()
Description
Sets the default border size used for new menu widgets.
Prototype
void MENU_SetDefaultBorderSize(unsigned BorderIndex, U8 BorderSize);
Parameter
BorderIndex
BorderSize
Description
(see table below)
Border size to be used.
Permitted values for parameter BorderIndex
MENU_BI_BOTTOM
MENU_BI_LEFT
MENU_BI_RIGHT
MENU_BI_TOP
Border between item text and item bottom.
Border between item text and left edge of item.
Border between item text and right edge of item
Border between item text and item top.
Additional information
For details, refer to “MENU_SetBorderSize()” on page 565.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
567
MENU_SetDefaultEffect()
Description
Sets the default effect for new menus.
Prototype
void MENU_SetDefaultEffect(const WIDGET_EFFECT * pEffect);
Parameter
pEffect
Description
Pointer to a WIDGET_EFFECT structure.
Additional information
For more information, refer to “WIDGET_SetDefaultEffect()” on page 353.
MENU_SetDefaultFont()
Description
Sets the pointer to the default font used to display the menu item text of new menus.
Prototype
void MENU_SetDefaultFont(const GUI_FONT * pFont);
Parameter
pFont
Description
Pointer to the
GUI_FONT structure to be used.
Additional information
For details, refer to “MENU_SetFont()” on page 568.
MENU_SetDefaultTextColor()
Description
Sets the default text color for new menus.
Prototype
void MENU_SetDefaultTextColor(unsigned ColorIndex, GUI_COLOR Color);
Parameter
ColorIndex
Color
Description
Index of color to be used (see table below)
Color to be used
Permitted values for parameter ColorIndex
MENU_CI_ACTIVE_SUBMENU
MENU_CI_DISABLED
MENU_CI_DISABLED_SEL
Text color of active submenu items.
Text color of disabled menu items.
Text color of disabled and selected menu items.
MENU_CI_ENABLED
Text color of enabled and not selected menu
items.
MENU_CI_SELECTED
Text color of enabled and selected menu items.
Additional information
For details, refer to “MENU_SetTextColor()” on page 569.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
568
CHAPTER
Window Objects (Widgets)
MENU_SetFont()
Before
After
Description
Sets the pointer to the default font used to display the menu item text of new menus.
Prototype
void MENU_SetFont(MENU_Handle hObj, const GUI_FONT * pFont);
Parameter
hObj
pFont
Description
Handle of widget.
Pointer to the
GUI_FONT structure to be used.
MENU_SetItem()
Before
After
Description
Sets the item information for the given menu item.
Prototype
void MENU_SetItem(MENU_Handle
hObj,
U16 ItemId,
const MENU_ITEM_DATA * pItemData);
Parameter
hObj
ItemId
pItemData
Description
Handle of widget.
Id of the menu item to be changed.
Pointer to a MENU_ITEM_DATA structure containing the new information.
MENU_SetOwner()
Description
Sets the owner of the menu to be informed by the widget.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
569
Prototype
void MENU_SetOwner(MENU_Handle hObj, WM_HWIN hOwner);
Parameter
Description
hObj
Handle of widget.
hOwner
Handle of the owner window which should receive the WM_MENU messages of the
menu.
Additional information
If no owner is set the parent window of the menu will receive WM_MENU messages. In
some cases it makes sense to send the messages not to the parent window of the
menu. In this case this function can be used to set the recipient for the WM_MENU messages.
MENU_SetSel()
Before
After
Description
Sets the selected item of the given menu.
Prototype
void MENU_SetSel(MENU_Handle hObj, int Sel);
Parameter
hObj
Sel
Description
Handle of widget.
Zero based index of menu item to be selected.
Return value
The function returns the zero based index of the previous selected menu item.
Additional information
A value <0 for parameter Sel deselects the menu items.
MENU_SetTextColor()
Before
After
Description
Sets the text color of the given menu.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
570
CHAPTER
Window Objects (Widgets)
Prototype
void MENU_SetTextColor(MENU_Handle hObj,
unsigned ColorIndex,
GUI_COLOR
Color);
Parameter
hObj
ColorIndex
Color
Description
Handle of widget.
Index of color to be used (see table below)
Color to be used.
Permitted values for parameter ColorIndex
MENU_CI_ACTIVE_SUBMENU
MENU_CI_DISABLED
MENU_CI_DISABLED_SEL
Text color of active submenu items.
Text color of disabled menu items.
Text color of disabled and selected menu items.
MENU_CI_ENABLED
Text color of enabled and not selected menu
items.
MENU_CI_SELECTED
Text color of enabled and selected menu items.
MENU_SetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_SetUserData().
17.15.6 Example
The Sample folder contains the following example which shows how the widget can be
used:
•
WIDGET_Menu.c
Note that several other examples also make use of this widget and may also be helpful to get familiar with the widget.
Screenshot of WIDGET_Menu.c:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
571
17.16 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. The table below shows the appearance of the MESSAGEBOX widget:
Simple message box
17.16.1 Configuration options
Type
Macro
Default
Description
N
MESSAGEBOX_BORDER
4
Distance between the elements of a message box
and the elements of the client window frame.
N
MESSAGEBOX_XSIZEOK
MESSAGEBOX_YSIZEOK
MESSAGEBOX_BKCOLOR
50
X-size of the "OK" button.
20
Y-size of the "OK" button.
GUI_WHITE
Color of the client window background.
N
S
17.16.2 Keyboard reaction
The widget consists of a frame window, a text and a button widget. When executing a
message box the button gains the input focus. For more information, refer to “Keyboard reaction” on page 357.
17.16.3 MESSAGEBOX API
The table below lists the available emWin MESSAGEBOX-related routines in alphabetical order. Detailed descriptions of the routines follow.
Routine
GUI_MessageBox()
MESSAGEBOX_Create()
Description
Creates and displays a message box.
Creates a message box.
GUI_MessageBox()
Description
Creates and displays a message box.
Prototype
int GUI_MessageBox(const char* sMessage, const char* sCaption, int Flags);
Parameter
sMessage
sCaption
Flags
Description
Message to display.
Caption for the title bar of the frame window.
(see table below)
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
572
CHAPTER
Window Objects (Widgets)
Permitted values for parameter Flags
The message box can be moved by dragging
GUI_MESSAGEBOX_CF_MOVEABLE the title bar or the frame.
No function.
0
Additional information
This function gives you the possibility to create and execute a message box with one
line of code. The Sample folder contains the example DIALOG_MessageBox.c which
shows how to use this function.
For details about dragging, refer to “FRAMEWIN_SetMoveable()” on page 437.
MESSAGEBOX_Create()
Description
Creates a message box.
Prototype
WM_HWIN GUI_MessageBox(const char* sMessage, const char* sCaption, int
Flags);
Parameter
sMessage
sCaption
Flags
Description
Message to display.
Caption for the title bar of the frame window.
(see table below)
Permitted values for parameter Flags
GUI_MESSAGEBOX_CF_MODAL
Creates a modal message box. The default is
creating a non modal message box.
Return value
Handle of the message box window.
Additional information
The function creates a message box consisting of a frame window with the caption
text in the title bar, a text widget with the message text and a button widget representing the ’OK’ button. After creating the message box the dialog behaviour could
be changed by using a user defined callback function or the properties of the box
items can be modified using the widget API functions. The following Ids can be used
for accessing the items:
Id
GUI_ID_TEXT0
GUI_ID_OK
Description
Id of the TEXT widget containing the message text.
Id of the ’OK’ BUTTON widget.
The frame window can be accessed by the handle returned by this function.
The function GUI_ExecCreatedDialog() should be used to execute the message box.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
573
17.17 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:
Description
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
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
574
CHAPTER
Window Objects (Widgets)
17.17.1 Configuration options
Type
S
N
N
N
N
Macro
Default
MULTIEDIT_FONT_DEFAULT
MULTIEDIT_BKCOLOR0_DEFAULT
MULTIEDIT_BKCOLOR2_DEFAULT
MULTIEDIT_TEXTCOLOR0_DEFAULT
MULTIEDIT_TEXTCOLOR2_DEFAULT
Description
GUI_Font13_1
Font used.
GUI_WHITE
Background color.
0xC0C0C0
Background color read only mode.
GUI_BLACK
Text color.
GUI_BLACK
Text color read only mode.
17.17.2 Notification codes
The following events are sent from the widget to its parent window as part of a
WM_NOTIFY_PARENT message:
Message
Description
WM_NOTIFICATION_CLICKED
WM_NOTIFICATION_RELEASED
Widget has been clicked.
Widget has been released.
WM_NOTIFICATION_MOVED_OUT
Widget has been clicked and pointer has been moved out
off of the widget without releasing.
WM_NOTIFICATION_SCROLL_CHANGED
The scroll position of the optional scrollbar has been
changed.
WM_NOTIFICATION_VALUE_CHANGED
The text of the widget has been changed.
17.17.3 Keyboard reaction
The widget reacts to the following keys if it has the input focus:
Key
GUI_KEY_UP
GUI_KEY_DOWN
GUI_KEY_RIGHT
GUI_KEY_LEFT
GUI_KEY_END
GUI_KEY_HOME
Reaction
Moves the cursor one line up.
Moves the cursor one line down.
Moves the cursor one character to the right.
Moves the cursor one character to the left.
Moves the cursor to the end of the current row.
Moves the cursor to the begin of the current row.
GUI_KEY_BACKSPACE
If the widget works in read/write mode this key deletes the character
before the cursor.
GUI_KEY_DELETE
If the widget works in read/write mode this key deletes the character
below the cursor.
GUI_KEY_INSERT
Toggles between insert and overwrite mode.
GUI_KEY_ENTER
If the widget works in read/write mode this key inserts a new line (’\n’)
at the current position. If the widget works in read only mode the cursor
will be moved to the beginning of the next line.
17.17.4 MULTIEDIT API
The table below lists the available emWin MULTIEDIT-related routines in alphabetical
order. Detailed descriptions of the routines follow.
Routine
MULTIEDIT_AddKey()
MULTIEDIT_AddText()
MULTIEDIT_Create()
MULTIEDIT_CreateEx()
MULTIEDIT_CreateIndirect()
Description
Key input routine.
Adds additional text at the current cursor position.
Creates a MULTIEDIT widget. (Obsolete)
Creates a MULTIEDIT widget.
Creates a MULTIEDIT widget from a resource table entry.
MULTIEDIT_CreateUser()
Creates a MULTIEDIT widget using extra bytes as user
data.
MULTIEDIT_EnableBlink()
Enables/disables a blinking cursor.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
575
Routine
MULTIEDIT_GetCursorCharPos()
MULTIEDIT_GetCursorPixelPos()
MULTIEDIT_GetPrompt()
MULTIEDIT_GetText()
MULTIEDIT_GetTextSize()
MULTIEDIT_GetUserData()
MULTIEDIT_SetAutoScrollH()
MULTIEDIT_SetAutoScrollV()
MULTIEDIT_SetBkColor()
MULTIEDIT_SetBufferSize()
MULTIEDIT_SetCursorOffset()
MULTIEDIT_SetFont()
MULTIEDIT_SetInsertMode()
MULTIEDIT_SetMaxNumChars()
MULTIEDIT_SetPasswordMode()
MULTIEDIT_SetPrompt()
MULTIEDIT_SetReadOnly()
MULTIEDIT_SetText()
MULTIEDIT_SetTextAlign()
MULTIEDIT_SetTextColor()
MULTIEDIT_SetUserData()
MULTIEDIT_SetWrapWord()
MULTIEDIT_SetWrapNone()
Description
Returns the number of the character at the cursor position.
Returns the pixel position of the cursor.
Returns the text of the prompt.
Returns the text.
Returns the buffer size used by the current text.
Retrieves the data set with MULTIEDIT_SetUserData().
Activates automatic use of a horizontal scrollbar.
Activates automatic use of a vertical scrollbar.
Sets the background color.
Sets the buffer size used for text and prompt.
Sets the cursor to the given character.
Sets the font.
Enables/disables the insert mode.
Sets the maximum number of characters including the
prompt.
Enables/disables password mode.
Sets the prompt text.
Enables/disables the read only mode.
Sets the text.
Sets the text alignment.
Sets the text color,
Sets the extra data of a MULTIEDIT widget.
Enables/disables word wrapping.
Enables/disables the non wrapping mode.
MULTIEDIT_AddKey()
Description
Adds user input to a specified multiedit widget.
Prototype
void MULTIEDIT_AddKey(MULTIEDIT_HANDLE hObj, int Key);
Parameter
hObj
Key
Description
Handle of multiedit widget.
Character to be added.
Additional information
The specified character is added to the user input of the multiedit widget. If the maximum count of characters has been reached, another character will not be added.
MULTIEDIT_AddText()
Description
Adds the given text at the current cursor position.
Prototype
int MULTIEDIT_AddText(MULTIEDIT_HANDLE hObj, const char * s);
Parameter
hObj
s
Description
Handle of multiedit widget.
Pointer to a NULL terminated text to be added.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
576
CHAPTER
Window Objects (Widgets)
Additional information
If the number of characters exceeds the limit set with the function
MULTIEDIT_SetMaxNumChars() the function will add only the characters of the text
which fit into the widget respecting the limit.
MULTIEDIT_Create()
(Obsolete, MULTIEDIT_CreateEx() should be used instead)
Description
Creates a MULTIEDIT widget of a specified size at a specified location.
Prototype
MULTIEDIT_HANDLE MULTIEDIT_Create(int
int
WM_HWIN
int
const char *
Parameter
x0
y0
xsize
ysize
hParent
Id
Flags
ExFlags
pText
MaxLen
x0,
xsize,
hParent,
Flags,
pText,
int
int
int
int
int
y0,
ysize,
Id,
ExFlags,
MaxLen);
Description
Leftmost pixel of the multiedit widget (in parent coordinates).
Topmost pixel of the multiedit widget (in parent coordinates).
Horizontal size of the multiedit widget (in pixels).
Vertical size of the multiedit widget (in pixels).
Parent window of the multiedit widget.
ID of the multiedit widget.
Window create flags. Typically WM_CF_SHOW in order to make the widget visible
immediately (refer to WM_CreateWindow() in the chapter “The Window Manager
(WM)” on page 289 for a list of available parameter values).
(see table below)
Text to be used.
Maximum number of bytes for text and prompt.
Permitted values for parameter ExFlags
MULTIEDIT_CF_AUTOSCROLLBAR_H
MULTIEDIT_CF_AUTOSCROLLBAR_V
MULTIEDIT_CF_INSERT
MULTIEDIT_CF_READONLY
Automatic use of a horizontal scrollbar.
Automatic use of a vertical scrollbar.
Enables insert mode.
Enables read only mode.
Return value
Handle of the created MULTIEDIT widget; 0 if the function fails.
MULTIEDIT_CreateEx()
Description
Creates a MULTIEDIT widget of a specified size at a specified location.
Prototype
MULTIEDIT_HANDLE MULTIEDIT_CreateEx(int
int
WM_HWIN
int
int
User's & reference manual for emWin V5.10
x0,
xsize,
hParent,
ExFlags,
BufferSize,
int
int
int
int
y0,
ysize,
WinFlags,
Id,
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
577
const char * pText);
Parameter
x0
y0
xsize
ysize
hParent
Description
Leftmost pixel of the widget (in parent coordinates).
Topmost pixel of the widget (in parent coordinates).
Horizontal size of the widget (in pixels).
Vertical size of the widget (in pixels).
Handle of parent window. If 0, the new MULTIEDIT widget will be a child of the desktop (top-level window).
Window create flags. Typically
WM_CF_SHOW in order to make the widget visible
WinFlags
immediately (refer to WM_CreateWindow() in the chapter “The Window Manager
(WM)” on page 289 for a list of available parameter values).
ExFlags
Id
(see table below)
Window ID of the widget.
BufferSize
Initial text buffer size of the widget. Use
the maximum number of characters.
pText
Text to be used.
MULTIEDIT_SetMaxNumChars to set
Permitted values for parameter ExFlags
MULTIEDIT_CF_AUTOSCROLLBAR_H
MULTIEDIT_CF_AUTOSCROLLBAR_V
MULTIEDIT_CF_INSERT
MULTIEDIT_CF_READONLY
Automatic use of a horizontal scrollbar.
Automatic use of a vertical scrollbar.
Enables insert mode.
Enables read only mode.
Return value
Handle of the created MULTIEDIT widget; 0 if the function fails.
MULTIEDIT_CreateIndirect()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateIndirect().
MULTIEDIT_CreateUser()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateUser(). For
a detailed description of the parameters the function MULTIEDIT_CreateEx() can be
referred to.
MULTIEDIT_EnableBlink()
Description
Enables/disables a blinking cursor.
Prototype
void MULTIEDIT_EnableBlink(EDIT_Handle hObj, int Period, int OnOff);
Parameter
hObj
Period
OnOff
Description
Handle of edit field.
Blinking period
1 enables blinking, 0 disables blinking
Additional information
This function calls GUI_X_GetTime().
MULTIEDIT_GetCursorCharPos()
Description
Returns the number of the character at the cursor position.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
578
CHAPTER
Window Objects (Widgets)
Prototype
int MULTIEDIT_GetCursorCharPos(MULTIEDIT_Handle hObj);
Parameter
hObj
Description
Handle of multiedit widget.
Return value
Number of the character at the cursor position.
Additional information
The widget returns the character position if it has the focus or not. This means the
cursor position is also returned, if the cursor is currently not visible in the widget.
MULTIEDIT_GetCursorPixelPos()
Description
Returns the pixel position of the cursor in window coordinates.
Prototype
void MULTIEDIT_GetCursorPixelPos(MULTIEDIT_Handle
hObj,
int
* pxPos, int * pyPos);
Parameter
hObj
pxPos
pyPos
Description
Handle of multiedit widget.
Pointer to integer variable for the X-position in window coordinates.
Pointer to integer variable for the Y-position in window coordinates.
Additional information
The widget returns the pixel position if it has the focus or not. This means the cursor
position is also returned, if the cursor is currently not visible in the widget.
MULTIEDIT_GetPrompt()
Description
Returns the current prompt text.
Prototype
void MULTIEDIT_GetPrompt(MULTIEDIT_HANDLE hObj, char * sDest, int MaxLen);
Parameter
hObj
sDest
MaxLen
Description
Handle of multiedit widget.
Buffer for the prompt text to be returned.
Maximum number of bytes to be copied to sDest.
Additional information
The function copies the current prompt text to the buffer given by sDest. The maximum number of bytes copied to the buffer is given by MaxLen.
MULTIEDIT_GetText()
Description
Returns the current text.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
579
Prototype
void MULTIEDIT_GetText(MULTIEDIT_HANDLE hObj, char * sDest, int MaxLen);
Parameter
hObj
sDest
MaxLen
Description
Handle of multiedit widget.
Buffer for the text to be returned.
Maximum number of bytes to be copied to sDest.
Additional information
The function copies the current text to the buffer given by sDest. The maximum
number of bytes copied to the buffer is given by MaxLen.
MULTIEDIT_GetTextSize()
Description
Returns the buffer size used to store the current text (and prompt).
Prototype
int MULTIEDIT_GetTextSize(MULTIEDIT_HANDLE hObj);
Parameter
hObj
Description
Handle of multiedit widget.
Return value
Buffer size used to store the current text (and prompt).
MULTIEDIT_GetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_GetUserData().
MULTIEDIT_SetAutoScrollH()
Description
Enables/disables the automatic use of a horizontal scrollbar.
Prototype
void MULTIEDIT_SetAutoScrollH(MULTIEDIT_HANDLE hObj, int OnOff);
Parameter
hObj
OnOff
Description
Handle of multiedit widget.
(See table below)
Permitted values for parameter OnOff
0
1
Disables automatic use of a horizontal scrollbar.
Enables automatic use of a horizontal scrollbar.
Additional information
Enabling the use of a automatic horizontal scrollbar makes only sense with the non
wrapping mode explained later in this chapter. If enabled the multiedit widget checks
if the width of the non wrapped text fits into the client area. If not a horizontal scrollbar will be attached to the window.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
580
CHAPTER
Window Objects (Widgets)
MULTIEDIT_SetAutoScrollV()
Description
Enables/disables the automatic use of a vertical scrollbar.
Prototype
void MULTIEDIT_SetAutoScrollV(MULTIEDIT_HANDLE hObj, int OnOff);
Parameter
hObj
OnOff
Description
Handle of multiedit widget.
(See table below)
Permitted values for parameter OnOff
0
1
Disables automatic use of a vertical scrollbar.
Enables automatic use of a vertical scrollbar.
Additional information
If enabled the multiedit widget checks if the height of the text fits into the client
area. If not a vertical scrollbar will be attached to the window.
MULTIEDIT_SetBkColor()
Description
Sets the background color of the given multiedit widget.
Prototype
void MULTIEDIT_SetBkColor(MULTIEDIT_HANDLE hObj,
unsigned int Index,
GUI_COLOR
Color);
Parameter
hObj
Index
Color
Description
Handle of multiedit widget.
(See table below)
Background color to be used.
Permitted values for parameter Index
MULTIEDIT_CI_EDIT
MULTIEDIT_CI_READONLY
Edit mode.
Read only mode.
MULTIEDIT_SetBufferSize()
Description
Sets the maximum number of bytes used by text and prompt.
Prototype
void MULTIEDIT_SetBufferSize(MULTIEDIT_HANDLE hObj, int BufferSize);
Parameter
hObj
BufferSize
Description
Handle of multiedit widget.
Maximum number of bytes.
Additional information
The function clears the current contents of the multiedit widget and allocates the
given number of bytes for the text and for the prompt.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
581
MULTIEDIT_SetCursorOffset()
Description
Sets the cursor position to the given character.
Prototype
void MULTIEDIT_SetCursorOffset(MULTIEDIT_HANDLE hObj, int Offset);
Parameter
hObj
Offset
Description
Handle of multiedit widget.
New cursor position.
Additional information
The number of characters used for the prompt has to be added to the parameter Offset. If a prompt is used the value for parameter Offset should not be smaller than the
number of characters used for the prompt.
MULTIEDIT_SetFont()
Description
Sets the font used to display the text and the prompt.
Prototype
void MULTIEDIT_SetFont(MULTIEDIT_HANDLE hObj, const GUI_FONT * pFont);
Parameter
hObj
pFont
Description
Handle of multiedit widget.
Pointer to font to be used.
MULTIEDIT_SetInsertMode()
Description
Enables/disables the insert mode. The default behaviour is overwrite mode.
Prototype
void MULTIEDIT_SetInsertMode(MULTIEDIT_HANDLE hObj, int OnOff);
Parameter
hObj
OnOff
Description
Handle of multiedit widget.
(See table below)
Permitted values for parameter OnOff
0
1
Disables insert mode.
Enables insert mode.
MULTIEDIT_SetMaxNumChars()
Description
Sets the maximum number of characters used by text and prompt.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
582
CHAPTER
Window Objects (Widgets)
Prototype
void MULTIEDIT_SetMaxNumChars(MULTIEDIT_HANDLE hObj, unsigned MaxNumChars);
Parameter
hObj
MaxNumChars
Description
Handle of multiedit widget.
Maximum number of characters.
MULTIEDIT_SetPasswordMode()
Description
Enables/disables the password mode.
Prototype
void MULTIEDIT_SetPasswordMode(MULTIEDIT_HANDLE hObj, int OnOff);
Parameter
hObj
OnOff
Description
Handle of multiedit widget.
(See table below)
Permitted values for parameter OnOff
0
1
Disables password mode.
Enables password mode.
Additional information
The password mode enables you to conceal the user input.
MULTIEDIT_SetPrompt()
Description
Sets the prompt text.
Prototype
void MULTIEDIT_SetPrompt(MULTIEDIT_HANDLE hObj, const char * sPrompt);
Parameter
hObj
sPrompt
Description
Handle of multiedit widget.
Pointer to the new prompt text.
Additional information
The prompt text is displayed first. The cursor can not be moved into the prompt.
MULTIEDIT_SetReadOnly()
Description
Enables/disables the read only mode.
Prototype
void MULTIEDIT_SetReadOnly(MULTIEDIT_HANDLE hObj, int OnOff);
Parameter
hObj
OnOff
Description
Handle of multiedit widget.
(see table below)
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
583
Permitted values for parameter OnOff
Disables read only mode.
0
1
Enables read only mode.
Additional information
If the read only mode has been set the widget does not change the text. Only the
cursor will be moved.
MULTIEDIT_SetText()
Description
Sets the text to be handled by the widget.
Prototype
void MULTIEDIT_SetText(MULTIEDIT_HANDLE hObj, const char * s);
Parameter
hObj
s
Description
Handle of multiedit widget.
Pointer to the text to be handled by the multiedit widget.
Additional information
The function copies the given text to the buffer allocated when creating the widget or
by
MULTIEDIT_SetMaxSize().
The
current
text
can
be
retrieved
by
MULTIEDIT_GetText().
MULTIEDIT_SetTextAlign()
Description
Sets the text alignment for the given MULTIEDIT widget.
Prototype
void MULTIEDIT_SetTextAlign(MULTIEDIT_HANDLE hObj, int Align);
Parameter
hObj
Align
Description
Handle of multiedit widget.
(see table below)
Permitted values for parameter Align
GUI_TA_LEFT
GUI_TA_RIGHT
Left text align.
Right text align.
MULTIEDIT_SetTextColor()
Description
Sets the text color.
Prototype
void MULTIEDIT_SetTextColor(MULTIEDIT_HANDLE hObj,
unsigned int Index,
GUI_COLOR
Color);
Parameter
hObj
Index
Color
Description
Handle of multiedit widget.
(See table below)
Text color to be used.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
584
CHAPTER
Window Objects (Widgets)
Permitted values for parameter Index
MULTIEDIT_CI_EDIT
MULTIEDIT_CI_READONLY
Edit mode.
Read only mode.
MULTIEDIT_SetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_SetUserData().
MULTIEDIT_SetWrapWord()
Description
Enables the word wrapping mode.
Prototype
void MULTIEDIT_SetWrapWord(MULTIEDIT_HANDLE hObj);
Parameter
hObj
Description
Handle of multiedit widget.
Additional information
If the word wrapping mode has been set the text at the end of a line will be wrapped
at the beginning of the last word (if possible).
MULTIEDIT_SetWrapNone()
Description
Enables the non wrapping mode.
Prototype
void MULTIEDIT_SetWrapNone(MULTIEDIT_HANDLE hObj);
Parameter
hObj
Description
Handle of multiedit widget.
Additional information
’Non wrapping’ means line wrapping would be done only at new lines. If the horizontal size of the text exceeds the size of the client area the text will be scrolled.
17.17.5 Example
The Sample folder contains the following example which shows how the widget can be
used:
•
WIDGET_MultiEdit.c
Note that several other examples also make use of this widget and may also be helpful to get familiar with it.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
585
Screenshot of WIDGET_Multiedit.c:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
586
CHAPTER
Window Objects (Widgets)
17.18 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:
Description
MULTIPAGE widget
MULTIPAGE widget with 3 pages,
alignment top/left.
MULTIPAGE widget with 6 pages,
alignment bottom/right.
Structure of MULTIPAGE widget
A MULTIPAGE widget with n pages consists of n+2 windows:
•
1 MULTIPAGE window
•
1 Client window
•
n Page windows
The page windows will be added to the
client window of the widget. The diagram
at the right side shows the structure of
the widget.
User's & reference manual for emWin V5.10
MULTIPAGE window
Client window
Page window 1
...
Page window n
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
587
17.18.1 Configuration options
Type
Macro
Default
Description
N
MULTIPAGE_ALIGN_DEFAULT
MULTIPAGE_ALIGN_LEFT
Default alignment.
| MULTIPAGE_ALIGN_TOP
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.
17.18.2 Notification codes
The following events are sent from the widget to its parent window as part of a
WM_NOTIFY_PARENT message:
Message
Description
WM_NOTIFICATION_CLICKED
WM_NOTIFICATION_RELEASED
Widget has been clicked.
Widget has been released.
WM_NOTIFICATION_MOVED_OUT
Widget has been clicked and pointer has been moved out
off of the widget without releasing.
WM_NOTIFICATION_VALUE_CHANGED
The text of the widget has been changed.
17.18.3 Keyboard reaction
The widget reacts to the following keys if it has the input focus:
Key
Reaction
Switches to the next page.
GUI_KEY_PGUP
GUI_KEY_PGDOWN
Switches to the previous page.
17.18.4 MULTIPAGE API
The table below lists the available emWin MULTIPAGE-related routines in alphabetical
order. Detailed descriptions of the routines follow.
Routine
MULTIPAGE_AddPage()
MULTIPAGE_CreateEx()
Description
Adds a page to a MULTIPAGE widget.
Creates a MULTIPAGE widget.
MULTIPAGE_CreateIndirect()
Creates a MULTIPAGE widget from a resource table
entry.
MULTIPAGE_CreateUser()
Creates a MULTIPAGE widget using extra bytes as user
data.
MULTIPAGE_DeletePage()
MULTIPAGE_DisablePage()
MULTIPAGE_EnablePage()
MULTIPAGE_GetDefaultAlign()
Deletes a page from a MULTIPAGE widget.
Disables a page from a MULTIPAGE widget.
Enables a page from a MULTIPAGE widget.
Returns the default alignment for MULTIPAGE widgets.
MULTIPAGE_GetDefaultBkColor()
Returns the default background color for MULTIPAGE
widgets.
MULTIPAGE_GetDefaultFont()
Returns the default font used for MULTIPAGE widgets.
MULTIPAGE_GetDefaultTextColor()
Returns the default text color used for MULTIPAGE widgets.
MULTIPAGE_GetSelection()
Returns the current selection.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
588
CHAPTER
Window Objects (Widgets)
Routine
MULTIPAGE_GetUserData()
MULTIPAGE_GetWindow()
MULTIPAGE_IsPageEnabled()
MULTIPAGE_SelectPage()
MULTIPAGE_SetAlign()
MULTIPAGE_SetBkColor()
Description
Retrieves the data set with MULTIPAGE_SetUserData().
Returns the window handle of a given page.
Returns if a given page is enabled or not.
Selects the given page.
Sets the alignment for the tabs.
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()
MULTIPAGE_SetRotation()
MULTIPAGE_SetText()
MULTIPAGE_SetTextColor()
MULTIPAGE_SetUserData()
Selects the font for the widget.
Sets the rotation mode for the widget.
Sets the text displayed in a tab of a MULTIPAGE widget.
Sets the text color.
Sets the extra data of a MULTIPAGE widget.
MULTIPAGE_AddPage()
Before
After
Description
Adds a new page to a given MULTIPAGE widget.
Prototype
void MULTIPAGE_AddPage(MULTIPAGE_Handle
hObj,
WM_HWIN hWin ,
const char
* pText);
Parameter
hObj
hWin
pText
Description
Handle of MULTIPAGE widget.
Handle of window to be shown in the given page.
Pointer to text to be displayed in the tab of the page.
Additional information
It is recommended, that all windows added to a MULTIPAGE widget handle the complete client area of the MULTIPAGE widget when processing the WM_PAINT message.
MULTIPAGE_CreateEx()
Description
Creates a MULTIPAGE widget of a specified size at a specified position.
Prototype
MULTIPAGE_Handle MULTIPAGE_CreateEx(int
int
User's & reference manual for emWin V5.10
x0,
xsize,
int y0,
int ysize,
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
589
WM_HWIN hParent, int WinFlags,
int
ExFlags, int Id);
Parameter
x0
y0
xsize
ysize
Description
X-position of the widget (in parent coordinates).
Y-position of the widget (in parent coordinates).
Horizontal size of the widget (in pixels).
Vertical size of the widget (in pixels).
hParent
Handle of parent window. If 0, the new widget will be a child of the desktop
(top-level window).
WinFlags
Window create flags. Typically WM_CF_SHOW in order to make the widget visible
immediately (refer to “WM_CreateWindow()” on page 309 for a list of available
parameter values).
ExFlags
Id
Not used yet, reserved for future use.
Window ID of the widget.
Return value
Handle of the new widget.
Additional information
The size of the tabs depends on the size of the font used for the MULTIPAGE widget.
MULTIPAGE_CreateIndirect()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateIndirect().
MULTIPAGE_CreateUser()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateUser(). For
a detailed description of the parameters the function MULTIPAGE_CreateEx() can be
referred to.
MULTIPAGE_DeletePage()
Before
After
Description
Removes a page from a MULTIPAGE widget and optional deletes the window.
Prototype
void MULTIPAGE_DeletePage(MULTIPAGE_Handle hObj,
unsigned Index,
int
Delete);
Parameter
hObj
Index
Delete
Description
Handle of MULTIPAGE widget.
Zero based index of the page to be removed from the MULTIPAGE widget.
If >0 the window attached to the page will be deleted.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
590
CHAPTER
Window Objects (Widgets)
MULTIPAGE_DisablePage()
Before
After
Description
Disables a page from a MULTIPAGE widget.
Prototype
void MULTIPAGE_DisablePage(MULTIPAGE_Handle hObj, unsigned Index);
Parameter
hObj
Index
Description
Handle of MULTIPAGE widget.
Zero based index of the page to be disabled.
Additional information
A disabled page of a window can not be selected by clicking the tab of the page. The
default state of MULTIEDIT pages is ’enabled’.
MULTIPAGE_EnablePage()
Before
After
Description
Enables a page of a MULTIPAGE widget.
Prototype
void MULTIPAGE_EnablePage(MULTIPAGE_Handle hObj, unsigned Index);
Parameter
hObj
Description
Handle of MULTIPAGE widget.
Additional information
The default state of MULTIEDIT pages is ’enabled’.
MULTIPAGE_GetDefaultAlign()
Description
Returns the default tab alignment for new MULTIPAGE widgets.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
591
Prototype
unsigned MULTIPAGE_GetDefaultAlign(void);
Return value
Default tab alignment for new MULTIPAGE widgets.
Additional information
The following table shows the alignment values returned by this function:
Appearance of MULTIPAGE
widget
Alignment
MULTIPAGE_ALIGN_LEFT | MULTIPAGE_ALIGN_TOP
MULTIPAGE_ALIGN_RIGHT | MULTIPAGE_ALIGN_TOP
MULTIPAGE_ALIGN_LEFT | MULTIPAGE_ALIGN_BOTTOM
MULTIPAGE_ALIGN_RIGHT | MULTIPAGE_ALIGN_BOTTOM
MULTIPAGE_GetDefaultBkColor()
Description
Returns the default background color for new MULTIPAGE widgets.
Prototype
GUI_COLOR MULTIPAGE_GetDefaultBkColor(unsigned Index);
Parameter
Index
Description
See table below.
Permitted values for parameter Index
0
1
Returns the default background color for pages in disabled state.
Returns the default background color for pages in enabled state.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
592
CHAPTER
Window Objects (Widgets)
Return value
Default background color for new MULTIPAGE widgets.
MULTIPAGE_GetDefaultFont()
Description
Returns a pointer to the font used to display the text in the tabs of new MULTIPAGE
widgets.
Prototype
const GUI_FONT * MULTIPAGE_GetDefaultFont(void);
Return value
Pointer to the font used to display the text in the tabs of new MULTIPAGE widgets.
MULTIPAGE_GetDefaultTextColor()
Description
Returns the default text color used to display the text in the tabs of new MULTIPAGE
widgets.
Prototype
GUI_COLOR MULTIPAGE_GetDefaultTextColor(unsigned Index);
Parameter
Index
Description
See table below.
Permitted values for parameter Index
0
1
Returns the default text color for pages in disabled state.
Returns the default text color for pages in enabled state.
Return value
Default text color used to display the text in the tabs of new MULTIPAGE widgets.
MULTIPAGE_GetSelection()
Description
Returns the zero based index of the currently selected page of a MULTIPAGE widget.
Prototype
int MULTIPAGE_GetSelection(MULTIPAGE_Handle hObj);
Parameter
hObj
Description
Handle of MULTIPAGE widget.
Return value
Zero based index of the currently selected page of a MULTIPAGE widget.
MULTIPAGE_GetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_GetUserData().
MULTIPAGE_GetWindow()
Description
Returns the handle of the window displayed in the given page.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
593
Prototype
WM_HWIN MULTIPAGE_GetWindow(MULTIPAGE_Handle hObj, unsigned Index);
Parameter
hObj
Index
Description
Handle of MULTIPAGE widget.
Zero based index of page.
Return value
Handle of the window displayed in the given page.
MULTIPAGE_IsPageEnabled()
Description
Returns if the given page of a MULTIEDIT widget is enabled or not.
Prototype
int MULTIPAGE_IsPageEnabled (MULTIPAGE_Handle hObj, unsigned Index);
Parameter
hObj
Index
Description
Handle of MULTIPAGE widget.
Zero based index of requested page.
Return value
1 if the given page is enabled, otherwise 0.
MULTIPAGE_SelectPage()
Before
After
Description
Sets the currently selected page of a MULTIPAGE widget.
Prototype
void MULTIPAGE_SelectPage(MULTIPAGE_Handle hObj, unsigned Index);
Parameter
hObj
Index
Description
Handle of MULTIPAGE widget.
Zero based index of page to be selected.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
594
CHAPTER
Window Objects (Widgets)
MULTIPAGE_SetAlign()
Before
After
Description
Sets the tab alignment for the given MULTIPAGE widget.
Prototype
void MULTIPAGE_SetAlign(MULTIPAGE_Handle hObj, unsigned Align);
Parameter
hObj
Align
Description
Handle of MULTIPAGE widget.
See table below.
Permitted values for parameter Index
(horizontal and vertical flags are OR-combinable)
MULTIPAGE_ALIGN_BOTTOM
MULTIPAGE_ALIGN_LEFT
MULTIPAGE_ALIGN_RIGHT
MULTIPAGE_ALIGN_TOP
Aligns the tabs at the right side.
Aligns the tabs at the left side.
Aligns the tabs at the top of the widget.
Aligns the tabs at the bottom of the widget.
Additional information
For more information, refer to “MULTIPAGE_GetDefaultAlign()” on page 590.
MULTIPAGE_SetBkColor()
Before
After
Description
Sets the background color of the given MULTIPAGE widget.
Prototype
void MULTIPAGE_SetBkColor(MULTIPAGE_Handle hObj,
GUI_COLOR Color,
unsigned
Index);
Parameter
hObj
Color
Index
Description
Handle of MULTIPAGE widget.
Color to be used.
See table below.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
595
Permitted values for parameter Index
MULTIPAGE_CI_DISABLED Sets the default text color for disabled pages.
Sets the default text color for enabled pages.
MULTIPAGE_CI_ENABLED
Additional information
The function only sets the background color for the MULTIPAGE widget. The child windows added to the widget are not affected. That means if the complete client area is
drawn by windows added to the widget, only the background color of the tabs
changes.
MULTIPAGE_SetDefaultAlign()
Description
Sets the default tab alignment for new MULTIPAGE widgets.
Prototype
void MULTIPAGE_SetDefaultAlign(unsigned Align);
Parameter
Align
Description
Tab alignment used for new MULTIPAGE widgets.
Additional information
For
more
informations
“MULTIPAGE_GetDefaultAlign()”
page 594.
about
the
on page 590
tab
alignment,
refer
and “MULTIPAGE_SetAlign()”
to
on
MULTIPAGE_SetDefaultBkColor()
Description
Sets the default background color used for new MULTIPAGE widgets.
Prototype
void MULTIPAGE_SetDefaultBkColor(GUI_COLOR Color, unsigned Index);
Parameter
Color
Index
Description
Color to be used.
See table below.
Permitted values for parameter Index
0
1
Sets the default background color for pages in disabled state.
Sets the default background color for pages in enabled state.
MULTIPAGE_SetDefaultFont()
Description
Sets the default font used to display the text in the tabs of new MULTIPAGE widgets.
Prototype
void MULTIPAGE_SetDefaultFont(const GUI_FONT * pFont);
Parameter
pFont
Description
Pointer to GUI_FONT structure to be used.
Additional information
The horizontal and vertical size of the tabs depends on the size of the used font.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
596
CHAPTER
Window Objects (Widgets)
MULTIPAGE_SetDefaultTextColor()
Description
Sets the default text color used to display the text in the tabs of new MULTIPAGE widgets.
Prototype
void MULTIPAGE_SetDefaultTextColor(GUI_COLOR Color, unsigned Index);
Parameter
Color
Index
Description
Color to be used.
See table below.
MULTIPAGE_SetFont()
Before
After
Description
Sets the font used to display the text in the tabs of a given MULTIPAGE widget.
Prototype
void MULTIPAGE_SetFont(MULTIPAGE_Handle hObj, const GUI_FONT * pFont);
Parameter
hObj
pFont
Description
Handle of MULTIPAGE widget.
Pointer to GUI_FONT structure used to display the text in the tabs.
Additional information
The vertical and horizontal size of the tabs depend on the size of the used font and
the text shown in the tabs.
MULTIPAGE_SetRotation()
Before
After
Description
Sets the rotation mode of the given widget.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
597
Prototype
void MULTIPAGE_SetRotation(MULTIPAGE_Handle hObj, unsigned Rotation);
Parameter
hObj
Rotation
Description
Handle of MULTIPAGE widget.
Rotation mode (see table below)
Permitted values for parameter Index
MULTIPAGE_CF_ROTATE_CW
Arranges the tabs at the vertical side and
rotates the tab text by 90 degrees clockwise.
0
Default horizontal mode.
MULTIPAGE_SetText()
Before
After
Description
Sets the text displayed in the tab of a given page.
Prototype
void MULTIPAGE_SetText(MULTIPAGE_Handle hObj,
const char * pText,
unsigned
Index);
Parameter
hObj
pText
Index
Description
Handle of MULTIPAGE widget.
Pointer to the text to be displayed.
Zero based index of the page.
MULTIPAGE_SetTextColor()
Before
After
Description
Sets the color used to display the text in the tabs of a MULTIPAGE widget.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
598
CHAPTER
Window Objects (Widgets)
Prototype
void MULTIPAGE_SetTextColor(MULTIPAGE_Handle hObj,
GUI_COLOR Color,
unsigned
Index);
Parameter
hObj
Color
Index
Description
Handle of MULTIPAGE widget.
Color to be used.
See table below.
Permitted values for parameter Index
0
1
Sets the text color for pages in disabled state.
Sets the text color for pages in enabled state.
MULTIPAGE_SetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_SetUserData().
17.18.5 Example
The Sample folder contains the following example which shows how the widget can be
used:
•
WIDGET_Multipage.c
Note that several other examples also make use of this widget and may also be helpful to get familiar with the widget.
Screenshot of WIDGET_Multipage.c:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
599
17.19 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. Example 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.
Skinning...
...is available for this widget. The screenshot above shows the widget using the
default skin. For details please refer to chapter ’Skinning’.
17.19.1 Configuration options
Type
S
N
N
N
N
Macro
Default
PROGBAR_DEFAULT_FONT
PROGBAR_DEFAULT_BARCOLOR0
PROGBAR_DEFAULT_BARCOLOR1
PROGBAR_DEFAULT_TEXTCOLOR0
PROGBAR_DEFAULT_TEXTCOLOR1
Description
GUI_DEFAULT_FONT
Font used.
0x555555 (dark gray) Left bar color.
0xAAAAAA (light gray) Right bar color.
0xFFFFFF
Text color, left bar.
0x000000
Text color, right bar.
17.19.2 Keyboard reaction
The widget can not gain the input focus and does not react on keyboard input.
17.19.3 PROGBAR API
The table below lists the available emWin PROGBAR-related routines in alphabetical
order. Detailed descriptions of the routines follow.
Routine
PROGBAR_Create()
PROGBAR_CreateAsChild()
PROGBAR_CreateEx()
PROGBAR_CreateIndirect()
PROGBAR_CreateUser()
PROGBAR_GetUserData()
PROGBAR_SetBarColor()
PROGBAR_SetFont()
PROGBAR_SetMinMax()
PROGBAR_SetText()
PROGBAR_SetTextAlign()
PROGBAR_SetTextColor()
PROGBAR_SetTextPos()
PROGBAR_SetUserData()
PROGBAR_SetValue()
Description
Creates a PROGBAR widget. (Obsolete)
Creates a PROGBAR widget as a child window. (Obsolete)
Creates a PROGBAR widget.
Creates a PROGBAR widget from resource table entry.
Creates a PROGBAR widget using extra bytes as user data.
Retrieves the data set with PROGBAR_SetUserData().
Sets the color(s) for the bar.
Select the font for the text.
Set the minimum and maximum values used for the bar.
Set the (optional) text for the bar graph.
Set text alignment (default is centered).
Set the color(s) for the text.
Set the text position (default 0,0).
Sets the extra data of a PROGBAR widget.
Set the value for the bar graph (and percentage if no text has been
assigned).
PROGBAR_Create()
(Obsolete, PROGBAR_CreateEx() should be used instead)
Description
Creates a PROGBAR widget of a specified size at a specified location.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
600
CHAPTER
Window Objects (Widgets)
Prototype
PROGBAR_Handle PROGBAR_Create(int x0,
int y0,
int xsize, int ysize, int Flags);
Parameter
x0
y0
xsize
ysize
Description
Leftmost pixel of the progress bar (in parent coordinates).
Topmost pixel of the progress bar (in parent coordinates).
Horizontal size of the progress bar (in pixels).
Vertical size of the progress bar (in pixels).
Window create flags. Typically
Flags
WM_CF_SHOW in order to make the widget visible
immediately (refer to WM_CreateWindow() in the chapter “The Window Manager
(WM)” on page 289 for a list of available parameter values).
Return value
Handle of the created PROGBAR widget; 0 if the function fails.
PROGBAR_CreateAsChild()
(Obsolete, PROGBAR_CreateEx should be used instead)
Description
Creates a PROGBAR widget as a child window.
Prototype
PROGBAR_Handle PROGBAR_CreateAsChild(int
int
WM_HWIN
int
Parameter
x0
y0
xsize
ysize
hParent
Id
Flags
x0,
int y0,
xsize,
int ysize,
hParent, int Id,
Flags);
Description
X-position of the progress bar relative to the parent window.
Y-position of the progress bar relative to the parent window.
Horizontal size of the progress bar (in pixels).
Vertical size of the progress bar (in pixels).
Handle of parent window.
ID to be returned.
Window create flags (see
PROGBAR_Create() ).
Return value
Handle of the created PROGBAR widget; 0 if the function fails.
PROGBAR_CreateEx()
Description
Creates a PROGBAR widget of a specified size at a specified location.
Prototype
PROGBAR_Handle PROGBAR_CreateEx(int
int
WM_HWIN
int
Parameter
x0
y0
xsize
x0,
xsize,
hParent,
ExFlags,
int
int
int
int
y0,
ysize,
WinFlags,
Id);
Description
Leftmost pixel of the widget (in parent coordinates).
Topmost pixel of the widget (in parent coordinates).
Horizontal size of the widget (in pixels).
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
601
Parameter
Description
ysize
Vertical size of the widget (in pixels).
hParent
Handle of parent window. If 0, the new PROGBAR widget will be a child of the desktop (top-level window).
Window create flags. Typically
WM_CF_SHOW in order to make the widget visible
WinFlags
immediately (refer to WM_CreateWindow() in the chapter “The Window Manager
(WM)” on page 289 for a list of available parameter values).
ExFlags
Id
(see table below)
Window ID of the widget.
Permitted values for parameter ExFlags
A vertical progress bar will be created.
PROGBAR_CF_VERTICAL
PROGBAR_CF_HORIZONTAL A horizontal progress bar will be created.
Return value
Handle of the created PROGBAR widget; 0 if the function fails.
PROGBAR_CreateIndirect()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateIndirect().
The elements Flags and Para of the resource passed as parameter are not used.
PROGBAR_CreateUser()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateUser(). For
a detailed description of the parameters the function PROGBAR_CreateEx() can be
referred to.
PROGBAR_GetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_GetUserData().
PROGBAR_SetBarColor()
Description
Sets the color(s) of the progress bar.
Prototype
void PROGBAR_SetBarColor(PROGBAR_Handle hObj,
unsigned int Index,
GUI_COLOR
Color);
Parameter
hObj
Index
Color
Description
Handle of progress bar.
See table below. Other values are not permitted.
Color to set (24-bit RGB value).
Permitted values for parameter Index
0
1
Left portion of the progress bar.
Right portion of the progress bar.
PROGBAR_SetFont()
Description
Selects the font for the text display inside the progress bar.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
602
CHAPTER
Window Objects (Widgets)
Prototype
void PROGBAR_SetFont(PROGBAR_Handle hObj, const GUI_FONT* pFont);
Parameter
hObj
pFont
Description
Handle of progress bar.
Pointer to the font.
Additional information
If this function is not called, the default font for progress bars (the GUI default font)
will be used. However, the progress bar default font may be changed in the
GUIConf.h file.
Simply #define the default font as follows (example):
#define PROGBAR_DEFAULT_FONT &GUI_Font13_ASCII
PROGBAR_SetMinMax()
Description
Sets the minimum and maximum values used for the progress bar.
Prototype
void PROGBAR_SetMinMax(PROGBAR_Handle hObj, int Min, int Max);
Parameter
Description
hObj
Handle of progress bar.
Min
Minimum value
Range: -16383 < Min <= 16383.
Max
Maximum value
Range: -16383 < Max <= 16383.
Additional information
If this function is not called, the default values of Min = 0, Max = 100 will be used.
PROGBAR_SetText()
Description
Sets the text displayed inside the progress bar.
Prototype
void PROGBAR_SetText(PROGBAR_Handle hObj, const char* s);
Parameter
Description
hObj
Handle of progress bar.
s
Text to display. A NULL pointer is permitted; in this case a percentage value will be
displayed.
Additional information
If this function is not called, a percentage value will be displayed as the default. If
you do not want to display any text at all, you should set an empty string.
PROGBAR_SetTextAlign()
Description
Sets the text alignment.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
603
Prototype
void PROGBAR_SetTextAlign(PROGBAR_Handle hObj, int Align);
Parameter
hObj
Align
Description
Handle of progress bar.
Horizontal alignment attribute for the text (see table below).
Permitted values for parameter Align
GUI_TA_HCENTER Centers the title (default).
Displays the title to the left.
GUI_TA_LEFT
Displays the title to the right.
GUI_TA_RIGHT
Additional information
If this function is not called, the default behavior is to display the text centered.
PROGBAR_SetTextColor()
Description
Sets the text color of the progress bar.
Prototype
void PROGBAR_SetTextColor(PROGBAR_Handle hObj,
unsigned int Index,
GUI_COLOR
Color);
Parameter
hObj
Index
Color
Description
Handle of progress bar.
See table below. Other values are not permitted.
Color to set (24-bit RGB value).
Permitted values for parameter Index
0
1
Left portion of the text.
Right portion of the text.
PROGBAR_SetTextPos()
Description
Sets the text position in pixels.
Prototype
void PROGBAR_SetTextPos(PROGBAR_Handle hObj, int XOff, int YOff);
Parameter
Description
hObj
Handle of progress bar.
XOff
Number of pixels to move text in horizontal direction.
Positive number will move text to the right.
YOff
Number of pixels to move text in vertical direction.
Positive number will move text down.
Additional information
The values move the text the specified number of pixels within the widget. Normally,
the default of (0,0) should be sufficient.
PROGBAR_SetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_SetUserData().
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
604
CHAPTER
Window Objects (Widgets)
PROGBAR_SetValue()
Description
Sets the value of the progress bar.
Prototype
void PROGBAR_SetValue(PROGBAR_Handle hObj, int v);
Parameter
hObj
v
Description
Handle of progress bar.
Value to set.
Additional information
The bar indicator will be calculated with regard to the max/min values. If a percentage is automatically displayed, the percentage will also be calculated using the given
min/max values as follows:
p = 100% * (v-Min)/(Max-Min)
The default value after creation of the widget is 0.
17.19.4 Examples
The Sample folder contains the following examples which show how the widget can be
used:
•
WIDGET_SimpleProgbar.c
•
WIDGET_Progbar.c
Note that several other examples also make use of this widget and may also be helpful to get familiar with the widget.
Screenshot of WIDGET_SimpleProgbar.c:
Screenshot of WIDGET_Progbar.c:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
605
17.20 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. The table below shows the default appearances of
a RADIO button:
Selected
Unselected
Enabled
Disabled
Skinning...
...is available for this widget. The screenshot above shows the widget using the
default skin. For details please refer to chapter ’Skinning’.
17.20.1 Configuration options
Type
Macro
Default
Description
S
RADIO_IMAGE0_DEFAULT
(see table above)
Default outer image used to show a disabled radio button.
S
RADIO_IMAGE1_DEFAULT
(see table above)
Default outer image used to show a
enabled radio button.
S
Default inner image used to mark the
RADIO_IMAGE_CHECK_DEFAULT (see table above) 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.
17.20.2 Notification codes
The following events are sent from a radio button widget to its parent window as part
of a WM_NOTIFY_PARENT message:
Message
WM_NOTIFICATION_CLICKED
WM_NOTIFICATION_RELEASED
Description
Radio button has been clicked.
Radio button has been released.
WM_NOTIFICATION_MOVED_OUT
Radio button has been clicked and pointer has been moved
out off of the button without releasing.
WM_NOTIFICATION_VALUE_CHANGED
Value (selection) of the radio button widget has changed.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
606
CHAPTER
Window Objects (Widgets)
17.20.3 Keyboard reaction
The widget reacts to the following keys if it has the input focus:
Key
GUI_KEY_RIGHT
GUI_KEY_DOWN
GUI_KEY_LEFT
GUI_KEY_UP
Reaction
Increments the selection by 1.
Increments the selection by 1.
Decrements the selection by 1.
Decrements the selection by 1.
17.20.4 RADIO API
The table below lists the available emWin RADIO-related routines in alphabetical
order. Detailed descriptions of the routines follow.
Routine
RADIO_Create()
RADIO_CreateEx()
RADIO_CreateIndirect()
RADIO_CreateUser()
RADIO_Dec()
Description
Creates a RADIO widget. (Obsolete)
Creates a RADIO widget.
Creates a RADIO widget from resource table entry.
Creates a RADIO widget using extra bytes as user data.
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()
RADIO_GetUserData()
RADIO_GetValue()
RADIO_Inc()
RADIO_SetBkColor()
RADIO_SetDefaultFocusColor()
Returns the text of a radio button item.
Retrieves the data set with RADIO_SetUserData().
Return the current button selection.
Increment the button selection by a value of 1.
Sets the background color of the radio button.
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()
RADIO_SetFont()
RADIO_SetGroupId()
RADIO_SetImage()
RADIO_SetText()
RADIO_SetTextColor()
RADIO_SetUserData()
RADIO_SetValue()
Sets the color of the focus rectangle.
Sets the font used to show the text of the radio button.
Sets the group Id of the given radio widget.
Sets the images used to display the radio button.
Sets the text
Sets the text color used to show the text of radio button.
Sets the extra data of a RADIO widget.
Set the button selection.
RADIO_Create()
(Obsolete, RADIO_CreateEx() should be used instead)
Description
Creates a RADIO widget of a specified size at a specified location.
Prototype
RADIO_Handle RADIO_Create(int
int
WM_HWIN
int
User's & reference manual for emWin V5.10
x0,
xsize,
hParent,
Flags,
int
int
int
unsigned
y0,
ysize,
Id,
Para);
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
607
Parameter
x0
y0
xsize
ysize
hParent
Id
Description
Leftmost pixel of the radio button widget (in parent coordinates).
Topmost pixel of the radio button widget (in parent coordinates).
Horizontal size of the radio button widget (in pixels).
Vertical size of the radio button widget (in pixels).
Handle of parent window.
ID to be returned.
Window create flags. Typically
WM_CF_SHOW in order to make the widget visible
Flags
immediately (refer to WM_CreateWindow() in the chapter “The Window Manager
(WM)” on page 289 for a list of available parameter values).
Para
Number of buttons in the group.
Return value
Handle of the created RADIO widget; 0 if the function fails.
RADIO_CreateEx()
Description
Creates a RADIO widget of a specified size at a specified location.
Prototype
RADIO_Handle RADIO_CreateEx(int
int
WM_HWIN
int
int
x0,
xsize,
hParent,
ExFlags,
NumItems,
Parameter
x0
y0
xsize
ysize
int
int
int
int
int
y0,
ysize,
WinFlags,
Id,
Spacing);
Description
Leftmost pixel of the widget (in parent coordinates).
Topmost pixel of the widget (in parent coordinates).
Horizontal size of the widget (in pixels).
Vertical size of the widget (in pixels).
hParent
Handle of parent window. If 0, the new RADIO widget will be a child of the desktop
(top-level window).
WinFlags
Window create flags. Typically WM_CF_SHOW in order to make the widget visible
immediately (refer to WM_CreateWindow() in the chapter “The Window Manager
(WM)” on page 289 for a list of available parameter values).
ExFlags
Id
NumItems
Spacing
Not used, reserved for future use.
Window ID of the widget.
Number of items of the radio widget. (default is 2)
Number of vertical pixels used for each item of the radio widget.
Return value
Handle of the created RADIO widget; 0 if the function fails.
Additional information
If creating a radio widget make sure, that the given ysize is enough to show all
items. The value should be at least NumItems * Spacing. If the given value of
NumItems is <= 0 a default value of 2 is used.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
608
CHAPTER
Window Objects (Widgets)
RADIO_CreateIndirect()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateIndirect().
The element Flags of the resource passed as parameter is not used. The following
table shows the use of the resource element Para:
Bits
0
8
16
24
- 7
- 15
- 23
- 31
Description
Number of items of the radio widget. If 0, a default value of 2 items is used.
Number of vertical pixels used for each item. If 0 the height of the default image is used.
Not used, reserved for future use.
Not used, reserved for future use.
RADIO_CreateUser()
Prototype explained at the beginning of the chapter as <WIDGET>_CreateUser(). For
a detailed description of the parameters the function RADIO_CreateEx() can be
referred to.
RADIO_Dec()
Before
After
Description
Decrements the selection by a value of 1.
Prototype
void RADIO_Dec(RADIO_Handle hObj);
Parameter
hObj
Description
Handle of radio button widget.
Additional information
Note that the numbering of the buttons always starts from the top with a value of 0;
therefore, decrementing the selection will actually move the selection one button up.
RADIO_GetDefaultFont()
Description
Returns the default font used to display the optional text next to new radio buttons.
Prototype
const GUI_FONT * RADIO_GetDefaultFont(void);
Return value
Default font used to display the optional text next to the radio buttons.
Additional information
For information about how to add text to a radio widget, refer to “RADIO_SetText()”
on page 614.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
609
RADIO_GetDefaultTextColor()
Description
Returns the default text color used to display the optional text next to new radio buttons.
Prototype
GUI_COLOR RADIO_GetDefaultTextColor (void);
Return value
Default text color used to display the optional text next to new radio buttons.
Additional information
For information about how to add text to a radio widget, refer to “RADIO_SetText()”
on page 614.
RADIO_GetText()
Description
Returns the optional text of the given radio button.
Prototype
int RADIO_GetText(RADIO_Handle
hObj,
unsigned Index,
char
* pBuffer, int
MaxLen);
Parameter
hObj
Index
pBuffer
MaxLen
Description
Handle of widget.
Index of the desired item.
Pointer to buffer to which the text will be copied.
Buffer size in bytes.
Return value
Length of the text copied into the buffer.
Additional information
If the desired item of the radio button contains no text the function returns 0 and the
buffer remains unchanged.
RADIO_GetUserData()
Prototype explained at the beginning of the chapter as <WIDGET>_GetUserData().
RADIO_GetValue()
Description
Returns the current button selection.
Prototype
void RADIO_GetValue(RADIO_Handle hObj);
Parameter
hObj
Description
Handle of radio button widget.
Return value
The value of the currently selected button. If no button is selected (in case of using a
radio button group) the return value is -1.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
610
CHAPTER
Window Objects (Widgets)
Additional information
For information about how to use
“RADIO_SetGroupID()” on page 613.
groups
of
radio
buttons,
refer
to
RADIO_Inc()
Before
After
Description
Increments the selection by a value of 1.
Prototype
void RADIO_Inc(RADIO_Handle hObj);
Parameter
hObj
Description
Handle of radio button widget.
Additional information
Note that the numbering of the buttons always starts from the top with a value of 0;
therefore, incrementing the selection will actually move the selection one button
down.
RADIO_SetBkColor()
Before
After
Description
Sets the background color of the radio widget.
Prototype
void RADIO_SetBkColor(RADIO_Handle hObj, GUI_COLOR Color);
Parameter
Description
hObj
Handle of radio button widget.
Color
Color to be used for the background.
(range 0x000000 and 0xFFFFFF or a valid color define)
GUI_INVALID_COLOR to make background transparent
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
611
Additional information
The background of this widget can either be filled with any available color or transparent. If a valid RGB color is specified, the background is filled with the color, otherwise the background (typically the contents of the parent window) is visible. If the
background is transparent, the widget is treated as transparent window, otherwise as
non-transparent window. Note that using a background color allows more efficient
(faster) rendering.
RADIO_SetDefaultFocusColor()
Description
Sets the default focus rectangle color for new radio buttons.
Prototype
GUI_COLOR RADIO_SetDefaultFocusColor(GUI_COLOR Color);
Parameter
Color
Description
Default color to be used for new radio buttons.
Return value
Previous default focus rectangle color.
Additional information
For more information, refer to “RADIO_SetFocusColor()” on page 612.
RADIO_SetDefaultFont()
Description
Sets the default font used to display the optional text next to new radio buttons.
Prototype
void RADIO_SetDefaultFont(const GUI_FONT * pFont);
Parameter
pFont
Description
Pointer to GUI_FONT structure used to show the text of new radio widgets.
Additional information
For information about how to add text to a radio widget, refer to “RADIO_SetText()”
on page 614.
RADIO_SetDefaultImage()
Description
Sets the images used to draw new radio buttons.
Prototype
void RADIO_SetDefaultImage(const GUI_BITMAP * pBitmap, unsigned int Index);
Parameter
pBitmap
Index
Description
Pointer to the bitmap.
(see table below)
Permitted values for parameter Index
RADIO_BI_INACTIV
RADIO_BI_ACTIV
RADIO_BI_CHECK
User's & reference manual for emWin V5.10
Outer image used to show a disabled radio button.
Outer image used to show a enabled radio button.
Inner image used to mark the selected item.
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
612
CHAPTER
Window Objects (Widgets)
Additional information
Two images are used to display a radio button. One image is used to draw the outer
frame used to display a unselected radio button. In dependence of the current state
it will be the bitmap referenced by RADIO_BI_ACTIV (default) or by RADIO_BI_ACTIV.
The second image (referenced by RADIO_BI_CHECK) is used to mark the currently
selected button.
RADIO_SetDefaultTextColor()
Description
Sets the default text color used to display the optional text next to new radio buttons.
Prototype
void RADIO_SetDefaultTextColor(GUI_COLOR TextColor);
Parameter
TextColor
Description
New color to be used.
Additional information
For information about how to add text to a radio widget, refer to “RADIO_SetText()”
on page 614.
RADIO_SetFocusColor()
Before
After
Description
Sets the color used to render the focus rectangle of the radio button.
Prototype
GUI_COLOR RADIO_SetFocusColor(RADIO_Handle hObj, GUI_COLOR Color);
Parameter
hObj
Color
Description
Handle of widget.
Color to be used for the focus rectangle.
Return value
Previous color of the focus rectangle.
Additional information
The focus rectangle is only visible if the widget has the input focus.
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
613
RADIO_SetFont()
Before
After
Description
Sets the font used to display the optional text next to the radio button.
Prototype
void RADIO_SetFont(RADIO_Handle hObj, const GUI_FONT * pFont);
Parameter
hObj
pFont
Description
Handle of radio button widget.
Pointer to GUI_FONT structure to be used to display the text.
Additional information
For information about how to add text to a radio widget, refer to “RADIO_SetText()”
on page 614.
RADIO_SetGroupID()
Before
After
Description
Sets the group ID of the radio widget.
Prototype
void RADIO_SetGroupID(RADIO_Handle hObj, U8 GroupID);
Parameter
Description
hObj
Handle of radio button widget.
GroupID
ID of the radio button group. Must be between 1 and 255. If the value is 0 the radio
widget is not assigned to a radio button group.
Additional information
This command can be used to create groups of radio buttons. The behavior of one
group is the same as the behavior of one radio button. This makes it possible to create for example 2 RADIO widgets side by side with 3 buttons each and build one
group of them.
Example
The following example shows how to create a group of 2 RADIO widgets as shown in
the screenshot at the beginning of the function description:
User's & reference manual for emWin V5.10
© 1997 - 2011 SEGGER Microcontroller GmbH & Co. KG
614
CHAPTER
Window Objects (Widgets)
hRadio_0 = RADIO_CreateEx(10, 10, 60, 0, WM_HBKWIN, WM_CF_SHOW, 0, 1234, 3, 20);
RADIO_SetText(hRadio_0, "Red", 0);
RADIO_SetText(hRadio_0, "Green", 1);
RADIO_SetText(hRadio_0, "Blue", 2);
hRadio_1 = RADIO_CreateEx(65, 10, 60, 0, WM_HBKWIN, WM_CF_SHOW, 0, 1234, 3, 20);
RADIO_SetText(hRadio_1, "Magenta", 0);
RADIO_SetText(hRadio_1, "Cyan", 1);
RADIO_SetText(hRadio_1, "Yellow", 2);
RADIO_SetGroupID(hRadio_0, 1);
RADIO_SetGroupID(hRadio_1, 1);
RADIO_SetImage()
Description
Sets the images used to draw the radio button.
Prototype
void RADIO_SetImage(RADIO_Handle hObj,
const GUI_BITMAP * pBitmap,
unsigned int Index);
Parameter
hObj
pBitmap
Index
Description
Handle of radio button widget.
Pointer to the bitmap.
(see table shown under
RADIO_SetDefaultImage )
Additional information
(see RADIO_SetDefaultImage).
RADIO_SetText()
Before
After
Description
Sets the optional text shown next to the radio buttons.
Prototype
void RADIO_SetText(RADIO_Handle hObj, const char * pText, unsigned Index);
Parameter
hObj
pText
Index
Description
Handle of radio button widget.
Pointer to the text to be shown next to the specified radio button.
Zero based index of the radio button.
Additional information
If using a RADIO widget without text (old style) the focus rectangle is drawn around
the buttons of the widget. If using radio button text the focus rectangle is shown
around