pooltool.interact
=================

.. py:module:: pooltool.interact

    An endpoint for classes that enable interaction
    -----------------------------------------------
    
    

Overview
--------

.. list-table:: Classes
   :header-rows: 0
   :widths: auto
   :class: summarytable

   * - :py:obj:`Game <pooltool.interact.Game>`
     - This class runs the pooltool application
   * - :py:obj:`ShotViewer <pooltool.interact.ShotViewer>`
     - An interface for viewing shots from within python.




Classes
-------
.. autoclass:: Game(config=ShowBaseConfig.default())


   Bases: :py:obj:`Interface`



   .. rubric:: Methods:
   .. py:method:: enter_game()

      Close the menu, setup the visualization, and start the game


   .. py:method:: create_system()

      Create the multisystem and game objects

      FIXME This is where menu options for game type and further specifications should
      plug into.



.. autoclass:: ShotViewer(config=ShowBaseConfig.default())


   Bases: :py:obj:`Interface`



   .. rubric:: Methods:
   .. py:method:: show(shot_or_shots: Union[pooltool.system.datatypes.System, pooltool.system.datatypes.MultiSystem], title: str = '', camera_state: Optional[pooltool.ani.camera.CameraState] = None)

      Opens the interactive interface for one or more shots.

      .. important::

         For instructions on how to use the interactive interface, see :doc:`The
         Interface </getting_started/interface>`.

      :param shot_or_shots: The shot or collection of shots to visualize. This can be a single
                            :class:`pooltool.system.datatypes.System` object or a
                            :class:`pooltool.system.datatypes.MultiSystem` object containing
                            multiple systems.

                            .. note::

                               If a multisystem is passed, the systems can be scrolled through by
                               pressing *n* (next) and *p* (previous).
      :param title: The title to display in the visualization. Defaults to an empty string.
      :param camera_state: The initial camera state that the visualization is rendered with.

      .. admonition:: Example

         This example visualizes a single shot.
         
         >>> import pooltool as pt
         >>> system = pt.System.example()
         
         Make sure the shot is simulated, otherwise it will make for a boring
         visualization:
         
         >>> pt.simulate(system, inplace=True)
         
         Create a :class:`ShotViewer` object:
         
         >>> gui = pt.ShotViewer()
         
         Now visualize the shot:
         
         >>> gui.show(system)
         
         (Press *escape* to exit the interface and continue script execution)

      .. admonition:: Example

         This example explains the order in which events and script execution
         happens.
         
         .. code-block:: python
         
             import pooltool as pt
             system = pt.System.example()
             pt.simulate(system, inplace=True)
         
             # This line takes a view seconds to execute. It will generate a visible
             # window. Once the window has been generated, script execution continues
             gui = pt.ShotViewer()
         
             # When this line is called, the window is populated with an animated
             # scene of the shot.
             gui.show(system)
         
             # This line will not execute until <esc> is pressed while the window is
             # active.
             print('script continues')
         
             # For subsequent calls to `show`, you must use the same `ShotViewer`
             # object:
             gui.show(system)