Skip to main content

ScrollView

ScrollView​

ScrollView is a focus-aware container for content that is larger than its viewport. It renders real child views, then translates an internal scrollable group as focus changes or as web mouse/touch input scrolls the surface.

Use ScrollView for small or medium static groups. For large, data-driven, or frequently changing lists, use CollectionView because it virtualizes rows and recycles cells.

Example​

Controls Scrollview

@view('ControlsScrollview')
export class ControlsScrollviewView extends BaseExampleScreenView<ControlsScrollviewState> {
  protected getViews(): ViewStruct<ViewState>[] {
    // --- edit below ---

    return [
      ScrollView([
        VGroup(
          Array(20).fill(0).map((_, i) =>
            Rectangle({
              id: `rectangle-${i}`,
              color: i % 2 === 0 ? '#4A90E2' : '#50E3C2',
              height: 80,
              width: 300,
            })
              .canReceiveFocus(true)
              .isInitialFocus(i === 0)
          )
        ).itemSpacing(10)
      ])
        .viewportHeight(300)
        .viewportWidth(400)
        .verticalAlignment(ScrollVerticalAlignment.Floating)
    ];
    // --- edit above ---
  }
}
Keep One Item Focused

Set .canReceiveFocus(true) on scrollable children and .isInitialFocus(true) on the first item you want focused. Auto-scroll follows the focused child.

Common API​

  • viewportWidth and viewportHeight: explicit visible area. If omitted, ScrollView falls back to its own size, a clipping parent, calculated size, or the default design surface.
  • autoScroll: when true, focused child changes move the scroll position.
  • verticalAlignment: Top, Center, Bottom, Floating, None, Predefined, CustomPosition, or CustomCallback.
  • horizontalAlignment: Left, Center, Right, Floating, None, Predefined, CustomPosition, or CustomCallback.
  • customPositionX and customPositionY: offsets used by custom-position alignment.
  • customVerticalPositionCallback and customHorizontalPositionCallback: calculate positions from the focus-change event.
  • scrollToChild: state field that animates a specific child into view.
  • animationDuration: duration for focus-driven and programmatic scroll animations.

Programmatic Scrolling​

const scrollView = this.getSubView<ScrollViewView>('settingsScroll');

scrollView?.scrollTo([0, -480], 250);
scrollView?.animateToChild(targetChild, 250);
scrollView?.reset();

scrollTo(position, duration) expects a scroll translation in design coordinates. animateToChild(child, duration) computes the translation needed to bring that child into view.

Mouse and Touch​

On web, ScrollView exposes an external scroll API used by input adapters:

  • Mouse wheel calls into a scroll controller and updates the scroll offset.
  • Touch drag starts a drag session and applies momentum after release.
  • Scroll extents can be hard-stopped or overscrolled by the controller.
  • Browser coordinates are normalized into Hosanna design coordinates before hit testing.

Application code usually does not call setExternalScrollOffset; it should configure the ScrollView's viewport and focus behavior, then let adapters drive pointer scrolling.

API Reference​

ScrollView API