diff --git a/src/classes/PMusrT0.cpp b/src/classes/PMusrT0.cpp index 98ab17301..100a70f1f 100644 --- a/src/classes/PMusrT0.cpp +++ b/src/classes/PMusrT0.cpp @@ -44,7 +44,9 @@ // Constructor //-------------------------------------------------------------------------- /** - *

Constructor. + * \brief Default constructor that initializes all member variables. + * + * Calls InitData() to set default values for all member variables. */ PMusrT0Data::PMusrT0Data() { @@ -55,7 +57,10 @@ PMusrT0Data::PMusrT0Data() // Destructor //-------------------------------------------------------------------------- /** - *

Destructor. + * \brief Destructor that cleans up all vector containers. + * + * Clears all vectors including raw run data references, histogram numbers, + * t0 values, and addrun t0 values. */ PMusrT0Data::~PMusrT0Data() { @@ -71,7 +76,10 @@ PMusrT0Data::~PMusrT0Data() // InitData //-------------------------------------------------------------------------- /** - *

Initialize the necessary variables. + * \brief Initializes all member variables to default values. + * + * Sets all indices to -1, flags to default states, and clears all vectors. + * This method is called by the constructor and can be used to reset the object. */ void PMusrT0Data::InitData() { @@ -94,13 +102,10 @@ void PMusrT0Data::InitData() // GetRawRunData //-------------------------------------------------------------------------- /** - *

Returns the raw run data set with index idx. + * \brief Returns pointer to raw run data at the specified index. * - * return: - * - raw run data set - * - 0 pointer, if idx is out of range - * - * \param idx index of the raw run data + * \param idx Index of raw run data (0=main run, >0=addruns) + * \return Pointer to PRawRunData object, or nullptr if idx is out of range */ PRawRunData* PMusrT0Data::GetRawRunData(Int_t idx) { @@ -114,13 +119,10 @@ PRawRunData* PMusrT0Data::GetRawRunData(Int_t idx) // GetHistoNo //-------------------------------------------------------------------------- /** - *

Get histogram number of a run. + * \brief Returns histogram number at the specified index. * - * return: - * - histogram number - * - -1 if index is out of range - * - * \param idx index of the run (msr-file). + * \param idx Index into histogram number vector + * \return Histogram number (with Red/Green offset applied), or -1 if out of range */ Int_t PMusrT0Data::GetHistoNo(UInt_t idx) { @@ -134,13 +136,10 @@ Int_t PMusrT0Data::GetHistoNo(UInt_t idx) // GetT0Bin //-------------------------------------------------------------------------- /** - *

Get t0 (in bin) of a run. + * \brief Returns t0 bin value for the main run at the specified index. * - * return: - * - t0 bin - * - -1 if index is out of range - * - * \param idx index of the run (msr-file). + * \param idx Index into main run t0 vector + * \return t0 bin value, or -1 if out of range */ Int_t PMusrT0Data::GetT0Bin(UInt_t idx) { @@ -154,13 +153,10 @@ Int_t PMusrT0Data::GetT0Bin(UInt_t idx) // GetAddT0BinSize //-------------------------------------------------------------------------- /** - *

Get addt0 size of a run, i.e. the number of addt0's for a given msr-file run. + * \brief Returns number of t0 bins for the specified addrun. * - * return: - * - number of addt0's - * - -1 if index is out of range - * - * \param idx index of the run (msr-file). + * \param idx Addrun index + * \return Number of t0 bin values for this addrun, or 0 if out of range */ UInt_t PMusrT0Data::GetAddT0BinSize(UInt_t idx) { @@ -174,14 +170,11 @@ UInt_t PMusrT0Data::GetAddT0BinSize(UInt_t idx) // GetAddT0Bin //-------------------------------------------------------------------------- /** - *

Get addt0 (in bin) of a run. + * \brief Returns t0 bin value for a specific addrun and histogram index. * - * return: - * - addt0 bin - * - -1 if index is out of range - * - * \param addRunIdx index of the addrun - * \param idx index of the run (msr-file). + * \param addRunIdx Addrun index + * \param idx Histogram index within the addrun + * \return t0 bin value, or -1 if either index is out of range */ Int_t PMusrT0Data::GetAddT0Bin(UInt_t addRunIdx, UInt_t idx) { @@ -198,10 +191,12 @@ Int_t PMusrT0Data::GetAddT0Bin(UInt_t addRunIdx, UInt_t idx) // SetT0Bin //-------------------------------------------------------------------------- /** - *

Set t0 value. + * \brief Sets t0 bin value for the main run at the specified index. * - * \param val t0 value to be set - * \param idx index at which t0 shall be set. + * Automatically resizes the t0 vector if idx is beyond current size. + * + * \param val t0 bin value to set + * \param idx Index at which to set the t0 value */ void PMusrT0Data::SetT0Bin(UInt_t val, UInt_t idx) { @@ -215,11 +210,13 @@ void PMusrT0Data::SetT0Bin(UInt_t val, UInt_t idx) // SetAddT0Bin //-------------------------------------------------------------------------- /** - *

Set addt0 value. + * \brief Sets t0 bin value for a specific addrun and histogram index. * - * \param val t0 value to be set - * \param addRunIdx addt0 index (for each addrun, there has to be an addt0) - * \param idx index at which t0 shall be set. + * Automatically resizes vectors if indices are beyond current size. + * + * \param val t0 bin value to set + * \param addRunIdx Addrun index (each addrun needs its own t0 values) + * \param idx Histogram index within the addrun */ void PMusrT0Data::SetAddT0Bin(UInt_t val, UInt_t addRunIdx, UInt_t idx) { @@ -240,7 +237,10 @@ ClassImpQ(PMusrT0) // Constructor //-------------------------------------------------------------------------- /** - *

Constructor. + * \brief Default constructor that creates an invalid PMusrT0 instance. + * + * Initializes all member variables to default values. The instance is marked + * as invalid (fValid=false) since no raw data has been provided. */ PMusrT0::PMusrT0() { @@ -264,9 +264,15 @@ PMusrT0::PMusrT0() // Constructor //-------------------------------------------------------------------------- /** - *

Constructor + * \brief Main constructor that initializes the GUI with raw run data. * - * \param data raw run data set + * Creates and initializes the interactive t0/range determination GUI. The constructor: + * - Validates raw data availability and histogram presence + * - Creates histogram from raw data (single or grouped/added) + * - Estimates initial t0 by finding the maximum bin value + * - Sets up canvas title with run name, histogram number, and detector tag + * + * \param data PMusrT0Data object containing raw run data and configuration */ PMusrT0::PMusrT0(PMusrT0Data &data) : fMusrT0Data(data) { @@ -535,7 +541,12 @@ PMusrT0::PMusrT0(PMusrT0Data &data) : fMusrT0Data(data) // Done (SIGNAL) //-------------------------------------------------------------------------- /** - *

Signal emitted if the user wants to terminate the application. + * \brief Emits Done signal to terminate the interactive session. + * + * This ROOT signal is emitted when the user finishes t0/range determination + * or closes the canvas. The status value determines the scope of termination. + * + * \param status Exit status: 0=local quit, 1=quit application, 2=global quit */ void PMusrT0::Done(Int_t status) { @@ -546,25 +557,29 @@ void PMusrT0::Done(Int_t status) // HandleCmdKey (SLOT) //-------------------------------------------------------------------------- /** - *

Filters keyboard and mouse events, and if they are a command key (see below) carries out the - * necessary actions. - *

Currently implemented command keys: - * - 'q' close the currently shown canvas - * - 'Q' quite the application - * - 'u' unzoom to the original range - * - 'z' zoom to the region aroung t0 - * - 's' show/hide (toggle) the t0 of the data file (if present) - * - 'T' set t0 channel to the estimated t0 - * - 't' set t0 channel to the current cursor position - * - 'b' set first background channel - * - 'B' set last background channel - * - 'd' set first good bin channel - * - 'D' set last good bin channel + * \brief Handles keyboard and mouse events for interactive t0/range selection. * - * \param event event type - * \param x keyboard event: character key; mouse event: x-position - * \param y mouse event: y-position - * \param selected not used + * Processes keyboard commands for t0 determination and range selection. + * Mouse position is tracked for bin selection. This is the main event + * handler for the interactive GUI. + * + * \par Keyboard Commands: + * - 'q': Close current canvas (local quit) + * - 'Q': Quit entire application (global quit) + * - 'u': Unzoom to original histogram range + * - 'z': Zoom to region around t0 + * - 's': Toggle visibility of t0 from data file + * - 'T': Set t0 to estimated value (maximum bin) + * - 't': Set t0 to cursor position + * - 'b': Set background start bin to cursor position + * - 'B': Set background end bin to cursor position + * - 'd': Set first good data bin to cursor position + * - 'D': Set last good data bin to cursor position + * + * \param event Event type (kKeyPress for keyboard events) + * \param x For keyboard: character key code; for mouse: x-position in pixels + * \param y For mouse: y-position in pixels + * \param selected Pointer to selected ROOT object (unused) */ void PMusrT0::HandleCmdKey(Int_t event, Int_t x, Int_t y, TObject *selected) { @@ -610,8 +625,10 @@ void PMusrT0::HandleCmdKey(Int_t event, Int_t x, Int_t y, TObject *selected) // Quit (public) //-------------------------------------------------------------------------- /** - *

Slot called when the canvas is closed via the close icon (cross top right corner). - * It is emitting a global quit singal. + * \brief Slot called when canvas is closed via the close button. + * + * This method is invoked when the user clicks the close icon (X) in the + * canvas window. It sets a global quit status and emits the Done signal. */ void PMusrT0::Quit() { @@ -623,9 +640,12 @@ void PMusrT0::Quit() // SetTimeout (public) //-------------------------------------------------------------------------- /** - *

+ * \brief Sets automatic timeout for the interactive session. * - * \param timeout after which the done signal shall be emitted. Given in seconds + * Creates and starts a timer that will automatically call Quit() if no + * user interaction occurs within the specified timeout period. + * + * \param timeout Timeout duration in seconds (≤0 disables timeout) */ void PMusrT0::SetTimeout(Int_t timeout) { @@ -645,9 +665,12 @@ void PMusrT0::SetTimeout(Int_t timeout) // SetMsrHandler //-------------------------------------------------------------------------- /** - *

Set the msr-file handler + * \brief Sets the MSR file handler for accessing run configuration. * - * \param msrHandler msr-file handler pointer + * The MSR handler provides access to run parameters, t0 values, and other + * configuration data needed for interactive t0/range determination. + * + * \param msrHandler Pointer to initialized PMsrHandler instance */ void PMusrT0::SetMsrHandler(PMsrHandler *msrHandler) { @@ -658,7 +681,12 @@ void PMusrT0::SetMsrHandler(PMsrHandler *msrHandler) // InitT0 //-------------------------------------------------------------------------- /** - *

Initialize t0 data. + * \brief Initializes the interactive t0 determination GUI. + * + * Creates and displays the t0 marker line on the histogram canvas. + * The initial t0 value is retrieved from the MSR file based on the + * current detector tag (forward/backward) and histogram index. + * The t0 line is drawn as a green vertical line from 0 to histogram maximum. */ void PMusrT0::InitT0() { @@ -699,7 +727,14 @@ void PMusrT0::InitT0() // InitDataAndBkg //-------------------------------------------------------------------------- /** - *

Initialize data and background ranges. + * \brief Initializes the interactive data and background range GUI. + * + * Creates and displays data and background region histograms overlaid on + * the main histogram. Retrieves initial range values from the MSR file + * based on detector tag (forward/backward): + * - Data region shown in blue (first good bin to last good bin) + * - Background region shown in red (background start to end) + * - Vertical lines mark the boundaries of both regions */ void PMusrT0::InitDataAndBkg() { @@ -795,7 +830,10 @@ void PMusrT0::InitDataAndBkg() // ShowDataFileT0Channel //-------------------------------------------------------------------------- /** - *

Show the t0 channel from the data file (if present). + * \brief Displays the t0 value found in the data file. + * + * Creates and draws an orange vertical line showing the t0 value that was + * read from the raw data file. This allows comparison with the user-selected t0. */ void PMusrT0::ShowDataFileT0Channel() { @@ -818,7 +856,10 @@ void PMusrT0::ShowDataFileT0Channel() // HideDataFileT0Channel //-------------------------------------------------------------------------- /** - *

Hide the t0 channel from the data file (if currently displayed). + * \brief Hides the t0 value line from the data file. + * + * Removes the orange vertical line showing the data file t0 value. + * The canvas is updated to reflect the change. */ void PMusrT0::HideDataFileT0Channel() { @@ -832,7 +873,11 @@ void PMusrT0::HideDataFileT0Channel() // SetT0Channel //-------------------------------------------------------------------------- /** - *

Set the t0 channel to the current cursor position and keep the x-position as new t0 bin. + * \brief Sets t0 to the current cursor position. + * + * Converts cursor pixel position to bin number, updates the MSR handler + * with the new t0 value, and moves the green t0 line to the cursor position. + * The t0 index is calculated based on detector tag and fit type (single/asymmetry). */ void PMusrT0::SetT0Channel() { @@ -876,7 +921,11 @@ void PMusrT0::SetT0Channel() // SetEstimatedT0Channel //-------------------------------------------------------------------------- /** - *

Set the estimated t0 channel to the current cursor position and keep the x-position as new t0 bin. + * \brief Sets t0 to the estimated value (maximum bin). + * + * Uses the automatically estimated t0 value (bin with maximum counts) as the + * new t0. Updates the MSR handler and moves the green t0 line to the estimated + * position. The t0 index is calculated based on detector tag and fit type. */ void PMusrT0::SetEstimatedT0Channel() { @@ -916,7 +965,11 @@ void PMusrT0::SetEstimatedT0Channel() // SetDataFirstChannel //-------------------------------------------------------------------------- /** - *

Set the first good data channel to the current cursor position and keep the x-position as new first good data bin. + * \brief Sets the first good data bin to the cursor position. + * + * Converts cursor position to bin number, updates the MSR handler with the + * new first good bin value, and redraws the blue data region histogram. + * The blue vertical line marking the data start is moved to the new position. */ void PMusrT0::SetDataFirstChannel() { @@ -962,7 +1015,11 @@ void PMusrT0::SetDataFirstChannel() // SetDataLastChannel //-------------------------------------------------------------------------- /** - *

Set the last good data channel to the current cursor position and keep the x-position as new last good data bin. + * \brief Sets the last good data bin to the cursor position. + * + * Converts cursor position to bin number, updates the MSR handler with the + * new last good bin value, and redraws the blue data region histogram. + * The blue vertical line marking the data end is moved to the new position. */ void PMusrT0::SetDataLastChannel() { @@ -1008,7 +1065,11 @@ void PMusrT0::SetDataLastChannel() // SetBkgFirstChannel //-------------------------------------------------------------------------- /** - *

Set the first background channel to the current cursor position and keep the x-position as new first background bin. + * \brief Sets the background start bin to the cursor position. + * + * Converts cursor position to bin number, updates the MSR handler with the + * new background start value, and redraws the red background region histogram. + * The red vertical line marking the background start is moved to the new position. */ void PMusrT0::SetBkgFirstChannel() { @@ -1054,7 +1115,11 @@ void PMusrT0::SetBkgFirstChannel() // SetBkgLastChannel //-------------------------------------------------------------------------- /** - *

Set the last background channel to the current cursor position and keep the x-position as new last background bin. + * \brief Sets the background end bin to the cursor position. + * + * Converts cursor position to bin number, updates the MSR handler with the + * new background end value, and redraws the red background region histogram. + * The red vertical line marking the background end is moved to the new position. */ void PMusrT0::SetBkgLastChannel() { @@ -1100,7 +1165,10 @@ void PMusrT0::SetBkgLastChannel() // UnZoom //-------------------------------------------------------------------------- /** - *

Unzoom the current histogram + * \brief Resets zoom to show the full histogram range. + * + * Unzooms both x and y axes of the histogram to display the complete + * data range. The canvas is updated to reflect the change. */ void PMusrT0::UnZoom() { @@ -1115,7 +1183,11 @@ void PMusrT0::UnZoom() // ZoomT0 //-------------------------------------------------------------------------- /** - *

Zoom into the histogram region of the t0, and/or estimated t0 range. + * \brief Zooms to the region around t0 for precise adjustment. + * + * Zooms the x-axis to a ±75 bin range centered on the current t0 position. + * This allows for precise t0 selection. If t0 is near the histogram edges, + * the zoom range is automatically adjusted to stay within valid bin numbers. */ void PMusrT0::ZoomT0() { diff --git a/src/include/PMusrT0.h b/src/include/PMusrT0.h index 04abc2b9b..6d2c23b3c 100644 --- a/src/include/PMusrT0.h +++ b/src/include/PMusrT0.h @@ -48,148 +48,269 @@ #include "PMsrHandler.h" #endif // __MAKECLING__ -#define PMUSRT0_FORWARD 0 -#define PMUSRT0_BACKWARD 1 +//-------------------------------------------------------------------------- +// Detector tags +//-------------------------------------------------------------------------- +#define PMUSRT0_FORWARD 0 ///< Forward detector tag +#define PMUSRT0_BACKWARD 1 ///< Backward detector tag -#define PMUSRT0_GET_T0 0 -#define PMUSRT0_GET_DATA_AND_BKG_RANGE 1 -#define PMUSRT0_GET_T0_DATA_AND_BKG_RANGE 2 +//-------------------------------------------------------------------------- +// Command/mode tags +//-------------------------------------------------------------------------- +#define PMUSRT0_GET_T0 0 ///< Mode: Determine t0 only +#define PMUSRT0_GET_DATA_AND_BKG_RANGE 1 ///< Mode: Determine data and background ranges only +#define PMUSRT0_GET_T0_DATA_AND_BKG_RANGE 2 ///< Mode: Determine t0, data range, and background range //-------------------------------------------------------------------------- /** - *

Handles the raw muSR run data sets. + * \brief Data container for musrt0 raw run data and histogram information. + * + * PMusrT0Data manages the raw histogram data needed for interactive t0 and + * range determination in the musrt0 tool. It stores: + * - Raw run data (main run and optional addruns) + * - Histogram numbers and detector grouping + * - Current and saved t0 bin values + * - Data and background range information + * + * The class supports both single histogram and asymmetry fit modes, and + * handles complex run configurations including addrun combinations. + * + * \see PMusrT0 for the GUI interface using this data + * \see PRawRunData for the underlying raw data structure */ class PMusrT0Data { public: + /// Default constructor PMusrT0Data(); + /// Destructor virtual ~PMusrT0Data(); - + /// Initializes data structures (currently empty implementation) virtual void InitData(); + /// Returns true if single histogram fit mode virtual Bool_t IsSingleHisto() { return fSingleHisto; } + /// Returns number of raw run data entries (1 + number of addruns) virtual UInt_t GetRawRunDataSize() { return fRawRunData.size(); } + /// Returns raw run data for given index (0=main run, >0=addruns) virtual PRawRunData* GetRawRunData(Int_t idx); + /// Returns MSR file run number virtual Int_t GetRunNo() { return fRunNo; } + /// Returns current addrun index virtual Int_t GetAddRunIdx() { return fAddRunIdx; } + /// Returns current histogram number index virtual Int_t GetHistoNoIdx() { return fHistoNoIdx; } + /// Returns number of histogram numbers virtual UInt_t GetHistoNoSize() { return fHistoNo.size(); } + /// Returns histogram number at given index virtual Int_t GetHistoNo(UInt_t idx); + /// Returns detector tag (PMUSRT0_FORWARD or PMUSRT0_BACKWARD) virtual Int_t GetDetectorTag() { return fDetectorTag; } + /// Returns command tag (mode for t0/range determination) virtual Int_t GetCmdTag() { return fCmdTag; } + /// Returns number of t0 bins for main run virtual UInt_t GetT0BinSize() { return fT0.size(); } + /// Returns t0 bin value at given index virtual Int_t GetT0Bin(UInt_t idx); + /// Returns number of addrun entries with t0 values virtual UInt_t GetAddT0Entries() { return fAddT0.size(); } + /// Returns number of t0 bins for given addrun virtual UInt_t GetAddT0BinSize(UInt_t idx); + /// Returns t0 bin for specific addrun and histogram virtual Int_t GetAddT0Bin(UInt_t addRunIdx, UInt_t idx); + /// Returns t0 bin found from data file virtual Int_t GetT0BinData() { return fT0Data; } + /// Sets single histogram fit mode flag virtual void SetSingleHisto(const Bool_t flag) { fSingleHisto = flag; } + /// Sets vector of raw run data pointers virtual void SetRawRunData(const std::vector rawRunData) { fRawRunData = rawRunData; } + /// Sets MSR file run number virtual void SetRunNo(const UInt_t runNo) { fRunNo = runNo; } + /// Sets current addrun index virtual void SetAddRunIdx(const UInt_t addRunIdx) { fAddRunIdx = addRunIdx; } + /// Sets current histogram number index virtual void SetHistoNoIdx(const UInt_t histoNoIdx) { fHistoNoIdx = histoNoIdx; } + /// Sets vector of histogram numbers virtual void SetHistoNo(const PIntVector histoNo) { fHistoNo = histoNo; } + /// Sets detector tag (forward/backward) virtual void SetDetectorTag(const UInt_t detectorTag) { fDetectorTag = detectorTag; } + /// Sets command/mode tag virtual void SetCmdTag(const UInt_t cmdTag) { fCmdTag = cmdTag; } + /// Sets t0 bin value at given index virtual void SetT0Bin(UInt_t val, UInt_t idx); + /// Sets t0 bin value for specific addrun and index virtual void SetAddT0Bin(UInt_t val, UInt_t addRunIdx, UInt_t idx); + /// Sets t0 bin value found from data file virtual void SetT0BinData(UInt_t val) { fT0Data = val; } private: - Bool_t fSingleHisto; ///< true if single histo fit, false for asymmetry fit - std::vector fRawRunData; ///< holds the raw data of the needed runs, idx=0 the run, idx>0 the addruns - Int_t fRunNo; ///< msr-file run number - Int_t fAddRunIdx; ///< msr-file addrun index - Int_t fHistoNoIdx; ///< msr-file histo number index - PIntVector fHistoNo; ///< msr-file histo numbers, i.e. idx + Red/Green offset - Int_t fDetectorTag; ///< detector tag. forward=0,backward=1 - Int_t fCmdTag; ///< command tag. 0=get t0, 1=get data-/bkg-range, 2=get t0, and data-/bkg-range - PIntVector fT0; ///< holding the t0's of the run - std::vector fAddT0; ///< holding the t0's of the addruns - Int_t fT0Data; ///< holding the t0 found in the current data set + Bool_t fSingleHisto; ///< True for single histogram fit, false for asymmetry fit + std::vector fRawRunData; ///< Raw data: index 0 = main run, index >0 = addruns + Int_t fRunNo; ///< MSR file run block number + Int_t fAddRunIdx; ///< Current addrun index being processed + Int_t fHistoNoIdx; ///< Current histogram number index + PIntVector fHistoNo; ///< Histogram numbers (with Red/Green offset applied) + Int_t fDetectorTag; ///< Detector: PMUSRT0_FORWARD (0) or PMUSRT0_BACKWARD (1) + Int_t fCmdTag; ///< Mode: 0=t0 only, 1=ranges only, 2=both t0 and ranges + PIntVector fT0; ///< t0 bin values for main run histograms + std::vector fAddT0; ///< t0 bin values for addrun histograms + Int_t fT0Data; ///< t0 bin found in current data file }; //-------------------------------------------------------------------------- /** - *

Handles the musrt0 graphical user interface. - *

The preprocessor tag __MAKECLING__ is used to hide away from rootcling + * \brief Interactive GUI for determining t0 and data/background ranges in μSR experiments. + * + * PMusrT0 provides a ROOT-based graphical interface for interactively determining: + * - t0 values (time zero calibration for detector histograms) + * - Data ranges (first good bin, last good bin) + * - Background ranges (background start/end bins) + * + * The tool displays raw histogram data and allows users to set these parameters + * through keyboard interactions. It supports: + * - Single histogram and asymmetry fit modes + * - Multiple histograms and addrun configurations + * - Visual markers for t0, data ranges, and background ranges + * - Zoom capabilities for precise bin selection + * + * \par Keyboard Controls: + * - 't': Set t0 at cursor position + * - 'e': Set estimated t0 + * - 'f': Set first good data bin + * - 'l': Set last good data bin + * - 'b': Set background start bin + * - 'n': Set background end bin + * - 'u': Unzoom to full histogram + * - 'z': Zoom to t0 region + * - 'd': Toggle data file t0 display + * - 'q': Quit/advance to next histogram + * + * \note The preprocessor tag __MAKECLING__ is used to hide away from rootcling * the overly complex spirit header files. + * + * \see PMusrT0Data for the underlying data container + * \see PMsrHandler for MSR file management */ class PMusrT0 : public TObject, public TQObject { public: + /// Default constructor (creates invalid instance) PMusrT0(); + /** + * \brief Main constructor that initializes the interactive GUI. + * \param data Reference to PMusrT0Data containing raw run data and configuration + */ PMusrT0(PMusrT0Data &data); + /** + * \brief Returns validity status of the PMusrT0 instance. + * \return True if raw data sets are available and GUI is functional, false otherwise + */ virtual Bool_t IsValid() { return fValid; } + /** + * \brief Emits signal indicating completion of t0/range determination. + * \param status Exit status: 0=local quit (single canvas), 1=quit entire application + */ virtual void Done(Int_t status=0); // *SIGNAL* + + /** + * \brief Handles keyboard input for interactive t0 and range selection. + * \param event Keyboard event code + * \param x Mouse x-coordinate in pixels + * \param y Mouse y-coordinate in pixels + * \param selected Pointer to selected ROOT object (unused) + * + * Processes keyboard commands for setting t0, data ranges, background ranges, + * and zoom controls. See class documentation for complete key bindings. + */ virtual void HandleCmdKey(Int_t event, Int_t x, Int_t y, TObject *selected); // SLOT + + /// Quit slot that emits Done signal to close the current canvas virtual void Quit(); // SLOT + + /** + * \brief Sets automatic timeout for the interactive session. + * \param timeout Timeout in milliseconds (≤0 disables timeout) + * + * If timeout expires without user interaction, the Done signal is automatically emitted. + */ virtual void SetTimeout(Int_t timeout); #ifndef __MAKECLING__ + /** + * \brief Sets the MSR file handler for accessing run configuration. + * \param msrHandler Pointer to initialized PMsrHandler instance + */ virtual void SetMsrHandler(PMsrHandler *msrHandler); #endif // __MAKECLING__ + /// Initializes GUI for interactive t0 determination virtual void InitT0(); + + /// Initializes GUI for interactive data and background range determination virtual void InitDataAndBkg(); + + /** + * \brief Returns current exit status. + * \return 0=local quit (single canvas terminates), 1=quit entire application + */ virtual Int_t GetStatus() { return fStatus; } private: #ifndef __MAKECLING__ - PMsrHandler *fMsrHandler; ///< msr-file handler + PMsrHandler *fMsrHandler; ///< MSR file handler for accessing run configuration #endif // __MAKECLING__ - Int_t fTimeout; ///< timeout after which the Done signal should be emited. If timeout <= 0, no timeout is taking place + Int_t fTimeout; ///< Timeout in ms after which Done signal is emitted (≤0 disables timeout) - Bool_t fValid; ///< true if raw data set are available, otherwise false + Bool_t fValid; ///< True if raw data sets are available and GUI is functional - Int_t fStatus; ///< 0=quit locally, i.e. only a single musrt0 raw data canvas will terminate but not the application, 1=quit the application + Int_t fStatus; ///< Exit status: 0=local quit (single canvas), 1=quit application - PMusrT0Data fMusrT0Data; ///< raw muSR run data sets. + PMusrT0Data fMusrT0Data; ///< Container for raw μSR run data and histogram information - Bool_t fDataAndBkgEnabled; ///< enable/disable data and background range handling (necessary in connection with grouping and addrun) - Bool_t fT0Enabled; ///< enable/disable t0 handling (necessary in connection with grouping and addrun) - Int_t fT0Estimated; ///< estimated t0 value (in bins) - Bool_t fShowT0DataChannel; + Bool_t fDataAndBkgEnabled; ///< Enable/disable data and background range handling (required for grouping/addrun) + Bool_t fT0Enabled; ///< Enable/disable t0 handling (required for grouping/addrun) + Int_t fT0Estimated; ///< Estimated t0 value in bins (used as initial guess) + Bool_t fShowT0DataChannel; ///< Flag to show/hide t0 value from data file - std::unique_ptr fTimeoutTimer; ///< timeout timer in order to terminate if no action is taking place for too long + std::unique_ptr fTimeoutTimer; ///< Timer to emit Done signal if no user interaction occurs - // canvas related variables - std::unique_ptr fMainCanvas; ///< main canvas for the graphical user interface + // Canvas related variables + std::unique_ptr fMainCanvas; ///< Main ROOT canvas for the interactive GUI - std::unique_ptr fHisto; ///< full raw data histogram - std::unique_ptr fData; ///< ranged raw data histogram (first good bin, last good bin) - std::unique_ptr fBkg; ///< histogram starting from 'bkg start' up to 'bkg end' + std::unique_ptr fHisto; ///< Full raw data histogram (all bins) + std::unique_ptr fData; ///< Data region histogram (first good bin to last good bin) + std::unique_ptr fBkg; ///< Background region histogram (background start to end) - std::unique_ptr fToDoInfo; ///< clear text user instruction string + std::unique_ptr fToDoInfo; ///< Text display showing current instructions to user - std::unique_ptr fT0Line; ///< line showing the position of t0 - std::unique_ptr fT0DataLine; ///< line showing the position of t0 found in the data file - std::unique_ptr fFirstBkgLine; ///< line showing the start of the background - std::unique_ptr fLastBkgLine; ///< line showing the end of the background - std::unique_ptr fFirstDataLine; ///< line showing the start of the data (first good data bin) - std::unique_ptr fLastDataLine; ///< line showing the end of the data (last good data bin) + std::unique_ptr fT0Line; ///< Vertical line marking current t0 position + std::unique_ptr fT0DataLine; ///< Vertical line marking t0 found in data file + std::unique_ptr fFirstBkgLine; ///< Vertical line marking background start bin + std::unique_ptr fLastBkgLine; ///< Vertical line marking background end bin + std::unique_ptr fFirstDataLine; ///< Vertical line marking first good data bin + std::unique_ptr fLastDataLine; ///< Vertical line marking last good data bin - Int_t fPx; ///< x-position of the cursor - Int_t fPy; ///< y-position of the cursor + Int_t fPx; ///< Current cursor x-position in pixel coordinates + Int_t fPy; ///< Current cursor y-position in pixel coordinates - Int_t fDataRange[2]; ///< data range (first good bin, last good bin) - Int_t fBkgRange[2]; ///< background range (first bkg bin, last bkg bin) + Int_t fDataRange[2]; ///< Data range in bins: [0]=first good bin, [1]=last good bin + Int_t fBkgRange[2]; ///< Background range in bins: [0]=first bkg bin, [1]=last bkg bin - void ShowDataFileT0Channel(); - void HideDataFileT0Channel(); - void SetT0Channel(); - void SetEstimatedT0Channel(); - void SetDataFirstChannel(); - void SetDataLastChannel(); - void SetBkgFirstChannel(); - void SetBkgLastChannel(); - void UnZoom(); - void ZoomT0(); + void ShowDataFileT0Channel(); ///< Displays vertical line showing t0 from data file + void HideDataFileT0Channel(); ///< Hides vertical line showing t0 from data file + void SetT0Channel(); ///< Sets t0 to cursor position and updates display + void SetEstimatedT0Channel(); ///< Sets t0 to estimated value and updates display + void SetDataFirstChannel(); ///< Sets first good data bin to cursor position + void SetDataLastChannel(); ///< Sets last good data bin to cursor position + void SetBkgFirstChannel(); ///< Sets background start bin to cursor position + void SetBkgLastChannel(); ///< Sets background end bin to cursor position + void UnZoom(); ///< Resets zoom to show full histogram range + void ZoomT0(); ///< Zooms to region around t0 for precise adjustment ClassDef(PMusrT0, 1) };