首页资源分类嵌入式系统 > ucUGLV4.04(in)手册.pdf

ucUGLV4.04(in)手册.pdf

已有 452958个资源

下载专区

上传者其他资源

嵌入式系统热门资源

本周本月全部

文档信息举报收藏

标    签: ucUGLV4 04

分    享:

文档简介

ucUGLV4.04原版英文手册,很详细的!值得收藏。

文档预览

Graphical User Interface with Graphic Library Version 4.04 Manual Rev. 0 Micriµm www.micrium.com Empowering Embedded Systems 2 Disclaimer Specifications written in this manual are believed to be accurate, but are not guaranteed to be entirely free of error. Specifications in this manual may be changed 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, Micrium Technologies Corporation (the distributor) assumes no responsibility for any errors or omissions and makes no warranties. The distributor specifically disclaims any implied warranty of fitness for a particular purpose. Copyright notice The latest version of this manual is available as PDF file in the download area of our website at www.micrium.com. You are welcome to copy and distribute the file as well as the printed version. You may not extract portions of this manual or modify the PDF file in any way without the prior written permission of Micrium Technologie Corporation. 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. © 2002-2006 Micrium, Weston, Florida 33327-1848, U.S.A. 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 please provide the following information: • Your full name and the name of your supervisor • Your company name • Your job title • Your email address and telephone number • Company name and address • Your company's main phone number • Your company's web site address • Name and version of the product Please send this information to: licensing@micrium.com Contact address Micrium Technologies Corporation 949 Crestview Circle Weston, FL 33327-1848 U.S.A. Phone : +1 954 217 2036 FAX : +1 954 217 2037 WEB : www.micrium.com Email : support@micrium.com User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 3 Manual versions This manual describes the latest software version. The software version number can be found in the table ’Software versions’ later in this chapter. If any error occurs, please inform us and we will try to help you as soon as possible. For further information on topics or routines not yet specified, please contact us. Print date: August 24, 2006 Manual version 4.04R0 4.02R0 4.01R0 4.00R0 Date By Explanation 060505 JE 060502 JE 060131 JE 051222 JE Chapter 15: Widgets - Function added to set the rotation mode of a MULTIPAGE widget. Chapter 7: 2-D graphic library - Filling polygons: New config option GUI_FP_MAXCOUNT added. Chapter 8: Displaying bitmap files - BMP subchapter: Support for 32bpp BMP files added. - JPEG subchapter: Adapted to the new decoder. Chapter 9: Fonts - New functions for getting the number of blank pixel columns added. Chapter 10: Bitmap converter - Support for 24bpp and RLE16 format added. Chapter 11: Colors - Fixed palette modes for 24bpp and 32bpp added. - Fixed palette modes for alpha blending added. Chapter 15: Widgets - Support for widget schemes added. - GRAPH: Invalid data can be excluded from drawing YT graphs. - LISTVIEW: Function added to fix one or more columns. - DROPDOWN: Notification WM_NOTIFICATION_SEL_CHANGED added. - MULTIEDIT: New function added to set the text alignment. Chapter 18: Multi layer support - Support for up to 6 layers/displays added. Chapter 24: Display drivers - Support for Sitronix ST7712 added to LCD66772.c - New driver added to support Epson S1D13700 in 2bpp mode. - New driver added to support RAIO 8822 in 2bpp mode. - New driver added to support Sitronix ST7529. - New driver added to support Sitronix ST7920. Chapter 9: Fonts - New functions for using external bitmap fonts added. Chapter 8: Displaying bitmap files - New functions added for drawing GIFs and BMPs without loading them into memory. - New functions added for drawing scaled GIFs and BMPs with and without loading them into memory. - New functions added for getting information about GIFs and BMPs without loading them into memory. Chapter 9: Fonts: - New type of font added. Chapter 15: Widgets - Keyboard support added to MULTIPAGE widget. Chapter 16: Dialogs - Keyboard can be used to move to the previous dialog item. Chapter 23: Foreign language support - Subchapter Arabic support revised. - New subchapter for Thai language support. Chapter 29: Performance and resource usage - Table for image drawing performance added. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 4 Manual version 3.98R0 3.96R0 Date By Explanation 051109 JE 050719 JE Chapter 5: Displaying text - New function for showing text with text wrapping support added. Chapter 8: Displaying bitmap files - New functions for drawing animated GIFs added. - New functions for drawing scaled JPEGs added. - New functions added to draw JPEGs without loading them into memory. - Memory requirement of JPEG decompression changed. Chapter 9: Fonts - Subchapter standard font revised. Chapter 12: Memory devices - New function added. Chapter 14: Window manager - New message WM_MOUSEOVER_END added to messages. Chapter 15: Widgets - EDIT: Functions added to get the cursor position and to edit unsigned long values, notification messages added. - FRAMEWIN: Config option added. - GRAPH: Prototype of GRAPH_DATA_XY_SetPenSize() changed. - HEADER: Function for limitiing dragging within the widget area added. - LISTVIEW: Sorting functions added, automatic use of scroll bars added, managing user data added, keyboard support enhanced, new config option added. - MENU: Popup menu added. - MESSAGEBOX: Config option added. - MULTIEDIT: Functions added to get the cursor position. - SCROLLBAR: Config options added. - TEXT: Text wrapping functions added. - Common: Mouse support of widgets explained, config option added. Chapter 21: Cursors - Function added. Chapter 24: Display drivers - LCDSLin: Support for RAIO 8822/8803/8835 added. - LCD667XX: Support for Sharp LR38825 and Samsung S6D0117 added. - LCDPage1bpp: Support for UltraChip UC1601 added. Chapter 7: 2-D Graphic Library - New function GUI_GetDrawMode() added. Chapter 8: Displaying bitmap files - Mentioned, that JPEG package is only part of color version. Chapter 9: Fonts - Antialiased SIF fonts added. Chapter 12: Memory devices - New function GUI_MEMDEV_WriteEx() added. - New function GUI_MEMDEV_WriteExAt() added. Chapter 14: Window manager - New function WM_GetCallback() added. Chapter 15: Widgets - Interface of SCROLLBAR_SetColor() changed. - Explanation added, how to determine the type of a widget. - New GRAPH widget added. - New function BUTTON_GetBitmap() added. - New function CHECKBOX_GetText() added. - New function DROPDOWN_SetColor() added. - New function DROPDOWN_SetDefaultColor() added. - New function DROPDOWN_SetDefaultScrollbarColor() added. - New function DROPDOWN_SetScrollbarColor() added. - New function LISTBOX_SetScrollbarColor() added. - New function RADIO_GetText() added. Chapter 24: Display drivers - LCD667XX driver: Support for Samsung S6D0110A added. - LCD07X1 driver: Support for Sitronix ST7541 added. - LCD66750 driver: Support for Hitachi HD66753 added. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 5 Manual version 3.95R0 3.94R0 Date By Explanation 050701 JE 050329 JE Chapter 23 (Unicode) and 24 (Shift JIS) merged to chapter 23 (Foreign Language Support). Chapter 23: - Arabic support added. New chapter 3: Viewer - Virtual screen support added. Chapter 7: 2-D Graphic Library - New function GUI_SetClipRect() added. Chapter 8: Displaying bitmap files - GIF file support added. Chapter 10: Bitmap converter - GIF file support added. Chapter 11: Colors - Mentioned that custom palettes only available for modes up to 8bpp. Chapter 12: Memory devices - Reworked and support for 1bpp memory devices added. Chapter 14: Window manager - API function classification basic/advanced removed. - New function WM_SetWindowPos() added. - New function WM_GetScrollPosH() added. - New function WM_GetScrollPosV() added. - New function WM_SetScrollPosH() added. - New function WM_SetScrollPosV() added. Chapter 15: Widgets - BUTTON: New function BUTTON_SetDefaultFocusColor. - BUTTON: New function BUTTON_SetFocusColor. - BUTTON: New config option BUTTON_FOCUSCOLOR_DEFAULT. - CHECKBOX: New function CHECKBOX_SetBoxBkColor(). - CHECKBOX: New function CHECKBOX_SetDefaultFocusColor(). - CHECKBOX: New function CHECKBOX_SetFocusColor(). - CHECKBOX: Notification WM_NOTIFICATION_VALUE_CHANGED added. - CHECKBOX: Image of ’unchecked’ state can now be set. - EDIT: New function EDIT_SetTextMode() added. - LISTBOX: New function LISTBOX_GetDefaultTextAlign() added. - LISTBOX: New function LISTBOX_GetTextAlign() added. - LISTBOX: New function LISTBOX_SetDefaultTextAlign() added. - LISTBOX: New function LISTBOX_SetTextAlign() added. - LISTBOX: New color index LISTBOX_CI_DISABLED added. - LISTVIEW: New color index LISTVIEW_CI_DISABLED added. - MENU: Keyboard support added. - PROGBAR: Vertical progress bar supported. - RADIO: New function RADIO_SetDefaultFocusColor() added. - RADIO: New function RADIO_SetFocusColor() added. - RADIO: Config options reworked. - SCROLLBAR: New function SCROLLBAR_SetColor() added. - SCROLLBAR: New function SCROLLBAR_SetDefaultColor() added. - SLIDER: New function SLIDER_SetDefaultFocusColor() added. - SLIDER: New function SLIDER_SetFocusColor() added. - Keyboard support explained for each widget. - Widget callback functions added. Chapter 22: Antialiasing - New function GUI_AA_DrawPolyOutlineEx() added. - Limitation of GUI_AA_DrawPolyOutline() explained. Chapter 23: Unicode - New function GUI_UC_ConvertUC2UTF8() added. - New function GUI_UC_ConvertUTF82UC() added. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 6 Manual version 3.92R0 3.90R0 Date By Explanation 041021 JE 040818 JE Chapter 25: Display drivers - New driver LCD0323 for Solomon SSD0323 controller added. - New driver LCD1200 for Toppoly C0C0 and C0E0 controller added. - New driver LCD13701 for Epson S1D13701 controller added. - New driver LCDNoritake for Noritake displays added. - New driver LCD667XX for Hitachi HD66772, HD66766 controller added. - New driver LCDXylon added. - LCDLin driver: New config macro LCD_FILL_RECT added. - LCDLin driver: New config macro LCD_LIN_SWAP added. - LCDLin driver: 32 bit version now supports 1 and 2 bpp color depth. Chapter 28: Low level config - LCD_REVERSE_LUT added. Chapter 3: Simulator and Viewer - Subchapter added: Using the source code of the simulator. Chapter 9: Bitmap converter - Saving of bitmaps reworked. Chapter 13: Window manager - New functions added: WM_PaintWindowAndDescs(), WM_Update() and WM_UpdateWindowAndDescs(). Chapter 14: Widgets - Flag GUI_MESSAGEBOX_CF_MODAL added for creating a modal message box. - Notification codes added to MULTIPAGE widget. - New functions added: LISTVIEW_DisableRow(), LISTVIEW_EnableRow() and LISTVIEW_GetItemText(). New Chapter 16: Virtual screens - New functions GUI_GetOrg() and GUI_SetOrg(). Chapter 24: Display driver - Support for Sitronix ST7565 added to Page1bpp driver. - LCDLin driver (8/16 bit): LCD_SET_LUT_ENTRY added. - LCDLin driver (32 bit): Explanation added how to migrate from LCDLin to LCDLin32. Chapter 27: High-Level Configuration - GUI_TRIAL_VERSION added. Chapter 6: 2-D Graphic library - GUI_DrawBitmapEx() does not render RLE-compressed bitmaps. Chapter 13: Window manager - Explanation added, which messages are not send to disabled windows. - New function WM_GetPrevSibling() added. - New message WM_MOUSEOVER added. - New create flag WM_CF_MEMDEV_ON_REDRAW added. - WM_MOVE message: Explanation reworked. Chapter 14: Widgets - MENU widget added. - WM_NOTIFICATION_SCROLL_CHANGED added to DROPDOWN, LISTBOX, LISTVIEW and MULTIEDIT - BUTTON widget: Support for disabled state added. - New functions added: DROPDOWN_SetTextHeight(), DROPDOWN_SetTextAlign(), FRAMEWIN_AddMenu(), FRAMEWIN_SetResizeable(), LISTVIEW_GetBkColor(), LISTVIEW_GetTextColor(), LISTVIEW_SetItemTextColor(), LISTVIEW_SetItemBkColor() Chapter 17: Pointer Input Devices - Explanation of structure GUI_PID_STATE changed. Chapter 23: Display driver - Support for Solomon SSD1815 added to Page1bpp driver Chapter 26: Low-Level Configuration - ’Real bus interface’ renamed to ’Memory mapped interface’ Chapter 29: Support - Warnings added to subchapter ’compiler warnings’. - Subchapter ’Contacting support’ added.’ User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 7 Manual version 3.82R0 Date By Explanation 040714 JE Chapter 1: Introduction: - ANSI standard described more detailed. Chapter 6: 2-D Graphic Library - Default limitation for drawing bitmaps with 16 bit CPUs added. Chapter 8: Fonts - Fonts added: GUI_FontD48, GUI_FontD64, GUI_FontD80, GUI_FontD37x48, GUI_FontD48x64, GUI_FontD61x80 Chapter 11: Memory devices - Supchapter ’Memory requirements’ and ’Performance’ added. Chapter 13: Window manager - Functions added: WM_IsCompletelyVisible(), WM_IsEnabled() - Message added: WM_NOTIFY_VIS_CHANGED - Config macro added: WM_SUPPORT_NOTIFY_VIS_CHANGED Chapter 14: Widgets - WM_... functions moved to Chapter 13 - Functions added: BUTTON_GetDefaultTextAlign(), BUTTON_GetDefaultBkColor(), BUTTON_GetDefaultFont(), BUTTON_GetDefaultTextColor(), BUTTON_SetDefaultTextAlign(), BUTTON_SetDefaultBkColor(), BUTTON_SetDefaultFont(), BUTTON_SetDefaultTextColor(), CHECKBOX_GetDefaultBkColor(), CHECKBOX_GetDefaultFont(), CHECKBOX_GetDefaultSpacing(), CHECKBOX_GetDefaultTextAlign(), CHECKBOX_GetDefaultTextColor(), CHECKBOX_GetState(), CHECKBOX_SetBkColor(), CHECKBOX_SetDefaultBkColor(), CHECKBOX_SetDefaultFont(), CHECKBOX_SetDefaultSpacing(), CHECKBOX_SetDefaultTextAlign(), CHECKBOX_SetDefaultTextColor(), CHECKBOX_SetFont(), CHECKBOX_SetNumStates(), CHECKBOX_SetSpacing(), CHECKBOX_SetState(), CHECKBOX_SetText(), CHECKBOX_SetTextAlign(), CHECKBOX_SetTextColor(), LISTBOX_GetDefaultBkColor(), LISTBOX_GetDefaultTextColor(), LISTBOX_SetDefaultBkColor(), LISTBOX_SetDefaultTextColor() - Config macros added: BUTTON_ALIGN_DEFAULT, BUTTON_REACT_ON_LEVEL, CHECKBOX_BKCOLOR_DEFAULT, CHECKBOX_FONT_DEFAULT, CHECKBOX_IMAGE0_DEFAULT, CHECKBOX_IMAGE1_DEFAULT, CHECKBOX_SPACING_DEFAULT, CHECKBOX_TEXTALIGN_DEFAULT, CHECKBOX_TEXTCOLOR_DEFAULT Chapter 15: Dialogs - Explanation of ’blocking’ and ’non blocking’ improoved. Chapter 23: Display drivers - LCDLin and LCDLin32 merged to one driver. - Support for S1D13A03, S1D13A04, S1D13A05 and S1D15710 added. Chapter 27: High level configuration - GUI_MAXBLOCKS and GUI_SUPPORT_LARGE_BITMAPS added. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 8 Manual version 3.80R0 3.76R0 Date By Explanation 040503 JE 040123 JE Chapter 3: Simulator & Viewer - SIM_SetMag added. Chapter 13: Window manager - Sample added to WM_PID_STATE_CHANGED message. - WM_SET_FOCUS added - Config subchapter added (WM_SUPPORT_TRANSPARENCY) - WM_SetTransState() added. Chapter 14: Widgets - New functions added: EDIT_GetNumChars(), EDIT_SetSel(), EDIT_SetpfAddKeyEx(), EDIT_SetInsertMode(), EDIT_SetFloatValue(), RADIO_GetDefaultFont(), RADIO_GetDefaultTextColor(), RADIO_SetBkColor(), RADIO_SetDefaultFont(), RADIO_SetDefaultTextColor(), RADIO_SetFont(), RADIO_SetGroupID(), RADIO_SetText(), RADIO_SetTextColor(), SLIDER_SetNumTicks(). - Explanation added how to use snapping with the slider widget. - Information added to CHECKBOX_CreateEx(). - Description of RADIO_CreateEx() reworked. Chapter 23: Display drivers: - New driver LCDPage4bpp added (support for Sitronix ST7528) - New driver LCD1781 added (support for Solomon SSD1781). - Support for Epson S1D13700 added to LCDSlin driver. - Support for Novatec NT7502, Samsung S6B1713 and Philips PCD8544 added to LCDPage1bpp. - Explanation how to use hardware for display orientation added to LCD07X1 and LCDPage1bpp. Chapter 28: LCD driver API - Chapter moved as subchapter to chapter 23. Chapter 12: Execution model - GUI_X_WAIT_EVENT and GUI_X_SIGNAL_EVENT added Chapter 13: Window manager - Message WM_INIT_DIALOG added. Chapter 14: Widgets - Notification codes added to SLIDER and SCROLLBAR - New functions added: EDIT_SetDefaultTextColor(), EDIT_SetDefaultBkColor(), EDIT_GetDefaultTextColor(), EDIT_GetDefaultBkColor(), EDIT_GetDefaultTextAlign(), DROPDOWN_SetScrollbarWidth() and LISTBOX_SetScrollbarWidth(). - WINDOW widget added. - MESSAGEBOX widget added. - MULTIPAGE widget added. - Creation flag DROPDOWN_CF_UP added. - Effect functions added. Chapter 17: Pointer input devices - From an interrupt routine callable functions denoted. Chapter 18: Keyboard input - From an interrupt routine callable functions denoted. Chapter 27: High level configuraton - Limitation for 16 bit CPU’s removed. Chapter 29: Performance and resource usage - Memory requirements reworked. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 9 Manual version 3.74R0 3.72R0 Date By Explanation 031219 JE 031204 JE Chapter 10: Colors: - New predefined color table (colors added) Chapter 11: Memory devices: - New function GUI_MEMDEV_CreateFixed() added. Chapter 13: Window manager: - Message WM_GET_ID added. - Explanation of window invalidation added. - Creation flags added: WM_CF_ANCHOR_LEFT, WM_CF_ANCHOR_TOP, WM_CF_ANCHOR_RIGHT and WM_CF_ANCHOR_BOTTOM. Chapter 14: Widgets: - Screenshots added to overview and FRAMEWIN widget. - FRAMEWIN_CreateButton-functions renamed to FRAMEWIN_AddButton... - TEXT_SetBkColor() and RADIO_SetBkColor() added. Chapter 17: Pointer input devices: - Explanation of runtime calibration added Chapter 26: Low-Level configuration: - Renamed to ’Low-Level configuration (LCDConf.h)’. Chapter 27: High-Level configuration: - Renamed to ’High-Level configuration (GUIConf.h)’. - Explanation of GUI_ALLOC_SIZE added. Chapter 2: Getting started: - Explanation added how to adapt the library batch files Chapter 4: Displaying text: - GUI_DispStringInRectEx added. Chapter 13: Window Manager: - Message documentation reworked. - Functions WM_SetID and WM_ForEachDesc added. - Explanation added how to react on a WM_PAINT message. Chapter 8: Fonts: - System independent font support added. - Standard fonts moved to this chapter. Chapter 14: Widget library: - BUTTON_SetTextAlign added. - DROPDOWN_SetItemSpacing added. - EDIT_GetFloatValue added. - EDIT_SetFloatMode added. - LISTBOX_SetItemSpacing added. - LISTVIEW_SetLBorder added. - LISTVIEW_SetRBorder added. - LISTVIEW_SetRowHeight added. - RADIO_SetBkColor added. - SLIDER_SetBkColor added. Chapter 17: Pointer input devices: - Devided into pointer input devices and keyboard input - Pointer input device documentation reworked Chapter 21: Unicode: - How to convert UTF-8 text to ’C’ strings added. Chapter 23: Display driver: - Support for UltraChip UC1611 and Hitachi HD66750 added. Chapter 30: Support: - Reworked and renamed to Support. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 10 Manual version 3.70R0 3.62R1 3.62R0 3.60R2 3.60R1 3.60R0 3.58R1 3.58R0 3.56R0 3.56R0 3.54R0 3.52R0 3.50R0 3.48R0 Date By Explanation 031010 JE 030916 JE 030901 JE 030718 RS 030716 JE 030714 RS 030710 RS 030701 JE 030626 JE 030626 JE 030603 JE 030516 JE 030515 JE 030415 JE Chapter 3: Viewer documentation improved. Chapter 10: Fixed palette modes and color index mask added. Chapter 22: Support for the following LCD controllers added: Fujitsu MB86290A (Cremson), Fujitsu MB86291 (Scarlet), Fujitsu MB86292 (Orchid), Fujitsu MB86293 (Coral Q), Fujitsu MB86294 (Coral B), Fujitsu MB86295 (Coral P), Samsung S6B33B1X and UltraChip UC1606. Chapter 22: Driver LCD180S1 renamed to LCD161620. Chapter 22: Hardware interface descriptions added. Chapter 16: Multi layer sample removed. Chapter 25: Configuration of SPI 3, SPI 4 and I2C bus interface added. Chapter 27: Keil 8051 compiler limitation added Chapter 23: Explanation of config options and GUI_VNC_X_StartServer changed. Chapter 13: Message data explained. Chapter 14: _CreateEx added, _Create and _CreateAsChild obsolete. Chapter 14: Interface from some functions changed from int to unsigned int. Chapter 14.4: Functions added: CHECKBOX_SetDefaultImage, CHECKBOX_SetImage Chapter 14.5: Functions added: DROPDOWN_Collapse, DROPROWN_DeleteItem, DROPDOWN_Expand, DROPDOWN_InsertString, DROPDOWN_SetAutoScroll Chapter 14.13: Functions added: RADIO_SetDefaultImage, RADIO_SetImage Chapter 23 added: VNC support. Chapter 24: SED1520-support added, new driver for Fujitsu MB87J2020 and MB87J2120 added. Chapter 14: Explanation of user draw function improved. Chapter 14.3: BUTTON_IsPressed() added Chapter 14: WIDGET_ITEM_GET_YSIZE added to structure WIDGET_ITEM_DRAW_INFO to enable items with different y sizes. Chapter 11: GUI_MEMDEV_GetDataPtr() added Chapter 13: WM_CF_CONST_OUTLINE added Chapter 24.4: Usage of display orientation macros explained. Chapter 22: LCD501 added. Chapter 22: LCD180S1 and LCD444 added. Chapter 22: LCD_CONTROLLER macro definition changed for several LCD controllers. Chapter 13: WM_MakeModal added. Chapter 25: AVR support added. Chapter 22: LCD180S1 and LCD444 added. Chapter 22: LCD_CONTROLLER macro definition changed for several LCD controllers. Chapter 13: WM_MakeModal added. Chapter 25: AVR support added. New chapter 7, "Displaying bitmap files" added. Chapter 12: WM_GetFocussedWindow added Chapter 13: LISTVIEW_DeleteRow and LISTVIEW_DeleteColumn added, LISTVIEW_GetNumColums renamed to LISTVIEW_GetNumColumns Chapter 4: GUI_SetTextStyle added. Chapter 6: GUI_SetLineStyle, GUI_GetLineStyle added. Chapter 12: WM_BroadcastMessage added. Chapter 13: MULTIEDIT_SetPasswordMode and MULTIEDIT_GetTextSize added. Chapter 12: WM_SetStayOnTop and WM_GetStayOnTop added. Chapter 13.7: FRAMEWIN_SetBorderSize added. Chapter 13.11: MULTIEDIT_SetMaxNumChars added. Chapter 14: Multi layer support revised. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 11 Manual version 3.46R0 3.44R0 3.42R1 3.42R0 3.40R0 3.38R0 3.36R0 3.34R2 3.34R1 3.34R0 3.32R0 3.30R1 3.30R0 3.28R1 3.28R0 3.26R0 3.24R4 Date By Explanation 030404 JE 030319 JE 030303 JE 030227 JE 030217 JE 030206 JE 030121 JE 021212 JE 021127 JE 020926 KG 020920 KG 020919 KG 020912 KG 020910 KG 020905 KG 020903 KG RS 020830 KG 020827 KG 020823 KG 020820 KG 020809 KG New chapter Multi layer support added. Colors: 86661 mode added. Chapter 18: Revised, UTF-8 support added. Chapter 13.9: LISTBOX_GetFont, LISTBOX_GetItemText, LISTBOX_GetMulti and LISTBOX_SetOwnerDraw added.w Chapter 13: New chapter 13.11 for MULTIEDIT widget added. Chapter 6: GUI_SaveContext and GUI_RestoreContext added. Chapter 12: WM_GetInvalidRect and WM_HasFocus added. Chapter 13.7: FRAMEWIN_SetTextColorEx, FRAMEWIN_Get-DefaultTextColor and FRAMEWIN_SetDefaultTextColor added. Chapter 13.9: LISTBOX_GetItemDisabled, LISTBOX_GetScrollStepH, LISTBOX_SetItemDisabled, LIST-BOX_SetItemSel, LISTBOX_SetScrollStepH, LISTBOX_Get-DefaultScrollStepH and LISTBOX_SetDefaultScrollStepH added. Chapter 13.15: TEXT_SetTextColor and TEXT_SetDefaultText-Color added. Chapter 3: Directory structure changed. Chapter 13: Functions added. Chapter 2: Color and gray scale conversion functions marked as optional. Chapter 13.3: Functions added. Chapter 13.9: Functions added. Chapter 13.13: Functions added. Chapter 12: Additional functions added. Chapter 13.7: Additional functions added. Chapter 23: Dynamic memory configuration added. Chapter 12: WM_GetClientRectEx and WM_GetWindowRectEx added. Chapter 13: WM_GetInsideRect and WM_GetInsideRectEx added. Chapter 4: Additional functions added. Chapter 6: Additional functions added. Chapter 10: Additional functions added. Chapter 12: Additional functions added. Chapter 13: Additional functions added. Additional functions added to section 13.5 (Edit widget). Additional function added to Chapter 12 (The Window Manager). BMP file support functions added to Chapter 6 (2-D Graphic Library). Chapter 13 (Window Objects): additional functions documented; message notification codes added. Chapter 12 (The Window Manager) restructured slightly; WM_NOTIFY_PARENT documented. Chapter 18 (Input Devices) moved to after Chapter 14 (Dialogs). Chapter 16 (Cursors) added. Additional function added to section 13.8 (Progress bar widget). Additional controller supported by LCD15XX in Chapter 19 (LCD Drivers). Additional function added to Chapter 18 (Input Devices). EDIT widget: Additional info on flags added. Additional functions added to Chapter 3 (Simulator). Starter kit "Berni" added to section 1.7 (Starter kits). Additional functions added to section 13.7 (List box widget). Headline-level format changes throughout. Modified trial version screen shots in Chapter 3 (Simulator). Chapter 18 (Touch-Screen Support) changed to Input Devices; mouse and keyboard support added; chapter restructured. Slight modifications to section 13.10 (Scroll bar widget). Additional macros added to Chapter 18 (Touch-Screen Support). Chapter 3 (Simulator) modified; addition of use of simulator with trial version of µC/GUI. Section 1.7 (Data types) revised. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 12 Manual version 3.24R3 3.24R2 3.24R1 3.24R0 3.22R1 3.22R0 3.20R0 3.14R3 3.14R2 3.14R1 Date By Explanation 020802 KG 020801 KG 020730 KG 020726 KG 020723 KG 020719 RS 020716 KG 020627 JE 020620 KG 020618 KG 020618 KG 020611 KG 020531 KG 020524 KG 020507 KG 020503 KG 020405 KG Additional macros added to sections 22.8 (LCDMem) and 22.9 (LCDMemC); same macros added to Chapter 20 (Low-Level Configuration). Section 2.3 (Creating a library) revised, table and diagram added. Minor changes throughout, including addition of () brackets to all API functions. Chapter 9 (Colors) revised; modes 1, 2, and 444 added. Chapter 11 (Execution Model: Single Task/Multitask) added. Chapter 1 (Introduction to µC/GUI) revised. Chapter 2 (Getting Started) revised. Chapter 18 (Time-Related Functions) changed to Timing and ExecutionRelated Functions; GUI_Exec() and GUI_Exec1() added. Small formatting changes throughout. Chapter 18 (µC/GUI in Multitasking Environments) merged with Chapter 22 (High-Level Configuration). Chapter 4 (Tutorial) merged with Chapter 2 (Getting Started). Chapter 10 (Colors) revised, color mode table added. GUI_X_ explanations added. Widget description enhanced, screen shots added. Chapter 13 (Window Objects) revised; SCROLLBAR and RADIO widgets added. Chapter 2 (Getting Started) revised. Chapter 14 (Dialogs) revised. Chapter 13 (Window Objects) revised; CHECKBOX, SLIDER and TEXT widgets added. Chapter 14 (Dialogs) added. Chapter 3 (Simulator) revised. Chapter 20 (Low-Level Configuration) revised. Chapter 22 (LCD Drivers) revised. Chapter 12 (The Window Manager) revised. Version control table added. Chapter 11 (Memory Devices) revised. Chapter 14 (Antialiasing) revised. Chapter 9 (Bitmap Converter) revised. Completely revised for language/grammar. Section 1.5 (Typographic conventions) updated. Chapter 8 changed to 7.6 (Font converter). Index revised. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 13 Software versions Software version 4.04 4.02 4.01 4.00 Date 060505 060502 060131 051222 By Explanation JE Widget library: - New function MULTIPAGE_SetRotation() added. Displaying bitmap files: - Support for 32bpp BMP files added. - New JPEG decoder added. Widget library: - Widget schemes added. - New functions added: LISTVIEW_SetFixed(), MULTIEDIT_SetTextAlign() Colors: _ Fixed palette modes added: 666, M666, 888, M888, 8888, JE M8888, 84444, 822216, -1 Bitmap converter: - New bitmap formats 888, M888, RLE16 and RLEM16 added. 2-D graphic library: - New functions GUI_GetTrailingBlankCols() and GUI_GetLeadingBlankCols() added. Multi layer support - Support for up to 6 layers/displays added. Display drivers: - New drivers added: LCD13700.c, LCD7529.c, LCD7920.c, LCD8822.c. Fonts: JE - New functions for using external bitmap fonts added: GUI_XBF_CreateFont(), GUI_XBF_DeleteFont() Displaying bitmap files: - Function GUI_GIF_DrawEx() renamed to GUI_GIF_DrawSub() - New functions added: GUI_BMP_GetYSizeEx(), GUI_BMP_DrawEx(), GUI_BMP_DrawScaled(), GUI_BMP_DrawScaledEx(), GUI_GIF_DrawEx(), GUI_GIF_DrawSubEx(), GUI_GIF_DrawSubScaled(), GUI_GIF_DrawSubScaledEx(), GUI_GIF_GetCommentEx(), GUI_GIF_GetImageInfoEx(), GUI_GIF_GetInfoEx(), GUI_GIF_GetXSizeEx(), GUI_GIF_GetYSizeEx() JE Widgets: - GUI_KEY_PGUP and GUI_KEY_PGDOWN now can be used to switch to the next / previous page of a MULTIPAGE widget. Dialogs: - GUI_KEY_BACKTAB now can be used to move the input focus to the previous dialog item. Foreign language support: - GUI_SUPPORT_ARABIC has been replaced by GUI_SUPPORT_BIDI Fonts: - New font type with extended character information added. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 14 Software version 3.98 Date 051109 By Explanation Displaying text - New function GUI_DispStringInRectWrap() added. Displaying bitmap files - New function GUI_GIF_DrawEx() added. - New function GUI_GIF_GetInfo() added. - New function GUI_JPEG_DrawEx() added. - New function GUI_JPEG_DrawScaled() added. - New function GUI_JPEG_DrawScaledEx() added. - New function GUI_JPEG_GetInfoEx() added. - Memory requirement of JPEG decompression changed. Memory devices - New function GUI_MEMDEV_MarkDirty() added. Window manager - New message WM_MOUSEOVER_END added. Widgets - New function EDIT_GetCursorCharPos() added. - New function EDIT_GetCursorPixelPos() added. - New function EDIT_SetUlongMode() added. - New function GRAPH_DATA_XY_SetLineStyle() added. - New function HEADER_SetDragLimit() added. - New function LISTVIEW_CompareDec() added. - New function LISTVIEW_CompareText() added. - New function LISTVIEW_DisableSort() added. - New function LISTVIEW_EnableSort() added. - New function LISTVIEW_GetSelUnsorted() added. - New function LISTVIEW_GetUserData() added. JE - New function LISTVIEW_InsertRow() added. - New function LISTVIEW_SetAutoScrollH() added. - New function LISTVIEW_SetAutoScrollV() added. - New function LISTVIEW_SetCompareFunc() added. - New function LISTVIEW_SetSelUnsorted() added. - New function LISTVIEW_SetSort() added. - New function LISTVIEW_SetUserData() added. - New function MENU_Popup() added. - New function MULTIEDIT_GetCursorPixelPos() added. - New function MULTIEDIT_GetCursorCharPos() added. - New function MULTIEDIT_AddText() added. - New function TEXT_SetWrapMode() added. - New function TEXT_SetDefaultWrapMode() added. - New config option LISTVIEW_SCROLLSTEP_H_DEFAULT added. - Keyboard support of LISTVIEW widget enhanced. - New config option WIDGET_USE_PARENT_EFFECT. - New config option GUI_MESSAGEBOX_CF_MOVEABLE. - New config option FRAMEWIN_ALLOW_DRAG_ON_FRAME. - Notification messages added to EDIT widget. - New config option SCROLLBAR_THUMB_SIZE_MIN_DEFAULT. Cursors - New function GUI_CURSOR_GetState() added. Display drivers - LCDSLin: Support for RAIO 8822/8803/8835 added. - LCD667XX: Support for Sharp LR38825 and Samsung S6D0117 added. - LCDPage1bpp: Support for UltraChip UC1601 added. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 15 Software version 3.96 Date 050719 By Explanation 2-D Graphic Library - New function GUI_GetDrawMode() added. Fonts - Antialiased SIF fonts added. Memory devices - New function GUI_MEMDEV_WriteEx() added. - New function GUI_MEMDEV_WriteExAt() added. Window manager - New function WM_GetCallback() added. Widgets - Interface of SCROLLBAR_SetColor() changed. - New GRAPH widget added. - New function BUTTON_GetBitmap() added. - New function CHECKBOX_GetText() added. - New function DROPDOWN_SetColor() added. - New function DROPDOWN_SetDefaultColor() added. - New function DROPDOWN_SetDefaultScrollbarColor() added. - New function DROPDOWN_SetScrollbarColor() added. - New function LISTBOX_SetScrollbarColor() added. - New function RADIO_GetText() added. Foreign languages - Arabic support added. Display drivers - LCD667XX driver: Support for Samsung S6D0110A added. - LCD07X1 driver: Support for Sitronix ST7541 added. - LCD66750 driver: Support for Hitachi HD66753 added. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 16 Software version 3.94 Date 050329 By Explanation Viewer - Virtual screen support added. 2-D Graphic Library - New function GUI_SetClipRect() added. Displaying bitmap files - GIF file support added. Bitmap converter - GIF file support added. Memory devices - Support for 1bpp memory devices added. Window manager - New function WM_SetWindowPos() added. - New function WM_GetScrollPosH() added. - New function WM_GetScrollPosV() added. - New function WM_SetScrollPosH() added. - New function WM_SetScrollPosV() added. Widgets - BUTTON: New function BUTTON_SetDefaultFocusColor(). - BUTTON: New function BUTTON_SetFocusColor(). - BUTTON: New config option BUTTON_FOCUSCOLOR_DEFAULT. - CHECKBOX: New function CHECKBOX_SetBoxBkColor(). - CHECKBOX: New function CHECKBOX_SetDefaultFocusColor(). - CHECKBOX: New function CHECKBOX_SetFocusColor(). - CHECKBOX: Notification WM_NOTIFICATION_VALUE_CHANGED added. JE - CHECKBOX: Image of ’unchecked’ state can now be set. - EDIT: New function EDIT_SetTextMode() added. - LISTBOX: New function LISTBOX_GetDefaultTextAlign() added. - LISTBOX: New function LISTBOX_GetTextAlign() added. - LISTBOX: New function LISTBOX_SetDefaultTextAlign() added. - LISTBOX: New function LISTBOX_SetTextAlign() added. - LISTBOX: New color index LISTBOX_CI_DISABLED added. - LISTVIEW: New color index LISTVIEW_CI_DISABLED added. - MENU: Keyboard support added. - PROGBAR: Vertical progress bar supported. - RADIO: New function RADIO_SetDefaultFocusColor() added. - RADIO: New function RADIO_SetFocusColor() added. - RADIO: Config options reworked. - SCROLLBAR: New function SCROLLBAR_SetColor() added. - SCROLLBAR: New function SCROLLBAR_SetDefaultColor() added. - SLIDER: New function SLIDER_SetDefaultFocusColor() added. - SLIDER: New function SLIDER_SetFocusColor() added. - Widget callback functions exported. Antialiasing - New function GUI_AA_DrawPolyOutlineEx() added. Unicode - New function GUI_UC_ConvertUC2UTF8() added. - New function GUI_UC_ConvertUTF82UC() added. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 17 Software version 3.92 3.90 Date 041021 040818 By Explanation Display drivers - New driver LCD0323 for Solomon SSD0323 controller added. - New driver LCD1200 for Toppoly C0C0 and C0E0 controller added. - New driver LCD13701 for Epson S1D13701 controller added. - New driver LCDNoritake for Noritake displays added. - New driver LCD667XX for Hitachi HD66772, HD66766 controller added. - New driver LCDXylon added. - LCDLin driver: New config macro LCD_FILL_RECT added. - LCDLin driver: New config macro LCD_LIN_SWAP added. - LCDLin driver: 32 bit version now supports 1 and 2 bpp color depth. Simulator and Viewer - The simulatior now can easily be used with other simulations. Window manager - New functions added: WM_PaintWindowAndDescs(), WM_Update() and WM_UpdateWindowAndDescs(). Widgets - Flag GUI_MESSAGEBOX_CF_MODAL added for creating a JE modal message box. - Notification codes added to MULTIPAGE widget. - New functions added: LISTVIEW_DisableRow(), LISTVIEW_EnableRow() and LISTVIEW_GetItemText(). Virtual screen support - New functions GUI_GetOrg() and GUI_SetOrg(). Display driver - Support for Sitronix ST7565 added to Page1bpp driver. - LCDLin driver (8/16 bit): LCD_SET_LUT_ENTRY added. Chapter 13: Window manager - New function WM_GetPrevSibling() added. - New message WM_MOUSEOVER added. - New create flag WM_CF_MEMDEV_ON_REDRAW added. Chapter 14: Widgets - MENU widget added. - WM_NOTIFICATION_SCROLL_CHANGED added to DROP- JE DOWN, LISTBOX, LISTVIEW and MULTIEDIT - BUTTON widget: Support for disabled state added. - New functions added: DROPDOWN_SetTextHeight(), DROPDOWN_SetTextAlign(), FRAMEWIN_AddMenu(), FRAMEWIN_SetResizeable(), LISTVIEW_GetBkColor(), LISTVIEW_GetTextColor(), LISTVIEW_SetItemTextColor(), LISTVIEW_SetItemBkColor() Chapter 23: Display driver - Support for Solomon SSD1815 added to Page1bpp driver User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 18 Software version 3.82 3.80 3.76 Date 040714 0040503 040123 By Explanation Chapter 13: Window manager - Functions added: WM_IsCompletelyVisible(), WM_IsEnabled() - Message added: WM_NOTIFY_VIS_CHANGED - Config macro added: WM_SUPPORT_NOTIFY_VIS_CHANGED Chapter 14: Widgets - Functions added: BUTTON_GetDefaultAlign(), BUTTON_GetDefaultBkColor(), BUTTON_GetDefaultFont(), BUTTON_GetDefaultTextColor(), BUTTON_SetDefaultAlign(), BUTTON_SetDefaultBkColor(), BUTTON_SetDefaultFont(), BUTTON_SetDefaultTextColor(), CHECKBOX_GetDefaultBkColor(), CHECKBOX_GetDefaultFont(), CHECKBOX_GetDefaultSpacing(), CHECKBOX_GetDefaultTextAlign(), CHECKBOX_GetDefaultTextColor(), CHECKBOX_GetState(), CHECKBOX_SetBkColor(), CHECKBOX_SetDefaultBkColor(), JE CHECKBOX_SetDefaultFont(), CHECKBOX_SetDefaultSpacing(), CHECKBOX_SetDefaultTextAlign(), CHECKBOX_SetDefaultTextColor(), CHECKBOX_SetFont(), CHECKBOX_SetNumStates(), CHECKBOX_SetSpacing(), CHECKBOX_SetState(), CHECKBOX_SetText(), CHECKBOX_SetTextAlign(), CHECKBOX_SetTextColor(), LISTBOX_GetDefaultBkColor(), LISTBOX_GetDefaultTextColor(), LISTBOX_SetDefaultBkColor(), LISTBOX_SetDefaultTextColor() - Config macros added: BUTTON_ALIGN_DEFAULT, BUTTON_REACT_ON_LEVEL, CHECKBOX_BKCOLOR_DEFAULT, CHECKBOX_FONT_DEFAULT, CHECKBOX_IMAGE0_DEFAULT, CHECKBOX_IMAGE1_DEFAULT, CHECKBOX_SPACING_DEFAULT, CHECKBOX_TEXTALIGN_DEFAULT, CHECKBOX_TEXTCOLOR_DEFAULT Chapter 23: Display drivers - Support for S1D13A03, S1D13A04 and S1D13A05 added. Simulator & Viewer - SIM_SetMag added. Widgets - New functions added: EDIT_GetNumChars(), EDIT_SetSel(), EDIT_SetpfAddKeyEx(), EDIT_SetInsertMode(), EDIT_SetFloatValue(), RADIO_GetDefaultFont(), RADIO_GetDefaultTextColor(), RADIO_SetBkColor(), JE RADIO_SetDefaultFont(), RADIO_SetDefaultTextColor(), RADIO_SetFont(), RADIO_SetGroupID(), RADIO_SetText(), RADIO_SetTextColor(), SLIDER_SetNumTicks(). Display drivers: - New driver LCDPage4bpp added (support for Sitronix ST7528) - New driver LCD1781 added (support for Solomon SSD1781). - Support for Novatec NT7502, Samsung S6B1713 and Philips PCD8544 added to LCDPage1bpp. Widgets - Notification codes added to SLIDER and SCROLLBAR - EDIT_SetDefaultTextColor() added. - EDIT_SetDefaultBkColor() added. - EDIT_GetDefaultTextColor() added. JE - EDIT_GetDefaultBkColor() added. - EDIT_GetDefaultTextAlign() added. - DROPDOWN_SetScrollbarWidth() added. - LISTBOX_SetScrollbarWidth() added. Memory allocation: - Limitation for 16 bit CPU’s removed. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 19 Software version 3.74 3.72 3.70 3.62 3.60 3.54 3.52 3.50 3.48 3.46 3.44 3.42 3.40 3.38 3.36 3.34 Date 031219 031204 031010 030901 030714 030603 030516 030509 030415 030404 030319 030227 030217 030206 030120 020926 By Explanation Colors: - GUI_MAGENTA changed from 0x8b008b to 0xFF00FF Memory devices: - New function GUI_MEMDEV_CreateFixed() added. JE Widgets: - FRAMEWIN_CreateButton-functions renamed to FRAMEWIN_AddButton... - New functions TEXT_SetBkColor() and RADIO_SetBkColor() added. Chapter 4: Displaying text: - GUI_DispStringInRectEx added. Chapter 13: Window Manager: - Functions WM_SetID and WM_ForEachDesc added. Chapter 8: Fonts: - System independent font support added. Chapter 14: Widget library: - BUTTON_SetTextAlign added. - DROPDOWN_SetItemSpacing added. JE - EDIT_GetFloatValue added. - EDIT_SetFloatMode added. - LISTBOX_SetItemSpacing added. - LISTVIEW_SetLBorder added. - LISTVIEW_SetRBorder added. - LISTVIEW_SetRowHeight added. - RADIO_SetBkColor added. - SLIDER_SetBkColor added. Chapter 23: Display driver: - Support for UltraChip UC1611 and Hitachi HD66750 added. Support for the following LCD controllers added: Fujitsu MB86290A (Cremson), Fujitsu MB86291 (Scarlet), Fujitsu JE MB86292 (Orchid), Fujitsu MB86293 (Coral Q), Fujitsu MB86294 (Coral B), Fujitsu MB86295 (Coral P), Samsung S6B33B1X and UltraChip UC1606. VNC support added. JE Functions added to DROPDOWN, CHECKBOX and RADIO widget Support for Epson SED1520 added. Support for Fujitsu MB87J2020 and MB87J2120 added. RS GUI_MEMDEV_GetDataPtr() added WM_CF_CONST_OUTLINE added RS JPEG file support added. JE Functions added to LISTVIEW widget. WM_GetFocussedWindow added to window manager. RS Core functions added. Functions added to window manager. JE Functions added to window manager. Functions added to widgets. JE Multi layer support added. UTF-8 support added JE MULTIEDIT widget added. User drawn LISTBOX added. Functions added to window manager. JE Functions added to FRAMEWIN widget. Multi selection mode added to LISTBOX widget. JE Multi selection mode added to LISTBOX widget. Activation of frame windows changed. JE Functions added to SCROLLBAR widget, BUTTON widget and LISTBOX widget. JE Functions added to FRAMEWIN widget and window manager. Dynamic memory support added. RS EDIT_SetCursorAtChar() and EDIT_SetCursorAtPixel() added. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 20 Software version 3.32 3.30 3.28 3.28 3.26 3.26 3.24 3.22 3.20 Date 020920 020912 020903 020830 020820 020820 020726 020719 020618 By Explanation RS WM_SetpfPollPID() added. BMP file support added. RS Cursor support added. GUI_TOUCH_StoreStateEx() added. RS Edit widget: flags added. Simulation: additional options for simulation of colored mono- chrome displays added. SIM_SetLCDColorBlack() and SIM_SetLCDColorWhite() added. RS New starter kit. LISTBOX_AddString() and LISTBOX_GetNumItems() added. RS Mouse and keyboard support added. RS Mouse and keyboard support added. RS GUI_Exec() and GUI_Exec1() added. RS Support for 444 color mode added Scrollbars, Radio buttons added. RS Dialog boxes added. Slider added. Check box added. 3D effects added. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 21 Table of Contents 1 Introduction to μC/GUI ...................................................................................................27 1.1 1.2 1.3 1.4 1.5 1.6 1.7 1.8 1.9 1.10 Purpose of this document ......................................................................... 27 Assumptions ........................................................................................... 27 Requirements.......................................................................................... 28 µC/GUI features ...................................................................................... 28 Samples and demos................................................................................. 30 How to use this manual ............................................................................ 30 Typographic conventions for syntax ........................................................... 30 Screen and coordinates ............................................................................ 31 How to connect the LCD to the microcontroller ............................................ 31 Data types.............................................................................................. 33 2 Getting Started...............................................................................................................35 2.1 Recommended directory structure.............................................................. 36 2.2 Adding µC/GUI to the target program......................................................... 37 2.3 Creating a library..................................................................................... 37 2.4 "C" files to include in the project................................................................ 39 2.5 Configuring µC/GUI.................................................................................. 40 2.6 Initializing µC/GUI ................................................................................... 41 2.7 Using µC/GUI with target hardware............................................................ 41 2.8 The "Hello world" sample program ............................................................. 41 3 Simulator........................................................................................................................45 3.1 Using the simulator.................................................................................. 46 3.2 Device simulation .................................................................................... 50 3.3 Integrating the µC/GUI simulation into an existing simulation ........................ 58 4 Viewer ...........................................................................................................................65 4.1 Using the viewer...................................................................................... 66 5 Displaying Text ..............................................................................................................71 5.1 Basic routines ......................................................................................... 72 5.2 Text API ................................................................................................. 72 5.3 Routines to display text ............................................................................ 73 5.4 Selecting text drawing modes.................................................................... 80 5.5 Selecting text alignment ........................................................................... 82 5.6 Setting the current text position ................................................................ 83 5.7 Retrieving the current text position ............................................................ 84 5.8 Routines to clear a window or parts of it ..................................................... 84 6 Displaying Values ..........................................................................................................87 6.1 Value API ............................................................................................... 88 User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 22 6.2 Displaying decimal values......................................................................... 88 6.3 Displaying floating-point values................................................................. 92 6.4 Displaying binary values........................................................................... 95 6.5 Displaying hexadecimal values .................................................................. 96 6.6 Version of µC/GUI ................................................................................... 97 7 2-D Graphic Library........................................................................................................99 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 Graphic API ...........................................................................................100 Drawing modes......................................................................................101 Query current client rectangle ..................................................................103 Basic drawing routines ............................................................................103 Drawing bitmaps ....................................................................................106 Drawing lines.........................................................................................109 Drawing polygons...................................................................................112 Drawing circles ......................................................................................117 Drawing ellipses.....................................................................................118 Drawing arcs .........................................................................................120 Drawing graphs .....................................................................................121 Saving and restoring the GUI-context .......................................................122 Clipping ................................................................................................123 8 Displaying bitmap files .................................................................................................125 8.1 BMP file support .....................................................................................126 8.2 JPEG file support ....................................................................................132 8.3 GIF file support ......................................................................................138 9 Fonts ............................................................................................................................149 9.1 Font types.............................................................................................150 9.2 Font formats..........................................................................................150 9.3 Font API................................................................................................151 9.4 Selection of a font ..................................................................................152 9.5 Font-related functions.............................................................................156 9.6 Character sets .......................................................................................160 9.7 Font converter .......................................................................................163 9.8 Standard fonts.......................................................................................165 10 Bitmap Converter .......................................................................................................189 10.1 10.2 10.3 10.4 10.5 10.6 10.7 10.8 What it does ..........................................................................................190 Loading a bitmap ...................................................................................190 Generating C files from bitmaps ...............................................................191 Color conversion ....................................................................................193 Compressed bitmaps ..............................................................................194 Using a custom palette ...........................................................................195 BmpCvt.exe: Command line usage ...........................................................195 Example of a converted bitmap ................................................................197 11 Colors.........................................................................................................................201 11.1 11.2 11.3 11.4 11.5 11.6 Predefined colors....................................................................................202 The color bar test routine ........................................................................202 Fixed palette modes ...............................................................................204 Custom palette modes ............................................................................216 Modifying the color lookup table at run time...............................................216 Color API ..............................................................................................217 User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 23 11.7 11.8 11.9 Basic color functions .............................................................................. 217 Index & color conversion ........................................................................ 219 Lookup table (LUT) group ....................................................................... 220 12 Memory Devices ........................................................................................................223 12.1 12.2 12.3 12.4 12.5 12.6 12.7 12.8 12.9 12.10 12.11 12.12 Using memory devices: an illustration ...................................................... 224 Supported color depth (bpp) ................................................................... 225 Memory devices and the window manager ................................................ 225 Memory requirements ............................................................................ 225 Performance ......................................................................................... 226 Basic functions ...................................................................................... 226 In order to be able to use memory devices................................................ 227 Memory device API ................................................................................ 227 Basic functions ...................................................................................... 228 Banding memory device ......................................................................... 240 Auto device object ................................................................................. 243 Measurement device object..................................................................... 248 13 Execution Model: Single Task / Multitask ..................................................................251 13.1 13.2 13.3 13.4 13.5 13.6 Supported execution models ................................................................... 252 Single task system (superloop)................................................................ 252 µC/GUI Multitask system: one task calling µC/GUI ..................................... 253 µC/GUI Multitask system: multiple tasks calling µC/GUI ............................ 254 GUI configuration macros for multitasking support ..................................... 255 Kernel interface routine API .................................................................... 257 14 The Window Manager (WM) ......................................................................................261 14.1 14.2 14.3 14.4 14.5 14.6 14.7 14.8 14.9 Explanation of terms .............................................................................. 262 Callback mechanism, invalidation and rendering ........................................ 263 Messages ............................................................................................. 267 Configuration options ............................................................................. 276 WM API ................................................................................................ 277 Basic functions ...................................................................................... 279 Memory device support (optional) ............................................................ 311 Widget related functions ......................................................................... 312 Example ............................................................................................... 316 15 Window Objects (Widgets).........................................................................................319 15.1 15.2 15.3 15.4 15.5 15.6 15.7 15.8 15.9 15.10 15.11 15.12 15.13 15.14 15.15 Some basics ......................................................................................... 320 Configuration options ............................................................................. 323 General widget API ................................................................................ 324 BUTTON: Button widget.......................................................................... 330 CHECKBOX: Check box widget................................................................. 349 DROPDOWN: Dropdown widget ............................................................... 365 EDIT: Edit widget .................................................................................. 377 FRAMEWIN: Frame window widget ........................................................... 396 GRAPH: Graph widget ............................................................................ 419 HEADER: Header widget ......................................................................... 443 LISTBOX: List box widget ....................................................................... 457 LISTVIEW: Listview widget...................................................................... 482 MENU: Menu widget............................................................................... 507 MESSAGEBOX: Message box widget ......................................................... 527 MULTIEDIT: Multi line text widget ............................................................ 529 User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 24 15.16 15.17 15.18 15.19 15.20 15.21 15.22 MULTIPAGE: Multiple page widget ............................................................542 PROGBAR: Progress bar widget ................................................................557 RADIO: Radio button widget ....................................................................566 SCROLLBAR: Scroll bar widget .................................................................578 SLIDER: Slider widget.............................................................................586 TEXT: Text widget ..................................................................................593 WINDOW: Window widget .......................................................................599 16 Dialogs .......................................................................................................................601 16.1 16.2 16.3 16.4 16.5 Dialog basics .........................................................................................602 Creating a dialog....................................................................................602 API reference: dialogs.............................................................................606 Dialog boxes..........................................................................................606 Message boxes ......................................................................................608 17 Virtual screen / Virtual pages .....................................................................................611 17.1 17.2 17.3 17.4 17.5 Introduction ..........................................................................................612 Requirements ........................................................................................612 Configuration.........................................................................................613 Samples ...............................................................................................614 Virtual screen API...................................................................................620 18 Multi layer / multi display support...............................................................................621 18.1 18.2 18.3 18.4 18.5 18.6 Introduction ..........................................................................................622 Using multi layer support ........................................................................626 Using multi display support......................................................................627 Configuring multi layer support ................................................................628 Configuring multi display support .............................................................629 Multi layer API .......................................................................................631 19 Pointer Input Devices.................................................................................................633 19.1 19.2 19.3 19.4 19.5 Description ............................................................................................634 Pointer input device API ..........................................................................635 Mouse driver .........................................................................................637 Touch-screen drivers ..............................................................................639 Joystick input sample..............................................................................647 20 Keyboard Input...........................................................................................................649 20.1 Description............................................................................................650 21 Cursors ......................................................................................................................653 21.1 21.2 Available cursors ....................................................................................654 Cursor API ............................................................................................654 22 Antialiasing.................................................................................................................657 22.1 22.2 22.3 22.4 22.5 Introduction ..........................................................................................658 Antialiasing API......................................................................................661 Control functions....................................................................................661 Drawing functions ..................................................................................662 Examples ..............................................................................................666 23 Foreign Language Support ........................................................................................671 User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 25 23.1 23.2 23.3 23.4 Unicode................................................................................................ 672 Arabic language support ......................................................................... 678 Thai language support............................................................................ 681 Shift JIS support ................................................................................... 682 24 Display drivers ...........................................................................................................687 24.1 24.2 24.3 24.4 Available drivers and supported display controllers ..................................... 688 CPU / Display controller interface............................................................. 691 Detailed display driver descriptions .......................................................... 695 LCD layer and display driver API .............................................................. 768 25 VNC support ..............................................................................................................779 25.1 25.2 25.3 25.4 25.5 25.6 Introduction.......................................................................................... 780 The VNC viewer..................................................................................... 781 µC/GUI VNC server ................................................................................ 782 Required resources ................................................................................ 783 Configuration options ............................................................................. 783 VNC API ............................................................................................... 783 26 Time-Related Functions.............................................................................................787 27 Low-Level Configuration (LCDConf.h) .......................................................................791 27.1 27.2 27.3 27.4 27.5 27.6 27.7 27.8 27.9 27.10 27.11 Available configuration macros ................................................................ 792 General (required) configuration .............................................................. 794 Initializing the controller ......................................................................... 795 Display orientation................................................................................. 796 Color configuration ................................................................................ 798 Magnifying the LCD................................................................................ 799 Simple bus interface configuration ........................................................... 800 Full bus interface configuration ................................................................ 804 LCD controller configuration: common/segment lines ................................. 809 COM/SEG lookup tables .......................................................................... 812 Miscellaneous........................................................................................ 813 28 High-Level Configuration (GUIConf.h) .......................................................................815 28.1 28.2 28.3 28.4 28.5 28.6 28.7 28.8 28.9 28.10 General notes ....................................................................................... 816 How to configure the GUI ....................................................................... 816 Available GUI configuration macros .......................................................... 816 GUI_X routine reference ......................................................................... 819 Init routine ........................................................................................... 819 Timing routines ..................................................................................... 819 Kernel interface routines......................................................................... 820 Debugging ............................................................................................ 820 Dynamic memory .................................................................................. 821 Special considerations for certain Compilers/CPUs ...................................... 823 29 Performance and Resource Usage............................................................................825 29.1 29.2 Performance benchmark ......................................................................... 826 Memory requirements ............................................................................ 828 30 Support ......................................................................................................................833 30.1 Problems with tool chain (compiler, linker) ................................................ 834 User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 26 30.2 30.3 30.4 30.5 30.6 Problems with hardware/driver ................................................................835 Problems with API functions.....................................................................836 Problems with the performance ................................................................837 Contacting support .................................................................................837 FAQ’s ...................................................................................................838 31 Index ..........................................................................................................................841 User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 27 Chapter 2 Introduction to µC/GUI 2.1 Purpose of this document This guide describes how to install, configure and use the µC/GUI graphical user interface for embedded applications. It also explains the internal structure of the software. 2.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, also covers the ANSI "C" standard. Knowledge of assembly programming is not required. User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 28 CHAPTER 2 Introduction to μC/GUI 2.3 Requirements A target system is not required in order to develop software with µC/GUI; 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. 2.3.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 LCD (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: 500 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 bytes • 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. 2.3.2 Development environment (compiler) The CPU used is of no importance; only an ANSI-compliant "C" compiler covering the international standard ISO/IEC 9899:1990, ISO/IEC 9899:1999 or ANSI/ISO 9899:1990 is required. If your compiler has some limitations, please 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. 2.4 µC/GUI features µC/GUI is designed to provide an efficient, processor- and LCD controller-independent graphical user interface for any application that operates with a graphical LCD. It is compatible with single-task and multitask environments, with a proprietary operating system or with any commercial RTOS. µC/GUI is shipped as "C" source code. It may be adapted to any size physical and virtual display with any LCD controller and CPU. Its features include the following: General • Any 8/16/32-bit CPU; only an ANSI "C" compiler is required. • Any (monochrome, grayscale or color) LCD with any controller supported (if the right driver is available). User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 29 • May work without LCD controller on smaller displays. • Any interface supported using configuration macros. • Display-size configurable. • Characters and bitmaps may be written at any point on the LCD, not just on even-numbered byte addresses. • Routines are optimized for both size and speed. • Compile time switches allow for different optimizations. • For slower LCD controllers, LCD 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 30: "Standard Fonts". • New fonts can be defined and simply linked in. • Only the fonts used by the application are actually linked to the resulting execut- able, resulting in minimum ROM usage. • Fonts are fully scalable, separately in X and Y. • Font converter available; any font available on your host system (i.e. 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. 20 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, µC/GUI offers touch-screen and mouse support. PC tools • Simulation plus viewer. • Bitmap converter. • Font converter.u User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 30 CHAPTER 2 Introduction to μC/GUI 2.5 Samples and demos To give you a better idea of what µC/GUI can do, we have different demos available as "ready-to-use" simulation executables under Sample\EXE. The source of the sample programs is located in the folder Sample. The folder Sample\GUIDemo contains an application program showing most of µC/GUI’s features. 2.6 How to use this manual This manual explains how to install, configure and use µC/GUI. It describes the internal structure of the software and all the functions that µC/GUI offers (the Application Program Interface, or API). Before actually using µC/GUI, you should read or at least glance through this manual in order to become familiar with the software. The following steps are then recommended: • Copy the µC/GUI files to your computer. • Go through Chapter 2: "Getting Started". • Use the simulator in order to become more familiar with what the software can do (refer to Chapter 4: "Simulator). • Expand your program using the rest of the manual for reference.Typographic conventions for syntax 2.7 Typographic conventions for syntax This manual uses the following typographic conventions: Style Body Keyword Parameter Sample New Sample Used for Body text. Text that you enter at the command-prompt or that appears on the display (i.e. system functions, file- or pathnames). Parameters in API functions. Sample code in program examples. Sample code that has been added to an existing program example. User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 31 2.8 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 µC/GUI 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 Y- axis. Coordinates are denoted as a pair consisting of an X- and a Y-value (X, Y). 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. 2.9 How to connect the LCD to the microcontroller µC/GUI handles all access to the LCD. Virtually any LCD controller can be supported, independently of how it is accessed. For details, please refer to Chapter 28: "LowLevel Configuration". Also, please get in contact with us if your LCD controller is not supported. We are currently writing drivers for all LCD controllers available on the market and may already have a proven driver for the LCD controller that you intend to use. It is usually very simple to write the routines (or macros) used to access the LCD in your application. Micrium offers the customization service, if necessary with your target hardware. It does not really matter how the LCD 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 explained in Chapter 25: "LCD Drivers". The most common ways to access the LCD are described as follows. If you simply want to understand how to use µC/GUI, you may skip this section. LCD with memory-mapped LCD controller: The LCD 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 LCD controller and is most recommended. The LCD addresses are defined to the segment LCDSEG, and in order to be able to access the LCD 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 LCD controllers. LCD with LCD controller connected to port / buffer For slower LCD controllers used on fast processors, the use of port-lines may be the only solution. This method of accessing the LCD has the disadvantage of being somewhat slower than direct bus-interface but, particularly with a cache that minimizes User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 32 CHAPTER 2 Introduction to μC/GUI the accesses to the LCD, the LCD 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 LCD is connected to. This type of interface is also supported by different drivers for the different LCD controllers. Proprietary solutions: LCD without LCD controller The LCD can also be connected without an LCD controller. In this case, the LCD 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 LCD driver because µC/GUI simply places all the display data into the LCD cache. You must write the hardware-dependent portion that periodically transfers the data in the cache memory to your LCD. Sample 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 μC/GUI © 2002-2005 Micrium Technologies Corporation 33 2.10 Data types Since "C" does not provide data types of fixed lengths which are identical on all platforms, µC/GUI uses, in most cases, its own data types as shown in the table below: Data type I8 U8 I16 U16 I32 U32 I16P U16P Definition Explanation signed char 8-bit signed value unsigned char 16-bit unsigned value signed short 16-bit signed value unsigned short 16-bit unsigned value signed long 32-bit signed value unsigned long 32-bit unsigned value signed short 16-bit (or more) signed value 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 configuration file LCDConf.h. User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 34 CHAPTER 2 Introduction to μC/GUI User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 35 Chapter 3 Getting Started The following chapter provides an overview of the basic procedures for setting up and configuring µC/GUI 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 μC/GUI © 2002-2005 Micrium Technologies Corporation 36 CHAPTER 3 Getting Started 3.1 Recommended directory structure We recommend keeping µC/GUI 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 µC/GUI by simply replacing the GUI\ directories. Your application files can be stored anywhere. 3.1.1 Subdirectories The following table shows the contents of all GUI subdirectories: Directory Config GUI\AntiAlias GUI\ConvertMono GUI\ConvertColor GUI\Core GUI\Font GUI\LCDDriver GUI\MemDev GUI\Widget GUI\WM Contents Configuration files Antialiasing support * Color conversion routines used for grayscale displays * Color conversion routines used for color displays * µC/GUI core files Font files LCD driver Memory device support * Widget library * Window manager * (* = optional) 3.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\Widget (if using 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 µC/GUI if you have old files included and therefore mix different versions. If you keep µC/GUI 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 (or at least renaming) the GUI\ directories prior to updating. User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 37 3.2 Adding µC/GUI 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 (linking in only the modules that are referenced and not those that are unreferenced), 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 sample projects available to help you get started. 3.3 Creating a library Building a library from the sources is a simple procedure. The first step is to copy the batch files (located under Sam- Makelib.bat ple\Makelib) into your root directory. Then, make any necce- sary 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 nor- mally need to make slight modifcations to the other three smaller files. Finally, start the file Makelib.bat to create the CC.bat library. The batch files assume that your GUI and Config subdi- rectories are set up as recommended. No The procedure for creating a library is illustrated in the flow chart to the right. The Makelib.bat file first calls Prep.bat to prepare the environment for the tool chain. Then it calls CC.bat All files in library? 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. File Makelib.bat Prep.bat CC.bat lib.bat Explanation Main batch file. No modification required. Called by Makelib.bat to prepare environment for the tool chain to be used, 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. 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 µC/GUI simulation. In order to create a target library, however, it will be necessary to modify Prep.bat, CC.bat, and lib.bat. User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 38 CHAPTER 3 Getting Started 3.3.1 Adapting the library batch files to a different system The following will show how to adapt the files by a sample adaptation for a Mitsubishi M32C CPU. 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 Lib Temp\Output Temp\Source Contents This folder should contain the library file after the build process. Should contain all the compiler output and the link list file. Will be deleted after the build process. 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 a sample 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 ****************************************************************** User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 39 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 a sample for the Mitsubishi librarian: @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 3.4 "C" files to include in the project Generally speaking, you need to include the core "C" files of µC/GUI, the LCD driver, all font files you plan to use and any optional modules you have ordered with µC/ GUI: • All "C" files of the folder GUI\Core • The fonts you plan to use (located in GUI\Font) • LCD driver: All "C" files of the folder GUI\LCDDriver. 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 User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 40 CHAPTER 3 Getting Started • Antialiasing: all "C" files located in GUI\AntiAlias • Memory devices: all "C" files located in GUI\MemDev • Widget library: all "C" files located in GUI\Widget • Window Manager: all "C" files located in GUI\WM Target specifics • GUI_X.c. A sample file is available as Sample\GUI_X. This file contains the hardware-dependent part of µC/GUI and should be modified as described in Chapter 29: "High-Level Configuration". Be sure that you include GUI.h in all of your source files that access µC/GUI. 3.5 Configuring µC/GUI The Config folder should contain the configuration files matching your order. The file LCDConf.h normally contains all the definitions necessary to adopt µC/GUI to your LCD, which is the main task when configuring µC/GUI. For details, please see Chapter 28: "Low-Level Configuration". If µC/GUI is not configured correctly, because you did not select the right display resolution or chose the wrong LCD controller, it will probably not display anything at all or display something that does not resemble what you expected. So take care to tailor LCDConf.h to your needs. If you do not wish to deal with this process, Micrium Technologies Corporation Inc. can do it for you, as well as test µC/GUI in your application with your hardware and your LCD. The following types of configuration macros exist: 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 an LCD. 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 LCD controller used, where the number selected denotes which source code (in which LCD 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 LCD) which is highly hardware-dependent. This type of macro is always declared using brackets (and optional parameters). User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 41 3.6 Initializing µC/GUI The routine GUI_Init() initializes the LCD and the internal data structures of µC/ GUI, and must be called before any other µC/GUI function. This is done by placing the following line into the init sequence of your program: GUI_Init(); If this call is left out, the entire graphics system will not be initialized and will therefore not be ready. 3.7 Using µC/GUI with target hardware The following is just a basic outline of the general steps that should be taken when starting to program with µC/GUI. All steps are explained further in subsequent chapters. Step 1: Customizing µC/GUI The first step is usually to customize µC/GUI by modifying the header file LCDConf.h. You must define the basic data types (U8, U16, etc.) and mandatory configuration switches regarding resolution of the display and the LCD controller used. Step 2: Defining access addresses or access routines For memory-mapped LCDs, the access addresses of the LCD simply need to be defined in LCDConf.h. For port/buffer-accessed LCDs, interface routines must be defined. Samples of the required routines are available under Samples\LCD_X or on our website in the download area. Step 3: Compiling, linking and testing the sample code µC/GUI comes with sample code for both single- and multitask environments. Compile, link and test these little sample programs until you feel comfortable doing so. Step 4: Modifying the sample program Make simple modifications to the sample 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 sample adaptations, please refer to Chapter 29: "High-Level Configuration". Step 6: Write your own application using µC/GUI By now you should have a clearer understanding of how to use µC/GUI. Think about how to structure the program your application requires and use µC/GUI by calling the appropriate routines. Consult the reference chapters later in this manual, as they discuss the specific µC/GUI functions and configuration macros that are available. 3.8 The "Hello world" sample program 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. A "Hello world" program with µC/GUI, called HELLO.c, is shown below and is available as BASIC_HelloWorld.c in the sample shipped with µC/GUI. User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 42 CHAPTER 3 Getting Started 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 LCD and the GUI must first be initialized. µC/GUI is initialized by a call to GUI_Init() at the start of the program, as described previously. In this example, we assume that the hardware of your application is already initialized. The “Hello world” program looks as follows: /********************************************************************* * Micrium Inc. * * Empowering embedded systems * * * * µC/GUI sample code * * * ********************************************************************** ---------------------------------------------------------------------- File : BASIC_HelloWorld.c Purpose : Simple demo drawing "Hello world" ---------------------------------------------------------------------- */ #include "GUI.H" /******************************************************************* * * main * ******************************************************************** */ void main(void) { /* ToDo: Make sure hardware is initilized first!! */ 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 LCD 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. /********************************************************************* * Micrium Inc. * * Empowering embedded systems * * * * µC/GUI sample code * * * ********************************************************************** ---------------------------------------------------------------------- File : BASIC_Hello1.c Purpose : Simple demo drawing "Hello world" ---------------------------------------------------------------------- */ #include "GUI.H" /******************************************************************* * * main * User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 43 ******************************************************************** */ void main(void) { int i=0; /* ToDo: Make sure hardware is initilized first!! */ GUI_Init(); GUI_DispString("Hello world!"); while(1) { GUI_DispDecAt( i++, 20,20,4); if (i>9999) i=0; } } User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 44 CHAPTER 3 Getting Started User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 45 Chapter 4 Simulator The PC simulation of µC/GUI 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 email. User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 46 CHAPTER 4 Simulator 4.1 Using the simulator The µC/GUI simulator uses 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 will have 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. 4.1.1 Using the simulator in the trial µC/GUI version The trial version of µC/GUI contains a full library which allows you to evaluate all available features of µC/GUI. It also includes the µC/GUI 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 change any configuration settings or view the source code, but you will still be able to become familiar with what µC/GUI can do. 4.1.1.1 Directory structure The directory structure of the simulator in the trial version will appear as pictured to the right. The table below explains the contents of the folders: Directory Application Config Exe GUI Sample Simulation Tool Contents Source of the demo program. configuration files used to build the library. Do not make any changes to these files! Ready-to-use demo program. Library files and include files needed to use the library. Simulation samples and their sources. Files needed for the simulation. The µC/GUI viewer, a demo version of the bitmap converter and a demo version of the font converter. User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 47 4.1.1.2 Visual C++ workspace The root directory shown above includes the Microsoft Visual C++ workspace (Simula- tionTrial.dsw) and project file (Simula- tionTrial.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. 4.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. Please 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 exited at any time by right-clicking on it and selecting Exit. 4.1.1.4 Compiling the samples The Sample directory contains ready-to-go samples that demonstrate different features of µC/GUI 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 sample which should be used by right-clicking on it and deselecting ’Settings\General\Exclude from build’. The screenshot below shows the sample DIALOG_SliderColor.c. • Step 3: Rebuild the sample by choosing Build/Rebuild All from the menu (or by pressing F7). • Step 4: Start the simulation by choosing Build/Start Debug/Go from the menu (or by pressing F5). The result of the sample selected above is pictured below: User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 48 CHAPTER 4 Simulator 4.1.2 Using the simulator with the µC/GUI source 4.1.2.1 Directory structure The root directory of the simulator can be anywhere on your PC, e.g. C:\work\uCGUISim. 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 2: "Getting Started" for more information). The following table shows the contents of the folders: Directory Doc Sample Start Tool Trial Contents Contains µC/GUI-Documentation. Code samples, described later in this documentation. All you need to create a new project with µC/GUI Tools shipped with µC/GUI Complete trial version User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 49 If you want to start a new project you should make a copy of the Start-folder. It contains all you need for a new project. The subdirectories containing µC/GUI program files are in the Start\GUI folder and should contain the exact same files as the directories of the same names which you are using for your target (cross) compiler. You should not make any changes to the GUI subdirectories, as this would make updating to a newer version of µC/GUI 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). 4.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 µC/GUI subdirectories. Please note that your GUI directory may not look exactly like the one pictured, depending on which additional features of µC/GUI you have. The folders Core, Font and LCDDriver are part of the basic µC/GUI package and will always appear in the workspace directory. 4.1.2.3 Compiling the application The demo simulation contains one or more application "C" files (located in the Application directory), which can be modified. You may also add files to or remove files from the project. Typically you would want to at least change the bitmap to your own company logo or image of choice. 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 simulator would be as follows: • 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. User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 50 CHAPTER 4 Simulator 4.2 Device simulation The simulator can show the simulated LCD in a bitmap of your choice, typically your target device. The bitmap can be dragged over the screen and may, in certain applications, be used to simulate the behavior of the entire target device. In order to simulate the appearance of the device, a bitmap is required. This bitmap is usually a photo (top view) of the device, and must 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 by including the following line in the resource file (extension .rc): 145 BITMAP DISCARDABLE "Device.bmp" For more information, please refer to the Win32 documentation. The size of the bitmap should be such that the size of the area in which the LCD will be shown equals the resolution of the simulated LCD. This is best seen in the following example: Device bitmap (Device.bmp) Device including simulated LCD as visible on screen The red area is automatically made transparent. The transparent 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 (0xFF0000) 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_SetTransColor(). 4.2.1 Device simulator API All of the device simulator API functions must be called in the setup phase. The calls should ideally be done from within the routine SIM_X_Init(), which is located in the file SIM_X.c. The example below calls SIM_SetLCDPos() in the setup: #include #include User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 51 #include "SIM.h" void SIM_X_Init() { SIM_SetLCDPos(0,0); } // Define the position of the LCD in the bitmap The table below lists the available device-simulation-related routines in alphabetical order within their respective categories. Detailed descriptions of the routines follow: Routine SIM_GUI_SetLCDColorBlack() SIM_GUI_SetLCDColorWhite() SIM_GUI_SetLCDPos() SIM_GUI_SetMag() SIM_GUI_SetTransColor() Explanation Set the color to be used as black (color monochrome displays). Set the color to be used as white (color monochrome displays). Set the position for the simulated LCD within the target device bitmap. Set magnification factors for X and/or Y axis. Set the color to be used for transparent areas (default: 0xFF0000). 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 Meaning 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_Init() { SIM_GUI_SetLCDPos(14,84); // Define the position of the LCD in the bitmap SIM_GUI_SetLCDColorBlack (0, 0x000000); // Define the color used as black SIM_GUI_SetLCDColorWhite (0, 0xFFFFFF); // Define the color used as white (used for colored monochrome displays) } User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 52 CHAPTER 4 Simulator Example using yellow instead of white void SIM_X_Init() { SIM_GUI_SetLCDPos(14,84); // Define the position of the LCD in the bitmap SIM_GUI_SetLCDColorBlack (0, 0x000000); // Define the color used as black SIM_GUI_SetLCDColorWhite (0, 0x00FFFF); // Define the color used as white (used for colored monochrome displays) } 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 x y Meaning X-position of the upper left corner for the simulated LCD (in pixels). 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. 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 Magnification factor for X axis. Magnification factor for Y axis. Meaning 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. User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 53 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 Meaning 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. 4.2.2 Hardkey simulation 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). This bitmap can again be in a separate file in the directory, or included as a resource in the executable. The filename needs to be Device1.bmp, and the following lines would typically be included in the resource file (extension .rc): 145 BITMAP DISCARDABLE "Device.bmp" 146 BITMAP DISCARDABLE "Device1.bmp" User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 54 CHAPTER 4 Simulator 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. 4.2.2.1 Hardkey simulator API The hardkey simulation functions are part of the standard simulation program shipped with µC/GUI. If using a user defined µC/GUI 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 SIM_HARDKEY_GetNum() SIM_HARDKEY_GetState() SIM_HARDKEY_SetCallback() SIM_HARDKEY_SetMode() SIM_HARDKEY_SetState() Explanation Return the number of available hardkeys. Return the state of a specified hardkey (0: unpressed, 1: pressed). Set a callback routine to be executed when the state of a specified hardkey changes. Set the behavior for a specified hardkey (default = 0: no toggle). Set the state for a specified hardkey (0: unpressed, 1: pressed). User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 55 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. SIM_HARDKEY_GetState() Description Returns the state of a specified hardkey. Prototype int SIM_HARDKEY_GetState(unsigned int KeyIndex); Parameter KeyIndex Meaning 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. User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 56 CHAPTER 4 Simulator Prototype SIM_HARDKEY_CB* SIM_HARDKEY_SetCallback(unsigned int KeyIndex, SIM_HARDKEY_CB* pfCallback); Parameter KeyIndex pfCallback Meaning Index of hardkey (0 = index of first key). Pointer to callback routine. Return value Pointer to the previous callback routine. Additional information The callback routine must have the following prototype: Prototype typedef void SIM_HARDKEY_CB(int KeyIndex, int State); Parameter KeyIndex State Meaning Index of hardkey (0 = index of first key). State of the specified hardkey (see table below). Permitted values for parameter State 0 Unpressed. 1 Pressed. SIM_HARDKEY_SetMode() Description Sets the behavior for a specified hardkey. Prototype int SIM_HARDKEY_SetMode(unsigned int KeyIndex, int Mode); Parameter KeyIndex Mode Meaning Index of hardkey (0 = index of first key). Behavior mode (see table below). Permitted values for parameter Mode 0 Normal behavior (default). 1 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. User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 57 SIM_HARDKEY_SetState() Description Sets the state for a specified hardkey. Prototype int SIM_HARDKEY_SetState(unsigned int KeyIndex, int State); Parameter KeyIndex State Meaning Index of hardkey (0 = index of first key). State of the specified hardkey (see table below). Permitted values for parameter State 0 Unpressed. 1 Pressed. Additional information This function is only usable when SIM_HARDKEY_SetMode() is set to 1 (toggle mode). User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 58 CHAPTER 4 Simulator 4.3 Integrating the µC/GUI simulation into an existing simulation In order to integrate the µC/GUI 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 µC/GUI. It is a separate (optional) software item and is not included in the µC/GUI basic package. Normally the source code of the µC/GUI 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 µC/GUI simulation should be added to an existing hardware or real time kernel (RTOS) simulation. To add the µC/GUI simulation to an existing simulation (wrtten in "C" or C++, using the Win32 API), only a few lines of code need to be added. 4.3.1 Directory structure The subfolder Simulation of the System folder contains the µC/GUI simulation. The directory structure is shown on the right. The table below explains the contents of the subfolders: Directory Simulation Res SIM_GUI WinMain Contents 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. Resource files. GUI simulation source code (optional). Contains the WinMain routine. 4.3.2 Using the simulation library The following steps will show how to use the simulation library to integrate the µC/ GUI 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, "Subdi- rectories". • Step 3: Add the include directories to the project as described in the chapter 2.1.2, "Include Directories". • Step 4: Modify WinMain. 4.3.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 this order as show in the following application code sample): User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 59 • SIM_GUI_Init • SIM_GUI_CreateLCDWindow • CreateThread • SIM_GUI_Exit 4.3.2.2 Sample application The following application is available under Sample\WinMain\SampleApp.c and shows how to integrate the µC/GUI simulation into an existing application: #include #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 */ User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 60 CHAPTER 4 Simulator hWndMain = CreateWindow("GUIApplication", "Application window", WS_OVERLAPPEDWINDOW | WS_CLIPCHILDREN | WS_VISIBLE, 0, 0, 328, 267, NULL, NULL, hInstance, NULL); /* Initialize the µC/GUI simulation and create a LCD window */ SIM_GUI_Init(hInstance, hWndMain, lpCmdLine, "RTOS - µC/GUI 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 μC/GUI © 2002-2005 Micrium Technologies Corporation 61 4.3.3 GUI simultion API The table below lists the available routines for user defined simulation programms in alphabetical order within their respective categories. The functions are only available with the source code of the µC/GUI 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 xSize ySize LayerIndex Meaning Handle of the parent window. X position in parent coordinates. Y position in parent coordinates. 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. 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. Index of layer to be shown. Additional information The created color window has no frame, no title bar and no buttons. User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 62 CHAPTER 4 Example SIM_GUI_CreateLCDInfoWindow(hWnd, 0, 0, 160, 160, 0); Screenshot Simulator 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 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. Meaning 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.h. 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 µC/GUI simulation and should be called before any other SIM_GUI... function call. Prototype int SIM_GUI_Init(HINSTANCE hInst, HWND hWndMain, User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 63 char * pCmdLine, const char * sAppName); Parameter hInst hWndMain pCmdLine sAppName Meaning 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. 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 Pointer to hook function. Meaning Prototype of hook function int Hook(HWND hWnd, UINT Message, WPARAM wParam, LPARAM lParam, int * pResult); Parameter hWnd Message wParam lParam pResult Meaning 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 μC/GUI © 2002-2005 Micrium Technologies Corporation 64 CHAPTER 4 Simulator User's & reference manual for μC/GUI © 2002-2005 Micrium Technologies Corporation 65 Chapter 5 Viewer If you use the simulator 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 μC/GUI © 2002-2006 Micrium Technologies Corporation 66 CHAPTER 5 Viewer 5.1 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 individ- ual 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. 5.1.1 Using the simulator and the viewer If you use the simulator 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 µC/GUI 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 μC/GUI © 2002-2006 Micrium Technologies Corporation 67 5.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 display 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: For more information about virtual screens please refer to chapter ’Virtual Screens’. 5.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. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 68 CHAPTER 5 Viewer 5.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. 5.1.5 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. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 69 5.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. 5.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: 5.1.8 Using the viewer with multiple layers If you are working with multiple displays 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. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 70 CHAPTER 5 Viewer Sample The sample 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 Transparency The viewer treats pixels with index 0 in a layer above layer 0 as transparent. Therefore in the composite view the pixels of the layers below are visible. The composite window shows the layers one above the other: No transparency Pixels with index 0 handled transparent Pixels with index 0 handled transparent Layer 0 Layer 1 Layer 2 Transparent pixels will be shown in layer windows tiled User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 71 Chapter 6 Displaying Text It is very easy to display text with µC/GUI. 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 μC/GUI © 2002-2006 Micrium Technologies Corporation 72 CHAPTER 6 Displaying Text 6.1 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. µC/GUI ignores all control characters except for the following: Char. ASCII Code code 10 LF 13 CR "C" Meaning Line feed. The current text position is changed to the beginning of the next line. Per \n default, this is: X = 0. Y + =font-distance in pixels (as delivered by GUI_GetFontDistY()). Carriage return. \r 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 6.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 GUI_DispChar() GUI_DispCharAt() GUI_DispChars() GUI_DispNextLine() GUI_DispString() Explanation Routines to display text Display single character at current position. Display single character at specified position. Display character a specified number of times. Moves the cursor to the beginning of the next line. Display string at current position. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 73 Routine Explanation GUI_DispStringAt() Display string at specified position. GUI_DispStringAtCEOL() Display string at specified position, then clear to end of line. GUI_DispStringHCenterAt() Displays string centered horizontaly at the given position. GUI_DispStringInRect() Display string in specified rectangle. GUI_DispStringInRectEx() Displays string in specified rectangle and optional rotates it. GUI_DispStringInRectWrap() Displays string in specified rectangle with optional wrapping. GUI_DispStringLen() Display string at current position with specified number of characters. Selecting text drawing modes GUI_GetTextMode() Returns the current text mode GUI_SetTextMode() Set text drawing mode. GUI_SetTextStyle() Sets the text style to be used. Selecting text alignment GUI_GetTextAlign() Return current text alignment mode. GUI_SetLBorder() Set left border after line feed. GUI_SetTextAlign() Set text alignment mode. Setting the current text position GUI_GotoX() Set current X-position. GUI_GotoXY() Set current (X,Y) position. GUI_GotoY() Set current Y-position. Retrieving the current text position GUI_GetDispPosX() Return current X-position. 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. 6.3 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 c Character to display. Meaning 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. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 74 CHAPTER 6 Displaying Text 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 Meaning 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() 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 c Cnt Meaning Character to display. 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. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 75 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 String to display. Meaning 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");// Disp text GUI_DispString("\nNext line");// Disp text Related topics GUI_DispStringAt(), GUI_DispStringAtCEOL(), GUI_DispStringLen(), GUI_DispStringAt() Description Displays the string passed as parameter at a specified position in the current window using the current font. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 76 CHAPTER 6 Displaying Text Prototype void GUI_DispStringAt(const char GUI_FAR *s, int x, int y); Parameter Meaning s String to display. x X-position to write to in pixels of the client window. y 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 horizontaly 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 Meaning 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. 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, const GUI_RECT *pRect, User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 77 int Align); Parameter s pRect Align Meaning 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(), 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 (optional) rotates it. Prototype void GUI_DispStringInRectEx(const char GUI_UNI_PTR *s, GUI_RECT* pRect, int TextAlign, int MaxLen, const GUI_ROTATION * pLCD_Api); Parameter s pRect TextAlign MaxLen pLCD_Api Meaning 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 align- ment 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_CCW Does not rotate the text. Shows it from left to right. Rotates the text counter 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"; User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 78 CHAPTER 6 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 Displaying Text Additional information If the specified rectangle is too small, the text will be clipped. GUI_DispStringInRectWrap() Description Description Displays a string at a specified position within a specified rectangle, in the current window using the current font and (optionaly) wraps the text. Prototype void GUI_DispStringInRectWrap(const char GUI_UNI_PTR * s, GUI_RECT * pRect, int TextAlign, GUI_WRAPMODE WrapMode); Parameter s pRect TextAlign WrapMode Meaning 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 align- ment 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. (see table below) Permitted values for parameter pLCD_Api 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. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 79 Example Shows a text centered horizontally and vertically in the given rectangle with word wrapping: int i; char acText[] = "This sample 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 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 s Len Meaning String to display. Should be a \0 terminated array of 8-bit character. Passing NULL as parameter is permitted. 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(), User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 80 CHAPTER 6 Displaying Text 6.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. µC/GUI 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 in reverse by specifying GUI_TEXTMODE_REVERSE. What is usually displayed as white on black will be displayed as black on white. Transparent text 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 erased. Text can be displayed transparently by specifying GUI_TEXTMODE_TRANS. XOR text 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 As with transparent text, it does not overwrite the background, and as with reverse text, the text is displayed in reverse. Text can be displayed in reverse transparently by specifying GUI_TEXTMODE_TRANS | GUI_TEXTMODE_REVERSE. Example Displays normal, reverse, transparent, XOR, and transparent reversed text: GUI_SetFont(&GUI_Font8x16); 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" , 160, 10); GUI_SetTextMode(GUI_TM_REV); GUI_DispStringHCenterAt("GUI_TM_REV" , 160, 26); GUI_SetTextMode(GUI_TM_TRANS); GUI_DispStringHCenterAt("GUI_TM_TRANS" , 160, 42); GUI_SetTextMode(GUI_TM_XOR); GUI_DispStringHCenterAt("GUI_TM_XOR" , 160, 58); GUI_SetTextMode(GUI_TM_TRANS | GUI_TM_REV); GUI_DispStringHCenterAt("GUI_TM_TRANS | GUI_TM_REV", 160, 74); User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 81 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 Meaning Text mode to set. May be any combination of the TEXTMODE flags. Permitted values for parameter TextMode (OR-combinable) GUI_TEXTMODE_NORMAL Sets normal text. This is the default setting; the value is identical to 0. GUI_TEXTMODE_REVERSE Sets reverse text. GUI_TEXTMODE_TRANSPARENT Sets transparent text. GUI_TEXTMODE_XOR Text will be inverted on the display. 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_REVERSE); GUI_DispDec(20, 3); GUI_SetTextMode(GUI_TEXTMODE_NORMAL); User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 82 CHAPTER 6 Displaying Text GUI_SetTextStyle() Description Sets the text style to the parameter specified. Prototype char GUI_SetTextStyle(char Style); Parameter Style Meaning Text style to set (see table below). Permitted values for parameter Style GUI_TS_NORMAL GUI_TS_UNDERLINE GUI_TS_STRIKETHRU GUI_TS_OVERLINE Renders text normal (default). Renders text underlined. Renders text in strikethrough type. Renders text in overline type. Return value The previous selected text style. 6.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 Meaning x New left border (in pixels, 0 is left border). GUI_SetTextAlign() Description Sets the text alignment mode for string output in the current window. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 83 Prototype int GUI_SetTextAlign(int TextAlign); Parameter TextAlign Meaning 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 Align X-position left (default). GUI_TA_HCENTER Center X-position. GUI_TA_RIGHT Align X-position right (default). Vertical alignment GUI_TA_TOP Align Y-position with top of characters (default). GUI_TA_VCENTER Center Y-position. GUI_TA_BOTTOM 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(). 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); 6.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 Meaning New X-position (in pixels, 0 is left border). New Y-position (in pixels, 0 is top border). User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 84 CHAPTER 6 Displaying Text 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"); 6.7 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); 6.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: User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 85 GUI_DispStringAt("Hello world", 0, 0);// Disp text GUI_Delay(1000);// Wait 1 second (not part of µC/GUI) 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 μC/GUI © 2002-2006 Micrium Technologies Corporation 86 CHAPTER 6 Displaying Text User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 87 Chapter 7 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. µC/ GUI 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 μC/GUI © 2002-2006 Micrium Technologies Corporation 88 CHAPTER 7 Displaying Values 7.1 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 GUI_DispDec() GUI_DispDecAt() GUI_DispDecMin() GUI_DispDecShift() GUI_DispDecSpace() GUI_DispSDec() GUI_DispSDecShift() GUI_DispFloat() GUI_DispFloatFix() GUI_DispFloatMin() GUI_DispSFloatFix() GUI_DispSFloatMin() GUI_DispBin() GUI_DispBinAt() GUI_DispHex() GUI_DispHexAt() Explanation Displaying decimal values Display value in decimal form at current position with specified number of characters. Display value in decimal form at specified position with specified number of characters. Display value in decimal form at current position with minimum number of characters. Display long value in decimal form with decimal point at current position with specified number of characters. Display value in decimal form at current position with specified number of characters, replace leading zeros with spaces. Display value in decimal form at current position with specified number of characters and sign. Display long value in decimal form with decimal point at current position with specified number of characters and sign. Displaying floating-point values Display floating-point value with specified number of characters. Display floating-point value with fixed no. of digits to the right of decimal point. Display floating-point value with minimum number of characters. Display floating-point value with fixed no. of digits to the right of decimal point and sign. Display floating-point value with minimum number of characters and sign. Displaying binary values Display value in binary form at current position. Display value in binary form at specified position. Displaying hexadecimal values Display value in hexadecimal form at current position. Display value in hexadecimal form at specified position. 7.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. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 89 Prototype void GUI_DispDec(I32 v, U8 Len); Parameter v Len Value to display. Minimum -2147483648 (= -2^31). Maximum 2147483647 (= 2^31 -1). No. of digits to display (max. 9). Meaning 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 Meaning 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. 9). 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 μC/GUI © 2002-2006 Micrium Technologies Corporation 90 CHAPTER 7 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 need not be specified; the minimum length will automatically be used. Prototype void GUI_DispDecMin(I32 v); Parameter v Meaning Value to display. Minimum: -2147483648 (= -2^31); maximum 2147483647 (= 2^31 -1). Maximum no. of digits displayed is 9. Additional information 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. 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 Meaning Value to display. Minimum: -2147483648 (= -2^31); maximum: 2147483647 (= 2^31 -1). No. of digits to display (max. 9). No. of digits to show to right of decimal point. Additional information Watch the maximum number of 9 characters (including sign and decimal point). 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). User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 91 Prototype void DispDecSpace(I32 v, U8 MaxDigits); Parameter v MaxDigits Meaning Value to display. Minimum: -2147483648 (= -2^31); maximum: 2147483647 (= 2^31 -1). No. of digits to display, including leading spaces. Maximum no. of digits displayed is 9 (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 v Len Meaning Value to display. Minimum: -2147483648 (= -2^31); maximum: 2147483647 (= 2^31 -1). No. of digits to display (max. 9). 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() 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. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 92 CHAPTER 7 Displaying Values Prototype void GUI_DispSDecShift(I32 v, U8 Len, U8 Shift); Parameter v Len Shift Meaning Value to display. Minimum: -2147483648 (= -2^31); maximum: 2147483647 (= 2^31 -1). No. of digits to display (max. 9). 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 7.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 v Len Meaning Value to display. Minimum 1.2 E-38; maximum 3.4 E38. No. of digits to display (max. 9). Additional information Leading zeros are suppressed. The decimal point counts as one character. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 93 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(); } 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. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 94 CHAPTER 7 Displaying Values Prototype void GUI_DispFloatFix (float v, char Len, char Decs); Parameter v Len Decs Meaning Value to display. Minimum 1.2 E-38; maximum 3.4 E38. No. of digits to display (max. 9). 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 v Fract Meaning Value to display. Minimum 1.2 E-38; maximum 3.4 E38. 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. 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 Meaning Value to display. Minimum 1.2 E-38; maximum 3.4 E38. No. of digits to display (max. 9). No. of digits to show to right of decimal point. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 95 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 v Fract Meaning Value to display. Minimum 1.2 E-38; maximum 3.4 E38. 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. 7.4 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 Meaning 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); User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 96 CHAPTER 7 Displaying Values 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 Meaning v x y Len 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() 7.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 Value to display, 16-bit. No. of digits to display. Meaning Additional information As with decimal and binary values, the least significant bit is rightmost. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 97 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 Meaning 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() 7.6 Version of µC/GUI GUI_GetVersionString() Description Returns a string containing the current version of µC/GUI 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 μC/GUI © 2002-2006 Micrium Technologies Corporation 98 CHAPTER 7 Displaying Values User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 99 Chapter 8 2-D Graphic Library µC/GUI contains a complete 2-D graphic library which should be sufficient for most applications. The routines supplied with µC/GUI can be used with or without clipping (please refer to Chapter 15: "The Window Manager") and are based on fast and efficient algorithms. Currently, only the DrawArc() function requires floating-point calculations. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 100 CHAPTER 8 2-D Graphic Library 8.1 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 GUI_GetDrawMode() GUI_SetDrawMode() GUI_GetClientRect() GUI_ClearRect() GUI_DrawPixel() GUI_DrawPoint() GUI_DrawRect() GUI_DrawRectEx() GUI_FillRect() GUI_FillRectEx() GUI_InvertRect() GUI_DrawBitmap() GUI_DrawBitmapEx() GUI_DrawBitmapExp() GUI_DrawBitmapMag() GUI_DrawHLine() GUI_DrawLine() GUI_DrawLineRel() GUI_DrawLineTo() GUI_DrawPolyLine() GUI_DrawVLine() GUI_GetLineStyle() GUI_MoveRel() GUI_MoveTo() GUI_SetLineStyle() GUI_DrawPolygon() GUI_EnlargePolygon() GUI_FillPolygon() GUI_MagnifyPolygon() GUI_RotatePolygon() GUI_DrawCircle() GUI_FillCircle() Explanation Drawing modes Returns the current drawing mode Sets the drawing mode. Query current client rectangle Returns the current available drawing area Basic drawing routines Fills a rectangular area with the background color. Draws a single pixel. Draws a point. Draws a rectangle. Draws a rectangle. Draws a filled rectangle. Draws a filled rectangle. Invert a rectangular area. Drawing bitmaps Draws a bitmap. Draws a scaled bitmap. Draws a bitmap using additional parameters. Draws a magnified bitmap. Drawing lines Draws a horizontal line. Draws a line from a specified startpoint to a specified endpoint (absolute coordinates). Draws a line from the current position to an endpoint specified by Xand Y-distances (relative coordinates). Draws a line from the current position to a specified endpoint. 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 Draws the outline of a polygon. Enlarges a polygon. Draws a filled polygon. Magnifys a polygon. Rotates a polygon by a specified angle. Drawing circles Draws the outline of a a circle. Draws a filled circle. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 101 Routine GUI_DrawEllipse() GUI_FillEllipse() GUI_DrawArc() GUI_DrawGraph() GUI_RestoreContext() GUI_SaveContext() GUI_SetClipRect() Explanation Drawing ellipses Draws the outline of an ellipse. Draws a filled ellipse. Drawing arcs Draws an arc. Drawing a graph Draws a graph. Saving and restoring the GUI-context Restores the GUI-context. Saves the GUI-context. Clipping Sets the rectangle used for clipping 8.2 Drawing modes µC/GUI 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 µC/GUI 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. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 102 CHAPTER 8 2-D Graphic Library Additional information For details about drawing modes please refer to the function GUI_SetDrawMode(). GUI_SetDrawMode() Description Selects the specified drawing mode. Prototype GUI_DRAWMODE GUI_SetDrawMode(GUI_DRAWMODE mode); Parameter mode Meaning Drawing mode to set. May be a value returned by any routine which sets the drawing mode or one of the constants below. NORMAL XOR Permitted values for parameter mode Default: Draws points, lines, areas, bitmaps. 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); User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 103 Screen shot of above example 8.3 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 Meaning pRect Pointer to GUI_RECT-structure to store result. 8.4 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 Upper left X-position. Upper left Y-position. Lower right X-position. Lower right Y-position. Meaning User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 104 CHAPTER 8 2-D Graphic Library Related topics GUI_InvertRect(), GUI_FillRect() GUI_DrawPixel() Description Draws a pixel at a specified position in the current window. Prototype void GUI_DrawPixel(int x, int y); Parameter x X-position of pixel. y Y-position of pixel. Meaning 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 X-position of point. Y-position of point. Meaning Related topics GUI_DrawPixel() 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 Upper left X-position. Upper left Y-position. Lower right X-position. Lower right Y-position. Meaning User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 105 GUI_DrawRectEx() Description Draws a rectangle at a specified position in the current window. Prototype void GUI_DrawRectEx(const GUI_RECT *pRect); Parameter Meaning pRect Pointer to a GUI_RECT-structure containing the coordinates of the rectangle 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 Upper left X-position. Upper left Y-position. Lower right X-position. Lower right Y-position. Meaning 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 rectangular area at a specified position in the current window. Prototype void GUI_FillRectEx (const GUI_RECT* pRect); Parameter Meaning pRect Pointer to a GUI_RECT-structure containing the coordinates of the rectangle GUI_InvertRect() Description Draws an inverted rectangular area at a specified position in the current window. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 106 CHAPTER 8 Prototype void GUI_InvertRect(int x0, int y0, int x1, int y1); Parameter x0 Upper left X-position. y0 Upper left Y-position. x1 Lower right X-position. y1 Lower right Y-position. Related topics GUI_FillRect(), GUI_ClearRect() Meaning 2-D Graphic Library 8.5 Drawing bitmaps 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 Meaning 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 bitmap data must be defined pixel by pixel. Every pixel is equivalent to one bit. The most significant bit (msb) defines the first pixel; the picture data is interpreted as bitstream starting with the 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, please refer to Chapter 11: "Bitmap Converter". Example extern const GUI_BITMAP bmMicriumLogo; /* declare external Bitmap */ void main() { GUI_Init(); GUI_DrawBitmap(&bmMicriumLogo,45,20); } User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 107 Screen shot of above example GUI_DrawBitmapExp() Description Same function as GUI_DrawBitmap(), but with additional parameters. Prototype void GUI_DrawBitmapExp(int x0, int y0, int XSize, int YSize, int XMul, int YMul, int BitsPerPixel, int BytesPerLine, const U8* pData, const GUI_LOGPALETTE* pPal); Parameter Meaning x0 y0 Xsize Ysize XMUL YMul BitsPerPixel BytesPerLine pData pPal 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. Number of pixels in horizontal direction. Valid range: 1... 255. Number of pixels in vertical direction. Valid range: 1... 255. Scale factor of X-direction. Scale factor of Y-direction. Number of bits per pixel. Number of bytes per line of the image. Pointer to the actual image, the data that defines what the bitmap looks like. Pointer to a GUI_LOGPALETTE structure. 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* pBitmap, int x0, int y0, int xCenter, int yCenter, int xMag, int yMag); Parameter pBM x0 y0 xCenter Meaning Pointer to the bitmap to display. X-position of the anker point in the display. Y-position of the anker point in the display. X-positiom of the anker point in the bitmap. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 108 CHAPTER 8 2-D Graphic Library Parameter Meaning yCenter xMag yMag Y-positiom of the anker 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_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 Meaning pBM x0 y0 XMul YMul 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. GUI_DrawStreamedBitmap() Description Draws a bitmap from a data bitmap data stream. Prototype void GUI_DrawStreamedBitmap(const GUI_BITMAP_STREAM* pBMH, int x, int y); Parameter Meaning pBMH x y 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 (Chapter 11) to create bitmap data streams. The format of these streams is not the same as the format of a .bmp file. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 109 8.6 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 Y-position. X-starting position. X-end position. Meaning 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 X-starting position. Y-starting position. X-end position. Y-end position. Meaning 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). User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 110 CHAPTER 8 2-D Graphic Library Prototype void GUI_DrawLineRel(int dx, int dy); Parameter Meaning dx Distance in X-direction to end of line to draw. dy Distance in Y-direction end of line to draw. 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 X-end position. Y-end position. Meaning 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 Meaning 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 X-position. Y-starting position. Y-end position. Meaning User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 111 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. 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 Distance to move in X. Distance to move in Y. Meaning 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 New position in X. New position in Y. Meaning GUI_SetLineStyle() Description Sets the current line style used by the function GUI_DrawLine. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 112 CHAPTER 8 2-D Graphic Library Prototype U8 GUI_SetLineStyle(U8 LineStyle); Parameter LineStyle Meaning New line style to be used (see table below). Permitted values for parameter LineStyle GUI_LS_SOLID GUI_LS_DASH GUI_LS_DOT GUI_LS_DASHDOT GUI_LS_DASHDOTDOT Lines would be drawn solid (default). Lines would be drawn dashed. Lines would be drawn dotted. Lines would be drawn alternating with dashes and dots. 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. 8.7 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 Meaning 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. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 113 Prototype void GUI_EnlargePolygon(GUI_POINT* pDest, const GUI_POINT* pSrc, int NumPoints, int Len); Parameter pDest pSrc NumPoints Len Meaning 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. Example #define countof(Array) (sizeof(Array) / sizeof(Array[0])) const GUI_POINT aPoints[] = { { 0, 20}, { 40, 20}, { 20, 0} }; GUI_POINT aEnlargedPoints[countof(aPoints)]; void Sample(void) { int i; GUI_Clear(); GUI_SetDrawMode(GUI_DM_XOR); GUI_FillPolygon(aPoints, countof(aPoints), 140, 110); for (i = 1; i < 10; i++) { GUI_EnlargePolygon(aEnlargedPoints, aPoints, countof(aPoints), i * 5); GUI_FillPolygon(aEnlargedPoints, 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. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 114 CHAPTER 8 2-D Graphic Library Prototype void GUI_FillPolygon(const GUI_POINT* pPoint, int NumPoints, int x, int y); Parameter Meaning pPoint NumPoints x y 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. Prototype void GUI_MagnifyPolygon(GUI_POINT* pDest, const GUI_POINT* pSrc, int NumPoints, int Mag); Parameter pDest pSrc NumPoints Mag Meaning 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. Whereas setting the parameter Len to 1 will enlarge the polygon by one pixel on all sides, setting the parameter Mag to 1 will have no effect. Example #define countof(Array) (sizeof(Array) / sizeof(Array[0])) const GUI_POINT aPoints[] = { { 0, 20}, { 40, 20}, { 20, 0} }; GUI_POINT aMagnifiedPoints[countof(aPoints)]; User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 115 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, countof(aPoints), Mag); for (i = Count; i > 0; i--, x += 40 * Mag) { GUI_FillPolygon(aMagnifiedPoints, 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, int NumPoints, float Angle); Parameter pDest pSrc NumPoints Angle Meaning 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. Example The following example shows how to draw a polygon. It is available as 2DGL_DrawPolygon.c in the samples shipped with µC/GUI. /********************************************************************* * Micrium Inc. * * Empowering embedded systems * * * User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 116 CHAPTER 8 2-D Graphic Library * µC/GUI sample code * * * ********************************************************************** ---------------------------------------------------------------------- File : 2DGL_DrawPolygon.c Purpose : Example for drawing a polygon ---------------------------------------------------------------------- */ #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); } User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 117 Screen shot of above example 8.8 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 Meaning 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++) GUI_DrawCircle(120,60,i); } User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 118 CHAPTER 8 Screen shot of above example 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 Meaning 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 8.9 Drawing ellipses GUI_DrawEllipse() Description Draws the outline of an ellipse of specified dimensions, at a specified position in the current window. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 119 Prototype void GUI_DrawEllipse (int x0, int y0, int rx, int ry); Parameter x0 y0 rx ry Meaning 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. X-radius of the ellipse (half the diameter). Minimum: 0; maximum: 180. 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. 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 rx ry Meaning 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. X-radius of the ellipse (half the diameter). Minimum: 0; maximum: 180. 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); User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 120 CHAPTER 8 Screen shot of above example 2-D Graphic Library 8.10 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 GL_DrawArc (int xCenter, int yCenter, int rx, int ry, int a0, int a1); Parameter xCenter yCenter rx ry a0 a1 Meaning 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 ); User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 121 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); } } } Screen shot of above example 8.11 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 Meaning 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. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 122 CHAPTER 8 2-D Graphic Library 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 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 8.12 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 Meaning 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 usefull 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) User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 123 Prototype void GUI_SaveContext(GUI_CONTEXT* pContext); Parameter pContext Meaning Pointer to a GUI_CONTEXT structure for saving the current context. 8.13 Clipping GUI_SetClipRect() Description Sets the clipping rectangle used for limiting the output. Prototype void GUI_SetClipRect(const GUI_RECT* pRect); Parameter pRect Meaning 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 usefull 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. Sample The following sample 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 μC/GUI © 2002-2006 Micrium Technologies Corporation 124 CHAPTER 8 2-D Graphic Library User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 125 Chapter 9 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 please refer to chapter 10, "Bitmap converter". If the application needs to display images not known at compile time, the image needs to be available in a graphic file format support by µC/GUI. 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 availalble memory is less than the size of the image file. µC/GUI currently supports BMP, JPEG and GIF file formats. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 126 CHAPTER 9 Displaying bitmap files 9.1 BMP file support Although bitmaps which can be used with µC/GUI are normally defined as GUI_BITMAP structures in "C", 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 (i.e. a company logo) it is much more efficient to define them as GUI_BITMAP structures that can be used directly by µC/GUI. This may be easily done with the Bitmap Converter. 9.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 no yes no no yes yes 9.1.2 BMP file API The table below lists the available BMP file related routines in alphabetical order. Detailed descriptions follows: Routine Explanation GUI_BMP_Draw() GUI_BMP_DrawEx() GUI_BMP_DrawScaled() GUI_BMP_DrawScaledEx() GUI_BMP_GetXSize() GUI_BMP_GetXSizeEx() GUI_BMP_GetYSize() GUI_BMP_GetYSizeEx() GUI_BMP_Serialize() GUI_BMP_SerializeEx() Draws a bitmap 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. Draws a BMP file with scaling which needs not to be loaded into memory. Returns the X-size of a bitmap loaded into memory. Returns the X-size of a BMP file which needs not to be loaded into memory. Returns the Y-size of a bitmap loaded into memory. Returns the Y-size of a BMP file which needs not to be loaded into memory. Creates a BMP-file. Creates a BMP-file from the given rectangle. GUI_BMP_Draw() Description Draws a Windows .bmp file, which has been loaded into memory, at a specified position in the current window. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 127 Prototype int GUI_BMP_Draw(const void* pBMP, int x0, int y0); Parameter pBMP x0 y0 Meaning 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 There are different types of .bmp files. Supported types are 1/4/8/24 bpp files. These are the most common file types; other types and compression are not supported. The samples shipped with µC/GUI contain an example that uses this function to show all files in the Windows system directory. 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_BMP_GET_DATA_FUNC * fpGetData, void * p, int x0, int y0); Parameter fpGetData p x0 y0 Meaning Pointer to a function which is called by the BMP routine for getting data. Void pointer passed to the function pointed by fpGetData. 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 fpGetData to read the data. Prototype of ’GetData’ function int APP_GetData(void * p, int NumBytesReq, const U8 ** ppData, unsigned StartOfFile); Description of ’GetData’ function The 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. Example The following code excerpt shows how to use the function: User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 128 CHAPTER 9 Displaying bitmap files static char acBuffer[0x200]; int APP_GetData(void * p, int NumBytesReq, const U8 ** ppData, unsigned StartOfFile){ DWORD NumBytesRead; HANDLE * phFile; phFile = (HANDLE *)p; if (StartOfFile) { /* Reset file pointer to the beginning of the file */ .../* TBD */ } /* Read BMP file data into buffer */ .../* TBD */ return NumBytesRead; } void DrawBMP(HANDLE hFile, int x, int y) { GUI_BMP_DrawEx(APP_GetData, (void *)&hFile, x, y); } 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 Meaning 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 shrinked 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_BMP_GET_DATA_FUNC * fpGetData, void * p, User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 129 int x0, int y0, int Num, int Denom); Parameter fpGetData p x0 y0 Num Denom Meaning Pointer to a function which is called by the GUI for getting data. Void pointer passed to the function pointed by fpGetData. 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 shrinked to 2/3 of size the parameter Num should be 2 and Denom should be 3. For more details please refer to the function GUI_BMP_DrawEx() explained earlier in this chapter. 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* pBMP); Parameter Meaning pBMP 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_BMP_GET_DATA_FUNC * fpGetData, void * p); Parameter fpGetData p Meaning Pointer to a function which is called by the GUI for getting data. Void pointer passed to the function pointed by fpGetData. Return value X-size of the bitmap. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 130 CHAPTER 9 Displaying bitmap files 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* pBMP);; Parameter Meaning pBMP Pointer to the start of the memory area in which the .bmp file resides. Return value Y-size of the bitmap. 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_BMP_GET_DATA_FUNC * fpGetData, void * p); Parameter Meaning fpGetData Pointer to a function which is called by the GUI for getting data. p Void pointer passed to the function pointed by fpGetData. 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 Meaning Pointer to serialization function Pointer to user defined data passed to serialization function Additional information The following sample 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); User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 131 } 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(); } 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 Meaning 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 (See GUI_BMP_Serialize) User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 132 CHAPTER 9 Displaying bitmap files 9.2 JPEG file support The µC/GUI JPEG file support can be found in the GUI\JPEG subdirectory and supports JPEG image decompression. 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. Please note, that the µC/GUI JPEG file support is only available in the color version. The JPEG package is not shipped with monochrome versions. 9.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 to the free JPEG software. (Since arithmetic coding provides only a marginal gain over the unpatented Huffman mode, it is unlikely that very many implementations will support it.) So far as we are aware, there are no patent restrictions on the remaining code. The library does cot contain provision for supporting the hierarchical or lossless processes defined in the standard. 9.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 µC/GUI. 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. Sample The following sample 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); ... } User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 133 9.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 please take a look to the memory device chapter. 9.2.4 Memory usage The JPEG decompression uses 38Kb RAM for decompression independent of the image size and a size dependent amount of bytes. The RAM requirement can be calculated as follows: Approximate RAM requirement = X-Size of image * 60 + 38Kb 9.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. 9.2.6 JPEG file API The table below lists the available JPEG file related routines in alphabetical order. Detailed descriptions follows: Routine Explanation GUI_JPEG_Draw() Draws a JPEG file which has been loaded into memory. GUI_JPEG_DrawEx() Draws a JPEG file which needs not to be loaded into memory. GUI_JPEG_DrawScaled() Draws a JPEG file with scaling which has been loaded into memory. GUI_JPEG_DrawScaledEx() GUI_JPEG_GetInfo() GUI_JPEG_GetInfoEx() Draws a JPEG file with scaling which needs not to be loaded into memory. Fills a GUI_JPEG_INFO structure from a JPEG file which has been loaded into memory. Fills a GUI_JPEG_INFO structure from a JPEG file which needs not to be loaded into memory. GUI_JPEG_Draw() Description Draws a .jpeg file, which has been loaded into memory, at a specified position in the current window. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 134 CHAPTER 9 Displaying bitmap files Prototype int GUI_JPEG_Draw(const void * pFileData, int DataSize, int x0, int y0); Parameter Meaning pFileData DataSize x0 y0 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 if success, nonzero if the function fails. (The current implementation always returns 0) Additional information The sample folder contains the sample 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_JPEG_GET_DATA_FUNC * fpGetData, void * p, int x0, int y0); Parameter fpGetData p x0 y0 Meaning Pointer to a function which is called by the JPEG routine for getting data. Void pointer passed to the function pointed by fpGetData. 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 if 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 for loading the whole file into memory. The JPEG library then calls the function pointed by the parameter fpGetData for getting data on demand. Prototype of ’GetData’ function int APP_GetData(void * p, int NumBytesReq, const U8 ** ppData, unsigned StartOfFile); Parameter p Application defined void pointer. Meaning User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 135 Parameter Meaning NumBytesReq Number of requested bytes. ppData Pointer to data pointer. This pointer should be set to a valid location. StartOfFile If this flag is 1, the data pointer should be set to the beginning of the data stream. Return value of ’GetData’ function The 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. Example The following code excerpt will show how to use the function: static char acBuffer[0x200]; int APP_GetData(void * p, int NumBytesReq, const U8 ** ppData, unsigned StartOfFile){ int NumBytes; HANDLE hFile; hFile = *(HANDLE *)p; if (StartOfFile) { /* Reset file pointer to the beginning of the file */ .../* TBD */ } /* Calculate number of bytes to read */ NumBytes = (sizeof(acBuffer) < NumBytesReq) ? sizeof(acBuffer) : NumBytesReq; /* Read JPEG file data into buffer */ .../* TBD */ return NumBytes; } void DrawJPEG(HANDLE hFile, int x, int y) { GUI_JPEG_DrawEx(APP_GetData, (void *)&hFile, x, y); } The sample folder contains the sample 2DGL_DrawJPGScaled.c which shows how to use a ’GetData’ function. 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 Meaning 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 if success, nonzero if the function fails. (The current implementation always returns 0) User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 136 CHAPTER 9 Displaying bitmap files Additional information The function scales the image by building a fraction with the given numerator and denominator. If for example an image should be shrinked to 2/3 of size the parameter Num should be 2 and Denom should be 3. The sample folder contains the sample 2DGL_DrawJPGScaled.c which shows how to draw scaled JPEGs. 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_JPEG_GET_DATA_FUNC * fpGetData, void * p, int x0, int y0, int Num, int Denom); Parameter fpGetData p x0 y0 Num Denom Meaning Pointer to a function which is called by the JPEG routine for getting data. Void pointer passed to the function pointed by fpGetData. 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 if 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 shrinked to 2/3 of size the parameter Num should be 2 and Denom should be 3. For more details please refer to the function GUI_JPEG_DrawEx() explained earlier in this chapter. The sample folder contains the sample 2DGL_DrawJPGScaled.c which shows how to use the function. GUI_JPEG_GetInfo() Description Fills a GUI_JPEG_INFO structure with information about the given image. Prototype int GUI_JPEG_GetInfo(const void * pFileData, int DataSize, User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 137 GUI_JPEG_INFO* pInfo); Parameter pFileData DataSize pInfo Meaning Pointer to the start of the memory area in which the .jpeg file resides. Number of bytes of the .jpeg file. Pointer to a GUI_JPEG_INFO structure to be filled by the function. Return value Zero if success, nonzero if the function fails. (The current implementation always returns 0) Elements of GUI_JPEG_INFO Data type Element Meaning int int XSize YSize Pixel size in X of the image. Pixel size in Y of the image. Additional information The sample folder contains the sample 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_JPEG_GET_DATA_FUNC * fpGetData, void * p, GUI_JPEG_INFO * pInfo); Parameter fpGetData p pInfo Meaning Pointer to a function which is called by the JPEG routine for getting data. Void pointer passed to the function pointed by fpGetData. Pointer to a GUI_JPEG_INFO structure to be filled by the function. Return value Zero if success, nonzero if the function fails. (The current implementation always returns 0) Additional information For more details about the function and the parameters fpGetData and p please refer to the function GUI_JPEG_GetInfo() and GUI_JPEG_DrawEx() explained earlier in this chapter. The sample folder contains the sample 2DGL_DrawJPGScaled.c which shows how to use the function. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 138 CHAPTER 9 Displaying bitmap files 9.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. The µC/GUI GIF file support is limited to only one image per file. Unsupported data like raw text or application specific data will be ignored. 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. 9.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’. 9.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 please take a look to the memory device chapter. 9.3.3 Memory usage The GIF decompression routine of µC/GUI needs about 16Kb static work area for decompression. 9.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 a GIF file which has been loaded into memory. GUI_GIF_DrawEx() Draws the given sub image of a GIF file which has been 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. 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. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 139 Routine GUI_GIF_GetImageInfoEx() GUI_GIF_GetInfo() GUI_GIF_GetInfoEx() GUI_GIF_GetXSize() GUI_GIF_GetXSizeEx() GUI_GIF_GetYSize() GUI_GIF_GetYSizeEx() Explanation Returns information about the given sub image of a GIF file which needs not to be loaded into memory. Returns a GUI_GIF_IMAGE_INFO structure used for drawing animated GIFs. Returns information about a GIF file which needs not to be loaded into memory. Returns the X-size of a bitmap loaded into memory. Returns the X-size of a bitmap which needs not to be loaded into memory. Returns the Y-size of a bitmap loaded into memory. 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 Meaning 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. 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_GIF_GET_DATA_FUNC * fpGetData, void * p, int x0, int y0); Parameter fpGetData p x0 y0 Meaning Pointer to a function which is called by the GUI for getting data. Void pointer passed to the function pointed by fpGetData. 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. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 140 CHAPTER 9 Displaying bitmap files Return value 0 on success, != 0 if the function fails. 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 fpGetData to read the data. Prototype of ’GetData’ function int APP_GetData(void * p, int NumBytesReq, const U8 ** ppData, unsigned StartOfFile); Parameter p NumBytesReq ppData StartOfFile Meaning Application defined void pointer. Number of requested bytes. Pointer to data pointer. This pointer should be set to a valid location. If this flag is 1, the data pointer should be set to the beginning of the data stream. Return value of ’GetData’ function The 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. Example The following code excerpt shows how to use the function: static char acBuffer[0x200]; int APP_GetData(void * p, int NumBytesReq, const U8 ** ppData, unsigned StartOfFile){ int NumBytes; HANDLE hFile; hFile = *(HANDLE *)p; if (StartOfFile) { /* Reset file pointer to the beginning of the file */ .../* TBD */ } /* Calculate number of bytes to read */ NumBytes = (sizeof(acBuffer) < NumBytesReq) ? sizeof(acBuffer) : NumBytesReq; /* Read JPEG file data into buffer */ .../* TBD */ return NumBytes; } void DrawJPEG(HANDLE hFile, int x, int y) { GUI_JPEG_DrawEx(APP_GetData, (void *)&hFile, x, y); } 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, User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 141 int x0, int y0, int Index); Parameter pGIF NumBytes x0 y0 Index Meaning 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. Zerobased 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. 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_GIF_GET_DATA_FUNC * fpGetData, void * p, int x0, int y0, int Index); Parameter fpGetData p x0 y0 Index Meaning Pointer to a function which is called by the GUI for getting data. Void pointer passed to the function pointed by fpGetData. 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. Zerobased 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 fpGetData to read the data. For more details please refer to the function GUI_GIF_DrawEx() explained earlier in this chapter. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 142 CHAPTER 9 Displaying bitmap files 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 * pFileData, int x0, int y0, int Index, int Num, int Denom); Parameter pFileData DataSize x0 y0 Index Num Denom Meaning 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. Zerobased 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 shrinked to 2/3 of size the parameter Num should be 2 and Denom should be 3. 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_GIF_GET_DATA_FUNC * fpGetData, void * p, int x0, int y0, int Index, int Num, int Denom); Parameter fpGetData p x0 y0 Index Num Denom Meaning Pointer to a function which is called by the GUI for getting data. Void pointer passed to the function pointed by fpGetData. 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. Zerobased 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. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 143 Additional information The function scales the image by building a fraction with the given numerator and denominator. If for example an image should be shrinked 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 the GIF image. Prototype int GUI_GIF_GetComment(const void * pGIF, U32 NumBytes, U8 * pBuffer, int MaxSize, int Index); Parameter Meaning pGIF NumBytes pBuffer MaxSize Index 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. 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_GIF_GET_DATA_FUNC * fpGetData, void * p, U8 * pBuffer, int MaxSize, int Index); Parameter fpGetData p pBuffer MaxSize Index Meaning Pointer to a function which is called by the GUI for getting data. Void pointer passed to the function pointed by fpGetData. 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. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 144 CHAPTER 9 Displaying bitmap files Additional information For details please refer to the function GUI_GIF_GetComment(). GUI_GIF_GetImageInfo() Description Returns information about the given sub image. Prototype int GUI_GIF_GetImageInfo(const void * pGIF, U32 NumBytes, GUI_GIF_IMAGE_INFO * pInfo, int Index); Parameter Meaning pGIF NumBytes pInfo Index 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 Element Meaning int int int int int xPos yPos xSize ySize Delay 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. 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_GIF_GET_DATA_FUNC * fpGetData, void * p, GUI_GIF_IMAGE_INFO * pInfo, int Index); Parameter fpGetData p pInfo Index Meaning Pointer to a function which is called by the GUI for getting data. Void pointer passed to the function pointed by fpGetData. Pointer to a GUI_GIF_IMAGE_INFO structure which will be filled by the function. Zero based index of sub image. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 145 Return value 0 on success, != 0 on error. Additional information For more details please refer to the function GUI_GIF_GetImageInfo(). GUI_GIF_GetInfo() Description Returns an information structure of the given GIF image with information about the size and the number of images within the given file. Prototype int GUI_GIF_GetInfo(const void * pGIF, U32 NumBytes, GUI_GIF_INFO * pInfo); Parameter pGIF NumBytes pInfo Meaning 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 Meaning Pixel size in X of the image. Pixel size in Y of the image. Number of images in the file. 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_GIF_GET_DATA_FUNC * fpGetData, void * p, GUI_GIF_INFO * pInfo);; Parameter fpGetData p pInfo Meaning Pointer to a function which is called by the GUI for getting data. Void pointer passed to the function pointed by fpGetData. Pointer to a GUI_GIF_INFO structure which will be filled by this function. Return value 0 on success, != 0 on error. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 146 CHAPTER 9 Displaying bitmap files Elements of GUI_GIF_INFO Data type int int int Element XSize YSize NumImages Meaning 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 Meaning pGIF 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_GIF_GET_DATA_FUNC * fpGetData, void * p); Parameter Meaning fpGetData Pointer to a function which is called by the GUI for getting data. p Void pointer passed to the function pointed by fpGetData. Return value X-size of the GIF image. 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 Meaning pGIF Pointer to the start of the memory area in which the .bmp file resides. Return value Y-size of the GIF image. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 147 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_GIF_GET_DATA_FUNC * fpGetData, void * p); Parameter fpGetData p Meaning Pointer to a function which is called by the GUI for getting data. Void pointer passed to the function pointed by fpGetData. Return value Y-size of the GIF image. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 148 CHAPTER 9 Displaying bitmap files User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 149 Chapter 10 Fonts The most common fonts are shipped with uC/GUI as standard fonts. In fact, you will probably find that these fonts are fully sufficient for your application. For detailed information on the individual fonts, please refer to the subchapter "Standard Fonts", which describes all fonts included with uC/GUI and shows all characters as they appear on the display. uC/GUI supports ASCII, ISO 8859-1 and Unicode. Usually, uC/GUI is compiled for 8bit 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. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 150 CHAPTER 10 Fonts 10.1 Font types The current µC/GUI version supports 5 types of fonts: • Monospaced bitmap fonts • Proportional bitmap fonts • Antialiased fonts with 2 bpp built-in antialiasing information • Antialiased fonts with 4 bpp built-in antialiasing information • Extended proportional bitmap fonts For more information on antialiased fonts, please refer to Chapter 22: "Antialiasing". 10.2 Font formats µC/GUI supports 3 kinds of font formats which are explained in the following. 10.2.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 µC/GUI as "C" file, object file or library. • The font file is linked with your application. • The font declaration is contained in the application. 10.2.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. For details about how to create system independent fonts please refer to the font converter documentation. 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). User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 151 10.2.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. Contrary to other fonts, XBF fonts do not have to reside in memory when they are used, whereas all other kinds of µC/GUI fonts need to reside completely in memory. The XBF font file can remain on any external media when 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 system 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. • 10.3 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 GUI_GetFont() GUI_SetFont() GUI_SIF_CreateFont() GUI_SIF_DeleteFont() GUI_XBF_CreateFont() GUI_XBF_DeleteFont() GUI_GetCharDistX() GUI_GetFontDistY() GUI_GetFontInfo() GUI_GetFontSizeY() GUI_GetLeadingBlankCols() GUI_GetStringDistX() GUI_GetTextExtend GUI_GetTrailingBlankCols() GUI_GetYDistOfFont() GUI_GetYSizeOfFont() GUI_IsInFont() Explanation Selection of a font Returns a pointer to the currently selected font. Sets the current font. Creates and selects a font by passing a pointer to system independent font data. Deletes a font created by GUI_SIF_CreateFont() Creates and selects a font by passing a pointer to a callback function, which is responsible for getting data from the XBF font file. Deletes a font created by GUI_XBF_CreateFont() Font-related functions Returns the width in pixels (X-size) of a specified character in the current 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 character. Returns the Y-spacing of a particular font. Returns the Y-size of a particular font. Evaluates whether a specified character is in a particular font. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 152 CHAPTER 10 Fonts 10.4 Selection of a font uC/GUI offers different fonts, one of which is always selected. This selection can be changed by calling the function GUI_SetFont(), which selects 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. GUI_GetFont() Description Returns a pointer to the currently selected font. Prototype const GUI_FONT * GUI_GetFont(void) GUI_SetFont() Description Sets the font to be used for text output. Prototype const GUI_FONT * GUI_SetFont(const GUI_FONT * pNewFont); Parameter pFont Meaning Pointer to the font to be selected and used. Return value Returns a pointer to the previously selected font so that it may be restored at a later point. Examples Displays sample text in 3 different sizes, restoring the former font afterwards: void DispText(void) { const GUI_FONT GUI_FLASH* OldFont=GUI_SetFont(&GUI_Font8x16); 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 font } Screen shot of above example: Displays text and value in different fonts: User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 153 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: 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 Meaning 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 A non antialiased 1bpp proportional font should be used. 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_EXT Should be used if the parameter pFont points to a non antialiased extended proportional font. Additional Information Contrary to the uC/GUI 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 please refer to the font converter documentation. When using this function uC/GUI 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 μC/GUI © 2002-2006 Micrium Technologies Corporation 154 CHAPTER 10 Fonts } } GUI_SIF_DeleteFont() Description Deletes a font pointed by the parameter pFont. Prototype void GUI_SIF_DeleteFont(GUI_FONT * pFont); Parameter pFont Pointer to the font to be deleted. Meaning 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); 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 * pFont, GUI_XBF_DATA * pXBF_Data, const GUI_XBF_TYPE * pFontType, GUI_XBF_GET_DATA_FUNC * pfGetData, void * pVoid); Parameter pFont pXBF_Data pFontType pfGetData pVoid Meaning 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. Pointer to a callback function which is responsible for getting data from the font file. Application defined pointer passed to the ’GetData’ callback function. Permitted values for element pFontType GUI_XBF_TYPE_PROP Should be used if a non antialiased proportional font should be created. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 155 Additional Information Contrary to the µC/GUI standard fonts, which must be compiled and linked with the application program, external binary fonts (XBF) are binary data blocks containing the font information. The font converter can be used to create XBF files. This tool is not part of the basic package. A short description of the font converter follows later in this chapter. 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 µC/GUI fonts need to reside completely in memory. The XBF font file can remain on any external media during 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 system with little memory. 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. These structures will be filled by the function with font information. It is required, that the contents of this structures remain valid during the use of the font. Because the function does not know what kind of XBF font should be created, the parameter pFontType is used to tell the function the type of the font to be created. This has been done to avoid linkage of code which is not required. Example static GUI_FONT Font; /* GUI_FONT structure in RAM */ static GUI_XBF_DATA XBF_Data; /* GUI_XBF_DATA structure in RAM */ static int _cbGetData(U32 Off, U16 NumBytes, void * pVoid, void * pBuffer) { /* May use the pVoid pointer 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, /* Pointer to GUI_FONT structure */ &XBF_Data, /* Pointer to GUI_XBF_DATA structure */ GUI_XBF_TYPE_PROP, /* Font type to be created */ _cbGetData, /* Pointer to callback function */ pVoid); /* 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 Pointer to the font to be deleted. Meaning User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 156 CHAPTER 10 Fonts Additional Information After using a font created with GUI_XBF_CreateFont() the font should be deleted if not used anymore. 10.5 Font-related functions GUI_GetCharDistX() Description Returns the width in pixels (X-size) used to display a specified character in the currently selected font. Prototype int GUI_GetCharDistX(U16 c); Parameter c Meaning Character to calculate width from. 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 Meaning 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 User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 157 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); 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 c Sample Character to be used. Meaning 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. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 158 CHAPTER 10 Fonts Prototype int GUI_GetStringDistX(const char GUI_FAR *s); Parameter s Pointer to the string. Meaning 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 Meaning Pointer to GUI_RECT-structure to store result. Pointer to the string. Number of characters of the string. 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 c Sample Character to be used. Meaning 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 Pointer to the font. Meaning User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 159 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 Pointer to the font. Meaning Additional information (see GUI_GetFontSizeY()) GUI_IsInFont() Description Evaluates whether or not a particular font contains a specified character. Prototype char GUI_IsInFont(const GUI_FONT*pFont, U16 c); Parameter pFont c Pointer to the font. Character to be searched for. Meaning 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'"); } User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 160 CHAPTER 10 Fonts 10.6 Character sets 10.6.1 ASCII uC/GUI supports the full set of ASCII characters. These are the following 96 characters from 32 to 127: Hex 0 1 2 3 4 5 6 7 8 9 A B C D E F 2x ! "# $ % & '( ) * + , - . / 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 [ \ ] ^ _ 6x `a b c d e f g h i j k l m n o 7x p q r s t u v w x y z { | } ~ 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. 10.6.2 ISO 8859-1 Western Latin character set uC/GUI supports the ISO 8859-1, which defines characters as listed below: Code 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 Description non-breaking space inverted exclamation cent sign pound sterling general currency sign yen sign broken vertical bar section sign umlaut (dieresis) copyright feminine ordinal left angle quote, guillemotleft not sign soft hyphen registered trademark macron accent degree sign plus or minus superscript two superscript three acute accent micro sign paragraph sign middle dot Char ¡ ¢ £ ¤ ¥ ¦ § ¨ © ª « ¬ ® ¯ ° ± ² ³ ´ µ ¶ · User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation Code 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 Description cedilla superscript one masculine ordinal right angle quote, guillemot right fraction one-fourth fraction one-half fraction three-fourth inverted question mark capital A, grave accent capital A, acute accent capital A, circumflex accent capital A, tilde capital A, dieresis or umlaut mark capital A, ring capital A, diphthong (ligature) capital C, cedilla capital E, grave accent capital E, acute accent capital E, circumflex accent capital E, dieresis or umlaut mark capital I, grave accent capital I, acute accent capital I, circumflex accent capital I, dieresis or umlaut mark Eth, Icelandic N, tilde capital O, grave accent capital O, acute accent capital O, circumflex accent capital O, tilde capital O, dieresis or umlaut mark multiply sign capital O, slash capital U, grave accent capital U, acute accent capital U, circumflex accent capital U, dieresis or umlaut mark capital Y, acute accent THORN, Icelandic sharp s, German (s-z ligature) small a, grave accent small a, acute accent small a, circumflex accent small a, tilde small a, dieresis or umlaut mark small a, ring small ae diphthong (ligature) cedilla small e, grave accent small e, acute accent small e, circumflex accent small e, dieresis or umlaut mark small i, grave accent User's & reference manual for μC/GUI 161 Char ¸ ¹ º » ¼ ½ ¾ ¿ À Á Â Ã Ä Å Æ Ç È É Ê Ë Ì Í Î Ï Ð Ñ Ò Ó Ô Õ Ö × Ø Ù Ú Û Ü Ý Þ ß à á â ã ä å æ ç è é ê ë ì © 2002-2006 Micrium Technologies Corporation 162 CHAPTER 10 Fonts Code 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 Description small i, acute accent small i, circumflex accent small i, dieresis or umlaut mark small eth, Icelandic small n, tilde small o, grave accent small o, acute accent small o, circumflex accent small o, tilde small o, dieresis or umlaut mark division sign small o, slash small u, grave accent small u, acute accent small u, circumflex accent small u, dieresis or umlaut mark small y, acute accent small thorn, Icelandic small y, dieresis or umlaut mark Char í î ï ð ñ ò ó õ õ ö ÷ ø ù ú û ü ý þ ÿ 10.6.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 uC/ GUI. It is the responsibility of the user to define these additional characters. Please contact Micrium or your distributor, as we may already have the character set that you need. User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 163 10.7 Font converter Fonts which can be used with uC/GUI 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 uC/GUI on demand. The character codes 0x00 - 0x1F and 0x80 - 0x9F are disabled by default. The following is a sample 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 Micrium (info@micrium.com). 10.7.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: User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 164 CHAPTER 10 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; } Fonts User's & reference manual for μC/GUI © 2002-2006 Micrium Technologies Corporation 165 10.8 Standard fonts uC/GUI 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 uC/GUI fonts. 10.8.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[