From a283347321738faf551c97fb5a2137c8ecc84f44 Mon Sep 17 00:00:00 2001 From: Andreas Suter Date: Tue, 25 Nov 2025 18:33:31 +0100 Subject: [PATCH] improve the doxygen documentation of the plotter-part of mupp. --- src/musredit_qt6/mupp/plotter/PMuppCanvas.cpp | 51 ++++- src/musredit_qt6/mupp/plotter/PMuppCanvas.h | 200 +++++++++++++++--- .../mupp/plotter/PMuppStartupHandler.cpp | 32 ++- .../mupp/plotter/PMuppStartupHandler.h | 195 +++++++++++++++-- src/musredit_qt6/mupp/plotter/mupp_plot.cpp | 35 ++- src/musredit_qt6/mupp/plotter/mupp_plot.h | 66 ++++-- 6 files changed, 504 insertions(+), 75 deletions(-) diff --git a/src/musredit_qt6/mupp/plotter/PMuppCanvas.cpp b/src/musredit_qt6/mupp/plotter/PMuppCanvas.cpp index 3fa1f91ff..e275c4916 100644 --- a/src/musredit_qt6/mupp/plotter/PMuppCanvas.cpp +++ b/src/musredit_qt6/mupp/plotter/PMuppCanvas.cpp @@ -5,6 +5,29 @@ Author: Andreas Suter e-mail: andreas.suter@psi.ch + This file implements the PMuppCanvas class, which provides the main plotting + functionality for the mupp_plot application. + + Key features implemented: + - ROOT canvas initialization with custom menu system + - IPC message queue monitoring for data updates + - Multi-graph plotting with TGraphAsymmErrors + - Configurable marker styles, sizes, and colors + - Interactive toggling between line and marker display + - Data export to text files + - Keyboard shortcuts and menu handlers + + The canvas polls an IPC message queue every 200ms to check for updates from + the mupp GUI. When new data arrives, ReadPlotData() is called to parse the + plot data file, and UpdateGraphs() recreates the TGraphAsymmErrors objects + and redraws the canvas. + + Data file format: + - Tab-separated values + - First line: "PLOT_DATA" header + - Collection blocks with name, x-label, y-labels, and data points + - Each data point: x-value, y-value, positive error, negative error + ***************************************************************************/ /*************************************************************************** @@ -53,7 +76,10 @@ ClassImpQ(PMuppCanvas) // Constructor //-------------------------------------------------------------------------- /** - * @brief PMuppCanvas::PMuppCanvas + * @brief Default constructor creating an invalid canvas. + * + * Initializes members to null/empty values and sets global histogram minimum + * to zero for proper bar chart handling. */ PMuppCanvas::PMuppCanvas() { @@ -69,15 +95,20 @@ PMuppCanvas::PMuppCanvas() // Constructor //-------------------------------------------------------------------------- /** - * @brief PMuppCanvas::PMuppCanvas - * @param title - * @param wtopx - * @param wtopy - * @param ww - * @param wh - * @param markerSytleList - * @param markerSizeList - * @param colorList + * @brief Main constructor that creates and initializes the canvas. + * + * Creates the ROOT canvas window with custom menu, installs an IPC message + * queue timer for monitoring data updates, and initializes the plotting style. + * + * @param title canvas window title + * @param wtopx x-position of window on screen + * @param wtopy y-position of window on screen + * @param ww window width in pixels + * @param wh window height in pixels + * @param markerSytleList vector of ROOT marker style codes from config + * @param markerSizeList vector of marker sizes from config + * @param colorList vector of ROOT color codes from config + * @param mupp_instance instance number (0-255) for IPC identification */ PMuppCanvas::PMuppCanvas(const Char_t *title, Int_t wtopx, Int_t wtopy, Int_t ww, Int_t wh, const PIntVector markerSytleList, diff --git a/src/musredit_qt6/mupp/plotter/PMuppCanvas.h b/src/musredit_qt6/mupp/plotter/PMuppCanvas.h index 092cb9f17..b129e5307 100644 --- a/src/musredit_qt6/mupp/plotter/PMuppCanvas.h +++ b/src/musredit_qt6/mupp/plotter/PMuppCanvas.h @@ -5,6 +5,19 @@ Author: Andreas Suter e-mail: andreas.suter@psi.ch + This header defines the PMuppCanvas class, which provides the main plotting + canvas for the mupp_plot application. It handles: + - ROOT canvas creation and management + - Multi-graph plotting with error bars + - IPC communication with the mupp GUI + - User interactions (keyboard commands, menu selections) + - Data import/export functionality + - Plot styling (markers, colors, lines) + + The canvas monitors an IPC message queue for data updates from the mupp + GUI and refreshes the plots accordingly. It supports interactive features + like toggling between line and marker display, exporting data, and zoom. + ***************************************************************************/ /*************************************************************************** @@ -52,76 +65,211 @@ #define P_MENU_ID_ABOUT 10003 //-------------------------------------------------------------------------- +/** + * @brief Structure holding a single data point with asymmetric errors. + * + * Stores a y-value and its corresponding positive and negative error bars. + * Used for representing data points with asymmetric uncertainties in plots. + */ struct PDataPoint { - Double_t y; - Double_t eYpos; - Double_t eYneg; + Double_t y; ///< y-value of the data point + Double_t eYpos; ///< positive error (upward) + Double_t eYneg; ///< negative error (downward) }; //-------------------------------------------------------------------------- +/** + * @brief Structure holding a complete data collection for plotting. + * + * Contains all data needed to plot one or more y-variables against a common + * x-variable. Supports multiple y-datasets per collection, each with its own + * label and data points (with asymmetric errors). + * + * Example usage: plotting multiple fit parameters (T1, sigma, etc.) versus + * run number or temperature. + */ struct PDataCollection { - TString name; // collection name - TString xLabel; - PStringVector yLabel; - PDoubleVector xValue; - std::vector< std::vector > yValue; + TString name; ///< collection name (typically the file or dataset name) + TString xLabel; ///< label for the x-axis + PStringVector yLabel; ///< labels for each y-dataset + PDoubleVector xValue; ///< x-values (common to all y-datasets) + std::vector< std::vector > yValue; ///< y-values with errors for each dataset }; //-------------------------------------------------------------------------- +/** + * @brief The PMuppCanvas class provides the main plotting canvas. + * + * This class manages the ROOT canvas for displaying multi-graph plots with + * error bars. It communicates with the mupp GUI via IPC message queues to + * receive plot data updates and provides an interactive interface for viewing + * and manipulating plots. + * + * Features: + * - Multi-graph plotting with asymmetric error bars + * - Configurable marker styles, sizes, and colors + * - Toggle between line and marker display modes + * - Data export to text files + * - Keyboard shortcuts ('q' quit, 'l' toggle lines, 'b' about) + * - Menu interface for common operations + * - Automatic refresh when data updates arrive via IPC + * + * The canvas polls an IPC message queue every 200ms to check for data updates + * from the mupp GUI. When new data arrives, it reads the plot data file and + * refreshes the display. + */ class PMuppCanvas : public TObject, public TQObject { public: + /** + * @brief Default constructor (creates an invalid canvas). + */ PMuppCanvas(); + + /** + * @brief Constructor that creates and initializes the canvas. + * @param title canvas window title + * @param wtopx canvas window x-position on screen + * @param wtopy canvas window y-position on screen + * @param ww canvas window width in pixels + * @param wh canvas window height in pixels + * @param markerSytleList vector of ROOT marker style codes + * @param markerSizeList vector of marker sizes + * @param colorList vector of ROOT color codes + * @param mupp_instance instance number (0-255) for IPC identification + */ PMuppCanvas(const Char_t* title, Int_t wtopx, Int_t wtopy, Int_t ww, Int_t wh, const PIntVector markerSytleList, const PDoubleVector markerSizeList, const PIntVector colorList, const int mupp_instance); + /** + * @brief Checks if the canvas was initialized successfully. + * @return true if valid, false otherwise + */ virtual Bool_t IsValid() { return fValid; } + /** + * @brief Signal emitted when the application should terminate. + * @param status exit status code (default 0) + */ virtual void Done(Int_t status=0); // *SIGNAL* + + /** + * @brief Slot that handles keyboard events. + * + * Processes command keys: + * - 'q': quit application + * - 'l': toggle line display + * - 'b': show about dialog + * + * @param event event type (must be kKeyPress) + * @param x character key code + * @param y unused + * @param selected unused + */ virtual void HandleCmdKey(Int_t event, Int_t x, Int_t y, TObject *selected); // SLOT + + /** + * @brief Slot that handles menu selections. + * @param id menu item ID + */ virtual void HandleMenuPopup(Int_t id); // SLOT + + /** + * @brief Slot called when the last canvas is closed. + * + * Emits Done(0) to terminate the application. + */ virtual void LastCanvasClosed(); // SLOT + + /** + * @brief Slot called when the canvas window is closed. + * + * Removes the canvas from ROOT's list and calls LastCanvasClosed(). + */ virtual void WindowClosed(); // SLOT + /** + * @brief Checks the IPC message queue for plot data updates. + * + * Called by a timer every 200ms. If a message is present, reads the plot + * data file and updates the graphs. + */ virtual void CheckIPCMsgQueue(); private: - Bool_t fValid; - Int_t fMuppInstance; + Bool_t fValid; ///< flag indicating whether canvas initialization succeeded + Int_t fMuppInstance; ///< mupp instance number (0-255) for IPC identification - TString fFtokName; - std::unique_ptr fCheckMsgQueue; ///< timer needed to check if a message in the IPC message queue is pending + TString fFtokName; ///< file token name for IPC message queue identification + std::unique_ptr fCheckMsgQueue; ///< timer that triggers IPC message queue polling every 200ms - std::vector fPlotData; + std::vector fPlotData; ///< vector of all data collections to be plotted - std::unique_ptr fStyle; ///< A collection of all graphics attributes + std::unique_ptr fStyle; ///< ROOT style object defining global graphics attributes - // canvas menu related variables + // Canvas menu related variables TRootCanvas *fImp; ///< ROOT native GUI version of main window with menubar and drawing area - TGMenuBar *fBar; ///< menu bar - TGPopupMenu *fPopupMain; ///< popup menu mupp in the main menu bar + TGMenuBar *fBar; ///< menu bar at the top of the canvas window + TGPopupMenu *fPopupMain; ///< popup menu "mupp" in the main menu bar - // canvas related variables - std::unique_ptr fMainCanvas; ///< main canvas - std::unique_ptr fMultiGraph; ///< main multi graph - std::vector fGraphE; ///< all error graphs + // Canvas and graph related variables + std::unique_ptr fMainCanvas; ///< main ROOT canvas for plotting + std::unique_ptr fMultiGraph; ///< multi-graph container holding all plot graphs + std::vector fGraphE; ///< vector of TGraphAsymmErrors, one per y-dataset - // perdefined markers, colors - PIntVector fMarkerStyleList; - PDoubleVector fMarkerSizeList; - PIntVector fColorList; + // Predefined markers, sizes, and colors + PIntVector fMarkerStyleList; ///< list of marker styles (from mupp_startup.xml or defaults) + PDoubleVector fMarkerSizeList; ///< list of marker sizes (from mupp_startup.xml or defaults) + PIntVector fColorList; ///< list of colors (from mupp_startup.xml or defaults) - bool fWithLines{false}; + bool fWithLines{false}; ///< flag indicating whether to draw lines connecting data points + /** + * @brief Creates and configures the ROOT style object. + * + * Sets up default graphics attributes for the canvas and plots. + */ virtual void CreateStyle(); + + /** + * @brief Initializes the canvas window and menu structure. + * @param title window title + * @param wtopx x-position on screen + * @param wtopy y-position on screen + * @param ww window width + * @param wh window height + */ virtual void InitMuppCanvas(const Char_t* title, Int_t wtopx, Int_t wtopy, Int_t ww, Int_t wh); + /** + * @brief Reads plot data from a file. + * @param fln file name/path of the plot data file + * @return 0 on success, non-zero on error + */ virtual int ReadPlotData(const Char_t *fln); + + /** + * @brief Initializes (clears) a data collection structure. + * @param coll reference to the data collection to initialize + */ virtual void InitDataCollection(PDataCollection &coll); + + /** + * @brief Updates the graphs with current plot data. + * + * Recreates all TGraphAsymmErrors objects from fPlotData and redraws the canvas. + */ virtual void UpdateGraphs(); + + /** + * @brief Exports plot data to a text file. + * + * Opens a file dialog for the user to select output file and writes + * all data collections in a human-readable format. + */ virtual void ExportData(); ClassDef(PMuppCanvas, 1) diff --git a/src/musredit_qt6/mupp/plotter/PMuppStartupHandler.cpp b/src/musredit_qt6/mupp/plotter/PMuppStartupHandler.cpp index ac5a76848..a4f79f5f7 100644 --- a/src/musredit_qt6/mupp/plotter/PMuppStartupHandler.cpp +++ b/src/musredit_qt6/mupp/plotter/PMuppStartupHandler.cpp @@ -5,6 +5,26 @@ Author: Andreas Suter e-mail: andreas.suter@psi.ch + This file implements the PMuppStartupHandler class, a SAX parser handler + for reading mupp_startup.xml configuration files. + + The implementation: + - Searches for mupp_startup.xml in current directory or $HOME/.musrfit/mupp/ + - Parses marker styles, sizes, and colors using ROOT's SAX parser + - Generates random defaults if file is not found or lists are incomplete + - Provides a parseXmlFile() utility function for reliable XML parsing + + SAX Parsing Flow: + 1. OnStartDocument() - initialize state + 2. OnStartElement() - detect marker/color blocks + 3. OnCharacters() - extract numeric values and color names + 4. OnEndElement() - finalize current block + 5. OnEndDocument() - validate lists with CheckLists() + + The CheckLists() method ensures all three lists (marker styles, sizes, + colors) have the same length, generating random values as needed for + consistency. + ***************************************************************************/ /*************************************************************************** @@ -79,7 +99,13 @@ int parseXmlFile(TSAXParser *saxParser, const char *startup_path_name) // Constructor //-------------------------------------------------------------------------- /** - * @brief PMuppStartupHandler::PMuppStartupHandler + * @brief Constructor that searches for mupp_startup.xml configuration file. + * + * Search order: + * 1. ./mupp_startup.xml (current directory) + * 2. $HOME/.musrfit/mupp/mupp_startup.xml (user configuration directory) + * + * Sets fStartupFileFound and fStartupFilePath based on search results. */ PMuppStartupHandler::PMuppStartupHandler() { @@ -116,7 +142,9 @@ PMuppStartupHandler::PMuppStartupHandler() // Destructor //-------------------------------------------------------------------------- /** - * @brief PMuppStartupHandler::~PStartupHandler + * @brief Destructor that cleans up style list vectors. + * + * Clears all marker style, size, and color list vectors to free memory. */ PMuppStartupHandler::~PMuppStartupHandler() { diff --git a/src/musredit_qt6/mupp/plotter/PMuppStartupHandler.h b/src/musredit_qt6/mupp/plotter/PMuppStartupHandler.h index 3bb4c6adf..b995cc647 100644 --- a/src/musredit_qt6/mupp/plotter/PMuppStartupHandler.h +++ b/src/musredit_qt6/mupp/plotter/PMuppStartupHandler.h @@ -5,6 +5,21 @@ Author: Andreas Suter e-mail: andreas.suter@psi.ch + This header defines the PMuppStartupHandler class, which parses the + mupp_startup.xml configuration file using ROOT's SAX (Simple API for XML) + parser. + + The configuration file defines plot styling attributes: + - Marker styles (circle, square, triangle, etc.) + - Marker sizes + - Color schemes + + The handler searches for mupp_startup.xml in: + 1. Current directory (./mupp_startup.xml) + 2. User's home directory ($HOME/.musrfit/mupp/mupp_startup.xml) + + If the file is not found or parsing fails, default random styles are used. + ***************************************************************************/ /*************************************************************************** @@ -42,46 +57,184 @@ #include "mupp_plot.h" //-------------------------------------------------------------------------- -// This function is a replacement for the ParseFile method of TSAXParser. +/** + * @brief Replacement for TSAXParser::ParseFile that works in more environments. + * + * This function reads the entire XML file into memory and uses ParseBuffer + * instead of ParseFile, which is more reliable in certain system environments + * where ParseFile fails. + * + * @param saxParser pointer to a TSAXParser object + * @param startup_path_name full path to the XML file to parse + * @return 0 on success, 1 if file cannot be read, or SAX parser error code + */ //-------------------------------------------------------------------------- int parseXmlFile(TSAXParser*, const char*); +/** + * @brief The PMuppStartupHandler class parses mupp_startup.xml configuration. + * + * This SAX parser handler reads the mupp plotting configuration file and + * extracts marker styles, sizes, and colors for use in plot display. + * + * XML Structure: + * @code + * + * + * + * 1.2 + * + * + * kBlue + * + * + * @endcode + * + * The handler implements ROOT's TSAXParser callback interface, processing + * XML events as the file is parsed. If parsing succeeds, the style lists + * are populated; otherwise, CheckLists() generates random defaults. + */ class PMuppStartupHandler : public TObject, public TQObject { public: + /** + * @brief Constructor that searches for mupp_startup.xml. + * + * Searches in current directory first, then in $HOME/.musrfit/mupp/. + * Sets fStartupFileFound flag if file is located. + */ PMuppStartupHandler(); + + /** + * @brief Destructor that cleans up style lists. + */ virtual ~PMuppStartupHandler(); + /** + * @brief SAX callback: called at the start of XML document parsing. + * + * Initializes parser state variables. + */ virtual void OnStartDocument(); // SLOT + + /** + * @brief SAX callback: called at the end of XML document parsing. + * + * Calls CheckLists() to validate or generate default style lists. + */ virtual void OnEndDocument(); // SLOT - virtual void OnStartElement(const Char_t*, const TList*); // SLOT - virtual void OnEndElement(const Char_t*); // SLOT - virtual void OnCharacters(const Char_t*); // SLOT - virtual void OnComment(const Char_t*); // SLOT - virtual void OnWarning(const Char_t*); // SLOT - virtual void OnError(const Char_t*); // SLOT - virtual void OnFatalError(const Char_t*); // SLOT - virtual void OnCdataBlock(const Char_t*, Int_t); // SLOT - virtual Bool_t StartupFileFound() { return fStartupFileFound; } ///< true = mupp_startup.xml found - virtual TString GetStartupFilePath() { return fStartupFilePath; } ///< returns FULLPATH/mupp_startup.xml, where FULLPATH=path were the mupp_startup.xml is found + /** + * @brief SAX callback: called when an XML element starts. + * @param name element name (e.g., "marker", "color", "style") + * @param attributes list of element attributes (unused in mupp_startup.xml) + */ + virtual void OnStartElement(const Char_t* name, const TList* attributes); // SLOT + /** + * @brief SAX callback: called when an XML element ends. + * @param name element name + */ + virtual void OnEndElement(const Char_t* name); // SLOT + + /** + * @brief SAX callback: called for character data within elements. + * @param characters the text content (e.g., marker style number, color name) + */ + virtual void OnCharacters(const Char_t* characters); // SLOT + + /** + * @brief SAX callback: called for XML comments (not used). + * @param comment the comment text + */ + virtual void OnComment(const Char_t* comment); // SLOT + + /** + * @brief SAX callback: called for parsing warnings. + * @param warning the warning message + */ + virtual void OnWarning(const Char_t* warning); // SLOT + + /** + * @brief SAX callback: called for parsing errors. + * @param error the error message + */ + virtual void OnError(const Char_t* error); // SLOT + + /** + * @brief SAX callback: called for fatal parsing errors. + * @param fatalerror the fatal error message + */ + virtual void OnFatalError(const Char_t* fatalerror); // SLOT + + /** + * @brief SAX callback: called for CDATA blocks (not used). + * @param cdata the CDATA text + * @param len length of the CDATA block + */ + virtual void OnCdataBlock(const Char_t* cdata, Int_t len); // SLOT + + /** + * @brief Checks if mupp_startup.xml was found. + * @return true if startup file exists, false otherwise + */ + virtual Bool_t StartupFileFound() { return fStartupFileFound; } + + /** + * @brief Gets the full path to mupp_startup.xml. + * @return full path where mupp_startup.xml was found (or empty if not found) + */ + virtual TString GetStartupFilePath() { return fStartupFilePath; } + + /** + * @brief Validates style lists and generates defaults if needed. + * + * Called after parsing. If lists are empty or sizes don't match, generates + * random default marker styles, sizes, and colors. + */ virtual void CheckLists(); - virtual const PIntVector GetMarkerStyleList() const { return fMarkerStyleList; } ///< returns the marker style list - virtual const PDoubleVector GetMarkerSizeList() const { return fMarkerSizeList; } ///< returns the marker size list - virtual const PIntVector GetColorList() const { return fColorList; } ///< returns the color list + /** + * @brief Gets the marker style list. + * @return vector of ROOT marker style codes + */ + virtual const PIntVector GetMarkerStyleList() const { return fMarkerStyleList; } + + /** + * @brief Gets the marker size list. + * @return vector of marker sizes + */ + virtual const PDoubleVector GetMarkerSizeList() const { return fMarkerSizeList; } + + /** + * @brief Gets the color list. + * @return vector of ROOT color codes + */ + virtual const PIntVector GetColorList() const { return fColorList; } private: - enum EKeyWords {eEmpty, eMarker, eColor}; - EKeyWords fKey; ///< xml filter key + /** + * @brief Enumeration for XML parsing state. + */ + enum EKeyWords { + eEmpty, ///< not inside a marker or color block + eMarker, ///< parsing marker element + eColor ///< parsing color element + }; - Bool_t fStartupFileFound; ///< startup file found flag - TString fStartupFilePath; ///< full mupp_startup.xml startup file paths - PIntVector fMarkerStyleList; ///< marker style list - PDoubleVector fMarkerSizeList; ///< marker size list - PIntVector fColorList; ///< color list + EKeyWords fKey; ///< current XML parsing state + Bool_t fStartupFileFound; ///< true if mupp_startup.xml was located + TString fStartupFilePath; ///< full path to mupp_startup.xml + PIntVector fMarkerStyleList; ///< parsed marker style codes + PDoubleVector fMarkerSizeList; ///< parsed marker sizes + PIntVector fColorList; ///< parsed color codes + + /** + * @brief Checks if a file exists and is readable. + * @param fln file name/path to check + * @return true if file exists and can be opened for reading, false otherwise + */ Bool_t StartupFileExists(Char_t *fln); ClassDef(PMuppStartupHandler, 1) diff --git a/src/musredit_qt6/mupp/plotter/mupp_plot.cpp b/src/musredit_qt6/mupp/plotter/mupp_plot.cpp index d24037466..7ac0650b4 100644 --- a/src/musredit_qt6/mupp/plotter/mupp_plot.cpp +++ b/src/musredit_qt6/mupp/plotter/mupp_plot.cpp @@ -5,6 +5,21 @@ Author: Andreas Suter e-mail: andreas.suter@psi.ch + This is the main entry point for the mupp_plot application, a standalone + ROOT-based plotting program that works in conjunction with the mupp GUI. + + The program: + - Takes a mupp instance number (0-255) as a command-line argument + - Reads plot styling configuration from mupp_startup.xml + - Creates a ROOT application with a PMuppCanvas for displaying plots + - Establishes IPC communication with the mupp GUI via message queues + - Monitors for plot data updates and refreshes the display accordingly + - Provides interactive features (zoom, export, line/marker toggle) + + The mupp_plot application runs as a separate process from the main mupp + GUI, allowing plots to be displayed and manipulated independently while + maintaining synchronization with the data analysis workflow. + ***************************************************************************/ /*************************************************************************** @@ -39,10 +54,22 @@ //-------------------------------------------------------------------------- /** - * @brief main - * @param argc - * @param argv - * @return + * @brief Main entry point for the mupp_plot application. + * + * Initializes the ROOT plotting environment, reads configuration from + * mupp_startup.xml, creates the canvas, and runs the ROOT event loop. + * + * The program flow: + * 1. Validates command-line arguments (mupp instance number) + * 2. Parses mupp_startup.xml for marker styles, sizes, and colors + * 3. Creates a TApplication and PMuppCanvas + * 4. Sets up signal/slot connections for window management + * 5. Runs the ROOT event loop + * 6. Cleans up resources on exit + * + * @param argc number of command-line arguments (must be 2) + * @param argv command-line arguments array; argv[1] must be instance number (0-255) + * @return exit status: 0 on success, -1 if argc != 2, -2 if instance number out of range */ int main(int argc, char *argv[]) { diff --git a/src/musredit_qt6/mupp/plotter/mupp_plot.h b/src/musredit_qt6/mupp/plotter/mupp_plot.h index c92eb3d0e..4f363a9e0 100644 --- a/src/musredit_qt6/mupp/plotter/mupp_plot.h +++ b/src/musredit_qt6/mupp/plotter/mupp_plot.h @@ -1,10 +1,24 @@ /*************************************************************************** - + mupp_plot.h - + Author: Andreas Suter e-mail: andreas.suter@psi.ch - + + This header file defines common type aliases used throughout the mupp_plot + application. These type definitions provide cleaner, more readable code by + wrapping STL container types with ROOT types. + + The file defines vector types for: + - Boolean values (for flags and state tracking) + - Integer values (for indices, IDs, and counts) + - Double values (for numerical data and coordinates) + - String values (for labels and names) + - Pair types (for x-y coordinates and ranges) + + These types are used extensively in the PMuppCanvas and related classes + for managing plot data, markers, colors, and other graphical attributes. + ***************************************************************************/ /*************************************************************************** @@ -38,55 +52,83 @@ //------------------------------------------------------------- /** - *

typedef to make to code more readable. Definition of a bool vector. + * @brief Type alias for a vector of boolean values. + * + * Used for storing flags, selection states, and boolean properties + * in the plotting system. */ typedef std::vector PBoolVector; //------------------------------------------------------------- /** - *

typedef to make to code more readable. Definition of an unsigned int vector + * @brief Type alias for a vector of unsigned integer values. + * + * Used for storing counts, indices, and other non-negative integer + * quantities in the plotting system. */ typedef std::vector PUIntVector; //------------------------------------------------------------- /** - *

typedef to make to code more readable. Definition of an int vector + * @brief Type alias for a vector of integer values. + * + * Used extensively for storing marker styles, color indices, and + * other integer properties in the plotting system. */ typedef std::vector PIntVector; //------------------------------------------------------------- /** - *

typedef to make to code more readable. Definition of an int pair + * @brief Type alias for a pair of integer values. + * + * Used for representing integer coordinate pairs, ranges, or + * index pairs in the plotting system. */ typedef std::pair PIntPair; //------------------------------------------------------------- /** - *

typedef to make to code more readable. Definition of an int pair vector + * @brief Type alias for a vector of integer pairs. + * + * Used for storing multiple integer coordinate pairs or ranges + * in the plotting system. */ typedef std::vector PIntPairVector; //------------------------------------------------------------- /** - *

typedef to make to code more readable. Definition of a double vector + * @brief Type alias for a vector of double-precision values. + * + * Used extensively for storing data points, marker sizes, axis values, + * and other floating-point quantities in the plotting system. */ typedef std::vector PDoubleVector; //------------------------------------------------------------- /** - *

typedef to make to code more readable. Definition of a double pair + * @brief Type alias for a pair of double-precision values. + * + * Used for representing coordinate pairs, data ranges, or error bounds + * in the plotting system. */ typedef std::pair PDoublePair; //------------------------------------------------------------- /** - *

typedef to make to code more readable. Definition of a double pair vector + * @brief Type alias for a vector of double pairs. + * + * Used for storing multiple coordinate pairs, data ranges, or + * error bounds in the plotting system. */ typedef std::vector PDoublePairVector; //------------------------------------------------------------- /** - *

typedef to make to code more readable. Definition of a string vector + * @brief Type alias for a vector of ROOT strings. + * + * Used for storing labels, names, titles, and other text data + * in the plotting system. Uses ROOT's TString for compatibility + * with ROOT graphics classes. */ typedef std::vector PStringVector;