diff --git a/src/musredit_qt6/musredit/PGetParameterBlockDialog.cpp b/src/musredit_qt6/musredit/PGetParameterBlockDialog.cpp index ddd82a4fb..ea215ae74 100644 --- a/src/musredit_qt6/musredit/PGetParameterBlockDialog.cpp +++ b/src/musredit_qt6/musredit/PGetParameterBlockDialog.cpp @@ -27,6 +27,19 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PGetParameterBlockDialog.cpp + * @brief Implementation of the PGetParameterBlockDialog class. + * @details This file implements the dialog for creating FITPARAMETER blocks + * in msr files. It handles user input validation, proper column formatting + * for the msr file format, and keyboard shortcuts for rapid parameter entry. + * + * @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 @@ -41,9 +54,21 @@ //---------------------------------------------------------------------------------------------------- /** - *

Constructor. + * @brief Constructs the FITPARAMETER block dialog. * - * \param helpUrl help url of the PARAMETER block. + * @details Initializes the dialog UI, sets up input validators for numeric + * fields, and installs an event filter to capture keyboard shortcuts. + * The dialog is created as modal. A monospace font (Courier, 10pt) is used + * for the parameter display to ensure proper column alignment. + * + * @par Input Validators: + * - Double validators: parameter value and step size + * + * @par Event Filter: + * An event filter is installed to intercept the Return key, allowing users + * to quickly add parameters by pressing Enter instead of clicking the Add button. + * + * @param helpUrl URL to the online documentation for FITPARAMETER blocks. */ PGetParameterBlockDialog::PGetParameterBlockDialog(const QString helpUrl) : fHelpUrl(helpUrl) { @@ -62,11 +87,18 @@ PGetParameterBlockDialog::PGetParameterBlockDialog(const QString helpUrl) : fHel //---------------------------------------------------------------------------------------------------- /** - *

This event filter is filtering out the return key, and if present adds the current parameters - * to the parameter list. + * @brief Event filter to intercept keyboard events. * - * \param obj object which was generating the event. - * \param ev event of the object. + * @details Filters keyboard events to intercept the Return/Enter key press. + * When Return is pressed, the current parameter values are validated and + * added to the parameter list via paramAdd(). This allows for rapid + * parameter entry without using the mouse to click the Add button. + * + * @param obj Pointer to the object that generated the event. + * @param ev Pointer to the event to be filtered. + * + * @return true if the event was handled (Return key was pressed and parameter + * was added), false otherwise (event is passed to the base class). */ bool PGetParameterBlockDialog::eventFilter( QObject *obj, QEvent *ev ) { @@ -89,7 +121,33 @@ bool PGetParameterBlockDialog::eventFilter( QObject *obj, QEvent *ev ) //---------------------------------------------------------------------------------------------------- /** - *

Adds a parameter to the text edit window. + * @brief Validates and adds a parameter to the FITPARAMETER block. + * + * @details Collects values from all input fields, validates required fields, + * formats the parameter line with proper column alignment, and appends it + * to the parameter text display. After successful addition, the input fields + * are reset and focus returns to the Name field for the next parameter. + * + * @par Validation Rules: + * - Parameter name is required (cannot be empty) + * - Parameter value is required (cannot be empty) + * - Parameter step is required (cannot be empty) + * - Lower boundary must be "none" or a valid double + * - Upper boundary must be "none" or a valid double + * + * @par Column Formatting: + * - Parameter number: right-aligned in 10 character field + * - Name: left-aligned, padded to 13 characters + * - Value: left-aligned, padded to 10 characters + * - Step: left-aligned, padded to 10 characters + * - Positive error: always "none" (11 characters) + * - Lower boundary: left-aligned, padded to 10 characters (optional) + * - Upper boundary: left-aligned, padded to 10 characters (optional) + * + * @par Post-Addition Actions: + * - Parameter number is auto-incremented + * - All input fields are cleared (boundaries reset to "none") + * - Focus moves to the Name field */ void PGetParameterBlockDialog::paramAdd() { @@ -213,7 +271,11 @@ void PGetParameterBlockDialog::paramAdd() //---------------------------------------------------------------------------------------------------- /** - *

Generates a help content window showing the description of the FITPARAMETER block. + * @brief Opens the online help documentation for FITPARAMETER 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 PGetParameterBlockDialog::helpContent() { diff --git a/src/musredit_qt6/musredit/PGetParameterBlockDialog.h b/src/musredit_qt6/musredit/PGetParameterBlockDialog.h index 2436f936c..bc41890f2 100644 --- a/src/musredit_qt6/musredit/PGetParameterBlockDialog.h +++ b/src/musredit_qt6/musredit/PGetParameterBlockDialog.h @@ -27,14 +27,62 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PGetParameterBlockDialog.h + * @brief Dialog for creating FITPARAMETER blocks in msr files. + * @details This header defines the PGetParameterBlockDialog class which provides + * a dialog for entering fit parameters needed to create a FITPARAMETER block + * in a musrfit msr file. The dialog supports parameter entry with validation + * and optional boundary constraints. + * + * @author Andreas Suter + * @date 2009-2025 + * @copyright Copyright (C) 2009-2025 by Andreas Suter + * @license GNU General Public License v2 or later + * + * @see PGetFunctionsBlockDialog For creating FUNCTIONS blocks using these parameters + * @see PGetTheoryBlockDialog For creating THEORY blocks + */ + #ifndef _PGETPARAMETERBLOCKDIALOG_H_ #define _PGETPARAMETERBLOCKDIALOG_H_ #include "ui_PGetParameterBlockDialog.h" -//----------------------------------------------------------------------------------- +//--------------------------------------------------------------------------- /** - *

Handles the content of the PARAMETER block dialog. + * @class PGetParameterBlockDialog + * @brief Dialog for creating FITPARAMETER blocks in msr files. + * + * @details This dialog allows users to define fit parameters for musrfit. + * Each parameter consists of a number, name, initial value, step size, and + * optional lower/upper boundaries. Parameters are formatted with proper + * column alignment for the msr file format. + * + * @par Parameter Fields: + * - **No**: Parameter number (auto-incremented) + * - **Name**: Parameter name (required, max ~12 chars for alignment) + * - **Value**: Initial parameter value (required) + * - **Step**: Initial step size for minimizer (required) + * - **Lower**: Lower boundary ("none" or numeric value) + * - **Upper**: Upper boundary ("none" or numeric value) + * + * @par Generated Output Format: + * The dialog generates properly formatted FITPARAMETER lines: + * @code + * FITPARAMETER + * 1 alpha 1.0 0.01 none + * 2 beta 0.5 0.001 none 0.0 1.0 + * 3 frequency 10.5 0.1 none + * @endcode + * + * @par User Interaction: + * - Press Return/Enter key to quickly add parameters + * - Parameter number auto-increments after each addition + * - Input fields are reset after adding a parameter + * - Focus returns to the Name field for rapid entry + * + * @see PGetFunctionsBlockDialog For defining functions using these parameters */ class PGetParameterBlockDialog : public QDialog, private Ui::PGetParameterBlockDialog { @@ -43,17 +91,37 @@ class PGetParameterBlockDialog : public QDialog, private Ui::PGetParameterBlockD public: PGetParameterBlockDialog(const QString helpUrl); + /** + * @brief Returns all entered parameters as formatted text. + * @return Complete FITPARAMETER block content ready for insertion + * into an msr file. + */ QString getParams() { return fParam_plainTextEdit->toPlainText(); } protected: + /** + * @brief Event filter to handle keyboard shortcuts. + * @details Intercepts the Return key to trigger parameter addition, + * allowing for rapid parameter entry without clicking the Add button. + * @param obj The object that generated the event. + * @param ev The event to be filtered. + * @return true if the event was handled (Return key), false otherwise. + */ bool eventFilter( QObject *obj, QEvent *ev ); private slots: + /** + * @brief Validates and adds a parameter to the FITPARAMETER block. + */ void paramAdd(); + + /** + * @brief Opens the online help for FITPARAMETER blocks. + */ void helpContent(); private: - QString fHelpUrl; ///< help url of the PARAMETER block description. + QString fHelpUrl; ///< URL to the online documentation for FITPARAMETER blocks. }; #endif // _PGETPARAMETERBLOCKDIALOG_H_