Menu and Reads

menu does what a tap in the menu does, and read tells what the editor holds now. The examples call the handle editor. See Get the handle.

menu: {
	closeSection: () => Promise<null>;
	openSection: (input: { section: 'ASPECT' | 'SCALE' }) => Promise<null>;
	select: (input: { item: EmbedEditorMenuItem }) => Promise<null>;
	toggle: (input: {
		item:
			| 'ADJUST'
			| 'AUTO'
			| 'BLACK_POINT'
			| 'BRIGHTNESS'
			| 'BRILLIANCE'
			| 'CONTRAST'
			| 'EXPOSURE'
			| 'FILTER'
			| 'FRAME'
			| 'HIGHLIGHTS'
			| 'SATURATION'
			| 'SHADOWS'
			| 'SHARPNESS'
			| 'VIBRANCE'
			| 'VIGNETTE'
			| 'WARMTH';
	}) => Promise<null>;
};

openSection() and closeSection() open and close Adjust’s Scale and Aspect sections: see Adjust’s sections. An item goes by its name: 'ADJUST' (the crop), 'RESIZE', 'OBFUSCATE', 'FRAME', 'WATERMARK', 'SIGNATURE', 'FILTER', 'AUTO', and the twelve adjustments: 'EXPOSURE', 'BRILLIANCE', 'HIGHLIGHTS', 'SHADOWS', 'CONTRAST', 'BRIGHTNESS', 'BLACK_POINT', 'SATURATION', 'VIBRANCE', 'WARMTH', 'SHARPNESS' and 'VIGNETTE'. 'WATERMARK' and 'SIGNATURE' are in the menu while your mark is there and not fixed. An item that isn’t in the menu rejects with NOT_AVAILABLE: one a prop turned off (enableFilter: false), one the edition doesn’t have, or a mark you didn’t give.

select()

Shows an item, as a tap on it in the menu: its tool opens on the stage. The item already shown stays as it is. The tool’s name doesn’t show over the photo, as it does when the user scrolls the menu. It makes no undo step. While Annotate is open the menu isn’t on screen, so it rejects with NOT_AVAILABLE: call annotate.close() first.

select.ts

await editor.menu.select({ item: 'EXPOSURE' });

const tool = editor.read.tool(); // 'FINETUNE'

toggle()

Turns an item with a ring off and back, as a tap on its ring: a value to zero and back to what it was, a filter, a frame or Auto off and back. It is one undo step, and it doesn’t show the item. The items with a ring: 'ADJUST' (its straightening), 'FRAME', 'FILTER', 'AUTO' and the twelve adjustments. Any other item is INVALID_COMMAND. An item already at zero or off, with nothing to come back to, stays as it is. Auto is the exception: it turns on at the photo’s own amount, once the photo is read. When the photo can’t be read, or its reading takes too long, it rejects with NOT_AVAILABLE and nothing changes.

toggle.ts

await editor.menu.toggle({ item: 'FILTER' }); // the filter off
await editor.menu.toggle({ item: 'FILTER' }); // back, as it was

Read

read: {
	item: () => EmbedEditorMenuItem | null;
	options: (input: { target: { arrow?: number; id: string } | { tool: AnnotateTool } }) => {
		commands: string[];
		style: Record<string, { range: { max: number; min: number }; value: number } | { value: number | string; values: readonly (number | string)[] }>;
	} | null;
	outputSize: () => Size | null;
	screenshot: (input?: { area?: Rect; maxSize?: number }) => Promise<File>;
	section: () => 'ASPECT' | 'MAIN' | 'SCALE' | null;
	selection: () => EmbedEditorSelection;
	size: () => Size | null;
	state: () => EditState | null;
	tool: () => EmbedEditorTool | null;
};

A read answers at once, with no Promise and no turn in the queue. It answers null until the image is on screen (ready), and once the editor has left the page. outputSize() and section() are Adjust’s: see Reads. screenshot() is the exception: it waits its turn and resolves, as a command does. options() is Annotate’s: see read.options().

EditState | null

The edit as Save would keep it now, in the saved state’s version 3. See EditState.

{ width: number; height: number } | null

The size the editor works the image at, in px: the px of every coordinate in the state and in the commands. The same as onLoad’s size.

EmbedEditorMenuItem | null

The menu item shown.

EmbedEditorSelection

What is selected now, as the select event tells it: while Annotate is open, a piece ({ id, kind: 'PIECE' }), a text’s added arrow ({ id, index, kind: 'ARROW' }) or the Numbers’ list ({ kind: 'LIST' }); otherwise Obfuscate’s area by its index; null for nothing. A piece a tap just made is selected, so its id is here for the commands that take one.

EmbedEditorTool | null

The tool open on the stage: 'CROP' for 'ADJUST', 'FINETUNE' for Auto and the adjustments, 'MARK' for the watermark and the signature, the item’s own name for the rest ('FILTER', 'FRAME', 'OBFUSCATE', 'RESIZE'), or 'ANNOTATE' while Annotate is open.

Promise<File>

A picture of the edit as Save makes it, the output size and the marks with no editor around it, as a PNG File: all of it, or an area of it in the output’s px, shrunk to maxSize px on its longer side where it is larger. It is what a model looks at before it marks the photo. An area off the output rejects with INVALID_COMMAND. A mark that can’t be drawn rejects with MARK_FAILED, and a file that can’t be made with EXPORT_FAILED, as output.exportFile; EXPORT_FAILED too when the picture can’t be made from it. Where the browser gives no 2D canvas to draw it on, it rejects with NOT_AVAILABLE.

screenshot.ts

const preview = await editor.read.screenshot({ maxSize: 200 }); // the whole edit, 200 px on its longer side
const corner = await editor.read.screenshot({ area: { x: 0, y: 0, width: 100, height: 100 } }); // a corner, at full size

A read through run waits its turn instead, after the commands called before it, and resolves to its value:

read.ts

editor.menu.select({ item: 'FILTER' });

const now = editor.read.item(); // 'ADJUST': the select waits its turn
const queued = await editor.run({ command: 'read.item' }); // 'FILTER'

Overview

Entry Points

Commands

Reference

Menu

select()

toggle()

Read

​Menu

​select()

​toggle()

​Read

Menu

select()

toggle()

Read