Visual designer (pyzed.designer)

pyzed.designer is the code side of the visual designer: run .pzform files, open forms as windows, build forms in code, and extend the toolbox with your own components and templates. Designed components (.pzcomp) are loaded from here too.

from pyzed import designer

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

Running forms

run

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

load(path)

Reads a .pzform file.

open_form

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

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

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

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

save(form, path)

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

open_document

open_document(path)

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

design

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

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

Forms and controls

Form

@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

Form.get(name)

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

Form.names

Form.names()

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

Form.children

Form.children(name)

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

Form.descendants

Form.descendants(name)

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

Form.ancestors

Form.ancestors(name)

The containers holding name, nearest first.

Form.walk

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

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

Form.is_inside

Form.is_inside(name, container)

Whether control name is inside container, at any depth.

Form.unique_name

Form.unique_name(base)

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

Form.add

Form.add(control)

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

Form.remove

Form.remove(names)

Removes controls and everything inside them.

Form.rename

Form.rename(old, new)

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

Form.reorder

Form.reorder(names, where)

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

Form.to_dict

Form.to_dict()

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

Form.from_dict

@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

Form.to_json()

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

Form.from_json

@classmethod
Form.from_json(text)

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

Form.copy

Form.copy()

Returns a deep copy of the form and its controls.

Control

@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

Control.min_size  # property

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

Control.max_size

Control.max_size  # property

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

Control.pivot

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

Control.rect  # property

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

Control.to_dict

Control.to_dict()

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

Control.from_dict

@classmethod
Control.from_dict(data)

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

Control.copy

Control.copy()

Returns a deep copy of the control.

Event

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

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

FormApp

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

FormApp.on_start()

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

FormWindow

class FormWindow

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

Methods and properties

FormWindow.on_open

FormWindow.on_open()

Raises the form’s load event when the window opens.

Document

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

Document.clipboard  # property

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

Document.open

@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

Document.code_path  # property

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

Document.display_name

Document.display_name  # property

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

Document.save

Document.save(path=None)

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

Document.commit

Document.commit(group=None)

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

Document.undo

Document.undo()

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

Document.redo

Document.redo()

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

Document.selected

Document.selected  # property

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

Document.primary

Document.primary  # property

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

Document.select

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

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

Document.select_all

Document.select_all()

Selects every control of the form.

Document.is_selected

Document.is_selected(name)

Whether the control name is selected.

Document.add

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

Document.rects()

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

Document.can_contain

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

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

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

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

Document.move_out(name)

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

Document.set_layout

Document.set_layout(name, key, value)

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

Document.delete

Document.delete()

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

Document.copy

Document.copy()

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

Document.clipboard_text

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

@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

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

Document.cut()

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

Document.paste

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

Document.duplicate()

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

Document.size

Document.size  # property

The form’s (width, height) in pixels.

Document.nudge

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

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

Document.center(axis='both')

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

Document.distribute

Document.distribute(axis)

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

Document.same_size

Document.same_size(which='both')

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

Document.snap_to_grid

Document.snap_to_grid()

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

Document.reorder

Document.reorder(where)

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

Document.set_rect

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

Document.set_prop(name, key, value)

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

Document.set_style

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

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

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

Document.remove_clip(name)

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

Document.set_autoplay

Document.set_autoplay(name)

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

Document.clear_style

Document.clear_style(name)

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

Document.set_field

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

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

Document.set_rule(name, rule, value)

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

Document.toggle_anchor

Document.toggle_anchor(name, edge)

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

Document.parent_size

Document.parent_size(name)

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

Document.set_anchor

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

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

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

Document.set_form(key, value)

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

Document.reflow

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

Document.rename(old, new)

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

Document.owner

Document.owner(name)

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

Document.events_of

Document.events_of(name)

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

Document.wire

Document.wire(name, event)

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

Document.unwire

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

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

Document.rename_handler

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

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

Document.set_handler_source(handler, source)

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

Document.set_code

Document.set_code(source)

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

Data binding and validation

check

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

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

read(data, path, default=None)

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

write

write(data, path, value)

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

has

has(data, path)

Whether data has a field at path.

evaluate

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

bound_prop(type_)

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

two_way

two_way(type_)

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

rules_for

rules_for(type_)

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

load_texts

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

@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

Component.default_event  # property

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

Component.all_events

Component.all_events  # property

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

Component.defaults

Component.defaults()

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

Component.prop

Component.prop(name)

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

Component.create

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

A new control of this type with default properties.

Prop

@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

Prop.title  # property

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

RenderContext

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

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

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

RenderContext.set

RenderContext.set(control, prop, value)

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

RenderContext.key

RenderContext.key(control)

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

register

register(component)

Adds (or replaces) a component in the toolbox.

component

component(type_)

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

all_components

all_components()

Returns every registered component, in registration order.

categories

categories()

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

Template

@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

register_template(template)

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

templates

templates()

Returns the registered form templates, in registration order.

Designed components

new_component

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

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

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:

Rating = import_component("rating.pzcomp")

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

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

discover

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

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

SceneDocument.scene  # property

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

SceneDocument.base_file

SceneDocument.base_file  # property

The .pzcomp this component extends, or None.

SceneDocument.base

SceneDocument.base  # property

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

SceneDocument.inherited

SceneDocument.inherited(name)

True for a control that comes from the base component.

SceneDocument.own_scene

SceneDocument.own_scene()

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

SceneDocument.set_base

SceneDocument.set_base(path)

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

SceneDocument.base_info

SceneDocument.base_info()

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

SceneDocument.all_members

SceneDocument.all_members  # property

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

SceneDocument.info

SceneDocument.info  # property

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

SceneDocument.code_ok

SceneDocument.code_ok  # property

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

SceneDocument.members

SceneDocument.members  # property

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

SceneDocument.member

SceneDocument.member(name)

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

SceneDocument.unique_member

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

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

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

SceneDocument.update_member

SceneDocument.update_member(member, **changes)

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

SceneDocument.set_member_source

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

SceneDocument.remove_member(name)

Removes property name from the class.

SceneDocument.move_member

SceneDocument.move_member(name, offset)

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

SceneDocument.custom_events

SceneDocument.custom_events  # property

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

SceneDocument.add_event

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

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

SceneDocument.update_event

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

SceneDocument.remove_event(name)

Removes the declared event name from the class.

SceneDocument.set_class_name

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

SceneDocument.set_description(text)

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

SceneDocument.set_scene

SceneDocument.set_scene(key, value)

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

SceneDocument.set_binding

SceneDocument.set_binding(control, prop, expression)

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

SceneDocument.add_method

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

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

Scene

@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

Scene.class_name  # property

The name of the component’s class (the scene’s name).

Scene.bound

Scene.bound(control)

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

SceneComponent

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

@classmethod
SceneComponent.scene_path()

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

SceneComponent.scene_model

@classmethod
SceneComponent.scene_model()

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

SceneComponent.ctx

SceneComponent.ctx  # property

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

render

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

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

distribute(controls, axis)

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

same_size

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

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

snap

snap(value, grid, enabled=True)

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

smart_guides

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

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

class Designer

The visual form editor.

EditorSettings

@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]’ = )

Methods and properties

EditorSettings.key_repeat

EditorSettings.key_repeat  # property

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

EditorSettings.to_dict

EditorSettings.to_dict()

Returns the settings as a JSON-ready dict.

EditorSettings.from_dict

@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

class History

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

Methods and properties

History.push

History.push(form, group=None)

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

History.steps

History.steps  # property

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

History.merge

History.merge(mark)

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

History.reset

History.reset(form)

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

History.can_undo

History.can_undo  # property

Whether there is a step to undo.

History.can_redo

History.can_redo  # property

Whether there is an undone step to redo.

History.undo

History.undo()

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

History.redo

History.redo()

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

theme_for

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…).