# Views and documents

> The four kinds of document in Pyzed Design and the view each one opens in: the Form view for windows, the Component view for reusable pieces, the Shader view for GPU effects and the code editor for Python.

Source: https://albakore.github.io/pyzed/editor/views/

Pyzed Design edits four kinds of document. Each opens in its own **view**: the same window, but the left dock, the
toolbar, the center and the Properties panel change to fit what you are making. The tab row tells you which view is
in front, and the title bar shows a **Component** or **Shader** badge when it is not a form.

| Document | File | Opens in | Think of it as |
| --- | --- | --- | --- |
| **Form** | `login.pzform` + `login.py` | Form view | A window of your app, like a Visual Basic form or a Qt Designer `.ui`. |
| **Component** | `rating.pzcomp` + `rating.py` | Component view | A reusable piece placed in forms, like a Godot scene or an Unreal widget blueprint. |
| **Shader** | `fire.pzshad` | Shader view | A GPU effect made of nodes, like Godot's visual shaders or Unreal's material editor. |
| **Code and text** | `*.py`, `*.toml`, `*.md`... | Code editor | The Python behind everything, with completion and diagnostics. |

All files are plain text (JSON or Python), so they diff well in git and you can open them in any other editor.

```mermaid
flowchart LR
    N["New (Ctrl+N)"] --> F[Form] & C[Component] & S[Shader]
    F -->|"place it"| C
    F -->|"Shader control"| S
    C -->|"Shader control"| S
    F & C -->|"double-click a control"| K[Code editor]
```

## Form view

**For:** the windows of your app: a login, a settings page, a dashboard, a dialog.

- **Left dock:** the **Toolbox** with every control, and the **Outline** of the form.
- **Center:** the form drawn in a window frame, with a dot grid, handles and smart guides.
- **Right dock:** **Properties** and **Events** of the selection (or of the form when nothing is selected).
- **Run** (<kbd>F5</kbd>) opens the form as a real window with its Python handlers.

Read [The Form view](https://albakore.github.io/pyzed/editor/form-view/) for a guided first form.

## Component view

**For:** pieces you use many times: a star rating, a profile card, a product tile. A component has no window; it lives
inside forms and other components.

- The same toolbox and canvas as a form, but the canvas shows an **accent frame with the class name** instead of a
  window, and the title bar a **Component** badge.
- With nothing selected, **Properties** shows the **Component panel**: the class name, how it shows in the toolbox,
  its typed **properties** and its **methods**. Its **custom events** are in the **Events** tab, below the
  built-in ones.
- **Run** previews the component alone in a window.
- Double-click a component placed on a form to open it in its own tab.

Everything is in [The Component view](https://albakore.github.io/pyzed/editor/component-designer/).

## Shader view

**For:** animated backgrounds, glows, transitions and game visuals drawn by the graphics card.

- **Left dock:** the **Shading** sidebar (every node, by category) and the **Outline** of variables, named values and
  nodes.
- **Center:** three tabs: **Graph** (the nodes), **Preview** (the result large, with a control per variable) and
  **WGSL** (the generated code, read only).
- **Properties:** the settings and inputs of the selected node, of a variable, or of the shader itself.
- **Run** opens the shader in a window that follows your edits.

Start with [The Shader view](https://albakore.github.io/pyzed/editor/shader-view/) in this manual, or go straight to the
[Shading section](https://albakore.github.io/pyzed/shading/).

## Code editor

**For:** the Python of every form and component (their event handlers and methods) and any text file of the project.

- Opens in the **bottom dock** when you double-click a control or an event, press <kbd>F7</kbd> for the whole file, or
  click a file in the Project panel. Each file is a tab of the Code panel.
- Completion, diagnostics, code lens, folding, a minimap, multiple cursors, find and replace, and key bindings you can
  change.

See [Code editor](https://albakore.github.io/pyzed/editor/code-editor/).

## Switching between views

- Every open document is a tab; click one to switch. Each keeps its own selection and undo history.
- Opening a file that is already open switches to its tab.
- Drag a tab out of the window to work on two documents side by side (see [The interface](https://albakore.github.io/pyzed/editor/interface/#document-tabs-and-windows)).

**Code with a syntax error:**

When you leave a form or component, its handler code is applied. If the code doesn't parse, the switch waits until you
fix it, and a notification says why: nothing you wrote is lost.

## From the command line

Pass a file to open it in the right view (it is created on the first save if it doesn't exist):

**uv:**

```bash
uv run pyzed design ui/login.pzform
uv run pyzed design ui/rating.pzcomp
uv run pyzed design shaders/fire.pzshad
```

**pip:**

```bash
pyzed design ui/login.pzform
pyzed design ui/rating.pzcomp
pyzed design shaders/fire.pzshad
```

**python:**

```bash title="macOS / Linux"
python3 -m pyzed design ui/login.pzform
```
```powershell title="Windows (PowerShell)"
py -m pyzed design ui\login.pzform
```