From 934b5cab4be338c6a2c84e1e42152252b69e5da4 Mon Sep 17 00:00:00 2001 From: Andreas Suter Date: Mon, 24 Nov 2025 10:53:43 +0100 Subject: [PATCH] improve the doxygen docu of PFindDialog.* (musredit_qt6). --- src/musredit_qt6/musredit/PFindDialog.cpp | 61 +++++++++++++++++++--- src/musredit_qt6/musredit/PFindDialog.h | 62 +++++++++++++++++++++-- 2 files changed, 112 insertions(+), 11 deletions(-) diff --git a/src/musredit_qt6/musredit/PFindDialog.cpp b/src/musredit_qt6/musredit/PFindDialog.cpp index f2e30e36d..5aee28394 100644 --- a/src/musredit_qt6/musredit/PFindDialog.cpp +++ b/src/musredit_qt6/musredit/PFindDialog.cpp @@ -27,6 +27,19 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PFindDialog.cpp + * @brief Implementation of the PFindDialog class. + * @details This file implements the find dialog functionality for the musredit + * text editor. The dialog allows users to search for text with various options + * such as case sensitivity, whole word matching, and search direction. + * + * @author Andreas Suter + * @date 2009-2025 + * @copyright Copyright (C) 2009-2025 by Andreas Suter + * @license GNU General Public License v2 or later + */ + #include #include #include @@ -37,12 +50,23 @@ //---------------------------------------------------------------------------------------------------- /** - *

Sets up the find dialog. + * @brief Constructs and initializes the find dialog. * - * \param data pointer to the find/replace data structure needed to perform the task. - * \param selection flag indicating if the find shall be restricted to the selected area - * \param parent pointer to the parent object - * \param f qt specific window flags + * @details Sets up the find dialog UI and initializes all controls with values + * from the provided data structure. The dialog is created as modal. + * + * The constructor performs the following initialization: + * -# Sets up the UI from the .ui file + * -# Disables the Find button if no search text is provided + * -# Disables the "Selected text" option if no text is selected in the editor + * -# Populates all controls with values from the data structure + * + * @param data Pointer to a PFindReplaceData structure containing initial search + * parameters and receiving the user's selections on dialog close. + * @param selection If true, text is currently selected in the editor and the + * "search in selection" option is enabled; if false, the option + * is disabled and unchecked. + * @param parent Pointer to the parent widget (typically the main editor window). */ PFindDialog::PFindDialog(PFindReplaceData *data, const bool selection, QWidget *parent) : QDialog(parent), fData(data) @@ -75,8 +99,22 @@ PFindDialog::PFindDialog(PFindReplaceData *data, const bool selection, QWidget * //---------------------------------------------------------------------------------------------------- /** - *

Extracts all the necessary informations from the find dialog, feeds it to the find/replace - * structure and returns a point to this structure. + * @brief Retrieves the search parameters from the dialog. + * + * @details Extracts the current values from all dialog controls and updates + * the PFindReplaceData structure. This method should be called after the + * dialog is accepted to retrieve the user's search settings. + * + * The following values are extracted: + * - findText: The text to search for + * - caseSensitive: Whether to match case + * - wholeWordsOnly: Whether to match whole words only + * - fromCursor: Whether to start search from cursor position + * - findBackwards: Whether to search backwards + * - selectedText: Whether to search only within selected text (if enabled) + * + * @return Pointer to the updated PFindReplaceData structure containing + * all search parameters as set by the user. */ PFindReplaceData* PFindDialog::getData() { @@ -93,7 +131,14 @@ PFindReplaceData* PFindDialog::getData() //---------------------------------------------------------------------------------------------------- /** - *

Enables the find button only if there is any find text entered. + * @brief Slot to enable/disable the Find button based on search text availability. + * + * @details This slot is connected to the text changed signal of the find combo box. + * It enables the Find button only when there is text to search for, preventing + * empty searches. + * + * @param text The current text in the combo box (parameter unused; the method + * reads directly from the widget to handle all input scenarios). */ void PFindDialog::onFindTextAvailable(const QString&) { diff --git a/src/musredit_qt6/musredit/PFindDialog.h b/src/musredit_qt6/musredit/PFindDialog.h index f2d963792..9d598ef8e 100644 --- a/src/musredit_qt6/musredit/PFindDialog.h +++ b/src/musredit_qt6/musredit/PFindDialog.h @@ -27,6 +27,22 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PFindDialog.h + * @brief Find dialog for text searching in musredit. + * @details This header defines the PFindDialog class which provides a dialog + * for searching text within msr files. The dialog supports various search + * options including case sensitivity, whole word matching, and search direction. + * + * @author Andreas Suter + * @date 2010-2025 + * @copyright Copyright (C) 2010-2025 by Andreas Suter + * @license GNU General Public License v2 or later + * + * @see PReplaceDialog For find and replace functionality + * @see PFindReplaceData For the data structure used by this dialog + */ + #ifndef _PFINDDIALOG_H_ #define _PFINDDIALOG_H_ @@ -35,7 +51,39 @@ //-------------------------------------------------------------------------------------------------- /** - *

PFindDialog is the class handling the find dialog. + * @class PFindDialog + * @brief Dialog for searching text in the editor. + * + * @details This class implements a modal dialog that allows users to search for + * text within the current msr file. The dialog provides various search options + * and stores the search parameters in a PFindReplaceData structure. + * + * @par Search Options: + * - Case sensitive matching + * - Whole words only matching + * - Search from cursor position or document start + * - Forward or backward search direction + * - Search within selected text only (when text is selected) + * + * @par UI Elements: + * The dialog UI is defined in PFindDialog.ui and includes: + * - A combo box (fFind_comboBox) for entering and selecting search text + * - Checkboxes for search options + * - Find and Cancel buttons + * + * @par Usage: + * @code + * PFindReplaceData data; + * data.findText = "searchterm"; + * PFindDialog dialog(&data, hasSelection, this); + * if (dialog.exec() == QDialog::Accepted) { + * PFindReplaceData *result = dialog.getData(); + * // Perform search with result->findText + * } + * @endcode + * + * @see PReplaceDialog For combined find and replace functionality + * @see PFindReplaceData For the structure storing search parameters */ class PFindDialog : public QDialog, private Ui::PFindDialog { @@ -43,15 +91,23 @@ class PFindDialog : public QDialog, private Ui::PFindDialog public: PFindDialog(PFindReplaceData *data, const bool selection, QWidget *parent = nullptr); + + /** + * @brief Virtual destructor. + */ virtual ~PFindDialog() {} virtual PFindReplaceData *getData(); protected slots: - virtual void onFindTextAvailable(const QString&); + /** + * @brief Slot called when the find text changes. + * @param text The current text in the find combo box (unused, reads from widget directly). + */ + virtual void onFindTextAvailable(const QString& text); private: - PFindReplaceData *fData; ///< stores the data necessary to perform find/replace. + PFindReplaceData *fData; ///< Pointer to the find/replace data structure for storing search parameters. }; #endif // _PFINDDIALOG_H_