improve the doxygen docu of PChangeDefaultPathDialog.* (musredit_qt6).
This commit is contained in:
@@ -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 <QString>
|
||||
#include <QStringView>
|
||||
#include <QMessageBox>
|
||||
@@ -39,12 +53,19 @@
|
||||
|
||||
#include "PChangeDefaultPathsDialog.h"
|
||||
|
||||
//++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
// Implementation of PDefaultPathsXMLParser
|
||||
//++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
/**
|
||||
* <p>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
|
||||
* \<data_path\> 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
|
||||
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>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 \<data_path\> 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)
|
||||
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>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()
|
||||
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>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 \<data_path\> elements; all other elements
|
||||
* are ignored.
|
||||
*
|
||||
* @return Always returns true.
|
||||
*/
|
||||
bool PDefaultPathsXMLParser::startElement()
|
||||
{
|
||||
@@ -127,8 +164,12 @@ bool PDefaultPathsXMLParser::startElement()
|
||||
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>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()
|
||||
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>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 \<data_path\>, the content (directory path) is
|
||||
* appended to the PDefaultPaths object.
|
||||
*
|
||||
* @return Always returns true.
|
||||
*/
|
||||
bool PDefaultPathsXMLParser::characters()
|
||||
{
|
||||
@@ -161,17 +207,37 @@ bool PDefaultPathsXMLParser::characters()
|
||||
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>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
|
||||
//++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
/**
|
||||
* <p>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 \<data_path\> elements
|
||||
* -# Inserts the current list widget entries as new \<data_path\> elements
|
||||
* -# Writes the modified content back to the file
|
||||
*
|
||||
* If no \<data_path\> elements existed in the original file, the new paths
|
||||
* are inserted just before the closing \</musrfit\> 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()
|
||||
{
|
||||
|
||||
@@ -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 \<data_path\> 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 \<data_path\> 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}
|
||||
* <data_path>/path/to/data/directory</data_path>
|
||||
* @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 \<data_path\> 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<PDefaultPaths> fDefaultPath;
|
||||
std::unique_ptr<PDefaultPaths> fDefaultPath; ///< Manages the default paths data.
|
||||
};
|
||||
|
||||
#endif // _PCHANGEDEFAULTPATHSDIALOG_H_
|
||||
|
||||
Reference in New Issue
Block a user