Frontend Module

The frontend module contains the Tkinter-based graphical user interface.

Main Menu

Main menu module. Contains the main application window and exit confirmation dialog.

frontend.ui_main_menu.create_main_menu(normal_fitting_callback, single_fit_multiple_datasets_callback, multiple_fits_single_dataset_callback, all_fits_single_dataset_callback, watch_data_callback, help_callback)

Create and display the main application menu window.

Parameters:

• normal_fitting_callback – Function to call for normal fitting

• single_fit_multiple_datasets_callback – Function to call for single fit on multiple datasets

• multiple_fits_single_dataset_callback – Function to call for multiple fits on single dataset

• all_fits_single_dataset_callback – Function to call for all fits on single dataset

• watch_data_callback – Function to call for viewing data

• help_callback – Function to display help information

Returns:

The main Tk window instance

frontend.ui_main_menu.show_exit_confirmation(parent_menu)

Display exit confirmation dialog.

Parameters:

parent_menu – The parent menu window to close if user confirms exit

frontend.ui_main_menu.start_main_menu(normal_fitting_callback, single_fit_multiple_datasets_callback, multiple_fits_single_dataset_callback, all_fits_single_dataset_callback, watch_data_callback, help_callback)

Create and run the main application menu.

This is the entry point for the GUI application.

Parameters:

• normal_fitting_callback – Function to call for normal fitting

• single_fit_multiple_datasets_callback – Function to call for single fit on multiple datasets

• multiple_fits_single_dataset_callback – Function to call for multiple fits on single dataset

• all_fits_single_dataset_callback – Function to call for all fits on single dataset

• watch_data_callback – Function to call for viewing data

• help_callback – Function to display help information

Image Utilities

Shared image loading and scaling for the Tkinter frontend.

frontend.image_utils.plot_display_path(output_path)

Return the path to use for displaying a plot in the GUI.

When the saved file is PDF, returns the _preview.png path if it exists, so Tkinter can show the image without breaking.

Parameters:

output_path – Full path to the saved plot file (e.g. PDF or PNG).

Returns:

Path to the image file to display (preview PNG for PDFs when available).

frontend.image_utils.preview_path_to_remove_after_display(display_path, original_output_path)

Return the path of an auxiliary preview file to remove after display.

If the displayed image is an auxiliary preview file (_preview.png), return its path so the caller can delete it after the window is closed.

Parameters:

• display_path – Path actually used for display (may be preview PNG).

• original_output_path – Original output path (e.g. PDF path).

Returns:

Path to the preview file to delete, or None if no cleanup needed.

frontend.image_utils.load_image_scaled(path, max_width, max_height)

Load an image from file and return a Tk PhotoImage scaled to fit within max dimensions.

Uses PIL when available. Supports PNG, JPG, JPEG. Returns None if the file cannot be opened (e.g. missing PIL), so callers can fall back to tkinter.PhotoImage(file=path) for raster formats or skip showing.

Parameters:

• path – Path to the image file.

• max_width – Maximum width in pixels.

• max_height – Maximum height in pixels.

Returns:

ImageTk.PhotoImage scaled to fit, or None on failure.

Keyboard Navigation

Keyboard navigation: arrow keys to move focus, Enter to activate.

frontend.keyboard_nav.bind_enter_to_accept(widgets, accept_callback)

Bind Enter key events to trigger accept callback on widgets.

Binds both <Return> and <KP_Enter> events on each widget to the accept_callback function, so that pressing Enter from input widgets (Spinbox, Entry, Combobox, etc.) triggers the accept action.

Parameters:

• widgets – Sequence of Tkinter widgets to bind events to.

• accept_callback – Callback function with signature () -> None to call when Enter is pressed.

frontend.keyboard_nav.setup_arrow_enter_navigation(widgets_grid, on_enter=None)

Set up keyboard navigation for a grid of widgets.

Binds arrow keys to move focus between widgets in the grid and Return/Enter keys to activate the focused widget. The grid is a 2D list of focusable widgets (e.g. ttk.Button); use None for empty cells.

Parameters:

• widgets_grid – 2D sequence of widgets arranged in a grid layout. Use None for empty cells in the grid.

• on_enter – Optional callback function called when Enter is pressed. Signature: on_enter(widget, event) -> bool. If it returns True, the default behavior (invoke button) is skipped. Use this to handle Enter on non-button widgets (e.g. radiobutton -> confirm dialog).

Window Positioning

Utilities for Tkinter window positioning.

frontend.window_utils.place_window_centered(win, width=None, height=None, *, preserve_size=False, max_width=900, max_height=650, max_width_ratio=0.7, max_height_ratio=0.7)

Position a Toplevel window centered on screen.

Parameters:

• win – The Toplevel window to position.

• width – Desired width in pixels. If None and not preserve_size, uses computed size.

• height – Desired height in pixels. If None and not preserve_size, uses computed size.

• preserve_size – If True, keeps the window’s current size and only sets position. Call after widgets are packed/gridded and after win.update_idletasks().

• max_width – Cap for width when computed from screen (default 900).

• max_height – Cap for height when computed from screen (default 650).

• max_width_ratio – Max width as fraction of screen when width is None.

• max_height_ratio – Max height as fraction of screen when height is None.

Dialogs

Main dialogs package (re-exports from ui_dialogs submodules).

UI Dialogs package. Contains all Tkinter dialog windows for user interaction, split by concern.

Load Data Dialog

Load data dialog using native file picker (replaces ask_file_type + ask_file_name).

frontend.ui_dialogs.load_data_dialog.open_load_dialog(parent)

Open native file dialog to select a data file (CSV, TXT, XLSX).

Replaces the two-step flow (file type + file name) with a single native OS dialog. Works on Windows, Linux, and macOS.

Parameters:

parent – Parent Tkinter window (Toplevel or Tk).

Returns:

Tuple (file_path, file_type) if user selects a file, or (None, None) if user cancels. file_type is one of ‘csv’, ‘txt’, ‘xlsx’.

Save Data Dialog

Save data dialog for the data view window.

frontend.ui_dialogs.save_data_dialog.open_save_dialog(parent, data, on_focus_data)

Open save file dialog for the current data.

Data Selection Dialog

Data selection dialogs: variables and data preview.

frontend.ui_dialogs.data_selection.ask_variables(parent_window, variable_names)

Dialog to select independent (x) and dependent (y) variables and plot name.

Parameters:

• parent_window – Parent Tkinter window.

• variable_names – List of available variable names from the dataset.

Returns:

Tuple of (x_name, y_name, plot_name). Returns ('', '', '') if user cancels.

frontend.ui_dialogs.data_selection.ask_multiple_x_variables(parent_window, variable_names, num_vars, first_x_name)

Dialog to select multiple independent (x) variables for multidimensional fitting.

Parameters:

• parent_window – Parent Tkinter window.

• variable_names – List of available variable names from the dataset.

• num_vars – Number of independent variables to select.

• first_x_name – Name of the first x variable already selected.

Returns:

List of x variable names. Returns empty list if user cancels.

frontend.ui_dialogs.data_selection.show_data_dialog(parent_window, data)

Dialog to display loaded data.

Provides transform, cleaning, save, and pair-plot options. Transform/clean dialogs are non-modal so focus stays on the data window for multiple ops. Pair plots auto-update when data is transformed (if already open).

Parameters:

• parent_window – Parent Tkinter window (Tk or Toplevel).

• data – DataFrame to display (or string). If DataFrame, converted to string for display using to_string() method.

Equation Dialog

Equation and parameter dialogs for fitting.

frontend.ui_dialogs.equation.ask_equation_type(parent_window)

Dialog to select fitting equation type.

Optionally allows configuring initial values and bounds per parameter. Displays a grid of buttons for predefined equation types, plus options for custom equations and exiting.

Parameters:

parent_window – Parent Tkinter window.

Returns:

Tuple of (equation_type, user_initial_guess, user_bounds). user_initial_guess and user_bounds are None when not configured.

frontend.ui_dialogs.equation.ask_num_parameters(parent_window)

Dialog to ask for number of parameters and independent variables in a custom function.

Displays a dialog with Spinboxes allowing the user to select the number of parameters (1-12) and number of independent variables (1-10) for a custom fitting function.

Parameters:

parent_window – Parent Tkinter window.

Returns:

Tuple of (number of parameters, number of independent variables), or None if the user closed the window.

frontend.ui_dialogs.equation.ask_parameter_names(parent_window, num_params)

Dialog to ask for parameter names in a custom function.

Displays a series of dialogs (one per parameter) asking the user to enter parameter names. Shows Unicode escape sequence hints for Greek letters. Parameter names are normalized (Unicode escapes replaced, whitespace removed).

Parameters:

• parent_window – Parent Tkinter window.

• num_params – Number of parameters to collect names for.

Returns:

List of parameter names entered by the user. Returns [EXIT_SIGNAL] if user cancels at any point.

frontend.ui_dialogs.equation.ask_custom_formula(parent_window, parameter_names, num_independent_vars=1)

Dialog to ask for custom function formula.

Displays a dialog allowing the user to enter a mathematical formula using the previously defined parameter names. Shows syntax hints and Unicode escape sequence reference for Greek letters.

Parameters:

• parent_window – Parent Tkinter window.

• parameter_names – List of parameter names that can be used in the formula.

• num_independent_vars – Number of independent variables (1 for x, >1 for x_0, x_1, etc.).

Returns:

Formula string entered by the user, with Unicode escape sequences normalized. Returns EXIT_SIGNAL if user cancels.

frontend.ui_dialogs.equation.ask_num_fits(parent_window, min_val=2, max_val=10)

Dialog to ask for number of multiple fits.

Displays a dialog with a Spinbox allowing the user to select the number of fits to perform (between min_val and max_val).

Parameters:

• parent_window – Parent Tkinter window.

• min_val – Minimum number of fits allowed (default: 2).

• max_val – Maximum number of fits allowed (default: 10).

Returns:

Selected number of fits (between min_val and max_val), or None if the user closed the window.

Help Dialog

Help dialog and text utilities for Tkinter display.

frontend.ui_dialogs.help.remove_markdown_bold(text)

Remove Markdown bold markers (**) from text for Tkinter display.

Only strips ** when the content between them has no asterisk, so exponentiation in code (e.g. x**2) is preserved.

Parameters:

text – String that may contain Markdown bold markers.

Returns:

String with **...** removed (content preserved).

frontend.ui_dialogs.help.show_data_view_help_dialog(parent_window)

Display help dialog for the Watch Data window (transform, clean, save options).

Shows collapsible sections: pair plots, transform (with each option detailed), clean (with each option detailed), and save. Used when the user clicks Help in the data view.

Parameters:

parent_window – Parent Tkinter window (the data view Toplevel).

frontend.ui_dialogs.help.show_help_dialog(parent_window)

Display help and information dialog about the application.

Shows information in collapsible sections (like the config dialog): objective, advantages, fitting modes, custom functions, data format, data location, output location, and statistics.

Parameters:

parent_window – Parent Tkinter window (Tk or Toplevel).

Configuration Dialog

Configuration dialog for editing .env settings.

frontend.ui_dialogs.config_dialog.show_config_dialog(parent_window)

Show configuration dialog to edit .env fields.

Pre-fills with current env values (or defaults). On Accept, writes .env and returns True so the caller can restart the app. On Cancel returns False.

Parameters:

parent_window – Parent Tkinter window (Tk or Toplevel).

Returns:

True if user accepted and .env was written (caller should restart). False if user cancelled.

Result Dialog

Result window for displaying fitting results and plot.

frontend.ui_dialogs.result.create_result_window(fit_name, text, equation_str, output_path, figure_3d=None, fit_info=None)

Create a Tkinter window to display the fitting results.

Creates a new Toplevel window showing the fitting results including parameter values, uncertainties, statistics, and the fitted equation plot.

Parameters:

• fit_name – Name of the fit for window title.

• text – Formatted text with parameters, uncertainties, and statistics.

• equation_str – Formatted equation string with parameter values.

• output_path – Path to the plot image file to display.

• figure_3d – Optional matplotlib Figure for 3D plot (embeds interactive canvas, rotatable with mouse).

• fit_info – Optional dict with ‘fit_func’, ‘params’, ‘cov’, ‘x_names’ for prediction feature.

Returns:

The created Toplevel window instance.

Tooltip

Tooltip binding for Tkinter widgets.

frontend.ui_dialogs.tooltip.bind_tooltip(widget, text, delay_ms=500)

Bind a tooltip to a Tkinter widget.

Shows a tooltip window after a delay when the mouse enters the widget, and hides it when the mouse leaves. Uses a contrasting background and border so the tooltip is visible over the UI.

Parameters:

• widget – Tkinter widget to bind the tooltip to.

• text – Tooltip text to display when mouse hovers over the widget.

• delay_ms – Delay in milliseconds before showing the tooltip (default: 500).