KTextWidgets

kfinddialog.h
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{
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
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 */
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 */
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
void optionsChanged()
This signal is sent whenever one of the option checkboxes is toggled.
void setSupportsBackwardsFind(bool supports)
Enable/disable the 'Find backwards' option, depending on whether the application supports it.
KFindDialog(QWidget *parent=nullptr, long options=0, const QStringList &findStrings=QStringList(), bool hasSelection=false, bool replaceDialog=false)
Construct a modal find dialog.
void setHasCursor(bool hasCursor)
Hide/show the 'from cursor' option, depending on whether the application implements a cursor.
void setSupportsWholeWordsFind(bool supports)
Enable/disable the 'Whole words only' option, depending on whether the application supports it.
void setSupportsCaseSensitiveFind(bool supports)
Enable/disable the 'Case sensitive' option, depending on whether the application supports it.
void setFindHistory(const QStringList &history)
Provide the list of strings to be displayed as the history of find strings.
QStringList findHistory() const
Returns the list of history items.
QString pattern() const
Returns the pattern to find.
void cancelClicked()
This signal is sent when the user clicks on Cancel button.
void setSupportsRegularExpressionFind(bool supports)
Enable/disable the 'Regular expression' option, depending on whether the application supports it.
long options() const
Returns the state of the options.
void setHasSelection(bool hasSelection)
Enable/disable the 'search in selection' option, depending on whether there actually is a selection.
~KFindDialog() override
Destructor.
void okClicked()
This signal is sent when the user clicks on Ok button.
void setOptions(long options)
Set the options which are checked.
void setPattern(const QString &pattern)
Sets the pattern to find.
QWidget * findExtension() const
Returns an empty widget which the user may fill with additional UI elements as required.
QDialog(QWidget *parent, Qt::WindowFlags f)
virtual void showEvent(QShowEvent *event) override
Q_OBJECTQ_OBJECT
Q_SIGNALSQ_SIGNALS
QObject * parent() const const
QWidget(QWidget *parent, Qt::WindowFlags f)
This file is part of the KDE documentation.
Documentation copyright © 1996-2025 The KDE developers.
Generated on Fri Jan 24 2025 11:48:44 by doxygen 1.13.2 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.