:py:mod:`interactive_figure.interactive_figure`
===============================================

.. py:module:: interactive_figure.interactive_figure

.. autoapi-nested-parse::

   This module provides functions to create and interact with a Matplotlib figure.

   The figure registers mouse presses, keyboard input and the location of the mouse
   after any input. The user has fine-grained control over when to wait for input
   and when to draw the contents of the figure.

   Source: https://github.com/teuncm/interactive-figure



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


Functions
~~~~~~~~~

.. autoapisummary::

   interactive_figure.interactive_figure.create
   interactive_figure.interactive_figure.toggle_fullscreen
   interactive_figure.interactive_figure.clear
   interactive_figure.interactive_figure.wait
   interactive_figure.interactive_figure.wait_for_interaction
   interactive_figure.interactive_figure.draw
   interactive_figure.interactive_figure.close
   interactive_figure.interactive_figure.gcf
   interactive_figure.interactive_figure.gca
   interactive_figure.interactive_figure.get_last_key_press
   interactive_figure.interactive_figure.get_last_mouse_press
   interactive_figure.interactive_figure.get_last_mouse_pos



.. py:function:: create(aspect_ratio='auto', hide_toolbar=False, **kwargs)

   Create the interactive figure.

   Parameters
   ----------
   aspect_ratio : str, optional
       aspect ratio of the Axes, by default "auto"
   hide_toolbar : bool, optional
       whether to hide the toolbar, by default False

   remaining arguments will be sent to the figure upon creation

   Raises
   ------
   RuntimeError
       if multiple interactive figures are created.


.. py:function:: toggle_fullscreen()

   Toggle fullscreen.


.. py:function:: clear()

   Reset the contents and layout of the drawable Axes.


.. py:function:: wait(timeout)

   Timeout for the given number of seconds. During this period it is
   not possible to interact with the figure. For sub-second timeouts use
   time.wait() instead.

   Parameters
   ----------
   timeout : float
       Number of seconds to wait for


.. py:function:: wait_for_interaction(timeout=-1)

   Wait for interaction with the interactive figure. Optionally
   use a timeout in seconds.

   Parameters
   ----------
   timeout : int, optional
       Timeout in seconds when waiting for input.

   Returns
   -------
   bool | None
       - True if a key was pressed.
       - False if a mouse button was pressed.
       - None if no input was given within the timeout.


.. py:function:: draw()

   Draw the figure.


.. py:function:: close()

   Close the figure.


.. py:function:: gcf()

   Get figure object of interactive figure.

   Returns
   -------
       Figure handler


.. py:function:: gca()

   Get Axes object of interactive figure.

   Returns
   -------
       Axes handler


.. py:function:: get_last_key_press()

   Get the last keypress and convert it to lowercase.

   Returns
   -------
   str | None
       The last key that was pressed


.. py:function:: get_last_mouse_press()

   Get the last mousepress and convert it to an integer value.

   Returns
   -------
   int | None
       The identifier of the last mouse button that was pressed


.. py:function:: get_last_mouse_pos()

   Get the last mouse position.

   Returns
   -------
   (x: float, y: float) | (None, None)
       The last registered mouse position after any interaction


