PANELITH DOCS Open the interactive docs ↗

Reference · Panelith 0.1.0 · plain HTML edition; the interactive edition has search and live examples

Pane

On this page 5 sections
  1. Attributes
  2. Hooks and methods
  3. initial_state
  4. restore_state
  5. on_open
  6. on_close
  7. on_event
  8. children_for
  9. view
  10. event_handlers
  11. spec
  12. @event
  13. event
  14. Bases for common shapes
  15. Child

Pane is the base class of every kind. The attributes describe how the shell presents it; the hooks describe how it behaves. See Panes, state and events for the model and Child for tethered children.

Attributes#

Attribute Type Default What it changes
kind str required the id: used by open_pane, Child, scope="kind:<id>" and the generated <kind>.new opener
label str '' the tab name and launcher caption
glyph str | Glyph 'ring' a built-in glyph name or a custom Glyph — Options:
49 options
ring square table list grid form file gear bolt star home info bell calendar database globe image play book user chat flask dollar key cube math code prompt terminal output graph chart plot solve steps puzzle puzzle-left puzzle-right text document pen author checklist report timer clipboard folder search commands
or a Glyph(...) of your own; all pictured in Glyphs
family str 'independent' the colour family of the glyph, tile and tethers — Options: independent · problem · author · assessment or any key of Theme.families (Theme)
widget str 'markdown' the widget that renders the body — Options: markdown · html · table · keyvalue · output · form · text · blocks or the id a plugin registers
widget_options dict[str, Any] {} passed to the widget unchanged
subtabs bool False a sub-tab strip inside the pane
closable bool True a × on the tab and a close command
launcher bool True a launcher tile and a generated <kind>.new opener
launcher_group str | None None a heading the launcher groups this kind's tile under; None keeps it in the first, unnamed group
tip str '' the launcher tile's tooltip
cycler str | None None a list id: ‹ › buttons that send a cycle event
header PaneHeader | None None PaneHeader(...) for this kind; None inherits the app's
single bool False at most one pane of this kind is open at a time
children list[Child] [] [Child(kind, placement, size, name, focus)] opened tethered to every new pane of this kind; children_for(ctx) decides per client
persist list[str] [] state keys a saved layout carries; the rest is rebuilt by restore_state (Saved layouts)
abstract bool False keeps a base class out of the registry

Hooks and methods#

initial_state#

initial_state(self, ctx: Context) -> dict[str, Any]

The state a new pane of this kind starts with (the widget renders it). Skipped when an open_pane action carried a state or a browser restores one.

restore_state#

restore_state(self, ctx: Context, saved: dict[str, Any]) -> dict[str, Any]

The state a pane gets when a saved layout is restored. saved holds the keys named in persist as they were when the layout was saved; the default rebuilds initial_state and lays those keys over it, so a kind whose content is live (today's figures) shows the current data under the saved selection. Override when the saved keys need work, e.g. a page id → the page's text.

Argument Meaning
ctx the context of the pane being restored.
saved the persisted keys (a subset of the state when it was saved).

on_open#

on_open(self, ctx: Context) -> Any

Extra actions when a pane of this kind opens (e.g. open a child).

on_close#

on_close(self, ctx: Context) -> None

Called when a pane of this kind is closed; its return value is ignored.

on_event#

on_event(self, ctx: Context, name: str, payload: dict[str, Any]) -> Any

Fallback for events without an @event handler.

children_for#

children_for(self, ctx: Context) -> list[Child]

The children to open with a new pane of this kind; children unless the kind wants to decide per client (ctx.narrow for a phone, say).

view#

view(self, state: dict[str, Any]) -> dict[str, Any] | None

Derive what the widget shows from the pane's state. Whatever this returns is merged over the state on its way to the browser, every time the state is set or patched, so handlers only ever update the model. A widget = "blocks" kind returns blocks.view(...) here.

event_handlers#

event_handlers() -> dict[str, Callable]

spec#

spec() -> s.KindSpec

@event#

event#

event(name: str) -> Callable[[Callable], Callable]

Mark a Pane method as the handler for a client event: @event("run").

Bases for common shapes#

Class Presets
EditorPane A kind whose body is an editable buffer with sub-tabs (Math, You's editors).; subtabs = True
OutputPane A read-only result surface, usually opened tethered to an editor.; widget = "output", launcher = False
ListPane A table bound to a ListSource (source names it).; widget = "table", source names the list

Child#

A kind a parent opens alongside itself, tethered: children = [Child("score", "below", 0.2)]. placement: "below" / "beside" (a new pane, size = its share of the split), "tab" (a tab in the parent's own pane), "new" (a new pane near the parent).

Field Type Default Options
kind str required
placement str 'below' focused · below · beside · new · tab
size float | None None
name str | None None
focus bool False