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

  PGetParameterBlockDialog.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 PGetParameterBlockDialog.h
 * @brief Dialog for creating FITPARAMETER blocks in msr files.
 * @details This header defines the PGetParameterBlockDialog class which provides
 * a dialog for entering fit parameters needed to create a FITPARAMETER block
 * in a musrfit msr file. The dialog supports parameter entry with validation
 * and optional boundary constraints.
 *
 * @author Andreas Suter
 * @date 2009-2025
 * @copyright Copyright (C) 2009-2025 by Andreas Suter
 * @license GNU General Public License v2 or later
 *
 * @see PGetFunctionsBlockDialog For creating FUNCTIONS blocks using these parameters
 * @see PGetTheoryBlockDialog For creating THEORY blocks
 */

#ifndef _PGETPARAMETERBLOCKDIALOG_H_
#define _PGETPARAMETERBLOCKDIALOG_H_

#include "ui_PGetParameterBlockDialog.h"

//---------------------------------------------------------------------------
/**
 * @class PGetParameterBlockDialog
 * @brief Dialog for creating FITPARAMETER blocks in msr files.
 *
 * @details This dialog allows users to define fit parameters for musrfit.
 * Each parameter consists of a number, name, initial value, step size, and
 * optional lower/upper boundaries. Parameters are formatted with proper
 * column alignment for the msr file format.
 *
 * @par Parameter Fields:
 * - **No**: Parameter number (auto-incremented)
 * - **Name**: Parameter name (required, max ~12 chars for alignment)
 * - **Value**: Initial parameter value (required)
 * - **Step**: Initial step size for minimizer (required)
 * - **Lower**: Lower boundary ("none" or numeric value)
 * - **Upper**: Upper boundary ("none" or numeric value)
 *
 * @par Generated Output Format:
 * The dialog generates properly formatted FITPARAMETER lines:
 * @code
 * FITPARAMETER
 *          1 alpha        1.0       0.01      none
 *          2 beta         0.5       0.001     none       0.0        1.0
 *          3 frequency    10.5      0.1       none
 * @endcode
 *
 * @par User Interaction:
 * - Press Return/Enter key to quickly add parameters
 * - Parameter number auto-increments after each addition
 * - Input fields are reset after adding a parameter
 * - Focus returns to the Name field for rapid entry
 *
 * @see PGetFunctionsBlockDialog For defining functions using these parameters
 */
class PGetParameterBlockDialog : public QDialog, private Ui::PGetParameterBlockDialog
{
  Q_OBJECT

  public:
    PGetParameterBlockDialog(const QString helpUrl);

    /**
     * @brief Returns all entered parameters as formatted text.
     * @return Complete FITPARAMETER block content ready for insertion
     *         into an msr file.
     */
    QString getParams() { return fParam_plainTextEdit->toPlainText(); }

  protected:
    /**
     * @brief Event filter to handle keyboard shortcuts.
     * @details Intercepts the Return key to trigger parameter addition,
     *          allowing for rapid parameter 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 slots:
    /**
     * @brief Validates and adds a parameter to the FITPARAMETER block.
     */
    void paramAdd();

    /**
     * @brief Opens the online help for FITPARAMETER blocks.
     */
    void helpContent();

  private:
    QString fHelpUrl; ///< URL to the online documentation for FITPARAMETER blocks.
};

#endif // _PGETPARAMETERBLOCKDIALOG_H_