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