> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embededitor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Menu and Reads

> Show a menu item or tap its ring from code, and read the state, the size, the item and the tool.

`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](https://docs.embededitor.com/api-reference/commands/overview.md#get-the-handle).

## Menu

```ts theme={"dark"}
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](https://docs.embededitor.com/api-reference/commands/adjust.md#adjusts-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.

```ts select.ts theme={"dark"}
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.

```ts toggle.ts theme={"dark"}
await editor.menu.toggle({ item: 'FILTER' }); // the filter off
await editor.menu.toggle({ item: 'FILTER' }); // back, as it was
```

## Read

```ts theme={"dark"}
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](https://docs.embededitor.com/api-reference/commands/adjust.md#reads). `screenshot()` is the exception: it waits its turn and resolves, as a command does. `options()` is Annotate's: see [read.options()](https://docs.embededitor.com/api-reference/commands/annotate.md#read-options).

**state()** `EditState | null`

The edit as Save would keep it now, in the saved state's version 3. See [EditState](https://docs.embededitor.com/api-reference/state.md).

**size()** `\{ 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`.

**item()** `EmbedEditorMenuItem | null`

The menu item shown.

**selection()** `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.

**tool()** `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.

**screenshot()** `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`.

```ts screenshot.ts theme={"dark"}
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`](https://docs.embededitor.com/api-reference/commands/for-ai) waits its turn instead, after the commands called before it, and resolves to its value:

```ts read.ts theme={"dark"}
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'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.