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

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

Browse Source
This commit is contained in:
suter_a
2025-11-24 13:30:27 +01:00
parent 456bc2adb4
commit 8b631e026c
2 changed files with 268 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

190
src/musredit_qt6/musredit/PGetMusrFTOptionsDialog.cpp
View File

@@ -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 <QLineEdit>
#include <QValidator>
#include <QComboBox>
@@ -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)
/** @} */
//----------------------------------------------------------------------------------------------------
/**
* <p>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
//----------------------------------------------------------------------------------------------------
/**
* <p>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()
//----------------------------------------------------------------------------------------------------
/**
* <p>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)
//----------------------------------------------------------------------------------------------------
/**
* <p>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)
//----------------------------------------------------------------------------------------------------
/**
* <p>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()
//----------------------------------------------------------------------------------------------------
/**
* <p>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()
//----------------------------------------------------------------------------------------------------
/**
* <p>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()
//----------------------------------------------------------------------------------------------------
/**
* <p>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()
//----------------------------------------------------------------------------------------------------
/**
* <p>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)
//----------------------------------------------------------------------------------------------------
/**
* <p>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()
//----------------------------------------------------------------------------------------------------
/**
* <p>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)
//----------------------------------------------------------------------------------------------------
/**
* <p>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)
//----------------------------------------------------------------------------------------------------
/**
* <p>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()
{

126
src/musredit_qt6/musredit/PGetMusrFTOptionsDialog.h
View File

@@ -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_