Source code for Karana.KUtils.MultibodyTUI.base

# Copyright (c) 2024-2025 Karana Dynamics Pty Ltd. All rights reserved.
#
# NOTICE TO USER:
#
# This source code and/or documentation (the "Licensed Materials") is
# the confidential and proprietary information of Karana Dynamics Inc.
# Use of these Licensed Materials is governed by the terms and conditions
# of a separate software license agreement between Karana Dynamics and the
# Licensee ("License Agreement"). Unless expressly permitted under that
# agreement, any reproduction, modification, distribution, or disclosure
# of the Licensed Materials, in whole or in part, to any third party
# without the prior written consent of Karana Dynamics is strictly prohibited.
#
# THE LICENSED MATERIALS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
# KARANA DYNAMICS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
# BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, AND
# FITNESS FOR A PARTICULAR PURPOSE.
#
# IN NO EVENT SHALL KARANA DYNAMICS BE LIABLE FOR ANY DAMAGES WHATSOEVER,
# INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS, DATA, OR USE, EVEN IF
# ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, WHETHER IN CONTRACT, TORT,
# OR OTHERWISE ARISING OUT OF OR IN CONNECTION WITH THE LICENSED MATERIALS.
#
# U.S. Government End Users: The Licensed Materials are a "commercial item"
# as defined at 48 C.F.R. 2.101, and are provided to the U.S. Government
# only as a commercial end item under the terms of this license.
#
# Any use of the Licensed Materials in individual or commercial software must
# include, in the user documentation and internal source code comments,
# this Notice, Disclaimer, and U.S. Government Use Provision.

"""Contains TUIBase, a base class for TUIs."""

from abc import ABC, abstractmethod

from .terminal import tuiMode, pollKey




class TUIBase(ABC):
    """Base class for terminal user interfaces."""

    def __init__(self, *, run=True):
        """Create an instance of TUIBase.

        Parameters
        ----------
        run: bool
            Whether to automatically call the run method
        """
        if run:
            self.run()



    @abstractmethod
    def redraw(self):
        """Redraw the TUI.

        A concrete TUI class must implement this method

        Typically the implementation should first clear the screen then print
        the TUI interface.
        """




    @abstractmethod
    def handleKey(self, key: str) -> bool:
        """Handle a single key press.

        A concrete TUI class must implement this method

        Parameters
        ----------
        key: str
            The pressed key as returned by pollKey

        Returns
        -------
        bool
            Return False to indicate the TUI should exit
        """




    def run(self):
        """Run the TUI, driven by redraw and handleKey.

        This will take control of the main thread unless interrupted or until
        handleKey returns True.
        """
        with tuiMode(on_resume=self.redraw):
            try:
                while True:
                    self.redraw()
                    while not (key := pollKey()):
                        pass

                    should_quit = not self.handleKey(key)
                    if should_quit:
                        break
            except KeyboardInterrupt:
                pass