diff --git a/src/musredit_qt6/musredit/PAdmin.cpp b/src/musredit_qt6/musredit/PAdmin.cpp index 3809672c8..821b8599d 100644 --- a/src/musredit_qt6/musredit/PAdmin.cpp +++ b/src/musredit_qt6/musredit/PAdmin.cpp @@ -27,6 +27,22 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PAdmin.cpp + * @brief Implementation of the PAdmin and PAdminXMLParser classes. + * @details This file contains the implementation of the musredit administration + * system, including: + * - XML parsing of the musredit_startup.xml configuration file + * - Configuration loading and saving + * - Recent files management + * - Default configuration file creation + * + * @author Andreas Suter + * @date 2010-2025 + * @copyright Copyright (C) 2010-2025 by Andreas Suter + * @license GNU General Public License v2 or later + */ + #include #include @@ -49,10 +65,18 @@ // implementation of PAdminXMLParser class //-------------------------------------------------------------------------- /** - *

XML Parser class for the musredit administration file. + * @brief Constructs an XML parser for the musredit configuration file. * - * \param fln file name of the musredit startup xml-file - * \param admin pointer to an admin class instance. + * @details Creates a parser instance and immediately parses the specified XML file. + * If the file is missing or corrupted, the user is prompted to create a default + * configuration file. After parsing completes, the validity can be checked + * using the isValid() method. + * + * @param fln Full path to the musredit_startup.xml configuration file. + * @param admin Pointer to the PAdmin object that will be populated with parsed data. + * + * @note If the configuration file cannot be opened or is empty, a warning dialog + * is displayed offering to create a default configuration file. */ PAdminXMLParser::PAdminXMLParser(const QString& fln, PAdmin *admin) : fAdmin(admin) { @@ -74,11 +98,16 @@ PAdminXMLParser::PAdminXMLParser(const QString& fln, PAdmin *admin) : fAdmin(adm //-------------------------------------------------------------------------- /** - *

parse the musredit startup xml-file. + * @brief Parse the XML configuration file. * - * \param device QFile object of the musredit startup xml-file + * @details Reads and processes the musredit_startup.xml file using Qt's + * QXmlStreamReader. The parser processes elements sequentially, calling + * appropriate handler methods for start elements, character data, and end elements. * - * @return true on success, false otherwise + * @param device QIODevice (typically QFile) opened for reading the XML file. + * + * @return true if parsing completed without XML errors, false otherwise. + * On failure, an error dialog is displayed with line/column information. */ bool PAdminXMLParser::parse(QIODevice *device) { @@ -113,7 +142,13 @@ bool PAdminXMLParser::parse(QIODevice *device) //-------------------------------------------------------------------------- /** - *

Routine called at the beginning of the XML parsing process. + * @brief Handler called at the beginning of XML document parsing. + * + * @details This method is invoked when the XML parser encounters the start + * of the document. Currently performs no initialization as all state is + * set up in the constructor. + * + * @return Always returns true. */ bool PAdminXMLParser::startDocument() { @@ -123,8 +158,15 @@ bool PAdminXMLParser::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 Maps the XML element name to an internal keyword enumeration (EAdminKeyWords) + * for subsequent character data processing. Also handles initialization of the + * PTheory structure when a \ element begins. + * + * @return Always returns true. + * + * @see EAdminKeyWords For the list of recognized XML element tags. */ bool PAdminXMLParser::startElement() { @@ -257,9 +299,13 @@ bool PAdminXMLParser::startElement() //-------------------------------------------------------------------------- /** - *

Routine called when the end XML tag is found. It is used to - * put the filtering tag to 'empty'. It also resets the fFunc flag in case - * the entry was a theory function. + * @brief Handler called when an XML end element is encountered. + * + * @details Resets the current keyword to eEmpty after element processing completes. + * For \ end tags, finalizes the theory item by adding it to the + * PAdmin's theory collection and resetting the function parsing flag. + * + * @return Always returns true. */ bool PAdminXMLParser::endElement() { @@ -277,8 +323,17 @@ bool PAdminXMLParser::endElement() //-------------------------------------------------------------------------- /** - *

This routine delivers the content of an XML tag. It fills the - * content into the load data structure. + * @brief Handler for XML character data (element content). + * + * @details Processes the text content of the current XML element based on the + * previously set keyword from startElement(). Routes the content to the + * appropriate PAdmin setter method or stores it in the temporary theory item + * structure when parsing function definitions. + * + * Boolean values in the XML use "y" for true and any other value for false. + * + * @return true on successful processing, false if a required conversion fails + * (e.g., invalid integer in params element). */ bool PAdminXMLParser::characters() { @@ -584,8 +639,15 @@ bool PAdminXMLParser::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 Performs post-processing after all XML elements have been parsed. + * Expands any environment variables (e.g., \c $HOME, \c $ROOTSYS) found in + * path settings to their full directory paths. + * + * @return Always returns true. + * + * @see expandPath() For the environment variable expansion implementation. */ bool PAdminXMLParser::endDocument() { @@ -618,7 +680,15 @@ bool PAdminXMLParser::endDocument() //-------------------------------------------------------------------------- /** - *

Dumps the content of the admin class. For debugging purposes only. + * @brief Dump all configuration values to stdout for debugging. + * + * @details Outputs the complete contents of the PAdmin object to standard output + * in a human-readable format. This includes general settings, recent files, + * help URLs, font settings, MSR file defaults, msr2data parameters, and all + * registered theory functions. + * + * @note This method is intended for debugging purposes only and is typically + * disabled in production builds. */ void PAdminXMLParser::dump() { @@ -702,9 +772,18 @@ void PAdminXMLParser::dump() //-------------------------------------------------------------------------- /** - *

Expands system variables to full path, e.g. $HOME -> \home\user + * @brief Expand environment variables in a path string. * - * \param str path string with none expanded system variables. + * @details Parses the input path and replaces any environment variable references + * (prefixed with \c $) with their actual values from the system environment. + * For example, \c $HOME/documents becomes \c /home/user/documents. + * + * @param str Path string potentially containing environment variable references. + * + * @return The expanded path string with all environment variables resolved. + * Returns an empty string if any referenced variable is not found or empty. + * + * @note Displays a warning dialog if an environment variable cannot be resolved. */ QString PAdminXMLParser::expandPath(const QString &str) { @@ -747,8 +826,21 @@ QString PAdminXMLParser::expandPath(const QString &str) // implementation of PAdmin class //-------------------------------------------------------------------------- /** - *

Initializes that PAdmin object, and calls the XML parser which feeds - * the object variables. + * @brief Constructs the PAdmin object and loads configuration. + * + * @details Initializes all member variables to default values, then searches for + * and loads the musredit_startup.xml configuration file. The search order is: + * -# Current working directory + * -# \c $HOME/.musrfit/musredit/ + * -# \c $MUSRFITPATH/ + * -# \c $ROOTSYS/bin/ + * + * If no configuration file is found, a default one is created in the user's + * home directory. After loading, the constructor verifies that the musrfit + * executable can be found and that required environment variables are set. + * + * @note Displays error dialogs if musrfit cannot be found or if required + * environment variables (ROOTSYS, MUSRFITPATH) are not set. */ PAdmin::PAdmin() : QObject() { @@ -835,10 +927,27 @@ PAdmin::PAdmin() : QObject() //-------------------------------------------------------------------------- /** - *

returns the help url corresponding the the tag. + * @brief Get the help URL for a specific documentation section. * - * \param tag to map the help url. At the moment the following tags should be present: - * main, title, parameters, theory, functions, run, command, fourier, plot, statistic + * @details Retrieves the URL for online help corresponding to the given tag. + * The URLs are loaded from the configuration file and map to sections of + * the musrfit user manual. + * + * @param tag Section identifier. Supported tags include: + * - \c main - Main musrfit documentation + * - \c title - TITLE block documentation + * - \c parameters - FITPARAMETER block documentation + * - \c theory - THEORY block documentation + * - \c functions - FUNCTIONS block documentation + * - \c run - RUN block documentation + * - \c command - COMMANDS block documentation + * - \c fourier - FOURIER block documentation + * - \c plot - PLOT block documentation + * - \c statistic - STATISTIC block documentation + * - \c msr2data - msr2data tool documentation + * - \c musrFT - musrFT tool documentation + * + * @return The URL string for the requested help section, or empty string if tag not found. */ QString PAdmin::getHelpUrl(QString tag) { @@ -847,9 +956,17 @@ QString PAdmin::getHelpUrl(QString tag) //-------------------------------------------------------------------------- /** - *

returns a theory item from position idx. If idx is out of the range, a null pointer is returned. + * @brief Get a theory function definition by index. * - * \param idx position of the theory item. + * @details Retrieves a pointer to a PTheory structure containing the definition + * of a theory function. Theory functions are used for fitting muon spin + * rotation/relaxation data. + * + * @param idx Zero-based index of the theory item in the collection. + * + * @return Pointer to the PTheory structure, or nullptr if idx is out of range. + * + * @see getTheoryCounts() To get the number of available theory items. */ PTheory* PAdmin::getTheoryItem(const unsigned int idx) { @@ -861,10 +978,17 @@ PTheory* PAdmin::getTheoryItem(const unsigned int idx) //-------------------------------------------------------------------------- /** - *

returns the recent path-file name at position idx. If idx is out of scope, - * an empty string is returned. + * @brief Get a recent file path by index. * - * \param idx index of the recent path-file name to be retrieved. + * @details Retrieves the full path of a recently opened file from the recent + * files list. The list is ordered with most recently opened files first. + * + * @param idx Zero-based index into the recent files list. + * + * @return The full path to the recent file, or empty string if idx is out of range. + * + * @see getNumRecentFiles() To get the number of recent files. + * @see addRecentFile() To add a new file to the recent list. */ QString PAdmin::getRecentFile(int idx) { @@ -876,11 +1000,15 @@ QString PAdmin::getRecentFile(int idx) //-------------------------------------------------------------------------- /** - *

set the help url, addressed via a tag. At the moment the following tags should be present: - * main, title, parameters, theory, functions, run, command, fourier, plot, statistic, msr2data + * @brief Set the help URL for a documentation section. * - * \param tag to address the help url - * \param url help url corresponding to the tag. + * @details Associates a URL with a documentation section tag. This is typically + * called during XML configuration parsing to load help URL mappings. + * + * @param tag Section identifier (e.g., "main", "theory", "parameters"). + * @param url Full URL to the online documentation for this section. + * + * @see getHelpUrl() To retrieve URLs by tag. */ void PAdmin::setHelpUrl(const QString tag, const QString url) { @@ -889,11 +1017,17 @@ void PAdmin::setHelpUrl(const QString tag, const QString url) //-------------------------------------------------------------------------- /** - *

Loads the preference file fln. + * @brief Load configuration from an XML file. * - * return: 1 on success, 0 otherwise + * @details Parses the specified musredit_startup.xml file and populates this + * PAdmin instance with the configuration values. Uses PAdminXMLParser for + * the actual XML parsing. * - * \param fln path-file name of the preference file to be loaded. + * @param fln Full path to the configuration XML file to load. + * + * @return 1 on successful load, 0 if the file doesn't exist or parsing fails. + * + * @note Displays an error dialog if parsing fails or the file is not found. */ int PAdmin::loadPrefs(QString fln) { @@ -916,11 +1050,21 @@ int PAdmin::loadPrefs(QString fln) //-------------------------------------------------------------------------- /** - *

Save the preference file pref_fln. + * @brief Save current configuration to an XML file. * - * return: 1 on success, 0 otherwise + * @details Saves modified preferences (timeout, flags, font settings) to the + * configuration file. The method reads the existing XML file, updates the + * relevant values in-place, and writes the result to the specified output file. * - * \param pref_fln preference path-file name + * If a local musredit_startup.xml exists in the current directory, it is used + * as the source; otherwise, the master configuration file is used. + * + * @param pref_fln Full path to the output configuration file. + * + * @return 1 on successful save, 0 if the file cannot be written. + * + * @note Only preference values are saved; structure elements like theory + * definitions are preserved from the source file. */ int PAdmin::savePrefs(QString pref_fln) { @@ -1055,9 +1199,16 @@ int PAdmin::savePrefs(QString pref_fln) //-------------------------------------------------------------------------- /** - *

Add recent path-file name to the internal ring-buffer. + * @brief Add a file to the recent files list. * - * \param str recent path-file name to be added + * @details Adds the specified file path to the front of the recent files list. + * If the file is already in the list, it is not added again (no duplicates). + * The list is maintained as a ring buffer with a maximum of MAX_RECENT_FILES entries. + * + * @param str Full path to the file to add to the recent list. + * + * @see getRecentFile() To retrieve files from the list. + * @see saveRecentFiles() To persist the list to the configuration file. */ void PAdmin::addRecentFile(const QString str) { @@ -1074,9 +1225,17 @@ void PAdmin::addRecentFile(const QString str) //-------------------------------------------------------------------------- /** - *

Merges the recent file ring buffer into musredit_startup.xml and saves it. - * If a local copy is present it will be saved there, otherwise the master file - * will be used. + * @brief Save the recent files list to the configuration file. + * + * @details Persists the current recent files list to musredit_startup.xml. + * The method reads the existing XML file, removes all existing \ + * entries, inserts the current list, and writes the file back. + * + * If a local musredit_startup.xml exists in the current directory, it is updated; + * otherwise, the master configuration file (fPrefPathName) is used. + * + * @note This method modifies the XML file in-place. If neither a local nor + * master configuration file exists, a warning dialog is displayed. */ void PAdmin::saveRecentFiles() { @@ -1143,7 +1302,18 @@ void PAdmin::saveRecentFiles() //-------------------------------------------------------------------------- /** - * @brief PAdmin::createMusreditStartupFile + * @brief Create a default musredit_startup.xml configuration file. + * + * @details Creates a new configuration file with default settings in the user's + * home directory at \c $HOME/.musrfit/musredit/musredit_startup.xml. + * The method: + * -# Creates the directory structure if it doesn't exist + * -# Reads the default template from internal Qt resources (musredit_startup.xml.in) + * -# Substitutes build-time paths (\@prefix\@, \@DOCDIR\@) with actual values + * -# Adjusts font settings for macOS (Courier New size 16 vs Monospace size 12) + * + * @note Displays an error dialog if the resource template cannot be found or + * the output file cannot be written. */ void PAdmin::createMusreditStartupFile() { diff --git a/src/musredit_qt6/musredit/PAdmin.h b/src/musredit_qt6/musredit/PAdmin.h index 920f8f8d1..c47345df9 100644 --- a/src/musredit_qt6/musredit/PAdmin.h +++ b/src/musredit_qt6/musredit/PAdmin.h @@ -27,6 +27,34 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PAdmin.h + * @brief Administration and configuration management for musredit. + * @details This header defines the classes and structures responsible for managing + * musredit's configuration settings. The configuration is stored in an XML file + * called \c musredit_startup.xml which contains: + * - Executable paths for musrfit tools + * - Editor font settings and window dimensions + * - Default parameters for msr2data operations + * - Theory function definitions with associated pixmaps + * - Online help URL mappings + * - Recently opened file list + * + * The configuration file is searched in the following order: + * -# Current working directory + * -# \c $HOME/.musrfit/musredit/ + * -# \c $MUSRFITPATH/ + * -# \c $ROOTSYS/bin/ + * + * @author Andreas Suter + * @date 2010-2025 + * @copyright Copyright (C) 2010-2025 by Andreas Suter + * @license GNU General Public License v2 or later + * + * @see PAdminXMLParser XML parser for the configuration file + * @see PAdmin Main administration class + */ + #ifndef _PADMIN_H_ #define _PADMIN_H_ @@ -42,33 +70,78 @@ class PAdmin; //--------------------------------------------------------------------------- /** - *

This structure is keeping informations necessary to handle musrfit - * theory functions (see also http://lmu.web.psi.ch/musrfit/user/html/user-manual.html#the-theory-block). + * @struct PTheory + * @brief Structure holding information about a musrfit theory function. + * + * @details This structure contains all necessary information to represent a theory + * function in the musredit GUI. Theory functions are mathematical models used to + * fit muon spin rotation/relaxation data (e.g., exponential relaxation, Gaussian + * Kubo-Toyabe, etc.). + * + * Each theory function has: + * - A unique name identifier used in msr files + * - A human-readable comment/description + * - A short label for GUI display + * - An optional pixmap showing the mathematical formula + * - The number of parameters the function accepts + * + * @see https://lmu.web.psi.ch/musrfit/user/html/user-manual.html#the-theory-block Theory block documentation */ struct PTheory { - QString name; - QString comment; - QString label; - QString pixmapName; - QPixmap pixmap; - int params; + QString name; ///< Internal function name used in msr files (e.g., "asymmetry", "simplExpo"). + QString comment; ///< Human-readable description of the theory function. + QString label; ///< Short label for GUI menus and buttons. + QString pixmapName; ///< Filename of the pixmap image showing the mathematical formula. + QPixmap pixmap; ///< Loaded pixmap image of the mathematical formula. + int params; ///< Number of parameters required by this theory function. }; //--------------------------------------------------------------------------- /** - * PAdminXMLParser is an XML parser class used to handle the musredit startup - * XML-file called musredit_startup.xml. This startup file contains - * necessary informations about executable pathes, online help informations, - * default font sizes, etc. + * @class PAdminXMLParser + * @brief XML parser for the musredit configuration file. + * + * @details This class implements an XML parser using Qt's QXmlStreamReader to parse + * the \c musredit_startup.xml configuration file. The parser extracts all settings + * and populates a PAdmin object with the configuration data. + * + * The XML file structure includes sections for: + * - General settings (timeout, paths, font preferences) + * - Recent files list + * - Help URL mappings + * - MSR file defaults (beamline, institute, file format) + * - msr2data default parameters + * - Theory function definitions + * + * @par Usage Example: + * @code + * PAdmin admin; + * PAdminXMLParser parser("musredit_startup.xml", &admin); + * if (parser.isValid()) { + * // Configuration loaded successfully + * } + * @endcode + * + * @see PAdmin The administration class that stores parsed configuration */ class PAdminXMLParser { public: PAdminXMLParser(const QString &fln, PAdmin*); + /** + * @brief Check if the XML file was parsed successfully. + * @return true if parsing was successful, false otherwise. + */ virtual bool isValid() { return fValid; } private: + /** + * @enum EAdminKeyWords + * @brief Enumeration of XML element keywords recognized by the parser. + * @details Each enum value corresponds to an XML element tag in the configuration file. + * The parser uses these to determine how to process element content. + */ enum EAdminKeyWords {eEmpty, eTimeout, eKeepMinuit2Output, eDumpAscii, eDumpRoot, eTitleFromDataFile, eChisqPreRunBlock, eEstimateN0, eYamlOut, eMusrviewShowFourier, eMusrviewShowAvg, eMusrviewShowOneToOne, eEnableMusrT0, @@ -92,142 +165,231 @@ class PAdminXMLParser QString expandPath(const QString&); - 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 - bool fFunc; ///< flag needed to indicate that a new theory function is found - PTheory fTheoryItem; ///< holding the informations necessary for a theory item - PAdmin *fAdmin; ///< a pointer to the main administration class object + QXmlStreamReader fXml; ///< Qt XML stream reader for parsing the configuration file. + bool fValid; ///< Flag indicating whether XML parsing completed successfully. + EAdminKeyWords fKeyWord; ///< Current XML element being processed. + bool fFunc; ///< Flag indicating parser is inside a \ element block. + PTheory fTheoryItem; ///< Temporary storage for theory function data during parsing. + PAdmin *fAdmin; ///< Pointer to the PAdmin object being populated with configuration data. }; //--------------------------------------------------------------------------- /** - * The PAdmin class is handling the informations contained in the XML startup file, - * musredit_startup.xml. This startup file contains - * necessary informations about executable pathes, online help informations, - * default font sizes, etc. The XML parsing is done with the help of the PAdminXMLParser - * class. + * @class PAdmin + * @brief Central administration class for musredit configuration management. + * + * @details The PAdmin class serves as the central repository for all musredit + * configuration settings. It loads configuration from the \c musredit_startup.xml + * file and provides getters/setters for all configurable parameters. + * + * @par Main Responsibilities: + * - Loading and saving configuration to XML files + * - Managing musrfit executable paths + * - Storing editor preferences (font, window size) + * - Tracking recently opened files + * - Managing theory function definitions + * - Storing msr2data default parameters + * - Mapping help URLs for context-sensitive help + * + * @par Configuration File Search Order: + * The constructor searches for \c musredit_startup.xml in: + * -# Current working directory + * -# \c $HOME/.musrfit/musredit/ + * -# \c $MUSRFITPATH/ + * -# \c $ROOTSYS/bin/ + * + * If no configuration file is found, a default one is created in + * \c $HOME/.musrfit/musredit/. + * + * @see PAdminXMLParser For XML parsing implementation + * @see PMsr2DataParam For msr2data parameter structure + * @see PTheory For theory function structure */ class PAdmin : public QObject { public: PAdmin(); - int getTimeout() { return fTimeout; } - QString getFontName() { return fFontName; } - int getFontSize() { return fFontSize; } - QString getExecPath() { return fExecPath; } - QString getDefaultSavePath() { return fDefaultSavePath; } - bool getTitleFromDataFileFlag() { return fTitleFromDataFile; } - bool getMusrviewShowFourierFlag() { return fMusrviewShowFourier; } - bool getMusrviewShowAvgFlag() { return fMusrviewShowAvg; } - bool getMusrviewShowOneToOneFlag() { return fMusrviewShowOneToOne; } - bool getEnableMusrT0Flag() { return fEnableMusrT0; } - bool getYamlOutFlag() { return fYamlOut; } - bool getKeepMinuit2OutputFlag() { return fKeepMinuit2Output; } - bool getDumpAsciiFlag() { return fDumpAscii; } - bool getDumpRootFlag() { return fDumpRoot; } - bool getEstimateN0Flag() { return fEstimateN0; } - bool getChisqPerRunBlockFlag() { return fChisqPreRunBlock; } - bool getIgnoreThemeAutoDetection() { return fIgnoreThemeAutoDetection; } - bool getDarkThemeIconsMenuFlag() { return fDarkThemeIconsMenu; } - bool getDarkThemeIconsToolbarFlag() { return fDarkThemeIconsToolbar; } - int getEditWidth() { return fEditWidth; } - int getEditHeight() { return fEditHeight; } - QString getBeamline() { return fBeamline; } - QString getInstitute() { return fInstitute; } - QString getFileFormat() { return fFileFormat; } - bool getLifetimeCorrectionFlag() { return fLifetimeCorrection; } + /** @name Configuration Getters + * @brief Methods to retrieve current configuration values. + * @{ + */ + int getTimeout() { return fTimeout; } ///< Get musrfit process timeout in seconds. + QString getFontName() { return fFontName; } ///< Get editor font family name. + int getFontSize() { return fFontSize; } ///< Get editor font size in points. + QString getExecPath() { return fExecPath; } ///< Get path to musrfit executables. + QString getDefaultSavePath() { return fDefaultSavePath; } ///< Get default directory for saving files. + bool getTitleFromDataFileFlag() { return fTitleFromDataFile; } ///< Check if title extraction from data file is enabled. + bool getMusrviewShowFourierFlag() { return fMusrviewShowFourier; } ///< Check if musrview shows Fourier at startup. + bool getMusrviewShowAvgFlag() { return fMusrviewShowAvg; } ///< Check if musrview shows averaged data. + bool getMusrviewShowOneToOneFlag() { return fMusrviewShowOneToOne; } ///< Check if one-to-one theory display is enabled. + bool getEnableMusrT0Flag() { return fEnableMusrT0; } ///< Check if musrT0 is enabled. + bool getYamlOutFlag() { return fYamlOut; } ///< Check if YAML output is enabled. + bool getKeepMinuit2OutputFlag() { return fKeepMinuit2Output; } ///< Check if MINUIT2 output files are preserved. + bool getDumpAsciiFlag() { return fDumpAscii; } ///< Check if ASCII dump is enabled. + bool getDumpRootFlag() { return fDumpRoot; } ///< Check if ROOT dump is enabled. + bool getEstimateN0Flag() { return fEstimateN0; } ///< Check if N0 estimation is enabled. + bool getChisqPerRunBlockFlag() { return fChisqPreRunBlock; } ///< Check if per-run-block chi-square is enabled. + bool getIgnoreThemeAutoDetection() { return fIgnoreThemeAutoDetection; } ///< Check if theme auto-detection is ignored. + bool getDarkThemeIconsMenuFlag() { return fDarkThemeIconsMenu; } ///< Check if dark theme icons are used in menus. + bool getDarkThemeIconsToolbarFlag() { return fDarkThemeIconsToolbar; } ///< Check if dark theme icons are used in toolbar. + int getEditWidth() { return fEditWidth; } ///< Get editor window width in pixels. + int getEditHeight() { return fEditHeight; } ///< Get editor window height in pixels. + QString getBeamline() { return fBeamline; } ///< Get default beamline name. + QString getInstitute() { return fInstitute; } ///< Get default institute name. + QString getFileFormat() { return fFileFormat; } ///< Get default data file format. + bool getLifetimeCorrectionFlag() { return fLifetimeCorrection; } ///< Check if lifetime correction is enabled. QString getHelpUrl(QString tag); - QString getTheoFuncPixmapPath() { return fTheoFuncPixmapPath; } - unsigned int getTheoryCounts() { return fTheory.size(); } + QString getTheoFuncPixmapPath() { return fTheoFuncPixmapPath; } ///< Get path to theory function pixmaps. + unsigned int getTheoryCounts() { return fTheory.size(); } ///< Get number of registered theory functions. PTheory* getTheoryItem(const unsigned int idx); - PMsr2DataParam getMsr2DataParam() { return fMsr2DataParam; } - int getNumRecentFiles() { return fRecentFile.size(); } - QString getDefaultPrefPathName() { return fPrefPathName; } + PMsr2DataParam getMsr2DataParam() { return fMsr2DataParam; } ///< Get msr2data default parameters. + int getNumRecentFiles() { return fRecentFile.size(); } ///< Get number of recent files in list. + QString getDefaultPrefPathName() { return fPrefPathName; } ///< Get path to active configuration file. QString getRecentFile(int idx); + /** @} */ - void setTimeout(const int ival) { fTimeout = ival; } - void setTitleFromDataFileFlag(const bool flag) { fTitleFromDataFile = flag; } - void setMusrviewShowFourierFlag(const bool flag) { fMusrviewShowFourier = flag; } - void setMusrviewShowAvgFlag(const bool flag) { fMusrviewShowAvg = flag; } - void setMusrviewShowOneToOneFlag(const bool flag) { fMusrviewShowOneToOne = flag; } - void setEnableMusrT0Flag(const bool flag) { fEnableMusrT0 = flag; } - void setKeepMinuit2OutputFlag(const bool flag) { fKeepMinuit2Output = flag; } - void setDumpAsciiFlag(const bool flag) { fDumpAscii = flag; } - void setDumpRootFlag(const bool flag) { fDumpRoot = flag; } - void setEstimateN0Flag(const bool flag) { fEstimateN0 = flag; } - void setYamlOutFlag(const bool flag) { fYamlOut = flag; } - void setChisqPerRunBlockFlag(const bool flag) { fChisqPreRunBlock = flag; } - void setIgnoreThemeAutoDetection(const bool flag) { fIgnoreThemeAutoDetection = flag; } - void setDarkThemeIconsMenuFlag(const bool flag) { fDarkThemeIconsMenu = flag; } - void setDarkThemeIconsToolbarFlag(const bool flag) { fDarkThemeIconsToolbar = flag; } - void setEditWidth(const int width) { fEditWidth = width; } - void setEditHeight(const int height) { fEditHeight = height; } + /** @name Configuration Setters + * @brief Methods to modify configuration values. + * @{ + */ + void setTimeout(const int ival) { fTimeout = ival; } ///< Set musrfit process timeout. + void setTitleFromDataFileFlag(const bool flag) { fTitleFromDataFile = flag; } ///< Enable/disable title extraction from data file. + void setMusrviewShowFourierFlag(const bool flag) { fMusrviewShowFourier = flag; } ///< Enable/disable Fourier display at startup. + void setMusrviewShowAvgFlag(const bool flag) { fMusrviewShowAvg = flag; } ///< Enable/disable averaged data display. + void setMusrviewShowOneToOneFlag(const bool flag) { fMusrviewShowOneToOne = flag; } ///< Enable/disable one-to-one theory. + void setEnableMusrT0Flag(const bool flag) { fEnableMusrT0 = flag; } ///< Enable/disable musrT0. + void setKeepMinuit2OutputFlag(const bool flag) { fKeepMinuit2Output = flag; } ///< Enable/disable MINUIT2 output preservation. + void setDumpAsciiFlag(const bool flag) { fDumpAscii = flag; } ///< Enable/disable ASCII dump. + void setDumpRootFlag(const bool flag) { fDumpRoot = flag; } ///< Enable/disable ROOT dump. + void setEstimateN0Flag(const bool flag) { fEstimateN0 = flag; } ///< Enable/disable N0 estimation. + void setYamlOutFlag(const bool flag) { fYamlOut = flag; } ///< Enable/disable YAML output. + void setChisqPerRunBlockFlag(const bool flag) { fChisqPreRunBlock = flag; } ///< Enable/disable per-run-block chi-square. + void setIgnoreThemeAutoDetection(const bool flag) { fIgnoreThemeAutoDetection = flag; } ///< Enable/disable theme auto-detection. + void setDarkThemeIconsMenuFlag(const bool flag) { fDarkThemeIconsMenu = flag; } ///< Enable/disable dark theme menu icons. + void setDarkThemeIconsToolbarFlag(const bool flag) { fDarkThemeIconsToolbar = flag; } ///< Enable/disable dark theme toolbar icons. + void setEditWidth(const int width) { fEditWidth = width; } ///< Set editor window width. + void setEditHeight(const int height) { fEditHeight = height; } ///< Set editor window height. - void setFontName(const QString str) { fFontName = str; } - void setFontSize(const int ival) { fFontSize = ival; } + void setFontName(const QString str) { fFontName = str; } ///< Set editor font family. + void setFontSize(const int ival) { fFontSize = ival; } ///< Set editor font size. void addRecentFile(const QString str); + /** @} */ + /** @name Persistence Methods + * @brief Methods for loading and saving configuration. + * @{ + */ int loadPrefs(QString fln); int savePrefs(QString pref_fln); - void saveRecentFiles(); ///< save recent file list + void saveRecentFiles(); ///< Save recent file list to configuration file. + /** @} */ protected: - void setExecPath(const QString str) { fExecPath = str; } - void setDefaultSavePath(const QString str) { fDefaultSavePath = str; } - void setBeamline(const QString str) { fBeamline = str; } - void setInstitute(const QString str) { fInstitute = str; } - void setFileFormat(const QString str) { fFileFormat = str; } - void setLifetimeCorrectionFlag(const bool flag) { fLifetimeCorrection = flag; } + /** @name Protected Setters + * @brief Setters accessible to friend class PAdminXMLParser during parsing. + * @{ + */ + void setExecPath(const QString str) { fExecPath = str; } ///< Set path to musrfit executables. + void setDefaultSavePath(const QString str) { fDefaultSavePath = str; } ///< Set default save directory. + void setBeamline(const QString str) { fBeamline = str; } ///< Set default beamline name. + void setInstitute(const QString str) { fInstitute = str; } ///< Set default institute name. + void setFileFormat(const QString str) { fFileFormat = str; } ///< Set default file format. + void setLifetimeCorrectionFlag(const bool flag) { fLifetimeCorrection = flag; } ///< Enable/disable lifetime correction. void setHelpUrl(const QString tag, const QString url); - void setTheoFuncPixmapPath (const QString str) { fTheoFuncPixmapPath = str; } - void addTheoryItem(const PTheory theo) { fTheory.push_back(theo); } + void setTheoFuncPixmapPath (const QString str) { fTheoFuncPixmapPath = str; } ///< Set path to theory pixmaps. + void addTheoryItem(const PTheory theo) { fTheory.push_back(theo); } ///< Add a theory function definition. + /** @} */ private: - friend class PAdminXMLParser; + friend class PAdminXMLParser; ///< Allow XML parser to access protected setters. - int fTimeout{3600}; ///< timeout in seconds + /** @name General Settings + * @brief Core application settings. + * @{ + */ + int fTimeout{3600}; ///< Timeout for musrfit processes in seconds (default: 1 hour). + QString fFontName{QString("Monospace")}; ///< Editor font family name (default: Monospace on Linux, Courier New on macOS). + int fFontSize{11}; ///< Editor font size in points (default: 11 on Linux, 16 on macOS). + /** @} */ - QString fFontName{QString("Monospace")}; ///< default font name - int fFontSize{11}; ///< default font size + /** @name Path Settings + * @brief File and directory paths. + * @{ + */ + QString fPrefPathName{QString("")}; ///< Full path to the active musredit_startup.xml configuration file. + QString fExecPath{QString("")}; ///< Directory containing musrfit executables (musrfit, musrview, etc.). + QString fDefaultSavePath{QString("")}; ///< Default directory for saving msr files. + QString fTheoFuncPixmapPath{QString("")}; ///< Directory containing theory function formula pixmaps. + /** @} */ - QString fPrefPathName{QString("")}; ///< path-name of the musredit_startup.xml - QString fExecPath{QString("")}; ///< system path to the musrfit executables - QString fDefaultSavePath{QString("")}; ///< default path where the msr-file should be saved - QString fTheoFuncPixmapPath{QString("")}; ///< path where the default pixmaps can be found + /** @name Recent Files + * @brief Recently opened file tracking. + * @{ + */ + QVector fRecentFile; ///< Ring buffer of recently opened file paths (max MAX_RECENT_FILES entries). + /** @} */ - QVector fRecentFile; ///< keep vector of recent path-file names + /** @name Display Flags + * @brief Flags controlling musrview and editor display behavior. + * @{ + */ + bool fMusrviewShowFourier{false}; ///< If true, musrview shows Fourier transform at startup instead of time-domain data. + bool fMusrviewShowAvg{false}; ///< If true, musrview shows run-averaged data; if false, shows individual runs. + bool fMusrviewShowOneToOne{false}; ///< If true, theory is calculated only at data points; if false, uses higher density. + bool fEnableMusrT0{true}; ///< If true, musrT0 tool is enabled in musredit (default: yes). + bool fIgnoreThemeAutoDetection{false}; ///< If true, ignore OS theme detection and use manual icon settings. + bool fDarkThemeIconsMenu{false}; ///< If true, use dark theme icons in application menus. + bool fDarkThemeIconsToolbar{false}; ///< If true, use dark theme icons in the toolbar. + int fEditWidth{900}; ///< Initial editor window width in pixels. + int fEditHeight{800}; ///< Initial editor window height in pixels. + /** @} */ - bool fMusrviewShowFourier{false}; ///< flag indicating if musrview should show at startup data (=false) or Fourier of data (=true). - bool fMusrviewShowAvg{false}; ///< flag indicating if musrview should show at startup averaged (=true) or original (=false) data/Fourier. - bool fMusrviewShowOneToOne{false}; ///< flag indicating if theory points are calculate only at the data points (=true) or a higher density theory points is calculated - bool fKeepMinuit2Output{false}; ///< flag indicating if the Minuit2 output shall be kept (default: no) - bool fDumpAscii{false}; ///< flag indicating if musrfit shall make an ascii-dump file (for debugging purposes, default: no). - bool fDumpRoot{false}; ///< flag indicating if musrfit shall make an root-dump file (for debugging purposes, default: no). - bool fTitleFromDataFile{true}; ///< flag indicating if the title should be extracted from the data file (default: yes). - bool fChisqPreRunBlock{false}; ///< flag indicating if musrfit shall write 'per run block' chisq to the msr-file (default: no). - bool fEstimateN0{true}; ///< flag indicating if musrfit shall estimate N0 for single histogram fits (default: yes). - bool fYamlOut{false}; ///< flag indicating if the MINUIT2.OUTPUT file should also be written as .yaml output. (default: no). - bool fEnableMusrT0{true}; ///< flag indicating if musrT0 shall be enabled at startup from within musredit (default: yes). - bool fIgnoreThemeAutoDetection{false}; ///< flag indicating that the theme autodetection shall be ignored. (default: no) - bool fDarkThemeIconsMenu{false}; ///< flag indicating if dark theme icons shall be used in the menu (default: no) - bool fDarkThemeIconsToolbar{false}; ///< flag indicating if dark theme icons shall be used in the toolbar (default: no) - int fEditWidth{900}; ///< startup edit width - int fEditHeight{800}; ///< startup edit height + /** @name Fit Output Flags + * @brief Flags controlling musrfit output options. + * @{ + */ + bool fKeepMinuit2Output{false}; ///< If true, preserve MINUIT2.OUTPUT and MINUIT2.root files after fitting. + bool fDumpAscii{false}; ///< If true, musrfit creates ASCII dump files (for debugging). + bool fDumpRoot{false}; ///< If true, musrfit creates ROOT dump files (for debugging). + bool fTitleFromDataFile{true}; ///< If true, extract msr-file title from the data file header. + bool fChisqPreRunBlock{false}; ///< If true, write per-run-block chi-square values to msr-file. + bool fEstimateN0{true}; ///< If true, estimate N0 parameter for single histogram fits. + bool fYamlOut{false}; ///< If true, write MINUIT2 output additionally as \.yaml. + /** @} */ - QString fBeamline; ///< name of the beamline. Used to generate default run header lines. - QString fInstitute; ///< name of the institute. Used to generate default run header lines. - QString fFileFormat; ///< default file format. Used to generate default run header lines. - bool fLifetimeCorrection; ///< flag indicating if by default the lifetime-correction-flag in a single histo file shall be set. + /** @name MSR File Defaults + * @brief Default values for new msr files. + * @{ + */ + QString fBeamline; ///< Default beamline name for new msr-file RUN blocks (e.g., "GPS", "LEM"). + QString fInstitute; ///< Default institute name for new msr-file RUN blocks (e.g., "PSI", "ISIS"). + QString fFileFormat; ///< Default data file format for new msr-files (e.g., "ROOT-NPP", "MusrRoot"). + bool fLifetimeCorrection; ///< If true, enable lifetime correction flag in single histogram msr-files. + /** @} */ - mutable PMsr2DataParam fMsr2DataParam; ///< keeps msr2data default parameter flags + /** @name Msr2Data Parameters + * @brief Default parameters for msr2data batch operations. + * @{ + */ + mutable PMsr2DataParam fMsr2DataParam; ///< Default parameter values for msr2data tool integration. + /** @} */ - QMap fHelpUrl; ///< maps tag to help url + /** @name Help System + * @brief Online help URL mappings. + * @{ + */ + QMap fHelpUrl; ///< Maps section tags (e.g., "theory", "parameters") to help URLs. + /** @} */ - QVector fTheory; ///< stores all known theories. Needed when generating theory blocks from within musredit. + /** @name Theory Functions + * @brief Available theory function definitions. + * @{ + */ + QVector fTheory; ///< Collection of theory functions available in the Theory menu. + /** @} */ - void createMusreditStartupFile(); ///< create default musredit_startup.xml + void createMusreditStartupFile(); ///< Create default musredit_startup.xml in user's home directory. }; #endif // _PADMIN_H_