From af23a52745e05277d3b9018700afc2fc8ef5e2e6 Mon Sep 17 00:00:00 2001 From: Andreas Suter Date: Mon, 24 Nov 2025 13:44:21 +0100 Subject: [PATCH] improve the doxygen docu of PGetPlotBlockDialog.* (musredit_qt6). --- .../musredit/PGetPlotBlockDialog.cpp | 77 +++++++++++++++-- .../musredit/PGetPlotBlockDialog.h | 82 ++++++++++++++++++- 2 files changed, 148 insertions(+), 11 deletions(-) diff --git a/src/musredit_qt6/musredit/PGetPlotBlockDialog.cpp b/src/musredit_qt6/musredit/PGetPlotBlockDialog.cpp index 0cd7ca79d..c74d9400d 100644 --- a/src/musredit_qt6/musredit/PGetPlotBlockDialog.cpp +++ b/src/musredit_qt6/musredit/PGetPlotBlockDialog.cpp @@ -27,6 +27,19 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PGetPlotBlockDialog.cpp + * @brief Implementation of the PGetPlotBlockDialog class. + * @details This file implements the dialog for creating PLOT blocks in msr + * files. It handles user input validation, proper formatting of plot + * specifications, and keyboard shortcuts for rapid plot entry. + * + * @author Andreas Suter + * @date 2009-2025 + * @copyright Copyright (C) 2009-2025 by Andreas Suter + * @license GNU General Public License v2 or later + */ + #include #include #include @@ -40,9 +53,21 @@ //---------------------------------------------------------------------------------------------------- /** - *

Constructor. + * @brief Constructs the PLOT block dialog. * - * \param helpUrl help url for the PLOT block. + * @details Initializes the dialog UI, sets up input validators for numeric + * range fields, and installs an event filter to capture keyboard shortcuts. + * The dialog is created as modal. A monospace font (Courier, 10pt) is used + * for the plot display to ensure proper column alignment. + * + * @par Input Validators: + * - Double validators: X-range lower/upper, Y-range lower/upper + * + * @par Event Filter: + * An event filter is installed to intercept the Return key, allowing users + * to quickly add plots by pressing Enter instead of clicking the Add button. + * + * @param helpUrl URL to the online documentation for PLOT blocks. */ PGetPlotBlockDialog::PGetPlotBlockDialog(const QString helpUrl) : fHelpUrl(helpUrl) { @@ -63,8 +88,32 @@ PGetPlotBlockDialog::PGetPlotBlockDialog(const QString helpUrl) : fHelpUrl(helpU //---------------------------------------------------------------------------------------------------- /** - *

Extracts the information of the top part of the dialog, constructs a msr-file PLOT block and - * writes it into the text edit window. + * @brief Validates and adds a plot specification to the PLOT block. + * + * @details Extracts values from all input fields, validates required fields, + * formats the plot block with proper column alignment, and appends it to the + * plot text display. After successful addition, the input fields are cleared + * and focus returns to the Run List field for the next plot. + * + * @par Validation Rules: + * - Lower X-range (time) is required + * - Upper X-range (time) is required + * - Y-range is optional, but if provided, both lower and upper must be specified + * + * @par Plot Type Codes: + * - "Single Histo" → 0 + * - "Asymmetry" → 2 + * - "MuMinus" → 4 + * - "NonMusr" → 8 + * + * @par Generated Format: + * @code + * PLOT () + * runs + * range [ ] + * @endcode + * + * @note The separator line (###...) is only added for the first plot block. */ void PGetPlotBlockDialog::addPlot() { @@ -154,7 +203,11 @@ void PGetPlotBlockDialog::addPlot() //---------------------------------------------------------------------------------------------------- /** - *

Generates a help content window showing the description of the PLOT block. + * @brief Opens the online help documentation for PLOT blocks. + * + * @details Attempts to open the help URL in the system's default web browser + * using QDesktopServices. If the URL is empty, displays an informational message. + * If the browser fails to open, displays an error message with a clickable link. */ void PGetPlotBlockDialog::helpContent() { @@ -171,10 +224,18 @@ void PGetPlotBlockDialog::helpContent() //---------------------------------------------------------------------------------------------------- /** - *

This event filter is filtering out the return key, and if present adds the current plot. + * @brief Event filter to intercept keyboard events. * - * \param obj object which is triggering the event - * \param ev the triggered event + * @details Filters keyboard events to intercept the Return/Enter key press. + * When Return is pressed, the current plot values are validated and added + * to the plot list via addPlot(). This allows for rapid plot entry without + * using the mouse to click the Add button. + * + * @param obj Pointer to the object that generated the event. + * @param ev Pointer to the event to be filtered. + * + * @return true if the event was handled (Return key was pressed and plot + * was added), false otherwise (event is passed to the base class). */ bool PGetPlotBlockDialog::eventFilter( QObject *obj, QEvent *ev ) { diff --git a/src/musredit_qt6/musredit/PGetPlotBlockDialog.h b/src/musredit_qt6/musredit/PGetPlotBlockDialog.h index 97431b250..949593710 100644 --- a/src/musredit_qt6/musredit/PGetPlotBlockDialog.h +++ b/src/musredit_qt6/musredit/PGetPlotBlockDialog.h @@ -27,14 +27,71 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PGetPlotBlockDialog.h + * @brief Dialog for creating PLOT blocks in msr files. + * @details This header defines the PGetPlotBlockDialog class which provides + * a dialog for entering plot parameters needed to create a PLOT block in a + * musrfit msr file. Multiple PLOT blocks can be defined to visualize different + * aspects of the fit data. + * + * @author Andreas Suter + * @date 2009-2025 + * @copyright Copyright (C) 2009-2025 by Andreas Suter + * @license GNU General Public License v2 or later + * + * @see PGetFourierBlockDialog For creating FOURIER blocks + * @see PGetAsymmetryRunBlockDialog For creating asymmetry RUN blocks + */ + #ifndef _PGETPLOTBLOCKDIALOG_H_ #define _PGETPLOTBLOCKDIALOG_H_ #include "ui_PGetPlotBlockDialog.h" -//-------------------------------------------------------------------------- +//--------------------------------------------------------------------------- /** - *

Handels content of the PLOT block dialog. + * @class PGetPlotBlockDialog + * @brief Dialog for creating PLOT blocks in msr files. + * + * @details This dialog allows users to define plot specifications for + * visualizing musrfit data. Multiple plots can be added, each with its + * own type, run selection, and axis ranges. The dialog supports keyboard + * shortcuts for rapid plot entry. + * + * @par Plot Types: + * | Type | Code | Description | + * |------|------|-------------| + * | Single Histo | 0 | Single histogram plot | + * | Asymmetry | 2 | Asymmetry plot | + * | MuMinus | 4 | Mu minus plot | + * | NonMusr | 8 | Non-muSR data plot | + * + * @par Plot Parameters: + * - **Type**: Plot type (Single Histo, Asymmetry, MuMinus, NonMusr) + * - **Runs**: Space-separated list of run numbers to include + * - **X-Range**: Time or x-axis range (both values required) + * - **Y-Range**: Asymmetry or y-axis range (optional, both or neither) + * + * @par Generated Output Format: + * The dialog generates properly formatted PLOT blocks: + * @code + * ############################################################### + * PLOT 2 (asymmetry plot) + * runs 1 2 3 + * range 0.0 10.0 -0.3 0.3 + * + * PLOT 0 (single histo plot) + * runs 1 + * range 0.0 10.0 + * @endcode + * + * @par User Interaction: + * - Press Return/Enter key to quickly add plots + * - Input fields are cleared after each plot addition + * - Focus returns to the Run List field for rapid entry + * + * @see PGetFourierBlockDialog For Fourier transform visualization settings */ class PGetPlotBlockDialog : public QDialog, private Ui::PGetPlotBlockDialog { @@ -43,17 +100,36 @@ class PGetPlotBlockDialog : public QDialog, private Ui::PGetPlotBlockDialog public: PGetPlotBlockDialog(const QString helpUrl); + /** + * @brief Returns all entered plot specifications as formatted text. + * @return Complete PLOT block content ready for insertion into an msr file. + */ QString getPlotBlock() { return fPlot_plainTextEdit->toPlainText(); } public slots: + /** + * @brief Validates and adds a plot specification to the PLOT block. + */ void addPlot(); + + /** + * @brief Opens the online help for PLOT blocks. + */ void helpContent(); protected: + /** + * @brief Event filter to handle keyboard shortcuts. + * @details Intercepts the Return key to trigger plot addition, + * allowing for rapid plot entry without clicking the Add button. + * @param obj The object that generated the event. + * @param ev The event to be filtered. + * @return true if the event was handled (Return key), false otherwise. + */ bool eventFilter( QObject *obj, QEvent *ev ); private: - QString fHelpUrl; ///< help url for the PLOT block + QString fHelpUrl; ///< URL to the online documentation for PLOT blocks. }; #endif // _PGETPLOTBLOCKDIALOG_H_