improve the doxygen docu of musrStep.
This commit is contained in:
@@ -27,6 +27,18 @@
|
||||
* 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *
|
||||
***************************************************************************/
|
||||
|
||||
/**
|
||||
* @file PMusrStep.cpp
|
||||
* @brief Implementation of the PMusrStep and PModSelect dialog classes.
|
||||
* @details This file contains the implementation of the GUI dialogs used
|
||||
* by the musrStep application to modify fit parameter step sizes in
|
||||
* muSR msr-files.
|
||||
*
|
||||
* @author Andreas Suter
|
||||
* @date 2007-2025
|
||||
* @copyright GNU General Public License v2 or later
|
||||
*/
|
||||
|
||||
#include <QMessageBox>
|
||||
#include <QString>
|
||||
#include <QStringList>
|
||||
@@ -48,7 +60,14 @@
|
||||
|
||||
//+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
/**
|
||||
* @brief Constructor for the PModSelect dialog.
|
||||
* @details Creates and initializes the dialog UI with the following controls:
|
||||
* - "Scale by Factor" button with associated factor input field
|
||||
* - "Absolute Value" checkbox to toggle between multiplicative and absolute scaling
|
||||
* - "Scale Automatically" button for automatic scaling based on parameter names
|
||||
* - "Cancel" button to close the dialog without applying changes
|
||||
*
|
||||
* @param parent Pointer to the parent widget (default: Q_NULLPTR)
|
||||
*/
|
||||
PModSelect::PModSelect(QWidget *parent) :
|
||||
QDialog(parent)
|
||||
@@ -91,8 +110,12 @@ PModSelect::PModSelect(QWidget *parent) :
|
||||
|
||||
//-------------------------------------------------------------------------
|
||||
/**
|
||||
* @brief PModSelect::absoluteValueStateChanged
|
||||
* @param ival
|
||||
* @brief Handles state changes of the absolute value checkbox.
|
||||
* @details Updates the UI labels to reflect the current mode:
|
||||
* - When unchecked: Shows "Factor" label and "Scale by Factor" button text
|
||||
* - When checked: Shows "Value" label and "Set Abs. Value" button text
|
||||
*
|
||||
* @param ival The new checkbox state (Qt::Checked or Qt::Unchecked)
|
||||
*/
|
||||
void PModSelect::absoluteValueStateChanged(int ival)
|
||||
{
|
||||
@@ -107,7 +130,10 @@ void PModSelect::absoluteValueStateChanged(int ival)
|
||||
|
||||
//-------------------------------------------------------------------------
|
||||
/**
|
||||
*
|
||||
* @brief Triggers automatic scaling of selected parameters.
|
||||
* @details Emits the scale() signal with automatic=true and a default
|
||||
* factor of 0.01. The parent dialog will then apply scaling factors
|
||||
* based on parameter naming conventions using its lookupTable() method.
|
||||
*/
|
||||
void PModSelect::scaleAuto()
|
||||
{
|
||||
@@ -117,7 +143,10 @@ void PModSelect::scaleAuto()
|
||||
|
||||
//-------------------------------------------------------------------------
|
||||
/**
|
||||
*
|
||||
* @brief Reads the user-specified factor and emits the scale signal.
|
||||
* @details Retrieves the factor value from the input field and the
|
||||
* absolute value checkbox state, then emits the scale() signal with
|
||||
* automatic=false to indicate manual scaling mode.
|
||||
*/
|
||||
void PModSelect::getFactor()
|
||||
{
|
||||
@@ -130,7 +159,21 @@ void PModSelect::getFactor()
|
||||
|
||||
//+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
/**
|
||||
* @brief Constructor for the PMusrStep main dialog.
|
||||
* @details Initializes the dialog with the following operations:
|
||||
* 1. Sets up the window title and icon based on the current theme
|
||||
* 2. Reads and parses the msr-file to extract fit parameters
|
||||
* 3. Creates the parameter table with columns for name, value, and step
|
||||
* 4. Sets up selection buttons (Check Specific, Check All, Uncheck All)
|
||||
* 5. Sets up modification buttons (Modify Automatic, Modify Selected)
|
||||
* 6. Sets up action buttons (Save&Quit, Cancel)
|
||||
* 7. Creates the PModSelect sub-dialog for detailed modification options
|
||||
*
|
||||
* The dialog height is automatically adjusted based on the number of
|
||||
* parameters, with a maximum limit based on screen resolution.
|
||||
*
|
||||
* @param fln Path to the msr-file to open and edit
|
||||
* @param parent Pointer to the parent widget (default: Q_NULLPTR)
|
||||
*/
|
||||
PMusrStep::PMusrStep(const char *fln, QWidget *parent) :
|
||||
QDialog(parent),
|
||||
@@ -257,7 +300,16 @@ PMusrStep::PMusrStep(const char *fln, QWidget *parent) :
|
||||
|
||||
//-------------------------------------------------------------------------
|
||||
/**
|
||||
* @brief Handles changes to cells in the parameter table.
|
||||
* @details Performs validation when table cells are modified:
|
||||
* - Column 0 (name): Prevents selection of fixed parameters (step == 0)
|
||||
* - Column 2 (step): Validates that entered values are valid numbers
|
||||
*
|
||||
* If an invalid step value is entered, the cell is restored to its
|
||||
* previous value from fParamVec.
|
||||
*
|
||||
* @param row The row index of the changed cell
|
||||
* @param column The column index of the changed cell
|
||||
*/
|
||||
void PMusrStep::handleCellChanged(int row, int column)
|
||||
{
|
||||
@@ -283,7 +335,10 @@ void PMusrStep::handleCellChanged(int row, int column)
|
||||
|
||||
//-------------------------------------------------------------------------
|
||||
/**
|
||||
*
|
||||
* @brief Allows selection of parameters matching a template string.
|
||||
* @details Opens an input dialog where the user can enter a template string.
|
||||
* All parameters whose names contain this template (case-sensitive) are
|
||||
* then checked, except for fixed parameters (step == 0 or "0.0").
|
||||
*/
|
||||
void PMusrStep::checkSpecific()
|
||||
{
|
||||
@@ -305,7 +360,9 @@ void PMusrStep::checkSpecific()
|
||||
|
||||
//-------------------------------------------------------------------------
|
||||
/**
|
||||
*
|
||||
* @brief Selects all non-fixed parameters in the table.
|
||||
* @details Iterates through all rows and checks parameters whose step
|
||||
* value is not "0" or "0.0" (fixed parameters remain unchecked).
|
||||
*/
|
||||
void PMusrStep::checkAll()
|
||||
{
|
||||
@@ -319,7 +376,9 @@ void PMusrStep::checkAll()
|
||||
|
||||
//-------------------------------------------------------------------------
|
||||
/**
|
||||
*
|
||||
* @brief Deselects all parameters in the table.
|
||||
* @details Iterates through all rows and unchecks every parameter,
|
||||
* regardless of whether it is fixed or not.
|
||||
*/
|
||||
void PMusrStep::unCheckAll()
|
||||
{
|
||||
@@ -330,7 +389,10 @@ void PMusrStep::unCheckAll()
|
||||
|
||||
//-------------------------------------------------------------------------
|
||||
/**
|
||||
*
|
||||
* @brief Applies automatic step size modification to all non-fixed parameters.
|
||||
* @details Iterates through all parameters and applies automatic scaling
|
||||
* using lookupTable() and adoptStep(). Fixed parameters (step == 0) are
|
||||
* skipped. Both the table display and the internal fParamVec are updated.
|
||||
*/
|
||||
void PMusrStep::modifyAuto()
|
||||
{
|
||||
@@ -350,7 +412,10 @@ void PMusrStep::modifyAuto()
|
||||
|
||||
//-------------------------------------------------------------------------
|
||||
/**
|
||||
*
|
||||
* @brief Opens the modification dialog for checked parameters.
|
||||
* @details Shows the PModSelect dialog, which allows the user to choose
|
||||
* between automatic scaling and manual factor-based scaling for the
|
||||
* currently selected parameters.
|
||||
*/
|
||||
void PMusrStep::modifyChecked()
|
||||
{
|
||||
@@ -359,7 +424,14 @@ void PMusrStep::modifyChecked()
|
||||
|
||||
//-------------------------------------------------------------------------
|
||||
/**
|
||||
* @brief Processes the scaling selection from the PModSelect dialog.
|
||||
* @details Applies the specified scaling operation to all checked parameters.
|
||||
* If automatic mode is selected, the factor is determined by lookupTable()
|
||||
* for each parameter individually.
|
||||
*
|
||||
* @param automatic If true, use automatic scaling based on parameter names
|
||||
* @param factor The scaling factor (used when automatic is false)
|
||||
* @param absVal If true, factor is used as absolute value; if false, as multiplier
|
||||
*/
|
||||
void PMusrStep::handleModSelect(bool automatic, double factor, bool absVal)
|
||||
{
|
||||
@@ -378,7 +450,9 @@ void PMusrStep::handleModSelect(bool automatic, double factor, bool absVal)
|
||||
|
||||
//-------------------------------------------------------------------------
|
||||
/**
|
||||
*
|
||||
* @brief Saves the modified msr-file and closes the dialog.
|
||||
* @details Calls writeMsrFile() to save all modifications, then
|
||||
* accepts the dialog to close it with a success status.
|
||||
*/
|
||||
void PMusrStep::saveAndQuit()
|
||||
{
|
||||
@@ -388,7 +462,11 @@ void PMusrStep::saveAndQuit()
|
||||
|
||||
//-------------------------------------------------------------------------
|
||||
/**
|
||||
* @brief Initializes a PParam structure with empty strings.
|
||||
* @details Sets all fields of the parameter structure to empty QString
|
||||
* objects. Used before populating a new parameter from file data.
|
||||
*
|
||||
* @param param Reference to the PParam structure to initialize
|
||||
*/
|
||||
void PMusrStep::initParam(PParam ¶m)
|
||||
{
|
||||
@@ -403,7 +481,21 @@ void PMusrStep::initParam(PParam ¶m)
|
||||
|
||||
//-------------------------------------------------------------------------
|
||||
/**
|
||||
* @brief Determines the appropriate step size factor based on parameter name.
|
||||
* @details Uses common muSR parameter naming conventions to identify
|
||||
* parameter types and return appropriate scaling factors:
|
||||
* - freq, frq, field: factor = 1e-3 (high precision for frequency/field)
|
||||
* - lambda, sigma, rlx, rate: factor = 0.1 (relaxation rates)
|
||||
* - phase, phs: factor = 5.0 (absolute value, for phase parameters)
|
||||
* - N0, Nrm, N_bkg, Bgr: factor = 0.01 (normalization/background)
|
||||
* - default: factor = 0.01
|
||||
*
|
||||
* The comparison is case-insensitive and matches the start of the
|
||||
* parameter name.
|
||||
*
|
||||
* @param str The parameter name to look up
|
||||
* @param absVal Output flag set to true if factor should be used as absolute value
|
||||
* @return The scaling factor to apply
|
||||
*/
|
||||
double PMusrStep::lookupTable(const QString str, bool &absVal)
|
||||
{
|
||||
@@ -435,7 +527,15 @@ double PMusrStep::lookupTable(const QString str, bool &absVal)
|
||||
|
||||
//-------------------------------------------------------------------------
|
||||
/**
|
||||
* @brief Calculates the new step value based on current value and factor.
|
||||
* @details Computes the new step size using either:
|
||||
* - Absolute mode (absVal=true): Returns the factor directly as the step
|
||||
* - Multiplicative mode (absVal=false): Returns factor * current_value
|
||||
*
|
||||
* @param str The current parameter value as a string
|
||||
* @param factor The scaling factor to apply
|
||||
* @param absVal If true, return factor directly; if false, multiply by value
|
||||
* @return The new step value as a QString
|
||||
*/
|
||||
QString PMusrStep::adoptStep(const QString str, double factor, bool absVal)
|
||||
{
|
||||
@@ -453,7 +553,19 @@ QString PMusrStep::adoptStep(const QString str, double factor, bool absVal)
|
||||
|
||||
//-------------------------------------------------------------------------
|
||||
/**
|
||||
* @brief Reads and parses the FITPARAMETER block from the msr-file.
|
||||
* @details Opens the msr-file specified in fMsrFileName and extracts
|
||||
* all parameters from the FITPARAMETER block (between FITPARAMETER
|
||||
* and THEORY keywords). Each parameter line must have either 5 or 7
|
||||
* space-separated fields:
|
||||
* - 5 fields: number, name, value, step, posErr
|
||||
* - 7 fields: above plus boundLow, boundHigh
|
||||
*
|
||||
* Comment lines (starting with #) and empty lines are ignored.
|
||||
*
|
||||
* @return 1 on success
|
||||
* @return -1 if file cannot be opened
|
||||
* @return -2 if a parameter line has invalid format
|
||||
*/
|
||||
int PMusrStep::readMsrFile()
|
||||
{
|
||||
@@ -512,7 +624,15 @@ int PMusrStep::readMsrFile()
|
||||
|
||||
//-------------------------------------------------------------------------
|
||||
/**
|
||||
* @brief Writes the modified parameters back to the msr-file.
|
||||
* @details Reads the entire original msr-file, then rewrites it with
|
||||
* updated step values in the FITPARAMETER block. All other content
|
||||
* is preserved unchanged. A "*** FIT DID NOT CONVERGE ***" marker is
|
||||
* appended to indicate the file has been modified.
|
||||
*
|
||||
* @return 1 on success
|
||||
* @return -1 if input file cannot be opened for reading
|
||||
* @return -2 if output file cannot be opened for writing
|
||||
*/
|
||||
int PMusrStep::writeMsrFile()
|
||||
{
|
||||
@@ -567,7 +687,14 @@ int PMusrStep::writeMsrFile()
|
||||
|
||||
//-------------------------------------------------------------------------
|
||||
/**
|
||||
* @brief Extracts a single line from a byte array at the given position.
|
||||
* @details Searches for the next newline character starting at idx and
|
||||
* extracts the text between the current position and the newline.
|
||||
* The idx parameter is updated to point to the character after the newline.
|
||||
*
|
||||
* @param data Reference to the byte array containing file data
|
||||
* @param idx Reference to the current position index (updated to next line start)
|
||||
* @return The extracted line as a QString, or empty string if no newline found
|
||||
*/
|
||||
QString PMusrStep::getLine(QByteArray &data, int &idx)
|
||||
{
|
||||
@@ -584,7 +711,19 @@ QString PMusrStep::getLine(QByteArray &data, int &idx)
|
||||
|
||||
//-------------------------------------------------------------------------
|
||||
/**
|
||||
* @brief Reconstructs a parameter line with updated values.
|
||||
* @details Searches fParamVec for a parameter matching the given line,
|
||||
* then formats a new parameter line with proper field widths:
|
||||
* - Column 1 (10 chars, right-aligned): parameter number
|
||||
* - Column 2 (12+ chars, left-aligned): parameter name
|
||||
* - Columns 3-5 (11 chars each): value, step, posErr
|
||||
* - Columns 6-7 (11 chars each, optional): boundLow, boundHigh
|
||||
*
|
||||
* The parameter is identified by finding its name sandwiched between
|
||||
* spaces in the input string to avoid partial matches.
|
||||
*
|
||||
* @param str The original parameter line to update
|
||||
* @return The reconstructed parameter line, or empty string if no match found
|
||||
*/
|
||||
QString PMusrStep::updateParamLine(const QString str)
|
||||
{
|
||||
|
||||
Reference in New Issue
Block a user