pyqt_reactive.protocols.widget_protocols

Functions

widget_capability_tags(widget_or_type)	Return all capability tags declared by a widget class and its bases.
widget_supports_capability(widget_or_type, ...)	Return whether a widget class declares a nominal capability tag.

Classes

ChangeSignalEmitter()	ABC for widgets that emit change signals.
ChildFieldChromeRefreshable()	ABC for compound widgets that render chrome for their own child fields.
ChildFieldIdentityProvider()	ABC for compound widgets that expose nominal child ObjectState identity.
ChildFieldNavigationTargetProvider()	ABC for compound widgets that expose concrete widgets for child fields.
ChildFieldSemanticChromeRefreshable()	ABC for compound widgets that render semantic chrome for child leaves.
ChildSubfieldNavigationTargetProvider()	ABC for compound widgets that expose structural descendant targets.
EnumSelectable()	ABC for widgets that can select from enum values.
InlineDataclassGroupBoxChromeProvider()	ABC for inline dataclass value widgets that contribute container title chrome.
InlineDataclassRootResettable()	ABC for inline dataclass widgets that can reset their child fields.
PlaceholderCapable()	ABC for widgets that can display placeholder text.
PlaceholderStateTrackable()	ABC for widgets that own placeholder chrome/cache state.
RangeConfigurable()	ABC for widgets that support numeric range configuration.
RawResolvedValueSettable()	ABC for widgets that can atomically apply a raw value and resolved preview.
ResolvedValuePreviewSettable()	ABC for widgets that render inherited/resolved values separately from raw edits.
ValueGettable()	ABC for widgets that can return a value.
ValueSettable()	ABC for widgets that can accept a value.
WidgetCapability(*values)	Nominal widget capability tags for generic service-level queries.
WidgetCapabilityTagged()	Base for widget contracts that advertise generic capability tags.

class pyqt_reactive.protocols.widget_protocols.WidgetCapability(*values)

Nominal widget capability tags for generic service-level queries.

PLACEHOLDER_STATE = 'placeholder_state'

class pyqt_reactive.protocols.widget_protocols.WidgetCapabilityTagged

Base for widget contracts that advertise generic capability tags.

widget_capabilities: ClassVar[frozenset[WidgetCapability]] = frozenset({})

pyqt_reactive.protocols.widget_protocols.widget_capability_tags(widget_or_type: Any) → frozenset[WidgetCapability]

Return all capability tags declared by a widget class and its bases.

pyqt_reactive.protocols.widget_protocols.widget_supports_capability(widget_or_type: Any, capability: WidgetCapability) → bool

Return whether a widget class declares a nominal capability tag.

class pyqt_reactive.protocols.widget_protocols.ValueGettable

ABC for widgets that can return a value.

All input widgets must implement this to participate in form value extraction.

abstractmethod get_value() → Any

Get the current value from the widget.

Returns:

The widget’s current value. None if no value set.

class pyqt_reactive.protocols.widget_protocols.ValueSettable

ABC for widgets that can accept a value.

All input widgets must implement this to participate in form value updates.

abstractmethod set_value(value: Any) → None

Set the widget’s value.

Parameters:

value – The value to set. None clears the widget.

class pyqt_reactive.protocols.widget_protocols.ResolvedValuePreviewSettable

ABC for widgets that render inherited/resolved values separately from raw edits.

Lazy dataclass container widgets may keep raw None child fields while previewing the resolved inherited dataclass. This contract lets form chrome refresh that preview without replacing the raw editable value.

abstractmethod set_resolved_value_preview(value: Any) → None

Set the resolved value used for display/preview only.

Parameters:

value – Resolved value for the same logical field.

class pyqt_reactive.protocols.widget_protocols.RawResolvedValueSettable

ABC for widgets that can atomically apply a raw value and resolved preview.

Lazy dataclass widgets can avoid rendering a raw intermediate state when a form refresh already has both ObjectState values available.

abstractmethod set_raw_value_with_resolved_preview(raw_value: Any, resolved_value: Any) → None

Set the editable raw value and resolved display preview in one pass.

Parameters:

• raw_value – Raw ObjectState value for editing.

• resolved_value – Resolved ObjectState value for inherited preview.

class pyqt_reactive.protocols.widget_protocols.ChildFieldChromeRefreshable

ABC for compound widgets that render chrome for their own child fields.

Inline dataclass widgets can own section labels/reset controls internally while still being edited as one form value. This contract lets the form manager refresh those child markers after ObjectState dirty/signature state changes without knowing widget-specific field names.

abstractmethod refresh_child_field_chrome(owner_field_paths: tuple['DottedFieldPath', ...] | None = None) → None

Refresh dirty/signature/reset chrome for child fields.

class pyqt_reactive.protocols.widget_protocols.ChildFieldNavigationTargetProvider

ABC for compound widgets that expose concrete widgets for child fields.

Inline dataclass widgets may render their own child sections internally instead of creating nested ParameterFormManager instances. This contract lets generic form navigation scroll to the concrete child section while keeping the widget-specific layout private to the inline editor.

abstractmethod child_field_navigation_target(field_name: str) → QWidget | None

Return the widget that visually represents a child field, if present.

Parameters:

field_name – Direct child field name inside the compound widget.

class pyqt_reactive.protocols.widget_protocols.ChildFieldIdentityProvider

ABC for compound widgets that expose nominal child ObjectState identity.

abstractmethod child_field_identity(field_name: str) → InlineDataclassChildFieldIdentity

Return the nominal identity for one direct child field.

class pyqt_reactive.protocols.widget_protocols.ChildFieldSemanticChromeRefreshable

ABC for compound widgets that render semantic chrome for child leaves.

abstractmethod child_field_semantic_owner_paths() → tuple['DottedFieldPath', ...]

Return ObjectState owner paths for structural child semantics.

abstractmethod refresh_child_field_semantics(owner_field_path: DottedFieldPath, semantic_index: ObjectStateSubfieldSemanticIndex) → None

Refresh dirty/default/inherited chrome for an ObjectState owner field.

class pyqt_reactive.protocols.widget_protocols.ChildSubfieldNavigationTargetProvider

ABC for compound widgets that expose structural descendant targets.

abstractmethod child_subfield_navigation_target(child_identity: InlineDataclassChildFieldIdentity, relative_path: StructuralValuePath) → StructuralFlashTarget | None

Return a concrete visual target for a child structural path.

An empty relative_path represents the child structural owner itself.

class pyqt_reactive.protocols.widget_protocols.InlineDataclassGroupBoxChromeProvider

ABC for inline dataclass value widgets that contribute container title chrome.

Regular nested dataclasses can move child widgets such as enableable checkboxes into the groupbox title row. Inline dataclass widgets do not have a nested ParameterFormManager, so they expose the same chrome through this contract while the container remains generic.

abstractmethod configure_inline_dataclass_groupbox(groupbox: Any) → None

Attach any inline title chrome to the owning groupbox.

Parameters:

groupbox – The InlineDataclassGroupBox hosting this value widget.

class pyqt_reactive.protocols.widget_protocols.InlineDataclassRootResettable

ABC for inline dataclass widgets that can reset their child fields.

abstractmethod reset_inline_dataclass_fields() → None

Reset the inline dataclass child fields to their signature defaults.

class pyqt_reactive.protocols.widget_protocols.PlaceholderCapable

ABC for widgets that can display placeholder text.

Placeholders show inherited/default values without setting actual values.

abstractmethod set_placeholder(text: str) → None

Set placeholder text for the widget.

Parameters:

text – Placeholder text to display (e.g., “Pipeline default: 42”)

class pyqt_reactive.protocols.widget_protocols.PlaceholderStateTrackable

ABC for widgets that own placeholder chrome/cache state.

widget_capabilities: ClassVar[frozenset[WidgetCapability]] = frozenset({WidgetCapability.PLACEHOLDER_STATE})

abstractmethod has_placeholder_state() → bool

Return whether placeholder chrome or cached placeholder data is present.

abstractmethod mark_placeholder_state() → None

Mark the widget as currently displaying placeholder chrome.

abstractmethod clear_placeholder_state() → None

Mark the widget as no longer displaying placeholder chrome.

abstractmethod cached_placeholder_text() → str | None

Return cached placeholder text, if any.

abstractmethod set_cached_placeholder_text(placeholder_text: str) → None

Cache placeholder text after a successful render.

abstractmethod cached_placeholder_resolved_value() → Any

Return cached placeholder resolved value, if any.

abstractmethod set_cached_placeholder_resolved_value(value: Any) → None

Cache the resolved value after a successful preview render.

abstractmethod clear_placeholder_cache() → None

Clear cached placeholder text and resolved value.

class pyqt_reactive.protocols.widget_protocols.RangeConfigurable

ABC for widgets that support numeric range configuration.

Typically implemented by numeric input widgets (spinboxes, sliders).

abstractmethod configure_range(minimum: float, maximum: float) → None

Configure the valid range for numeric input.

Parameters:

• minimum – Minimum allowed value

• maximum – Maximum allowed value

class pyqt_reactive.protocols.widget_protocols.EnumSelectable

ABC for widgets that can select from enum values.

Typically implemented by dropdowns and radio button groups.

abstractmethod set_enum_options(enum_type: type) → None

Configure widget with enum options.

Parameters:

enum_type – The Enum class to populate options from

abstractmethod get_selected_enum() → Any

Get the currently selected enum value.

Returns:

The selected enum member, or None if no selection

class pyqt_reactive.protocols.widget_protocols.ChangeSignalEmitter

ABC for widgets that emit change signals.

Provides explicit contract for signal connection, eliminating duck typing of signal names (textChanged vs valueChanged vs currentIndexChanged).

abstractmethod connect_change_signal(callback: Callable[[Any], None]) → None

Connect callback to widget’s change signal.

The callback will be invoked whenever the widget’s value changes, receiving the new value as its argument.

Parameters:

callback – Function to call when widget value changes. Signature: callback(new_value: Any) -> None

abstractmethod disconnect_change_signal(callback: Callable[[Any], None]) → None

Disconnect callback from widget’s change signal.

Parameters:

callback – The callback function to disconnect