Karana.KUtils.MultibodyTUI.view
===============================

.. py:module:: Karana.KUtils.MultibodyTUI.view

.. autoapi-nested-parse::

   Classes to control the view of the MultibodyTUI.



Attributes
----------

.. autoapisummary::

   Karana.KUtils.MultibodyTUI.view.Value


Classes
-------

.. autoapisummary::

   Karana.KUtils.MultibodyTUI.view.HasId
   Karana.KUtils.MultibodyTUI.view.View


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

.. py:class:: HasId

   Bases: :py:obj:`Protocol`


   Structural type to require an id getter method.


   .. py:method:: id() -> int

      Id of the object.

      :returns: The ID of the object.
      :rtype: int



.. py:data:: Value

.. py:class:: View(name: str, init_values: collections.abc.Iterable[Value])

   Bases: :py:obj:`Generic`\ [\ :py:obj:`Value`\ ]


   Container for exploring subsets of items of a given type.

   At any time, the view has a current list of items (the 'selection').
   And, if the selection is nonempty, a single specific item from the
   selection (the 'current item').

   Key features:

   - Change to a different selection, maintaining the current item if
     it is a member of the new selection.
   - Mark the current item as a 'favorite' and list all favorites.
   - Take any number of steps forward or backward in the selection.


   .. py:method:: copy() -> Self

      Create a copy of this view.

      :returns: A copy of this view
      :rtype: typing.Self



   .. py:property:: current
      :type: Value | None


      The current item or None if the selection is empty.


   .. py:property:: selection
      :type: list[Value]


      The selection.


   .. py:property:: index
      :type: int


      The index of the current item in the selection list.


   .. py:property:: name
      :type: str


      The name of the view.


   .. py:method:: select(values: collections.abc.Iterable[Value], current: Value | None = None)

      Change to a new selection.

      :param values: The new selection
      :type values: Iterable[Value]
      :param current: The preferred current item in the new selection, using the
                      current item from the prior selection if None.
      :type current: Value | None = None



   .. py:method:: isFavorite(value: Value) -> bool

      Whether the given item is a favorite.

      :param value: The item to check
      :type value: Value

      :returns: Whether the given item is a favorite
      :rtype: bool



   .. py:property:: on_favorite
      :type: bool


      Whether the current item is a favorite.


   .. py:property:: favorites
      :type: list[Value]


      The list of all favorite items.


   .. py:method:: toggleFavorite(value: Value | None = None)

      Toggle the favorite status of an item.

      :param value: The item to toggle, or the current item if None
      :type value: Value | None = None



   .. py:method:: next(step: int = 1)

      Increment the current item index.

      When the step size is greater than one, this has 'sticky'
      behavior around the endpoints of the selection, stopping early
      at both the end and beginning of the selection. This is more
      complex than the more obvious solution of using modulo, but will
      hopefully result in more intuitive behavior to the user.

      :param step: The amount to increment the current item index
      :type step: int = 1



   .. py:method:: prev(step: int = 1)

      Decrement the current item index.

      When the step size is greater than one, this has 'sticky'
      behavior around the endpoints of the selection, stopping early
      at both the beginning and end of the selection. This is more
      complex than the more obvious solution of using modulo, but will
      hopefully result in more intuitive behavior to the user.

      :param step: The amount to decrement the current item index
      :type step: int = 1



   .. py:method:: __bool__() -> bool

      Whether the view's selection is nonempty.



   .. py:method:: __eq__(other: View) -> bool

      Whether the views have identical state.



   .. py:method:: __len__() -> int

      Get the number of items in the view's selection.