diff --git a/src/damaris/gui/DamarisGUI.py b/src/damaris/gui/DamarisGUI.py index ab06404..19cb16e 100644 --- a/src/damaris/gui/DamarisGUI.py +++ b/src/damaris/gui/DamarisGUI.py @@ -1310,8 +1310,23 @@ class start_browser( threading.Thread ): class LogWindow: - """ - writes messages to the log window + """Manages the application log window. + + Provides a timestamped, scrollable text view for application messages. + Messages are dispatched via ``gobject.idle_add`` to keep the GTK main + loop responsive. + + Args: + xml_gui: The :class:`gtk.Builder` instance containing the GUI widgets. + damaris_gui: Reference to the main :class:`DamarisGUI` application. + + Attributes: + textview (:class:`gtk.TextView`): The monospaced text view widget. + textbuffer (:class:`gtk.TextBuffer`): The buffer backing the text view. + + Examples: + >>> log = LogWindow(xml_gui, damaris_gui) + >>> log("Application started") """ def __init__( self, xml_gui, damaris_gui ): @@ -1356,9 +1371,55 @@ class LogWindow: class ScriptWidgets: + """Manages experiment and result script editing widgets. + + Provides two syntax-highlighted, auto-completing text views for editing + DAMARIS experiment and result scripts. Handles file open/save dialogs, + toolbar state management, line/column indicators, and search functionality. + + Args: + xml_gui: The :class:`gtk.Builder` instance containing the GUI widgets. + outer_space: Reference to the parent application (typically + :class:`DamarisGUI`) that owns this widget set. + + Attributes: + editing_state (bool): ``True`` if scripts are editable, ``False`` during + experiment execution. + exp_script_filename (str or None): Path to the currently loaded + experiment script file. + res_script_filename (str or None): Path to the currently loaded + result script file. + experiment_script_textview (:class:`gtksourceview2.View`): Text view + for the experiment script. + data_handling_textview (:class:`gtksourceview2.View`): Text view for + the result script. + + Public Methods: + set_scripts: Replace script buffer contents. + get_scripts: Retrieve current script text from both buffers. + enable_editing: Re-enable script editing. + disable_editing: Lock scripts during experiment execution. + open_file: Open a script file via file chooser dialog. + open_hdf5: Load data and scripts from an HDF5 file. + save_file: Save the current script to its associated file. + save_file_as: Save the current script with a new filename. + save_all_files: Save both experiment and result scripts. + new_file: Clear the current script buffer. + check_script: Compile-check the current script for syntax errors. + undo / redo: Undo/redo text edits. + search: Open the search-and-replace dialog. + """ def __init__( self, xml_gui, outer_space ): - """ - initialize text widgets with text + """Initialize text widgets with syntax highlighting and completion. + + Sets up two :class:`gtksourceview2.View` instances with Python + syntax highlighting, keyword auto-completion, line numbers, and + smart indentation. Connects text buffer signals to toolbar and + status bar update handlers. + + Args: + xml_gui: The :class:`gtk.Builder` instance containing the GUI widgets. + outer_space: Reference to the parent application. """ self.xml_gui = xml_gui self.outer_space = outer_space @@ -2848,9 +2909,54 @@ pygobject version %(pygobject)s class MonitorWidgets: + """Manages the matplotlib-based data visualization panel. + + Provides an interactive plot canvas with zoom, pan, scaling controls, + a data source selector, and real-time updates from the DAMARIS data pool. + Supports :class:`Accumulation`, :class:`ADC_Result`, and + :class:`MeasurementResult` data types with automatic axis rescaling, + error bars, and statistics overlays. + + Args: + xml_gui: The :class:`gtk.Builder` instance containing the GUI widgets. + + Attributes: + matplot_figure (:class:`matplotlib.figure.Figure`): The underlying + matplotlib figure. + matplot_axes (:class:`matplotlib.axes.Axes`): The plot axes. + matplot_canvas (:class:`matplotlib.backends.backend_gtk3.FigureCanvas`): + The GTK canvas embedding the figure. + matplot_toolbar (:class:`matplotlib.backends.backend_gtk3.NavigationToolbar2GTK3`): + The navigation toolbar with pan/zoom/cursor controls. + data_pool (:class:`damaris.data.DataPool` or None): The data pool + being observed for real-time updates. + displayed_data (list): ``[data_name, data_object]`` of the currently + selected data, or ``[None, None]``. + + Public Methods: + observe_data_pool: Register a listener and begin observing a data pool. + source_list_reset: Reset the data source selector tree. + source_list_add: Add a data source entry to the selector tree. + source_list_remove: Remove a data source entry from the selector tree. + source_list_current: Get the currently selected data source name. + clear_display: Clear all plot elements and reset axes. + update_display: Redraw the plot with current data. + renew_display: Clear and redraw the plot with current data. + save_display_data_as_text: Export displayed data to a CSV file. + toggle_cursor: Toggle the matplotlib crosshair cursor. + copy_canvas_as_png: Copy the plot as a PNG image to the clipboard. + copy_canvas_as_svg: Copy the plot as SVG text to the clipboard. + """ def __init__( self, xml_gui ): - """ - initialize matplotlib widgets and stuff around + """Initialize matplotlib widgets, canvas, toolbar, and source selector. + + Creates a :class:`matplotlib.figure.Figure` with linear x/y axes, + embeds it in a GTK canvas, attaches a navigation toolbar with a + custom crosshair toggle button, and builds a hierarchical source + selector :class:`gtk.TreeStore`. + + Args: + xml_gui: The :class:`gtk.Builder` instance containing the GUI widgets. """ self.xml_gui = xml_gui @@ -3953,14 +4059,55 @@ class MonitorWidgets: class ScriptInterface: - """ - texts or code objects are executed as experiment and result script the backend is started with sufficient arguments + """Executes experiment and result scripts, coordinating with the DAMARIS backend. + + Manages the lifecycle of experiment and result script execution. Depending + on whether a backend executable is provided, it either uses + :class:`BackendDriver.BackendDriver` to spawn an external process or falls + back to in-process :class:`ExperimentWriter` and :class:`ResultReader` + components. A shared :class:`DataPool` is used for communication between + scripts and the GUI. + + Args: + exp_script (str or None): Python source code for the experiment script. + res_script (str or None): Python source code for the result script. + backend_executable (str or None): Path to the DAMARIS backend executable. + If ``None``, in-process execution is used. + spool_dir (str): Directory for inter-process communication spool files. + Defaults to ``"spool"``. + clear_jobs (bool): Clear pending jobs on startup. Defaults to ``True``. + clear_results (bool): Clear pending results on startup. Defaults to ``True``. + log_callback (callable or None): Optional callback for log messages. + + Attributes: + data (:class:`damaris.data.DataPool`): Shared data pool for + experiment/result communication. + exp_handling (:class:`ExperimentHandling.ExperimentHandling` or None): + The running experiment handler thread. + res_handling (:class:`ResultHandling.ResultHandling` or None): + The running result handler thread. + back_driver (:class:`BackendDriver.BackendDriver` or None): + The backend process driver, if a backend executable was provided. + + Public Methods: + runScripts: Start experiment, result, and backend handlers. """ def __init__( self, exp_script=None, res_script=None, backend_executable=None, spool_dir="spool", clear_jobs=True, clear_results=True, log_callback=None ): - """ - run experiment scripts and result scripts + """Initialize the script execution environment. + + Sets up the data pool, experiment writer, result reader, and optional + backend driver based on the provided configuration. + + Args: + exp_script (str or None): Python source code for the experiment script. + res_script (str or None): Python source code for the result script. + backend_executable (str or None): Path to the DAMARIS backend executable. + spool_dir (str): Directory for inter-process communication spool files. + clear_jobs (bool): Clear pending jobs on startup. + clear_results (bool): Clear pending results on startup. + log_callback (callable or None): Optional callback for log messages. """ self.exp_script = exp_script @@ -3995,6 +4142,13 @@ class ScriptInterface: self.data = DataPool( ) def runScripts( self ): + """Start experiment, result, and backend handler threads. + + Creates and starts :class:`ExperimentHandling` and + :class:`ResultHandling` threads, and optionally starts the backend + driver process. Waits for the backend to report a valid PID before + proceeding. + """ try: # get script engines self.exp_handling = self.res_handling = None