1/*
2 Copyright (C) 2001, S.R.Haque <srhaque@iee.org>.
3 Copyright (C) 2002, David Faure <david@mandrakesoft.com>
4 This file is part of the KDE project
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Library General Public
8 License version 2, as published by the Free Software Foundation.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20
21#ifndef KFINDDIALOG_H
22#define KFINDDIALOG_H
23
24#include <kdialog.h>
25
26/**
27 * @brief A generic "find" dialog.
28 *
29 * @author S.R.Haque <srhaque@iee.org>
30 *
31 * \b Detail:
32 *
33 * This widget inherits from KDialog and implements
34 * the following additional functionalities: a find string
35 * object and an area for a user-defined widget to extend the dialog.
36 *
37 * \b Example:
38 *
39 * To use the basic modal find dialog, and then run the search:
40 *
41 * \code
42 * KFindDialog dlg(....)
43 * if ( dlg.exec() != QDialog::Accepted )
44 * return;
45 *
46 * // proceed with KFind from here
47 * \endcode
48 *
49 * To create a non-modal find dialog:
50 * \code
51 * if ( m_findDia )
52 * KWindowSystem::activateWindow( m_findDia->winId() );
53 * else
54 * {
55 * m_findDia = new KFindDialog(false,...);
56 * connect( m_findDia, SIGNAL(okClicked()), this, SLOT(findTextNext()) );
57 * }
58 * \endcode
59 * Don't forget to delete and reset m_findDia when closed.
60 * (But do NOT delete your KFind object at that point, it's needed for "Find Next".)
61 *
62 * @note If using a non-modal find dialog, in the slot connected to the okClicked()
63 * signal you need to check if a regular expression has been entered and if so,
64 * whether it is valid. Otherwise, if it is invalid, the user will see an error
65 * message followed unexpectedly by a search taking place.
66 * \code
67 * if ( (m_findDia->options() & KFind::RegularExpression)
68 * && !QRegExp(m_findDia->pattern()).isValid() )
69 * {
70 * // Don't attempt to search
71 * }
72 * \endcode
73 *
74 * To use your own extensions: see findExtension().
75 *
76 * \image html kfinddialog.png "KDE Find Dialog"
77 */
78class KDEUI_EXPORT KFindDialog:
79 public KDialog
80{
81 Q_OBJECT
82
83public:
84
85
86 /**
87 * Construct a modal find dialog
88 *
89 * @param parent The parent object of this widget.
90 * @param options A bitfield of the Options to be checked.
91 * @param findStrings The find history, see findHistory()
92 * @param hasSelection Whether a selection exists
93 */
94 explicit KFindDialog( QWidget *parent = 0, long options = 0,
95 const QStringList &findStrings = QStringList(), bool hasSelection = false, bool replaceDialog = false );
96
97 /**
98 * Destructor.
99 */
100 virtual ~KFindDialog();
101
102 /**
103 * Provide the list of @p strings to be displayed as the history
104 * of find strings. @p strings might get truncated if it is
105 * too long.
106 *
107 * @param history The find history.
108 * @see findHistory
109 */
110 void setFindHistory( const QStringList &history );
111
112 /**
113 * Returns the list of history items.
114 *
115 * @see setFindHistory
116 */
117 QStringList findHistory() const;
118
119 /**
120 * Enable/disable the 'search in selection' option, depending
121 * on whether there actually is a selection.
122 *
123 * @param hasSelection true if a selection exists
124 */
125 void setHasSelection( bool hasSelection );
126
127 /**
128 * Hide/show the 'from cursor' option, depending
129 * on whether the application implements a cursor.
130 *
131 * @param hasCursor true if the application features a cursor
132 * This is assumed to be the case by default.
133 */
134 void setHasCursor( bool hasCursor );
135
136 /**
137 * Enable/disable the 'Find backwards' option, depending
138 * on whether the application supports it.
139 *
140 * @param supports true if the application supports backwards find
141 * This is assumed to be the case by default.
142 */
143 void setSupportsBackwardsFind( bool supports );
144
145 /**
146 * Enable/disable the 'Case sensitive' option, depending
147 * on whether the application supports it.
148 *
149 * @param supports true if the application supports case sensitive find
150 * This is assumed to be the case by default.
151 */
152 void setSupportsCaseSensitiveFind( bool supports );
153
154 /**
155 * Enable/disable the 'Whole words only' option, depending
156 * on whether the application supports it.
157 *
158 * @param supports true if the application supports whole words only find
159 * This is assumed to be the case by default.
160 */
161 void setSupportsWholeWordsFind( bool supports );
162
163 /**
164 * Enable/disable the 'Regular expression' option, depending
165 * on whether the application supports it.
166 *
167 * @param supports true if the application supports regular expression find
168 * This is assumed to be the case by default.
169 */
170 void setSupportsRegularExpressionFind( bool supports );
171
172 /**
173 * Set the options which are checked.
174 *
175 * @param options The setting of the Options.
176 *
177 * @see options()
178 * @see KFind::Options
179 */
180 void setOptions( long options );
181
182 /**
183 * Returns the state of the options. Disabled options may be returned in
184 * an indeterminate state.
185 *
186 * @see setOptions()
187 * @see KFind::Options
188 */
189 long options() const;
190
191 /**
192 * Returns the pattern to find.
193 */
194 QString pattern() const;
195
196 /**
197 * Sets the pattern to find
198 */
199 void setPattern ( const QString &pattern );
200
201 /**
202 * Returns an empty widget which the user may fill with additional UI
203 * elements as required. The widget occupies the width of the dialog,
204 * and is positioned immediately below the regular expression support
205 * widgets for the pattern string.
206 */
207 QWidget *findExtension() const;
208
209Q_SIGNALS:
210 /**
211 * This signal is sent whenever one of the option checkboxes is toggled.
212 * Call options() to get the new state of the checkboxes.
213 */
214 void optionsChanged();
215
216protected:
217 virtual void showEvent ( QShowEvent * );
218
219private:
220 friend class KReplaceDialog;
221 friend class KReplaceDialogPrivate;
222 class KFindDialogPrivate;
223 KFindDialogPrivate* const d;
224
225 Q_PRIVATE_SLOT( d, void _k_slotPlaceholdersAboutToShow() )
226 Q_PRIVATE_SLOT( d, void _k_slotOk() )
227 Q_PRIVATE_SLOT( d, void _k_slotSelectedTextToggled(bool) )
228 Q_PRIVATE_SLOT( d, void _k_showPatterns() )
229 Q_PRIVATE_SLOT( d, void _k_showPlaceholders() )
230 Q_PRIVATE_SLOT( d, void _k_textSearchChanged(const QString&) )
231};
232
233#endif // KFINDDIALOG_H
234