GUI Documentation
=================

The ZEFIR GUI provides an interactive environment for creating and visualizing potential flows.

Architecture
------------

The GUI is built with a modular architecture using PySide6:

- **Main Window** (``main_window.py``): Top-level window with dockable panels
- **Plot Widget** (``plot_widget.py``): Matplotlib embedded widget for visualization
- **Flow Manager** (``flow_widgets.py``): Controls for adding/editing flows
- **Visualization Panel** (``visualization_panel.py``): Display options and settings
- **Log Console** (``log_widget.py``): Real-time log display with level filtering

Components
----------

Main Window
~~~~~~~~~~~

.. autoclass:: zefir.gui.potential.main_window.PotentialFlowGUI
   :members:
   :undoc-members:
   :show-inheritance:

Plot Widget
~~~~~~~~~~~

.. autoclass:: zefir.gui.potential.plot_widget.PotentialFlowPlotWidget
   :members:
   :undoc-members:
   :show-inheritance:

Flow Widgets
~~~~~~~~~~~~

.. autoclass:: zefir.gui.potential.flow_widgets.FlowListManager
   :members:
   :undoc-members:
   :show-inheritance:

.. autoclass:: zefir.gui.potential.flow_widgets.GenericFlowWidget
   :members:
   :undoc-members:
   :show-inheritance:

Visualization Panel
~~~~~~~~~~~~~~~~~~~

.. autoclass:: zefir.gui.potential.visualization_panel.VisualizationPanel
   :members:
   :undoc-members:
   :show-inheritance:

Log Console
~~~~~~~~~~~

.. autoclass:: zefir.gui.potential.log_widget.LogConsole
   :members:
   :undoc-members:
   :show-inheritance:

The log console provides:

- **Real-time logging**: Displays log messages as they are generated
- **Level filtering**: Filter by Debug, Info, Warning, Error, or Critical
- **Color coding**: Different colors for different log levels
- **Monospace font**: Easy to read log messages

Entry Point
~~~~~~~~~~~

The GUI can be launched via the CLI or programmatically:

**CLI Entry Point:**

.. autofunction:: zefir.gui.potential.__init__.main

**Parser Configuration:**

.. autofunction:: zefir.gui.potential.__init__.get_parser

**Programmatic Launch:**

.. autofunction:: zefir.gui.potential.__init__.run_from_args

Flow Metadata System
--------------------

Each flow class includes metadata that enables automatic GUI generation:

.. autoclass:: zefir.potential.flows.base.FlowMetadata
   :members:
   :undoc-members:
   :show-inheritance:

Example: Adding a New Flow Type
-------------------------------

To add a new flow type:

1. Create a new module in ``zefir/potential/flows/``
2. Define the flow class with metadata:

.. code-block:: python

   class MyNewFlow(ComplexPotential):
       metadata = FlowMetadata(
           "My Flow Name",
           {
               "parameter1": {
                   "type": "float",
                   "default": 1.0,
                   "min": 0,
                   "max": 10
               }
           },
           has_position=True
       )
       
       def __init__(self, parameter1, center):
           self._param1 = parameter1
           self._center = complex(*center)
       
       def __call__(self, z, deriv=0):
           # Implement your flow
           pass

3. Import it in ``zefir/potential/flows/__init__.py``
4. Add to ``FLOW_TYPES`` in ``FlowListManager``

The GUI will automatically create appropriate input widgets based on the metadata.

Extending the GUI
-----------------

To add a new GUI application (e.g., for a different physics module):

1. Create a new package in ``zefir/gui/`` (e.g., ``zefir/gui/aero/``)
2. Implement ``get_parser()`` and ``run_from_args()`` in ``__init__.py``:

.. code-block:: python

   def get_parser() -> argparse.ArgumentParser:
       """Return argument parser for this GUI."""
       parser = argparse.ArgumentParser(
           description="Launch the aero GUI"
       )
       parser.add_argument(
           "--log-level",
           choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
           default="INFO",
           help="Set the logging level"
       )
       return parser

   def run_from_args(args: argparse.Namespace) -> int:
       """Run the GUI with parsed arguments."""
       configure_log(level=getattr(LogLevel, args.log_level))
       # Launch your GUI
       return 0

3. Update ``zefir/__main__.py`` to discover your new GUI:

.. code-block:: python

   import zefir.gui.aero as aero_gui
   guis["aero"] = (aero_gui.get_parser, aero_gui.run_from_args)

Your new GUI will then be accessible via ``python -m zefir aero``.