diff --git a/src/musredit_qt6/mupp/PVarDialog.cpp b/src/musredit_qt6/mupp/PVarDialog.cpp index 0d737bd8a..c48db0af3 100644 --- a/src/musredit_qt6/mupp/PVarDialog.cpp +++ b/src/musredit_qt6/mupp/PVarDialog.cpp @@ -41,8 +41,13 @@ //-------------------------------------------------------------------------- /** - * @brief PShowVarNameDialog::PShowVarNameDialog. Ctor - * @param info containing the necessary information of the collection + * @brief Constructor for PShowVarNameDialog. + * + * Creates a dialog displaying all variable names from a collection. If the + * collection name contains a path, only the filename portion is displayed. + * Each variable is shown with its index number. + * + * @param info reference to PCollInfo structure containing the collection name and variable names */ PShowVarNameDialog::PShowVarNameDialog(PCollInfo &info) { @@ -85,12 +90,25 @@ PShowVarNameDialog::PShowVarNameDialog(PCollInfo &info) //-------------------------------------------------------------------------- /** - * @brief PVarDialog::PVarDialog. Variable GUI allowing the users to define - * variables. - * @param collection_list list of all the collections - * @param darkTheme plain/dark theme flag - * @param parent parent widget pointer - * @param f window flag + * @brief Constructor for PVarDialog. + * + * Creates a variable definition dialog with a text editor for variable expressions + * and a collection list view. The dialog allows users to define custom variables + * using expressions that reference collection variables as identifiers (prefixed + * with '$'). Multiple collections can be selected, and the dialog validates that + * all identifiers exist in the selected collections. + * + * The dialog includes buttons for: + * - Check: validates variable definitions + * - Add: adds variables to the mupp GUI + * - Help: displays syntax information + * - ShowVarName: displays variable names from selected collection + * - Cancel: closes the dialog + * + * @param collection_list vector of all available collections with their variable names + * @param darkTheme if true, uses dark theme icons; if false, uses plain icons + * @param parent optional parent widget pointer + * @param f optional window flags for the dialog */ PVarDialog::PVarDialog(QVector collection_list, bool darkTheme, QWidget *parent, Qt::WindowFlags f) : @@ -166,7 +184,12 @@ PVarDialog::PVarDialog(QVector collection_list, bool darkTheme, //-------------------------------------------------------------------------- /** - * @brief PVarDialog::check. Allows the user to check the variable string. + * @brief Validates variable definitions and emits check_request signal. + * + * Performs basic checks (syntax, presence of 'var' keyword, error variable + * definitions) and consistency checks (identifiers exist in collections). + * If validation succeeds, emits the check_request signal with the variable + * string and selected collection indices. */ void PVarDialog::check() { @@ -187,7 +210,12 @@ void PVarDialog::check() //-------------------------------------------------------------------------- /** - * @brief PVarDialog::add. It is used to initiate the add variable to the mupp GUI. + * @brief Validates and adds variable definitions to the mupp GUI. + * + * Checks that input is present and at least one collection is selected. + * Performs basic checks and consistency validation. If all checks pass, + * emits the add_request signal with the variable string and selected + * collection indices. */ void PVarDialog::add() { @@ -218,7 +246,13 @@ void PVarDialog::add() //-------------------------------------------------------------------------- /** - * @brief PVarDialog::help + * @brief Displays help information about variable definition syntax. + * + * Shows a message box explaining the syntax for defining variables: + * - Basic syntax: var = + * - Identifiers are prefixed with '$' (e.g., $sigma) + * - Expressions can use standard mathematical functions + * - Example: var sigSC = pow(abs(pow($sigma,2.0)-pow(0.11,2.0)),0.5) */ void PVarDialog::help() { @@ -233,8 +267,12 @@ void PVarDialog::help() //-------------------------------------------------------------------------- /** - * @brief PVarDialog::showVarNames. Show a variable name dialog for a given - * selected collection. + * @brief Displays variable names from the selected collection. + * + * Shows a PShowVarNameDialog containing all variable names from the currently + * selected collection. Only one collection can be displayed at a time. + * Displays error messages if no collection is selected, multiple collections + * are selected, or if an invalid collection index is encountered. */ void PVarDialog::showVarNames() { @@ -262,9 +300,16 @@ void PVarDialog::showVarNames() //-------------------------------------------------------------------------- /** - * @brief PVarDialog::basic_check. Carry out basic checks before feeding it - * to the parser. - * @return true on success + * @brief Performs basic validation checks on variable definitions. + * + * Validates the following: + * - Input is not empty + * - At least one collection is selected + * - At least one 'var' definition is present + * - Each 'var' keyword is followed by a variable name + * - For each variable, a corresponding error variable (with 'Err' suffix) exists + * + * @return true if all basic checks pass, false otherwise (with error message displayed) */ bool PVarDialog::basic_check() { @@ -313,10 +358,17 @@ bool PVarDialog::basic_check() //-------------------------------------------------------------------------- /** - * @brief PVarDialog::var_consistency_check. Variable consistency checks. For - * instance it is checked that for each variable there is also the corresponding - * error variable defined. - * @return true on success + * @brief Validates that all identifiers exist in selected collections. + * + * Collects all identifiers (prefixed with '$') and variable names from the + * variable definition string. For each identifier, checks that it either: + * 1. Is a variable being defined in the current definition string, or + * 2. Exists as a variable in one of the selected collections + * + * Handles both regular identifiers and error identifiers (ending with 'Err'). + * Displays error message if any identifier is not found in selected collections. + * + * @return true if all identifiers are valid, false otherwise (with error message displayed) */ bool PVarDialog::var_consistency_check() { @@ -404,10 +456,15 @@ bool PVarDialog::var_consistency_check() //-------------------------------------------------------------------------- /** - * @brief PVarDialog::collectVarNames. Collect variable names from edit variable. - * @param list input list - * @param ok true if ok - * @return return variable list + * @brief Collects all variable names from a tokenized string list. + * + * Scans the input list for 'var' keywords and extracts the following token + * as the variable name. Sets the ok flag to false if a 'var' keyword is + * found at the end of the list without a following variable name. + * + * @param list reference to a tokenized string list containing variable definitions + * @param ok reference to boolean flag; set to true if all 'var' keywords have associated names, false otherwise + * @return QStringList containing all collected variable names */ QStringList PVarDialog::collectVarNames(QStringList &list, bool &ok) { @@ -430,10 +487,16 @@ QStringList PVarDialog::collectVarNames(QStringList &list, bool &ok) //-------------------------------------------------------------------------- /** - * @brief PVarDialog::hasErrorDef. Check for error definition - * @param varNames variable name list - * @param name failed variable name - * @return true on success + * @brief Checks that each variable has a corresponding error definition. + * + * For every variable name in the list that doesn't contain 'Err', checks + * that a corresponding variable with an 'Err' suffix exists in the list. + * If any variable lacks its error counterpart, the variable name is stored + * in the name parameter. + * + * @param varNames reference to a list of variable names to validate + * @param name reference to QString that will hold the name of the first variable without an error definition + * @return true if all non-error variables have corresponding error definitions, false otherwise */ bool PVarDialog::hasErrorDef(QStringList &varNames, QString &name) { diff --git a/src/musredit_qt6/mupp/PVarDialog.h b/src/musredit_qt6/mupp/PVarDialog.h index 2960bbb70..3074f7377 100644 --- a/src/musredit_qt6/mupp/PVarDialog.h +++ b/src/musredit_qt6/mupp/PVarDialog.h @@ -40,64 +40,151 @@ //----------------------------------------------------------------------------- /** - * @brief The PCollInfo struct + * @brief The PCollInfo struct holds collection information. + * + * This structure stores the name of a collection and a list of all variable + * names contained within that collection. It is used to pass collection + * metadata to various dialogs and functions. */ struct PCollInfo { - QString fCollName; ///< collection name + QString fCollName; ///< collection name (may include path) QStringList fVarName; ///< variable names of the given collection }; //----------------------------------------------------------------------------- /** - * @brief The PShowVarNameDialog class. Class used to create a show variable - * name dialog. + * @brief The PShowVarNameDialog class displays variable names from a collection. + * + * This dialog shows all variable names contained in a selected collection, + * displaying them as an indexed list. It provides a simple interface for + * users to browse through available variables in a collection. */ class PShowVarNameDialog : public QDialog { Q_OBJECT public: + /** + * @brief Constructor for PShowVarNameDialog. + * @param info reference to a PCollInfo structure containing the collection name and variable names to display + */ PShowVarNameDialog(PCollInfo &info); }; //----------------------------------------------------------------------------- /** - * @brief The PVarDialog class + * @brief The PVarDialog class provides a GUI for defining custom variables. + * + * This dialog allows users to define custom variables based on existing + * variables from selected collections. Variables are defined using expressions + * that can reference collection variables as identifiers (prefixed with '$'). + * The dialog validates that both a variable and its corresponding error variable + * (suffixed with 'Err') are defined, and checks that all identifiers exist in + * the selected collections. + * + * Example variable definition: + * @code + * var sigSC = pow(abs(pow($sigma,2.0)-pow(0.11,2.0)),0.5) + * var sigSCErr = + * @endcode */ class PVarDialog : public QDialog { Q_OBJECT public: + /** + * @brief Constructor for PVarDialog. + * @param collection_list vector of PCollInfo structures containing all available collections + * @param darkTheme flag indicating whether to use dark theme icons (true) or plain icons (false) + * @param parent optional parent widget pointer + * @param f optional window flags for the dialog + */ PVarDialog(QVector collection_list, bool darkTheme, QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags()); private: - std::unique_ptr fVarEdit; - std::unique_ptr fCollectionView; - std::unique_ptr fCancel; - std::unique_ptr fAdd; - std::unique_ptr fCheck; - std::unique_ptr fHelp; - std::unique_ptr fShowVarName; + std::unique_ptr fVarEdit; ///< text editor for variable definitions + std::unique_ptr fCollectionView; ///< list widget displaying available collections + std::unique_ptr fCancel; ///< cancel button to reject the dialog + std::unique_ptr fAdd; ///< add button to add variables to mupp GUI + std::unique_ptr fCheck; ///< check button to validate variable definitions + std::unique_ptr fHelp; ///< help button to display syntax information + std::unique_ptr fShowVarName; ///< button to show variable names from selected collection - QVector fCollList; + QVector fCollList; ///< vector holding all collection information + /** + * @brief Performs basic validation checks on variable definitions. + * @return true if basic checks pass, false otherwise + */ bool basic_check(); + + /** + * @brief Validates that all identifiers exist in selected collections. + * + * Checks that every identifier (prefixed with '$') used in the variable + * definitions exists either as a variable being defined or as a variable + * in one of the selected collections. + * @return true if all identifiers are valid, false otherwise + */ bool var_consistency_check(); + + /** + * @brief Collects all variable names from a tokenized string list. + * @param list reference to a tokenized string list containing variable definitions + * @param ok reference to a boolean flag indicating success or failure + * @return QStringList containing all collected variable names + */ QStringList collectVarNames(QStringList &list, bool& ok); + + /** + * @brief Checks that each variable has a corresponding error definition. + * + * For every variable name that doesn't end with 'Err', checks that a + * corresponding variable with 'Err' suffix exists. + * @param varNames reference to a list of variable names to check + * @param name reference to QString that will hold the name of the first variable without an error definition + * @return true if all variables have error definitions, false otherwise + */ bool hasErrorDef(QStringList &varNames, QString& name); private slots: + /** + * @brief Slot to validate variable definitions and emit check_request signal. + */ void check(); + + /** + * @brief Slot to validate and add variable definitions, emitting add_request signal. + */ void add(); + + /** + * @brief Slot to display help information about variable syntax. + */ void help(); + + /** + * @brief Slot to show a dialog displaying variable names from the selected collection. + */ void showVarNames(); signals: + /** + * @brief Signal emitted when user requests to check variable definitions. + * @param varStr the complete variable definition string from the text editor + * @param idx vector of indices indicating which collections are selected + */ void check_request(QString varStr, QVector idx); + + /** + * @brief Signal emitted when user requests to add variable definitions. + * @param varStr the complete variable definition string from the text editor + * @param idx vector of indices indicating which collections are selected + */ void add_request(QString varStr, QVector idx); };