# View
URL: https://lsd.tools/docs/api-view
Updated: 2026-07-18

`View` is the one presentable surface in LSD, and the symmetry partner of `Entity`: an entity's base
verb is **run**, a view's base verb is **show**. A `View` is a `Configurable`, so its fields are
[`param()`](/docs/tools-params-ports) descriptors (typing, coercion, validation, the JSON schema, the
parameter-changed event — all inherited). On top it adds `@action` buttons, optional data
(`feed` + `to_text` / `to_image`), the one data-linking verb [`watch`](/docs/api-view-watch), and a
JSON state round-trip.

There are two shapes of `View`. **With no `kind`** it is `param()` fields + `@action` — it
renders as a form. A **data view** sets a `kind` (`table`, `chart`, `flowchart`, or a custom one) and
overrides `feed` / `to_text` / `to_image` to render a representation of data. Either way a `View`
never imports GTK: the desktop registers the renderer and LSD stays front-end-agnostic.

## Usage

```python
from lsdtools import View, action, param, views, Engine

class Clip(View):                                  # no kind: params + actions
    cutoff = param(float, default=0.5, min=0.0, max=1.0, label="Cut-off")

    @action(label="Run", style="suggested")
    def run(self):
        ...  # reads self.cutoff

engine = Engine()
assays = my_entity(...); engine.add(assays)
grades = views.table(title="Assays"); engine.add(grades)
grades.watch(assays)          # THE data verb — any order works
engine.run_all()              # the view now holds the output; re-runs refresh it
grades.show()                 # a window, or console text when headless
```

## The View surface

A view links to an entity's **data** with one verb; everything else is presentation and state.

| Method | What it does |
|---|---|
| [`watch(*targets)`](/docs/api-view-watch) | Hold each entity's pipeline output and refresh on re-run. Returns `self`. The one data verb — [drag-drop, the 3D checkbox, "Show in ▸"](/docs/tools-rendering) are all sugar over it. |
| `unwatch(*targets)` | Break the link to an entity (or name). Already-delivered data stays — unwatching does not clear the view. |
| `watched` | The names of the entities this view watches (live: a renamed entity reports its new name), plus any names still pending an entity. |
| `on_output(entity, output)` | Called with a watched entity's fresh output; the default hands it to `feed`. Override for a view that keys several entities at once (a 3D viewer layering by `entity.id`). |
| `feed(data)` | Give the view its data (a `Table`, a payload dict, a graph). Data views store it and redraw; a params-and-actions View has no data, so the base raises. |
| `show(mode="auto")` | Present the view — a window when a front-end is loaded, else the console rendering. `mode` is `"window"`, `"text"`, or `"auto"`. |
| `get_state()` / `apply_state(state)` | A JSON-able snapshot (config values + the `watch` links, keyed by entity **id**) and its inverse — so a restored view re-links to the same entities across a rename and a project reload. |
| `to_text()` / `to_image(path=None, *, width, height)` | Headless renderings for an agent, the CLI, or logs. Data views override; a no-kind View's `to_text` is a params + actions summary. |
| `invoke(name)` / `get_actions()` | Run an `@action` by name (the single dispatch entry for every front-end) and snapshot the declared actions for a renderer to build controls. |

A view attaches to the [`Engine`](/docs/api-engine) alongside entities: `engine.add(view)` then
[`engine.show()`](/docs/api-engine-show) presents them all — *run executes the entities, show presents
the views*. The same `View` a package contributes with [`@tool.view`](/docs/api-tool-view) also runs
standalone through its own `show()`.

## Where to start

**Learn** — [Rendering & payloads](/docs/tools-rendering) · [How a package fits together](/docs/start-architecture) · [Naming: which is which](/docs/tools-glossary)

**API** — [watch](/docs/api-view-watch) · [ViewerPayload](/docs/api-viewerpayload) · [Engine.show](/docs/api-engine-show) · [Tool.view](/docs/api-tool-view)