pySimBlocks.gui.blocks.block_meta

class pySimBlocks.gui.blocks.block_meta.BlockMeta

Bases: ABC

Define the GUI metadata contract for one block type.

Subclasses declare static block metadata, optional dialog customizations, and dynamic port-resolution rules used by the GUI layer.

name: str

User-facing block name.

category: str

GUI block category.

type: str

Stable block type identifier.

summary: str

Short summary displayed in the GUI.

description: str

Rich description displayed in the dialog.

doc_path: Path | None = None

Optional documentation file path, relative to the project directory.

parameters: Sequence[ParameterMeta] = ()

Declared block parameters.

inputs: Sequence[PortMeta] = ()

Declared input port metadata.

outputs: Sequence[PortMeta] = ()

Declared output port metadata.

create_dialog_session(instance: BlockInstance, project_dir: Path | None = None, project_state=None) → BlockDialogSession

Create a dialog session for a block instance.

Parameters:

• instance – Block instance being edited.

• project_dir – Project directory used to resolve relative files.

• project_state – Full project state for blocks that need to inspect other blocks in the diagram. None outside the GUI.

Returns:

New dialog session object bound to the instance.

is_parameter_active(param_name: str, instance_params: Dict[str, Any]) → bool

Return whether a parameter should be visible for an instance.

Parameters:

• param_name – Parameter name to test.

• instance_params – Current instance parameter values.

Returns:

True when the parameter is active.

gather_params(session: BlockDialogSession) → dict[str, Any]

Collect dialog parameters into a serialized parameter mapping.

Parameters:

session – Active dialog session.

Returns:

Parameter mapping gathered from the dialog state.

resolve_port_group(port_meta: PortMeta, direction: Literal['input', 'output'], instance: BlockInstance) → list[PortInstance]

Resolve one declared port group into concrete port instances.

Parameters:

• port_meta – Declared port metadata.

• direction – Direction of the port group.

• instance – Block instance whose ports are being built.

Returns:

Concrete port instances for the given port group.

build_ports(instance: BlockInstance) → list[PortInstance]

Build all concrete ports for a block instance.

Parameters:

instance – Block instance whose ports are being built.

Returns:

Ordered list of resolved input and output ports.

build_description(form: QFormLayout)

Build the default block description section in the dialog.

Parameters:

form – Form layout receiving the description widgets.

build_pre_param(session: BlockDialogSession, form: QFormLayout, readonly: bool = False)

Build widgets shown before the standard parameter rows.

Parameters:

• session – Active dialog session.

• form – Form layout receiving the widgets.

• readonly – Whether the dialog is read-only.

build_param(session: BlockDialogSession, form: QFormLayout, readonly: bool = False)

Build the standard parameter widgets for the dialog.

Parameters:

• session – Active dialog session.

• form – Form layout receiving the widgets.

• readonly – Whether the dialog is read-only.

build_post_param(session: BlockDialogSession, form: QFormLayout, readonly: bool = False)

Build widgets shown after the standard parameter rows.

Parameters:

• session – Active dialog session.

• form – Form layout receiving the widgets.

• readonly – Whether the dialog is read-only.

build_file_param_row(session: BlockDialogSession, form: QFormLayout, pmeta: ParameterMeta, readonly: bool = False, file_filter: str = 'Python files (*.py);;All files (*)') → None

Build a parameter row with a file picker button.

Parameters:

• session – Active dialog session.

• form – Form layout receiving the widgets.

• pmeta – Metadata of the file parameter.

• readonly – Whether the dialog is read-only.

• file_filter – File picker filter string.

refresh_form(session: BlockDialogSession)

Refresh widget visibility from the current local parameter state.

Parameters:

session – Active dialog session.