ScrollMenu - Creating Scrollable Lists and Menus

Welcome to the UNA SDK tutorial series! The ScrollMenu app demonstrates fundamental concepts of menu navigation on the UNA Watch platform. This tutorial focuses on building an application with a scrollable menu using hardware buttons, providing a foundation for more complex user interfaces.

Project Folder

What You’ll Learn

• How to implement GUI applications with TouchGFX

• Handling hardware button events for menu navigation

• Understanding the UNA app framework for interactive applications

Getting Started

Prerequisites

Before building the ScrollMenu app, you need to set up the UNA SDK environment. Follow the toolchain setup for complete installation instructions, including:

• UNA SDK cloned with submodules (git clone --recursive)

• ST ARM GCC Toolchain (from STM32CubeIDE/CubeCLT, not system GCC)

• CMake 3.21+ and make

• Python 3 with pip packages installed

Minimum requirements for ScrollMenu:

• UNA_SDK environment variable pointing to SDK root

• ARM GCC toolchain in PATH

• CMake and build tools

For GUI development/modification:

• TouchGFX Designer installed (see toolchain setup)

Building and Running ScrollMenu

1. Verify your environment setup (see toolchain setup for details):

   echo $UNA_SDK                   # Should point to SDK root.
                                   # Note for backward compatibility with linux path notation it uses '/'
   
   which arm-none-eabi-gcc         # Should find ST toolchain
   which cmake                     # Should find CMake
   

2. Navigate to the ScrollMenu directory:

   cd $UNA_SDK/Docs/Tutorials/ScrollMenu
   

3. Build the application:

   mkdir build && cd build
   cmake -G "Unix Makefiles" ../Software/Apps/ScrollMenu-CMake
   make
   

The app will start and display an initial menu with three items. Use the hardware buttons to navigate the menu and perform actions, demonstrating menu navigation patterns.

Running on Simulator

To test the app on the simulator (Windows only):

1. Open ScrollMenu.touchgfx in TouchGFX Designer and click Generate Code (F4) (do this once).

2. Navigate to ScrollMenu\Software\Apps\TouchGFX-GUI\simulator\msvs

3. Open Application.vcxproj in Visual Studio

4. Press F5 to start debugging and run the simulator

In the simulator, use keyboard keys to simulate hardware buttons:

• 1 = L1 (Previous menu item)

• 2 = L2 (Next menu item)

• 3 = R1 (Perform action on selected item)

• 4 = R2 (Double-press to exit)

The simulator will display the scrollable menu with Counter, Increase, Decrease items. For detailed simulator setup and button mapping, see Simulator.

ScrollMenu App Overview

Navigation Flow

• Start with menu displaying Counter, Increase, Decrease items

• Press left button (L1) → Select previous menu item

• Press top left button (L2) → Select next menu item

• Press top right button (R1) → Perform action on selected item:

  • Counter: Reset counter to 0

  • Increase: Increment counter

  • Decrease: Decrement counter

• Double-press bottom right button (R2) → Exit the app

Architecture Components

The Service Layer (Backend)

• Manages the application lifecycle

• Handles communication with the GUI layer

• Minimal implementation since no sensors are used

The GUI Layer (Frontend)

• Built with TouchGFX framework

• Handles button events and screen transitions

• Updates the display based on user input

• Manages screen state and visual elements

Button Event Handling

The app responds to hardware button presses through the handleKeyEvent method in MainView.cpp. L1 and L2 buttons navigate the menu by selecting previous or next items. R1 button performs the action associated with the currently selected menu item, such as resetting, incrementing, or decrementing the counter. R2 button detects double-presses to exit the application.

Menu Item Management

The menu displays items with different appearances for selected and unselected states:

• Selected items are highlighted in the center of the menu (typically with different styling)

• Unselected items are shown in the background with standard appearance

• When updating dynamic content (like the counter value), both selected and unselected versions of the item are updated to maintain consistency when scrolling

Screen Updates

After performing actions that change the menu display (such as updating the counter value), the invalidate() method is called on the menu and its items to refresh the display, ensuring changes are visible to the user.

ScrollMenu app creation process

1. Copy HelloWorld tutorial

2. Change naming: Rename project directory, cmake directory and name of the project in CMakeLists.txt; Also change APP_ID to something else.

3. Commit initial changes: it’s a good practice to use version control system like git

4. *Add text keys using TouchGFX Designer:

   • In TouchGFX Designer, go to the Texts tab

   • Click + Add Text to create new text entries

   • Add three text entries with the following properties:

     • Text Id: “Counter”, Alignment: Center, Typography: Poppins_Medium_25, Translation (GB): “Counter”

     • Text Id: “Increase”, Alignment: Center, Typography: Poppins_Medium_25, Translation (GB): “Increase”

     • Text Id: “Decrease”, Alignment: Center, Typography: Poppins_Medium_25, Translation (GB): “Decrease”

   • These will generate the text keys T_COUNTER, T_INCREASE, T_DECREASE used in the code

5. *Edit TouchGFX:

   • Rename *.touchgfx to ScrollMenu.touchgfx

   • Rename ScrollMenu.touchgfx:163 "Name": "ScrollMenu"

   • Open the main screen in the designer

   • From the widget palette, locate and drag a Menu widget onto the main screen canvas

   • Name the menu widget menu1 in the properties panel

   • Configure the menu properties:

     • Set the number of items to 3

     • Customize the appearance of selected and unselected items (fonts, colors, etc.)

     • Set initial text for each item using the text keys (T_COUNTER, T_INCREASE, T_DECREASE)

   • Position and size the menu widget appropriately on the screen (typically centered)

   • Click Generate code

6. Edit MainView.hpp:

   • Add member variables for state tracking:

     class MainView : public MainViewBase
     {
         uint8_t lastKeyPressed = {'\0'};
         int counter = 0;
     public:
         MainView();
         virtual ~MainView() {}
         virtual void setupScreen();
         virtual void tearDownScreen();
     
     protected:
         virtual void handleKeyEvent(uint8_t key) override;
     };
     

7. Edit MainView.cpp:

   • In setupScreen(), configure the menu items:

     void MainView::setupScreen()
     {
         MainViewBase::setupScreen();
     
         menu1.setNumberOfItems(3);
         menu1.getNotSelectedItem(0)->config(T_COUNTER);
         menu1.getNotSelectedItem(1)->config(T_INCREASE);
         menu1.getNotSelectedItem(2)->config(T_DECREASE);
         menu1.getSelectedItem(0)->config(T_COUNTER);
         menu1.getSelectedItem(1)->config(T_INCREASE);
         menu1.getSelectedItem(2)->config(T_DECREASE);
         menu1.invalidate();
     
         buttons.setL1(ButtonsSet::NONE);
         buttons.setL2(ButtonsSet::NONE);
         buttons.setR1(ButtonsSet::NONE);
         buttons.setR2(ButtonsSet::AMBER);
     }
     

   • Implement handleKeyEvent for menu navigation and actions:

     void MainView::handleKeyEvent(uint8_t key)
     {
         if (key == Gui::Config::Button::L1) {
             menu1.selectPrev();
         }
     
         if (key == Gui::Config::Button::L2) {
             menu1.selectNext();
         }
     
         if (key == Gui::Config::Button::R1) {
             int selected = menu1.getSelectedItem();
             auto* counter_nosel_item = menu1.getNotSelectedItem(0);
             auto* counter_sel_item = menu1.getSelectedItem(0);
     
             touchgfx::Unicode::UnicodeChar buffer[32];
             switch (selected) {
             case 0:
                 // Reset counter
                 counter = 0;
                 touchgfx::Unicode::snprintf(buffer, 32, "Counter: %d", counter);
                 counter_nosel_item->config(buffer);
                 counter_sel_item->config(buffer);
                 break;
             case 1:
                 counter++;
                 touchgfx::Unicode::snprintf(buffer, 32, "Counter: %d", counter);
                 counter_nosel_item->config(buffer);
                 counter_sel_item->config(buffer);
                 // Increment counter
                 break;
             case 2:
                 // Decrement counter
                 counter--;
                 touchgfx::Unicode::snprintf(buffer, 32, "Counter: %d", counter);
                 counter_nosel_item->config(buffer);
                 counter_sel_item->config(buffer);
                 break;
             }
             menu1.invalidate();
             counter_nosel_item->invalidate();
             counter_sel_item->invalidate();
         }
     
         if (key == Gui::Config::Button::R2) {
             if (lastKeyPressed == key) presenter->exit();
         }
         lastKeyPressed = key;
     }
     

8. Compile code using SDK setup instructions.

Understanding Menu Navigation

The ScrollMenu app demonstrates how to handle hardware button events for menu navigation in TouchGFX applications. Key concepts include:

Button Event Processing

• Button presses are captured in the handleKeyEvent(uint8_t key) method

• L1 and L2 buttons navigate the menu (select previous/next item)

• R1 button performs the action associated with the selected menu item

• R2 button detects double-presses for app exit

Menu State Management

• The app maintains current menu selection state

• Menu items display dynamic content (counter value)

• The invalidate() call ensures the display refreshes after changes

Exit Handling

• Double-press detection for the R2 button implements app exit

• State tracking with lastKeyPressed prevents accidental exits

Common Patterns and Best Practices

Button Handling

• Map button IDs to meaningful actions consistently

• Use state variables to track multi-press sequences

• Always call invalidate() after visual changes

UI Updates

• Keep event handlers lightweight to maintain responsiveness

• Use appropriate TouchGFX widgets for different content types

• Consider user feedback for button presses (visual/audio)

Code Organization

• Separate UI logic from business logic

• Use clear naming for button actions and screen states

• Document button mappings in comments

Performance Considerations

• Minimize work in event handlers

• Batch UI updates when possible

• Avoid blocking operations that could delay response

Key Code Insights for New Developers

MainView.cpp Structure

• handleKeyEvent() is the central point for user input

• Menu navigation uses menu1.selectPrev() and menu1.selectNext()

• Menu actions update counter and refresh display with invalidate() calls

Menu Configuration

• Menu is configured in setupScreen() with item texts and count

• The Menu widget manages item selection and display

• Menu items can be configured with text using config() method

State Tracking

• Use member variables like counter and lastKeyPressed to maintain app state

• Track sequences like double-presses for special actions

• Update menu item text dynamically based on state changes

Next Steps

1. Run the ScrollMenu app - Build and test the menu navigation

2. Modify menu items - Experiment with different menu actions

3. Add new menu items - Extend the app with additional menu options

4. Explore TouchGFX widgets - Add text, images, or other elements

5. Study advanced examples - Look at apps with more complex navigation

Troubleshooting

Build Issues

• Ensure TouchGFX Designer is properly installed

• Check that all project files are generated correctly

• Verify CMake configuration matches your environment

Runtime Issues

• Confirm button mappings in the simulator match hardware

• Check log output for event handling errors

• Test on actual hardware for button responsiveness

Common Mistakes

• Forgetting to call invalidate() after UI changes

• Incorrect button ID constants

• Not handling all button states appropriately

The ScrollMenu app provides a solid foundation for understanding menu navigation on the UNA platform. Mastering these patterns will enable you to create engaging, responsive applications.