File indexing completed on 2024-12-01 12:39:35
0001 /* 0002 This file is part of the KDE project 0003 SPDX-FileCopyrightText: 2001 S.R. Haque <srhaque@iee.org>. 0004 SPDX-FileCopyrightText: 2002 David Faure <david@mandrakesoft.com> 0005 0006 SPDX-License-Identifier: LGPL-2.0-only 0007 */ 0008 0009 #ifndef KFINDDIALOG_H 0010 #define KFINDDIALOG_H 0011 0012 #include "ktextwidgets_export.h" 0013 0014 #include <QDialog> 0015 #include <memory> 0016 0017 class KFindDialogPrivate; 0018 0019 /** 0020 * @class KFindDialog kfinddialog.h <KFindDialog> 0021 * 0022 * @brief A generic "find" dialog. 0023 * 0024 * @author S.R.Haque <srhaque@iee.org> 0025 * 0026 * \b Detail: 0027 * 0028 * This widget inherits from KDialog and implements 0029 * the following additional functionalities: a find string 0030 * object and an area for a user-defined widget to extend the dialog. 0031 * 0032 * \b Example: 0033 * 0034 * To use the basic modal find dialog, and then run the search: 0035 * 0036 * \code 0037 * KFindDialog dlg(....) 0038 * if (dlg.exec() != QDialog::Accepted) 0039 * return; 0040 * 0041 * // proceed with KFind from here 0042 * \endcode 0043 * 0044 * To create a non-modal find dialog: 0045 * \code 0046 * if (m_findDialog) { 0047 * m_findDialog->activateWindow(); 0048 * } else { 0049 * m_findDialog = new KFindDialog(...); 0050 * connect(m_findDialog, &KFindDialog::okClicked, this, [this] { 0051 * m_findDialog->close(); 0052 * delete m_find; 0053 * m_find = new KFind(m_findDialog->pattern(), m_findDialog->options(), this); 0054 * // ... see KFind documentation for what else should be done here 0055 * }); 0056 * } 0057 * \endcode 0058 * Don't forget to delete and reset m_findDialog when closed. 0059 * (But do NOT delete your KFind object at that point, it's needed for "Find Next".) 0060 * 0061 * To use your own extensions: see findExtension(). 0062 * 0063 * \image html kfinddialog.png "KFindDialog Widget" 0064 */ 0065 class KTEXTWIDGETS_EXPORT KFindDialog : public QDialog 0066 { 0067 Q_OBJECT 0068 0069 public: 0070 /** 0071 * Construct a modal find dialog 0072 * 0073 * @param parent The parent object of this widget. 0074 * @param options A bitfield of the Options to be checked. 0075 * @param findStrings The find history, see findHistory() 0076 * @param hasSelection Whether a selection exists 0077 */ 0078 explicit KFindDialog(QWidget *parent = nullptr, 0079 long options = 0, 0080 const QStringList &findStrings = QStringList(), 0081 bool hasSelection = false, 0082 bool replaceDialog = false); 0083 0084 /** 0085 * Destructor. 0086 */ 0087 ~KFindDialog() override; 0088 0089 /** 0090 * Provide the list of @p strings to be displayed as the history 0091 * of find strings. @p strings might get truncated if it is 0092 * too long. 0093 * 0094 * @param history The find history. 0095 * @see findHistory 0096 */ 0097 void setFindHistory(const QStringList &history); 0098 0099 /** 0100 * Returns the list of history items. 0101 * 0102 * @see setFindHistory 0103 */ 0104 QStringList findHistory() const; 0105 0106 /** 0107 * Enable/disable the 'search in selection' option, depending 0108 * on whether there actually is a selection. 0109 * 0110 * @param hasSelection true if a selection exists 0111 */ 0112 void setHasSelection(bool hasSelection); 0113 0114 /** 0115 * Hide/show the 'from cursor' option, depending 0116 * on whether the application implements a cursor. 0117 * 0118 * @param hasCursor true if the application features a cursor 0119 * This is assumed to be the case by default. 0120 */ 0121 void setHasCursor(bool hasCursor); 0122 0123 /** 0124 * Enable/disable the 'Find backwards' option, depending 0125 * on whether the application supports it. 0126 * 0127 * @param supports true if the application supports backwards find 0128 * This is assumed to be the case by default. 0129 */ 0130 void setSupportsBackwardsFind(bool supports); 0131 0132 /** 0133 * Enable/disable the 'Case sensitive' option, depending 0134 * on whether the application supports it. 0135 * 0136 * @param supports true if the application supports case sensitive find 0137 * This is assumed to be the case by default. 0138 */ 0139 void setSupportsCaseSensitiveFind(bool supports); 0140 0141 /** 0142 * Enable/disable the 'Whole words only' option, depending 0143 * on whether the application supports it. 0144 * 0145 * @param supports true if the application supports whole words only find 0146 * This is assumed to be the case by default. 0147 */ 0148 void setSupportsWholeWordsFind(bool supports); 0149 0150 /** 0151 * Enable/disable the 'Regular expression' option, depending 0152 * on whether the application supports it. 0153 * 0154 * @param supports true if the application supports regular expression find 0155 * This is assumed to be the case by default. 0156 */ 0157 void setSupportsRegularExpressionFind(bool supports); 0158 0159 /** 0160 * Set the options which are checked. 0161 * 0162 * @param options The setting of the Options. 0163 * 0164 * @see options() 0165 * @see KFind::Options 0166 */ 0167 void setOptions(long options); 0168 0169 /** 0170 * Returns the state of the options. Disabled options may be returned in 0171 * an indeterminate state. 0172 * 0173 * @see setOptions() 0174 * @see KFind::Options 0175 */ 0176 long options() const; 0177 0178 /** 0179 * Returns the pattern to find. 0180 */ 0181 QString pattern() const; 0182 0183 /** 0184 * Sets the pattern to find 0185 */ 0186 void setPattern(const QString &pattern); 0187 0188 /** 0189 * Returns an empty widget which the user may fill with additional UI 0190 * elements as required. The widget occupies the width of the dialog, 0191 * and is positioned immediately below the regular expression support 0192 * widgets for the pattern string. 0193 */ 0194 QWidget *findExtension() const; 0195 0196 Q_SIGNALS: 0197 /** 0198 * This signal is sent whenever one of the option checkboxes is toggled. 0199 * Call options() to get the new state of the checkboxes. 0200 */ 0201 void optionsChanged(); 0202 0203 /** 0204 * This signal is sent when the user clicks on Ok button. 0205 */ 0206 void okClicked(); 0207 0208 /** 0209 * This signal is sent when the user clicks on Cancel button. 0210 */ 0211 void cancelClicked(); 0212 0213 protected: 0214 void showEvent(QShowEvent *) override; 0215 0216 protected: 0217 KTEXTWIDGETS_NO_EXPORT explicit KFindDialog(KFindDialogPrivate &dd, 0218 QWidget *parent = nullptr, 0219 long options = 0, 0220 const QStringList &findStrings = QStringList(), 0221 bool hasSelection = false, 0222 bool replaceDialog = false); 0223 0224 private: 0225 friend class KReplaceDialog; 0226 Q_DECLARE_PRIVATE_D(d, KFindDialog) 0227 std::unique_ptr<class KFindDialogPrivate> const d; 0228 // KF6 TODO: change private d to protected d_ptr, use normal Q_DECLARE_PRIVATE, remove friend 0229 }; 0230 0231 #endif // KFINDDIALOG_H