diff --git a/src/musredit_qt6/musredit/PChangeDefaultPathsDialog.cpp b/src/musredit_qt6/musredit/PChangeDefaultPathsDialog.cpp index f7e115c1b..7d65a3a72 100644 --- a/src/musredit_qt6/musredit/PChangeDefaultPathsDialog.cpp +++ b/src/musredit_qt6/musredit/PChangeDefaultPathsDialog.cpp @@ -27,6 +27,20 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PChangeDefaultPathsDialog.cpp + * @brief Implementation of classes for managing default data file search paths. + * @details This file implements the PDefaultPathsXMLParser, PDefaultPaths, and + * PChangeDefaultPathsDialog classes that together provide functionality for + * reading, displaying, editing, and saving the default search paths for muon + * data files. + * + * @author Andreas Suter + * @date 2010-2025 + * @copyright Copyright (C) 2010-2025 by Andreas Suter + * @license GNU General Public License v2 or later + */ + #include #include #include @@ -39,12 +53,19 @@ #include "PChangeDefaultPathsDialog.h" +//++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +// Implementation of PDefaultPathsXMLParser //++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ /** - *

XML Parser class for the musrfit administration file. + * @brief Constructs an XML parser for reading default data paths. * - * \param fln file name of the musredit startup xml-file - * @param defaultPaths + * @details Opens and parses the specified XML configuration file to extract + * \ elements. The parsed paths are stored in the provided + * PDefaultPaths object. After construction, call isValid() to check if + * parsing succeeded. + * + * @param fln Full path to the musrfit_startup.xml configuration file. + * @param defaultPaths Pointer to the PDefaultPaths object to populate with parsed paths. */ PDefaultPathsXMLParser::PDefaultPathsXMLParser(const QString& fln, PDefaultPaths *defaultPaths) : fDefaultPaths(defaultPaths) @@ -62,11 +83,17 @@ PDefaultPathsXMLParser::PDefaultPathsXMLParser(const QString& fln, PDefaultPaths //-------------------------------------------------------------------------- /** - *

parse the musrfit startup xml-file. + * @brief Parse the XML configuration file for data paths. * - * \param device QFile object of the musrfit startup xml-file + * @details Reads the XML file using Qt's QXmlStreamReader, processing elements + * sequentially. Recognized \ elements have their content extracted + * and added to the associated PDefaultPaths object. * - * @return true on success, false otherwise + * @param device QIODevice (typically a QFile) opened for reading. + * + * @return true if parsing completed without XML errors, false otherwise. + * On error, displays a message box with error details including + * line and column numbers. */ bool PDefaultPathsXMLParser::parse(QIODevice *device) { @@ -101,7 +128,12 @@ bool PDefaultPathsXMLParser::parse(QIODevice *device) //-------------------------------------------------------------------------- /** - *

Routine called at the beginning of the XML parsing process. + * @brief Handler called at the start of XML document parsing. + * + * @details This method is invoked when the parser encounters the beginning + * of the XML document. Currently performs no initialization. + * + * @return Always returns true. */ bool PDefaultPathsXMLParser::startDocument() { @@ -111,8 +143,13 @@ bool PDefaultPathsXMLParser::startDocument() //-------------------------------------------------------------------------- /** - *

Routine called when a new XML tag is found. Here it is used - * to set a tag for filtering afterwards the content. + * @brief Handler called when an XML start element is encountered. + * + * @details Sets the internal keyword flag based on the element name. + * Currently only recognizes \ elements; all other elements + * are ignored. + * + * @return Always returns true. */ bool PDefaultPathsXMLParser::startElement() { @@ -127,8 +164,12 @@ bool PDefaultPathsXMLParser::startElement() //-------------------------------------------------------------------------- /** - *

Routine called when the end XML tag is found. It is used to - * put the filtering tag to 'empty'. + * @brief Handler called when an XML end element is encountered. + * + * @details Resets the keyword flag to eEmpty after finishing processing + * of an element. + * + * @return Always returns true. */ bool PDefaultPathsXMLParser::endElement() { @@ -139,8 +180,13 @@ bool PDefaultPathsXMLParser::endElement() //-------------------------------------------------------------------------- /** - *

This routine delivers the content of an XML tag. It fills the - * content into the load data structure. + * @brief Handler for XML element character content. + * + * @details Processes the text content of the current XML element. If the + * current element is a \, the content (directory path) is + * appended to the PDefaultPaths object. + * + * @return Always returns true. */ bool PDefaultPathsXMLParser::characters() { @@ -161,17 +207,37 @@ bool PDefaultPathsXMLParser::characters() //-------------------------------------------------------------------------- /** - *

Called at the end of the XML parse process. It checks if default paths - * contain system variables, and if so expand them for the further use. + * @brief Handler called at the end of XML document parsing. + * + * @details This method is invoked when the parser reaches the end of the + * XML document. Currently performs no post-processing. + * + * @return Always returns true. */ bool PDefaultPathsXMLParser::endDocument() { return true; } +//++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +// Implementation of PDefaultPaths //++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ /** - * @brief PDefaultPaths::PDefaultPaths + * @brief Constructs a PDefaultPaths object and loads paths from configuration. + * + * @details Searches for the musrfit_startup.xml configuration file in the + * standard search locations, then parses it to extract default data paths. + * + * @par Search Order: + * -# Current working directory (./musrfit_startup.xml) + * -# User's home directory ($HOME/.musrfit/musrfit_startup.xml) + * -# MUSRFITPATH environment variable ($MUSRFITPATH/musrfit_startup.xml) + * -# ROOT installation ($ROOTSYS/bin/musrfit_startup.xml) + * + * After construction, call isValid() to check if configuration was loaded + * successfully. + * + * @note Displays an error dialog if parsing fails. */ PDefaultPaths::PDefaultPaths() : QObject() { @@ -211,11 +277,23 @@ PDefaultPaths::PDefaultPaths() : QObject() } } +//++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +// Implementation of PChangeDefaultPathsDialog //++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ /** - *

Constructor. + * @brief Constructs the default paths dialog. * - * \param fAdmin keeps all the needed flags + * @details Initializes the dialog by: + * -# Creating a PDefaultPaths object to load current paths + * -# Setting up the UI from the .ui file + * -# Populating the list widget with existing paths + * -# Connecting button signals to handler slots + * + * The dialog is created as modal, blocking interaction with other windows + * until closed. + * + * @note If path loading fails (PDefaultPaths invalid), the constructor + * returns early without fully initializing the dialog. */ PChangeDefaultPathsDialog::PChangeDefaultPathsDialog() { @@ -243,7 +321,15 @@ PChangeDefaultPathsDialog::PChangeDefaultPathsDialog() //---------------------------------------------------------------------------------------------------- /** - * @brief PChangeDefaultPathsDialog::addItem + * @brief Slot to add a new directory path to the list. + * + * @details Opens a directory selection dialog allowing the user to browse + * for and select a directory. If the user selects a directory (doesn't cancel), + * the path is inserted into the list widget immediately after the currently + * selected item. + * + * @note Uses QFileDialog configured to show only directories and not resolve + * symbolic links. */ void PChangeDefaultPathsDialog::addItem() { @@ -265,7 +351,10 @@ void PChangeDefaultPathsDialog::addItem() //---------------------------------------------------------------------------------------------------- /** - * @brief PChangeDefaultPathsDialog::deleteItem + * @brief Slot to remove the currently selected path from the list. + * + * @details Removes the currently selected item from the list widget and + * frees its memory. If no item is selected, the method has no effect. */ void PChangeDefaultPathsDialog::deleteItem() { @@ -276,7 +365,20 @@ void PChangeDefaultPathsDialog::deleteItem() //---------------------------------------------------------------------------------------------------- /** - * @brief PChangeDefaultPathsDialog::saveDefaultPathList + * @brief Slot to save the modified path list to the configuration file. + * + * @details Persists the current list of data paths to the musrfit_startup.xml + * configuration file. The method: + * -# Reads the existing configuration file content + * -# Removes all existing \ elements + * -# Inserts the current list widget entries as new \ elements + * -# Writes the modified content back to the file + * + * If no \ elements existed in the original file, the new paths + * are inserted just before the closing \ tag. + * + * @note This slot is connected to the dialog's accept signal, so it is called + * automatically when the user clicks OK. */ void PChangeDefaultPathsDialog::saveDefaultPathList() { diff --git a/src/musredit_qt6/musredit/PChangeDefaultPathsDialog.h b/src/musredit_qt6/musredit/PChangeDefaultPathsDialog.h index 3d9280698..14fad6d15 100644 --- a/src/musredit_qt6/musredit/PChangeDefaultPathsDialog.h +++ b/src/musredit_qt6/musredit/PChangeDefaultPathsDialog.h @@ -27,6 +27,27 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PChangeDefaultPathsDialog.h + * @brief Dialog for managing default data file search paths in musredit. + * @details This header defines classes for managing the default search paths + * used by musrfit to locate data files. The paths are stored in the + * \c musrfit_startup.xml configuration file and can be edited through + * a graphical dialog. + * + * The file contains three main classes: + * - PDefaultPathsXMLParser: Parses \ elements from XML + * - PDefaultPaths: Stores and manages the list of default paths + * - PChangeDefaultPathsDialog: Qt dialog for user interaction + * + * @author Andreas Suter + * @date 2010-2025 + * @copyright Copyright (C) 2010-2025 by Andreas Suter + * @license GNU General Public License v2 or later + * + * @see PAdmin For main configuration management + */ + #ifndef _PCHANGEDEFAULTPATHSDIALOG_H_ #define _PCHANGEDEFAULTPATHSDIALOG_H_ @@ -42,16 +63,48 @@ class PDefaultPaths; //--------------------------------------------------------------------------- +/** + * @class PDefaultPathsXMLParser + * @brief XML parser for extracting default data paths from configuration. + * + * @details This class parses the \c musrfit_startup.xml configuration file + * to extract the \ elements that define default search directories + * for muon data files. The parser uses Qt's QXmlStreamReader for efficient + * streaming XML parsing. + * + * @par XML Format: + * The parser expects elements in the form: + * @code{.xml} + * /path/to/data/directory + * @endcode + * + * @see PDefaultPaths The class that stores the parsed paths + */ class PDefaultPathsXMLParser { public: PDefaultPathsXMLParser(const QString &fln, PDefaultPaths *defaultPaths); + + /** + * @brief Virtual destructor. + */ virtual ~PDefaultPathsXMLParser() {} + /** + * @brief Check if the XML file was parsed successfully. + * @return true if parsing succeeded, false otherwise. + */ virtual bool isValid() { return fValid; } private: - enum EAdminKeyWords {eEmpty, eDataPath}; + /** + * @enum EAdminKeyWords + * @brief Keywords for identifying XML elements during parsing. + */ + enum EAdminKeyWords { + eEmpty, ///< No element currently being processed. + eDataPath ///< Processing a \ element. + }; bool parse(QIODevice *device); bool startDocument(); @@ -60,33 +113,99 @@ class PDefaultPathsXMLParser bool characters(); bool endDocument(); - QXmlStreamReader fXml; ///< xml stream reader object - bool fValid; ///< flag showing if XML read has been successful - EAdminKeyWords fKeyWord; ///< key word tag to know how to handle the content - PDefaultPaths *fDefaultPaths; ///< keeps the default search paths for the data files + QXmlStreamReader fXml; ///< Qt XML stream reader for parsing. + bool fValid; ///< Flag indicating successful parsing. + EAdminKeyWords fKeyWord; ///< Current element type being processed. + PDefaultPaths *fDefaultPaths; ///< Pointer to the object storing parsed paths. }; //--------------------------------------------------------------------------- +/** + * @class PDefaultPaths + * @brief Container class for managing default data file search paths. + * + * @details This class loads and stores the list of default directory paths + * where musrfit searches for muon data files. The paths are read from + * the \c musrfit_startup.xml configuration file during construction. + * + * The configuration file is searched in the following order: + * -# Current working directory + * -# \c $HOME/.musrfit/ + * -# \c $MUSRFITPATH/ + * -# \c $ROOTSYS/bin/ + * + * @see PDefaultPathsXMLParser For the XML parsing implementation + * @see PChangeDefaultPathsDialog For the user interface to edit paths + */ class PDefaultPaths : public QObject { public: PDefaultPaths(); + + /** + * @brief Virtual destructor. + */ virtual ~PDefaultPaths() {} + /** + * @brief Check if the configuration was loaded successfully. + * @return true if valid, false if loading failed. + */ virtual bool isValid() { return fValid; } + + /** + * @brief Add a new path to the default paths list. + * @param str Directory path to add. + */ virtual void appendDefaultPath(QString str) { fDefaultPath << str; } + + /** + * @brief Get the list of default search paths. + * @return Pointer to the QStringList containing all paths. + */ virtual QStringList *getDefaultPathList() { return &fDefaultPath; } + + /** + * @brief Get the path to the configuration file being used. + * @return Full path to the musrfit_startup.xml file. + */ virtual QString getPrefPathName() { return fPrefPathName; } private: - friend class PDefaultPathsXMLParser; + friend class PDefaultPathsXMLParser; ///< Allow parser to access private members. - bool fValid; - QString fPrefPathName; - QStringList fDefaultPath; + bool fValid; ///< Flag indicating if configuration loaded successfully. + QString fPrefPathName; ///< Full path to the active configuration file. + QStringList fDefaultPath; ///< List of default data file search directories. }; //--------------------------------------------------------------------------- +/** + * @class PChangeDefaultPathsDialog + * @brief Dialog for editing default data file search paths. + * + * @details This dialog provides a graphical interface for users to view, add, + * and remove the default directory paths where musrfit searches for muon + * spin rotation data files. + * + * @par Features: + * - Displays current search paths in a list widget + * - Add new paths via directory browser dialog + * - Delete selected paths from the list + * - Save changes back to the configuration file + * + * The dialog is modal and changes are persisted to musrfit_startup.xml + * when the user accepts the dialog (clicks OK). + * + * @par UI Elements: + * The dialog UI is defined in PChangeDefaultPathsDialog.ui and includes: + * - A list widget (fSearchPath_listWidget) showing current paths + * - Add button (fAdd_pushButton) to add new directories + * - Delete button (fDelete_pushButton) to remove selected path + * - Standard OK/Cancel button box + * + * @see PDefaultPaths For path storage and loading + */ class PChangeDefaultPathsDialog : public QDialog, private Ui::PChangeDefaultPathsDialog { Q_OBJECT @@ -95,12 +214,23 @@ class PChangeDefaultPathsDialog : public QDialog, private Ui::PChangeDefaultPath PChangeDefaultPathsDialog(); private slots: + /** + * @brief Remove the currently selected path from the list. + */ void deleteItem(); + + /** + * @brief Add a new directory path via file browser dialog. + */ void addItem(); + + /** + * @brief Save the modified path list to the configuration file. + */ void saveDefaultPathList(); private: - std::unique_ptr fDefaultPath; + std::unique_ptr fDefaultPath; ///< Manages the default paths data. }; #endif // _PCHANGEDEFAULTPATHSDIALOG_H_