libstp.ui.screen
================

.. py:module:: libstp.ui.screen

.. autoapi-nested-parse::

   UIScreen - Base class for self-contained UI screens.

   Each screen handles its own events and state.
   The UIStep orchestrates which screens to show.



Attributes
----------

.. autoapisummary::

   libstp.ui.screen.T


Classes
-------

.. autoapisummary::

   libstp.ui.screen.UIScreen


Module Contents
---------------

.. py:data:: T

.. py:class:: UIScreen

   Bases: :py:obj:`abc.ABC`, :py:obj:`Generic`\ [\ :py:obj:`T`\ ], :py:obj:`libstp.class_name_logger.ClassNameLogger`


   A self-contained screen with its own layout and event handlers.

   Subclass this to create reusable screen components. The screen
   runs until close() is called, then returns a result to the Step.

   .. rubric:: Example

   class ConfirmScreen(UIScreen[bool]):
       title = "Confirm"

       def __init__(self, message: str):
           super().__init__()
           self.message = message

       def build(self) -> Widget:
           return Center(children=[
               Text(self.message, size="large"),
               Row(children=[
                   Button("no", "Cancel", style="secondary"),
                   Button("yes", "Confirm", style="success"),
               ]),
           ])

       @on_click("yes")
       async def on_yes(self):
           self.close(True)

       @on_click("no")
       async def on_no(self):
           self.close(False)


   .. py:attribute:: title
      :type:  str
      :value: 'Screen'



   .. py:method:: build() -> libstp.ui.widgets.Widget
      :abstractmethod:


      Build the screen layout.

      Called on every render. Return a Widget tree describing
      what to display.



   .. py:method:: close(result: T = None) -> None

      Close this screen and return to the Step.

      :param result: The value to return to the Step. Type should match
                     the Generic type parameter.



   .. py:method:: refresh() -> None
      :async:


      Re-render this screen.

      Call this after changing state that affects the UI.



   .. py:method:: get_value(widget_id: str, default: Any = None) -> Any

      Get the current value of an input widget.

      :param widget_id: The ID of the input widget
      :param default: Value to return if widget not found

      :returns: The current value of the widget



   .. py:method:: set_value(widget_id: str, value: Any) -> None

      Set the value of an input widget.

      :param widget_id: The ID of the input widget
      :param value: The new value



   .. py:property:: robot

      Access the robot instance.


   .. py:property:: is_closed
      :type: bool


      Check if screen is closed.


   .. py:method:: read_sensor(port: int, sensor_type: str = 'analog') -> float
      :async:


      Read a sensor value.

      :param port: The sensor port number
      :param sensor_type: "analog" or "digital"

      :returns: The sensor reading