APPLICATION NOTE

Atmel AVR1614: Widget Toolkit – Getting Started

Atmel Microcontrollers

Prerequisites

• Required knowledge • Basic knowledge of microcontrollers and the C programming language • Software prerequisites • Atmel® Studio 6 • Atmel Software Framework 3.3.0 or later • Hardware prerequisites • mXT143E Xplained evaluation board • Xplained series MCU evaluation board • Programmer/debugger: • Atmel AVR® JTAGICE 3 • Atmel AVR Dragon™ • Atmel AVR JTAGICE mkll • Atmel AVR ONE! • Estimated completion time • 2 hours

Introduction

The aim of this document is to introduce the Window system and Widget toolkit (WTK) which is distributed with the Atmel Software Framework. This application note is organized as a training which will go through: • The basics of setting up graphical widgets on a screen to make a graphical user interface (GUI) • How to get feedback when a user has interacted with a widget • How to draw custom graphical elements on the screen

8300B−AVR−07/2012

Table of Contents

1. Introduction to the Window system and widget toolkit ...... 3 1.1 Overview ...... 3 1.2 The Window system ...... 4 1.3 Event handling ...... 5 1.3.2 The draw event ...... 6 1.4 The Widget toolkit ...... 6 1.5 Window system event queue ...... 7 2. Training tasks ...... 7 2.1 Task 1: Getting started ...... 7 2.2 Task 2: Adding a button ...... 10 2.3 Task 3: Adding a basic frame ...... 10 2.4 Task 4: Connecting it all together ...... 11 3. Revision history ...... 12

Atmel AVR1614: Widget Toolkit – Getting Started [APPLICATION NOTE] 2 8300B−AVR−07/2012

1. Introduction to the Window system and widget toolkit

1.1 Overview The graphical display system consists of several layers of drivers which can be used in a graphical application. The available layers are illustrated in Figure 1-1.

Figure 1-1. Layers of the graphical display system.

Atmel AVR1614: Widget Toolkit – Getting Started [APPLICATION NOTE] 3 8300B−AVR−07/2012

1.2 The Window system The Window system is a module for organizing two-dimensional windows. The windows are organized in a tree structure where each window can have one parent and several children. The Window system also allows events to be queued and handled by the event handler of the affected windows. Table 1-1 shows the properties that define a window.

Table 1-1. Window properties.

Property Description Position and area/size The position on screen and size of the window. Relation to parent and children Windows are organized in a tree structure where they can have one parent, several siblings and several children. Visibility A window can be visible/mapped or invisible/unmapped on the screen. Background A background bitmap which can be either a solid color or a bitmap stored in either data or program memory. Window behavior flags Currently implemented behaviors are: • Raise on press: raises the window as the top child when a pointer event occurs within the window • Redraw parent: redraws parent when drawing a window, useful for transparent windows

Event handler Pointer to a function that handles events for the window.

The Window system can be used on its own or together with the Widget toolkit. Figure 1-2 shows the relations between windows that are used to represent some example widgets. The figure shows the top_child and next_sibling pointers. The parent and prev_sibling pointers, which just point in the opposite direction, are omitted to simplify the figure. The figure also illustrates how the position and size affects how the windows could be represented on a display.

Atmel AVR1614: Widget Toolkit – Getting Started [APPLICATION NOTE] 4 8300B−AVR−07/2012

Figure 1-2. Window representations.

1.3 Event handling The Window system uses events to update the available windows when user or system interaction occurs. A global event handler for the Window system calls the configured event handler function for each of the affected windows. Table 1-2 describes the types of events which can be issued by the Window system.

Table 1-2. Event types for windows.

Event name Description Pointer event The user has clicked, moved or released a mouse or touch screen inside a window. Keyboard event The user has pushed a key on a keyboard or keypad. Raise event The window has been raised to the top inside its parent window. Unraise event The window is no longer the top child as another window has been raised to the top. Get focus event The window got keyboard focus. Lose focus event The window lost keyboard focus. Draw event Request to draw window (after window background has been drawn). Attribute event Attributes of window has changed (such as background, position etc). Destroy event Request to free all memory allocated for the window not handled by the Window system itself.

Atmel AVR1614: Widget Toolkit – Getting Started [APPLICATION NOTE] 5 8300B−AVR−07/2012

1.3.2 The draw event The draw event is used when drawing a window. When drawing a window, the following will happen: 1. Parent will be drawn if WIN_BEHAVIOR_REDRAW_PARENT attribute is set. 2. Background for window will be drawn. 3. Event handler for window will be called to draw the window/widget. 4. Children will be drawn starting with the bottom child and ending with the top child.

1.4 The Widget toolkit The Widget toolkit implements many common widgets for use on a graphical display. The toolkit uses the features from the Window system and display drivers to implement the widgets. A widget is defined as a graphical display element located on a screen that can show feedback to the user. Many widgets can also be manipulated by a mouse or touch screen. An example widget is a button widget. This widget is common in graphical user interfaces (GUI). This widget can show some text like “Initiate Launch Sequence”, and when the user clicks on the widget it will change color to indicate that it has been pressed. When user releases the press it will initiate an action as indicated by the text on the button. Table 1-3 lists the types of pre-implemented widgets that are distributed with the Widget toolkit, while Figure 1-3 shows how some of them can look when they are drawn on display.

Table 1-3. Implemented widget types.

Widget name Typical/example usage Basic frame Main window for the other widgets. Frame Frame with border and title bar. Button Register touch/mouse press from the user. Check box Allows the user to switch on (check) or off (uncheck) a feature. Progress bar Used to graphically represent a progress of a task or the current state of a variable (like the level of a tank or speed of a car). Radio button Allows the user to select one out of several features available. Slider Allows the user to set a specific input value with the mouse or touch input. Label Display text on the screen.

Figure 1-3. Example rendering of widgets.

Atmel AVR1614: Widget Toolkit – Getting Started [APPLICATION NOTE] 6 8300B−AVR−07/2012

1.5 Window system event queue As mentioned earlier, the Window system has an internal event queue. This queue must be processed regularly in order for user input to be handled and updates of the Window system to occur. Naturally, since the widget toolkit is based on the Window system, the widgets also require the Window system’s event queue to be processed regularly. In addition, the Window system does not automatically interface user input drivers (like touch sensors or push buttons), so it is the responsibility of the application to do the low-level handling of user input and generating the corresponding events in the Window system’s event queue. Refer to the work loop in the training project’s main function for an example of how to do such user input handling and event queue processing.

2. Training tasks This hands-on session covers how to get started with the Window system and widget toolkit. The goal of this training is to get familiar with the code and learn now to create your own GUI application. The training consists of the following four tasks: Task 1: Getting started This task shows how to start a new Widget toolkit training project in Atmel Studio, and how to get the application running on your board. Task 2: Adding a button This task shows how to add a button widget. Task 3: Adding a basic frame This task shows how to add a basic frame widget that can be used to draw on the screen. Task 4: Connecting it all together This task shows how to connect the button and frame together to allow the value of a counter to be manipulated and shown on the screen. Good luck!

2.1 Task 1: Getting started Let’s get started with the graphical user interfaces. The goal for this task is that you learn how to: • Connect the evaluation board and debugger • Compile the code • Upload the code to the Xplained board

1. Make sure that the correct version of Atmel Studio and Atmel Software Framework is installed on your computer. 2. Start Atmel Studio and create a new Widget toolkit training project, as shown in Figure 2-1: 1. Click “File” → “New” → “Example project from ASF…” 2. Enter “widget” in the search field 3. Select the training project for your Xplained board and click “OK”

Atmel AVR1614: Widget Toolkit – Getting Started [APPLICATION NOTE] 7 8300B−AVR−07/2012

Figure 2-1. Creating Widget toolkit training project with ASF project wizard.

3. Connect the mXT143E Xplained to the Xplained MCU board. Ensure correct orientation by lining up the drill holes with the white squares around them, as shown in Figure 2-2.

Figure 2-2. Correct alignment of the Xplained boards.

1. Set the SPI switch on the mXT143E Xplained in the correct position: use “Native SPI” unless it is for XMEGA®. 2. Connect the programmer/debugger to the JTAG (10-pin) or PDI (6-pin) header on the Xplained MCU board: • Atmel JTAGICE 3 only fits one way. Make sure to use the probe with same number of pins as the header • Atmel AVR Dragon requires a ribbon cable to connect to the board • Atmel AVR JTAGICE mkII and AVR ONE! require the squid probe or an extender • Figure 2-3 shows how to locate pin 1 of the header. Refer to Atmel Studio Help for details on connecting a specific tool to a JTAG or PDI header

Atmel AVR1614: Widget Toolkit – Getting Started [APPLICATION NOTE] 8 8300B−AVR−07/2012

Figure 2-3. Locating pin 1 on JTAG or PDI headers.

6. Connect the USB cable from the computer to the programmer/debugger and power it on. Install the USB drivers if not already installed. 7. Connect the USB cable from the computer to the Xplained MCU board. You do not need to install a driver for this training. If Windows® asks you to install a driver at this point, press “Cancel”. 8. Open the project properties by pressing ALT+F7 or clicking “Project” → “Properties”, then select your programmer/debugger and interface on the “Tool” tab, shown in Figure 2-4.

Figure 2-4. Tool settings for Atmel Studio projects.

9. Press F5 or click “Debug” → “Continue” to build the application and start a debug session. 10. Use the application and inspect the source to understand how it works. You can press CTRL+F5 or “Debug” → “Break All” to pause execution, then repeat step 9 to unpause. What does the application do?

Now, let’s change the background color to a color you like. The background color is defined in the source file app_widget.c with the APP_BACKGROUND_COLOR macro, which uses the GFX_COLOR macro. 11. Click “Help” → “View ASF Example Help” to go to the online documentation of the project. 12. Go to the documentation of “app_widget.c” and click “GFX_COLOR” to see the documentation of this macro. 13. Change the background color to a color you like, recompile and run.

Atmel AVR1614: Widget Toolkit – Getting Started [APPLICATION NOTE] 9 8300B−AVR−07/2012

2.2 Task 2: Adding a button Now let’s make some modifications to the code and add a button that can be clicked. The goal for this task is for you to know how to: • Create a button • Handle click events

1. Locate the app_widget_launch function in app_widget.c. Try to understand how the different widgets are configured before we add another widget. 2. Copy or type the following code below the line that says “//! \todo Add code to set up button here”: area.pos.x = 10; area.pos.y = 150; area.size.x = 90; area.size.y = 40;

btn = wtk_button_create(parent, &area, "Click", (win_command_t)BUTTON_ID); if (!btn) { goto error_widget; } win_show(wtk_button_as_child(btn)); 3. Compile and run the code. What does the above code do? 4. Add code in the “widget_frame_command_handler” for handling button presses and increment the variable counter for each button press. 5. Compile the code, and verify that it works.

2.3 Task 3: Adding a basic frame Now let’s make a widget that we can draw on. The basic frame widget has a callback function that can be used to draw on the screen. With the help of this callback function it is possible to implement visual feedback to the user in an easy way. First let’s create the widget. The goal for this task is for you to know how to: • Create a basic frame • Set up a basic frame draw handler

1. Locate the app_widget_launch function in app_widget.c. Let’s add a basic frame to the code as well. 2. Add the following code below the line that says: “//! \todo Add code to set up basic frame here.” area.pos.x += area.size.x + 40;

sub_frame_background.type = GFX_BITMAP_SOLID; sub_frame_background.data.color = GFX_COLOR(127, 0, 0);

Atmel AVR1614: Widget Toolkit – Getting Started [APPLICATION NOTE] 10 8300B−AVR−07/2012

sub_frame = wtk_basic_frame_create(parent, &area, &sub_frame_background, sub_frame_draw_handler, NULL, NULL); if (!sub_frame) { goto error_widget; } win_show(wtk_basic_frame_as_child(sub_frame)); 3. Compile and run the code. What does the above code do?

4. Change the color of the background of the widget to a different color. 5. Recompile, run and verify that the color has changed on screen.

2.4 Task 4: Connecting it all together Now we have a button that takes our input and a basic frame that we can draw on to give visual feedback to the user. Let’s show the click count of the button on the frame we created in the previous task. The goal for this task is for you to know how to: • Draw and format text on the screen • Make your own basic frame draw handler

1. Locate the sub_frame_draw_handler function in app_widget.c. 2. Find the line which contains: “\todo Add code here to draw text on screen”. To draw text on the screen, we need to use the gfx_draw_string function. For this we need to know how it is used. Let’s find the documentation for this function. 3. Open the online project documentation’s main page in the same way as in task 1. 4. Since this is a function in the graphics system related to fonts, we find its documentation under “Graphical display system” → “Font support”. 5. Click “gfx_draw_string” to read the descriptions of its parameters. 6. Add code using the gfx_draw_string function to print the text stored in buffer to the location clip >origin.x and clip >origin.y, using the font &sysfont and the colors of your preference via the GFX_COLOR macro. 7. Recompile and run the code. Why doesn’t the text update when we click the button?

Next, we’ll add user interaction by making the printed value increment (increase by 1) with each press of the button. Each such press generates a command event which can be handled by the main widget frame. 8. Locate the widget_frame_command_handler function. 9. Find the line which contains “\todo Add code here to handle button press”. 10. First, add code to increment count. To print the new value, we must trigger a redrawing of the sub frame widget window. 11. Use the wtk_basic_frame_as_child function to get a pointer to the window of sub_frame, and the win_redraw function to issue the redrawing of it. The documentation of these functions can be found in the modules “Window System” and “Widget toolkit” → “Basic frame widget” in the online project documentation. 12. Compile, run and verify that the text is updated when you click the button.

Atmel AVR1614: Widget Toolkit – Getting Started [APPLICATION NOTE] 11 8300B−AVR−07/2012

Congratulations! You have now created your own GUI element and added logic that updates it when the user interacts with the GUI!

If you have time, you can make the counter output nicer by: • Moving the text to the center of the widget. • Draw a rectangle around the text with the gfx_draw_rectangle function. (If you need hints for any of the tasks, see the file app_widget_solution.c for the full solution.)

3. Revision history

Doc. Rev. Date Comments 8300A 09/2010 Initial document release 8300B 07/2012 Update training for Atmel Software Framework and Xplained series of boards

Atmel AVR1614: Widget Toolkit – Getting Started [APPLICATION NOTE] 12 8300B−AVR−07/2012

Atmel Corporation Atmel Asia Limited Atmel Munich GmbH Atmel Japan G.K. 1600 Technology Drive Unit 01-5 & 16, 19F Business Campus 16F Shin-Osaki Kangyo Bldg. San Jose, CA 95110 BEA Tower, Millennium City 5 Parkring 4 1-6-4 Osaki, Shinagawa-ku USA 418 Kwun Tong Road D-85748 Garching b. Munich Tokyo 141-0032 Tel: (+1)(408) 441-0311 Kwun Tong, Kowloon GERMANY JAPAN Fax: (+1)(408) 487-2600 HONG KONG Tel: (+49) 89-31970-0 Tel: (+81)(3) 6417-0300 www.atmel.com Tel: (+852) 2245-6100 Fax: (+49) 89-3194621 Fax: (+81)(3) 6417-0370 Fax: (+852) 2722-1369

© 2012 Atmel Corporation. All rights reserved. / Rev.: 8300B−AVR−07/2012

Atmel®, Atmel logo and combinations thereof, Enabling Unlimited Possibilities®, AVR®, XMEGA®, and others are registered trademarks or trademarks of Atmel Corporation or its subsidiaries. Windows® is a registered trademark of Microsoft Corporation in U.S. and or other countries. Other terms and product names may be trademarks of others.

Disclaimer: The information in this document is provided in connection with Atmel products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN THE ATMEL TERMS AND CONDITIONS OF SALES LOCATED ON THE ATMEL WEBSITE, ATMEL ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS AND PROFITS, BUSINESS INTERRUPTION, OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF ATMEL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and products descriptions at any time without notice. Atmel does not make any commitment to update the information contained herein. Unless specifically provided otherwise, Atmel products are not suitable for, and shall not be used in, automotive applications. Atmel products are not intended, authorized, or warranted for use as components in applications intended to support or sustain life.