haybale-protokol 0.0.3__tar.gz

haybale_protokol-0.0.3/.gitignore

@@ -0,0 +1,42 @@
+# Patterns below are anchored with a leading slash (/build/) so they match only
+# at the repo root. An unanchored pattern (build/) matches at EVERY depth —
+# including inside barn/, where it would silently exclude your library's own
+# files. See the note at the end of this file before adding patterns.
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging (root only)
+/build/
+/dist/
+*.egg-info/
+*.egg
+
+# Virtual environments (root only)
+/.venv/
+/venv/
+/env/
+
+# Test / type-check caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.tox/
+.coverage
+htmlcov/
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/
+
+# Haywire per-session UI state (open graph, pan/zoom) — not project state
+.haywire/workspace_state.json
+
+# ── Before you add a pattern ────────────────────────────────────────────────
+# Anything ignored inside barn/<your-library>/ will be MISSING for everyone who
+# installs your library — haywire share publishes by git URL, so consumers get
+# a clone of this repo, not a built package. If a pattern is only meant for the
+# repo root, anchor it with a leading slash: /build/ not build/.

haybale_protokol-0.0.3/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.5
+Name: haybale-protokol
+Version: 0.0.3
+Summary: Control protocols for graphs: gates, shared lines and the base for OSC, MIDI and gamepad
+Project-URL: Source, https://github.com/going-haywire/haybale-protokol
+License: MIT
+Keywords: control,gamepad,midi,osc,protocol
+Requires-Python: >=3.12
+Requires-Dist: haywire-core>=0.5.0
+Requires-Dist: nicegui
+Requires-Dist: tomlkit

haybale_protokol-0.0.3/README.md

@@ -0,0 +1,108 @@
+# Protokol
+
+# Protokol
+
+Control protocols for Haywire graphs: OSC now, then MIDI and gamepads, each added by its own
+protocol haybale (`haybale-protokol-osc`, ...). This haybale is the shared base. It has no
+nodes of its own.
+
+## Gates
+
+A graph refers to a **Gate** by name only. The project's Gate file,
+`.haywire/protokol.toml`, is committed with the project and defines each gate:
+
+```toml
+[gates.touchosc-in]
+protocol = "osc"
+direction = "in"        # in, out, or two-way where the protocol has one shared channel
+transport = "udp"
+port = 8000
+bind = "0.0.0.0"        # default: all interfaces
+
+[gates.lights-out]
+protocol = "osc"
+direction = "out"
+port = 9000
+host = "10.0.0.2"
+
+[gates.desk]            # OSC over TCP: we connect to the peer
+protocol = "osc"
+direction = "two-way"   # TCP has one shared channel, so a gate may go both ways
+transport = "tcp"
+role = "client"         # or "server": peers connect to us (on bind, default all interfaces)
+host = "10.0.0.5"
+port = 3032
+framing = "1.1"         # "1.0" length prefix, or "1.1" SLIP (default)
+```
+
+MIDI and gamepad gates name a **Device** (`device = "desk"`). The machine's Device list,
+`~/.haywire/protokol-devices.toml`, maps that name to what the OS calls the hardware.
+
+## Lines
+
+Gates that resolve to the same connection (the same protocol, transport, address and port)
+share one **Line**, the only thing that opens a port. Two gates on one port with different
+bind addresses are two Lines, and the second cannot open (`cannot open: ...`). A Line opens
+with its first user and closes once the last one has left and the grace period has passed
+(setting **Line grace period**, default 2 s), so a graph restart keeps its peers. Lines run on
+their own threads; a slow flow never holds a Line up.
+
+## Editors
+
+| Editor | Slot | What it does | Who may change things |
+|---|---|---|---|
+| **Gates** | left icon bar | The project's gates, with each one's Line and status. Add, edit, delete; "Bind…" for a gate whose device this machine does not know; open the Monitor on a gate. | Edit access |
+| **Monitor** | centre tab | Click a line's eye to watch it; the eye then hides or shows its messages in the output without losing them. Each watched line has its own Clear, Export (JSONL or CSV) and Stop watching; the toolbar's act on all shown lines. Filter by text, pause. Test-send to output gates. "New line…" watches a Line no gate uses yet, and "Save as gate…" keeps it. | Watching open Lines: view access. Opening Lines, test-send, saving gates: edit access |
+| **Device** | right icon bar | Follows the selection: a device, a gate (its options, Line and last values) or a Line. With nothing selected, the machine's Device list. | Editing the Device list: admin access |
+
+The Monitor never slows a Line: each watched source keeps the last 2000 messages (older ones
+drop and are counted), and the output redraws at most five times a second, showing the newest
+300 messages: newest first, or oldest first like a log (the toolbar toggles it; a log follows the
+newest message unless you scroll up to read). Export writes everything the filter keeps.
+
+A gate edited while graphs use it applies when those graphs next start.
+
+## Status texts
+
+Receive and Send nodes report problems on their `status` outlet; nothing crashes the graph:
+
+| Status | Meaning |
+|---|---|
+| `no gate named 'x'` | The Gate file has no such gate |
+| `gate file: ...` | The Gate file cannot be read |
+| `protocol not installed` | No enabled haybale provides the gate's protocol |
+| `unbound gate: no device 'x' on this machine` | The Device list does not know the gate's device |
+| `'x' is an input gate` / `an output gate` | The node uses the gate in the wrong direction |
+| `cannot open: ...` | The port or device could not be opened (for example, already in use) |
+| `gate 'x': ...` | The gate's options are incomplete or wrong, or disagree with another gate on the same Line |
+
+<!-- marketstall:share-url:start -->
+Always the latest (tracks the current branch):
+
+```sh
+https://github.com/going-haywire/haybale-protokol/blob/master/marketstall.toml
+```
+
+Frozen to this version:
+
+```sh
+https://github.com/going-haywire/haybale-protokol/blob/v0.0.3/marketstall.toml
+```
+<!-- marketstall:share-url:end -->
+
+Control protocols for graphs: gates, shared lines and the base for OSC, MIDI and gamepad
+
+## Widgets
+- **GateSelectWidget** — Pick gates as chips from the gates that fit the node, each coloured by its state
+
+## Settings
+- **Protokol** — Lines shared by gates and the Monitor
+
+## States
+- **Protokol** — Protocol drivers, the project's gates and the Lines they share
+- **Protokol selection** — The gate, Line or Device this session has selected
+
+## Editors
+- **Device** — The device or Line in the Protokol selection
+- **Gates** — The project's gates and their Lines
+- **Monitor** — Live traffic on Lines

haybale_protokol-0.0.3/haybale_protokol/NOTES.md

@@ -0,0 +1,75 @@
+# Protokol
+
+Control protocols for Haywire graphs: OSC now, then MIDI and gamepads, each added by its own
+protocol haybale (`haybale-protokol-osc`, ...). This haybale is the shared base. It has no
+nodes of its own.
+
+## Gates
+
+A graph refers to a **Gate** by name only. The project's Gate file,
+`.haywire/protokol.toml`, is committed with the project and defines each gate:
+
+```toml
+[gates.touchosc-in]
+protocol = "osc"
+direction = "in"        # in, out, or two-way where the protocol has one shared channel
+transport = "udp"
+port = 8000
+bind = "0.0.0.0"        # default: all interfaces
+
+[gates.lights-out]
+protocol = "osc"
+direction = "out"
+port = 9000
+host = "10.0.0.2"
+
+[gates.desk]            # OSC over TCP: we connect to the peer
+protocol = "osc"
+direction = "two-way"   # TCP has one shared channel, so a gate may go both ways
+transport = "tcp"
+role = "client"         # or "server": peers connect to us (on bind, default all interfaces)
+host = "10.0.0.5"
+port = 3032
+framing = "1.1"         # "1.0" length prefix, or "1.1" SLIP (default)
+```
+
+MIDI and gamepad gates name a **Device** (`device = "desk"`). The machine's Device list,
+`~/.haywire/protokol-devices.toml`, maps that name to what the OS calls the hardware.
+
+## Lines
+
+Gates that resolve to the same connection (the same protocol, transport, address and port)
+share one **Line**, the only thing that opens a port. Two gates on one port with different
+bind addresses are two Lines, and the second cannot open (`cannot open: ...`). A Line opens
+with its first user and closes once the last one has left and the grace period has passed
+(setting **Line grace period**, default 2 s), so a graph restart keeps its peers. Lines run on
+their own threads; a slow flow never holds a Line up.
+
+## Editors
+
+| Editor | Slot | What it does | Who may change things |
+|---|---|---|---|
+| **Gates** | left icon bar | The project's gates, with each one's Line and status. Add, edit, delete; "Bind…" for a gate whose device this machine does not know; open the Monitor on a gate. | Edit access |
+| **Monitor** | centre tab | Click a line's eye to watch it; the eye then hides or shows its messages in the output without losing them. Each watched line has its own Clear, Export (JSONL or CSV) and Stop watching; the toolbar's act on all shown lines. Filter by text, pause. Test-send to output gates. "New line…" watches a Line no gate uses yet, and "Save as gate…" keeps it. | Watching open Lines: view access. Opening Lines, test-send, saving gates: edit access |
+| **Device** | right icon bar | Follows the selection: a device, a gate (its options, Line and last values) or a Line. With nothing selected, the machine's Device list. | Editing the Device list: admin access |
+
+The Monitor never slows a Line: each watched source keeps the last 2000 messages (older ones
+drop and are counted), and the output redraws at most five times a second, showing the newest
+300 messages: newest first, or oldest first like a log (the toolbar toggles it; a log follows the
+newest message unless you scroll up to read). Export writes everything the filter keeps.
+
+A gate edited while graphs use it applies when those graphs next start.
+
+## Status texts
+
+Receive and Send nodes report problems on their `status` outlet; nothing crashes the graph:
+
+| Status | Meaning |
+|---|---|
+| `no gate named 'x'` | The Gate file has no such gate |
+| `gate file: ...` | The Gate file cannot be read |
+| `protocol not installed` | No enabled haybale provides the gate's protocol |
+| `unbound gate: no device 'x' on this machine` | The Device list does not know the gate's device |
+| `'x' is an input gate` / `an output gate` | The node uses the gate in the wrong direction |
+| `cannot open: ...` | The port or device could not be opened (for example, already in use) |
+| `gate 'x': ...` | The gate's options are incomplete or wrong, or disagree with another gate on the same Line |

haybale_protokol-0.0.3/haybale_protokol/OVERVIEW.md

@@ -0,0 +1,18 @@
+# Protokol
+
+Control protocols for graphs: gates, shared lines and the base for OSC, MIDI and gamepad
+
+## Widgets
+- **GateSelectWidget** — Pick gates as chips from the gates that fit the node, each coloured by its state
+
+## Settings
+- **Protokol** — Lines shared by gates and the Monitor
+
+## States
+- **Protokol** — Protocol drivers, the project's gates and the Lines they share
+- **Protokol selection** — The gate, Line or Device this session has selected
+
+## Editors
+- **Device** — The device or Line in the Protokol selection
+- **Gates** — The project's gates and their Lines
+- **Monitor** — Live traffic on Lines

haybale_protokol-0.0.3/haybale_protokol/QUICKREF.md

@@ -0,0 +1,16 @@
+# haybale-protokol — component index (v0.0.3)
+
+## widget
+- `haybale-protokol:widget:GateSelectWidget` — GateSelectWidget — Pick gates as chips from the gates that fit the node, each coloured by its state
+
+## setting
+- `haybale-protokol:setting:ProtokolSettings` — Protokol — Lines shared by gates and the Monitor
+
+## state
+- `haybale-protokol:state:ProtokolSelection` — Protokol selection — The gate, Line or Device this session has selected
+- `haybale-protokol:state:ProtokolState` — Protokol — Protocol drivers, the project's gates and the Lines they share
+
+## editor
+- `haybale-protokol:editor:DeviceEditor` — Device — The device or Line in the Protokol selection
+- `haybale-protokol:editor:GatesEditor` — Gates — The project's gates and their Lines
+- `haybale-protokol:editor:MonitorEditor` — Monitor — Live traffic on Lines

haybale_protokol-0.0.3/haybale_protokol/__init__.py

@@ -0,0 +1,103 @@
+"""
+Local haybale library for the haybale-protokol project.
+
+Add your custom components in the corresponding folders:
+- nodes/      — node definitions
+- macros/     — macro documents (.hwm)
+- types/      — custom data types
+- widgets/    — UI widgets for data types
+- skins/      — custom node skins
+- adapters/   — type-to-type conversion adapters
+- settings/   — library settings definitions
+- states/     — library app and session states
+- themes/     — workbench and node themes
+- panels/     — custom UI panels
+- editors/    — custom UI editors
+"""
+
+from pathlib import Path
+
+from haywire.api import (
+    AdapterRegistry,
+    BaseLibrary,
+    MacroRegistry,
+    NodeRegistry,
+    SettingsRegistry,
+    SkinRegistry,
+    ThemeRegistry,
+    TypeRegistry,
+    WidgetRegistry,
+    library,
+)
+
+from haywire.api.workbench import EditorRegistry, PanelRegistry, StateRegistry
+
+
+@library(
+    file_watcher=True,
+)
+class Library(BaseLibrary):
+    """Local project library — add your components in the subfolders."""
+
+    def register_components(self):
+        """Register all components with the global registries."""
+        base_path = Path(__file__).parent
+
+        self.add_folder_to_registry(
+            folder_path=str(base_path / "settings"),
+            registry_cls=SettingsRegistry,
+        )
+
+        self.add_folder_to_registry(
+            folder_path=str(base_path / "states"),
+            registry_cls=StateRegistry,
+        )
+
+        self.add_folder_to_registry(
+            folder_path=str(base_path / "themes"),
+            registry_cls=ThemeRegistry,
+        )
+
+        self.add_folder_to_registry(
+            folder_path=str(base_path / "types"),
+            registry_cls=TypeRegistry,
+        )
+
+        self.add_folder_to_registry(
+            folder_path=str(base_path / "adapters"),
+            registry_cls=AdapterRegistry,
+        )
+
+        self.add_folder_to_registry(
+            folder_path=str(base_path / "widgets"),
+            registry_cls=WidgetRegistry,
+        )
+
+        self.add_folder_to_registry(
+            folder_path=str(base_path / "skins"),
+            registry_cls=SkinRegistry,
+        )
+
+        self.add_folder_to_registry(
+            folder_path=str(base_path / "nodes"),
+            registry_cls=NodeRegistry,
+        )
+
+        self.add_folder_to_registry(
+            folder_path=str(base_path / "macros"),
+            registry_cls=MacroRegistry,
+        )
+
+        self.add_folder_to_registry(
+            folder_path=str(base_path / "panels"),
+            registry_cls=PanelRegistry,
+        )
+
+        self.add_folder_to_registry(
+            folder_path=str(base_path / "editors"),
+            registry_cls=EditorRegistry,
+        )
+
+    def validate(self) -> bool:
+        """Validate library structure."""
+        return True

haybale_protokol-0.0.3/haybale_protokol/devices.py

@@ -0,0 +1,82 @@
+"""Devices and the machine's Device list, ``~/.haywire/protokol-devices.toml``.
+
+A Device is hardware this machine knows, under a name the user chose, mapped to what the OS
+calls it. Every project on the machine shares the list; it holds nothing about network peers::
+
+    [devices.desk]
+    protocol = "midi"
+    os_id = "IAC Driver Bus 1"
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+import tomlkit
+
+from haywire.core.tomlio import plain, read_toml, write_toml  # noqa: TID251 -- not in the Author API yet, reported (issue #3)
+
+
+class DeviceListError(ValueError):
+    """The Device list cannot be read; the message names the file and, where known, the device."""
+
+
+@dataclass(frozen=True)
+class Device:
+    """A piece of hardware under the user's name for it."""
+
+    name: str
+    protocol: str
+    os_id: str
+    """The OS's identifier: a MIDI port name, an SDL GUID."""
+
+
+def device_list_path() -> Path:
+    """Return where this machine's Device list lives (read at call time, so HOME may change)."""
+    return Path.home() / ".haywire" / "protokol-devices.toml"
+
+
+def load_devices(path: Path) -> dict[str, Device]:
+    """Read every device in ``path``, by name; a missing file has none.
+
+    Raises:
+        DeviceListError: The file is not valid TOML, or a device is malformed.
+    """
+    if not path.is_file():
+        return {}
+    try:
+        data = plain(read_toml(path))
+    except (ValueError, OSError) as exc:  # read_toml raises toml.TomlDecodeError, a ValueError
+        raise DeviceListError(f"{path}: {exc}") from exc
+    tables = data.get("devices", {})
+    if not isinstance(tables, dict):
+        raise DeviceListError(f"{path}: [devices] must be a table")
+    devices: dict[str, Device] = {}
+    for name, table in tables.items():
+        if not isinstance(table, dict):
+            raise DeviceListError(f"{path}: device '{name}' must be a table")
+        protocol, os_id = table.get("protocol"), table.get("os_id")
+        if not isinstance(protocol, str) or not protocol or not isinstance(os_id, str) or not os_id:
+            raise DeviceListError(f"{path}: device '{name}' needs a protocol and an os_id")
+        devices[name] = Device(name, protocol, os_id)
+    return devices
+
+
+def save_devices(path: Path, devices: Iterable[Device]) -> None:
+    """Write ``devices`` to ``path`` as the whole Device list, keeping the file's comments."""
+    document = read_toml(path) if path.is_file() else tomlkit.document()
+    if "devices" not in document:
+        document["devices"] = tomlkit.table(is_super_table=True)
+    tables = document["devices"]
+    wanted = {device.name: device for device in devices}
+    for name in [name for name in tables if name not in wanted]:
+        del tables[name]
+    for name, device in wanted.items():
+        if name not in tables:
+            tables[name] = tomlkit.table()
+        tables[name]["protocol"] = device.protocol
+        tables[name]["os_id"] = device.os_id
+    path.parent.mkdir(parents=True, exist_ok=True)
+    write_toml(path, document)

haybale_protokol-0.0.3/haybale_protokol/dispatch.py

@@ -0,0 +1,70 @@
+"""How a Receive node's flow queues the messages its Line delivers.
+
+Stream kinds (OSC, MIDI CC, gamepad axes) default to Drop with a queue of one and fire their
+Start value; event kinds (notes, buttons) default to Block and do not. A MIDI node's kind can
+change, so the defaults are an "Auto" choice resolved by kind, not fixed per class.
+"""
+
+from __future__ import annotations
+
+from haywire.api import CHOICES, INT, CallbackEvent, NodeSettings, Promotable, QueueMode, setting
+
+AUTO = "Auto (by message kind)"
+BLOCK = "Block (every message)"
+DROP = "Drop (newest only)"
+ON = "On"
+OFF = "Off"
+
+
+class ReceiveDispatchSettings(NodeSettings):
+    """How incoming messages queue, and whether the Line cache fires at start. Applies on the next start."""
+
+    queue_mode = setting[CHOICES](
+        AUTO,
+        label="Queue Mode",
+        category="Dispatch",
+        description=(
+            "Block runs the flow for every message; a slow flow then falls behind, never the Line. "
+            "Drop keeps only the newest message. Auto uses Drop for values (faders, axes, OSC) and "
+            "Block for events (notes, buttons)."
+        ),
+        widget_config={"options": [AUTO, BLOCK, DROP]},
+        promotable=Promotable.CONFIG,
+    )
+    max_queue_size = setting[INT](
+        100,
+        min=1,
+        max=1024,
+        label="Max Queue Size",
+        category="Dispatch",
+        description="How many messages Block holds while the flow runs behind. Drop always holds one.",
+        promotable=Promotable.CONFIG,
+    )
+    start_value = setting[CHOICES](
+        AUTO,
+        label="Start Value",
+        category="Dispatch",
+        description=(
+            "Fire once with the last message the Line saw when the graph starts. "
+            "Auto: on for values, off for events."
+        ),
+        widget_config={"options": [AUTO, ON, OFF]},
+        promotable=Promotable.CONFIG,
+    )
+
+
+def resolve_dispatch(dispatch: ReceiveDispatchSettings, *, stream: bool) -> tuple[QueueMode, int, bool]:
+    """Return ``(queue mode, queue size, start value)`` for a node receiving a stream or event kind."""
+    mode = str(dispatch.queue_mode)
+    if mode == AUTO:
+        mode = DROP if stream else BLOCK
+    start = str(dispatch.start_value)
+    start_value = stream if start == AUTO else start == ON
+    if mode == DROP:
+        return QueueMode.DROP, 1, start_value
+    return QueueMode.BLOCK, int(dispatch.max_queue_size), start_value
+
+
+def event_source_for(node_id: str, queue_mode: QueueMode, max_queue_size: int) -> CallbackEvent:
+    """The event subscription of a Receive node: a callback named after the node."""
+    return CallbackEvent(event_name=node_id, queue_mode=queue_mode, max_queue_size=max_queue_size)

haybale_protokol-0.0.3/haybale_protokol/docs/haybale-protokol.editor.DeviceEditor.md

@@ -0,0 +1,21 @@
+# Device
+
+`haybale-protokol:editor:DeviceEditor` · kind: editor
+
+The device or Line in the Protokol selection
+
+## Details
+
+- **default_slot**: `context`
+- **opens**: `OpenBehavior.REQUIRED`
+- **order**: `100`
+
+## Notes
+
+Follows the Protokol selection.
+
+- A device: its OS name, and whether the protocol sees it connected. With ADMIN: edit or
+  delete it, or map a gate's device name that this machine does not know yet.
+- A gate: its options, its Line's status and users, and the Line cache.
+- A Line: its key, status, users and cache.
+- Nothing: the Device list.

haybale_protokol-0.0.3/haybale_protokol/docs/haybale-protokol.editor.GatesEditor.md

@@ -0,0 +1,20 @@
+# Gates
+
+`haybale-protokol:editor:GatesEditor` · kind: editor
+
+The project's gates and their Lines
+
+## Details
+
+- **default_slot**: `action`
+- **opens**: `OpenBehavior.REQUIRED`
+- **order**: `100`
+
+## Notes
+
+One row per gate: its name, protocol and direction, and below them its status.
+
+The status says whether its Line is open (and by how many users), closed, or why the gate
+cannot be used: protocol not installed, unbound device, or a malformed entry. With EDIT a
+row can be edited or deleted and the header adds a gate. An unbound gate offers "Bind…",
+which selects its device for the Device editor.

haybale_protokol-0.0.3/haybale_protokol/docs/haybale-protokol.editor.MonitorEditor.md

@@ -0,0 +1,20 @@
+# Monitor
+
+`haybale-protokol:editor:MonitorEditor` · kind: editor
+
+Live traffic on Lines
+
+## Details
+
+- **default_slot**: `edit`
+- **opens**: `OpenBehavior.ON_CONTEXT`
+- **order**: `100`
+
+## Notes
+
+Tick a gate or an open Line to watch it; the table shows the newest messages first.
+
+The filter matches the message text, case-insensitively. "New line…" opens a Line no gate
+uses yet, and "Save as gate…" turns it into a gate. A ticked output gate gets a test-send
+row: type a message in the protocol's own form (for OSC: ``/address 0.5 3 word``).
+Export writes every message the filter keeps, as JSONL or CSV.

haybale_protokol-0.0.3/haybale_protokol/docs/haybale-protokol.setting.ProtokolSettings.md

@@ -0,0 +1,9 @@
+# Protokol
+
+`haybale-protokol:setting:ProtokolSettings` · kind: setting
+
+Lines shared by gates and the Monitor
+
+## Notes
+
+How long a Line stays open after its last user leaves.

haybale_protokol-0.0.3/haybale_protokol/docs/haybale-protokol.state.ProtokolSelection.md

@@ -0,0 +1,9 @@
+# Protokol selection
+
+`haybale-protokol:state:ProtokolSelection` · kind: state
+
+The gate, Line or Device this session has selected
+
+## Notes
+
+What the Device editor follows. At most one of the three is set.

haybale_protokol-0.0.3/haybale_protokol/docs/haybale-protokol.state.ProtokolState.md

@@ -0,0 +1,12 @@
+# Protokol
+
+`haybale-protokol:state:ProtokolState` · kind: state
+
+Protocol drivers, the project's gates and the Lines they share
+
+## Notes
+
+Owns the Protocol drivers and the open Lines; reads the Gate file and the Device list.
+
+One per app, shared by every session and by execution. Lines run on their own threads, so
+every change is published as a payload-free ``ProtokolChanged`` scheduled onto the loop.

haybale_protokol-0.0.3/haybale_protokol/docs/haybale-protokol.widget.GateSelectWidget.md

@@ -0,0 +1,26 @@
+# GateSelectWidget
+
+`haybale-protokol:widget:GateSelectWidget` · kind: widget
+
+Pick gates as chips from the gates that fit the node, each coloured by its state
+
+## Details
+
+
+## Notes
+
+A select of gates; its behaviour is set by plain properties, as the port saves them.
+
+Each chosen gate shows as a chip coloured by its state: success when usable, warning when this
+machine cannot use it now (protocol not installed, device unbound), danger when there is no such
+gate or it is of another protocol or direction. The select takes input only in edit mode.
+
+Properties (``GateSelectWidget.config(properties={...})``):
+
+- ``protocol``: the gates to offer and check, e.g. ``"osc"``.
+- ``direction``: ``"in"`` or ``"out"``; two-way gates fit both.
+- ``multiple`` (default ``True``): several gates, stored as ``"a, b"``; ``False`` for exactly one.
+- ``typed`` (default ``True``): a name typed and confirmed with Enter is kept even when no such
+  gate exists yet.
+
+The offered gates are read from the project each time the widget is drawn, so new gates appear.