mitk.mxn.layout.MxNLayoutDocument

mitk.mxn.layout.MxNLayoutDocument#

class mitk.mxn.layout.MxNLayoutDocument(root, name=None, version='2.0')#

Bases: object

A complete MxN layout document. In-memory documents are always strict: groups covers every label any window references.

Parameters:
__init__(root, name=None, version='2.0')#
Parameters:
Return type:

None

Methods

__init__(root[, name, version])

create(root, *[, name, groups, version])

Primary constructor.

find_window(id)

Return the leaf window with the given id, or None if the document does not contain one.

from_json(doc)

Parse a v2.0 JSON document.

to_json()

Emit a strict-mode v2.0 JSON document with stable key ordering.

validate()

Run cross-document checks on self.

window_ids()

Pre-order list of window ids (the routing identities).

windows()

Pre-order iterator over every leaf window in the document.

with_default_ids(*[, editor_name, ...])

Re-number all leaves in pre-order to qualified form.

Attributes

groups

Read-only Mapping view; mutations to the returned object do not affect the document.

name

select_windows

Entry point for the fluent MxNWindowSelector filter and bulk-transform API.

version

root

__eq__(other)#

Return self==value.

classmethod create(root, *, name=None, groups=None, version='2.0')#

Primary constructor. Always materialises a strict-mode document.

Parameters:

  • root (Split) – Tree root. Always a Split (matches schema).

  • name (str | None) – Optional preset display label.

  • groups (Mapping[str, Group] | Iterable[Group] | None) – Group registry. Mapping[str, Group] (key must equal Group.name), Iterable[Group] (uniqueness enforced), or None to auto-materialise: every label referenced in any window’s links becomes a Group with property defaults.

  • version (str)

Return type:

MxNLayoutDocument

find_window(id)#

Return the leaf window with the given id, or None if the document does not contain one.

Return type:

LayoutWindow | None

Parameters:

id (str)

classmethod from_json(doc)#

Parse a v2.0 JSON document.

Accepts either a parsed mapping or a JSON-string. Up-front version check raises ValueError before any structural parsing when the document’s version is not LAYOUT_VERSION. Lazy-mode input (no top-level groups) is materialised to strict eagerly during parse – the in-memory document never represents lazy state.

Return type:

MxNLayoutDocument

Parameters:

doc (Mapping[str, Any] | str)

property groups: Mapping[str, Group]#

Read-only Mapping view; mutations to the returned object do not affect the document.

name: str | None = None#
root: Split#
property select_windows: MxNWindowSelector[MxNLayoutDocument]#

Entry point for the fluent MxNWindowSelector filter and bulk-transform API. Selector terminals return a fresh MxNLayoutDocument (the original is left untouched).

to_json()#

Emit a strict-mode v2.0 JSON document with stable key ordering.

Key order follows the schema’s example ordering: - top-level: version, name?, groups, root - per window: type, id, name?, view_direction, links, size - per split: type, orientation, children, size? size on the document root is always omitted (no parent splitter).

Return type:

dict[str, Any]

validate()#

Run cross-document checks on self.

Raises ValueError with a message that names the offending element. Per-window structural checks are not re-run here – those are enforced once in LayoutWindow.create().

Return type:

None

version: str = '2.0'#
window_ids()#

Pre-order list of window ids (the routing identities).

Return type:

list[str]

windows()#

Pre-order iterator over every leaf window in the document.

Return type:

Iterator[LayoutWindow]

with_default_ids(*, editor_name='mxn', bare_id_stem='widget', start_index=0)#

Re-number all leaves in pre-order to qualified form.

Produces f"{editor_name}__{bare_id_stem}{i}" for i starting at start_index. Display names (.name) are preserved; only ids change.

WARNING: same caveat as LayoutWindow.with_id() – re-numbering an already-published document invalidates persisted references. Intended for use on freshly-built or freshly-loaded documents prior to PUT.

Return type:

MxNLayoutDocument

Parameters:

  • editor_name (str)

  • bare_id_stem (str)

  • start_index (int)