# Visual designer (pyzed.designer)

> API reference for pyzed.designer: run, open and build forms from Python code, and register toolbox components and templates.

Source: https://albakore.github.io/pyzed/reference/designer/

<!-- Generated by docs/scripts/gen_api.py. Edit docs/scripts/api_docs_en.py. -->

`pyzed.designer` is the code side of the [visual designer](https://albakore.github.io/pyzed/editor/): run `.pzform` files,
open forms as windows, build forms in code, and extend the toolbox with your own components and
templates. [Designed components](https://albakore.github.io/pyzed/editor/component-designer/) (`.pzcomp`) are loaded from here too.

```python
from pyzed import designer

designer.run("ui/main.pzform", reload=True)
```

## Running forms

### `run`

```python
run(path, *, reload=None, splash=None)
```

Runs the form at `path` with all the logic wired in the designer.

`reload=True` turns on hot reload: saving the form (from the designer or by hand)
or its handlers module updates the running window without restarting it. `None`
follows `PYZED_RELOAD`, like `pz.run`. `splash` (a `pz.Splash`) is shown before
the form's window opens (see `App.splash`).

### `load`

```python
load(path)
```

Reads a `.pzform` file.

### `open_form`

```python
open_form(path)
```

Loads a `.pzform` and its handlers into a `FormApp` ready to `run()` or `screenshot()`.

If the form belongs to a project (see `pyzed.project`), the project is activated first
so its handlers can import the backend and the packages of its `.venv`.

### `open_window`

```python
open_window(form, *, data=None, handlers=None, folder=None)
```

A `Command` that opens `form` in a new window (see `form_window` for the arguments).

### `form_window`

```python
form_window(form, *, data=None, handlers=None, folder=None)
```

A `FormWindow` for `form` (a `.pzform` path or name, or a `Form`), ready to open.

A form loaded from a file gets its handlers module; a `Form` built in code uses
`handlers` (a dict of functions). `data` reaches the new form as `form.data`.

### `new_form`

```python
new_form(
    path,
    *,
    title=None,
    template='blank',
    width=None,
    height=None,
    overwrite=False,
)
```

Creates `path` (`.pzform` added if missing) and its handlers module from `template`.

The form is named after the file (`order-details.pzform` -> `OrderDetails`).

Returns the form's path. Raises `FileExistsError` if it exists, unless `overwrite`.

### `save`

```python
save(form, path)
```

Writes `form` to `path` (`.pzform` is added when there is no suffix).

### `open_document`

```python
open_document(path)
```

Opens a `.pzform` as a `Document`, a `.pzcomp` as a `SceneDocument` or a `.pzshad` as a
`ShaderDocument`.

### `design`

```python
design(path=None, *, theme=None)
```

Opens the visual designer, optionally on a `.pzform` file (created on first save).

## Forms and controls

### `Form`

```python
@dataclass
class Form(name='Form1', title='Form1', width=640.0, height=420.0, theme='One Dark', accent=None, background=None, radius=None, font_size=14.0, resizable=True, grid=8, style={}, controls=[], events={}, code=None, animations=[], autoplay='')
```

A window designed visually: its settings, its controls (in z-order) and its events.

`theme` is any registered theme name; `accent`, `radius` and `font_size`
tweak it without writing a theme file. `style` is the form's global style
(`pz.Style.to_dict()`), applied to the whole window. `grid` is the designer's snapping step.

**Methods and properties**

#### `Form.get`

```python
Form.get(name)
```

Returns the control called `name`, or `None` if there is none.

#### `Form.names`

```python
Form.names()
```

Returns the names of all controls, in z-order.

#### `Form.children`

```python
Form.children(name)
```

The controls directly inside `name` (the form itself when `None`), in z-order.

#### `Form.descendants`

```python
Form.descendants(name)
```

Every control inside `name`, at any depth (parents before their children).

#### `Form.ancestors`

```python
Form.ancestors(name)
```

The containers holding `name`, nearest first.

#### `Form.walk`

```python
Form.walk(parent=None, depth=0)
```

`(control, depth)` in drawing order: each control, then what it contains.

#### `Form.is_inside`

```python
Form.is_inside(name, container)
```

Whether control `name` is inside `container`, at any depth.

#### `Form.unique_name`

```python
Form.unique_name(base)
```

The first free `base1`, `base2`... (Visual Basic style).

#### `Form.add`

```python
Form.add(control)
```

Appends `control` (on top of the z-order) and returns it.

#### `Form.remove`

```python
Form.remove(names)
```

Removes controls and everything inside them.

#### `Form.rename`

```python
Form.rename(old, new)
```

Renames a control and returns the name actually used (made unique and valid).

#### `Form.reorder`

```python
Form.reorder(names, where)
```

Moves controls to the `"front"` or `"back"` of the z-order.

#### `Form.to_dict`

```python
Form.to_dict()
```

Returns the form as JSON-ready data: `{"format", "form": settings, "controls": [...]}`.

#### `Form.from_dict`

```python
@classmethod
Form.from_dict(data)
```

Builds a form from saved `data` (see `to_dict`), ignoring unknown settings and repairing broken parents; raises `ValueError` if it is not a Pyzed form.

#### `Form.to_json`

```python
Form.to_json()
```

Returns the form as indented JSON text (the contents of a `.pzform` file).

#### `Form.from_json`

```python
@classmethod
Form.from_json(text)
```

Builds a form from the JSON `text` of a `.pzform` file.

#### `Form.copy`

```python
Form.copy()
```

Returns a deep copy of the form and its controls.

### `Control`

```python
@dataclass
class Control(name, type, x=0.0, y=0.0, width=100.0, height=28.0, props={}, events={}, anchor=('left', 'top'), visible=True, enabled=True, locked=False, parent=None, layout={}, style={}, animations=[], bind='', rules={}, hidden_in_editor=False)
```

One component placed on a form.

`x`, `y`, `width` and `height` are in logical pixels relative to the form's
client area, or to the top-left corner of `parent` when the control sits inside a
container (a panel, a group box, a flex row...). `props` holds the component's own
properties (`text`, `checked`...) and `events` maps event names (`"click"`) to
handler function names. `layout` holds options read by the parent's layout, such as
`grow` in a flex row or `span` in a grid. `style` holds CSS-like style properties
(`pz.Style.to_dict()`: background, border, radius, font...) drawn on top of the props.
`animations` lists the control's animations (see `designer.motion`). `bind` names the
field of `form.data` the control shows (and edits, for inputs), and `rules` what its
value must be (see `designer.binding`). `hidden_in_editor` hides it on the designer's canvas only
(the outline's eye with the "editor" setting); the running form ignores it.

**Methods and properties**

#### `Control.min_size`

```python
Control.min_size  # property
```

`(min_width, min_height)` from `layout` (`0` means no limit).

#### `Control.max_size`

```python
Control.max_size  # property
```

`(max_width, max_height)` from `layout` (`0` means no limit).

#### `Control.pivot`

```python
Control.pivot  # property
```

The point rotation and scale turn around, and that stays put when a size limit stops the control from stretching: `(0, 0)` is the top-left corner, `(0.5, 0.5)` (the default) the center.

#### `Control.rect`

```python
Control.rect  # property
```

The control's `(x, y, width, height)`, relative to its parent (or the form).

#### `Control.to_dict`

```python
Control.to_dict()
```

Returns the control as JSON-ready data; empty `parent`, `layout` and `style` are left out.

#### `Control.from_dict`

```python
@classmethod
Control.from_dict(data)
```

Builds a control from saved `data`, ignoring unknown keys and invalid anchors.

#### `Control.copy`

```python
Control.copy()
```

Returns a deep copy of the control.

### `Event`

```python
@dataclass
class Event(sender, name, value=None)
```

What a handler receives besides the form: who raised it, which event and its value.

### `FormApp`

```python
class FormApp
```

A form as the main application window.

`path` (set by `open_form`) is the `.pzform` file; with hot reload on, saving it
or its handlers module updates the running window.

**Methods and properties**

#### `FormApp.on_start`

```python
FormApp.on_start()
```

Watches the form and its handlers module for hot reload (when it is on), then raises `load`.

### `FormWindow`

```python
class FormWindow
```

A form in an extra window (`form.open(...)`, `designer.open_window` and the designer's preview).

**Methods and properties**

#### `FormWindow.on_open`

```python
FormWindow.on_open()
```

Raises the form's `load` event when the window opens.

### `Document`

```python
class Document
```

A form open in the designer.

`code` is the text of the handlers module, kept in memory and written next to
the form on `save`. `selection` holds control names, primary first.

**Methods and properties**

#### `Document.clipboard`

```python
Document.clipboard  # property
```

The copied controls (as `Control.to_dict()` data), shared by every document.

#### `Document.open`

```python
@classmethod
Document.open(path)
```

Loads the form at `path` and the text of its handlers module (if the file exists) into a new document.

#### `Document.code_path`

```python
Document.code_path  # property
```

Where the handlers module is saved, or `None` while the form has no file.

#### `Document.display_name`

```python
Document.display_name  # property
```

The name shown for the document: its file name, or `<form name>.pzform` if unsaved.

#### `Document.save`

```python
Document.save(path=None)
```

Writes the form and its handlers module; returns the form path.

#### `Document.commit`

```python
Document.commit(group=None)
```

Records an undo step after an edit (`group` merges repeated edits of one field).

#### `Document.undo`

```python
Document.undo()
```

Goes back one undo step; returns `False` if there was nothing to undo.

#### `Document.redo`

```python
Document.redo()
```

Redoes one undone step; returns `False` if there was nothing to redo.

#### `Document.selected`

```python
Document.selected  # property
```

The selected controls, primary first (names that no longer exist are skipped).

#### `Document.primary`

```python
Document.primary  # property
```

The primary (first) selected control, or `None` when nothing is selected.

#### `Document.select`

```python
Document.select(names, *, add=False)
```

Selects the controls `names` (one name, several, or `None` for none); unknown names are ignored.

#### `Document.select_all`

```python
Document.select_all()
```

Selects every control of the form.

#### `Document.is_selected`

```python
Document.is_selected(name)
```

Whether the control `name` is selected.

#### `Document.add`

```python
Document.add(type_, x, y, width=None, height=None, *, snap=True, parent=None)
```

Places a new `type_` control (snapped to the grid) and selects it.

#### `Document.rects`

```python
Document.rects()
```

The absolute rectangle of every control (see `layout.resolve`).

#### `Document.can_contain`

```python
Document.can_contain(container, name)
```

Whether control `name` can be moved into `container` (`None` is the form, which takes anything): it must be a container other than the control itself and not inside it.

#### `Document.reparent`

```python
Document.reparent(names, parent, *, index=None, at=None, commit=True, rects=None)
```

Moves controls into `parent` (or onto the form with `None`), keeping them where they are.

#### `Document.wrap`

```python
Document.wrap(type_, names=None, props=None)
```

Puts controls (the selection by default) inside a new container of `type_` around them, with `props` set on it (an invisible panel for a group).

#### `Document.ungroup`

```python
Document.ungroup(names=None)
```

Takes the children out of the selected containers (`names`), where they are on screen, and removes the emptied containers; the children become the selection. Returns the removed containers' names.

#### `Document.move_out`

```python
Document.move_out(name)
```

Moves a control out of its container, into the container's own parent.

#### `Document.set_layout`

```python
Document.set_layout(name, key, value)
```

Sets an option the parent's layout reads (`grow`, `span`).

#### `Document.delete`

```python
Document.delete()
```

Removes the selected controls (and what is inside them); returns the removed names.

#### `Document.copy`

```python
Document.copy()
```

Copies the selection, with whatever is inside the selected containers.

#### `Document.clipboard_text`

```python
Document.clipboard_text()
```

The copied controls as JSON for the system clipboard, so another form, another Pyzed Design window or a text file can take them (see `paste_text`).

#### `Document.parse_clipboard`

```python
@staticmethod
Document.parse_clipboard(text)
```

The controls in clipboard `text` written by `clipboard_text`, or `None` when it holds something else. Controls of a type this Pyzed does not know are left out.

#### `Document.paste_text`

```python
Document.paste_text(text, offset=16)
```

Pastes the controls in system clipboard `text` (see `clipboard_text`); returns the new names, or `None` when the text holds no Pyzed controls.

#### `Document.cut`

```python
Document.cut()
```

Copies the selection to the clipboard and deletes it; returns how many controls were copied.

#### `Document.paste`

```python
Document.paste(offset=16)
```

Adds copies of the clipboard (shifted by `offset`) without their events; they keep their names when those are free in this form.

#### `Document.duplicate`

```python
Document.duplicate()
```

Pastes a copy of the selection right away, leaving the clipboard as it was; returns the new names.

#### `Document.size`

```python
Document.size  # property
```

The form's `(width, height)` in pixels.

#### `Document.nudge`

```python
Document.nudge(dx, dy)
```

Moves the selected controls (those not placed by a layout) by `dx`, `dy` pixels, kept inside their container when they share one; repeated nudges merge into one undo step.

#### `Document.align`

```python
Document.align(edge, *, to_form=False)
```

Aligns the selected controls on `edge` (see `geometry.align`): to each other, or to the form with `to_form` or when only one control is selected.

#### `Document.center`

```python
Document.center(axis='both')
```

Centers the selection (as a group) in the form.

#### `Document.distribute`

```python
Document.distribute(axis)
```

Spaces the selected controls evenly along `axis` (see `geometry.distribute`).

#### `Document.same_size`

```python
Document.same_size(which='both')
```

Gives the selected controls the primary one's width, height or both (`which`).

#### `Document.snap_to_grid`

```python
Document.snap_to_grid()
```

Snaps the selected controls (or all of them if nothing is selected) to the form's grid.

#### `Document.reorder`

```python
Document.reorder(where)
```

Moves the selected controls in the z-order (`where`: see `Form.reorder`).

#### `Document.set_rect`

```python
Document.set_rect(name, rect, *, group=None)
```

Sets the position and size of control `name` from `rect` `(x, y, width, height)`, rounded to whole pixels; edits with the same `group` merge into one undo step.

#### `Document.set_prop`

```python
Document.set_prop(name, key, value)
```

Sets property `key` of control `name` to `value` (repeated edits merge into one undo step).

#### `Document.set_style`

```python
Document.set_style(name, key, value)
```

Sets one style property of a control, or of the form's global style when `name` is `None`; `None` removes it.

#### `Document.set_animations`

```python
Document.set_animations(name, animations, *, group=None)
```

Replaces the animations of control `name` (see `designer.motion`). Edits with the same `group` in a row undo together (typing a duration).

#### `Document.set_clip`

```python
Document.set_clip(clip, *, old=None, group=None)
```

Stores the `pz.Clip` `clip` in the form (in place of the clip `old` when it is renamed).

#### `Document.remove_clip`

```python
Document.remove_clip(name)
```

Removes the clip `name` (and stops it playing when the form opens).

#### `Document.set_autoplay`

```python
Document.set_autoplay(name)
```

Plays the clip `name` when the form opens (`""`: none).

#### `Document.clear_style`

```python
Document.clear_style(name)
```

Removes every style property of a control (or of the form's global style).

#### `Document.set_field`

```python
Document.set_field(name, key, value)
```

Sets a `Control` attribute (x, y, width, height, visible, enabled, locked, anchor); a container's new width or height moves what is inside it as its anchors say.

#### `Document.set_bind`

```python
Document.set_bind(name, bind)
```

Binds control `name` to the field (or, for display controls, the expression) `bind` of `form.data`; `None` or `""` unbinds it.

#### `Document.set_rule`

```python
Document.set_rule(name, rule, value)
```

Sets validation `rule` (`required`, `min_length`, `pattern`...) of control `name`; `None`, `""` or `False` removes it.

#### `Document.toggle_anchor`

```python
Document.toggle_anchor(name, edge)
```

Adds `edge` to the anchors of control `name`, or removes it if it was there.

#### `Document.parent_size`

```python
Document.parent_size(name)
```

The design size of what control `name` is anchored to: its container, or the form.

#### `Document.set_anchor`

```python
Document.set_anchor(name, anchor, *, move=False, margin=0.0)
```

Anchors control `name` with a preset (`"top_right"`, `"full"`...) or edges. With `move` it is also moved (and, on stretched axes, sized) to where the anchor points, `margin` pixels in.

#### `Document.set_offset`

```python
Document.set_offset(name, side, value)
```

Sets the distance from the `side` (`left`, `top`, `right`, `bottom`) of the container to control `name`; the opposite side stays where it is, so the control grows or shrinks.

#### `Document.set_pivot`

```python
Document.set_pivot(name, x, y)
```

Sets the pivot of control `name` (`0` to `1` on each axis; the center is the default).

#### `Document.set_form`

```python
Document.set_form(key, value)
```

Sets attribute `key` of the form (a new `name` is made a valid identifier first).

#### `Document.reflow`

```python
Document.reflow(parent, size)
```

After the form (`parent` `None`) or container `parent` was resized from `size`, moves and sizes what is inside it the way the anchors say (unless `follow_anchors` is off).

#### `Document.rename`

```python
Document.rename(old, new)
```

Renames a control, its selection entry and the handlers that follow the naming convention.

#### `Document.owner`

```python
Document.owner(name)
```

The display name and event map of a control, or of the form when `name` is `None`.

#### `Document.events_of`

```python
Document.events_of(name)
```

Returns the events of control `name`, or the form's events when `name` is `None`.

#### `Document.wire`

```python
Document.wire(name, event)
```

Connects `event` to a handler (creating its stub if needed) and returns the function name.

#### `Document.unwire`

```python
Document.unwire(name, event, *, delete_code=False)
```

Disconnects `event`; with `delete_code` an untouched stub is removed too.

#### `Document.rename_handler`

```python
Document.rename_handler(old, new)
```

Points the events wired to handler `old` at `new` (after its function was renamed in the code); returns whether any event used it.

#### `Document.handler_source`

```python
Document.handler_source(handler)
```

Returns the source of `handler` in the code, or a new stub if it is not there yet.

#### `Document.set_handler_source`

```python
Document.set_handler_source(handler, source)
```

Replaces one handler's code (raises `SyntaxError` and changes nothing if it is invalid).

#### `Document.set_code`

```python
Document.set_code(source)
```

Replaces the whole text of the handlers module and marks the document as changed.

## Data binding and validation

### `check`

```python
check(value, rules, type_='input')
```

The message of the first rule `value` breaks, or `None` when it passes them all.

`required` (a checked box for check boxes and switches), `min_length`, `max_length`, `pattern`
(a regular expression the whole text must match), `min` and `max`. `message`, when set, replaces
the built-in message. Empty values only fail `required`.

### `translate`

```python
translate(value, language=None)
```

`value` with `@key` texts looked up in the current (or given) language; lists are translated item by
item and `@@` stands for a literal `@`.

### `read`

```python
read(data, path, default=None)
```

The field at `path` in `data` (dicts, lists and objects), or `default` when it is missing.

### `write`

```python
write(data, path, value)
```

Sets the field at `path` in `data`, creating missing dicts on the way.

### `has`

```python
has(data, path)
```

Whether `data` has a field at `path`.

### `evaluate`

```python
evaluate(expression, data, **extra)
```

The value of `bind` for `data`: the field when it is a path, else the Python expression evaluated
over the data's fields. Raises on a missing field or a bad expression.

### `bound_prop`

```python
bound_prop(type_)
```

The property a control of `type_` binds (`None` if it cannot be bound).

### `two_way`

```python
two_way(type_)
```

Whether a control of `type_` writes the user's changes back to the data.

### `rules_for`

```python
rules_for(type_)
```

The validation rules that make sense for `type_` (none for display controls).

### `load_texts`

```python
load_texts(path)
```

Loads the translation catalogs of the form at `path`: `locales/` next to it and in the folders
above, up to the project root. Returns the languages found.

### `BIND_PROPS`

The property each control type binds, and whether the user edits it (two-way): `{type: (property, two_way)}`.

## Toolbox

### `Component`

```python
@dataclass
class Component(type, label, icon, category, render, size=(120, 28), props=(), events=(), description='', visual=True, container=None, child_layout=(), children=(), role=None)
```

A toolbox entry: how a control of this `type` looks, behaves and is configured.

**Methods and properties**

#### `Component.default_event`

```python
Component.default_event  # property
```

The event opened by double-clicking the control in the designer.

#### `Component.all_events`

```python
Component.all_events  # property
```

The control's own events followed, for visual components, by the common mouse events.

#### `Component.defaults`

```python
Component.defaults()
```

Returns a new dict of the default value of each property, by name.

#### `Component.prop`

```python
Component.prop(name)
```

Returns the property called `name`, or `None` if the component has none.

#### `Component.create`

```python
Component.create(name, x=0, y=0, width=None, height=None)
```

A new control of this type with default properties.

### `Prop`

```python
@dataclass
class Prop(name, kind, default=None, label='', choices=(), min=None, max=None, step=1.0, group='Appearance', type='', accept='')
```

A property shown in the designer's property grid.

`kind` picks the editor: text, multiline, number, bool, color, choice (from
`choices`), list (one item per line), rows (comma-separated rows, the first one the
header), icon (a Lucide icon name), file or folder (a path with a button that opens the
system's dialog; `accept` names the kind of file, like `"image"`, or its extensions,
like `"wgsl pzshad"`) or typed (any annotation in `type`: unions, optionals, dicts,
tuples...).

**Methods and properties**

#### `Prop.title`

```python
Prop.title  # property
```

The label shown in the property grid: `label`, or the name with underscores as spaces.

### `RenderContext`

```python
class RenderContext
```

What a component's `render` needs: the theme and a way to raise events.

`live` is `False` in the designer, where callbacks are inert placeholders so
controls look enabled but do nothing.

**Methods and properties**

#### `RenderContext.on`

```python
RenderContext.on(control, event, prop=None)
```

A callback for `event`; when `prop` is given the value is also stored there.

#### `RenderContext.set`

```python
RenderContext.set(control, prop, value)
```

Stores `value` in `prop` of a running control without raising an event (a tree's open folders).

#### `RenderContext.key`

```python
RenderContext.key(control)
```

A stable id for widgets with internal state (editors, inputs).

### `register`

```python
register(component)
```

Adds (or replaces) a component in the toolbox.

### `component`

```python
component(type_)
```

Returns the registered component for `type_`; raises `KeyError` listing the known types.

### `all_components`

```python
all_components()
```

Returns every registered component, in registration order.

### `categories`

```python
categories()
```

Returns the registered components grouped by `category` (toolbox sections), in registration order.

### `Template`

```python
@dataclass
class Template(name, label, icon, description, build=None, size=(640, 420), handlers=(), form=None)
```

A starting point for new forms: a `build` function that fills an empty `Form`, or a saved form.

### `register_template`

```python
register_template(template)
```

Adds (or replaces, by name) a template offered in the "New form" dialog; returns it.

### `templates`

```python
templates()
```

Returns the registered form templates, in registration order.

## Designed components

### `new_component`

```python
new_component(
    name='Component1',
    path=None,
    *,
    width=240,
    height=120,
    label='',
    icon='component',
    category='Custom',
    description='',
    extends=None,
)
```

A new designed component (not saved yet; call `save()`): its scene and an empty class.

`extends` is the `.pzcomp` of a component to inherit from: the new class derives
from it and starts with its controls, properties, events and methods.

### `load_component`

```python
load_component(path)
```

Imports the class of the component saved at `path` (fresh, so edits are picked up).

Defining the class registers it in the toolbox, replacing an older version. Returns
the class, or `None` (with the reason in `errors`) if its code fails to import.

### `import_component`

```python
import_component(scene)
```

The class of the designed component saved at `scene`, to inherit from it.

A relative path is relative to the module calling it, so a component can extend
another one next to it:

```python
Rating = import_component("rating.pzcomp")

class BigRating(Rating, scene="big_rating.pzcomp"):
    ...
```

The class is imported once and reused until its code changes.

### `discover`

```python
discover(root=None, *, fresh=True)
```

Imports every designed component under `root` (the current folder by default).

Components may use each other, so a failed import is retried once the others
loaded (`errors` keeps what still failed). With `fresh=False` a component whose code
did not change since it was last imported is kept as it is.

### `SceneDocument`

```python
class SceneDocument
```

A component open in the designer: its scene, its class code, selection and undo.

Every command of `Document` works (placing, moving, aligning controls...). Events
of controls become methods of the class (`def ok_click(self, event)`), and the
component's own events are its lifecycle methods (`setup`, `on_mount`...).
Properties and custom events are read from the class and written back to it.

**Methods and properties**

#### `SceneDocument.scene`

```python
SceneDocument.scene  # property
```

The component's scene (the document's `form`, typed as a `Scene`).

#### `SceneDocument.base_file`

```python
SceneDocument.base_file  # property
```

The `.pzcomp` this component extends, or `None`.

#### `SceneDocument.base`

```python
SceneDocument.base  # property
```

The scene this component extends, with everything it inherits itself (`None` if none).

#### `SceneDocument.inherited`

```python
SceneDocument.inherited(name)
```

`True` for a control that comes from the base component.

#### `SceneDocument.own_scene`

```python
SceneDocument.own_scene()
```

What this component's own `.pzcomp` holds: its controls, and the inherited ones it changed.

#### `SceneDocument.set_base`

```python
SceneDocument.set_base(path)
```

Makes this component inherit from the one saved at `path` (`None` inherits from nothing).

#### `SceneDocument.base_info`

```python
SceneDocument.base_info()
```

The classes this component inherits from (nearest first) as `(scene file name, class info)`.

#### `SceneDocument.all_members`

```python
SceneDocument.all_members  # property
```

This component's properties and the ones it inherits (bindings can use both).

#### `SceneDocument.info`

```python
SceneDocument.info  # property
```

The class as last parsed (the last good parse while the code has a syntax error).

#### `SceneDocument.code_ok`

```python
SceneDocument.code_ok  # property
```

Whether the class code currently parses (`info` falls back to the last good parse otherwise).

#### `SceneDocument.members`

```python
SceneDocument.members  # property
```

The component's properties and private state as declared in its class, in order (a copy).

#### `SceneDocument.member`

```python
SceneDocument.member(name)
```

Returns the declared property or state called `name`, or `None`.

#### `SceneDocument.unique_member`

```python
SceneDocument.unique_member(base='value')
```

Returns `base` (made an identifier), or `base2`, `base3`... if it is taken by a member, method, control or reserved name.

#### `SceneDocument.add_member`

```python
SceneDocument.add_member(name='', type_='str', default=None, *, public=True, description='')
```

Declares a new property (`public=False` makes it private state).

#### `SceneDocument.update_member`

```python
SceneDocument.update_member(member, **changes)
```

Changes a property (`name`, `type`, `default`, `public`, `description`); returns its name.

#### `SceneDocument.set_member_source`

```python
SceneDocument.set_member_source(name, source)
```

Sets the default of property `name` to the Python expression `source` (`[1, 2]`, `Point(x=1)`...).

#### `SceneDocument.remove_member`

```python
SceneDocument.remove_member(name)
```

Removes property `name` from the class.

#### `SceneDocument.move_member`

```python
SceneDocument.move_member(name, offset)
```

Moves property `name` by `offset` places in the class's declaration order (clamped).

#### `SceneDocument.custom_events`

```python
SceneDocument.custom_events  # property
```

The events the component declares, as `{name: description}` (a copy).

#### `SceneDocument.add_event`

```python
SceneDocument.add_event(name='changed', description='')
```

Declares a new event called `name` (made unique) with `description`; returns its name.

#### `SceneDocument.update_event`

```python
SceneDocument.update_event(name, *, new_name=None, description=None)
```

Renames event `name` to `new_name` (if valid and free) and/or changes its `description`, keeping its place; returns the event's name. Raises `KeyError` if it does not exist.

#### `SceneDocument.remove_event`

```python
SceneDocument.remove_event(name)
```

Removes the declared event `name` from the class.

#### `SceneDocument.set_class_name`

```python
SceneDocument.set_class_name(name)
```

Renames the component's class (made a valid class name) in the code and the scene; returns the new name.

#### `SceneDocument.set_description`

```python
SceneDocument.set_description(text)
```

Sets the component's description, also as its class's docstring.

#### `SceneDocument.set_scene`

```python
SceneDocument.set_scene(key, value)
```

Sets how the component shows in the toolbox (`label`, `icon`, `category`) or its size.

#### `SceneDocument.set_binding`

```python
SceneDocument.set_binding(control, prop, expression)
```

Makes `prop` of `control` follow `expression` (`None` or `""` removes the binding).

#### `SceneDocument.add_method`

```python
SceneDocument.add_method(name='do_something', args='self', doc='')
```

Adds a reusable method (not an event handler) to the class; returns its name.

### `Scene`

```python
@dataclass
class Scene(name='Component1', title='Component1', width=240.0, height=120.0, theme='One Dark', accent=None, background=None, radius=None, font_size=14.0, resizable=False, grid=8, style={}, controls=[], events={}, code=None, animations=[], autoplay='', label='', icon='component', category='Custom', description='', extends='', bindings={})
```

The layout of a designed component: a `Form` whose `name` is the class name.

`bindings` maps a control name to `{control property: expression}`; the
expression (usually a component property, such as `value`, or any Python
expression over them, such as `f"{value} stars"`) is evaluated on every render.

**Methods and properties**

#### `Scene.class_name`

```python
Scene.class_name  # property
```

The name of the component's class (the scene's `name`).

#### `Scene.bound`

```python
Scene.bound(control)
```

Returns the bindings of `control` as `{property: expression}` (empty if it has none).

### `SceneComponent`

```python
class SceneComponent
```

Base class of the components made in the designer's component mode.

`scene` is the `.pzcomp` file with the layout, relative to the module. The
toolbox label, icon, category, description and default size come from the scene
unless the class sets them.

**Methods and properties**

#### `SceneComponent.scene_path`

```python
@classmethod
SceneComponent.scene_path()
```

Returns the `.pzcomp` file the class is tied to, or `None`.

#### `SceneComponent.scene_model`

```python
@classmethod
SceneComponent.scene_model()
```

The scene as currently saved (or previewed by the designer), or `None`.

#### `SceneComponent.ctx`

```python
SceneComponent.ctx  # property
```

A render context for this instance, in the theme of its scene (what `ControlProxy.focus()` needs).

### `render`

```python
render(control, ctx)
```

Draws `control` at its size (its own props, falling back to the component defaults).

A control whose fields, theme, language and animations are the same as last time gets its
last drawing back, so a form with hundreds of controls only rebuilds the ones that changed.
Controls made from a `pz.Component` keep their own cache (see `pyzed.component`).

## Layout helpers

### `align`

```python
align(controls, edge, *, to=None)
```

Lines controls up on `edge` (left, center, right, top, middle, bottom).

With `to` (e.g. the form rectangle) they align to it; otherwise to the bounds of the
selection, or to the form when a single control is given via `to`.

### `distribute`

```python
distribute(controls, axis)
```

Spaces three or more controls evenly along `"horizontal"` or `"vertical"`.

### `same_size`

```python
same_size(controls, which='both', *, reference=None)
```

Gives every control the `"width"`, `"height"` or `"both"` of `reference` (the first one).

### `snap`

```python
snap(value, grid, enabled=True)
```

Rounds `value` to the nearest multiple of `grid` (unchanged if disabled).

### `smart_guides`

```python
smart_guides(rect, others, size, threshold=4.0)
```

Snaps a moving rectangle to the edges and centers of `others` and of the form.

Returns `(dx, dy, lines)`: the correction to apply and the guide lines to draw
(as thin `(x1, y1, x2, y2)` boxes), like the alignment guides of Figma or Qt Designer.

### `anchored`

```python
anchored(control, design, actual)
```

Where a control goes when its form is resized from `design` to `actual` size.

Like WinForms anchors: an edge anchored to the form keeps its distance to that
side; anchored to both sides it stretches; anchored to neither it keeps its
relative position (centered controls stay centered). The control's minimum and
maximum size and its pivot (`Control.layout`) apply too; see `pyzed.anchors.place`.

## Designer app

### `Designer`

```python
class Designer
```

The visual form editor.

### `EditorSettings`

```python
@dataclass
class EditorSettings(theme='', font_family='', font_size=14.0, tab_size=4, hard_tabs=False, convert_indentation=False, backspace_unindent=True, repeat_delay=500.0, repeat_rate=20.0, show_whitespace=False, wrap=False, line_numbers=True, highlight_line=True, autocomplete=True, code_lens=True, inline_diagnostics=True, format_on_apply=False, auto_close=True, folding=True, minimap=True, cursor_shape='bar', cursor_blink=True, cursor_width=2.0, line_height='standard', scrollbar=True, match_brackets=True, selection_highlight=True, hover=True, sticky_scroll=True, ty=True, ruff=True, keymap={})
```

EditorSettings(theme: 'str' = '', font_family: 'str' = '', font_size: 'float' = 14.0, tab_size: 'int' = 4, hard_tabs: 'bool' = False, convert_indentation: 'bool' = False, backspace_unindent: 'bool' = True, repeat_delay: 'float' = 500.0, repeat_rate: 'float' = 20.0, show_whitespace: 'bool' = False, wrap: 'bool' = False, line_numbers: 'bool' = True, highlight_line: 'bool' = True, autocomplete: 'bool' = True, code_lens: 'bool' = True, inline_diagnostics: 'bool' = True, format_on_apply: 'bool' = False, auto_close: 'bool' = True, folding: 'bool' = True, minimap: 'bool' = True, cursor_shape: 'str' = 'bar', cursor_blink: 'bool' = True, cursor_width: 'float' = 2.0, line_height: 'str' = 'standard', scrollbar: 'bool' = True, match_brackets: 'bool' = True, selection_highlight: 'bool' = True, hover: 'bool' = True, sticky_scroll: 'bool' = True, ty: 'bool' = True, ruff: 'bool' = True, keymap: 'Dict[str, str]' = <factory>)

**Methods and properties**

#### `EditorSettings.key_repeat`

```python
EditorSettings.key_repeat  # property
```

The editor's `repeat_delay` and `repeat_rate` (`None` where the system's key repeat stays).

#### `EditorSettings.to_dict`

```python
EditorSettings.to_dict()
```

Returns the settings as a JSON-ready dict.

#### `EditorSettings.from_dict`

```python
@classmethod
EditorSettings.from_dict(data)
```

Builds settings from saved `data`, keeping defaults for missing or invalid values and clamping the tab size, font size and cursor shape to valid ones.

### `History`

```python
class History
```

Snapshots of a form: `push` after an edit, then `undo`/`redo` to move through them.

**Methods and properties**

#### `History.push`

```python
History.push(form, group=None)
```

Records the form's current state; returns `False` if nothing changed.

#### `History.steps`

```python
History.steps  # property
```

How many undo steps there are (a mark for `merge`).

#### `History.merge`

```python
History.merge(mark)
```

Makes every step recorded since `mark` (`steps` before a batch of edits) a single undo step.

#### `History.reset`

```python
History.reset(form)
```

Forgets all undo and redo steps and starts again from `form`'s current state.

#### `History.can_undo`

```python
History.can_undo  # property
```

Whether there is a step to undo.

#### `History.can_redo`

```python
History.can_redo  # property
```

Whether there is an undone step to redo.

#### `History.undo`

```python
History.undo()
```

Steps back one snapshot; returns the previous form (a new object) or `None` if there is none.

#### `History.redo`

```python
History.redo()
```

Steps forward one snapshot; returns the restored form (a new object) or `None` if there is none.

### `theme_for`

```python
theme_for(form, theme_name=None)
```

The theme a form runs with: its base theme (or `theme_name`, to preview it with another one) plus
accent, radius, font and background tweaks.

### `COMMON_EVENTS`

Events every control can handle in the designer's Events dock.

### `FORM_EVENTS`

Events of the form itself (`load`, `close`, `resize`, `key`...).