diff --git a/src/musredit_qt6/musredit/PDumpOutputHandler.cpp b/src/musredit_qt6/musredit/PDumpOutputHandler.cpp index f049bcb1e..9bb32a7b9 100644 --- a/src/musredit_qt6/musredit/PDumpOutputHandler.cpp +++ b/src/musredit_qt6/musredit/PDumpOutputHandler.cpp @@ -27,6 +27,19 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PDumpOutputHandler.cpp + * @brief Implementation of the PDumpOutputHandler class. + * @details This file implements the PDumpOutputHandler dialog which executes + * the dump_header command and displays its output. The implementation handles + * process lifecycle management, output capture, and proper cleanup. + * + * @author Andreas Suter + * @date 2012-2025 + * @copyright Copyright (C) 2012-2025 by Andreas Suter + * @license GNU General Public License v2 or later + */ + #include #include @@ -35,9 +48,25 @@ //---------------------------------------------------------------------------------------------------- /** - *

Sets up the dump output handler GUI and starts the actual dump_header command + * @brief Constructs the dump output handler dialog and starts the command. * - * \param cmd command string vector. From this the actual dump_header command will be generated and executed. + * @details Initializes the dialog UI and starts the dump_header process. The + * constructor performs the following steps: + * -# Creates the dialog layout with a text output area and Quit button + * -# Configures the process environment with appropriate library paths + * -# Extracts the program and arguments from the command vector + * -# Starts the process and connects output signals to display slots + * + * @par Environment Configuration: + * - On macOS: Sets DYLD_LIBRARY_PATH to include $ROOTSYS/lib + * - On Linux: Sets LD_LIBRARY_PATH to include $ROOTSYS/lib + * + * @param cmd Command vector where cmd[0] is the executable path and + * subsequent elements are command-line arguments. + * + * @note If the command vector is empty, the constructor returns immediately + * without creating the UI. If the process fails to start, an error dialog + * is displayed. */ PDumpOutputHandler::PDumpOutputHandler(QVector &cmd) { @@ -92,7 +121,17 @@ PDumpOutputHandler::PDumpOutputHandler(QVector &cmd) //---------------------------------------------------------------------------------------------------- /** - *

Destructor. Checks if the a dump_header is still running and if yes try to kill it. + * @brief Destructor - ensures the dump_header process is terminated. + * + * @details Performs cleanup by ensuring the child process is properly terminated. + * The termination sequence is: + * -# Attempt graceful termination with QProcess::terminate() + * -# Wait for process to finish + * -# If still running, use QProcess::kill() + * -# As a last resort, use system kill -9 command + * + * This multi-stage approach ensures the process doesn't become orphaned, + * even if it doesn't respond to normal termination signals. */ PDumpOutputHandler::~PDumpOutputHandler() { @@ -114,7 +153,12 @@ PDumpOutputHandler::~PDumpOutputHandler() //---------------------------------------------------------------------------------------------------- /** - *

Captures the standard output and adds it to the output text edit. + * @brief Slot to capture and display standard output from the process. + * + * @details Reads all available data from the process's standard output stream + * and appends it to the text display widget. This slot is connected to the + * QProcess::readyReadStandardOutput signal and may be called multiple times + * as output arrives in chunks. */ void PDumpOutputHandler::readFromStdOut() { @@ -125,7 +169,15 @@ void PDumpOutputHandler::readFromStdOut() //---------------------------------------------------------------------------------------------------- /** - *

Captures the standard error and adds it to the output text edit. + * @brief Slot to capture and display standard error from the process. + * + * @details Reads all available data from the process's standard error stream + * and appends it to the text display widget. This slot is connected to the + * QProcess::readyReadStandardError signal and may be called multiple times + * as error output arrives in chunks. + * + * Error output is displayed alongside normal output in the same text widget, + * allowing users to see errors in context with regular output. */ void PDumpOutputHandler::readFromStdErr() { @@ -136,8 +188,15 @@ void PDumpOutputHandler::readFromStdErr() //---------------------------------------------------------------------------------------------------- /** - *

If the quit button is pressed while the dump_header is still running, try to terminate dump_header, if this - * does not work, try to kill dump_header. + * @brief Slot called when the Quit button is pressed. + * + * @details Handles user request to close the dialog. If the dump_header process + * is still running, attempts to terminate it gracefully using QProcess::terminate(). + * If graceful termination fails within the timeout period, forcefully kills + * the process using QProcess::kill(). + * + * After ensuring the process is stopped, accepts the dialog (closes it with + * QDialog::Accepted result). */ void PDumpOutputHandler::quitButtonPressed() { diff --git a/src/musredit_qt6/musredit/PDumpOutputHandler.h b/src/musredit_qt6/musredit/PDumpOutputHandler.h index fb4f6c71f..19adb4bf8 100644 --- a/src/musredit_qt6/musredit/PDumpOutputHandler.h +++ b/src/musredit_qt6/musredit/PDumpOutputHandler.h @@ -27,6 +27,22 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PDumpOutputHandler.h + * @brief Dialog for displaying dump_header command output. + * @details This header defines the PDumpOutputHandler class which provides + * a dialog window for executing the dump_header tool and displaying its + * output in real-time. The dump_header tool is used to display header + * information from muon data files. + * + * @author Andreas Suter + * @date 2012-2025 + * @copyright Copyright (C) 2012-2025 by Andreas Suter + * @license GNU General Public License v2 or later + * + * @see PFitOutputHandler For similar output handling during fitting + */ + #ifndef _PDUMPOUTPUTHANDLER_H_ #define _PDUMPOUTPUTHANDLER_H_ @@ -44,9 +60,34 @@ //--------------------------------------------------------------------------------------- /** - *

This class is the capturing the output of musrfit and displays it in a dialog so - * the user has the chance to follow the fitting process, warnings, error messages of - * musrfit. + * @class PDumpOutputHandler + * @brief Dialog for executing and displaying dump_header command output. + * + * @details This class provides a modal dialog that executes the dump_header + * external command and displays its output in real-time. The dump_header tool + * is part of the musrfit suite and extracts header information from muon spin + * rotation/relaxation data files. + * + * @par Features: + * - Executes dump_header as a child process via QProcess + * - Captures both stdout and stderr output + * - Displays output in a read-only text widget + * - Provides a Quit button to terminate the process + * - Handles process cleanup on dialog close + * + * @par Usage: + * @code + * QVector cmd; + * cmd << "/path/to/dump_header" << "-f" << "datafile.root"; + * PDumpOutputHandler dialog(cmd); + * dialog.exec(); + * @endcode + * + * @par Platform Notes: + * - On macOS, sets DYLD_LIBRARY_PATH for ROOT library access + * - On Linux, sets LD_LIBRARY_PATH for ROOT library access + * + * @see PFitOutputHandler For similar handling of musrfit output */ class PDumpOutputHandler : public QDialog { @@ -57,17 +98,38 @@ class PDumpOutputHandler : public QDialog virtual ~PDumpOutputHandler(); private slots: + /** + * @brief Slot to read and display standard output from the process. + */ virtual void readFromStdOut(); + + /** + * @brief Slot to read and display standard error from the process. + */ virtual void readFromStdErr(); + + /** + * @brief Slot called when the Quit button is pressed. + */ virtual void quitButtonPressed(); -private: - qint64 fProcPID; ///< keeps the process PID - std::unique_ptr fProc; ///< pointer to the dump_header process + private: + /** @name Process Management + * @brief Members for managing the external process. + * @{ + */ + qint64 fProcPID; ///< Process ID of the running dump_header command. + std::unique_ptr fProc; ///< QProcess object managing the dump_header execution. + /** @} */ - std::unique_ptr fVbox; ///< pointer to the dialog layout manager - std::unique_ptr fOutput; ///< the captured dump_header output is written (read only) into this text edit object. - std::unique_ptr fQuitButton; ///< quit button + /** @name UI Components + * @brief Dialog user interface elements. + * @{ + */ + std::unique_ptr fVbox; ///< Vertical layout manager for dialog widgets. + std::unique_ptr fOutput; ///< Read-only text widget displaying command output. + std::unique_ptr fQuitButton; ///< Button to close dialog and terminate process. + /** @} */ }; #endif // _PDUMPOUTPUTHANDLER_H_