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

improve the doxygen docu of PDumpOutputHandler.* (musredit_qt6).

Browse Source
This commit is contained in:
suter_a
2025-11-24 10:48:14 +01:00
parent eb807ade7b
commit b714c8d170
2 changed files with 137 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
src/musredit_qt6/musredit/PDumpOutputHandler.cpp
View File

@@ -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 <QTimer>
#include <QtDebug>
@@ -35,9 +48,25 @@
//----------------------------------------------------------------------------------------------------
/**
* <p>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<QString> &cmd)
{
@@ -92,7 +121,17 @@ PDumpOutputHandler::PDumpOutputHandler(QVector<QString> &cmd)
//----------------------------------------------------------------------------------------------------
/**
* <p>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()
//----------------------------------------------------------------------------------------------------
/**
* <p>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()
//----------------------------------------------------------------------------------------------------
/**
* <p>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()
//----------------------------------------------------------------------------------------------------
/**
* <p>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()
{

80
src/musredit_qt6/musredit/PDumpOutputHandler.h
View File

@@ -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 @@
//---------------------------------------------------------------------------------------
/**
* <p>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<QString> 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<QProcess> 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<QProcess> fProc; ///< QProcess object managing the dump_header execution.
/** @} */
std::unique_ptr<QVBoxLayout> fVbox; ///< pointer to the dialog layout manager
std::unique_ptr<QTextEdit> fOutput; ///< the captured dump_header output is written (read only) into this text edit object.
std::unique_ptr<QPushButton> fQuitButton; ///< quit button
/** @name UI Components
* @brief Dialog user interface elements.
* @{
*/
std::unique_ptr<QVBoxLayout> fVbox; ///< Vertical layout manager for dialog widgets.
std::unique_ptr<QTextEdit> fOutput; ///< Read-only text widget displaying command output.
std::unique_ptr<QPushButton> fQuitButton; ///< Button to close dialog and terminate process.
/** @} */
};
#endif // _PDUMPOUTPUTHANDLER_H_