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 | */ |
78 | class KDEUI_EXPORT KFindDialog: |
79 | public KDialog |
80 | { |
81 | Q_OBJECT |
82 | |
83 | public: |
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 | |
209 | Q_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 | |
216 | protected: |
217 | virtual void showEvent ( QShowEvent * ); |
218 | |
219 | private: |
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 | |