LMU/musrfit
5
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases 4 Activity

improve the doxygen docu of PPrefsDialog.* (musredit_qt6).

Browse Source
This commit is contained in:
suter_a
2025-11-25 08:36:54 +01:00
parent 02ddc3889d
commit 87fcf91593
2 changed files with 457 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

213
src/musredit_qt6/musredit/PPrefsDialog.cpp
View File

@@ -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 <memory>
#include "PChangeDefaultPathsDialog.h"
@@ -34,9 +51,66 @@
//----------------------------------------------------------------------------------------------------
/**
* <p>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)
//----------------------------------------------------------------------------------------------------
/**
* <p>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()
//----------------------------------------------------------------------------------------------------
/**
* <p>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()
//----------------------------------------------------------------------------------------------------
/**
* <p>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()
//----------------------------------------------------------------------------------------------------
/**
*<p>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()
{

255
src/musredit_qt6/musredit/PPrefsDialog.h
View File

@@ -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"
/**
* <p>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_