ScrollIndicator

Overview

The ScrollIndicator widget renders a circular arc indicator on the left edge of the screen that tracks the selected item in a scroll-wheel menu. A sliding arc handle moves along a background rail arc as the user navigates the list. It supports smooth animated transitions including wrap-around (last → first and first → last) using a dual-handle technique.

Components

Name	Type	Description
rail	Circle arc	Background track, 232°–308°, radius 112 px
handle	Circle arc	Active position indicator, slides along the rail
handleOvf	Circle arc	Hidden; used only during wrap-around animations

Container size: 36×146 px, positioned at X=0, Y=47. The arc center is at (120, 73) relative to the screen — the same virtual center used by Buttons — so the indicator aligns with the bezel geometry.

Predefined Configs

Two configurations are available as static constexpr members:

Config	Rail range	Handle span	Use case
ScrollIndicator::kBig	232°–308° (76°)	18°	Menus with few items (≤ 5)
ScrollIndicator::kSmall	252°–288° (36°)	10°	Menus with many items

The default (applied by the Designer-generated base) is kBig. Call setConfig(kSmall) to switch.

Custom configs can be built from ScrollIndicatorConfig:

struct ScrollIndicatorConfig {
    float    handleLen;    // Handle arc span (degrees)
    float    railMin;      // Rail low bound (degrees)
    float    railMax;      // Rail high bound (degrees)
    uint32_t handleColor;  // Handle color (0xRRGGBB)
    uint32_t railColor;    // Rail background color (0xRRGGBB)
};

API

void setConfig(const ScrollIndicatorConfig& cfg);  // apply config (optional, default = kBig)

void setCount(uint16_t count);       // total items; handle hidden when count <= 1
void setActiveId(uint16_t index);    // instant jump to item
void animateToId(int16_t index,
                 int16_t animationSteps = 0);  // animated move; 0 = instant
uint16_t getActiveId();              // current (or target) index

Wrap-around values for animateToId: passing -1 wraps to the last item; passing count wraps to item 0.

Usage in TouchGFX Designer

1. Import the package:

   • Open TouchGFX Designer

   • Go to Edit → Import → Custom Containers

   • Select ScrollIndicator.tpkg

2. Add to screen: drag the ScrollIndicator container onto your screen. Position at X=0, Y=47.

3. No designer properties — all configuration is done in C++.

Usage in C++ Code

#include <gui/containers/ScrollIndicator.hpp>

ScrollIndicator scrollIndicator;
add(scrollIndicator);
scrollIndicator.setPosition(0, 47, 36, 146);

// Setup (kBig is default; only call setConfig to switch or customize)
scrollIndicator.setConfig(ScrollIndicator::kSmall);
scrollIndicator.setCount(5);     // 5-item list, starts at index 0
scrollIndicator.setActiveId(0);

// Navigate — animated (8 ticks ≈ smooth on 60 fps)
scrollIndicator.animateToId(nextIndex, 8);

// Navigate — instant
scrollIndicator.setActiveId(2);

// Wrap-around (last -> first)
scrollIndicator.animateToId(scrollIndicator.getActiveId() + 1, 8);
// If activeId was the last item, animateToId wraps back to 0 automatically.

Notes

• The handle is automatically hidden when count <= 1.

• Starting a new animation while one is in progress snaps the handle to the position it has reached before proceeding — no visual glitch.

• The overflow handle (handleOvf) is managed internally and must not be manipulated directly.

• Handle arcs are clipped to the rail range. During a wrap-around slide the outgoing handle shrinks into the near rail end and the incoming one grows out of the far end, so neither is ever drawn past the rail into empty container space.

• That clipping is presentation only. The widget tracks the unclipped position internally, so interrupting a slide resumes from where the handle actually was rather than from the rail edge it was drawn at.

• The timer widget is automatically unregistered when the animation completes or in the destructor.

Files Included

• manifest.xml — package manifest (requires TouchGFX ≥ 4.26.1)

• content/CustomContainerExport.touchgfx — Designer container definition

• content/CustomContainerManifest.xml — container manifest

• files/gui/include/gui/containers/ScrollIndicator.hpp — header

• files/gui/src/containers/ScrollIndicator.cpp — implementation

Dependencies

• TouchGFX Framework (minimum version 4.26.1)

• No image assets — fully vector-based