improve the doxygen docu.
This commit is contained in:
@@ -50,7 +50,20 @@ ClassImpQ(PFourierCanvas)
|
||||
|
||||
//---------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Constructor
|
||||
* <p>Default constructor - creates uninitialized canvas.
|
||||
*
|
||||
* <p>Initializes all member variables to safe default values. This
|
||||
* constructor produces an invalid canvas (IsValid() returns false).
|
||||
* Use full constructors with Fourier data for functional canvases.
|
||||
*
|
||||
* <p><b>State after construction:</b>
|
||||
* - No timeout, no batch mode
|
||||
* - All view flags disabled
|
||||
* - Empty title and axis labels
|
||||
* - Zero phase offset
|
||||
* - Null GUI pointers
|
||||
*
|
||||
* <p>Primarily used internally or for two-stage initialization patterns.
|
||||
*/
|
||||
PFourierCanvas::PFourierCanvas()
|
||||
{
|
||||
@@ -76,19 +89,39 @@ PFourierCanvas::PFourierCanvas()
|
||||
|
||||
//---------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Constructor
|
||||
* <p>Full constructor with automatic marker/color generation.
|
||||
*
|
||||
* \param fourier
|
||||
* \param title
|
||||
* \param showAverage
|
||||
* \param fourierPlotOpt
|
||||
* \param fourierXrange
|
||||
* \param phase
|
||||
* \param wtopx
|
||||
* \param wtopy
|
||||
* \param ww
|
||||
* \param wh
|
||||
* \param batch
|
||||
* <p>Creates a complete, functional Fourier canvas ready for display.
|
||||
* Automatically generates random but consistent markers (styles 20-29)
|
||||
* and colors for each dataset based on seeded random numbers.
|
||||
*
|
||||
* <p><b>Initialization sequence:</b>
|
||||
* 1. Store configuration parameters
|
||||
* 2. Generate random markers/colors (reproducible from dataset index)
|
||||
* 3. Create axis titles based on unit type
|
||||
* 4. Set up ROOT plotting style
|
||||
* 5. Generate all Fourier histograms (Re/Im/Pwr/Phase/PhaseOpt)
|
||||
* 6. Create ROOT canvas with menus and pads
|
||||
* 7. Connect signals/slots for interactivity
|
||||
*
|
||||
* @param fourier Vector of PFourier objects (must be already transformed)
|
||||
* @param dataSetTag Dataset group identifiers for averaging
|
||||
* @param title Window title string
|
||||
* @param showAverage Start in all-data averaged view
|
||||
* @param showAveragePerDataSet Start in per-dataset averaged view
|
||||
* @param fourierPlotOpt Initial view mode (FOURIER_PLOT_*)
|
||||
* @param fourierXrange X-axis display range [min, max]
|
||||
* @param phase Initial phase offset in degrees (for Re/Im views)
|
||||
* @param wtopx Canvas window x-position in pixels
|
||||
* @param wtopy Canvas window y-position in pixels
|
||||
* @param ww Canvas width in pixels
|
||||
* @param wh Canvas height in pixels
|
||||
* @param batch If true, suppress GUI (for automated plotting)
|
||||
*
|
||||
* <p>Check IsValid() after construction to verify success.
|
||||
*
|
||||
* @see InitFourierDataSets()
|
||||
* @see InitFourierCanvas()
|
||||
*/
|
||||
PFourierCanvas::PFourierCanvas(std::vector<PFourier*> &fourier, PIntVector dataSetTag, const Char_t* title,
|
||||
const Bool_t showAverage, const Bool_t showAveragePerDataSet,
|
||||
@@ -127,21 +160,45 @@ PFourierCanvas::PFourierCanvas(std::vector<PFourier*> &fourier, PIntVector dataS
|
||||
|
||||
//---------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Constructor
|
||||
* <p>Full constructor with explicit marker/color specification.
|
||||
*
|
||||
* \param fourier
|
||||
* \param title
|
||||
* \param showAverage
|
||||
* \param fourierPlotOpt
|
||||
* \param fourierXrange
|
||||
* \param phase
|
||||
* \param wtopx
|
||||
* \param wtopy
|
||||
* \param ww
|
||||
* \param wh
|
||||
* \param markerList
|
||||
* \param colorList
|
||||
* \param batch
|
||||
* <p>Creates a complete Fourier canvas with user-defined plot styling.
|
||||
* Provides full control over visual appearance by specifying ROOT marker
|
||||
* styles and color indices for each dataset.
|
||||
*
|
||||
* <p><b>Marker styles:</b> ROOT marker codes (typically 20-34):
|
||||
* - 20: filled circle
|
||||
* - 21: filled square
|
||||
* - 22: filled triangle up
|
||||
* - 23: filled triangle down
|
||||
* - etc.
|
||||
*
|
||||
* <p><b>Colors:</b> ROOT color palette indices or RGB-defined colors
|
||||
* via TColor::GetColor(r,g,b).
|
||||
*
|
||||
* <p><b>Partial lists:</b> If markerList or colorList contain fewer
|
||||
* entries than datasets, remaining entries are auto-generated randomly.
|
||||
*
|
||||
* @param fourier Vector of PFourier objects (must be already transformed)
|
||||
* @param dataSetTag Dataset group identifiers for averaging
|
||||
* @param title Window title string
|
||||
* @param showAverage Start in all-data averaged view
|
||||
* @param showAveragePerDataSet Start in per-dataset averaged view
|
||||
* @param fourierPlotOpt Initial view mode (FOURIER_PLOT_*)
|
||||
* @param fourierXrange X-axis display range [min, max]
|
||||
* @param phase Initial phase offset in degrees (for Re/Im views)
|
||||
* @param wtopx Canvas window x-position in pixels
|
||||
* @param wtopy Canvas window y-position in pixels
|
||||
* @param ww Canvas width in pixels
|
||||
* @param wh Canvas height in pixels
|
||||
* @param markerList ROOT marker style codes for each dataset
|
||||
* @param colorList ROOT color indices for each dataset
|
||||
* @param batch If true, suppress GUI (for automated plotting)
|
||||
*
|
||||
* <p>Check IsValid() after construction to verify success.
|
||||
*
|
||||
* @see InitFourierDataSets()
|
||||
* @see InitFourierCanvas()
|
||||
*/
|
||||
PFourierCanvas::PFourierCanvas(std::vector<PFourier*> &fourier, PIntVector dataSetTag, const Char_t* title,
|
||||
const Bool_t showAverage, const Bool_t showAveragePerDataSet,
|
||||
@@ -185,9 +242,25 @@ PFourierCanvas::PFourierCanvas(std::vector<PFourier*> &fourier, PIntVector dataS
|
||||
// Done (SIGNAL)
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Signal emitted that the user wants to terminate the application.
|
||||
* <p>Emits Done signal to notify parent application of canvas closure.
|
||||
*
|
||||
* \param status Status info
|
||||
* <p>This ROOT signal mechanism allows parent objects to connect cleanup
|
||||
* handlers or application flow logic. Typically called when:
|
||||
* - User closes canvas window
|
||||
* - User presses 'q' to quit
|
||||
* - Timeout expires
|
||||
* - SaveGraphicsAndQuit() completes
|
||||
*
|
||||
* @param status Exit status: 0=normal, non-zero=error/abort
|
||||
*
|
||||
* <p><b>Example connection:</b>
|
||||
* @code
|
||||
* PFourierCanvas *canvas = new PFourierCanvas(...);
|
||||
* QObject::connect(canvas, SIGNAL(Done(Int_t)), app, SLOT(Quit()));
|
||||
* @endcode
|
||||
*
|
||||
* @see LastCanvasClosed()
|
||||
* @see SaveGraphicsAndQuit()
|
||||
*/
|
||||
void PFourierCanvas::Done(Int_t status)
|
||||
{
|
||||
@@ -198,19 +271,37 @@ void PFourierCanvas::Done(Int_t status)
|
||||
// HandleCmdKey (SLOT)
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Filters keyboard events, and if they are a command key (see below) carries out the
|
||||
* necessary actions.
|
||||
* <p>Currently implemented command keys:
|
||||
* - 'q' quit musrview
|
||||
* - 'u' unzoom to the original plot range given in the msr-file.
|
||||
* - 'a' toggle between average view and single Fourier histo view.
|
||||
* - '+' increment the phase (real/imaginary Fourier). The phase step is defined in the musrfit_startup.xml
|
||||
* - '-' decrement the phase (real/imaginary Fourier). The phase step is defined in the musrfit_startup.xml
|
||||
* <p>Processes keyboard shortcuts for canvas control.
|
||||
*
|
||||
* \param event event type
|
||||
* \param x character key
|
||||
* \param y not used
|
||||
* \param selected not used
|
||||
* <p>This slot receives keyboard events from ROOT and dispatches
|
||||
* appropriate actions. Ignored in batch mode.
|
||||
*
|
||||
* <p><b>Keyboard shortcuts:</b>
|
||||
* - <b>'q':</b> Quit - emits Done(0) signal to close canvas
|
||||
* - <b>'u':</b> Unzoom - reset view to initial X/Y range
|
||||
* - <b>'a':</b> Toggle all-data average view on/off
|
||||
* - <b>'d':</b> Toggle per-dataset average view on/off
|
||||
* - <b>'c':</b> Toggle crosshair cursor on/off
|
||||
* - <b>'+':</b> Increment phase by 5° (Re/Im views only)
|
||||
* - <b>'-':</b> Decrement phase by 5° (Re/Im views only)
|
||||
*
|
||||
* <p><b>Phase adjustment:</b> Only affects Real and Imaginary Fourier
|
||||
* views. Phase value is displayed as text overlay on canvas.
|
||||
*
|
||||
* <p><b>Average toggling:</b> 'a' and 'd' are mutually exclusive.
|
||||
* Activating one deactivates the other. Switching triggers histogram
|
||||
* recomputation via HandleAverage().
|
||||
*
|
||||
* @param event ROOT event type (must be kKeyPress to process)
|
||||
* @param x ASCII code of pressed key
|
||||
* @param y Mouse y-coordinate (unused)
|
||||
* @param selected Object under cursor (unused)
|
||||
*
|
||||
* @see IncrementFourierPhase()
|
||||
* @see DecrementFourierPhase()
|
||||
* @see HandleAverage()
|
||||
* @see PlotFourier()
|
||||
* @see PlotAverage()
|
||||
*/
|
||||
void PFourierCanvas::HandleCmdKey(Int_t event, Int_t x, Int_t y, TObject *selected)
|
||||
{
|
||||
@@ -282,9 +373,33 @@ void PFourierCanvas::HandleCmdKey(Int_t event, Int_t x, Int_t y, TObject *select
|
||||
// HandleMenuPopup (SLOT)
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Handles the MusrFT menu.
|
||||
* <p>Processes menu selection events from the MusrFT menu bar.
|
||||
*
|
||||
* \param id identification key of the selected menu
|
||||
* <p>Handles all menu item clicks including:
|
||||
* - Fourier view mode selection (Real/Imag/Power/Phase/etc.)
|
||||
* - Averaging mode toggles (All/Per-dataset/Off)
|
||||
* - Phase adjustment (±5°)
|
||||
* - Data export
|
||||
*
|
||||
* <p><b>Menu structure:</b>
|
||||
* - <b>MusrFT/Fourier:</b> View mode submenu
|
||||
* - Real, Imaginary, Real+Imag, Power, Phase, Phase-Optimized
|
||||
* - Phase +/- adjustments
|
||||
* - <b>MusrFT/Average:</b> All-data average toggle
|
||||
* - <b>MusrFT/Average Per Data Set:</b> Per-dataset average toggle
|
||||
* - <b>MusrFT/Export Data:</b> Save to ASCII file
|
||||
*
|
||||
* <p>View changes trigger canvas redraw with new histogram type.
|
||||
* Averaging changes recompute histograms via HandleAverage().
|
||||
*
|
||||
* <p>Ignored in batch mode.
|
||||
*
|
||||
* @param id Menu item identifier (P_MENU_ID_* constants)
|
||||
*
|
||||
* @see HandleAverage()
|
||||
* @see PlotFourier()
|
||||
* @see PlotAverage()
|
||||
* @see ExportData()
|
||||
*/
|
||||
void PFourierCanvas::HandleMenuPopup(Int_t id)
|
||||
{
|
||||
@@ -473,9 +588,26 @@ void PFourierCanvas::UpdateInfoPad()
|
||||
// SetTimeout (public)
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>sets the timeout after which the program shall terminate.
|
||||
* <p>Configures automatic canvas closure after specified timeout.
|
||||
*
|
||||
* \param timeout after which the done signal shall be emitted. Given in seconds
|
||||
* <p>Creates and starts a ROOT TTimer that emits Done() signal after
|
||||
* the timeout expires. Useful for:
|
||||
* - Batch processing with timed display
|
||||
* - Automated testing and screenshot capture
|
||||
* - Slideshow-style data review
|
||||
*
|
||||
* <p>If timeout ≤ 0, no timer is created (infinite display time).
|
||||
*
|
||||
* <p><b>Timer behavior:</b> Single-shot (kTRUE flag), fires once then stops.
|
||||
*
|
||||
* @param timeout Duration in <b>seconds</b> before auto-close (≤0 = disabled)
|
||||
*
|
||||
* <p><b>Example:</b>
|
||||
* @code
|
||||
* canvas->SetTimeout(30); // Close after 30 seconds
|
||||
* @endcode
|
||||
*
|
||||
* @see Done()
|
||||
*/
|
||||
void PFourierCanvas::SetTimeout(Int_t timeout)
|
||||
{
|
||||
@@ -495,9 +627,32 @@ void PFourierCanvas::SetTimeout(Int_t timeout)
|
||||
// SaveGraphicsAndQuit
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Will save the canvas as graphics output. Needed in the batch mode of musrview.
|
||||
* <p>Exports canvas to graphics file and terminates.
|
||||
*
|
||||
* \param fileName file name under which the canvas shall be saved.
|
||||
* <p>Saves current canvas view to image file, then emits Done(0) signal
|
||||
* to trigger cleanup. Primary use: batch mode automated plotting.
|
||||
*
|
||||
* <p><b>Supported formats</b> (determined by file extension):
|
||||
* - <b>.pdf:</b> Vector PDF (best for publications)
|
||||
* - <b>.eps:</b> Encapsulated PostScript (vector)
|
||||
* - <b>.png:</b> Raster PNG (good for web/presentations)
|
||||
* - <b>.jpg/.jpeg:</b> Raster JPEG (compressed)
|
||||
* - <b>.svg:</b> Scalable Vector Graphics
|
||||
* - <b>.root:</b> ROOT file (preserves interactive features)
|
||||
* - <b>.C:</b> ROOT macro (for programmatic recreation)
|
||||
*
|
||||
* <p>ROOT's TCanvas::SaveAs() handles format detection automatically.
|
||||
*
|
||||
* @param fileName Output file path with extension indicating format
|
||||
*
|
||||
* <p><b>Batch mode workflow:</b>
|
||||
* @code
|
||||
* PFourierCanvas *canvas = new PFourierCanvas(..., batch=true);
|
||||
* canvas->SaveGraphicsAndQuit("output.pdf");
|
||||
* // Canvas closes automatically after saving
|
||||
* @endcode
|
||||
*
|
||||
* @see Done()
|
||||
*/
|
||||
void PFourierCanvas::SaveGraphicsAndQuit(const Char_t *fileName)
|
||||
{
|
||||
@@ -512,7 +667,44 @@ void PFourierCanvas::SaveGraphicsAndQuit(const Char_t *fileName)
|
||||
// ExportData
|
||||
//--------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Exports the currently displayed Fourier data set in ascii column format.
|
||||
* <p>Exports currently displayed Fourier spectrum to ASCII data file.
|
||||
*
|
||||
* <p>Writes frequency/field values and corresponding spectrum amplitudes
|
||||
* in columnar text format suitable for:
|
||||
* - External plotting tools (Origin, MATLAB, Gnuplot, etc.)
|
||||
* - Statistical analysis packages (R, Python, etc.)
|
||||
* - Spreadsheet applications (Excel, LibreOffice)
|
||||
* - Archival data storage
|
||||
*
|
||||
* <p><b>File format:</b>
|
||||
* - Header: Column labels (X-axis, dataset names)
|
||||
* - Data: Space-separated columns
|
||||
* - Column 1: Frequency/field values
|
||||
* - Columns 2+: Spectrum values for each dataset
|
||||
*
|
||||
* <p><b>Exported spectrum:</b> Depends on current view mode:
|
||||
* - Real view → Real parts
|
||||
* - Imaginary view → Imaginary parts
|
||||
* - Power view → Power spectra
|
||||
* - Phase view → Phase spectra
|
||||
* - Phase-optimized → Phase-corrected real parts
|
||||
* - Real+Imag view → Both real and imaginary columns
|
||||
*
|
||||
* <p><b>Averaging:</b> If average mode active, exports averaged data
|
||||
* instead of individual runs.
|
||||
*
|
||||
* <p><b>X-range:</b> Only exports visible X-axis range (honors zoom).
|
||||
*
|
||||
* @param pathFileName Output file path (typically .dat extension).
|
||||
* Must not be nullptr.
|
||||
*
|
||||
* <p><b>Example output format:</b>
|
||||
* @code
|
||||
* # Field(G) Run1_Real Run2_Real Run3_Real
|
||||
* 100.5 0.234 0.221 0.245
|
||||
* 101.0 0.198 0.187 0.203
|
||||
* ...
|
||||
* @endcode
|
||||
*/
|
||||
void PFourierCanvas::ExportData(const Char_t *pathFileName)
|
||||
{
|
||||
|
||||
Reference in New Issue
Block a user