diff --git a/src/musredit_qt6/musredit/PGetNonMusrRunBlockDialog.cpp b/src/musredit_qt6/musredit/PGetNonMusrRunBlockDialog.cpp index a72db83ec..0eeaa2e59 100644 --- a/src/musredit_qt6/musredit/PGetNonMusrRunBlockDialog.cpp +++ b/src/musredit_qt6/musredit/PGetNonMusrRunBlockDialog.cpp @@ -27,6 +27,19 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PGetNonMusrRunBlockDialog.cpp + * @brief Implementation of the PGetNonMusrRunBlockDialog class. + * @details This file implements the dialog for creating non-muSR type RUN blocks + * in msr files. It handles user input validation and generates properly formatted + * msr-file text for fitting generic x-y data. + * + * @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 @@ -38,9 +51,18 @@ //---------------------------------------------------------------------------------------------------- /** - *

Constructor + * @brief Constructs the non-muSR RUN block dialog. * - * \param helpUrl help url for the NonMusr run block. + * @details Initializes the dialog UI and sets up input validators for numeric + * fields. The dialog is created as modal. The file format combo box is + * automatically set to "DB" (database format) as the default, which is the + * most common format for non-muSR data. + * + * @par Input Validators: + * - Double validators: fit range start and end values + * + * @param helpUrl URL to the online documentation for non-muSR RUN blocks. + * Defaults to empty string if not provided. */ PGetNonMusrRunBlockDialog::PGetNonMusrRunBlockDialog(const QString helpUrl) : fHelpUrl(helpUrl) { @@ -65,7 +87,14 @@ PGetNonMusrRunBlockDialog::PGetNonMusrRunBlockDialog(const QString helpUrl) : fH //---------------------------------------------------------------------------------------------------- /** - *

Extracts the run header information from the dialog, and returns it as a string. + * @brief Generates the RUN header line for the non-muSR block. + * + * @details Creates the first line of the RUN block containing the run file name, + * beamline identifier, institute name, and data file format. The beamline is + * converted to uppercase. + * + * @return Formatted RUN header string, e.g.: + * "RUN datafile BEAMLINE PSI DB (name beamline institute data-file-format)\\n" */ QString PGetNonMusrRunBlockDialog::getRunHeaderInfo() { @@ -81,9 +110,16 @@ QString PGetNonMusrRunBlockDialog::getRunHeaderInfo() //---------------------------------------------------------------------------------------------------- /** - *

Extracts the map from the dialog, and returns it as a string. + * @brief Generates the parameter map line for the non-muSR block. * - * \param valid flag indicating of the map is potentially being valid. + * @details The map line defines the mapping between theory function parameters + * and the fit parameters defined in the FITPARAMETER block. The method validates + * that the map contains only space-separated integers. + * + * @param[out] valid Set to true if the map contains only digits and spaces, + * false if invalid characters are found. + * + * @return Formatted map string, e.g.: "map 1 2 3\\n" */ QString PGetNonMusrRunBlockDialog::getMap(bool &valid) { @@ -104,9 +140,17 @@ QString PGetNonMusrRunBlockDialog::getMap(bool &valid) //---------------------------------------------------------------------------------------------------- /** - *

Extracts xy-data from the dialog and returns it as a string. + * @brief Generates the xy-data specification line for the non-muSR block. * - * \param valid flag showing that x/y-data are present. + * @details Creates the "xy-data" line specifying which columns in the data file + * contain the x (independent variable) and y (dependent variable) values. + * Both columns must be specified for the line to be valid. + * + * @param[out] valid Set to true if both x and y data column numbers are provided, + * false if either is missing. + * + * @return Formatted xy-data string, e.g.: "xy-data 1 2\\n" + * Returns empty string if either x or y data is not specified. */ QString PGetNonMusrRunBlockDialog::getXYData(bool &valid) { @@ -126,10 +170,17 @@ QString PGetNonMusrRunBlockDialog::getXYData(bool &valid) //---------------------------------------------------------------------------------------------------- /** - *

Extracts the fit-range from the dialog and returns it as a string. If not fit-range was given, - * a fit-range from 0 to 10 us will be returned and the valid flag will be set to false. + * @brief Generates the fit range specification line for the non-muSR block. * - * \param valid flag showing if a fit-range is given. + * @details Creates the "fit" line specifying the x-value range over which the + * fit will be performed. If no fit range is provided by the user, a default + * range of [0.0, 10.0] is returned. + * + * @param[out] valid Set to true if both fit range values are provided by the user, + * false if using the default range. + * + * @return Formatted fit range string, e.g.: "fit 0.5 99.5\\n" + * Returns default "fit 0.0 10.0\\n" if values are missing. */ QString PGetNonMusrRunBlockDialog::getFitRange(bool &valid) { @@ -150,7 +201,11 @@ QString PGetNonMusrRunBlockDialog::getFitRange(bool &valid) //---------------------------------------------------------------------------------------------------- /** - *

Generates a help content window showing the description of the NonMusr run block. + * @brief Opens the online help documentation for non-muSR RUN blocks. + * + * @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 PGetNonMusrRunBlockDialog::helpContent() { diff --git a/src/musredit_qt6/musredit/PGetNonMusrRunBlockDialog.h b/src/musredit_qt6/musredit/PGetNonMusrRunBlockDialog.h index 357311369..94578f28b 100644 --- a/src/musredit_qt6/musredit/PGetNonMusrRunBlockDialog.h +++ b/src/musredit_qt6/musredit/PGetNonMusrRunBlockDialog.h @@ -27,14 +27,60 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PGetNonMusrRunBlockDialog.h + * @brief Dialog for creating non-muSR RUN blocks in msr files. + * @details This header defines the PGetNonMusrRunBlockDialog class which provides + * a dialog for entering parameters needed to create a non-muSR type RUN block + * in a musrfit msr file. Non-muSR data fitting is used for generic x-y data + * that does not follow the standard muon spin rotation format. + * + * @author Andreas Suter + * @date 2009-2025 + * @copyright Copyright (C) 2009-2025 by Andreas Suter + * @license GNU General Public License v2 or later + * + * @see PGetAsymmetryRunBlockDialog For asymmetry RUN blocks + * @see PGetSingleHistoRunBlockDialog For single histogram RUN blocks + */ + #ifndef _PGETNONMUSRRUNBLOCKDIALOG_H_ #define _PGETNONMUSRRUNBLOCKDIALOG_H_ #include "ui_PGetNonMusrRunBlockDialog.h" -//------------------------------------------------------------------------------------- +//--------------------------------------------------------------------------- /** - *

Handles the content of the NonMusr run block dialog. + * @class PGetNonMusrRunBlockDialog + * @brief Dialog for creating non-muSR type RUN blocks in msr files. + * + * @details This dialog collects all parameters needed to generate a non-muSR + * RUN block for fitting generic x-y data. Unlike muon spin rotation data, + * non-muSR data is typically used for fitting arbitrary datasets such as + * magnetization curves, susceptibility data, or other experimental measurements. + * + * @par RUN Block Parameters: + * - Run file name, beamline, institute, and file format (typically DB) + * - Parameter map (mapping to FITPARAMETER block) + * - X-Y data column specifications + * - Fit range + * + * @par Generated Output Format: + * The dialog generates msr-file formatted text blocks such as: + * @code + * RUN datafile BEAMLINE PSI DB (name beamline institute data-file-format) + * map 1 2 3 + * xy-data 1 2 + * fit 0.0 100.0 + * @endcode + * + * @par Supported File Formats: + * - DB: Generic database format (default) + * - ASCII: Plain text column data + * - Other formats as supported by musrfit + * + * @see PGetAsymmetryRunBlockDialog For muSR asymmetry fitting + * @see PGetSingleHistoRunBlockDialog For single histogram muSR fitting */ class PGetNonMusrRunBlockDialog : public QDialog, private Ui::PGetNonMusrRunBlockDialog { @@ -43,16 +89,46 @@ class PGetNonMusrRunBlockDialog : public QDialog, private Ui::PGetNonMusrRunBloc public: PGetNonMusrRunBlockDialog(const QString helpUrl = ""); + /** @name RUN Block Generators + * @brief Methods to generate formatted msr-file text for each parameter. + * @{ + */ + /** + * @brief Generates the RUN header line. + * @return Formatted RUN header string with file name, beamline, institute, and format. + */ QString getRunHeaderInfo(); - QString getMap(bool &valid); - QString getXYData(bool &valid); - QString getFitRange(bool &valid); - private slots: + /** + * @brief Generates the parameter map line. + * @param[out] valid Set to true if the map contains only valid characters. + * @return Formatted map string for the msr file. + */ + QString getMap(bool &valid); + + /** + * @brief Generates the xy-data specification line. + * @param[out] valid Set to true if both x and y data columns are specified. + * @return Formatted xy-data string for the msr file. + */ + QString getXYData(bool &valid); + + /** + * @brief Generates the fit range specification line. + * @param[out] valid Set to true if a fit range was provided, false if using defaults. + * @return Formatted fit range string for the msr file. + */ + QString getFitRange(bool &valid); + /** @} */ + + private slots: + /** + * @brief Opens the online help for non-muSR RUN blocks. + */ void helpContent(); private: - QString fHelpUrl; ///< help url address for the NonMusr run block. + QString fHelpUrl; ///< URL to the online documentation for non-muSR RUN blocks. }; #endif // _PGETNONMUSRRUNBLOCKDIALOG_H_