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

improve the doxygen docu of PmuppAdmin.* (musredit_qt6).
All checks were successful
Build and Deploy Documentation / build-and-deploy (push) Successful in 20s
Details

Browse Source
This commit is contained in:
suter_a
2025-11-25 12:18:18 +01:00
parent 20d5955977
commit 0cb9b20738
2 changed files with 557 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files

267
src/musredit_qt6/mupp/PmuppAdmin.cpp
View File

@@ -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 <cstdlib>
#include <iostream>
@@ -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
//--------------------------------------------------------------------------
/**
* <p>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)
//--------------------------------------------------------------------------
/**
* <p>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)
//--------------------------------------------------------------------------
/**
* <p>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()
//--------------------------------------------------------------------------
/**
* <p>Routine called when a new XML tag is found. Here it is used
* to set a tag for filtering afterwards the content.
* @brief Handler called when 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()
//--------------------------------------------------------------------------
/**
* <p>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()
//--------------------------------------------------------------------------
/**
* <p>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()
//--------------------------------------------------------------------------
/**
* <p>Called at the end of the XML parse process. It checks if default paths
* contain system variables, and if so expand them for the further use.
* @brief Handler called at the end of XML document parsing.
*
* 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
//--------------------------------------------------------------------------
/**
* <p>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()
//--------------------------------------------------------------------------
/**
* <p>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()
//--------------------------------------------------------------------------
/**
* <p>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)
//--------------------------------------------------------------------------
/**
* <p>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 \<path_file_name\> 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()
{

382
src/musredit_qt6/mupp/PmuppAdmin.h
View File

@@ -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 <tt>mupp_startup.xml</tt>. 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:
* - \<recent_files\>: List of recently opened files
* - \<ignore_theme_auto_detection\>: Theme detection override
* - \<dark_theme_icon_menu\>: Menu icon theme preference
* - \<dark_theme_icon_toolbar\>: Toolbar icon theme preference
* - \<marker\>: Plot marker definitions
* - \<color\>: 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,
* <tt>mupp_startup.xml</tt>. 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<PmuppMarker> 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<PmuppColor> 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<QString> fRecentFile; ///< keep vector of recent path-file names
QVector<QString> fRecentFile; ///< ring buffer of recent file paths (max MAX_RECENT_FILES)
bool fIgnoreThemeAutoDetection{false};
bool fDarkThemeIconsMenu{false};
bool fDarkThemeIconsToolbar{false};
QVector<PmuppMarker> fMarker;
QVector<PmuppColor> 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<PmuppMarker> fMarker; ///< vector of configured plot markers
QVector<PmuppColor> 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_