A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file scroll-view.ts
* @brief createScrollView — a clipped, scrollable panel for arbitrary content.
*
* The non-virtualized sibling of createListView: a Scissor-masked viewport
* whose content frame is translated by a ScrollContainer (wheel + drag/touch
* with kinetic fling, driven by the behavior plugin). Parent anything under
* `content`; sizes are explicit because scroll math needs them up front.
*/
import type { Entity, Vec2 } from '../../types';
import type { World } from '../../ecs/world';
import { UINode, UIPositionType, type UINodeData } from '../core/ui-node';
import { px } from '../core/dimension';
import { UIMask, MaskMode } from '../core/ui-mask';
import { ScrollContainer } from '../collection/scroll-container';
import { spawnUIEntity, type UINodeInit, type UIVisualInit } from '../core/compose';
import { makeWidgetInteractable } from '../input/interactable';
import type { ListViewHost } from './list-view';
export interface ScrollViewOptions {
world: World;
/** The plugin that routes scroll input (`uiPlugin`). */
host: ListViewHost;
parent?: Entity;
/** Pixel size of the visible window. */
viewportSize: Vec2;
/** Pixel size of the scrollable content frame. */
contentSize: Vec2;
/** Extra viewport UINode props (its size defaults to `viewportSize`). */
node?: UINodeInit;
/** Viewport background. Default: a transparent hit-target (so the wheel works). */
background?: UIVisualInit;
/** Scroll axis. Default 'vertical'. */
direction?: 'vertical' | 'horizontal' | 'both';
/** Wheel delta multiplier. Default 1. */
wheelSpeed?: number;
/** Drag/touch scrolling with a kinetic fling. Default true. */
dragScroll?: boolean;
/** Fling velocity fraction left after 1s of coasting. Default 0.135. */
decelerationRate?: number;
onScroll?: (offset: Vec2) => void;
}
export interface ScrollViewHandle {
/** The viewport entity (the clipped window; add it to your UI tree). */
readonly entity: Entity;
/** The scrolling content frame — parent your content here. */
readonly content: Entity;
/** The scroll model (escape hatch: `scrollBy`, `onScroll`, …). */
readonly scroll: ScrollContainer;
scrollTo(offset: Vec2): void;
/** Update the scroll range after content changes size. */
setContentSize(size: Vec2): void;
dispose(): void;
}
export function createScrollView(opts: ScrollViewOptions): ScrollViewHandle {
const { world, host, viewportSize, contentSize } = opts;
const viewport = spawnUIEntity({
world,
parent: opts.parent,
node: { width: px(viewportSize.x), height: px(viewportSize.y), ...opts.node },
visual: opts.background ?? { color: { r: 0, g: 0, b: 0, a: 0 } },
});
world.insert(viewport, UIMask, { enabled: true, mode: MaskMode.Scissor });
makeWidgetInteractable(world, viewport, { focusable: false });
const content = spawnUIEntity({
world,
parent: viewport,
node: {
position: UIPositionType.Absolute,
insetLeft: px(0),
insetTop: px(0),
width: px(contentSize.x),
height: px(contentSize.y),
},
});
const scroll = new ScrollContainer({
viewportSize,
contentSize,
direction: opts.direction ?? 'vertical',
wheelSpeed: opts.wheelSpeed,
dragScroll: opts.dragScroll,
decelerationRate: opts.decelerationRate,
});
const offScroll = scroll.onScroll((offset) => {
const n = world.get(content, UINode) as UINodeData;
n.insetLeft = px(-offset.x);
n.insetTop = px(-offset.y);
world.insert(content, UINode, n);
opts.onScroll?.(offset);
});
host.attachScrollContainer(viewport, scroll);
let disposed = false;
return {
entity: viewport,
content,
scroll,
scrollTo: (offset) => scroll.setOffset(offset),
setContentSize: (size) => {
const n = world.get(content, UINode) as UINodeData;
n.width = px(size.x);
n.height = px(size.y);
world.insert(content, UINode, n);
scroll.setContentSize(size);
},
dispose: () => {
if (disposed) return;
disposed = true;
offScroll();
host.detachScrollContainer(viewport);
scroll.dispose();
if (world.valid(viewport)) world.despawn(viewport);
},
};
}