improve the doxygen docu of PGetTheoryBlockDialog.* (musredit_qt6).
This commit is contained in:
@@ -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 <QMessageBox>
|
||||
#include <QTextEdit>
|
||||
#include <QComboBox>
|
||||
@@ -41,10 +54,32 @@
|
||||
|
||||
//----------------------------------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>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),
|
||||
@@ -73,7 +108,39 @@ PGetTheoryBlockDialog::PGetTheoryBlockDialog(PAdmin *admin, const QString helpUr
|
||||
|
||||
//----------------------------------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>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()
|
||||
|
||||
//----------------------------------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>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()
|
||||
|
||||
//----------------------------------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>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()
|
||||
|
||||
//----------------------------------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>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()
|
||||
{
|
||||
|
||||
@@ -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"
|
||||
|
||||
//-----------------------------------------------------------------------------
|
||||
//---------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>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_
|
||||
|
||||
Reference in New Issue
Block a user