1/*
2 This file is part of the KDE project
3 SPDX-FileCopyrightText: 2001 S.R. Haque <srhaque@iee.org>.
4 SPDX-FileCopyrightText: 2002 David Faure <david@mandrakesoft.com>
5 SPDX-FileCopyrightText: 2004 Arend van Beelen jr. <arend@auton.nl>
6
7 SPDX-License-Identifier: LGPL-2.0-only
8*/
9
10#ifndef KFINDDIALOG_H
11#define KFINDDIALOG_H
12
13#include "ktextwidgets_export.h"
14
15#include <QDialog>
16#include <memory>
17
18class KFindDialogPrivate;
19
20/*!
21 * \class KFindDialog
22 * \inmodule KTextWidgets
23 *
24 * \brief A generic "find" dialog.
25 *
26 * \b Detail:
27 *
28 * This widget inherits from KDialog and implements
29 * the following additional functionalities: a find string
30 * object and an area for a user-defined widget to extend the dialog.
31 *
32 * \b Example:
33 *
34 * To use the basic modal find dialog, and then run the search:
35 *
36 * \code
37 * KFindDialog dlg(....)
38 * if (dlg.exec() != QDialog::Accepted)
39 * return;
40 *
41 * // proceed with KFind from here
42 * \endcode
43 *
44 * To create a non-modal find dialog:
45 * \code
46 * if (m_findDialog) {
47 * m_findDialog->activateWindow();
48 * } else {
49 * m_findDialog = new KFindDialog(...);
50 * connect(m_findDialog, &KFindDialog::okClicked, this, [this] {
51 * m_findDialog->close();
52 * delete m_find;
53 * m_find = new KFind(m_findDialog->pattern(), m_findDialog->options(), this);
54 * // ... see KFind documentation for what else should be done here
55 * });
56 * }
57 * \endcode
58 * Don't forget to delete and reset m_findDialog when closed.
59 * (But do NOT delete your KFind object at that point, it's needed for "Find Next".)
60 *
61 * To use your own extensions: see findExtension().
62 *
63 * \image kfinddialog.png "KFindDialog Widget"
64 */
65class KTEXTWIDGETS_EXPORT KFindDialog : public QDialog
66{
67 Q_OBJECT
68
69public:
70 /*!
71 * Construct a modal find dialog
72 *
73 * \a parent The parent object of this widget.
74 *
75 * \a options A bitfield of the Options to be checked.
76 *
77 * \a findStrings The find history, see findHistory()
78 *
79 * \a hasSelection Whether a selection exists
80 */
81 explicit KFindDialog(QWidget *parent = nullptr,
82 long options = 0,
83 const QStringList &findStrings = QStringList(),
84 bool hasSelection = false,
85 bool replaceDialog = false);
86
87 /*!
88 * Destructor.
89 */
90 ~KFindDialog() override;
91
92 /*!
93 * Provide the list of strings to be displayed as the history
94 * of find strings. The \a history might get truncated if it is
95 * too long.
96 *
97 * \sa findHistory
98 */
99 void setFindHistory(const QStringList &history);
100
101 /*!
102 * Returns the list of history items.
103 *
104 * \sa setFindHistory
105 */
106 QStringList findHistory() const;
107
108 /*!
109 * Enable/disable the 'search in selection' option, depending
110 * on whether there actually is a selection.
111 *
112 * \a hasSelection true if a selection exists
113 */
114 void setHasSelection(bool hasSelection);
115
116 /*!
117 * Hide/show the 'from cursor' option, depending
118 * on whether the application implements a cursor.
119 *
120 * \a hasCursor true if the application features a cursor.
121 * This is assumed to be the case by default.
122 */
123 void setHasCursor(bool hasCursor);
124
125 /*!
126 * Enable/disable the 'Find backwards' option, depending
127 * on whether the application supports it.
128 *
129 * \a supports true if the application supports backwards find.
130 * This is assumed to be the case by default.
131 */
132 void setSupportsBackwardsFind(bool supports);
133
134 /*!
135 * Enable/disable the 'Case sensitive' option, depending
136 * on whether the application supports it.
137 *
138 * \a supports true if the application supports case sensitive find.
139 * This is assumed to be the case by default.
140 */
141 void setSupportsCaseSensitiveFind(bool supports);
142
143 /*!
144 * Enable/disable the 'Whole words only' option, depending
145 * on whether the application supports it.
146 *
147 * \a supports true if the application supports whole words only find.
148 * This is assumed to be the case by default.
149 */
150 void setSupportsWholeWordsFind(bool supports);
151
152 /*!
153 * Enable/disable the 'Regular expression' option, depending
154 * on whether the application supports it.
155 *
156 * \a supports true if the application supports regular expression find.
157 * This is assumed to be the case by default.
158 */
159 void setSupportsRegularExpressionFind(bool supports);
160
161 /*!
162 * Set the options which are checked.
163 *
164 * \a options The setting of the Options.
165 *
166 * \sa options()
167 * \sa KFind::Options
168 */
169 void setOptions(long options);
170
171 /*!
172 * Returns the state of the options. Disabled options may be returned in
173 * an indeterminate state.
174 *
175 * \sa setOptions()
176 * \sa KFind::Options
177 */
178 long options() const;
179
180 /*!
181 * Returns the pattern to find.
182 */
183 QString pattern() const;
184
185 /*!
186 * Sets the \a pattern to find.
187 */
188 void setPattern(const QString &pattern);
189
190 /*!
191 * Returns an empty widget which the user may fill with additional UI
192 * elements as required. The widget occupies the width of the dialog,
193 * and is positioned immediately below the regular expression support
194 * widgets for the pattern string.
195 */
196 QWidget *findExtension() const;
197
198Q_SIGNALS:
199 /*!
200 * This signal is sent whenever one of the option checkboxes is toggled.
201 * Call options() to get the new state of the checkboxes.
202 */
203 void optionsChanged();
204
205 /*!
206 * This signal is sent when the user clicks on Ok button.
207 */
208 void okClicked();
209
210 /*!
211 * This signal is sent when the user clicks on Cancel button.
212 */
213 void cancelClicked();
214
215protected:
216 void showEvent(QShowEvent *) override;
217
218protected:
219 KTEXTWIDGETS_NO_EXPORT explicit KFindDialog(KFindDialogPrivate &dd,
220 QWidget *parent = nullptr,
221 long options = 0,
222 const QStringList &findStrings = QStringList(),
223 bool hasSelection = false,
224 bool replaceDialog = false);
225
226protected:
227 std::unique_ptr<class KFindDialogPrivate> const d_ptr;
228
229private:
230 Q_DECLARE_PRIVATE(KFindDialog)
231};
232
233#endif // KFINDDIALOG_H
234

source code of ktextwidgets/src/findreplace/kfinddialog.h