Source code for Karana.KUtils.MultibodyTUI.history

# Copyright (c) 2024-2026 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 StateHistroy. A class for keeping track of the TUI state history."""

from typing import TypeVar, Generic

State = TypeVar("State")




class StateHistory(Generic[State]):
    """Container for a state object with undo and redo capabilities."""

    def __init__(self, init_state: State):
        """Create an instance of StateHistory.

        Parameters
        ----------
        init_state: State
            The initial state
        """
        self._stack = [init_state]
        self._redo_stack = []

    @property
    def state(self) -> State:
        """The current state."""
        return self._stack[-1]

    @state.setter
    def state(self, state: State):
        """Set a new state."""
        self.push(state)



    def push(self, state: State):
        """Set a new state."""
        if state == self.state:
            return state
        self._stack.append(state)
        if self._redo_stack:
            self._redo_stack = []


    @property
    def current_state_count(self) -> int:
        """The number of states in the undo stack.

        Note that this includes the current state and is always
        positive.
        """
        return len(self._stack)

    @property
    def total_state_count(self) -> int:
        """The number of states - past, present, and future.

        This is similar to past_state_count but also includes states in
        the redo stack.
        """
        return len(self._stack) + len(self._redo_stack)



    def undoStackSize(self) -> int:
        """Return the number of states in the undo stack.

        Note that this includes the current state and is always positive
        """
        return len(self._stack)




    def canUndo(self) -> bool:
        """Return whether an undo state is available."""
        return len(self._stack) > 1




    def undo(self):
        """Return to the previous state."""
        if not self.canUndo():
            return
        self._redo_stack.append(self._stack.pop())




    def canRedo(self) -> bool:
        """Return whether a redo state is available."""
        return bool(self._redo_stack)




    def redo(self):
        """Return to the next state (i.e., undo a previous undo)."""
        if not self.canRedo():
            return
        self._stack.append(self._redo_stack.pop())