From a40c431396fc211e238e2600932a15246f390e43 Mon Sep 17 00:00:00 2001 From: Andreas Suter Date: Fri, 14 Nov 2025 07:57:06 +0100 Subject: [PATCH] improve doxygen documentation of PMsgBox.* --- src/classes/PMsgBox.cpp | 72 +++++++++++++++++++++++++++++++++++++++-- src/include/PMsgBox.h | 55 ++++++++++++++++++++++++++++++- 2 files changed, 123 insertions(+), 4 deletions(-) diff --git a/src/classes/PMsgBox.cpp b/src/classes/PMsgBox.cpp index 4e939cd62..29b49e8af 100644 --- a/src/classes/PMsgBox.cpp +++ b/src/classes/PMsgBox.cpp @@ -29,10 +29,42 @@ #include "PMsgBox.h" +//-------------------------------------------------------------------------- +// Constructor +//-------------------------------------------------------------------------- +/** + * \brief Constructor that creates and displays the message box GUI. + * + * This constructor performs the following steps: + * 1. Creates a scrollable list box widget + * 2. Parses the error message string by splitting at newline characters + * 3. Populates the list box with individual message lines + * 4. Creates an Exit button with callback to DoExit() + * 5. Configures layout and displays the window + * + * The message parsing algorithm: + * - Adds an initial empty line + * - Splits the input string at each '\n' character + * - Each substring becomes a separate list box entry + * - Handles multi-line messages gracefully + * + * GUI Layout: + * - List box: 600x200 pixels, expandable, with 5-pixel margins + * - Button frame: Fixed width (150px), contains Exit button + * - Window title: "Error Message" + * + * \param errMsg Multi-line error message string with '\n' separators + * \param p Parent window pointer (typically gClient->GetRoot()) + * \param w Initial window width in pixels + * \param h Initial window height in pixels + * + * \note The window is automatically mapped (displayed) after construction + * \note The list box ID is set to 89 (ROOT widget identifier) + */ PMsgBox::PMsgBox(const std::string errMsg, const TGWindow *p, UInt_t w, UInt_t h) : TGMainFrame(p, w, h) { fListBox = new TGListBox(this, 89); - + // feed list box with errMsg size_t start = 0; size_t end = errMsg.find("\n"); @@ -45,7 +77,7 @@ PMsgBox::PMsgBox(const std::string errMsg, const TGWindow *p, UInt_t w, UInt_t h end = errMsg.find("\n", start); fListBox->AddEntry(tok.c_str(), i++); } - + fListBox->Resize(600, 200); AddFrame(fListBox, new TGLayoutHints(kLHintsTop | kLHintsLeft | kLHintsExpandX | kLHintsExpandY, 5, 5, 5, 5)); @@ -67,11 +99,45 @@ PMsgBox::PMsgBox(const std::string errMsg, const TGWindow *p, UInt_t w, UInt_t h MapWindow(); } +//-------------------------------------------------------------------------- +// Destructor +//-------------------------------------------------------------------------- +/** + * \brief Destructor that cleans up the message box resources. + * + * The ROOT framework automatically handles cleanup of GUI components + * (list box, buttons, frames) through the TGMainFrame destructor chain, + * so no explicit cleanup is required here. + * + * \note GUI widgets are managed by ROOT and are automatically deleted + * when the main frame is destroyed + */ PMsgBox::~PMsgBox() { - // nothing to be done here? + // nothing to be done here - ROOT handles GUI cleanup automatically } +//-------------------------------------------------------------------------- +// DoExit +//-------------------------------------------------------------------------- +/** + * \brief Exit button callback that terminates the application. + * + * This method is invoked when the user clicks the Exit button. + * It terminates the entire ROOT application with exit code 0, + * which causes a clean shutdown of the program. + * + * The method is connected to the Exit button's "Pressed()" signal + * in the constructor via ROOT's signal/slot mechanism: + * \code + * exit->Connect("Pressed()", "PMsgBox", this, "DoExit()"); + * \endcode + * + * \note This terminates the entire application, not just the message box window + * \note Exit code 0 indicates successful termination + * + * \see gApplication for ROOT's global application object + */ void PMsgBox::DoExit() { gApplication->Terminate(0); diff --git a/src/include/PMsgBox.h b/src/include/PMsgBox.h index 2abfecc6b..9b4e812bb 100644 --- a/src/include/PMsgBox.h +++ b/src/include/PMsgBox.h @@ -38,14 +38,67 @@ #include #include +//-------------------------------------------------------------------------- +/** + * \brief GUI message box for displaying error messages and warnings. + * + * PMsgBox is a ROOT-based GUI window that displays multi-line error messages + * in a scrollable list box. It provides a simple, modal-like interface for + * showing diagnostic information to the user. + * + * The message box: + * - Parses multi-line error messages (separated by newline characters) + * - Displays each line in a scrollable list box + * - Provides an Exit button that terminates the application + * - Uses ROOT's TGMainFrame for window management + * + * Typical use case: + * \code + * std::string errorMsg = "Error parsing file:\nLine 42: Invalid syntax\nAborting..."; + * PMsgBox msgBox(errorMsg, gClient->GetRoot(), 640, 240); + * \endcode + * + * \see TGMainFrame for the base class + */ class PMsgBox : public TGMainFrame { private: - TGListBox *fListBox; + TGListBox *fListBox; ///< List box widget displaying error message lines public: + //----------------------------------------------------------------------- + /** + * \brief Constructor that creates and displays the message box window. + * + * Creates a GUI window containing: + * - A scrollable list box with the parsed error message + * - An Exit button that terminates the application + * + * The error message is split at newline characters, and each line is + * displayed as a separate entry in the list box. + * + * \param errMsg Multi-line error message string (lines separated by '\n') + * \param p Parent window (typically gClient->GetRoot()) + * \param w Window width in pixels + * \param h Window height in pixels + */ PMsgBox(const std::string errMsg, const TGWindow *p, UInt_t w, UInt_t h); + + //----------------------------------------------------------------------- + /** + * \brief Destructor that cleans up the message box resources. + */ ~PMsgBox() override; + + //----------------------------------------------------------------------- + /** + * \brief Exit button callback that terminates the application. + * + * This method is called when the user clicks the Exit button. + * It terminates the entire application with exit code 0. + * + * \note This will exit the entire application, not just close the window + */ void DoExit(); ClassDefOverride(PMsgBox, 0)