diff --git a/src/musredit_qt6/musredit/PGetTheoryBlockDialog.cpp b/src/musredit_qt6/musredit/PGetTheoryBlockDialog.cpp index 81fd6d061..4b0086ae6 100644 --- a/src/musredit_qt6/musredit/PGetTheoryBlockDialog.cpp +++ b/src/musredit_qt6/musredit/PGetTheoryBlockDialog.cpp @@ -27,6 +27,19 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PGetTheoryBlockDialog.cpp + * @brief Implementation of the THEORY block dialog for musredit. + * + * @details Provides the implementation of PGetTheoryBlockDialog class methods + * for creating and editing THEORY blocks in musrfit msr files. The dialog + * enables interactive selection and combination of theory functions with + * visual LaTeX equation previews. + * + * @author Andreas Suter + * @date 2009-2025 + */ + #include #include #include @@ -41,10 +54,32 @@ //---------------------------------------------------------------------------------------------------- /** - *

Constructor. + * @brief Constructor - Initializes the THEORY block dialog. * - * \param admin pointer to the administration class object needed to extract the default theory set informations. - * \param helpUrl help url for the asymmetry run block + * @details Sets up the user interface and populates the theory function combo box + * with all available theory functions from the administration object. Each function + * is displayed with its label and, if available, a LaTeX-rendered equation icon. + * + * The combo box icon size is set to 250x20 pixels to accommodate LaTeX equation + * images. Icons are loaded from embedded Qt resources (:/latex_images/) based on + * the pixmap name specified in each theory function definition. + * + * The dialog is configured as modal, requiring user interaction before returning + * control to the parent window. + * + * @param admin Pointer to the PAdmin administration object containing theory + * function definitions loaded from musrfit_startup.xml. Must not be + * nullptr for proper operation. + * @param helpUrl URL string for the online help documentation. If empty, help + * button will display a placeholder message instead of opening a + * web browser. + * + * @note The dialog assumes fAdmin is valid and contains at least one theory function. + * No validation is performed on the admin pointer. + * + * @see PAdmin::getTheoryCounts() Returns the number of available theory functions + * @see PAdmin::getTheoryItem() Retrieves a specific theory function definition + * @see PTheory Structure containing function name, parameters, label, and pixmap name */ PGetTheoryBlockDialog::PGetTheoryBlockDialog(PAdmin *admin, const QString helpUrl) : fAdmin(admin), @@ -62,7 +97,7 @@ PGetTheoryBlockDialog::PGetTheoryBlockDialog(PAdmin *admin, const QString helpUr for (unsigned int i=0; igetTheoryCounts(); i++) { theoItem = fAdmin->getTheoryItem(i); if (theoItem->pixmapName.length() > 0) { - iconName = QString(":/latex_images/") + theoItem->pixmapName; + iconName = QString(":/latex_images/") + theoItem->pixmapName; icon = new QIcon(QPixmap(iconName)); fTheoryFunction_comboBox->insertItem(i, *icon, theoItem->label); } else { @@ -73,7 +108,39 @@ PGetTheoryBlockDialog::PGetTheoryBlockDialog(PAdmin *admin, const QString helpUr //---------------------------------------------------------------------------------------------------- /** - *

returns the theory function string of the currently selected theory function. + * @brief Generates the formatted theory function string for the selected function. + * + * @details Constructs a complete theory function line suitable for insertion into + * an msr file THEORY block. The format depends on the function type: + * + * For standard functions: + * @code + * functionName 1 2 3 ... (comment) + * @endcode + * + * For user-defined functions (userFcn): + * @code + * userFcn libMyLibrary.so TMyFunction 1 2 ... (comment) + * @endcode + * + * The parameter numbers (1, 2, 3, ...) are placeholders that should be replaced + * with actual FITPARAMETER indices or map references before the msr file is used + * for fitting. + * + * @return QString containing the formatted theory function line with: + * - Function name + * - Library and function names (for userFcn only) + * - Sequential parameter placeholders (1 to params count) + * - Parameter comment from theory definition + * Returns "????" if the theory item cannot be retrieved (invalid index). + * + * @note This is a private slot method typically called by addPlus() and addMultiply(). + * + * @see PTheory::name Function name as defined in XML + * @see PTheory::params Number of parameters required by the function + * @see PTheory::comment Descriptive text explaining the parameters + * @see addPlus() Uses this method to add functions with addition + * @see addMultiply() Uses this method to add functions with multiplication */ QString PGetTheoryBlockDialog::getTheoFuncString() { @@ -100,7 +167,27 @@ QString PGetTheoryBlockDialog::getTheoFuncString() //---------------------------------------------------------------------------------------------------- /** - *

adds the current theory function to the text field and additionally adds a '+'. + * @brief Adds the current theory function followed by a '+' operator. + * + * @details Retrieves the formatted string for the currently selected theory + * function and appends it to the theory block text editor, followed by a newline + * and a '+' character. The '+' indicates that the next function should be added + * (summed) rather than multiplied with the current function. + * + * This creates additive terms in the fit model. For example: + * @code + * asymmetry 1 + * simpleGss 2 (rate) + * + + * asymmetry 3 + * simpleLor 4 (rate) + * @endcode + * Represents: A1*Gss(t) + A2*Lor(t) + * + * @note This slot is connected to the "Plus" button in the UI (fPlus_pushButton). + * + * @see getTheoFuncString() Generates the theory function string + * @see addMultiply() For multiplicative combination of functions */ void PGetTheoryBlockDialog::addPlus() { @@ -110,7 +197,27 @@ void PGetTheoryBlockDialog::addPlus() //---------------------------------------------------------------------------------------------------- /** - *

adds the current theory function to the text field (newline == '*'). + * @brief Adds the current theory function for multiplication. + * + * @details Retrieves the formatted string for the currently selected theory + * function and appends it to the theory block text editor on a new line. In + * musrfit theory block syntax, functions on consecutive lines (without a '+' + * separator between them) are implicitly multiplied together. + * + * This creates multiplicative terms in the fit model. For example: + * @code + * asymmetry 1 + * simpleGss 2 (rate) + * TFieldCos 3 4 (phase frequency) + * @endcode + * Represents: A1 * Gss(t) * cos(ωt + φ) + * + * @note In the code comment "newline == '*'" refers to the implicit multiplication + * semantics: a newline without '+' means multiply. + * @note This slot is connected to the "Multiply" button in the UI (fMultiply_pushButton). + * + * @see getTheoFuncString() Generates the theory function string + * @see addPlus() For additive combination of functions */ void PGetTheoryBlockDialog::addMultiply() { @@ -120,7 +227,25 @@ void PGetTheoryBlockDialog::addMultiply() //---------------------------------------------------------------------------------------------------- /** - *

Generates a help content window showing the description of the theory block. + * @brief Opens online help documentation for THEORY blocks. + * + * @details Attempts to open the help URL in the user's default web browser using + * QDesktopServices::openUrl(). The help typically provides comprehensive + * documentation on: + * - Available theory functions and their physical meanings + * - Parameter descriptions for each function + * - Syntax rules for combining functions + * - Examples of common theory block patterns for µSR data analysis + * + * Error handling: + * - If fHelpUrl is empty: displays an information dialog with a placeholder message + * - If the browser fails to open: displays a critical error dialog with the URL + * formatted as a clickable hyperlink for manual access + * + * @note The URL is parsed in TolerantMode to handle various URL formats gracefully. + * @note This slot is connected to the help button in the UI. + * + * @see PGetTheoryBlockDialog::PGetTheoryBlockDialog() Where fHelpUrl is initialized */ void PGetTheoryBlockDialog::helpContent() { diff --git a/src/musredit_qt6/musredit/PGetTheoryBlockDialog.h b/src/musredit_qt6/musredit/PGetTheoryBlockDialog.h index b46d75f2f..eaa894170 100644 --- a/src/musredit_qt6/musredit/PGetTheoryBlockDialog.h +++ b/src/musredit_qt6/musredit/PGetTheoryBlockDialog.h @@ -27,34 +27,192 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PGetTheoryBlockDialog.h + * @brief Dialog for creating THEORY blocks in msr files. + * @details This header defines the PGetTheoryBlockDialog class which provides + * a dialog for building theory function expressions needed to create a THEORY + * block in a musrfit msr file. The dialog presents available theory functions + * with LaTeX-rendered equation previews. + * + * @author Andreas Suter + * @date 2009-2025 + * @copyright Copyright (C) 2009-2025 by Andreas Suter + * @license GNU General Public License v2 or later + * + * @see PGetParameterBlockDialog For creating FITPARAMETER blocks + * @see PGetFunctionsBlockDialog For creating FUNCTIONS blocks + * @see PAdmin For theory function definitions loaded from XML + */ + #ifndef _PGETTHEORYBLOCKDIALOG_H_ #define _PGETTHEORYBLOCKDIALOG_H_ #include "PAdmin.h" #include "ui_PGetTheoryBlockDialog.h" -//----------------------------------------------------------------------------- +//--------------------------------------------------------------------------- /** - *

Class handling the content of the menu: Edit/Add Block/Theory Block. + * @class PGetTheoryBlockDialog + * @brief Dialog for creating THEORY blocks in msr files. + * + * @details This dialog allows users to build theory function expressions by + * selecting from a list of available theory functions. Functions can be + * combined using addition (+) or multiplication (*) operators. The dialog + * displays LaTeX-rendered equation icons for visual function identification. + * + * @par Available Theory Functions: + * Theory functions are loaded from the XML configuration file and include: + * - Asymmetry functions (asymmetry, simpleGss, simpleLor, etc.) + * - Relaxation functions (expLF, stretchedExp, etc.) + * - Oscillation functions (TFieldCos, internFld, etc.) + * - User-defined functions (userFcn) + * + * @par Theory Block Syntax: + * Functions on the same line are multiplied; functions preceded by '+' are added: + * @code + * THEORY + * asymmetry 1 + * simpleGss 2 (rate) + * + + * asymmetry 3 + * simpleLor 4 (rate) + * @endcode + * This represents: A1 * Gss(t) + A2 * Lor(t) + * + * @par Parameter Numbering: + * Each function line includes placeholder parameter numbers (1, 2, 3...) that + * should be replaced with actual parameter references from the FITPARAMETER + * block or map indices. + * + * @see PAdmin For loading and managing theory function definitions + * @see PTheory For the structure holding individual theory function data */ class PGetTheoryBlockDialog : public QDialog, private Ui::PGetTheoryBlockDialog { Q_OBJECT public: + /** + * @brief Constructs a dialog for creating THEORY blocks. + * + * @details Initializes the dialog with available theory functions from the + * administration object. Sets up the combo box with function names and + * LaTeX equation icons loaded from embedded resources. The dialog is + * configured as modal to ensure user interaction completion. + * + * @param admin Pointer to the PAdmin object containing theory function + * definitions loaded from the XML configuration file. If nullptr, + * the dialog will not function properly. + * @param helpUrl URL string pointing to online documentation for THEORY blocks. + * If empty, help button will show a placeholder message. + * + * @see PAdmin::getTheoryCounts() For retrieving number of available functions + * @see PAdmin::getTheoryItem() For accessing individual theory function data + */ PGetTheoryBlockDialog(PAdmin *admin = 0, const QString helpUrl = ""); + /** + * @brief Returns the complete theory block text. + * + * @details Retrieves all theory function expressions entered by the user + * through the dialog interface. The returned string is formatted according + * to musrfit msr file specifications and is ready for direct insertion into + * the THEORY section of an msr file. + * + * @return QString containing all theory function lines, with proper formatting + * including function names, parameter placeholders, comments, and + * operators ('+' for addition, newline for multiplication). + * + * @note The returned string should be parsed and parameter numbers replaced + * with actual FITPARAMETER references before saving to file. + */ QString getTheoryBlock() { return fTheoryBlock_plainTextEdit->toPlainText(); } private slots: + /** + * @brief Generates the theory function string for the selected function. + * + * @details Constructs a formatted string for the currently selected theory + * function from the combo box. The string includes: + * - Function name (e.g., "asymmetry", "simpleGss") + * - For userFcn: library and function names (e.g., "libMyLibrary.so TMyFunction") + * - Sequential parameter placeholders (1, 2, 3, ...) + * - Function comment describing parameters + * + * Example output: "simpleGss 1 2 (phase frequency)" + * + * @return QString containing the formatted theory function line. Returns "????" + * if no valid theory item is found at the current index. + * + * @see PTheory For the structure defining theory function properties + */ QString getTheoFuncString(); + + /** + * @brief Adds the selected function followed by a '+' operator. + * + * @details Appends the currently selected theory function to the text editor, + * followed by a '+' character on a new line. This indicates that the next + * function should be added (summed) rather than multiplied. In musrfit + * theory blocks, the '+' operator creates additive terms in the fit function. + * + * Example result in editor: + * @code + * asymmetry 1 + * simpleGss 2 (rate) + * + + * @endcode + * + * @note Connected to the "Plus" button click signal in the UI. + * + * @see addMultiply() For multiplicative combination + */ void addPlus(); + + /** + * @brief Adds the selected function (multiplication with next line). + * + * @details Appends the currently selected theory function to the text editor + * on a new line. In musrfit theory blocks, functions on consecutive lines + * (without a '+' separator) are multiplied together. This is the default + * operation for combining functions like asymmetry with relaxation. + * + * Example result in editor: + * @code + * asymmetry 1 + * simpleGss 2 (rate) + * @endcode + * Represents: A1 * Gss(t) + * + * @note Connected to the "Multiply" button click signal in the UI. + * + * @see addPlus() For additive combination + */ void addMultiply(); + + /** + * @brief Opens the online help for THEORY blocks. + * + * @details Attempts to open the help URL in the system's default web browser + * using QDesktopServices. If the URL is empty, displays a placeholder + * information message. If the browser cannot be opened, shows an error + * dialog with the URL for manual access. + * + * The help documentation typically covers: + * - Available theory functions and their parameters + * - Syntax for combining functions + * - Examples of common theory block patterns + * + * @note Connected to the help button click signal in the UI. + * + * @see PGetTheoryBlockDialog::PGetTheoryBlockDialog() Where helpUrl is set + */ void helpContent(); private: - PAdmin *fAdmin; ///< pointer to the administration class object needed to extract the default theory set informations. - QString fHelpUrl; ///< help url for the asymmetry run block + PAdmin *fAdmin; ///< Pointer to the administration object for accessing theory function definitions. + QString fHelpUrl; ///< URL to the online documentation for THEORY blocks. }; #endif // _PGETTHEORYBLOCKDIALOG_H_