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

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

Browse Source
This commit is contained in:
suter_a
2025-11-24 13:44:21 +01:00
parent 4ed0ec2087
commit af23a52745
2 changed files with 148 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
src/musredit_qt6/musredit/PGetPlotBlockDialog.cpp
View File

@@ -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 <QLineEdit>
#include <QValidator>
#include <QMessageBox>
@@ -40,9 +53,21 @@
//----------------------------------------------------------------------------------------------------
/**
* <p>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
//----------------------------------------------------------------------------------------------------
/**
* <p>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 <type_code> (<type description>)
* runs <run_list>
* range <x_low> <x_high> [<y_low> <y_high>]
* @endcode
*
* @note The separator line (###...) is only added for the first plot block.
*/
void PGetPlotBlockDialog::addPlot()
{
@@ -154,7 +203,11 @@ void PGetPlotBlockDialog::addPlot()
//----------------------------------------------------------------------------------------------------
/**
* <p>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()
//----------------------------------------------------------------------------------------------------
/**
* <p>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 )
{

82
src/musredit_qt6/musredit/PGetPlotBlockDialog.h
View File

@@ -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"
//--------------------------------------------------------------------------
//---------------------------------------------------------------------------
/**
* <p>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_