diff --git a/src/musredit_qt6/mupp/PmuppAdmin.cpp b/src/musredit_qt6/mupp/PmuppAdmin.cpp index 43f7000a3..5f3ce6ccb 100644 --- a/src/musredit_qt6/mupp/PmuppAdmin.cpp +++ b/src/musredit_qt6/mupp/PmuppAdmin.cpp @@ -27,6 +27,30 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PmuppAdmin.cpp + * + * @brief Implementation of mupp configuration and administration classes. + * + * This file implements the configuration management system for mupp, including: + * - XML parsing of the mupp_startup.xml configuration file + * - Recent file history management + * - Plot appearance settings (colors and markers) + * - Theme preferences for UI elements + * - Automatic creation of default configuration files + * + * The implementation provides: + * - PmuppColor: RGB color storage and manipulation + * - PmuppAdminXMLParser: XML configuration file parsing + * - PmuppAdmin: Main configuration manager with file search hierarchy + * + * Configuration file handling: + * - Searches multiple standard locations for configuration + * - Creates default configuration if none found + * - Automatically saves recent file history on exit + * - Validates configuration values (marker codes, RGB ranges) + */ + #include #include @@ -48,7 +72,10 @@ // implementation of PmuppColor class //-------------------------------------------------------------------------- /** - * @brief PmuppColor::PmuppColor. Ctor + * @brief Default constructor for PmuppColor. + * + * Initializes a color with an "UnDef" name and invalid RGB values (-1). + * Invalid values indicate the color has not been properly initialized. */ PmuppColor::PmuppColor() { @@ -60,10 +87,15 @@ PmuppColor::PmuppColor() //-------------------------------------------------------------------------- /** - * @brief PmuppColor::setRGB. set RGB value - * @param r red (0..255) - * @param g green (0..255) - * @param b blue (0..255) + * @brief Sets the RGB color values with validation. + * + * Sets the red, green, and blue components of the color. Each component + * is validated to be in the range [0, 255]. Values outside this range + * are ignored and the corresponding component remains unchanged. + * + * @param r red component (0-255) + * @param g green component (0-255) + * @param b blue component (0-255) */ void PmuppColor::setRGB(const int r, const int g, const int b) { @@ -79,9 +111,14 @@ void PmuppColor::setRGB(const int r, const int g, const int b) // implementation of PmuppAdminXMLParser class //-------------------------------------------------------------------------- /** - *

XML Parser class for the mupp administration file. + * @brief Constructor for XML parser. * - * \param admin pointer to an admin class instance. + * Initializes the XML parser and attempts to open and parse the + * specified configuration file. The parsed data is stored in the + * provided PmuppAdmin object. + * + * @param fln path to the mupp_startup.xml configuration file + * @param admin pointer to the PmuppAdmin instance to populate with parsed data */ PmuppAdminXMLParser::PmuppAdminXMLParser(const QString& fln, PmuppAdmin *admin) : fAdmin(admin) { @@ -98,11 +135,18 @@ PmuppAdminXMLParser::PmuppAdminXMLParser(const QString& fln, PmuppAdmin *admin) //-------------------------------------------------------------------------- /** - *

parse the mupp startup xml-file. + * @brief Parses the mupp startup XML file. * - * \param device QFile object of the mupp startup xml-file + * This method uses Qt's QXmlStreamReader to parse the configuration file. + * It processes each XML element sequentially, calling appropriate handler + * methods (startElement, characters, endElement) based on the element type. * - * @return true on success, false otherwise + * The parser is event-driven and maintains state through the fKeyWord + * enumeration to determine how to process element content. + * + * @param device QIODevice (typically QFile) containing the XML data + * + * @return true if parsing succeeds without errors, false otherwise */ bool PmuppAdminXMLParser::parse(QIODevice *device) { @@ -137,7 +181,12 @@ bool PmuppAdminXMLParser::parse(QIODevice *device) //-------------------------------------------------------------------------- /** - *

Routine called at the beginning of the XML parsing process. + * @brief Handler called at the start of XML document parsing. + * + * This is invoked when the XML parser encounters the document start. + * Currently performs no actions but provides a hook for future initialization. + * + * @return always returns true */ bool PmuppAdminXMLParser::startDocument() { @@ -147,8 +196,22 @@ bool PmuppAdminXMLParser::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 a new XML element is encountered. + * + * This method is invoked when the parser encounters an opening XML tag. + * It identifies the element type and sets the fKeyWord state accordingly, + * which determines how the element's content will be processed in the + * characters() method. + * + * Recognized elements: + * - path_file_name: Recent file entry + * - ignore_theme_auto_detection: Theme detection override + * - dark_theme_icon_menu: Menu icon theme + * - dark_theme_icon_toolbar: Toolbar icon theme + * - marker: Plot marker definition + * - color: RGB color definition + * + * @return always returns true */ bool PmuppAdminXMLParser::startElement() { @@ -173,9 +236,13 @@ bool PmuppAdminXMLParser::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 closing tag is encountered. + * + * This method is invoked when the parser encounters a closing XML tag. + * It resets the fKeyWord state to eEmpty, ending the current element's + * context for content processing. + * + * @return always returns true */ bool PmuppAdminXMLParser::endElement() { @@ -186,8 +253,21 @@ bool PmuppAdminXMLParser::endElement() //-------------------------------------------------------------------------- /** - *

This routine delivers the content of an XML tag. It fills the - * content into the load data structure. + * @brief Handler called to process XML element content. + * + * This method processes the text content between XML opening and closing + * tags. The content interpretation depends on the current fKeyWord state + * (set by startElement). + * + * Content processing by element type: + * - eRecentFile: Adds file path to recent files list + * - eIgnoreThemeAutoDetection: Sets theme auto-detection flag (yes/no/true/false) + * - eDarkThemeIconsMenu: Sets menu icon theme preference + * - eDarkThemeIconsToolbar: Sets toolbar icon theme preference + * - eMarker: Parses marker definition (code[,size]) + * - eColor: Parses RGB color definition (r,g,b[,name]) + * + * @return true if content is valid, false on parsing errors */ bool PmuppAdminXMLParser::characters() { @@ -273,8 +353,13 @@ bool PmuppAdminXMLParser::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. + * + * This is invoked when the parser reaches the end of the XML document. + * Currently performs no post-processing but provides a hook for future + * finalization tasks such as path expansion or validation. + * + * @return always returns true */ bool PmuppAdminXMLParser::endDocument() { @@ -285,8 +370,20 @@ bool PmuppAdminXMLParser::endDocument() // implementation of PmuppAdmin class //-------------------------------------------------------------------------- /** - *

Initializes that PmuppAdmin object, and calls the XML parser which feeds - * the object variables. + * @brief Constructor for PmuppAdmin. + * + * Initializes the administration object and searches for a configuration + * file in multiple standard locations. The search proceeds in order: + * 1. Current directory (./mupp_startup.xml) + * 2. User home directory ($HOME/.musrfit/mupp/mupp_startup.xml) + * 3. MUSRFITPATH directory ($MUSRFITPATH/mupp_startup.xml) + * 4. ROOTSYS directory ($ROOTSYS/bin/mupp_startup.xml) + * + * If no configuration file is found, creates a default one in the user's + * home directory using the embedded resource template. + * + * The constructor loads all configuration settings including recent files, + * markers, colors, and theme preferences via the PmuppAdminXMLParser. */ PmuppAdmin::PmuppAdmin() : QObject() { @@ -336,7 +433,11 @@ PmuppAdmin::PmuppAdmin() : QObject() //-------------------------------------------------------------------------- /** - *

Destructor + * @brief Destructor for PmuppAdmin. + * + * Saves the current recent file list to the configuration file before + * destruction. This ensures that the file history is preserved across + * application sessions. */ PmuppAdmin::~PmuppAdmin() { @@ -345,9 +446,14 @@ PmuppAdmin::~PmuppAdmin() //-------------------------------------------------------------------------- /** - *

Add recent path-file name to the internal ring-buffer. + * @brief Adds a file to the recent files list. * - * \param str recent path-file name to be added + * Adds a file path to the front of the recent files ring buffer. If the + * file is already in the list, it is not added again (no duplicates). + * The list is limited to MAX_RECENT_FILES entries; older entries are + * removed when the limit is exceeded. + * + * @param str the full path and filename to add to recent files */ void PmuppAdmin::addRecentFile(const QString str) { @@ -364,12 +470,14 @@ void PmuppAdmin::addRecentFile(const QString str) //-------------------------------------------------------------------------- /** - * @brief PmuppAdmin::getRecentFile. Get a file from the recent files with - * index idx. - * @param idx + * @brief Retrieves a recent file path by index. * - * @return return the recent file with index idx if present, otherwise return - * an empty string. + * Returns the file path at the specified position in the recent files list. + * Index 0 refers to the most recently accessed file. + * + * @param idx zero-based index into the recent files list (0 is most recent) + * + * @return the file path if index is valid, or an empty string otherwise */ QString PmuppAdmin::getRecentFile(int idx) { @@ -383,10 +491,14 @@ QString PmuppAdmin::getRecentFile(int idx) //-------------------------------------------------------------------------- /** - * @brief PmuppAdmin::getMarker. Get the marker with index idx. - * @param idx marker index + * @brief Retrieves a marker definition by index. * - * @return requested marker + * Returns the marker at the specified index in the marker list. + * Markers are used to define the visual appearance of data points in plots. + * + * @param idx zero-based index into the marker list + * + * @return the marker definition if index is valid, or a default marker otherwise */ PmuppMarker PmuppAdmin::getMarker(int idx) { PmuppMarker marker; @@ -399,11 +511,15 @@ PmuppMarker PmuppAdmin::getMarker(int idx) { //-------------------------------------------------------------------------- /** - * @brief PmuppAdmin::getColor. Get rgb color codes of name - * @param name of the requeset color. - * @param r red value (0..255) - * @param g green value (0..255) - * @param b blue value (0..255 + * @brief Retrieves a color by name. + * + * Searches for a color with the specified name and returns its RGB values. + * If the color is not found, all RGB components are set to -1. + * + * @param name the name of the color to retrieve + * @param r output parameter: red component (0-255, or -1 if not found) + * @param g output parameter: green component (0-255, or -1 if not found) + * @param b output parameter: blue component (0-255, or -1 if not found) */ void PmuppAdmin::getColor(QString name, int &r, int &g, int &b) { @@ -426,11 +542,16 @@ void PmuppAdmin::getColor(QString name, int &r, int &g, int &b) //-------------------------------------------------------------------------- /** - * @brief PmuppAdmin::getColor. Get color codes of color at index idx - * @param idx requested color index - * @param r red value (0..255) - * @param g green value (0..255) - * @param b blue value (0..255) + * @brief Retrieves a color by index. + * + * Returns the RGB values of the color at the specified index in the + * color list. If the index is out of range, all RGB components are + * set to -1. + * + * @param idx zero-based index into the color list + * @param r output parameter: red component (0-255, or -1 if invalid index) + * @param g output parameter: green component (0-255, or -1 if invalid index) + * @param b output parameter: blue component (0-255, or -1 if invalid index) */ void PmuppAdmin::getColor(int idx, int &r, int &g, int &b) { @@ -445,9 +566,14 @@ void PmuppAdmin::getColor(int idx, int &r, int &g, int &b) //-------------------------------------------------------------------------- /** - * @brief PmuppAdmin::setMaker. Set a marker - * @param marker marker code - * @param size marker size + * @brief Adds a marker definition to the configuration. + * + * Creates a new marker with the specified code and size, validates it, + * and adds it to the marker list. Marker codes must be in the range 1-49 + * (following ROOT conventions). Invalid markers are rejected with a warning. + * + * @param marker the marker code (1-49, ROOT style marker codes) + * @param size the marker size multiplier */ void PmuppAdmin::setMarker(const int marker, const double size) { @@ -466,11 +592,16 @@ void PmuppAdmin::setMarker(const int marker, const double size) //-------------------------------------------------------------------------- /** - * @brief PmuppAdmin::setColor. Set a color - * @param r red value (0..255) - * @param g green value (0..255) - * @param b blue value (0..255) - * @param name color name + * @brief Adds a color definition to the configuration. + * + * Creates a new color with the specified RGB values and optional name, + * validates it, and adds it to the color list. RGB values must be in + * the range 0-255. Invalid colors are rejected with a warning. + * + * @param r red component (0-255) + * @param g green component (0-255) + * @param b blue component (0-255) + * @param name optional name for the color (empty by default) */ void PmuppAdmin::setColor(const int r, const int g, const int b, QString name) { @@ -490,9 +621,21 @@ void PmuppAdmin::setColor(const int r, const int g, const int b, QString name) //-------------------------------------------------------------------------- /** - *

Merges the recent file ring buffer into mupp_startup.xml and saves it. - * If a local copy is present it will be saved there, otherwise the master file - * will be used. + * @brief Saves the recent files list to the configuration file. + * + * Updates the mupp_startup.xml file with the current recent file list. + * The method first searches for a local configuration file in the current + * directory; if not found, it uses the user's home directory version + * ($HOME/.musrfit/mupp/mupp_startup.xml). + * + * The implementation: + * 1. Reads the entire configuration file into memory + * 2. Removes all existing \ entries + * 3. Inserts current recent files list + * 4. Writes the updated configuration back to disk + * + * This preserves all other configuration settings while updating only + * the recent file history. */ void PmuppAdmin::saveRecentFiles() { @@ -561,8 +704,20 @@ void PmuppAdmin::saveRecentFiles() //-------------------------------------------------------------------------- /** - * @brief PmuppAdmin::createMuppStartupFile. Create a default mupp_startup.xml - * file if not present. + * @brief Creates a default mupp_startup.xml configuration file. + * + * This method is called when no configuration file is found in any of + * the standard locations. It creates a new default configuration file + * in the user's home directory ($HOME/.musrfit/mupp/mupp_startup.xml). + * + * The implementation: + * 1. Creates the directory $HOME/.musrfit/mupp if it doesn't exist + * 2. Loads the default template from embedded resources (mupp_startup.xml.in) + * 3. Writes the template to the user's home directory + * + * The default configuration includes standard marker styles, color + * definitions, and empty recent file list, providing a working baseline + * for new users or clean installations. */ void PmuppAdmin::createMuppStartupFile() { diff --git a/src/musredit_qt6/mupp/PmuppAdmin.h b/src/musredit_qt6/mupp/PmuppAdmin.h index cad418c2c..a1599e53c 100644 --- a/src/musredit_qt6/mupp/PmuppAdmin.h +++ b/src/musredit_qt6/mupp/PmuppAdmin.h @@ -8,7 +8,7 @@ *****************************************************************************/ /*************************************************************************** - * Copyright (C) 2010-2017 by Andreas Suter * + * Copyright (C) 2010-2025 by Andreas Suter * * andreas.suter@psi.ch * * * * This program is free software; you can redistribute it and/or modify * @@ -27,6 +27,32 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PmuppAdmin.h + * + * @brief Administration and configuration management for mupp application. + * + * This header file defines classes for managing mupp's configuration and + * user preferences. It provides functionality for: + * - Reading and parsing XML configuration files (mupp_startup.xml) + * - Managing recent file history + * - Storing plot appearance settings (colors, markers) + * - Handling theme preferences (light/dark mode icons) + * + * The configuration system supports multiple file locations with the + * following search priority: + * 1. Local directory (./mupp_startup.xml) + * 2. User home (~/.musrfit/mupp/mupp_startup.xml) + * 3. MUSRFITPATH environment variable location + * 4. ROOTSYS/bin location + * + * Key components: + * - PmuppColor: RGB color definitions for plot elements + * - PmuppMarker: Marker style and size specifications + * - PmuppAdminXMLParser: XML parser for configuration files + * - PmuppAdmin: Main administration class managing all settings + */ + #ifndef _PMUPPADMIN_H_ #define _PMUPPADMIN_H_ @@ -42,134 +68,418 @@ class PmuppAdmin; //--------------------------------------------------------------------------- /** - * @brief The PmuppColor class. Contains to colors read from the xml-startup - * which are used for the plotted data. + * @brief Represents an RGB color for plotting. + * + * The PmuppColor class encapsulates a named color with RGB components. + * Colors are read from the XML startup configuration file and used for + * plotting data points, lines, and other graphical elements in mupp. + * + * Each color has: + * - A name identifier (optional) + * - RGB values in the range 0-255 + * + * These colors allow users to customize the appearance of plots and + * ensure consistency across different data collections. */ class PmuppColor { public: + /** + * @brief Default constructor. Initializes color with undefined values. + */ PmuppColor(); + + /** + * @brief Destructor. + */ virtual ~PmuppColor() {} + /** + * @brief Gets the color name. + * @return the name identifier of the color + */ QString getName() { return fName; } + + /** + * @brief Gets the RGB values of the color. + * @param r output parameter: red component (0-255) + * @param g output parameter: green component (0-255) + * @param b output parameter: blue component (0-255) + */ void getRGB(int &r, int &g, int &b) { r=fRed; g=fGreen; b=fBlue; } + /** + * @brief Sets the color name. + * @param name the name identifier to assign to this color + */ void setName(const QString name) { fName = name; } + + /** + * @brief Sets the RGB values with validation. + * @param r red component (0-255) + * @param g green component (0-255) + * @param b blue component (0-255) + */ void setRGB(const int r, const int g, const int b); private: - QString fName; - int fRed; - int fGreen; - int fBlue; + QString fName; ///< optional name identifier for the color + int fRed; ///< red component (0-255) + int fGreen; ///< green component (0-255) + int fBlue; ///< blue component (0-255) }; //--------------------------------------------------------------------------- /** - * @brief The PmuppMarker class. List of the markers used in the plotter. Read - * from the xml-startup. + * @brief Represents a plot marker style and size. + * + * The PmuppMarker class encapsulates marker properties used for plotting + * data points in mupp. Markers are read from the XML startup configuration + * file and define the visual appearance of data points in plots. + * + * Each marker has: + * - A marker code (1-49, following ROOT marker conventions) + * - A size multiplier (relative to default size) + * + * Different markers allow users to visually distinguish between multiple + * data series in a single plot. */ class PmuppMarker { public: + /** + * @brief Default constructor. Initializes with marker code 20 and size 1.0. + */ PmuppMarker() { fMarker = 20; fMarkerSize = 1.0; } + + /** + * @brief Constructor with specified marker properties. + * @param marker the marker code (1-49) + * @param size the marker size multiplier + */ PmuppMarker(int marker, double size) : fMarker(marker), fMarkerSize(size) {} + + /** + * @brief Destructor. + */ virtual ~PmuppMarker() {} + /** + * @brief Gets both marker code and size. + * @param marker output parameter: marker code + * @param size output parameter: marker size multiplier + */ void getMarker(int &marker, double &size) { marker = fMarker; size = fMarkerSize; } + + /** + * @brief Gets the marker code. + * @return the marker code (1-49) + */ int getMarker() { return fMarker; } + + /** + * @brief Gets the marker size multiplier. + * @return the marker size multiplier + */ double getMarkerSize() { return fMarkerSize; } + /** + * @brief Sets the marker code. + * @param marker the marker code to set (1-49) + */ void setMarker(int marker) { fMarker = marker; } + + /** + * @brief Sets the marker size multiplier. + * @param size the size multiplier to set + */ void setMarkerSize(double size) { fMarkerSize = size; } private: - int fMarker; - double fMarkerSize; + int fMarker; ///< marker code (1-49, ROOT style) + double fMarkerSize; ///< size multiplier (1.0 = default size) }; //--------------------------------------------------------------------------- /** - * PAdminXMLParser is an XML parser class used to handle the mupp startup - * XML-file called mupp_startup.xml. This startup file contains - * necessary informations about executable pathes, online help informations, - * default font sizes, etc. + * @brief XML parser for mupp configuration files. + * + * PmuppAdminXMLParser is responsible for reading and parsing the mupp + * startup XML file (mupp_startup.xml). This configuration file contains: + * - Recent file history + * - Theme preferences (light/dark mode icons) + * - Plot marker styles and sizes + * - Plot color definitions + * + * The parser uses Qt's QXmlStreamReader for efficient XML processing + * and populates a PmuppAdmin object with the configuration data. + * + * XML structure handled: + * - \: List of recently opened files + * - \: Theme detection override + * - \: Menu icon theme preference + * - \: Toolbar icon theme preference + * - \: Plot marker definitions + * - \: RGB color definitions */ class PmuppAdminXMLParser { public: + /** + * @brief Constructor that parses the XML configuration file. + * @param fln path to the mupp_startup.xml file + * @param admin pointer to PmuppAdmin object to populate with parsed data + */ PmuppAdminXMLParser(const QString &fln, PmuppAdmin*); + + /** + * @brief Destructor. + */ virtual ~PmuppAdminXMLParser() {} + /** + * @brief Checks if the XML parsing was successful. + * @return true if parsing succeeded, false otherwise + */ virtual bool isValid() { return fValid; } private: - enum EAdminKeyWords {eEmpty, eRecentFile, - eIgnoreThemeAutoDetection, eDarkThemeIconsMenu, eDarkThemeIconsToolbar, - eMarker, eColor}; + /** + * @brief Enumeration of recognized XML element types. + * + * These keywords determine how to process the content of each XML element. + */ + enum EAdminKeyWords {eEmpty, ///< no specific element being processed + eRecentFile, ///< recent file path element + eIgnoreThemeAutoDetection, ///< theme auto-detection override + eDarkThemeIconsMenu, ///< menu icon theme setting + eDarkThemeIconsToolbar, ///< toolbar icon theme setting + eMarker, ///< marker definition element + eColor}; ///< color definition element + /** + * @brief Main parsing method that processes the XML document. + * @param device QIODevice containing the XML data to parse + * @return true if parsing succeeds, false on error + */ bool parse(QIODevice *device); + + /** + * @brief Handler for XML document start. + * @return true if successful + */ bool startDocument(); + + /** + * @brief Handler for XML element opening tags. + * @return true if successful + */ bool startElement(); + + /** + * @brief Handler for XML element closing tags. + * @return true if successful + */ bool endElement(); + + /** + * @brief Handler for XML element text content. + * @return true if content is valid, false on error + */ bool characters(); + + /** + * @brief Handler for XML document end. + * @return true if successful + */ 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 - PmuppAdmin *fAdmin; ///< a pointer to the main administration class object + QXmlStreamReader fXml; ///< Qt XML stream reader object for parsing + bool fValid; ///< flag indicating successful XML parsing + EAdminKeyWords fKeyWord; ///< current element type being processed + PmuppAdmin *fAdmin; ///< pointer to the admin object being populated }; //--------------------------------------------------------------------------- /** - * The PMuppAdmin class is handling the informations contained in the XML startup file, - * mupp_startup.xml. This startup file contains - * necessary informations like marker style, marker color, etc. The XML parsing is done - * with the help of the PmuppAdminXMLParser class. + * @brief Main administration class for mupp configuration management. + * + * The PmuppAdmin class manages all configuration settings and user preferences + * for the mupp application. It loads settings from the XML startup file + * (mupp_startup.xml) and provides access to: + * - Recent file history (up to MAX_RECENT_FILES entries) + * - Plot appearance settings (markers and colors) + * - Theme preferences for UI icons + * + * Configuration file search order: + * 1. ./mupp_startup.xml (local directory) + * 2. $HOME/.musrfit/mupp/mupp_startup.xml (user home) + * 3. $MUSRFITPATH/mupp_startup.xml (installation directory) + * 4. $ROOTSYS/bin/mupp_startup.xml (ROOT installation) + * + * If no configuration file is found, a default one is created in the + * user's home directory (~/.musrfit/mupp/). + * + * The class automatically saves the recent file list when destroyed, + * updating the configuration file with the current session's file history. */ class PmuppAdmin : public QObject { public: + /** + * @brief Constructor. Loads configuration from mupp_startup.xml. + */ PmuppAdmin(); + + /** + * @brief Destructor. Saves recent files list before destruction. + */ virtual ~PmuppAdmin(); + /** + * @brief Adds a file to the recent files list. + * @param str the file path to add + */ void addRecentFile(const QString str); + + /** + * @brief Gets the number of recent files. + * @return the count of recent files stored (maximum MAX_RECENT_FILES) + */ int getNumRecentFiles() { return fRecentFile.size(); } + + /** + * @brief Gets a recent file path by index. + * @param idx zero-based index (0 is most recent) + * @return the file path, or empty string if index is out of range + */ QString getRecentFile(int idx); - - + /** + * @brief Gets the number of configured markers. + * @return the count of marker definitions + */ int getNoOfMarkers() { return fMarker.size(); } + + /** + * @brief Gets all markers. + * @return vector of all marker definitions + */ QVector getMarkers() { return fMarker; } + + /** + * @brief Gets a marker definition by index. + * @param idx zero-based index into the marker list + * @return the marker definition, or default marker if index is out of range + */ PmuppMarker getMarker(int idx); + /** + * @brief Gets the number of configured colors. + * @return the count of color definitions + */ int getNoOfColors() { return fColor.size(); } + + /** + * @brief Gets all colors. + * @return vector of all color definitions + */ QVector getColors() { return fColor; } + + /** + * @brief Gets a color by name. + * @param name the color name to search for + * @param r output parameter: red component (0-255, or -1 if not found) + * @param g output parameter: green component (0-255, or -1 if not found) + * @param b output parameter: blue component (0-255, or -1 if not found) + */ void getColor(QString name, int &r, int &g, int &b); + + /** + * @brief Gets a color by index. + * @param idx zero-based index into the color list + * @param r output parameter: red component (0-255, or -1 if invalid) + * @param g output parameter: green component (0-255, or -1 if invalid) + * @param b output parameter: blue component (0-255, or -1 if invalid) + */ void getColor(int idx, int &r, int &g, int &b); + /** + * @brief Checks if theme auto-detection should be ignored. + * @return true if auto-detection is disabled, false otherwise + */ bool getIgnoreThemeAutoDetection() { return fIgnoreThemeAutoDetection; } + + /** + * @brief Checks if dark theme icons should be used for menus. + * @return true if dark theme icons are enabled for menus + */ bool getDarkThemeIconsMenuFlag() { return fDarkThemeIconsMenu; } + + /** + * @brief Checks if dark theme icons should be used for toolbars. + * @return true if dark theme icons are enabled for toolbars + */ bool getDarkThemeIconsToolbarFlag() { return fDarkThemeIconsToolbar; } + /** + * @brief Sets the theme auto-detection preference. + * @param theme true to ignore auto-detection, false to enable it + */ void setIgnoreThemeAutoDetection(const bool theme) { fIgnoreThemeAutoDetection = theme; } + + /** + * @brief Sets the menu icon theme preference. + * @param theme true for dark theme icons, false for light theme icons + */ void setThemeIconsMenu(const bool theme) { fDarkThemeIconsMenu = theme; } + + /** + * @brief Sets the toolbar icon theme preference. + * @param theme true for dark theme icons, false for light theme icons + */ void setThemeIconsToolbar(const bool theme) { fDarkThemeIconsToolbar = theme; } + + /** + * @brief Adds a marker definition to the configuration. + * @param marker the marker code (1-49, ROOT style) + * @param size the marker size multiplier + */ void setMarker(const int marker, const double size); + + /** + * @brief Adds a color definition to the configuration. + * @param r red component (0-255) + * @param g green component (0-255) + * @param b blue component (0-255) + * @param name optional name for the color + */ void setColor(const int r, const int g, const int b, QString name=""); private: friend class PmuppAdminXMLParser; - QVector fRecentFile; ///< keep vector of recent path-file names + QVector fRecentFile; ///< ring buffer of recent file paths (max MAX_RECENT_FILES) - bool fIgnoreThemeAutoDetection{false}; - bool fDarkThemeIconsMenu{false}; - bool fDarkThemeIconsToolbar{false}; - QVector fMarker; - QVector fColor; + bool fIgnoreThemeAutoDetection{false}; ///< flag to override automatic theme detection + bool fDarkThemeIconsMenu{false}; ///< flag for dark theme menu icons + bool fDarkThemeIconsToolbar{false}; ///< flag for dark theme toolbar icons + QVector fMarker; ///< vector of configured plot markers + QVector fColor; ///< vector of configured plot colors - void saveRecentFiles(); ///< save recent file list - void createMuppStartupFile(); ///< create default mupp_startup.xml + /** + * @brief Saves the recent files list to the configuration file. + * + * Updates mupp_startup.xml with current recent file history while + * preserving other configuration settings. + */ + void saveRecentFiles(); + + /** + * @brief Creates a default mupp_startup.xml configuration file. + * + * Called when no configuration file is found. Creates the file in + * $HOME/.musrfit/mupp/ using the embedded resource template. + */ + void createMuppStartupFile(); }; #endif // _PMUPPADMIN_H_