libstp.ui.screens.basic
=======================

.. py:module:: libstp.ui.screens.basic

.. autoapi-nested-parse::

   Basic pre-built screens for common UI patterns.



Classes
-------

.. autoapisummary::

   libstp.ui.screens.basic.WaitForButtonScreen
   libstp.ui.screens.basic.ConfirmScreen
   libstp.ui.screens.basic.MessageScreen
   libstp.ui.screens.basic.ChoiceScreen
   libstp.ui.screens.basic.ProgressScreen
   libstp.ui.screens.basic.StatusScreen


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

.. py:class:: WaitForButtonScreen(message: str = 'Press the button to continue', icon_name: str = 'touch_app', icon_color: str = 'amber')

   Bases: :py:obj:`libstp.ui.screen.UIScreen`\ [\ :py:obj:`None`\ ]


   Shows a message and waits for physical button press.

   .. rubric:: Example

   await self.show(WaitForButtonScreen("Place robot at start"))


   .. py:attribute:: title
      :value: 'Ready'



   .. py:attribute:: message
      :value: 'Press the button to continue'



   .. py:attribute:: icon_name
      :value: 'touch_app'



   .. py:attribute:: icon_color
      :value: 'amber'



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

      Build the screen layout.

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



   .. py:method:: on_press()
      :async:



.. py:class:: ConfirmScreen(title: str, message: str, confirm_label: str = 'Confirm', cancel_label: str = 'Cancel', confirm_style: str = 'success', icon_name: str = 'help_outline', icon_color: str = 'blue')

   Bases: :py:obj:`libstp.ui.screen.UIScreen`\ [\ :py:obj:`bool`\ ]


   Two-button confirmation dialog. Returns True or False.

   .. rubric:: Example

   confirmed = await self.show(ConfirmScreen(
       "Warning",
       "Robot will move. Continue?"
   ))


   .. py:attribute:: title


   .. py:attribute:: message


   .. py:attribute:: confirm_label
      :value: 'Confirm'



   .. py:attribute:: cancel_label
      :value: 'Cancel'



   .. py:attribute:: confirm_style
      :value: 'success'



   .. py:attribute:: icon_name
      :value: 'help_outline'



   .. py:attribute:: icon_color
      :value: 'blue'



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

      Build the screen layout.

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



   .. py:method:: on_confirm()
      :async:



   .. py:method:: on_cancel()
      :async:



.. py:class:: MessageScreen(title: str, message: str, button_label: str = 'OK', icon_name: Optional[str] = None, icon_color: str = 'blue')

   Bases: :py:obj:`libstp.ui.screen.UIScreen`\ [\ :py:obj:`None`\ ]


   Shows a message with a single dismiss button.

   .. rubric:: Example

   await self.show(MessageScreen(
       "Success",
       "Calibration complete!",
       icon="check",
       icon_color="green"
   ))


   .. py:attribute:: title


   .. py:attribute:: message


   .. py:attribute:: button_label
      :value: 'OK'



   .. py:attribute:: icon_name
      :value: None



   .. py:attribute:: icon_color
      :value: 'blue'



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

      Build the screen layout.

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



   .. py:method:: on_ok()
      :async:



.. py:class:: ChoiceScreen(title: str, message: str, choices: List[tuple], cancel_label: Optional[str] = 'Cancel')

   Bases: :py:obj:`libstp.ui.screen.UIScreen`\ [\ :py:obj:`str`\ ]


   Multiple choice selection. Returns the selected option ID.

   .. rubric:: Example

   choice = await self.show(ChoiceScreen(
       "Select Mode",
       "Choose a driving mode:",
       [
           ("careful", "Careful", "Slow and precise"),
           ("normal", "Normal", "Balanced speed"),
           ("fast", "Fast", "Maximum speed"),
       ]
   ))


   .. py:attribute:: title


   .. py:attribute:: message


   .. py:attribute:: choices


   .. py:attribute:: cancel_label
      :value: 'Cancel'



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

      Build the screen layout.

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



   .. py:method:: on_cancel()
      :async:



.. py:class:: ProgressScreen(message: str = 'Please wait...', show_spinner: bool = True, show_progress: bool = False)

   Bases: :py:obj:`libstp.ui.screen.UIScreen`\ [\ :py:obj:`None`\ ]


   Progress/loading screen for use with non-blocking display.

   Use with `display()` or `showing()` while running background tasks.

   .. rubric:: Example

   async with self.showing(ProgressScreen("Calibrating...")) as ctx:
       for i in range(100):
           ctx.screen.progress = i
           ctx.screen.status = f"Step {i+1}/100"
           await ctx.screen.refresh()
           await asyncio.sleep(0.1)


   .. py:attribute:: title
      :value: 'Working'



   .. py:attribute:: message
      :value: 'Please wait...'



   .. py:attribute:: show_spinner
      :value: True



   .. py:attribute:: show_progress
      :value: False



   .. py:attribute:: progress
      :type:  int
      :value: 0



   .. py:attribute:: status
      :type:  str
      :value: ''



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

      Build the screen layout.

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



.. py:class:: StatusScreen(message: str, icon_name: str = 'info', icon_color: str = 'blue', status: str = '')

   Bases: :py:obj:`libstp.ui.screen.UIScreen`\ [\ :py:obj:`None`\ ]


   Simple status display screen for non-blocking use.

   Shows an icon, message, and optional status text.
   Good for showing current state during long operations.

   .. rubric:: Example

   await self.display(StatusScreen(
       "Connecting...",
       icon="wifi",
       icon_color="blue"
   ))


   .. py:attribute:: title
      :value: 'Status'



   .. py:attribute:: message


   .. py:attribute:: icon_name
      :value: 'info'



   .. py:attribute:: icon_color
      :value: 'blue'



   .. py:attribute:: status
      :value: ''



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

      Build the screen layout.

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