/****************************************************************************

  PGetPlotBlockDialog.h

  Author: Andreas Suter
  e-mail: andreas.suter@psi.ch

*****************************************************************************/

/***************************************************************************
 *   Copyright (C) 2009-2025 by Andreas Suter                              *
 *   andreas.suter@psi.ch                                                  *
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 *   This program is distributed in the hope that it will be useful,       *
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
 *   GNU General Public License for more details.                          *
 *                                                                         *
 *   You should have received a copy of the GNU General Public License     *
 *   along with this program; if not, write to the                         *
 *   Free Software Foundation, Inc.,                                       *
 *   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"

//---------------------------------------------------------------------------
/**
 * @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
{
  Q_OBJECT

  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; ///< URL to the online documentation for PLOT blocks.
};

#endif // _PGETPLOTBLOCKDIALOG_H_