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
6 SPDX-License-Identifier: LGPL-2.0-only
7*/
8
9#ifndef KFINDDIALOG_H
10#define KFINDDIALOG_H
11
12#include "ktextwidgets_export.h"
13
14#include <QDialog>
15#include <memory>
16
17class KFindDialogPrivate;
18
19/**
20 * @class KFindDialog kfinddialog.h <KFindDialog>
21 *
22 * @brief A generic "find" dialog.
23 *
24 * @author S.R.Haque <srhaque@iee.org>
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 html 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 * @param parent The parent object of this widget.
74 * @param options A bitfield of the Options to be checked.
75 * @param findStrings The find history, see findHistory()
76 * @param hasSelection Whether a selection exists
77 */
78 explicit KFindDialog(QWidget *parent = nullptr,
79 long options = 0,
80 const QStringList &findStrings = QStringList(),
81 bool hasSelection = false,
82 bool replaceDialog = false);
83
84 /**
85 * Destructor.
86 */
87 ~KFindDialog() override;
88
89 /**
90 * Provide the list of @p strings to be displayed as the history
91 * of find strings. @p strings might get truncated if it is
92 * too long.
93 *
94 * @param history The find history.
95 * @see findHistory
96 */
97 void setFindHistory(const QStringList &history);
98
99 /**
100 * Returns the list of history items.
101 *
102 * @see setFindHistory
103 */
104 QStringList findHistory() const;
105
106 /**
107 * Enable/disable the 'search in selection' option, depending
108 * on whether there actually is a selection.
109 *
110 * @param hasSelection true if a selection exists
111 */
112 void setHasSelection(bool hasSelection);
113
114 /**
115 * Hide/show the 'from cursor' option, depending
116 * on whether the application implements a cursor.
117 *
118 * @param hasCursor true if the application features a cursor
119 * This is assumed to be the case by default.
120 */
121 void setHasCursor(bool hasCursor);
122
123 /**
124 * Enable/disable the 'Find backwards' option, depending
125 * on whether the application supports it.
126 *
127 * @param supports true if the application supports backwards find
128 * This is assumed to be the case by default.
129 */
130 void setSupportsBackwardsFind(bool supports);
131
132 /**
133 * Enable/disable the 'Case sensitive' option, depending
134 * on whether the application supports it.
135 *
136 * @param supports true if the application supports case sensitive find
137 * This is assumed to be the case by default.
138 */
139 void setSupportsCaseSensitiveFind(bool supports);
140
141 /**
142 * Enable/disable the 'Whole words only' option, depending
143 * on whether the application supports it.
144 *
145 * @param supports true if the application supports whole words only find
146 * This is assumed to be the case by default.
147 */
148 void setSupportsWholeWordsFind(bool supports);
149
150 /**
151 * Enable/disable the 'Regular expression' option, depending
152 * on whether the application supports it.
153 *
154 * @param supports true if the application supports regular expression find
155 * This is assumed to be the case by default.
156 */
157 void setSupportsRegularExpressionFind(bool supports);
158
159 /**
160 * Set the options which are checked.
161 *
162 * @param options The setting of the Options.
163 *
164 * @see options()
165 * @see KFind::Options
166 */
167 void setOptions(long options);
168
169 /**
170 * Returns the state of the options. Disabled options may be returned in
171 * an indeterminate state.
172 *
173 * @see setOptions()
174 * @see KFind::Options
175 */
176 long options() const;
177
178 /**
179 * Returns the pattern to find.
180 */
181 QString pattern() const;
182
183 /**
184 * Sets the pattern to find
185 */
186 void setPattern(const QString &pattern);
187
188 /**
189 * Returns an empty widget which the user may fill with additional UI
190 * elements as required. The widget occupies the width of the dialog,
191 * and is positioned immediately below the regular expression support
192 * widgets for the pattern string.
193 */
194 QWidget *findExtension() const;
195
196Q_SIGNALS:
197 /**
198 * This signal is sent whenever one of the option checkboxes is toggled.
199 * Call options() to get the new state of the checkboxes.
200 */
201 void optionsChanged();
202
203 /**
204 * This signal is sent when the user clicks on Ok button.
205 */
206 void okClicked();
207
208 /**
209 * This signal is sent when the user clicks on Cancel button.
210 */
211 void cancelClicked();
212
213protected:
214 void showEvent(QShowEvent *) override;
215
216protected:
217 KTEXTWIDGETS_NO_EXPORT explicit KFindDialog(KFindDialogPrivate &dd,
218 QWidget *parent = nullptr,
219 long options = 0,
220 const QStringList &findStrings = QStringList(),
221 bool hasSelection = false,
222 bool replaceDialog = false);
223
224protected:
225 std::unique_ptr<class KFindDialogPrivate> const d_ptr;
226
227private:
228 Q_DECLARE_PRIVATE(KFindDialog)
229};
230
231#endif // KFINDDIALOG_H
232

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