G2 only: You can pair the glasses with a bluetooth keyboard. It will relay key events, and you can use it to type in some apps and to navigate the UI.
216 lines
8.6 KiB
TypeScript
216 lines
8.6 KiB
TypeScript
import { type GrayImage } from "../graphics/image";
|
|
import { type Plane } from "../graphics/plane";
|
|
import { type IconName } from "../graphics/icons";
|
|
import { type LayerActions } from "../ui/layers";
|
|
import { type InProcessAppOptions, type InProcessWindow } from "../ui/shell/in-process-window";
|
|
import { WorkerAppHost } from "../ui/shell/worker-window";
|
|
import { shell, type TrayWidget } from "../ui/shell/shell";
|
|
|
|
/**
|
|
* An app, as seen from outside while it isn't running. Each app directory's
|
|
* index.ts default-exports one of these, and all-apps.ts collects them; the
|
|
* controller and shell reach apps only through this surface. Meant to grow
|
|
* into the sole export of an app package (the boundary for sandboxing and
|
|
* dynamic loading).
|
|
*/
|
|
export type AppDefinition = {
|
|
appId: string;
|
|
/** Launcher-grid and window-title label. */
|
|
title: string;
|
|
/** Launcher-grid icon. */
|
|
icon: IconName;
|
|
/** App-supplied launcher icon renderer; icon remains the fallback. */
|
|
renderIcon?: (size: number) => GrayImage | null;
|
|
/** Open the app's window (or focus it if already open). */
|
|
launch: (ctx: AppContext, params?: AppLaunchParams) => Promise<void>;
|
|
/**
|
|
* Runs once at shell startup, before any launch. For apps that must exist
|
|
* from boot (the launcher registers its pinned window here).
|
|
*/
|
|
boot?: (ctx: AppContext) => void;
|
|
/** False for apps that must not appear in the launcher grid (the launcher itself). */
|
|
showInLauncher?: boolean;
|
|
/**
|
|
* False while the paired glasses can't run the app (absent means they can).
|
|
* It then leaves the launcher grid and what mirrors it: the watch remote and
|
|
* the apps.launch tool. A window restored from before a re-pair still opens,
|
|
* so the app needs to say what's wrong rather than assume it never runs.
|
|
*/
|
|
isSupported?: () => boolean;
|
|
/** Present on the app that handles text shared via the Android share intent. */
|
|
openSharedText?: (ctx: AppContext, title: string, text: string) => void;
|
|
/**
|
|
* Present on the app that supplies the Glanceboard: the sleep-time display
|
|
* the controller shows on a tap or hold while the shell is asleep (see
|
|
* app/g2/glance-host.ts). At most one app provides it.
|
|
*/
|
|
glanceboard?: GlanceboardProvider;
|
|
};
|
|
|
|
/** A board the glance host can show while the shell sleeps. */
|
|
export type GlanceboardProvider = {
|
|
/** Board pixel size; the host centres it in the standard 576x288 band. */
|
|
size: { width: number; height: number };
|
|
/** Whether sleep-time gestures should show the board at all (user setting). */
|
|
isEnabled: () => boolean;
|
|
/** Whether a single tap shows the board (for tapTimeoutMs). */
|
|
showOnTap: () => boolean;
|
|
/** How long a tap or head-tilt keeps the board up. */
|
|
tapTimeoutMs: () => number;
|
|
/** Whether a long-press holds the board up until released. */
|
|
showOnLongPress: () => boolean;
|
|
/** Whether the head-tilt wake goes to the board rather than the regular UI. */
|
|
showOnHeadTilt: () => boolean;
|
|
/** Stereo depth (firmware units; positive is nearer) while the board covers the screen. */
|
|
depth: () => number;
|
|
/** A fresh board; requestRender asks the host to repaint it. */
|
|
createBoard: (requestRender: () => void) => GlanceBoardInstance;
|
|
};
|
|
|
|
export type GlanceBoardInstance = {
|
|
/** The board is about to show: start widgets (subscriptions, hardware). */
|
|
start: () => void;
|
|
/** The board was hidden: stop everything start began. */
|
|
stop: () => void;
|
|
/** Paint the board at its size. */
|
|
paint: () => GrayImage;
|
|
};
|
|
|
|
export type AppLaunchParams = {
|
|
/** Settings-app section deep-link (window menu -> Settings). */
|
|
section?: string;
|
|
};
|
|
|
|
/**
|
|
* Shell/controller services available to an app's launch and boot callbacks,
|
|
* bound to that app's id. This is deliberately the only channel from app
|
|
* definitions back into the controller.
|
|
*/
|
|
export type AppContext = {
|
|
/** The id of the app this context was built for. */
|
|
appId: string;
|
|
/** Every app, in launcher-grid order. */
|
|
apps: readonly AppDefinition[];
|
|
/** Shared layer actions (voice capture, text-setting edits, buzzer, ...). */
|
|
actions: Omit<LayerActions, "requestRender">;
|
|
/** Launch (or focus) any app by id through the shell. */
|
|
launchApp: (appId: string, params?: AppLaunchParams) => Promise<void>;
|
|
/** Uninstall a dynamically registered app, if the app id supports it. */
|
|
uninstallApp: (appId: string) => Promise<void>;
|
|
/** Launch-or-focus a main-thread singleton window keyed by windowId. */
|
|
launchInProcessApp: (
|
|
windowId: string,
|
|
surfaceId: string,
|
|
create: (options: InProcessAppOptions) => InProcessWindow,
|
|
) => Promise<void>;
|
|
/**
|
|
* Open a main-thread singleton window in the background (neither
|
|
* foregrounded nor focused) unless it is open already; `opened` says this
|
|
* call opened it. For windows the shell brings forward itself, such as an
|
|
* app widget's (see inProcessTrayWidget). Hosts that leave it out can't.
|
|
*/
|
|
openInProcessAppInBackground?: (
|
|
windowId: string,
|
|
surfaceId: string,
|
|
create: (options: InProcessAppOptions) => InProcessWindow,
|
|
) => { window: InProcessWindow; opened: boolean };
|
|
/** Get this app's shared worker host, spawning the worker on first use. */
|
|
ensureWorkerHost: (createWorker: () => Worker) => WorkerAppHost;
|
|
/** Submit a window surface's painted frame, as planes (windows created outside launchInProcessApp). */
|
|
submitWindowFrame: (surfaceId: string, planes: Plane[], paintMs: number, frameId: number) => Promise<void>;
|
|
setWindowSurfaceVisible: (surfaceId: string, visible: boolean) => void;
|
|
requestShellRender: () => void;
|
|
appendLog: (message: string) => void;
|
|
/**
|
|
* Register (or clear, with null) the window hosting the on-glasses
|
|
* text-setting editor, so the controller can sync it with the phone-side
|
|
* editor field.
|
|
*/
|
|
setTextEditorHost: (host: TextEditorHost | null) => void;
|
|
};
|
|
|
|
/** See AppContext.setTextEditorHost. */
|
|
export type TextEditorHost = {
|
|
/** Whether the glasses-side text-setting editor is the top layer. */
|
|
isTextEditorOnTop: () => boolean;
|
|
/** Pop the text-setting editor if it is on top; returns whether it was. */
|
|
closeTextEditor: () => boolean;
|
|
requestRender: () => void;
|
|
};
|
|
|
|
/**
|
|
* A tray widget (see Shell.setTrayIcon) whose window is a main-thread
|
|
* singleton app window, opened in the background while the switcher's
|
|
* selection is on it; undefined on hosts that can't do that. `show`, if
|
|
* given, runs each time the selection moves onto the widget, once the
|
|
* window is open, to bring what the widget stands for on screen in it (the
|
|
* shell repaints the window after).
|
|
*/
|
|
export function inProcessTrayWidget(
|
|
ctx: AppContext,
|
|
windowId: string,
|
|
surfaceId: string,
|
|
create: (options: InProcessAppOptions) => InProcessWindow,
|
|
show?: () => void,
|
|
): TrayWidget | undefined {
|
|
const open = ctx.openInProcessAppInBackground;
|
|
if (!open) return undefined;
|
|
return {
|
|
openWindow: () => {
|
|
const { window, opened } = open(windowId, surfaceId, create);
|
|
show?.();
|
|
return { window: window.window, opened };
|
|
},
|
|
};
|
|
}
|
|
|
|
/**
|
|
* Launch-or-focus flow shared by the worker-hosted apps: focus the app's
|
|
* existing window if one is open, otherwise open a window in the app's shared
|
|
* worker (spawned on first launch).
|
|
*/
|
|
export async function launchWorkerAppWindow(
|
|
ctx: AppContext,
|
|
options: {
|
|
/** Must construct the worker with a string-literal path (webpack worker loader). */
|
|
createWorker: () => Worker;
|
|
windowId: string;
|
|
title: string;
|
|
iconLetter: string;
|
|
icon: IconName;
|
|
/**
|
|
* Which existing window counts as "already launched": any window of this
|
|
* app (default), or only options.windowId exactly (multi-window apps like
|
|
* the terminal, where launching should reopen the hub even while other
|
|
* windows are open).
|
|
*/
|
|
matchExistingBy?: "appId" | "windowId";
|
|
/** Deliver watch swipes raw instead of the fallback (see WorkerWindowSpec). */
|
|
acceptsDirectional?: boolean;
|
|
/** Deliver hardware-keyboard keys as keys (see WorkerWindowSpec). */
|
|
acceptsKeys?: boolean;
|
|
},
|
|
): Promise<void> {
|
|
const existing = shell
|
|
.getWindows()
|
|
.find((window) =>
|
|
options.matchExistingBy === "windowId" ? window.windowId === options.windowId : window.appId === ctx.appId,
|
|
);
|
|
if (existing) {
|
|
shell.focusWindow(existing.windowId);
|
|
ctx.requestShellRender();
|
|
return;
|
|
}
|
|
const host = ctx.ensureWorkerHost(options.createWorker);
|
|
host.openWindow({
|
|
windowId: options.windowId,
|
|
title: options.title,
|
|
iconLetter: options.iconLetter,
|
|
icon: options.icon,
|
|
focus: true,
|
|
acceptsDirectional: options.acceptsDirectional,
|
|
acceptsKeys: options.acceptsKeys,
|
|
});
|
|
ctx.appendLog(`launched ${options.windowId}`);
|
|
}
|