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