diff --git a/src/musredit_qt6/musredit/PTextEdit.cpp b/src/musredit_qt6/musredit/PTextEdit.cpp index fefcdf2f3..4455a698c 100644 --- a/src/musredit_qt6/musredit/PTextEdit.cpp +++ b/src/musredit_qt6/musredit/PTextEdit.cpp @@ -27,6 +27,69 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PTextEdit.cpp + * @brief Implementation of the main window class for musredit. + * + * @details This file provides the complete implementation of the PTextEdit + * class which serves as the main application window for musredit. It handles + * all user interactions including file operations, text editing, menu and + * toolbar actions, dialog management, external process execution, and + * integration with the musrfit analysis framework. + * + * **Key Implementation Areas:** + * + * - **Menu and Toolbar Setup**: Configures all application menus (File, Edit, + * Text, Musr, Help) with appropriate icons, shortcuts, and signal-slot + * connections. Theme-aware icon selection supports both light and dark modes. + * + * - **File Operations**: Implements new file creation, opening, saving, closing, + * printing, and recent file tracking. Includes save-before-close prompts and + * file system change monitoring. + * + * - **Text Editing**: Provides comprehensive editing operations including undo/ + * redo, cut/copy/paste, select all, comment/uncomment, and font management. + * + * - **Find and Replace**: Implements full-featured search with options for case + * sensitivity, whole word matching, search direction, and scope (selection or + * entire document). Replace operations support interactive confirmation or + * batch processing. + * + * - **MSR File Block Insertion**: Delegates to PSubTextEdit for dialog-based + * insertion of all msr file block types (FITPARAMETER, THEORY, FUNCTIONS, + * RUN, COMMANDS, FOURIER, PLOT, STATISTIC). + * + * - **External Tool Integration**: Spawns and manages external processes: + * - musrfit: Fitting engine execution with output capture + * - musrview: Data visualization + * - musrWiz: Interactive msr file creation wizard + * - musrT0: Timing parameter determination + * - musrStep: Step size configuration + * - msr2data: Batch data conversion + * - mupp: Parameter evolution plotting + * + * - **Tab Management**: Implements multi-document interface with tab creation, + * switching, reordering, and closing. Maintains filename associations and + * tracks modification state for each tab. + * + * - **File System Monitoring**: Uses QFileSystemWatcher to detect external + * changes to open files, prompting user to reload when modifications occur. + * + * - **Theme Detection**: Automatically detects system theme (light/dark) and + * selects appropriate icon variants for optimal visibility. + * + * - **Configuration Persistence**: Loads and saves application settings via + * PAdmin including fonts, window dimensions, default paths, recent files, + * and theme preferences. + * + * @author Andreas Suter + * @date 2010-2025 + * + * @see PTextEdit.h for class interface documentation + * @see PSubTextEdit for the text editor widget implementation + * @see PAdmin for configuration management + */ + #include #include @@ -82,10 +145,14 @@ //---------------------------------------------------------------------------------------------------- /** - *

Constructor + * @brief Constructs the main musredit application window. * - * \param parent pointer to the parent object - * \param f qt windows flags + * @details Initializes the complete musredit environment with all menus, + * toolbars, file system monitoring, theme detection, and configuration + * management. This constructor performs extensive setup to create a + * fully-functional msr file editor with integrated analysis capabilities. + * + * @param parent Pointer to parent widget (typically nullptr for main window). */ PTextEdit::PTextEdit( QWidget *parent ) : QMainWindow( parent ) @@ -161,8 +228,21 @@ PTextEdit::PTextEdit( QWidget *parent ) //---------------------------------------------------------------------------------------------------- /** - *

This slot is called if the main application is on the way to quit. This ensures that allocated - * memory indeed can be free'd. + * @brief Cleanup handler called before application termination. + * + * @details Frees dynamically allocated data structures that are not managed + * by Qt's parent-child ownership system. This slot is connected to + * QApplication::aboutToQuit() to ensure proper cleanup during shutdown. + * + * **Resources freed:** + * - PMsr2DataParam structure (msr2data configuration) + * - PFindReplaceData structure (find/replace settings) + * + * Both pointers are checked for nullptr before deletion and set to nullptr + * afterward to prevent double deletion. + * + * @note Qt's parent-child ownership automatically handles GUI widget cleanup. + * @note This method should only be called once during application shutdown. */ void PTextEdit::aboutToQuit() { @@ -178,7 +258,22 @@ void PTextEdit::aboutToQuit() //---------------------------------------------------------------------------------------------------- /** - *

Setup the file menu and the necessary actions. + * @brief Initializes the File menu and toolbar. + * + * @details Creates and configures all File menu items and corresponding + * toolbar buttons. Each action includes: + * - Icon (with theme-appropriate variant) + * - Keyboard shortcut + * - Status bar tip + * - Signal-slot connection + * + * **Menu Items Created:** + * New, Open, Recent Files, Reload, Open Prefs, Save, Save As, Save Prefs, + * Print, Close, Close All, Close All Others, Exit + * + * **Theme Support:** + * Icons are loaded in dark and plain variants. Menu and toolbar may use + * different variants based on system theme detection and user preferences. */ void PTextEdit::setupFileActions() { @@ -355,7 +450,12 @@ void PTextEdit::setupFileActions() //---------------------------------------------------------------------------------------------------- /** - *

Setup the edit menu and the necessary actions. + * @brief Initializes the Edit menu and toolbar. + * + * @details Creates and configures all Edit menu items and corresponding + * toolbar buttons including Undo, Redo, Select All, Copy, Cut, Paste, + * Find, Find Next, Find Previous, Replace, Comment, and Uncomment. + * Each action includes icons (theme-aware), shortcuts, and connections. */ void PTextEdit::setupEditActions() { @@ -637,7 +737,11 @@ void PTextEdit::setupEditActions() //---------------------------------------------------------------------------------------------------- /** - *

Setup the font/font size menu. + * @brief Initializes the Text menu and font toolbar controls. + * + * @details Creates the Text menu and adds font family and font size combo + * boxes to the toolbar. Users can select from available system fonts and + * standard font sizes to customize the editor appearance. */ void PTextEdit::setupTextActions() { @@ -675,7 +779,14 @@ void PTextEdit::setupTextActions() //---------------------------------------------------------------------------------------------------- /** - *

Setup the musrfit menu and the necessary actions. + * @brief Initializes the Musr menu and toolbar. + * + * @details Creates and configures all µSR-specific menu items including + * analysis tools (musrFit, musrView, msr2data, musrT0, musrFT, musrCalcChisq, + * musrStep, musrDump, mupp), utility functions (musrWiz, musrSwapMsrMlog), + * and all block insertion commands (Title, FITPARAMETER, THEORY, FUNCTIONS, + * RUN blocks, COMMANDS, FOURIER, PLOT, STATISTIC). Includes theory function + * submenu with all available theory functions. */ void PTextEdit::setupMusrActions() { @@ -957,7 +1068,11 @@ void PTextEdit::setupMusrActions() //---------------------------------------------------------------------------------------------------- /** - *

Setup the help menu and the necessary actions. + * @brief Initializes the Help menu. + * + * @details Creates the Help menu with actions for accessing online + * documentation (Contents), displaying Qt version information (About Qt), + * and showing the musredit About dialog with version and copyright info. */ void PTextEdit::setupHelpActions() { diff --git a/src/musredit_qt6/musredit/PTextEdit.h b/src/musredit_qt6/musredit/PTextEdit.h index 6a03808eb..3c8b5dbca 100644 --- a/src/musredit_qt6/musredit/PTextEdit.h +++ b/src/musredit_qt6/musredit/PTextEdit.h @@ -27,6 +27,26 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PTextEdit.h + * @brief Main window class for the musredit application. + * + * @details This header defines the PTextEdit class which implements the main + * application window for musredit, a specialized editor for musrfit msr files. + * The class provides a complete IDE-like environment with multi-tab editing, + * integrated fit execution, data visualization, and comprehensive menu/toolbar + * interfaces tailored for µSR data analysis workflows. + * + * @author Andreas Suter + * @date 2010-2025 + * @copyright Copyright (C) 2010-2025 by Andreas Suter + * @license GNU General Public License v2 or later + * + * @see PSubTextEdit Text editor widget used in each tab + * @see PAdmin Global administration and configuration + * @see musrfit Main fitting application + */ + #ifndef _PTEXTEDIT_H_ #define _PTEXTEDIT_H_ @@ -62,113 +82,873 @@ class QMenu; //---------------------------------------------------------------------------------------------- /** - *

Main class for musredit. + * @class PTextEdit + * @brief Main window class for the musredit application. + * + * @details PTextEdit is the primary window class that orchestrates the entire + * musredit application. It provides a comprehensive environment for creating, + * editing, and managing msr (muon spin rotation/relaxation fit) files with + * integrated analysis capabilities. + * + * @par Application Architecture: + * The application follows a tab-based document interface where: + * - Each tab contains a PSubTextEdit widget for editing one msr file + * - Multiple files can be open simultaneously in separate tabs + * - Tabs can be reordered by dragging + * - Each tab maintains independent undo/redo state + * - File system watcher monitors external changes to open files + * + * @par Menu Structure: + * **File Menu:** + * - New, Open, Recent Files, Reload + * - Save, Save As, Save Prefs + * - Print + * - Close, Close All, Close All Others + * - Exit + * + * **Edit Menu:** + * - Undo, Redo + * - Select All + * - Copy, Cut, Paste + * - Find, Find Next, Find Previous + * - Find and Replace + * - Comment, Uncomment + * + * **Text Menu:** + * - Font family selection + * - Font size selection + * + * **Musr Menu:** + * - musrWiz (wizard for msr file creation) + * - musrCalcChisq (calculate chi-square) + * - musrFit (run fit with current msr file) + * - msr2data (convert msr to data files) + * - musrView (view fit results) + * - musrView2Dat (view two data files) + * - musrT0 (determine t0 timing parameter) + * - musrFT (Fourier transform) + * - musrPrefs (preferences dialog) + * - musrSwapMsrMlog (swap between msr and mlog files) + * - musrSetSteps (set fit step sizes) + * - musrDump (dump run data) + * - mupp (muon parameter plot) + * - Block insertion dialogs for all msr file block types + * + * **Help Menu:** + * - Contents (online documentation) + * - About Qt + * - About musredit + * + * @par Integrated Analysis Features: + * The editor provides direct integration with musrfit analysis tools: + * - **musrFit**: Execute fits directly from the editor + * - **musrView**: Launch data visualization immediately after fitting + * - **msr2data**: Batch convert msr files to data format + * - **musrT0**: Determine timing parameters interactively + * - **musrFT**: Perform Fourier transforms on µSR data + * - **musrDump**: Inspect raw histogram data + * + * @par Block Insertion Dialogs: + * Dialog-based assistants for creating structured msr file blocks: + * - Title block (optional description) + * - FITPARAMETER block (parameter definitions) + * - THEORY block (fit functions) + * - FUNCTIONS block (user-defined functions) + * - RUN blocks (asymmetry, single histogram, non-µSR) + * - COMMANDS block (MINUIT commands) + * - FOURIER block (frequency analysis) + * - PLOT block (visualization settings) + * - STATISTIC block (fit results) + * + * @par File System Monitoring: + * The class uses QFileSystemWatcher to detect external modifications: + * - Notifies user when an open file changes on disk + * - Offers to reload the modified file + * - Prevents data loss from conflicting edits + * - Temporarily disabled during save operations + * + * @par Theme Support: + * Automatic adaptation to system themes: + * - Detects light vs. dark themes + * - Selects appropriate icon sets for menu and toolbar + * - Theme preferences saved in musredit_startup.xml + * - Manual override available in preferences + * + * @par Configuration Management: + * The class relies on PAdmin for persistent configuration: + * - Default directories (save path, executable paths) + * - Font preferences (family, size) + * - Editor dimensions (width, height) + * - Recent file list (up to MAX_RECENT_FILES) + * - Theme icon preferences + * - Theory function definitions + * - Help URL locations + * + * @par Find and Replace: + * Comprehensive search functionality: + * - Find with regular expression support + * - Find Next/Previous for iterating matches + * - Replace with confirmation or batch mode + * - Options: case sensitive, whole words, backwards search + * - Scope: entire document or selected text only + * + * @par Process Management: + * The editor spawns external processes for analysis: + * - musrWiz: Interactive msr file creation wizard + * - musrFit: Fitting engine execution + * - musrView: Results visualization + * - musrT0: Timing parameter determination + * - Exit status monitoring with appropriate error handling + * + * @par Recent Files: + * Maintains a list of recently opened files: + * - Quick access via File → Recent Files menu + * - Automatically updated when files are opened + * - Persisted across application sessions + * - Maximum of MAX_RECENT_FILES entries + * + * @par Tab Management: + * Advanced tab functionality: + * - Create new tabs (Ctrl+N) + * - Close individual tabs (Ctrl+W) + * - Close all tabs + * - Close all tabs except current (Ctrl+Shift+W) + * - Reorder tabs by dragging + * - Switch tabs via keyboard or mouse + * - Tab titles show filename (modified indicator if unsaved) + * + * @par Jump to Block: + * Quick navigation within msr files: + * - Combo box in toolbar lists all msr file blocks + * - Select block to jump cursor to that location + * - Automatically updates as file content changes + * - Helps navigate large msr files efficiently + * + * @note This class serves as the main entry point for the musredit application. + * @note The class manages the application lifecycle including initialization + * and cleanup of all resources. + * @note All dialog-based operations are modal to ensure focused interaction. + * + * @see PSubTextEdit For the text editor widget in each tab + * @see PAdmin For configuration and administration + * @see musrfit For the fitting engine + * @see musrview For data visualization */ class PTextEdit : public QMainWindow { Q_OBJECT public: + /** + * @brief Constructs the main musredit window. + * + * @details Initializes the complete musredit application window including + * menus, toolbars, tab widget, configuration management, file system + * monitoring, and theme detection. If command-line arguments are provided, + * attempts to load those files; otherwise creates a new empty file. + * + * **Initialization sequence:** + * 1. Load configuration from musredit_startup.xml via PAdmin + * 2. Detect system theme and select appropriate icon sets + * 3. Configure default editor dimensions from preferences + * 4. Initialize file system watcher for change detection + * 5. Set up all menus and toolbars (File, Edit, Text, Musr, Help) + * 6. Create tab widget for multi-document interface + * 7. Apply font settings from preferences + * 8. Set application icon based on theme + * 9. Load files from command-line arguments or create new file + * 10. Connect tab change signal to font settings application + * 11. Initialize status bar + * + * **Theme Detection:** + * The constructor attempts to detect the system theme automatically: + * - Recognizes light and dark themes + * - Selects appropriate icon sets (dark/plain variants) + * - Falls back to preferences if detection fails + * - Updates preferences with detected theme + * + * **File System Watcher:** + * Monitors open files for external changes: + * - Detects modifications, deletions, renames + * - Prompts user to reload when changes detected + * - Prevents data loss from conflicting edits + * + * **Command-Line File Loading:** + * If arguments are provided: + * @code + * musredit file1.msr file2.msr file3.msr + * @endcode + * Each file is loaded into a separate tab. + * + * @param parent Pointer to parent widget. Typically nullptr for the main + * window. If provided, establishes parent-child relationship + * for proper memory management and event propagation. + * + * @note The constructor displays error messages via QMessageBox if critical + * initialization steps fail (e.g., file system watcher creation). + * @note Font and size combo boxes are created and added to toolbar during + * text actions setup. + * @note All menus and toolbars are configured with keyboard shortcuts + * and status tips for accessibility. + * + * @see PAdmin For configuration management + * @see setupFileActions() Creates File menu and toolbar + * @see setupEditActions() Creates Edit menu and toolbar + * @see setupTextActions() Creates Text menu and toolbar + * @see setupMusrActions() Creates Musr menu and toolbar + * @see setupHelpActions() Creates Help menu + * @see load() For file loading mechanism + */ PTextEdit( QWidget *parent = nullptr ); + /** + * @brief Gets the configured editor width. + * + * @details Returns the default editor window width as configured in the + * musredit preferences. This value is loaded from musredit_startup.xml + * during initialization and represents the preferred window width in pixels. + * + * @return int Editor width in pixels (default typically 900). + * + * @see getEditH() For editor height + * @see PAdmin::getEditWidth() Source of the width value + */ int getEditW() { return fEditW; } + + /** + * @brief Gets the configured editor height. + * + * @details Returns the default editor window height as configured in the + * musredit preferences. This value is loaded from musredit_startup.xml + * during initialization and represents the preferred window height in pixels. + * + * @return int Editor height in pixels (default typically 800). + * + * @see getEditW() For editor width + * @see PAdmin::getEditHeight() Source of the height value + */ int getEditH() { return fEditH; } public slots: + /** + * @brief Slot: Cleanup handler called before application quits. + * + * @details Performs final cleanup of dynamically allocated resources before + * the application terminates. This slot is typically connected to + * QApplication::aboutToQuit() signal to ensure proper memory deallocation. + * + * **Resources freed:** + * - fMsr2DataParam: msr2data configuration structure + * - fFindReplaceData: find/replace settings structure + * + * Both pointers are safely checked for nullptr before deletion and set to + * nullptr after freeing to prevent double deletion. + * + * @note This slot should be called only once during application shutdown. + * @note Qt's parent-child ownership handles cleanup of most GUI elements; + * this only handles explicitly allocated data structures. + * + * @see PMsr2DataParam For msr2data configuration structure + * @see PFindReplaceData For find/replace settings structure + */ void aboutToQuit(); signals: + /** + * @brief Signal: Emitted when the main window is closing. + * + * @details This signal notifies connected objects that the main window + * is about to close. Can be used to trigger cleanup operations in other + * components or to synchronize shutdown sequencing. + * + * @note Not to be confused with QWidget::close() method; this is a custom + * signal specific to PTextEdit. + */ void close(); private: + /** + * @brief Initializes File menu and toolbar actions. + * + * @details Creates and configures all File menu items and corresponding + * toolbar buttons including New, Open, Recent Files, Reload, Save, Print, + * Close, and Exit. Sets up keyboard shortcuts, status tips, icons (with + * theme-appropriate variants), and signal-slot connections. + * + * @see fileNew(), fileOpen(), fileSave(), etc. for slot implementations + */ void setupFileActions(); + + /** + * @brief Initializes Edit menu and toolbar actions. + * + * @details Creates and configures all Edit menu items and corresponding + * toolbar buttons including Undo, Redo, Select All, Copy, Cut, Paste, + * Find, Find Next, Find Previous, Replace, Comment, and Uncomment. + * + * @see editUndo(), editCopy(), editFind(), etc. for slot implementations + */ void setupEditActions(); + + /** + * @brief Initializes Text menu and toolbar actions. + * + * @details Creates font family and font size combo boxes in the toolbar, + * allowing users to change text formatting for the current editor. + * + * @see textFamily(), textSize() for slot implementations + */ void setupTextActions(); + + /** + * @brief Initializes Musr menu and toolbar actions. + * + * @details Creates and configures all µSR-specific menu items including + * musrWiz, musrFit, msr2data, musrView, musrT0, musrFT, and all block + * insertion commands. Sets up icons, shortcuts, and connections to + * analysis tools. + * + * @see musrFit(), musrView(), insertTheoryBlock(), etc. for implementations + */ void setupMusrActions(); + + /** + * @brief Initializes Help menu actions. + * + * @details Creates Help menu with Contents (online documentation), + * About Qt, and About musredit items. + * + * @see helpContents(), helpAbout() for slot implementations + */ void setupHelpActions(); + + /** + * @brief Initializes the Jump to Block combo box. + * + * @details Creates a combo box in the toolbar that lists all msr file + * blocks (FITPARAMETER, THEORY, RUN, COMMANDS, etc.), allowing quick + * navigation to any block by selecting it from the dropdown. + * + * @see jumpToBlock() for the navigation slot implementation + */ void setupJumpToBlock(); + + /** + * @brief Loads a file into the editor. + * + * @details Opens and loads the specified file into a new tab or existing + * tab if already open. Handles file reading, error checking, and tab + * creation/switching. Updates recent files list and file system watcher. + * + * @param f Absolute or relative path to the file to load. + * @param index Optional tab index where file should be loaded. If -1 + * (default), creates a new tab or switches to existing tab. + * + * @see fileOpen() for the user-facing file open dialog + * @see fileAlreadyOpen() to check if file is already loaded + */ void load( const QString &f, const int index=-1 ); + + /** + * @brief Gets the currently active editor widget. + * + * @details Returns a pointer to the PSubTextEdit widget in the currently + * visible tab. Returns nullptr if no tabs are open. + * + * @return PSubTextEdit* Pointer to current editor, or nullptr if none. + * + * @see PSubTextEdit for the editor widget class + */ PSubTextEdit *currentEditor() const; + + /** + * @brief Establishes signal-slot connections for an editor. + * + * @details Connects the given editor widget's signals to appropriate slots + * in the main window for font changes, text changes, cursor position + * updates, and other editor events. + * + * @param e Pointer to the PSubTextEdit widget to connect. Must not be nullptr. + * + * @see fontChanged(), textChanged(), currentCursorPosition() for connected slots + */ void doConnections( PSubTextEdit *e ); + + /** + * @brief Manages file system watcher activation state. + * + * @details Enables or disables the file system watcher based on + * fFileSystemWatcherActive flag. Called after file operations to prevent + * spurious change notifications during saves. + * + * @see fileChanged() for handling file change notifications + */ void fileSystemWatcherActivation(); private slots: + // Block insertion slots (delegate to PSubTextEdit) + /** + * @brief Slot: Inserts a title block into the current editor. + * @details Delegates to PSubTextEdit::insertTitle(). + * @see PSubTextEdit::insertTitle() + */ void insertTitle(); + + /** + * @brief Slot: Inserts a FITPARAMETER block into the current editor. + * @details Delegates to PSubTextEdit::insertParameterBlock(). + * @see PSubTextEdit::insertParameterBlock() + */ void insertParameterBlock(); + + /** + * @brief Slot: Inserts a THEORY block into the current editor. + * @details Delegates to PSubTextEdit::insertTheoryBlock(). + * @see PSubTextEdit::insertTheoryBlock() + */ void insertTheoryBlock(); + + /** + * @brief Slot: Inserts a specific theory function into the current editor. + * @param a QAction containing the theory function name. + * @details Extracts theory function name from action and delegates to + * PSubTextEdit::insertTheoryFunction(). + * @see PSubTextEdit::insertTheoryFunction() + */ void insertTheoryFunction(QAction *a); + + /** + * @brief Slot: Inserts a FUNCTIONS block into the current editor. + * @details Delegates to PSubTextEdit::insertFunctionBlock(). + * @see PSubTextEdit::insertFunctionBlock() + */ void insertFunctionBlock(); + + /** + * @brief Slot: Inserts an asymmetry RUN block into the current editor. + * @details Delegates to PSubTextEdit::insertAsymRunBlock(). + * @see PSubTextEdit::insertAsymRunBlock() + */ void insertAsymRunBlock(); + + /** + * @brief Slot: Inserts a single histogram RUN block into the current editor. + * @details Delegates to PSubTextEdit::insertSingleHistRunBlock(). + * @see PSubTextEdit::insertSingleHistRunBlock() + */ void insertSingleHistRunBlock(); + + /** + * @brief Slot: Inserts a non-µSR RUN block into the current editor. + * @details Delegates to PSubTextEdit::insertNonMusrRunBlock(). + * @see PSubTextEdit::insertNonMusrRunBlock() + */ void insertNonMusrRunBlock(); + + /** + * @brief Slot: Inserts a COMMANDS block into the current editor. + * @details Delegates to PSubTextEdit::insertCommandBlock(). + * @see PSubTextEdit::insertCommandBlock() + */ void insertCommandBlock(); + + /** + * @brief Slot: Inserts a FOURIER block into the current editor. + * @details Delegates to PSubTextEdit::insertFourierBlock(). + * @see PSubTextEdit::insertFourierBlock() + */ void insertFourierBlock(); + + /** + * @brief Slot: Inserts a PLOT block into the current editor. + * @details Delegates to PSubTextEdit::insertPlotBlock(). + * @see PSubTextEdit::insertPlotBlock() + */ void insertPlotBlock(); + + /** + * @brief Slot: Inserts a STATISTIC block into the current editor. + * @details Delegates to PSubTextEdit::insertStatisticBlock(). + * @see PSubTextEdit::insertStatisticBlock() + */ void insertStatisticBlock(); + // File menu slots + /** + * @brief Slot: Creates a new empty msr file in a new tab. + * @details Creates a new tab with an empty PSubTextEdit widget ready for + * editing. The new file is initially untitled until saved. + */ void fileNew(); + + /** + * @brief Slot: Opens a file dialog to load an msr file. + * @details Displays QFileDialog for file selection, then loads the chosen + * file via load(). Filters for .msr and .mlog files by default. + * @see load() for the actual file loading mechanism + */ void fileOpen(); + + /** + * @brief Slot: Opens a recently used file. + * @details Identifies which recent file action was triggered and loads + * that file. Updates the recent files list. + * @see fillRecentFiles() for recent files management + */ void fileOpenRecent(); + + /** + * @brief Slot: Reloads the current file from disk. + * @details Discards any unsaved changes and reloads the current file. + * Prompts user to confirm if file has been modified. + */ void fileReload(); + + /** + * @brief Slot: Opens the preferences file in a new tab. + * @details Loads musredit_startup.xml into the editor for direct editing + * of application preferences. + * @see fileSavePrefs() to save preferences changes + */ void fileOpenPrefs(); + + /** + * @brief Slot: Saves the current file. + * @details Saves the current editor content to disk. If file is untitled, + * prompts for a filename via fileSaveAs(). Temporarily disables + * file system watcher during save to prevent change notifications. + * @see fileSaveAs() for save with filename prompt + */ void fileSave(); + + /** + * @brief Slot: Saves the current file with a new name. + * @details Displays QFileDialog to choose save location and filename, + * then saves current editor content. Updates tab title and + * recent files list. + */ void fileSaveAs(); + + /** + * @brief Slot: Saves the preferences file. + * @details If preferences file (musredit_startup.xml) is currently being + * edited, saves it. Otherwise displays a message. + */ void fileSavePrefs(); + + /** + * @brief Slot: Prints the current file. + * @details Displays QPrintDialog and prints the current editor content + * to the selected printer or PDF file. + */ void filePrint(); + + /** + * @brief Slot: Closes the current tab. + * @param check If true, prompts to save if file has been modified. + * If false, closes without checking for changes. + * @details Closes the active tab and removes associated editor widget. + * If last tab is closed, creates a new empty tab. + */ void fileClose( const bool check = true ); + + /** + * @brief Slot: Closes all open tabs. + * @details Iterates through all tabs, prompting to save modified files, + * then closes all tabs. Creates one new empty tab afterward. + */ void fileCloseAll(); + + /** + * @brief Slot: Closes all tabs except the current one. + * @details Prompts to save modified files, then closes all tabs except + * the currently active tab. + */ void fileCloseAllOthers(); + + /** + * @brief Slot: Exits the application. + * @details Closes all tabs (prompting to save changes), then quits the + * application. Emits close() signal before exiting. + */ void fileExit(); + // Edit menu slots + /** @brief Slot: Undo last edit operation. */ void editUndo(); + + /** @brief Slot: Redo previously undone edit operation. */ void editRedo(); + + /** @brief Slot: Select all text in current editor. */ void editSelectAll(); + + /** @brief Slot: Cut selected text to clipboard. */ void editCut(); + + /** @brief Slot: Copy selected text to clipboard. */ void editCopy(); + + /** @brief Slot: Paste text from clipboard at cursor position. */ void editPaste(); + + /** + * @brief Slot: Opens find dialog. + * @details Displays PFindDialog for searching text in current editor. + * @see editFindNext(), editFindPrevious() for iterative search + */ void editFind(); + + /** + * @brief Slot: Finds next occurrence of search text. + * @details Uses settings from last find operation to search forward. + */ void editFindNext(); + + /** + * @brief Slot: Finds previous occurrence of search text. + * @details Uses settings from last find operation to search backward. + */ void editFindPrevious(); + + /** + * @brief Slot: Opens find and replace dialog. + * @details Displays PReplaceDialog for searching and replacing text. + * @see replace(), replaceAll() for replacement operations + */ void editFindAndReplace(); + + /** + * @brief Slot: Comments out selected lines. + * @details Adds '#' character at the beginning of each selected line. + */ void editComment(); + + /** + * @brief Slot: Uncomments selected lines. + * @details Removes leading '#' character from each selected line. + */ void editUncomment(); + // Text menu slots + /** + * @brief Slot: Changes font family for current editor. + * @param f Font family name (e.g., "Courier", "Monospace"). + */ void textFamily( const QString &f ); + + /** + * @brief Slot: Changes font size for current editor. + * @param p Font size as string (e.g., "10", "12", "14"). + */ void textSize( const QString &p ); + // Musr menu slots + /** + * @brief Slot: Launches musrWiz (msr file creation wizard). + * @details Spawns musrWiz as external process for interactive msr file + * creation with step-by-step guidance. + */ void musrWiz(); + + /** + * @brief Slot: Calculates chi-square for current msr file. + * @details Runs musrfit with chi-square calculation mode. + */ void musrCalcChisq(); + + /** + * @brief Slot: Executes fit with current msr file. + * @details Saves current file, runs musrfit fitting engine, captures + * output, and optionally launches musrView for visualization. + */ void musrFit(); + + /** + * @brief Slot: Opens msr2data conversion dialog. + * @details Displays PMsr2DataDialog for batch conversion of msr files + * to various data formats. + * @see PMsr2DataDialog for conversion options + */ void musrMsr2Data(); + + /** + * @brief Slot: Launches musrView for viewing fit results. + * @details Spawns musrview to visualize data and fit from current msr file. + */ void musrView(); + + /** + * @brief Slot: Launches musrView in 2-data file mode. + * @details Spawns musrview to compare two data files side-by-side. + */ void musrView2Dat(); + + /** + * @brief Slot: Opens musrT0 dialog for determining t0 timing parameter. + * @details Launches tool to determine t0 (time zero) from raw data. + */ void musrT0(); + + /** + * @brief Slot: Opens Fourier transform dialog. + * @details Displays PGetMusrFTOptionsDialog for configuring and + * performing Fourier transforms on µSR data. + */ void musrFT(); + + /** + * @brief Slot: Opens preferences dialog. + * @details Displays PPrefsDialog for configuring application settings + * like default paths, font, editor dimensions, theme icons. + * @see PPrefsDialog for available preferences + */ void musrPrefs(); + + /** + * @brief Slot: Swaps between .msr and .mlog files. + * @details If current file is .msr, switches to corresponding .mlog file + * (fit log). If .mlog, switches to .msr file. + */ void musrSwapMsrMlog(); + + /** + * @brief Slot: Launches musrStep for setting fit step sizes. + * @details Spawns musrStep tool to configure MINUIT step sizes for + * parameters based on parameter statistics. + */ void musrSetSteps(); + + /** + * @brief Slot: Dumps raw histogram data from run files. + * @details Displays dialog to select run file and dump raw data in + * various formats for inspection or external analysis. + */ void musrDump(); + + /** + * @brief Slot: Launches mupp (muon parameter plot). + * @details Spawns mupp tool for plotting parameter evolution across + * multiple msr files. + */ void mupp(); + // Help menu slots + /** + * @brief Slot: Opens online documentation. + * @details Launches web browser with musrfit/musredit documentation URL. + */ void helpContents(); + + /** + * @brief Slot: Displays Qt About dialog. + * @details Shows QMessageBox::aboutQt() with Qt version information. + */ void helpAboutQt(); + + /** + * @brief Slot: Displays musredit About dialog. + * @details Shows PMusrEditAbout dialog with version and copyright info. + * @see PMusrEditAbout for about dialog implementation + */ void helpAbout(); + // Process exit status handlers + /** + * @brief Slot: Handles exit status of musrWiz process. + * @param exitCode Process exit code (0 = success, non-zero = error). + * @param exitStatus Exit status (normal exit or crash). + * @details Called when musrWiz process terminates. Checks for errors + * and displays appropriate messages. + */ void exitStatusMusrWiz(int exitCode, QProcess::ExitStatus exitStatus); + + /** + * @brief Slot: Handles exit status of musrSetSteps process. + * @param exitCode Process exit code (0 = success, non-zero = error). + * @param exitStatus Exit status (normal exit or crash). + * @details Called when musrSetSteps process terminates. Checks for errors + * and displays appropriate messages. + */ void exitStatusMusrSetSteps(int exitCode, QProcess::ExitStatus exitStatus); + // Editor event handlers + /** + * @brief Slot: Responds to font changes in editor. + * @param f New font that was applied to the editor. + * @details Updates font combo boxes in toolbar to reflect current font. + */ void fontChanged( const QFont &f ); + + /** + * @brief Slot: Responds to text changes in editor. + * @param forced If true, forces update even if fFontChanging is true. + * @details Updates window title to show modified state, refreshes + * jump-to-block combo box to reflect current msr file structure. + */ void textChanged(const bool forced = false); + + /** + * @brief Slot: Updates status bar with current cursor position. + * @details Displays current line and column number in status bar as + * "Line: X, Col: Y". + */ void currentCursorPosition(); + // Find/replace operation handlers + /** + * @brief Slot: Replaces current match and finds next occurrence. + * @details Performs replacement at current cursor position, then searches + * for next match. Used in interactive replace mode. + */ void replace(); + + /** + * @brief Slot: Replaces current match and closes replace dialog. + * @details Performs replacement at current cursor position, then closes + * the find/replace dialog. + */ void replaceAndClose(); + + /** + * @brief Slot: Replaces all occurrences without prompting. + * @details Iterates through document replacing all matches of search + * pattern with replacement text. Used in batch replace mode. + */ void replaceAll(); + // Tab and file system handlers + /** + * @brief Slot: Applies font settings when tab changes. + * @param Unused tab index parameter (uses currentEditor() instead). + * @details When user switches tabs, updates font combo boxes to reflect + * the font settings of the newly active editor. + */ void applyFontSettings(int); + + /** + * @brief Slot: Handles file system watcher notifications. + * @param fileName Path to the file that changed on disk. + * @details Called when an open file is modified externally. Prompts user + * to reload the file to see changes or keep current version. + */ void fileChanged(const QString &fileName); + + /** + * @brief Slot: Re-enables file system watcher after delay. + * @details Connected to timer that fires after save operations complete, + * re-enabling change detection for open files. + * @see fileSystemWatcherActivation() for activation management + */ void setFileSystemWatcherActive(); + // Navigation + /** + * @brief Slot: Jumps cursor to selected msr file block. + * @param idx Index of selected block in jump-to-block combo box. + * @details Moves cursor to the beginning of the selected block + * (FITPARAMETER, THEORY, RUN, COMMANDS, etc.) for quick navigation. + */ void jumpToBlock(int idx); private: @@ -200,12 +980,81 @@ private: QMenu *fRecentFilesMenu; ///< recent file menu QAction *fRecentFilesAction[MAX_RECENT_FILES]; ///< array of the recent file actions + /** + * @brief Detects the current system theme. + * + * @details Attempts to detect whether the system is using a light or dark + * theme by examining palette colors. Sets fDarkMenuIcon and fDarkToolBarIcon + * flags accordingly for appropriate icon selection. + * + * @return bool true if theme detection succeeded, false if detection failed + * (in which case defaults from preferences are used). + * + * @note Detection method may vary by platform and desktop environment. + */ bool getTheme(); + + /** + * @brief Populates the Recent Files menu. + * + * @details Reads recent file list from PAdmin configuration and creates + * menu actions for each recent file. Updates action visibility and text + * to show available recent files. + * + * @see fileOpenRecent() for opening selected recent files + */ void fillRecentFiles(); + + /** + * @brief Parses a run list string into individual run numbers. + * + * @details Converts comma-separated or space-separated run numbers into + * a QStringList. Handles various input formats and validates that all + * entries are valid run numbers. + * + * @param runListStr String containing run numbers (e.g., "1234, 1235, 1236"). + * @param ok Output parameter set to true if parsing succeeded, false otherwise. + * + * @return QStringList List of individual run number strings. Empty if + * parsing failed. + */ QStringList getRunList(QString runListStr, bool &ok); + + /** + * @brief Checks if a file is already open in a tab. + * + * @details Searches through all open tabs to determine if the given file + * is already loaded. If found, returns the tab index. + * + * @param finfo QFileInfo object for the file to check. + * @param idx Output parameter set to tab index if file is open, -1 otherwise. + * + * @return bool true if file is already open, false otherwise. + * + * @see load() for file loading mechanism + */ bool fileAlreadyOpen(QFileInfo &finfo, int &idx); + /** + * @brief Switches menu icons between dark and plain variants. + * + * @details Updates all menu action icons to use either dark-themed or + * plain icons based on fDarkMenuIcon flag. Called when theme changes + * or preferences are updated. + * + * @see getTheme() for theme detection + */ void switchMenuIcons(); + + /** + * @brief Switches toolbar icons between dark and plain variants. + * + * @details Updates all toolbar action icons to use either dark-themed or + * plain icons based on fDarkToolBarIcon flag. Called when theme changes + * or preferences are updated. + * + * @see getTheme() for theme detection + */ void switchToolbarIcons(); };