LMU/musrfit
5
0
Fork 0
Code Issues 5 Pull Requests Actions Packages Projects Releases 4 Activity

improve the doxygen docu of PAdmin.* (musredit_qt6).

Browse Source
This commit is contained in:
suter_a
2025-11-24 10:34:58 +01:00
parent 94b3f1ac5a
commit 882ea4649c
2 changed files with 491 additions and 159 deletions
Download Patch File Download Diff File Expand all files Collapse all files

260
src/musredit_qt6/musredit/PAdmin.cpp
View File

@@ -27,6 +27,22 @@
* 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * * 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 <cstdlib> #include <cstdlib>
#include <iostream> #include <iostream>
@@ -49,10 +65,18 @@
// implementation of PAdminXMLParser class // implementation of PAdminXMLParser class
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* <p>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 * @details Creates a parser instance and immediately parses the specified XML file.
* \param admin pointer to an admin class instance. * 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) PAdminXMLParser::PAdminXMLParser(const QString& fln, PAdmin *admin) : fAdmin(admin)
{ {
@@ -74,11 +98,16 @@ PAdminXMLParser::PAdminXMLParser(const QString& fln, PAdmin *admin) : fAdmin(adm
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* <p>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) bool PAdminXMLParser::parse(QIODevice *device)
{ {
@@ -113,7 +142,13 @@ bool PAdminXMLParser::parse(QIODevice *device)
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* <p>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() bool PAdminXMLParser::startDocument()
{ {
@@ -123,8 +158,15 @@ bool PAdminXMLParser::startDocument()
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* <p>Routine called when a new XML tag is found. Here it is used * @brief Handler called when an XML start element is encountered.
* to set a tag for filtering afterwards the content. *
* @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 \<func\> element begins.
*
* @return Always returns true.
*
* @see EAdminKeyWords For the list of recognized XML element tags.
*/ */
bool PAdminXMLParser::startElement() bool PAdminXMLParser::startElement()
{ {
@@ -257,9 +299,13 @@ bool PAdminXMLParser::startElement()
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* <p>Routine called when the end XML tag is found. It is used to * @brief Handler called when an XML end element is encountered.
* put the filtering tag to 'empty'. It also resets the fFunc flag in case *
* the entry was a theory function. * @details Resets the current keyword to eEmpty after element processing completes.
* For \</func\> 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() bool PAdminXMLParser::endElement()
{ {
@@ -277,8 +323,17 @@ bool PAdminXMLParser::endElement()
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* <p>This routine delivers the content of an XML tag. It fills the * @brief Handler for XML character data (element content).
* content into the load data structure. *
* @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() bool PAdminXMLParser::characters()
{ {
@@ -584,8 +639,15 @@ bool PAdminXMLParser::characters()
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* <p>Called at the end of the XML parse process. It checks if default paths * @brief Handler called at the end of XML document parsing.
* contain system variables, and if so expand them for the further use. *
* @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() bool PAdminXMLParser::endDocument()
{ {
@@ -618,7 +680,15 @@ bool PAdminXMLParser::endDocument()
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* <p>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() void PAdminXMLParser::dump()
{ {
@@ -702,9 +772,18 @@ void PAdminXMLParser::dump()
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* <p>Expands system variables to full path, e.g. <tt>$HOME -> \home\user</tt> * @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) QString PAdminXMLParser::expandPath(const QString &str)
{ {
@@ -747,8 +826,21 @@ QString PAdminXMLParser::expandPath(const QString &str)
// implementation of PAdmin class // implementation of PAdmin class
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* <p>Initializes that PAdmin object, and calls the XML parser which feeds * @brief Constructs the PAdmin object and loads configuration.
* the object variables. *
* @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() PAdmin::PAdmin() : QObject()
{ {
@@ -835,10 +927,27 @@ PAdmin::PAdmin() : QObject()
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* <p>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: * @details Retrieves the URL for online help corresponding to the given tag.
* main, title, parameters, theory, functions, run, command, fourier, plot, statistic * 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) QString PAdmin::getHelpUrl(QString tag)
{ {
@@ -847,9 +956,17 @@ QString PAdmin::getHelpUrl(QString tag)
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* <p>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) PTheory* PAdmin::getTheoryItem(const unsigned int idx)
{ {
@@ -861,10 +978,17 @@ PTheory* PAdmin::getTheoryItem(const unsigned int idx)
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* <p>returns the recent path-file name at position idx. If idx is out of scope, * @brief Get a recent file path by index.
* an empty string is returned.
* *
* \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) QString PAdmin::getRecentFile(int idx)
{ {
@@ -876,11 +1000,15 @@ QString PAdmin::getRecentFile(int idx)
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* <p>set the help url, addressed via a tag. At the moment the following tags should be present: * @brief Set the help URL for a documentation section.
* main, title, parameters, theory, functions, run, command, fourier, plot, statistic, msr2data
* *
* \param tag to address the help url * @details Associates a URL with a documentation section tag. This is typically
* \param url help url corresponding to the tag. * 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) void PAdmin::setHelpUrl(const QString tag, const QString url)
{ {
@@ -889,11 +1017,17 @@ void PAdmin::setHelpUrl(const QString tag, const QString url)
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* <p>Loads the preference file fln. * @brief Load configuration from an XML file.
* *
* <b>return:</b> 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) int PAdmin::loadPrefs(QString fln)
{ {
@@ -916,11 +1050,21 @@ int PAdmin::loadPrefs(QString fln)
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* <p>Save the preference file pref_fln. * @brief Save current configuration to an XML file.
* *
* <b>return:</b> 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) int PAdmin::savePrefs(QString pref_fln)
{ {
@@ -1055,9 +1199,16 @@ int PAdmin::savePrefs(QString pref_fln)
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* <p>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) void PAdmin::addRecentFile(const QString str)
{ {
@@ -1074,9 +1225,17 @@ void PAdmin::addRecentFile(const QString str)
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** /**
* <p>Merges the recent file ring buffer into musredit_startup.xml and saves it. * @brief Save the recent files list to the configuration file.
* If a local copy is present it will be saved there, otherwise the master file *
* will be used. * @details Persists the current recent files list to musredit_startup.xml.
* The method reads the existing XML file, removes all existing \<path_file_name\>
* 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() 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() void PAdmin::createMusreditStartupFile()
{ {

390
src/musredit_qt6/musredit/PAdmin.h
View File

@@ -27,6 +27,34 @@
* 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * * 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_ #ifndef _PADMIN_H_
#define _PADMIN_H_ #define _PADMIN_H_
@@ -42,33 +70,78 @@ class PAdmin;
//--------------------------------------------------------------------------- //---------------------------------------------------------------------------
/** /**
* <p>This structure is keeping informations necessary to handle musrfit * @struct PTheory
* theory functions (see also <code>http://lmu.web.psi.ch/musrfit/user/html/user-manual.html#the-theory-block</code>). * @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 { struct PTheory {
QString name; QString name; ///< Internal function name used in msr files (e.g., "asymmetry", "simplExpo").
QString comment; QString comment; ///< Human-readable description of the theory function.
QString label; QString label; ///< Short label for GUI menus and buttons.
QString pixmapName; QString pixmapName; ///< Filename of the pixmap image showing the mathematical formula.
QPixmap pixmap; QPixmap pixmap; ///< Loaded pixmap image of the mathematical formula.
int params; int params; ///< Number of parameters required by this theory function.
}; };
//--------------------------------------------------------------------------- //---------------------------------------------------------------------------
/** /**
* PAdminXMLParser is an XML parser class used to handle the musredit startup * @class PAdminXMLParser
* XML-file called <tt>musredit_startup.xml</tt>. This startup file contains * @brief XML parser for the musredit configuration file.
* necessary informations about executable pathes, online help informations, *
* default font sizes, etc. * @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 class PAdminXMLParser
{ {
public: public:
PAdminXMLParser(const QString &fln, PAdmin*); 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; } virtual bool isValid() { return fValid; }
private: 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, enum EAdminKeyWords {eEmpty, eTimeout, eKeepMinuit2Output, eDumpAscii, eDumpRoot,
eTitleFromDataFile, eChisqPreRunBlock, eEstimateN0, eYamlOut, eTitleFromDataFile, eChisqPreRunBlock, eEstimateN0, eYamlOut,
eMusrviewShowFourier, eMusrviewShowAvg, eMusrviewShowOneToOne, eEnableMusrT0, eMusrviewShowFourier, eMusrviewShowAvg, eMusrviewShowOneToOne, eEnableMusrT0,
@@ -92,142 +165,231 @@ class PAdminXMLParser
QString expandPath(const QString&); QString expandPath(const QString&);
QXmlStreamReader fXml; ///< xml stream reader object QXmlStreamReader fXml; ///< Qt XML stream reader for parsing the configuration file.
bool fValid; ///< flag showing if XML read has been successful bool fValid; ///< Flag indicating whether XML parsing completed successfully.
EAdminKeyWords fKeyWord; ///< key word tag to know how to handle the content EAdminKeyWords fKeyWord; ///< Current XML element being processed.
bool fFunc; ///< flag needed to indicate that a new theory function is found bool fFunc; ///< Flag indicating parser is inside a \<func\> element block.
PTheory fTheoryItem; ///< holding the informations necessary for a theory item PTheory fTheoryItem; ///< Temporary storage for theory function data during parsing.
PAdmin *fAdmin; ///< a pointer to the main administration class object 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, * @class PAdmin
* <tt>musredit_startup.xml</tt>. This startup file contains * @brief Central administration class for musredit configuration management.
* necessary informations about executable pathes, online help informations, *
* default font sizes, etc. The XML parsing is done with the help of the PAdminXMLParser * @details The PAdmin class serves as the central repository for all musredit
* class. * 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 class PAdmin : public QObject
{ {
public: public:
PAdmin(); PAdmin();
int getTimeout() { return fTimeout; } /** @name Configuration Getters
QString getFontName() { return fFontName; } * @brief Methods to retrieve current configuration values.
int getFontSize() { return fFontSize; } * @{
QString getExecPath() { return fExecPath; } */
QString getDefaultSavePath() { return fDefaultSavePath; } int getTimeout() { return fTimeout; } ///< Get musrfit process timeout in seconds.
bool getTitleFromDataFileFlag() { return fTitleFromDataFile; } QString getFontName() { return fFontName; } ///< Get editor font family name.
bool getMusrviewShowFourierFlag() { return fMusrviewShowFourier; } int getFontSize() { return fFontSize; } ///< Get editor font size in points.
bool getMusrviewShowAvgFlag() { return fMusrviewShowAvg; } QString getExecPath() { return fExecPath; } ///< Get path to musrfit executables.
bool getMusrviewShowOneToOneFlag() { return fMusrviewShowOneToOne; } QString getDefaultSavePath() { return fDefaultSavePath; } ///< Get default directory for saving files.
bool getEnableMusrT0Flag() { return fEnableMusrT0; } bool getTitleFromDataFileFlag() { return fTitleFromDataFile; } ///< Check if title extraction from data file is enabled.
bool getYamlOutFlag() { return fYamlOut; } bool getMusrviewShowFourierFlag() { return fMusrviewShowFourier; } ///< Check if musrview shows Fourier at startup.
bool getKeepMinuit2OutputFlag() { return fKeepMinuit2Output; } bool getMusrviewShowAvgFlag() { return fMusrviewShowAvg; } ///< Check if musrview shows averaged data.
bool getDumpAsciiFlag() { return fDumpAscii; } bool getMusrviewShowOneToOneFlag() { return fMusrviewShowOneToOne; } ///< Check if one-to-one theory display is enabled.
bool getDumpRootFlag() { return fDumpRoot; } bool getEnableMusrT0Flag() { return fEnableMusrT0; } ///< Check if musrT0 is enabled.
bool getEstimateN0Flag() { return fEstimateN0; } bool getYamlOutFlag() { return fYamlOut; } ///< Check if YAML output is enabled.
bool getChisqPerRunBlockFlag() { return fChisqPreRunBlock; } bool getKeepMinuit2OutputFlag() { return fKeepMinuit2Output; } ///< Check if MINUIT2 output files are preserved.
bool getIgnoreThemeAutoDetection() { return fIgnoreThemeAutoDetection; } bool getDumpAsciiFlag() { return fDumpAscii; } ///< Check if ASCII dump is enabled.
bool getDarkThemeIconsMenuFlag() { return fDarkThemeIconsMenu; } bool getDumpRootFlag() { return fDumpRoot; } ///< Check if ROOT dump is enabled.
bool getDarkThemeIconsToolbarFlag() { return fDarkThemeIconsToolbar; } bool getEstimateN0Flag() { return fEstimateN0; } ///< Check if N0 estimation is enabled.
int getEditWidth() { return fEditWidth; } bool getChisqPerRunBlockFlag() { return fChisqPreRunBlock; } ///< Check if per-run-block chi-square is enabled.
int getEditHeight() { return fEditHeight; } bool getIgnoreThemeAutoDetection() { return fIgnoreThemeAutoDetection; } ///< Check if theme auto-detection is ignored.
QString getBeamline() { return fBeamline; } bool getDarkThemeIconsMenuFlag() { return fDarkThemeIconsMenu; } ///< Check if dark theme icons are used in menus.
QString getInstitute() { return fInstitute; } bool getDarkThemeIconsToolbarFlag() { return fDarkThemeIconsToolbar; } ///< Check if dark theme icons are used in toolbar.
QString getFileFormat() { return fFileFormat; } int getEditWidth() { return fEditWidth; } ///< Get editor window width in pixels.
bool getLifetimeCorrectionFlag() { return fLifetimeCorrection; } 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 getHelpUrl(QString tag);
QString getTheoFuncPixmapPath() { return fTheoFuncPixmapPath; } QString getTheoFuncPixmapPath() { return fTheoFuncPixmapPath; } ///< Get path to theory function pixmaps.
unsigned int getTheoryCounts() { return fTheory.size(); } unsigned int getTheoryCounts() { return fTheory.size(); } ///< Get number of registered theory functions.
PTheory* getTheoryItem(const unsigned int idx); PTheory* getTheoryItem(const unsigned int idx);
PMsr2DataParam getMsr2DataParam() { return fMsr2DataParam; } PMsr2DataParam getMsr2DataParam() { return fMsr2DataParam; } ///< Get msr2data default parameters.
int getNumRecentFiles() { return fRecentFile.size(); } int getNumRecentFiles() { return fRecentFile.size(); } ///< Get number of recent files in list.
QString getDefaultPrefPathName() { return fPrefPathName; } QString getDefaultPrefPathName() { return fPrefPathName; } ///< Get path to active configuration file.
QString getRecentFile(int idx); QString getRecentFile(int idx);
/** @} */
void setTimeout(const int ival) { fTimeout = ival; } /** @name Configuration Setters
void setTitleFromDataFileFlag(const bool flag) { fTitleFromDataFile = flag; } * @brief Methods to modify configuration values.
void setMusrviewShowFourierFlag(const bool flag) { fMusrviewShowFourier = flag; } * @{
void setMusrviewShowAvgFlag(const bool flag) { fMusrviewShowAvg = flag; } */
void setMusrviewShowOneToOneFlag(const bool flag) { fMusrviewShowOneToOne = flag; } void setTimeout(const int ival) { fTimeout = ival; } ///< Set musrfit process timeout.
void setEnableMusrT0Flag(const bool flag) { fEnableMusrT0 = flag; } void setTitleFromDataFileFlag(const bool flag) { fTitleFromDataFile = flag; } ///< Enable/disable title extraction from data file.
void setKeepMinuit2OutputFlag(const bool flag) { fKeepMinuit2Output = flag; } void setMusrviewShowFourierFlag(const bool flag) { fMusrviewShowFourier = flag; } ///< Enable/disable Fourier display at startup.
void setDumpAsciiFlag(const bool flag) { fDumpAscii = flag; } void setMusrviewShowAvgFlag(const bool flag) { fMusrviewShowAvg = flag; } ///< Enable/disable averaged data display.
void setDumpRootFlag(const bool flag) { fDumpRoot = flag; } void setMusrviewShowOneToOneFlag(const bool flag) { fMusrviewShowOneToOne = flag; } ///< Enable/disable one-to-one theory.
void setEstimateN0Flag(const bool flag) { fEstimateN0 = flag; } void setEnableMusrT0Flag(const bool flag) { fEnableMusrT0 = flag; } ///< Enable/disable musrT0.
void setYamlOutFlag(const bool flag) { fYamlOut = flag; } void setKeepMinuit2OutputFlag(const bool flag) { fKeepMinuit2Output = flag; } ///< Enable/disable MINUIT2 output preservation.
void setChisqPerRunBlockFlag(const bool flag) { fChisqPreRunBlock = flag; } void setDumpAsciiFlag(const bool flag) { fDumpAscii = flag; } ///< Enable/disable ASCII dump.
void setIgnoreThemeAutoDetection(const bool flag) { fIgnoreThemeAutoDetection = flag; } void setDumpRootFlag(const bool flag) { fDumpRoot = flag; } ///< Enable/disable ROOT dump.
void setDarkThemeIconsMenuFlag(const bool flag) { fDarkThemeIconsMenu = flag; } void setEstimateN0Flag(const bool flag) { fEstimateN0 = flag; } ///< Enable/disable N0 estimation.
void setDarkThemeIconsToolbarFlag(const bool flag) { fDarkThemeIconsToolbar = flag; } void setYamlOutFlag(const bool flag) { fYamlOut = flag; } ///< Enable/disable YAML output.
void setEditWidth(const int width) { fEditWidth = width; } void setChisqPerRunBlockFlag(const bool flag) { fChisqPreRunBlock = flag; } ///< Enable/disable per-run-block chi-square.
void setEditHeight(const int height) { fEditHeight = height; } 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 setFontName(const QString str) { fFontName = str; } ///< Set editor font family.
void setFontSize(const int ival) { fFontSize = ival; } void setFontSize(const int ival) { fFontSize = ival; } ///< Set editor font size.
void addRecentFile(const QString str); void addRecentFile(const QString str);
/** @} */
/** @name Persistence Methods
* @brief Methods for loading and saving configuration.
* @{
*/
int loadPrefs(QString fln); int loadPrefs(QString fln);
int savePrefs(QString pref_fln); int savePrefs(QString pref_fln);
void saveRecentFiles(); ///< save recent file list void saveRecentFiles(); ///< Save recent file list to configuration file.
/** @} */
protected: protected:
void setExecPath(const QString str) { fExecPath = str; } /** @name Protected Setters
void setDefaultSavePath(const QString str) { fDefaultSavePath = str; } * @brief Setters accessible to friend class PAdminXMLParser during parsing.
void setBeamline(const QString str) { fBeamline = str; } * @{
void setInstitute(const QString str) { fInstitute = str; } */
void setFileFormat(const QString str) { fFileFormat = str; } void setExecPath(const QString str) { fExecPath = str; } ///< Set path to musrfit executables.
void setLifetimeCorrectionFlag(const bool flag) { fLifetimeCorrection = flag; } 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 setHelpUrl(const QString tag, const QString url);
void setTheoFuncPixmapPath (const QString str) { fTheoFuncPixmapPath = str; } void setTheoFuncPixmapPath (const QString str) { fTheoFuncPixmapPath = str; } ///< Set path to theory pixmaps.
void addTheoryItem(const PTheory theo) { fTheory.push_back(theo); } void addTheoryItem(const PTheory theo) { fTheory.push_back(theo); } ///< Add a theory function definition.
/** @} */
private: 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 /** @name Path Settings
int fFontSize{11}; ///< default font size * @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 /** @name Recent Files
QString fExecPath{QString("")}; ///< system path to the musrfit executables * @brief Recently opened file tracking.
QString fDefaultSavePath{QString("")}; ///< default path where the msr-file should be saved * @{
QString fTheoFuncPixmapPath{QString("")}; ///< path where the default pixmaps can be found */
QVector<QString> fRecentFile; ///< Ring buffer of recently opened file paths (max MAX_RECENT_FILES entries).
/** @} */
QVector<QString> 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). /** @name Fit Output Flags
bool fMusrviewShowAvg{false}; ///< flag indicating if musrview should show at startup averaged (=true) or original (=false) data/Fourier. * @brief Flags controlling musrfit output options.
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 fKeepMinuit2Output{false}; ///< If true, preserve MINUIT2.OUTPUT and MINUIT2.root files after fitting.
bool fDumpRoot{false}; ///< flag indicating if musrfit shall make an root-dump file (for debugging purposes, default: no). bool fDumpAscii{false}; ///< If true, musrfit creates ASCII dump files (for debugging).
bool fTitleFromDataFile{true}; ///< flag indicating if the title should be extracted from the data file (default: yes). bool fDumpRoot{false}; ///< If true, musrfit creates ROOT dump files (for debugging).
bool fChisqPreRunBlock{false}; ///< flag indicating if musrfit shall write 'per run block' chisq to the msr-file (default: no). bool fTitleFromDataFile{true}; ///< If true, extract msr-file title from the data file header.
bool fEstimateN0{true}; ///< flag indicating if musrfit shall estimate N0 for single histogram fits (default: yes). bool fChisqPreRunBlock{false}; ///< If true, write per-run-block chi-square values to msr-file.
bool fYamlOut{false}; ///< flag indicating if the MINUIT2.OUTPUT file should also be written as <msr-file>.yaml output. (default: no). bool fEstimateN0{true}; ///< If true, estimate N0 parameter for single histogram fits.
bool fEnableMusrT0{true}; ///< flag indicating if musrT0 shall be enabled at startup from within musredit (default: yes). bool fYamlOut{false}; ///< If true, write MINUIT2 output additionally as \<msr-file\>.yaml.
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
QString fBeamline; ///< name of the beamline. Used to generate default run header lines. /** @name MSR File Defaults
QString fInstitute; ///< name of the institute. Used to generate default run header lines. * @brief Default values for new msr files.
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. */
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<QString, QString> fHelpUrl; ///< maps tag to help url /** @name Help System
* @brief Online help URL mappings.
* @{
*/
QMap<QString, QString> fHelpUrl; ///< Maps section tags (e.g., "theory", "parameters") to help URLs.
/** @} */
QVector<PTheory> fTheory; ///< stores all known theories. Needed when generating theory blocks from within musredit. /** @name Theory Functions
* @brief Available theory function definitions.
* @{
*/
QVector<PTheory> 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_ #endif // _PADMIN_H_