diff --git a/src/musredit_qt6/musredit/PPrefsDialog.cpp b/src/musredit_qt6/musredit/PPrefsDialog.cpp index 523d11815..fc2087715 100644 --- a/src/musredit_qt6/musredit/PPrefsDialog.cpp +++ b/src/musredit_qt6/musredit/PPrefsDialog.cpp @@ -27,6 +27,23 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PPrefsDialog.cpp + * @brief Implementation of the musredit preferences dialog. + * + * @details Provides the implementation of PPrefsDialog class methods for + * managing musredit and musrfit application preferences. The dialog handles + * initialization of UI controls from saved preferences, enforces option + * interdependencies, and provides methods for retrieving user-configured + * settings. + * + * Preferences cover fitting behavior, output formats, visualization options, + * theme settings, and system paths. + * + * @author Andreas Suter + * @date 2009-2025 + */ + #include #include "PChangeDefaultPathsDialog.h" @@ -34,9 +51,66 @@ //---------------------------------------------------------------------------------------------------- /** - *

Constructor. + * @brief Constructor - Initializes the preferences dialog. * - * \param fAdmin keeps all the needed flags + * @details Sets up the preferences dialog user interface and populates all + * controls with current preference values from the PAdmin administration + * object. The initialization process includes: + * + * 1. **Safety Check**: Validates that admin pointer is not nullptr + * 2. **UI Setup**: Loads dialog layout from Qt Designer UI file + * 3. **Modal Configuration**: Sets dialog as modal to ensure completion + * 4. **Preference Loading**: Populates all UI controls with saved values + * 5. **Validators**: Installs integer validator on timeout field + * 6. **Signal Connections**: Establishes slot connections for UI interactions + * + * **Preference Categories and Initialization:** + * + * **Theme Preferences:** + * - Dark theme icons for menus (checked/unchecked state) + * - Dark theme icons for toolbars (checked/unchecked state) + * - Theme auto-detection override (checked/unchecked state) + * + * **Fitting Options:** + * - Keep MINUIT2 output files (boolean checkbox) + * - Dump format selection (ASCII/ROOT, mutually exclusive) + * - Per-run block chi-square calculation (boolean checkbox) + * - Estimate N0 from data (boolean checkbox) + * - Fitting timeout in seconds (integer with validation) + * + * **Output Options:** + * - Title extraction from data files (boolean checkbox) + * - YAML format output generation (boolean checkbox) + * + * **Data Processing:** + * - Enable musrT0 tool for t0 determination (boolean checkbox) + * + * **Visualization (musrview):** + * - Show Fourier transform plots by default (boolean checkbox) + * - Show averaged data plots (boolean checkbox) + * - Enable one-to-one plotting mode (boolean checkbox) + * + * **Dump Format Logic:** + * The dump format checkboxes are handled with special logic to ensure + * mutual exclusivity: + * - If ASCII is set and ROOT is not: check ASCII only + * - If ROOT is set and ASCII is not: check ROOT only + * - Otherwise (both or neither set): uncheck both + * + * @param admin Pointer to the global PAdmin administration object containing + * all current preference values. If nullptr, the constructor + * returns early without initializing the dialog (defensive + * programming). + * + * @note The timeout field accepts only integer input via QIntValidator. + * @note The "Change Default Paths" button is connected to handleDefaultPaths() + * slot for managing data file search paths. + * @note All checkboxes are initialized from PAdmin getter methods to ensure + * consistency with saved preferences. + * + * @see PAdmin Global preferences storage and management + * @see setupUi() Qt Designer generated UI initialization + * @see handleDefaultPaths() Slot for managing data file search paths */ PPrefsDialog::PPrefsDialog(PAdmin *admin) : fAdmin(admin) { @@ -95,7 +169,37 @@ PPrefsDialog::PPrefsDialog(PAdmin *admin) : fAdmin(admin) //---------------------------------------------------------------------------------------------------- /** - *

returns the dump flag (see the '--dump' option of musrfit). 0 == no dump, 1 == ascii dump, 2 == root dump + * @brief Returns the selected dump format preference. + * + * @details Determines which data dump format is currently selected in the + * preferences dialog. This corresponds to musrfit's --dump command-line option, + * which controls how fitted data is exported for external analysis. + * + * **Return Values:** + * - **0**: No dumping - Fitted data is not exported to files + * - **1**: ASCII dump - Data is written to human-readable text files with + * columnar format suitable for plotting tools like gnuplot or Excel + * - **2**: ROOT dump - Data is written to ROOT framework files (.root) with + * structured histograms and trees for analysis with ROOT tools + * + * **Use Cases:** + * - ASCII dump: Simple plotting, spreadsheet analysis, custom scripts + * - ROOT dump: Advanced analysis with ROOT framework, complex histogramming + * + * The dump formats are mutually exclusive - only one can be active at a time. + * This exclusivity is enforced by the dumpAscii() and dumpRoot() slot methods. + * + * @return int Dump format code: + * - 0 = no dump + * - 1 = ASCII format dump + * - 2 = ROOT format dump + * + * @note The ASCII format typically produces .dat files with tab-separated columns. + * @note The ROOT format creates .root files with TTree and TH1 objects. + * @note Dump files are created in the same directory as the msr file. + * + * @see dumpAscii() Slot that enforces mutual exclusivity with ROOT dump + * @see dumpRoot() Slot that enforces mutual exclusivity with ASCII dump */ int PPrefsDialog::getDump() { @@ -111,8 +215,31 @@ int PPrefsDialog::getDump() //---------------------------------------------------------------------------------------------------- /** - *

SLOT: called when the QCheckBox 'dump ascii' is selected. Will uncheck 'dump root' since these - * two options are mutually exclusive. + * @brief Slot: Handles ASCII dump checkbox selection. + * + * @details Called when the "Dump ASCII" checkbox state changes. Enforces + * mutual exclusivity between ASCII and ROOT dump formats by automatically + * unchecking the ROOT dump checkbox when ASCII dump is selected. + * + * **ASCII Dump Format Details:** + * - Produces human-readable text files with columnar data + * - Typical format: tab-separated or space-separated values + * - Output includes time bins, data values, theory values, errors + * - Suitable for plotting with gnuplot, Excel, Origin, or custom scripts + * - Files typically have .dat or .txt extensions + * + * **Mutual Exclusivity Rationale:** + * Only one dump format can be active because musrfit's --dump option accepts + * a single format specification. Allowing both would create ambiguity about + * which format to use. + * + * @note This slot is typically connected to the clicked() or toggled() signal + * of the ASCII dump checkbox. + * @note If the user wants both formats, they must run musrfit twice with + * different dump settings. + * + * @see dumpRoot() Complementary slot for ROOT dump format + * @see getDump() Returns the selected dump format code */ void PPrefsDialog::dumpAscii() { @@ -122,8 +249,39 @@ void PPrefsDialog::dumpAscii() //---------------------------------------------------------------------------------------------------- /** - *

SLOT: called when the QCheckBox 'dump root' is selected. Will uncheck 'dump ascii' since these - * two options are mutually exclusive. + * @brief Slot: Handles ROOT dump checkbox selection. + * + * @details Called when the "Dump ROOT" checkbox state changes. Enforces + * mutual exclusivity between ROOT and ASCII dump formats by automatically + * unchecking the ASCII dump checkbox when ROOT dump is selected. + * + * **ROOT Dump Format Details:** + * - Produces ROOT framework files (.root extension) + * - Contains structured data objects (TTree, TH1F, TGraph, etc.) + * - Enables advanced analysis with ROOT toolkit + * - Preserves full precision and metadata + * - Suitable for complex statistical analysis, histogramming, fitting + * - Can be opened with ROOT TBrowser or custom ROOT macros + * + * **ROOT Dump Advantages:** + * - Maintains full numerical precision + * - Supports complex data structures + * - Integration with ROOT's analysis framework + * - Efficient storage for large datasets + * + * **Mutual Exclusivity Rationale:** + * Only one dump format can be active because musrfit's --dump option accepts + * a single format specification. Allowing both would create ambiguity about + * which format to use. + * + * @note This slot is typically connected to the clicked() or toggled() signal + * of the ROOT dump checkbox. + * @note ROOT must be installed and properly configured to read ROOT dump files. + * @note If the user wants both formats, they must run musrfit twice with + * different dump settings. + * + * @see dumpAscii() Complementary slot for ASCII dump format + * @see getDump() Returns the selected dump format code */ void PPrefsDialog::dumpRoot() { @@ -133,8 +291,45 @@ void PPrefsDialog::dumpRoot() //---------------------------------------------------------------------------------------------------- /** - *

SLOT: called when the QPushButton 'Change Default Search Paths' is clicked. Will call a - * dialog which allows to deal with the default search paths to look for data files. + * @brief Slot: Opens the default search paths configuration dialog. + * + * @details Called when the "Change Default Search Paths" button is clicked. + * Launches the PChangeDefaultPathsDialog which allows users to configure + * the list of directories where musrfit searches for data files when run + * numbers are specified without full paths. + * + * **Default Search Paths Purpose:** + * When an msr file specifies a run number (e.g., "RUN 2024 PSI" without a + * full path), musrfit searches through the default path list to locate the + * corresponding data file. This eliminates the need to specify full paths in + * every msr file. + * + * **Typical Search Path Examples:** + * - /data/musr/2024/ + * - ~/experiments/muon/raw/ + * - /mnt/analysis/data/ + * - //network/share/musr-data/ + * + * **Dialog Workflow:** + * 1. User clicks "Change Default Search Paths" button + * 2. PChangeDefaultPathsDialog opens showing current path list + * 3. User adds, removes, or reorders paths + * 4. If user accepts (OK), changes are saved to PAdmin + * 5. If user cancels, changes are discarded + * + * The dialog is created using std::unique_ptr for automatic memory management. + * When the dialog goes out of scope, it is automatically destroyed. + * + * @note Changes to default paths take effect immediately for subsequent + * file operations. + * @note The path list is typically stored in the user's configuration file + * and persists across application sessions. + * @note Order matters: paths are searched in the order they appear in the list. + * @note The dialog currently executes but performs no action on acceptance + * (empty if block) - paths are managed within the child dialog. + * + * @see PChangeDefaultPathsDialog For the search paths management interface + * @see PAdmin For the global storage of default search paths */ void PPrefsDialog::handleDefaultPaths() { diff --git a/src/musredit_qt6/musredit/PPrefsDialog.h b/src/musredit_qt6/musredit/PPrefsDialog.h index e1c5d83d9..bbd9ff48f 100644 --- a/src/musredit_qt6/musredit/PPrefsDialog.h +++ b/src/musredit_qt6/musredit/PPrefsDialog.h @@ -27,6 +27,24 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PPrefsDialog.h + * @brief Preferences dialog for musredit application settings. + * + * @details This header defines the PPrefsDialog class which provides a + * centralized interface for configuring musredit and musrfit application + * preferences. The dialog manages settings related to fitting behavior, + * output formats, visualization options, theme preferences, and system paths. + * + * @author Andreas Suter + * @date 2010-2025 + * @copyright Copyright (C) 2010-2025 by Andreas Suter + * @license GNU General Public License v2 or later + * + * @see PAdmin Global administration object storing all preferences + * @see musredit Main editor application + */ + #ifndef _PPREFSDIALOG_H_ #define _PPREFSDIALOG_H_ @@ -37,38 +55,271 @@ #include "ui_PPrefsDialog.h" /** - *

Class handling the content of the MusrFit/Preferences. + * @class PPrefsDialog + * @brief Preferences dialog for configuring musredit and musrfit settings. + * + * @details This dialog provides a centralized interface for managing all + * application preferences. Settings are organized into several categories: + * + * @par Fitting and Output Options: + * - **MINUIT2 output**: Keep detailed MINUIT2 fitting output files + * - **Dump format**: ASCII or ROOT format for dumping fitted data + * - **YAML output**: Generate YAML format files for fit results + * - **Per-run chi-square**: Include chi-square values for individual runs + * - **Estimate N0**: Automatically estimate initial asymmetry from data + * - **Timeout**: Maximum fitting time in seconds (prevents infinite loops) + * + * @par Data File Options: + * - **Title from data file**: Extract msr file title from data file headers + * - **Enable musrT0**: Use musrT0 tool for t0 determination + * - **Default paths**: Configure search paths for data files + * + * @par Visualization (musrview) Options: + * - **Show Fourier**: Display Fourier transform plots by default + * - **Show average**: Display averaged data plots + * - **One-to-one plotting**: Direct data-to-theory comparison mode + * + * @par Theme and Appearance: + * - **Dark theme icons (menu)**: Use dark-themed icons in menus + * - **Dark theme icons (toolbar)**: Use dark-themed icons in toolbar + * - **Ignore theme auto-detection**: Disable automatic theme detection + * + * @par Mutual Exclusivity: + * Some options are mutually exclusive: + * - ASCII dump and ROOT dump cannot both be enabled + * - These constraints are enforced through slot handlers + * + * All preferences are stored in the PAdmin global administration object + * and persisted across application sessions. + * + * @note The dialog is modal, requiring user interaction before continuing. + * @note Changes take effect after dialog acceptance (OK button). + * @note Some settings (like theme changes) may require application restart. + * + * @see PAdmin Global preferences storage + * @see PChangeDefaultPathsDialog For managing data file search paths */ class PPrefsDialog : public QDialog, private Ui::PPrefsDialog { Q_OBJECT public: + /** + * @brief Constructs the preferences dialog. + * + * @details Initializes the dialog with current preference values from the + * PAdmin administration object. Sets up UI controls, validators, and + * signal-slot connections for option interdependencies. + * + * @param admin Pointer to the global PAdmin object containing current + * preference values. Must not be nullptr. The dialog reads + * from and writes to this object. + * + * @see PAdmin For the global preferences storage object + */ PPrefsDialog(PAdmin *admin); + /** + * @brief Returns the musrview Fourier display preference. + * + * @details Indicates whether Fourier transform plots should be shown by + * default when opening data files in musrview. + * + * @return true if Fourier plots should be displayed by default. + */ bool getMusrviewShowFourierFlag() { return fFourier_checkBox->isChecked(); } + + /** + * @brief Returns the musrview average display preference. + * + * @details Indicates whether averaged data plots should be shown by + * default when opening data files in musrview. + * + * @return true if average plots should be displayed by default. + */ bool getMusrviewShowAvgFlag() { return fAvg_checkBox->isChecked(); } + + /** + * @brief Returns the musrview one-to-one plotting preference. + * + * @details Indicates whether one-to-one (direct data-to-theory comparison) + * plotting mode should be used by default in musrview. + * + * @return true if one-to-one plotting should be enabled by default. + */ bool getMusrviewShowOneToOneFlag() { return fOneToOne_checkBox->isChecked(); } + + /** + * @brief Returns the MINUIT2 output preservation preference. + * + * @details Indicates whether detailed MINUIT2 fitting output files should + * be kept after fits complete. Useful for debugging fit convergence issues. + * + * @return true if MINUIT2 output files should be preserved. + */ bool getKeepMinuit2OutputFlag() { return fKeepMn2Output_checkBox->isChecked(); } + + /** + * @brief Returns the title-from-data-file preference. + * + * @details Indicates whether msr file titles should be automatically + * extracted from data file headers when available. + * + * @return true if titles should be read from data files. + */ bool getTitleFromDataFileFlag() { return fTitleFromData_checkBox->isChecked(); } + + /** + * @brief Returns the musrT0 enablement preference. + * + * @details Indicates whether the musrT0 tool should be used for automatic + * t0 (time zero) determination from data files. + * + * @return true if musrT0 tool should be enabled. + */ bool getEnableMusrT0Flag() { return fEnableMusrT0_checkBox->isChecked(); } + + /** + * @brief Returns the per-run chi-square preference. + * + * @details Indicates whether chi-square values for individual runs (in + * multi-run fits) should be calculated and reported separately. + * + * @return true if per-run chi-square values should be calculated. + */ bool getKeepRunPerBlockChisqFlag() { return fPerRunBlockChisq_checkBox->isChecked(); } + + /** + * @brief Returns the N0 estimation preference. + * + * @details Indicates whether initial asymmetry (N0) should be automatically + * estimated from data rather than using msr file values. + * + * @return true if N0 should be estimated from data. + */ bool getEstimateN0Flag() { return fEstimateN0_checkBox->isChecked(); } + + /** + * @brief Returns the YAML output preference. + * + * @details Indicates whether fit results should be exported in YAML format + * in addition to standard output formats. + * + * @return true if YAML output files should be generated. + */ bool getYamlOutFlag() { return fYamlOut_checkBox->isChecked(); } + + /** + * @brief Returns the theme auto-detection override preference. + * + * @details Indicates whether automatic system theme detection should be + * ignored, allowing manual theme configuration. + * + * @return true if automatic theme detection should be disabled. + */ bool getIgnoreThemeAutoDetection() { return fIgnoreThemeAutoDetection_checkBox->isChecked(); } + + /** + * @brief Returns the dark theme menu icons preference. + * + * @details Indicates whether dark-themed icon variants should be used + * in application menus for better visibility on dark backgrounds. + * + * @return true if dark theme menu icons should be used. + */ bool getDarkThemeIconsMenuFlag() { return fDarkThemeIconsMenu_checkBox->isChecked(); } + + /** + * @brief Returns the dark theme toolbar icons preference. + * + * @details Indicates whether dark-themed icon variants should be used + * in the application toolbar for better visibility on dark backgrounds. + * + * @return true if dark theme toolbar icons should be used. + */ bool getDarkThemeIconsToolbarFlag() { return fDarkThemeIconsToolbar_checkBox->isChecked(); } + + /** + * @brief Returns the one-to-one plotting preference. + * + * @details Alias for getMusrviewShowOneToOneFlag(). Indicates whether + * one-to-one plotting mode should be enabled. + * + * @return true if one-to-one plotting should be enabled. + * + * @see getMusrviewShowOneToOneFlag() Primary method for this preference + */ bool getOneToOneFlag() { return fOneToOne_checkBox->isChecked(); } + + /** + * @brief Returns the dump format preference. + * + * @details Determines the format for dumping fitted data using musrfit's + * --dump option. The values are: + * - 0: No dumping + * - 1: ASCII format dump + * - 2: ROOT format dump + * + * @return int Dump format code (0=none, 1=ASCII, 2=ROOT). + * + * @note ASCII and ROOT dump formats are mutually exclusive. + * + * @see dumpAscii() Enforces mutual exclusivity + * @see dumpRoot() Enforces mutual exclusivity + */ int getDump(); + + /** + * @brief Returns the fitting timeout preference. + * + * @details Returns the maximum time (in seconds) that a fit should be + * allowed to run before being terminated. This prevents infinite loops + * or extremely slow fits from hanging the application. + * + * @return int Timeout in seconds. Default is typically 3600 (1 hour). + * + * @note A value of 0 typically means no timeout (unlimited time). + */ int getTimeout() { return fTimeout_lineEdit->text().toInt(); } public slots: + /** + * @brief Slot: Handles ASCII dump checkbox selection. + * + * @details Called when the "Dump ASCII" checkbox is toggled. If checked, + * automatically unchecks "Dump ROOT" since these formats are mutually + * exclusive. + * + * @see dumpRoot() Complementary slot for ROOT dump + * @see getDump() Returns the selected dump format + */ void dumpAscii(); + + /** + * @brief Slot: Handles ROOT dump checkbox selection. + * + * @details Called when the "Dump ROOT" checkbox is toggled. If checked, + * automatically unchecks "Dump ASCII" since these formats are mutually + * exclusive. + * + * @see dumpAscii() Complementary slot for ASCII dump + * @see getDump() Returns the selected dump format + */ void dumpRoot(); + + /** + * @brief Slot: Opens the default paths configuration dialog. + * + * @details Called when the "Change Default Search Paths" button is clicked. + * Launches the PChangeDefaultPathsDialog to allow users to configure the + * directories where musrfit searches for data files. + * + * @see PChangeDefaultPathsDialog For the paths management dialog + */ void handleDefaultPaths(); private: - PAdmin *fAdmin; + PAdmin *fAdmin; ///< Pointer to global administration object storing all preferences. }; #endif // _PPREFSDIALOG_H_