diff --git a/src/musredit_qt6/musredit/PGetMusrFTOptionsDialog.cpp b/src/musredit_qt6/musredit/PGetMusrFTOptionsDialog.cpp index 9e6919d91..29a0f2e96 100644 --- a/src/musredit_qt6/musredit/PGetMusrFTOptionsDialog.cpp +++ b/src/musredit_qt6/musredit/PGetMusrFTOptionsDialog.cpp @@ -27,6 +27,20 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PGetMusrFTOptionsDialog.cpp + * @brief Implementation of the PGetMusrFTOptionsDialog class. + * @details This file implements the dialog for configuring musrFT command-line + * options. It handles file selection, option parsing from previous commands, + * signal/slot connections for UI interactions, and generation of the complete + * command-line argument list. + * + * @author Andreas Suter + * @date 2009-2025 + * @copyright Copyright (C) 2009-2025 by Andreas Suter + * @license GNU General Public License v2 or later + */ + #include #include #include @@ -37,31 +51,63 @@ #include "PGetMusrFTOptionsDialog.h" -#define MUSRFT_OPT_UNDEF 0 -#define MUSRFT_OPT_REAL 1 -#define MUSRFT_OPT_IMAG 2 -#define MUSRFT_OPT_REAL_AND_IMAG 3 -#define MUSRFT_OPT_POWER 4 -#define MUSRFT_OPT_PHASE 5 +/** + * @name Fourier Option Indices + * @brief Combo box indices for Fourier plot type options. + * @{ + */ +#define MUSRFT_OPT_UNDEF 0 ///< Undefined/default option +#define MUSRFT_OPT_REAL 1 ///< Real part of Fourier transform +#define MUSRFT_OPT_IMAG 2 ///< Imaginary part of Fourier transform +#define MUSRFT_OPT_REAL_AND_IMAG 3 ///< Both real and imaginary parts +#define MUSRFT_OPT_POWER 4 ///< Power spectrum +#define MUSRFT_OPT_PHASE 5 ///< Phase spectrum +/** @} */ -#define MUSRFT_APOD_UNDEF 0 -#define MUSRFT_APOD_WEAK 1 -#define MUSRFT_APOD_MEDIUM 2 -#define MUSRFT_APOD_STRONG 3 +/** + * @name Apodization Indices + * @brief Combo box indices for apodization window function options. + * @{ + */ +#define MUSRFT_APOD_UNDEF 0 ///< Undefined/no apodization +#define MUSRFT_APOD_WEAK 1 ///< Weak apodization +#define MUSRFT_APOD_MEDIUM 2 ///< Medium apodization +#define MUSRFT_APOD_STRONG 3 ///< Strong apodization +/** @} */ -#define MUSRFT_UNIT_UNDEF 0 -#define MUSRFT_UNIT_GAUSS 1 -#define MUSRFT_UNIT_TESLA 2 -#define MUSRFT_UNIT_FREQ 3 -#define MUSRFT_UNIT_CYCLE 4 +/** + * @name Unit Indices + * @brief Combo box indices for frequency unit options. + * @{ + */ +#define MUSRFT_UNIT_UNDEF 0 ///< Undefined/default units +#define MUSRFT_UNIT_GAUSS 1 ///< Gauss (magnetic field units) +#define MUSRFT_UNIT_TESLA 2 ///< Tesla (magnetic field units) +#define MUSRFT_UNIT_FREQ 3 ///< MHz (frequency units) +#define MUSRFT_UNIT_CYCLE 4 ///< Mc/s (megacycles per second) +/** @} */ //---------------------------------------------------------------------------------------------------- /** - *

Constructor. + * @brief Constructs the musrFT options dialog. * - * \param currentMsrFile path-file name of the currently active msr-file in musredit - * \param prevCmd list of the last (potential) previously call. - * \param helpUrl help url for the asymmetry run block + * @details Initializes the dialog UI, sets up input validators for numeric fields, + * parses any previous command to restore settings, and connects all signal/slot + * pairs for UI interaction. The dialog is created as modal. + * + * @par Input Validators: + * - Integer validators: background range bins, packing, Fourier power + * - Double validators: time range, lifetime correction, Fourier range + * + * @par Previous Command Parsing: + * If prevCmd contains a previous musrFT command, the dialog will parse it and + * restore all settings. Recognized options include: -fo, -ap, -fp, -u, -fr, -tr, + * -br, -pa, -a, -ad, -lc, -df, --histo, --t0, --title, --create-msr-file. + * + * @param currentMsrFile Full path-name of the currently active msr-file in musredit. + * @param prevCmd QStringList containing the previous musrFT command arguments + * (can be empty for fresh start). + * @param helpUrl URL to the online documentation for musrFT. */ PGetMusrFTOptionsDialog::PGetMusrFTOptionsDialog(QString currentMsrFile, QStringList &prevCmd, const QString helpUrl) : fCurrentMsrFileName(currentMsrFile), fHelpUrl(helpUrl) @@ -250,7 +296,34 @@ PGetMusrFTOptionsDialog::PGetMusrFTOptionsDialog(QString currentMsrFile, QString //---------------------------------------------------------------------------------------------------- /** - *

returns the musrFT command line options. + * @brief Builds and returns the complete musrFT command-line options. + * + * @details Collects all user-configured options from the dialog widgets and + * assembles them into a QStringList suitable for passing to musrFT. The method + * handles the logic for mutually exclusive options (e.g., current file vs. + * file list) and only includes options that have been explicitly set. + * + * @par Generated Options: + * The returned list may include any combination of: + * - msr-file names (or current msr-file if that option is selected) + * - -df followed by data file names + * - -br start end (background range) + * - -fo option (Fourier option: real, imag, power, phase) + * - -ap option (apodization: weak, medium, strong) + * - -fp value (Fourier power) + * - -u units (Gauss, Tesla, MHz, Mc/s) + * - -fr start end (Fourier range) + * - -tr start end (time range) + * - --histo list (histogram numbers) + * - -a (average all) + * - -ad (average per data set) + * - --t0 list (t0 values) + * - -pa value (packing) + * - --title text + * - --create-msr-file filename + * - -lc value (lifetime correction) + * + * @return QStringList containing the complete command-line arguments for musrFT. */ QStringList PGetMusrFTOptionsDialog::getMusrFTOptions() { @@ -381,8 +454,14 @@ QStringList PGetMusrFTOptionsDialog::getMusrFTOptions() //---------------------------------------------------------------------------------------------------- /** - *

SLOT called when fCurrentMsrFile_checkBox is checked/unchecked. If checked, it will clean up - * the msr-file path-file list and the data-file path-file list. + * @brief Slot called when the "current msr-file" checkbox state changes. + * + * @details When checked, this option uses the currently active msr-file in + * musredit instead of a manually selected file list. Checking this option + * will uncheck the "all msr-files" option and clear any previously selected + * msr-files and data files. + * + * @param state The new checkbox state (Qt::Checked or Qt::Unchecked). */ void PGetMusrFTOptionsDialog::currentMsrFileTagChanged(int state) { @@ -401,7 +480,12 @@ void PGetMusrFTOptionsDialog::currentMsrFileTagChanged(int state) //---------------------------------------------------------------------------------------------------- /** - *

SLOT called when fAllMsrFiles_checkBox is checked/unchecked. Currently it has no functionality. + * @brief Slot called when the "all msr-files" checkbox state changes. + * + * @details When checked, unchecks the "current msr-file" option to maintain + * mutual exclusivity between these two file selection modes. + * + * @param state The new checkbox state (Qt::Checked or Qt::Unchecked). */ void PGetMusrFTOptionsDialog::allMsrFileTagChanged(int state) { @@ -412,7 +496,12 @@ void PGetMusrFTOptionsDialog::allMsrFileTagChanged(int state) //---------------------------------------------------------------------------------------------------- /** - *

SLOT called when fMsrFileSelector_pushButton is clicked. Collects the msr-file path-name list. + * @brief Slot to open file dialog for selecting msr-files. + * + * @details Opens a multi-file selection dialog filtered for .msr files. Selected + * files are split into path and name components and stored separately in + * fMsrFilePaths and fMsrFileNames. The file names are displayed in the + * corresponding line edit widget. */ void PGetMusrFTOptionsDialog::selectMsrFileNames() { @@ -450,7 +539,10 @@ void PGetMusrFTOptionsDialog::selectMsrFileNames() //---------------------------------------------------------------------------------------------------- /** - *

SLOT called when the fMsrFileNameClear_pushButton is clicked. + * @brief Slot to clear the msr-file selection. + * + * @details Clears the msr-file selector line edit and empties both the + * fMsrFilePaths and fMsrFileNames lists. */ void PGetMusrFTOptionsDialog::clearMsrFileNames() { @@ -461,7 +553,12 @@ void PGetMusrFTOptionsDialog::clearMsrFileNames() //---------------------------------------------------------------------------------------------------- /** - *

SLOT called when fDataFileSelector_pushButton is clicked. Collects the data-file path-name list. + * @brief Slot to open file dialog for selecting data files. + * + * @details Opens a multi-file selection dialog filtered for data files + * (.root, .bin, .msr, .nxs, .mdu). Selected files are split into path and + * name components and stored separately in fDataFilePaths and fDataFileNames. + * The file names are displayed in the corresponding line edit widget. */ void PGetMusrFTOptionsDialog::selectDataFileNames() { @@ -499,7 +596,10 @@ void PGetMusrFTOptionsDialog::selectDataFileNames() //---------------------------------------------------------------------------------------------------- /** - *

SLOT called when the fDataFileNameClear_pushButton is clicked. + * @brief Slot to clear the data file selection. + * + * @details Clears the data file selector line edit and empties both the + * fDataFilePaths and fDataFileNames lists. */ void PGetMusrFTOptionsDialog::clearDataFileNames() { @@ -510,7 +610,13 @@ void PGetMusrFTOptionsDialog::clearDataFileNames() //---------------------------------------------------------------------------------------------------- /** - *

SLOT called when the create-msr-file tag has changed + * @brief Slot called when the "create msr-file" checkbox state changes. + * + * @details When checked, opens a file save dialog to specify the output + * msr-file name. If the user cancels the dialog, the checkbox is automatically + * unchecked. When unchecked, clears the stored create msr-file name. + * + * @param state The new checkbox state (Qt::Checked or Qt::Unchecked). */ void PGetMusrFTOptionsDialog::createMsrFileChanged(int state) { @@ -525,7 +631,11 @@ void PGetMusrFTOptionsDialog::createMsrFileChanged(int state) //---------------------------------------------------------------------------------------------------- /** - *

SLOT called when the Reset All button is pressed. Will remove all settings. + * @brief Slot to reset all dialog options to default values. + * + * @details Clears all input fields, unchecks all checkboxes, and resets all + * combo boxes to their undefined/default state. This provides a clean slate + * for configuring new musrFT options. */ void PGetMusrFTOptionsDialog::resetAll() { @@ -560,7 +670,13 @@ void PGetMusrFTOptionsDialog::resetAll() //---------------------------------------------------------------------------------------------------- /** - *

SLOT called when averaged view for ALL data is checked. + * @brief Slot called when the "average all" checkbox state changes. + * + * @details Ensures mutual exclusivity with the "average per data set" option. + * When this option is checked, the per-data-set averaging is automatically + * unchecked since both options cannot be active simultaneously. + * + * @param state The new checkbox state (Qt::Checked or Qt::Unchecked). */ void PGetMusrFTOptionsDialog::averagedAll(int state) { @@ -570,7 +686,13 @@ void PGetMusrFTOptionsDialog::averagedAll(int state) //---------------------------------------------------------------------------------------------------- /** - *

SLOT called when averaged view per data set is checked. + * @brief Slot called when the "average per data set" checkbox state changes. + * + * @details Ensures mutual exclusivity with the "average all" option. + * When this option is checked, the all-data averaging is automatically + * unchecked since both options cannot be active simultaneously. + * + * @param state The new checkbox state (Qt::Checked or Qt::Unchecked). */ void PGetMusrFTOptionsDialog::averagedPerDataSet(int state) { @@ -580,7 +702,11 @@ void PGetMusrFTOptionsDialog::averagedPerDataSet(int state) //---------------------------------------------------------------------------------------------------- /** - *

Generates a help content window showing the description for musrFT. + * @brief Opens the online help documentation for musrFT. + * + * @details Attempts to open the help URL in the system's default web browser + * using QDesktopServices. If the URL is empty, displays an informational message. + * If the browser fails to open, displays an error message with a clickable link. */ void PGetMusrFTOptionsDialog::helpContent() { diff --git a/src/musredit_qt6/musredit/PGetMusrFTOptionsDialog.h b/src/musredit_qt6/musredit/PGetMusrFTOptionsDialog.h index b90cf9259..e737e6817 100644 --- a/src/musredit_qt6/musredit/PGetMusrFTOptionsDialog.h +++ b/src/musredit_qt6/musredit/PGetMusrFTOptionsDialog.h @@ -27,6 +27,22 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PGetMusrFTOptionsDialog.h + * @brief Dialog for configuring musrFT command-line options. + * @details This header defines the PGetMusrFTOptionsDialog class which provides + * a comprehensive dialog for configuring all command-line options for the musrFT + * Fourier transform tool. The dialog supports file selection, Fourier transform + * parameters, and various display options. + * + * @author Andreas Suter + * @date 2010-2025 + * @copyright Copyright (C) 2010-2025 by Andreas Suter + * @license GNU General Public License v2 or later + * + * @see PGetFourierBlockDialog For FOURIER block creation in msr files + */ + #ifndef _PGETMUSRFTOPTIONSDIALOG_H_ #define _PGETMUSRFTOPTIONSDIALOG_H_ @@ -35,37 +51,115 @@ #include "ui_PGetMusrFTOptionsDialog.h" +//--------------------------------------------------------------------------- +/** + * @class PGetMusrFTOptionsDialog + * @brief Dialog for configuring musrFT Fourier transform tool options. + * + * @details This dialog provides a comprehensive interface for configuring all + * command-line options for the musrFT tool, which performs Fourier transforms + * on muon spin rotation data. The dialog remembers previous settings and can + * restore them on subsequent invocations. + * + * @par Supported Options: + * - **File Selection**: Current msr-file, multiple msr-files, or data files + * - **Fourier Options**: Plot type (real, imag, power, phase), apodization, units + * - **Range Settings**: Time range, Fourier range, background range + * - **Data Processing**: Packing, histogram selection, t0 values, lifetime correction + * - **Output Options**: Averaged views, msr-file creation, custom title + * + * @par Command-Line Options Generated: + * | Option | Description | + * |--------|-------------| + * | -fo | Fourier option (real, imag, power, phase) | + * | -ap | Apodization (weak, medium, strong) | + * | -u | Units (Gauss, Tesla, MHz, Mc/s) | + * | -fp | Fourier power (zero-padding) | + * | -fr | Fourier range | + * | -tr | Time range | + * | -br | Background range (bins) | + * | -pa | Packing factor | + * | -a | Average all data | + * | -ad | Average per data set | + * | -lc | Lifetime correction | + * | --histo | Histogram list | + * | --t0 | T0 values | + * | --title | Plot title | + * | --create-msr-file | Create msr-file from Fourier | + * + * @par Usage: + * @code + * QStringList prevCmd; // previous command (empty or from last call) + * PGetMusrFTOptionsDialog dialog(currentMsrFile, prevCmd, helpUrl); + * if (dialog.exec() == QDialog::Accepted) { + * QStringList options = dialog.getMusrFTOptions(); + * // Execute musrFT with options... + * } + * @endcode + * + * @see PGetFourierBlockDialog For static FOURIER blocks in msr files + */ class PGetMusrFTOptionsDialog : public QDialog, private Ui::PGetMusrFTOptionsDialog { Q_OBJECT public: PGetMusrFTOptionsDialog(QString currentMsrFile, QStringList &prevCmd, const QString helpUrl); + + /** + * @brief Builds and returns the musrFT command-line options. + * @return QStringList containing all configured command-line arguments + * ready to be passed to musrFT. + */ QStringList getMusrFTOptions(); public slots: + /** + * @brief Opens the online help for musrFT. + */ void helpContent(); private slots: - void currentMsrFileTagChanged(int state); - void allMsrFileTagChanged(int state); - void selectMsrFileNames(); - void clearMsrFileNames(); - void selectDataFileNames(); - void clearDataFileNames(); - void createMsrFileChanged(int state); + /** @name File Selection Slots + * @brief Slots for handling file selection changes. + * @{ + */ + void currentMsrFileTagChanged(int state); ///< Handles current msr-file checkbox state change. + void allMsrFileTagChanged(int state); ///< Handles all msr-files checkbox state change. + void selectMsrFileNames(); ///< Opens file dialog to select msr-files. + void clearMsrFileNames(); ///< Clears the msr-file selection. + void selectDataFileNames(); ///< Opens file dialog to select data files. + void clearDataFileNames(); ///< Clears the data file selection. + void createMsrFileChanged(int state); ///< Handles create msr-file checkbox state change. + /** @} */ + + /** @name View Option Slots + * @brief Slots for handling averaging options. + * @{ + */ + void averagedAll(int state); ///< Handles average-all checkbox (mutually exclusive with per-dataset). + void averagedPerDataSet(int state); ///< Handles average-per-dataset checkbox (mutually exclusive with all). + /** @} */ + + /** + * @brief Resets all dialog options to their default values. + */ void resetAll(); - void averagedAll(int state); - void averagedPerDataSet(int state); private: - QStringList fMsrFilePaths; ///< list keeping all the paths from the msr-file path-name list - QStringList fMsrFileNames; ///< list keeping all the names from the msr-file path-name list - QStringList fDataFilePaths; ///< list keeping all the paths from the data-file path-name list - QStringList fDataFileNames; ///< list keeping all the names from the data-file path-name list - QString fCreateMsrFileName; ///< keeps the msr-path-file name for msr-file creation - QString fCurrentMsrFileName; ///< keeps the msr-path-file name of the currently active msr-file in musredit. - QString fHelpUrl; ///< help url for the asymmetry run block + /** @name File Path Storage + * @brief Lists for storing selected file paths and names. + * @{ + */ + QStringList fMsrFilePaths; ///< Directory paths for selected msr-files. + QStringList fMsrFileNames; ///< File names (without path) for selected msr-files. + QStringList fDataFilePaths; ///< Directory paths for selected data files. + QStringList fDataFileNames; ///< File names (without path) for selected data files. + /** @} */ + + QString fCreateMsrFileName; ///< Full path-name for msr-file creation output. + QString fCurrentMsrFileName; ///< Full path-name of the currently active msr-file in musredit. + QString fHelpUrl; ///< URL to the online documentation for musrFT. }; #endif // _PGETMUSRFTOPTIONSDIALOG_H_