Files
James Babcock a02b849200 Borderless modes have different padding inside the builtin apps
Most of the builtin apps had some padding between the window edge and
their content, because they expect to be displayed with a line border on
their edge. We added a customization option to remove the border, so,
that padding is not always necessary. Make the layouts dynamically
adjust, to omit the padding when it isn't needed.
2026-11-11 15:19:29 -08:00

525 lines
23 KiB
TypeScript

import { DrawExpression as E } from "../graphics/draw-expression";
import { GrayImage } from "../graphics/image";
import { menuScrollList, slidingHighlightY, type MenuScrollHighlight } from "../graphics/menu-scroll-list";
import type { InputEvent } from "./gestures";
import { MenuHighlightMotion } from "./menu-highlight-motion";
import { MenuScrollMotion, scrollOffsetExpression, type MenuScrollAnimation } from "./menu-scroll-motion";
/** Selected-row fill while the menu owns input; the outline alone marks an unfocused menu's selection. */
export const MENU_HIGHLIGHT_FILL = 15;
export const MENU_HIGHLIGHT_STROKE = 45;
const SCROLLBAR_TRACK_VALUE = 30;
const SCROLLBAR_THUMB_VALUE = 120;
const SCROLLBAR_WIDTH = 3;
const SCROLLBAR_MIN_THUMB = 8;
/** Largest packed scroll strip, in bytes: the firmware's per-resource limit. */
const MAX_SCROLL_STRIP_BYTES = 65536;
/** A bounce overshoots by this fraction of the end row's pitch, as if starting to reveal another row. */
export const BOUNCE_FRACTION = 0.4;
export const MAX_BOUNCE = 24;
/**
* A rectangle in image coordinates. padTop and padBottom are blank rows
* inside the scrolled content, before the first row and after the last
* (default none): they scroll away with the rows. A list whose box runs to
* a window's top or bottom edge passes the padding suggested for that edge
* (viewport.ts), so its end rows keep clear of a border line there while
* rows scrolled past them are cut off right at the edge.
*/
export type MenuBox = { x: number; y: number; width: number; height: number; padTop?: number; padBottom?: number };
export type MenuDrawArgs<T> = {
/**
* Draw into this image, inside the (x, y, width, height) rect. For the
* selected row this is a scratch image exactly the rect's size (so x and y
* are 0), replayed over the highlight. While a scroll animates, rows are
* also drawn into a strip image covering both viewports. Never draw
* relative to image.width or image.height, and never outside the rect.
*/
image: GrayImage;
item: T;
index: number;
x: number;
y: number;
width: number;
height: number;
selected: boolean;
/** Whether the menu owns input right now: the `focused` flag the host passed to paint. */
focused: boolean;
};
export type MenuHighlightStyle = {
/** Corner radius of the selection box. Default 8. */
radius?: number;
/** Stereo depth of the selection box. Default 0. */
depth?: number;
};
export type MenuOptions<T> = {
items?: readonly T[];
/** Initial selection. Default: the first selectable item. */
selectedIndex?: number | null;
/** Row pitch in pixels (including rowGap) for an item laid out at this width. */
getHeight: (item: T, width: number) => number;
/** Default: every item is selectable. Non-selectable items (group labels) are skipped by navigation. */
isSelectable?: (item: T) => boolean;
draw: (args: MenuDrawArgs<T>) => void;
/** Called by activate() / a click with the selected item. */
onSelect?: (item: T, index: number) => void | Promise<void>;
/**
* Whether scrolling past either end wraps to the other. When false the
* selection stays put and onExitTop / onExitBottom is called instead; with
* no callback for that end, the list bounces.
*/
wrap?: boolean;
onExitTop?: () => void;
onExitBottom?: () => void;
/** Pixels between consecutive rows, excluded from each row's drawable box and highlight. Default 0. */
rowGap?: number;
/** Selection box style, or false to draw no highlight (the draw callback shows the selection itself). */
highlight?: MenuHighlightStyle | false;
};
/** Row tops and pitches in content coordinates; `total` includes the box's padTop and padBottom. */
type MenuLayout = { tops: number[]; heights: number[]; total: number };
/**
* A vertical list with one selected row: the menu proper, independent of the
* Layer stack. A host paints it into a rect of its own image and forwards
* scroll / click events while the menu has focus; the host keeps the rest
* (title, box, focus between several menus, back navigation).
*
* Rows may vary in height and some may be unselectable; navigation skips
* those. Scrolling is pixel-based: the viewport moves the minimum needed to
* keep the selection and its neighbors fully visible (just the selection
* when they don't all fit), then aligns to a row top so the list never
* starts with a partially visible row. A row cut off by the viewport's edge
* is drawn clipped, so a box that isn't a whole number of rows tall shows
* part of the next row as a hint that there is more.
*
* Navigation that scrolls (without wrapping) animates on the glasses: the
* rows visible before and after are drawn into one strip, and a display list
* slides a viewport-sized copy of it while the highlight moves on the same
* timeline. Scrolling past an end without wrap or an exit callback bounces
* the same way, with the highlight carried along by its row. When the strip
* would be too large or the menu doesn't fit the assumptions in scrollStrip,
* the motion snaps instead.
*/
export class Menu<T> {
private itemList: readonly T[];
private selected: number | null;
/**
* The caller asked for no selection. Otherwise a null selection only means
* nothing was selectable, and the first selectable item is chosen as soon
* as one exists (a menu created empty and filled later starts on it).
*/
private deselected: boolean;
private scrollY = 0;
private lastBox: MenuBox | null = null;
private readonly motion = new MenuHighlightMotion();
private readonly scrollMotion = new MenuScrollMotion();
constructor(private readonly options: MenuOptions<T>) {
this.itemList = options.items ?? [];
this.deselected = options.selectedIndex === null;
this.selected = this.settle(options.selectedIndex ?? null);
}
get items(): readonly T[] {
return this.itemList;
}
get selectedIndex(): number | null {
this.reconcile();
return this.selected;
}
get selectedItem(): T | null {
const index = this.selectedIndex;
return index === null ? null : this.itemList[index]!;
}
/** Content offset of the viewport's top edge, in pixels. */
get scrollTop(): number {
return this.scrollY;
}
/** Move the viewport's top edge; the next paint clamps it and scrolls the selection back into view. */
set scrollTop(value: number) {
this.scrollY = Math.max(0, value | 0);
}
/** True when the content did not fit the box given to the last paint. */
get overflows(): boolean {
if (!this.lastBox) return false;
return this.layout(this.lastBox).total > this.lastBox.height;
}
/**
* Replace the items. `selectedIndex` names the new selection (null for
* none); left out, the selection stays at the same index, clamped into
* range, or lands on the first selectable item if there was none. The
* viewport keeps the selected row at the same on-screen position when it can.
*/
setItems(items: readonly T[], selectedIndex?: number | null): void {
const box = this.lastBox;
const before = this.selected !== null && box
? this.layout(box).tops[this.selected]! - this.scrollY
: null;
this.itemList = items;
if (selectedIndex !== undefined) this.deselected = selectedIndex === null;
this.selected = this.settle(selectedIndex === undefined ? this.selected : selectedIndex);
if (before !== null && this.selected !== null && box) {
this.scrollY = Math.max(0, this.layout(box).tops[this.selected]! - before);
}
}
/**
* Move the selection; a non-selectable or out-of-range index lands on the
* nearest selectable one. null clears it until the user scrolls or a
* number is selected.
*/
select(index: number | null): void {
this.deselected = index === null;
this.selected = this.settle(index);
}
/** Step the selection by one selectable row; handles wrap and the exit callbacks. */
moveSelection(delta: -1 | 1): void {
this.reconcile();
const from = this.selected;
const next = this.nextSelectable(from, delta);
if (next !== null) {
if (from !== null) this.motion.navigate(from, false);
this.scrollMotion.navigate(false);
this.selected = next;
this.deselected = false;
return;
}
if (from === null && this.scrollContent(delta)) return;
if (this.options.wrap) {
const wrapped = this.nextSelectable(null, delta);
if (wrapped !== null && wrapped !== from) {
if (from !== null) this.motion.navigate(from, true);
this.scrollMotion.navigate(true);
this.selected = wrapped;
this.deselected = false;
} else if (from === null && this.lastBox) {
this.scrollY = delta > 0 ? 0 : this.maxScroll(this.layout(this.lastBox), this.lastBox.height);
}
return;
}
const exit = delta > 0 ? this.options.onExitBottom : this.options.onExitTop;
if (exit) exit();
else this.bounce(delta);
}
/** Invoke onSelect for the selected item. Returns false when nothing is selected. */
async activate(): Promise<boolean> {
this.reconcile();
if (this.selected === null) return false;
await this.options.onSelect?.(this.itemList[this.selected]!, this.selected);
return true;
}
/** Handle scroll-up, scroll-down and click. Returns false for any other event, or a click with nothing selected. */
async handleInput(event: InputEvent): Promise<boolean> {
switch (event.type) {
case "scroll-up":
this.moveSelection(-1);
return true;
case "scroll-down":
this.moveSelection(1);
return true;
case "click":
return this.activate();
default:
return false;
}
}
/** The selectable item under image-coordinate y in the last painted box, for touch/mirror input. */
indexAt(y: number): number | null {
const box = this.lastBox;
if (!box || y < box.y || y >= box.y + box.height) return null;
const layout = this.layout(box);
const contentY = y - box.y + this.scrollY;
for (let index = 0; index < this.itemList.length; index++) {
if (contentY >= layout.tops[index]! && contentY < layout.tops[index]! + layout.heights[index]!) {
return this.isSelectable(index) ? index : null;
}
}
return null;
}
paint(image: GrayImage, box: MenuBox, focused: boolean): void {
this.lastBox = box;
this.reconcile();
const layout = this.layout(box);
this.ensureVisible(layout, box.height);
const now = Date.now();
const scroll = this.scrollMotion.paint(this.scrollY, box, now);
const strip = scroll ? this.scrollStrip(image, layout, box, focused, scroll) : null;
if (scroll && !strip) this.scrollMotion.cancel();
const gap = this.options.rowGap ?? 0;
const highlight = this.options.highlight;
let scrollHighlight: MenuScrollHighlight | undefined;
for (let index = 0; index < this.itemList.length; index++) {
const top = layout.tops[index]! - this.scrollY;
const height = layout.heights[index]! - gap;
const selected = index === this.selected;
if (top + height <= 0 || top >= box.height) continue;
const rowY = box.y + top;
const item = this.itemList[index]!;
if (selected && highlight !== false) {
const animation = this.motion.paint(index, this.scrollY, box.x, rowY, box.width, height, now, !!strip);
const background = focused ? MENU_HIGHLIGHT_FILL : 0;
if (strip && scroll) {
// The strip already holds this row's content; only the box is drawn over it.
let y = slidingHighlightY(top, animation, scroll.startedAt);
// A bounce carries the highlight with its row.
if (scroll.peak !== undefined) y = y.add(E.i32(scroll.to)).sub(scrollOffsetExpression(scroll));
scrollHighlight = { y, width: box.width, height, radius: highlight?.radius ?? 8,
background, border: MENU_HIGHLIGHT_STROKE };
continue;
}
// A selected row taller than the box is drawn whole, from its top.
const row = new GrayImage(box.width, height, 0);
this.options.draw({ image: row, item, index, x: 0, y: 0, width: box.width, height, selected, focused });
image.drawMenuSelection(row, box.x, rowY, background, MENU_HIGHLIGHT_STROKE,
highlight?.radius ?? 8, highlight?.depth ?? 0, animation);
} else {
this.drawRow(image, index, box.x, rowY, box.width, height, focused, box.y, box.y + box.height);
}
}
// The rows painted above stay underneath: once the animation ends, the
// strip's final frame and the static paint are pixel-identical.
if (strip && scroll) {
const sourceY = scrollOffsetExpression(scroll).sub(E.i32(strip.top));
image.drawDisplayList(menuScrollList(strip.image, strip.x, box.height, scroll, sourceY, scrollHighlight),
box.x, box.y, box.width, box.height, 0);
}
}
/** Draw a vertical scrollbar for the last painted box (no-op unless the content overflows it). */
drawScrollbar(image: GrayImage, x: number, y: number, height: number): void {
const box = this.lastBox;
if (!box) return;
const layout = this.layout(box);
if (layout.total <= box.height) return;
const maxScroll = this.maxScroll(layout, box.height);
const thumbHeight = Math.max(SCROLLBAR_MIN_THUMB, (height * box.height / layout.total) | 0);
const fraction = Math.min(1, Math.max(0, this.scrollY) / maxScroll);
image.fillRect(x, y, SCROLLBAR_WIDTH, height, SCROLLBAR_TRACK_VALUE);
image.fillRect(x, y + (((height - thumbHeight) * fraction) | 0), SCROLLBAR_WIDTH, thumbHeight, SCROLLBAR_THUMB_VALUE);
}
/**
* Draw one row at (x, y), clipped to target rows [clipTop, clipBottom).
* Selected rows with a highlight are drawn in a scratch image the row's
* size, like the static selection, which clips their ink to the row.
*/
private drawRow(target: GrayImage, index: number, x: number, y: number, width: number, height: number,
focused: boolean, clipTop: number, clipBottom: number): void {
const item = this.itemList[index]!;
const selected = index === this.selected;
const scratch = selected && this.options.highlight !== false;
if (!scratch && y >= clipTop && y + height <= clipBottom) {
this.options.draw({ image: target, item, index, x, y, width, height, selected, focused });
return;
}
const row = new GrayImage(width, height, 0);
this.options.draw({ image: row, item, index, x: 0, y: 0, width, height, selected, focused });
const skip = Math.max(0, clipTop - y);
target.bitBlt(row.withDrawsBaked(), x, y + skip,
{ sy: skip, height: Math.min(height, clipBottom - y) - skip, transparentZero: true });
}
/**
* Render every row visible at any point of the motion into one strip, or
* return null to snap. Its first and last frames must match the static
* paints on either side, which clip rows at the viewport's edges the same
* way. The strip copy is opaque, so this also requires a black background
* under the menu, a selected row that fits, and a highlight at the menu's
* own depth.
*/
private scrollStrip(image: GrayImage, layout: MenuLayout, box: MenuBox, focused: boolean,
scroll: MenuScrollAnimation): { image: GrayImage; x: number; top: number } | null {
const highlight = this.options.highlight;
if (highlight !== false && (highlight?.depth ?? 0) !== 0) return null;
const gap = this.options.rowGap ?? 0;
const selected = this.selected;
if (selected !== null && layout.tops[selected]! + layout.heights[selected]! - gap - scroll.to > box.height) return null;
const offsets = [scroll.from, scroll.to, scroll.peak ?? scroll.to];
const top = Math.min(...offsets);
const bottom = Math.max(...offsets) + box.height;
const strip = new GrayImage(box.width, bottom - top, 0);
for (let index = 0; index < this.itemList.length; index++) {
const rowTop = layout.tops[index]!;
const height = layout.heights[index]! - gap;
if (rowTop + height <= top || rowTop >= bottom) continue;
this.drawRow(strip, index, 0, rowTop - top, box.width, height, focused, 0, strip.height);
}
// Crop to the columns with ink; the static paint shows the rest unchanged.
const baked = strip.withDrawsBaked();
let left = baked.width, right = -1;
for (let y = 0; y < baked.height; y++) {
const row = y * baked.width;
for (let x = 0; x < left; x++) if (baked.pixels[row + x]! >= 8) { left = x; break; }
for (let x = baked.width - 1; x > right; x--) if (baked.pixels[row + x]! >= 8) { right = x; break; }
}
if (right < left) return null;
const width = right - left + 1;
if (5 + Math.ceil(width / 2) * baked.height > MAX_SCROLL_STRIP_BYTES) return null;
// Whatever the host drew under the copied columns would be covered.
for (let y = box.y; y < box.y + box.height; y++) {
for (let x = box.x + left; x <= box.x + right; x++) {
if (x >= 0 && y >= 0 && x < image.width && y < image.height && image.pixels[y * image.width + x]! >= 8) return null;
}
}
const cropped = new GrayImage(width, baked.height, 0);
cropped.bitBlt(baked, -left, 0);
return { image: cropped, x: left, top };
}
/** At an end with nowhere to go, overshoot a little past it and come back. */
private bounce(delta: -1 | 1): void {
const count = this.itemList.length;
if (!this.lastBox || !count) return;
const layout = this.layout(this.lastBox);
const pitch = layout.heights[delta > 0 ? count - 1 : 0]!;
const amount = Math.min(MAX_BOUNCE, Math.round(pitch * BOUNCE_FRACTION));
if (amount > 0) this.scrollMotion.bounce(delta * amount);
}
private isSelectable(index: number): boolean {
return this.options.isSelectable?.(this.itemList[index]!) ?? true;
}
/** The next selectable index after `from` in direction `delta`; from null, the first (or last) selectable. */
private nextSelectable(from: number | null, delta: -1 | 1): number | null {
const count = this.itemList.length;
let index = from === null ? (delta > 0 ? 0 : count - 1) : from + delta;
for (; index >= 0 && index < count; index += delta) {
if (this.isSelectable(index)) return index;
}
return null;
}
/** Resolve a stored selection: null stays null only when the caller deselected. */
private settle(index: number | null): number | null {
if (index === null) return this.deselected ? null : this.nextSelectable(null, 1);
return this.resolve(index);
}
/** Clamp an index into range and onto a selectable row (nearest below, else nearest above). */
private resolve(index: number): number | null {
if (!this.itemList.length) return null;
const clamped = Math.max(0, Math.min(this.itemList.length - 1, index | 0));
if (this.isSelectable(clamped)) return clamped;
return this.nextSelectable(clamped, 1) ?? this.nextSelectable(clamped, -1);
}
/** Re-validate the selection against the current items (they may have been edited in place). */
private reconcile(): void {
this.selected = this.settle(this.selected);
}
private layout(box: MenuBox): MenuLayout {
const tops: number[] = [];
const heights: number[] = [];
let total = Math.max(0, (box.padTop ?? 0) | 0);
for (const item of this.itemList) {
const height = Math.max(0, this.options.getHeight(item, box.width) | 0);
tops.push(total);
heights.push(height);
total += height;
}
if (this.itemList.length) total -= this.options.rowGap ?? 0;
total += Math.max(0, (box.padBottom ?? 0) | 0);
return { tops, heights, total };
}
/**
* Where the viewport's top rests to show row `index` from its start: the
* row's top, or for the first row the content's, so the padding above it
* shows too.
*/
private restTop(layout: MenuLayout, index: number): number {
return index === 0 ? 0 : layout.tops[index]!;
}
private maxScroll(layout: MenuLayout, viewportHeight: number): number {
return Math.max(0, layout.total - viewportHeight);
}
/** Scroll the viewport so the selected row is fully inside it, aligning the top to a row edge when it moves. */
private ensureVisible(layout: MenuLayout, viewportHeight: number): void {
if (this.selected === null) {
this.scrollY = Math.max(0, Math.min(this.maxScroll(layout, viewportHeight), this.scrollY));
return;
}
const gap = this.options.rowGap ?? 0;
const selected = this.selected;
const last = this.itemList.length - 1;
const top = layout.tops[selected]!;
const bottom = top + layout.heights[selected]! - gap;
// The content's padding counts as part of its end rows: showing the
// first row shows the padding above it, and the last the padding below.
const startOf = (index: number) => this.restTop(layout, index);
const endOf = (index: number) => index === last ? layout.total : layout.tops[index]! + layout.heights[index]! - gap;
// Keep the neighbors in view too when all three fit, so the user sees
// what the next step will reach.
const contextTop = startOf(Math.max(0, selected - 1));
const contextBottom = endOf(Math.min(last, selected + 1));
const paddedFits = endOf(selected) - startOf(selected) <= viewportHeight;
const fits = contextBottom - contextTop <= viewportHeight;
const wantTop = fits ? contextTop : paddedFits ? startOf(selected) : top;
const wantBottom = fits ? contextBottom : paddedFits ? endOf(selected) : bottom;
let target = this.scrollY;
if (wantTop < target) {
target = wantTop;
} else if (wantBottom > target + viewportHeight) {
// A row taller than the viewport shows from its top.
target = Math.min(top, wantBottom - viewportHeight);
// Snap to the first row that starts inside the viewport: the wanted
// rows still fit (their bottom is within viewportHeight of that top).
for (let index = 0; index <= selected; index++) {
if (startOf(index) >= target) {
target = startOf(index);
break;
}
}
}
// Never scroll past the end (setItems can leave the viewport there when
// rows are removed or inserted above the selection): pull back to the
// first row top that still shows the last row, so no partial row starts
// the list. The selected row stays visible, since it ends by the list's end.
const maxScroll = this.maxScroll(layout, viewportHeight);
if (target > maxScroll) {
const aligned = layout.tops.map((_, index) => startOf(index)).find((rowTop) => rowTop >= maxScroll);
target = aligned !== undefined && aligned <= target ? aligned : maxScroll;
}
this.scrollY = Math.max(0, target);
}
/** With nothing selectable, up/down page the content by rows. Returns false at the end being scrolled past. */
private scrollContent(delta: -1 | 1): boolean {
if (!this.lastBox) return false;
const layout = this.layout(this.lastBox);
const maxScroll = this.maxScroll(layout, this.lastBox.height);
const stops = layout.tops.map((_, index) => this.restTop(layout, index));
if (delta > 0) {
if (this.scrollY >= maxScroll) return false;
const next = stops.find((top) => top > this.scrollY);
this.scrollY = Math.min(maxScroll, next ?? maxScroll);
} else {
if (this.scrollY <= 0) return false;
let previous = 0;
for (const top of stops) if (top < this.scrollY) previous = top;
this.scrollY = Math.max(0, previous);
}
return true;
}
}