From 9fa970a53ecd93f7da896d3cd41b9c5d20a236dc Mon Sep 17 00:00:00 2001 From: Andreas Suter Date: Tue, 25 Nov 2025 08:39:44 +0100 Subject: [PATCH] improve the doxygen docu of PReplaceConfirmationDialog.* (musredit_qt6). --- .../musredit/PReplaceConfirmationDialog.cpp | 90 +++++++++++++- .../musredit/PReplaceConfirmationDialog.h | 110 ++++++++++++++++++ 2 files changed, 197 insertions(+), 3 deletions(-) diff --git a/src/musredit_qt6/musredit/PReplaceConfirmationDialog.cpp b/src/musredit_qt6/musredit/PReplaceConfirmationDialog.cpp index f699b0471..63b8eaf94 100644 --- a/src/musredit_qt6/musredit/PReplaceConfirmationDialog.cpp +++ b/src/musredit_qt6/musredit/PReplaceConfirmationDialog.cpp @@ -27,14 +27,98 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PReplaceConfirmationDialog.cpp + * @brief Implementation of the find-and-replace confirmation dialog. + * + * @details Provides the implementation of the PReplaceConfirmationDialog + * class which handles user confirmation for individual replacements during + * interactive find-and-replace operations in musredit. The dialog provides + * a simple, focused interface for making replacement decisions. + * + * @author Andreas Suter + * @date 2010-2025 + */ + #include "PReplaceConfirmationDialog.h" //---------------------------------------------------------------------------------------------------- /** - *

Constructor. + * @brief Constructor - Initializes the replace confirmation dialog. * - * \param parent pointer to the parent object - * \param f qt windows flags + * @details Sets up a simple, focused dialog for confirming individual + * replacements during interactive find-and-replace operations. The + * initialization is minimal, establishing only the essential dialog + * configuration for user interaction. + * + * **Initialization Process:** + * + * 1. **Base Class Initialization**: Calls QDialog constructor with parent + * widget to establish proper parent-child relationship + * + * 2. **UI Setup**: Loads the dialog layout, labels, and buttons from the + * Qt Designer UI file via setupUi(). The UI file defines: + * - Dialog title and dimensions + * - Confirmation message text + * - Action buttons (Replace, Skip, Replace All, Cancel, etc.) + * - Button layout and spacing + * - Keyboard shortcuts for quick access + * + * 3. **Modal Configuration**: Sets the dialog as modal using setModal(true), + * ensuring that: + * - The dialog blocks interaction with the main editor + * - User must make an explicit decision + * - No other editor operations can occur until dialog is closed + * - Focus remains on the dialog until user responds + * + * **Dialog Workflow:** + * + * After construction, the typical usage pattern is: + * 1. Caller creates dialog instance (this constructor executes) + * 2. Caller updates dialog text to show current match context (optional) + * 3. Caller invokes exec() to display dialog and wait for user response + * 4. User clicks a button (Replace, Skip, Replace All, Cancel) + * 5. Dialog returns with appropriate QDialog result code + * 6. Caller interprets result and takes appropriate action + * 7. Process repeats for next match or terminates + * + * **Button Actions (typical configuration):** + * - **Replace button**: Returns QDialog::Accepted, triggers replacement + * - **Skip button**: Returns custom code, advances without replacing + * - **Replace All**: Returns custom code, batch replaces remaining matches + * - **Cancel button**: Returns QDialog::Rejected, aborts operation + * + * **Modal Behavior Benefits:** + * - Prevents accidental document edits during confirmation + * - Maintains clear workflow state + * - Ensures user attention on decision + * - Simplifies state management in calling code + * + * @param parent Pointer to the parent widget, typically the main musredit + * editor window. The parent relationship provides: + * - Automatic dialog centering over parent window + * - Consistent visual style and theme + * - Automatic cleanup when parent is destroyed + * - Proper z-order (dialog appears on top of parent) + * + * If nullptr, the dialog has no parent and will not center + * over any specific window, though it will still be modal + * with respect to the application. + * + * @note The dialog is created but not displayed by the constructor. Use + * exec() or show() to make it visible to the user. + * @note The actual button configuration and return codes are determined by + * the UI file design and any signal-slot connections established there. + * @note Modal dialogs entered via exec() run their own event loop, blocking + * the calling code until the dialog closes. + * @note The simple constructor design (no parameters for search/replace text) + * suggests the dialog may be updated after construction but before + * display, or that it shows generic confirmation text. + * + * @see exec() Qt method to display the dialog modally and return user choice + * @see setModal() Qt method that configures modal behavior (called here) + * @see setupUi() Qt Designer generated method that constructs the UI + * @see QDialog For base class documentation on dialog behavior and return codes */ PReplaceConfirmationDialog::PReplaceConfirmationDialog(QWidget *parent) : QDialog(parent) { diff --git a/src/musredit_qt6/musredit/PReplaceConfirmationDialog.h b/src/musredit_qt6/musredit/PReplaceConfirmationDialog.h index f47142d8e..14305a265 100644 --- a/src/musredit_qt6/musredit/PReplaceConfirmationDialog.h +++ b/src/musredit_qt6/musredit/PReplaceConfirmationDialog.h @@ -27,6 +27,25 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PReplaceConfirmationDialog.h + * @brief Confirmation dialog for find-and-replace operations in musredit. + * + * @details This header defines the PReplaceConfirmationDialog class which + * provides a user confirmation dialog for search-and-replace operations in + * the musredit text editor. The dialog allows users to confirm, skip, or + * control individual replacements during interactive find-and-replace + * sessions. + * + * @author Andreas Suter + * @date 2010-2025 + * @copyright Copyright (C) 2010-2025 by Andreas Suter + * @license GNU General Public License v2 or later + * + * @see musredit Main editor application with find-and-replace functionality + * @see PFindDialog For the find/replace search dialog + */ + #ifndef _PREPLACECONFIRMATIONDIALOG_H_ #define _PREPLACECONFIRMATIONDIALOG_H_ @@ -35,12 +54,103 @@ #include "ui_PReplaceConfirmationDialog.h" +/** + * @class PReplaceConfirmationDialog + * @brief Confirmation dialog for interactive find-and-replace operations. + * + * @details This dialog provides user control over individual replacement + * operations during interactive find-and-replace sessions in musredit. When + * the user performs a "Replace" (as opposed to "Replace All") operation, this + * dialog appears for each match, allowing fine-grained control over which + * instances should be replaced. + * + * @par Dialog Purpose: + * The dialog serves as an interactive confirmation mechanism that prevents + * unintended replacements by giving users the opportunity to review each + * match before replacement occurs. + * + * @par Typical User Actions: + * The dialog typically provides several options (exact buttons defined in UI): + * - **Replace**: Confirm this replacement and move to next match + * - **Skip**: Leave this match unchanged and move to next match + * - **Replace All**: Replace this and all remaining matches without further confirmation + * - **Cancel/Close**: Abort the replace operation entirely + * + * @par Usage Context: + * This dialog is invoked during interactive find-and-replace workflows: + * 1. User opens Find/Replace dialog (Edit → Find/Replace) + * 2. User enters search term and replacement text + * 3. User clicks "Replace" button (not "Replace All") + * 4. Editor finds first match and shows context + * 5. This confirmation dialog appears + * 6. User makes decision (replace/skip/etc.) + * 7. Process repeats for next match until completion or cancellation + * + * @par Dialog Behavior: + * - Modal: Blocks interaction with main editor until decision is made + * - Non-resizable: Fixed size appropriate for decision buttons + * - Centered over parent: Appears centered on the editor window + * - Quick keyboard access: Buttons typically have keyboard shortcuts + * + * @par Integration: + * The dialog integrates with musredit's find-and-replace engine, which: + * - Highlights the current match in the editor + * - Manages the search state across multiple matches + * - Executes the replacement based on user choice + * - Advances to the next match after each decision + * + * @note The dialog is modal, requiring explicit user action before continuing. + * @note Return values (via exec()) indicate the user's choice for action. + * @note The actual button configuration and return values are defined in the + * UI file and handled by the calling find-and-replace code. + * + * @see musredit For the main text editor with find-and-replace functionality + * @see PFindDialog For the primary find/replace dialog interface + */ class PReplaceConfirmationDialog : public QDialog, public Ui::PReplaceConfirmationDialog { Q_OBJECT public: + /** + * @brief Constructs the replace confirmation dialog. + * + * @details Initializes the dialog with a simple confirmation interface + * for find-and-replace operations. The dialog is configured as modal to + * ensure users make an explicit decision before continuing with the + * replacement process. + * + * The constructor sets up the UI from the Qt Designer UI file and + * configures basic dialog properties. The actual button configuration, + * labels, and layout are defined in the UI file. + * + * @param parent Pointer to the parent widget (typically the main editor + * window). If nullptr, the dialog has no parent. The + * parent-child relationship ensures: + * - Proper dialog centering over the parent window + * - Automatic cleanup when parent is destroyed + * - Consistent styling and theme inheritance + * + * @note The dialog is created but not shown by the constructor. The + * caller must invoke exec() to display it modally. + * @note Parent ownership is recommended to ensure proper cleanup and + * visual integration with the main application. + * + * @see exec() Qt method to display the dialog and wait for user response + * @see setupUi() Qt Designer generated UI initialization + */ PReplaceConfirmationDialog(QWidget *parent = nullptr); + + /** + * @brief Virtual destructor. + * + * @details Default destructor implementation. Qt's parent-child ownership + * system automatically handles cleanup of UI elements created by setupUi(). + * No manual resource cleanup is required. + * + * @note Declared virtual to ensure proper cleanup in inheritance + * hierarchies, following C++ best practices. + */ virtual ~PReplaceConfirmationDialog() {} };