diff --git a/src/musredit_qt6/musredit/PGetTitleBlockDialog.cpp b/src/musredit_qt6/musredit/PGetTitleBlockDialog.cpp index 806d8c0b5..d9dfefb1d 100644 --- a/src/musredit_qt6/musredit/PGetTitleBlockDialog.cpp +++ b/src/musredit_qt6/musredit/PGetTitleBlockDialog.cpp @@ -27,6 +27,19 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PGetTitleBlockDialog.cpp + * @brief Implementation of the TITLE block dialog for musredit. + * + * @details Provides the implementation of PGetTitleBlockDialog class methods + * for creating and editing TITLE blocks in musrfit msr files. The dialog + * offers a straightforward text input interface for entering descriptive + * titles that document the purpose or content of the analysis. + * + * @author Andreas Suter + * @date 2010-2025 + */ + #include #include #include @@ -35,9 +48,33 @@ //--------------------------------------------------------------------------- /** - *

Constructor. + * @brief Constructor - Initializes the TITLE block dialog. * - * \param helpUrl help url for the title. + * @details Sets up the user interface for the title input dialog. The dialog + * contains a single QLineEdit widget for text entry and standard OK/Cancel + * buttons. The interface is loaded from the UI definition file and configured + * as a modal dialog. + * + * The dialog is designed to be simple and focused, presenting only the + * essential controls needed to enter or edit a title string. No complex + * initialization or data loading is required beyond basic UI setup. + * + * The modal configuration ensures that users complete the title entry or + * explicitly cancel before returning to the main editor, preventing + * incomplete or ambiguous states. + * + * @param helpUrl URL string for the online help documentation. If empty, the + * help button will display a placeholder message instead of + * opening a web browser. The URL should point to documentation + * explaining the purpose and format of msr file titles. + * + * @note The dialog does not validate the title content. Validation, if needed, + * should be performed by the caller after retrieving the title via + * getTitle(). + * + * @see setupUi() Qt Designer generated UI initialization method + * @see setModal() Configures the dialog as modal + * @see getTitle() Retrieves the entered title after dialog acceptance */ PGetTitleBlockDialog::PGetTitleBlockDialog(const QString helpUrl) : fHelpUrl(helpUrl) { @@ -48,7 +85,32 @@ PGetTitleBlockDialog::PGetTitleBlockDialog(const QString helpUrl) : fHelpUrl(hel //--------------------------------------------------------------------------- /** - *

Generates a help content window showing the description of title block. + * @brief Opens online help documentation for TITLE blocks. + * + * @details Attempts to open the help URL in the user's default web browser using + * QDesktopServices::openUrl(). The help documentation typically provides: + * - Explanation of the TITLE block's purpose in msr files + * - Format specifications and constraints + * - Examples of well-formed titles for various analysis types + * - Best practices for creating informative and consistent titles + * + * Error handling: + * - If fHelpUrl is empty: displays an information dialog with a placeholder + * message indicating that help documentation will be available in the future + * - If the browser fails to open: displays a critical error dialog with the URL + * formatted as a clickable hyperlink, allowing users to manually copy and + * paste the URL into their browser + * + * The URL is parsed in TolerantMode, which allows for flexible URL formatting + * and automatically handles common URL variations (e.g., with or without + * protocol specification). + * + * @note This slot is connected to the help button click signal in the UI. + * @note The dialog remains open after help is displayed, allowing users to + * reference the documentation while entering the title. + * + * @see PGetTitleBlockDialog::PGetTitleBlockDialog() Where fHelpUrl is initialized + * @see QDesktopServices::openUrl() For the browser opening mechanism */ void PGetTitleBlockDialog::helpContent() { diff --git a/src/musredit_qt6/musredit/PGetTitleBlockDialog.h b/src/musredit_qt6/musredit/PGetTitleBlockDialog.h index 07dd295e0..f69e7d9cc 100644 --- a/src/musredit_qt6/musredit/PGetTitleBlockDialog.h +++ b/src/musredit_qt6/musredit/PGetTitleBlockDialog.h @@ -27,6 +27,25 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PGetTitleBlockDialog.h + * @brief Dialog for creating and editing TITLE blocks in msr files. + * + * @details This header defines the PGetTitleBlockDialog class which provides + * a simple dialog for entering or editing the title line of a musrfit msr file. + * The TITLE block is optional but commonly used to provide a descriptive name + * or summary for the fit analysis. + * + * @author Andreas Suter + * @date 2010-2025 + * @copyright Copyright (C) 2010-2025 by Andreas Suter + * @license GNU General Public License v2 or later + * + * @see PGetParameterBlockDialog For creating FITPARAMETER blocks + * @see PGetTheoryBlockDialog For creating THEORY blocks + * @see PGetFunctionsBlockDialog For creating FUNCTIONS blocks + */ + #ifndef _PGETTITLEBLOCKDIALOG_H_ #define _PGETTITLEBLOCKDIALOG_H_ @@ -35,23 +54,104 @@ //-------------------------------------------------------------------------- /** - *

Class handling the content of the menu: Edit/Add Block/Title Block. + * @class PGetTitleBlockDialog + * @brief Dialog for creating and editing TITLE blocks in msr files. + * + * @details This dialog provides a simple text input interface for entering + * or modifying the title of a musrfit msr file. The title serves as a + * descriptive label for the analysis and appears at the beginning of the + * msr file. + * + * @par TITLE Block Format: + * The TITLE block consists of a single line in the msr file: + * @code + * sample_name or_measurement_description + * @endcode + * + * @par Usage: + * The dialog is accessed through the menu: Edit → Add Block → Title Block. + * It presents a single-line text input field where users can enter or edit + * the title text. The dialog is modal, requiring user interaction before + * returning to the main editor. + * + * @par Example Titles: + * - "TF-ZF transition measurement on Cu sample at 10K" + * - "Longitudinal field scan H=0-2000G" + * - "Temperature dependence study 5-300K" + * + * @note The title is optional in msr files but recommended for documentation + * purposes. + * @note The title should be a single line without newline characters. + * + * @see musredit Main editor application */ class PGetTitleBlockDialog : public QDialog, private Ui::PGetTitleBlockDialog { Q_OBJECT public: + /** + * @brief Constructs a dialog for entering or editing a title. + * + * @details Initializes the dialog with a text input field and help button. + * The dialog is configured as modal to ensure user interaction completion + * before returning to the main editor window. + * + * @param helpUrl URL string pointing to online documentation for TITLE blocks. + * If empty, the help button will display a placeholder message. + * + * @see helpContent() For the help system implementation + */ PGetTitleBlockDialog(const QString helpUrl); + + /** + * @brief Virtual destructor. + * + * @details Default destructor implementation. Qt's parent-child ownership + * system handles cleanup of UI elements automatically. + */ virtual ~PGetTitleBlockDialog() {} + /** + * @brief Returns the entered title text. + * + * @details Retrieves the text currently entered in the title line edit field. + * This method is typically called after the dialog is accepted to obtain + * the title string for insertion into the msr file. + * + * @return QString containing the title text entered by the user. May be + * empty if no text was entered. The returned string is trimmed + * of leading/trailing whitespace by the QLineEdit widget. + * + * @note The caller should validate that the returned string does not contain + * newline characters, as msr file titles must be single-line. + * + * @see QLineEdit::text() For the underlying widget method + */ QString getTitle() { return fTitle_lineEdit->text(); } private slots: + /** + * @brief Opens the online help for TITLE blocks. + * + * @details Attempts to open the help URL in the system's default web browser + * using QDesktopServices. If the URL is empty, displays a placeholder + * information message. If the browser cannot be opened, shows an error + * dialog with the URL for manual access. + * + * The help documentation typically covers: + * - Purpose and format of the TITLE block + * - Examples of well-formed titles + * - Best practices for title naming + * + * @note Connected to the help button click signal in the UI. + * + * @see PGetTitleBlockDialog::PGetTitleBlockDialog() Where helpUrl is set + */ void helpContent(); private: - QString fHelpUrl; ///< help url for the asymmetry run block + QString fHelpUrl; ///< URL to the online documentation for TITLE blocks. }; #endif // _PGETTITLEBLOCKDIALOG_H_