1 | /* This file is part of the KDE libraries |
2 | Copyright (C) 1999,2000,2001 Carsten Pfeiffer <pfeiffer@kde.org> |
3 | |
4 | library is free software; you can redistribute it and/or |
5 | modify it under the terms of the GNU Library General Public |
6 | License version 2, as published by the Free Software Foundation. |
7 | |
8 | This library is distributed in the hope that it will be useful, |
9 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
10 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
11 | Library General Public License for more details. |
12 | |
13 | You should have received a copy of the GNU Library General Public License |
14 | along with this library; see the file COPYING.LIB. If not, write to |
15 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
16 | Boston, MA 02110-1301, USA. |
17 | */ |
18 | |
19 | #ifndef KURLREQUESTER_H |
20 | #define KURLREQUESTER_H |
21 | |
22 | #include <kfile.h> |
23 | #include <kpushbutton.h> |
24 | #include <kurl.h> |
25 | #include <khbox.h> |
26 | |
27 | #ifndef KDE_NO_DEPRECATED |
28 | #include <keditlistbox.h> |
29 | #else |
30 | #include <keditlistwidget.h> |
31 | #endif |
32 | |
33 | class KComboBox; |
34 | class KFileDialog; |
35 | class KLineEdit; |
36 | class KUrlCompletion; |
37 | |
38 | class QString; |
39 | class QEvent; |
40 | |
41 | /** |
42 | * This class is a widget showing a lineedit and a button, which invokes a |
43 | * filedialog. File name completion is available in the lineedit. |
44 | * |
45 | * The defaults for the filedialog are to ask for one existing local file, i.e. |
46 | * KFileDialog::setMode( KFile::File | KFile::ExistingOnly | KFile::LocalOnly ) |
47 | * The default filter is "*", i.e. show all files, and the start directory is |
48 | * the current working directory, or the last directory where a file has been |
49 | * selected. |
50 | * |
51 | * You can change this behavior by using setMode() or setFilter(). |
52 | * |
53 | * The default window modality for the file dialog is Qt::ApplicationModal |
54 | * |
55 | * \image html kurlrequester.png "KDE URL Requester" |
56 | * |
57 | * @short A widget to request a filename/url from the user |
58 | * @author Carsten Pfeiffer <pfeiffer@kde.org> |
59 | */ |
60 | class KIO_EXPORT KUrlRequester : public KHBox |
61 | { |
62 | Q_OBJECT |
63 | Q_PROPERTY( KUrl url READ url WRITE setUrl NOTIFY textChanged USER true ) |
64 | Q_PROPERTY( QString filter READ filter WRITE setFilter ) |
65 | Q_PROPERTY( KFile::Modes mode READ mode WRITE setMode ) |
66 | Q_PROPERTY( QString clickMessage READ clickMessage WRITE setClickMessage ) |
67 | Q_PROPERTY(QString text READ text WRITE setText) |
68 | Q_PROPERTY( Qt::WindowModality fileDialogModality READ fileDialogModality WRITE setFileDialogModality ) |
69 | |
70 | public: |
71 | /** |
72 | * Constructs a KUrlRequester widget. |
73 | */ |
74 | explicit KUrlRequester( QWidget *parent=0); |
75 | |
76 | /** |
77 | * Constructs a KUrlRequester widget with the initial URL @p url. |
78 | */ |
79 | explicit KUrlRequester( const KUrl& url, QWidget *parent=0); |
80 | |
81 | /** |
82 | * Special constructor, which creates a KUrlRequester widget with a custom |
83 | * edit-widget. The edit-widget can be either a KComboBox or a KLineEdit |
84 | * (or inherited thereof). Note: for geometry management reasons, the |
85 | * edit-widget is reparented to have the KUrlRequester as parent. |
86 | */ |
87 | KUrlRequester( QWidget *editWidget, QWidget *parent); |
88 | /** |
89 | * Destructs the KUrlRequester. |
90 | */ |
91 | ~KUrlRequester(); |
92 | |
93 | /** |
94 | * @returns the current url in the lineedit. May be malformed, if the user |
95 | * entered something weird. ~user or environment variables are substituted |
96 | * for local files. |
97 | */ |
98 | KUrl url() const; |
99 | |
100 | /** |
101 | * @returns the current start dir |
102 | * @since 4.3 |
103 | */ |
104 | KUrl startDir() const; |
105 | |
106 | /** |
107 | * @returns the current text in the lineedit or combobox. |
108 | * This does not do the URL expansion that url() does, it's only provided |
109 | * for cases where KUrlRequester is used to enter URL-or-something-else, |
110 | * like KOpenWithDialog where you can type a full command with arguments. |
111 | * |
112 | * @since 4.2 |
113 | */ |
114 | QString text() const; |
115 | |
116 | /** |
117 | * Sets the mode of the file dialog. |
118 | * Note: you can only select one file with the filedialog, |
119 | * so KFile::Files doesn't make much sense. |
120 | * @see KFileDialog::setMode() |
121 | */ |
122 | void setMode( KFile::Modes m ); |
123 | |
124 | /** |
125 | * Returns the current mode |
126 | * @see KFileDialog::mode() |
127 | */ |
128 | KFile::Modes mode() const; |
129 | |
130 | /** |
131 | * Sets the filter for the file dialog. |
132 | * @see KFileDialog::setFilter() |
133 | */ |
134 | void setFilter( const QString& filter ); |
135 | |
136 | /** |
137 | * Returns the current filter for the file dialog. |
138 | * @see KFileDialog::filter() |
139 | */ |
140 | QString filter() const; |
141 | |
142 | /** |
143 | * @returns a pointer to the filedialog. |
144 | * You can use this to customize the dialog, e.g. to call setLocationLabel |
145 | * or other things which are not accessible in the KUrlRequester API. |
146 | * |
147 | * Never returns 0. This method creates the file dialog on demand. |
148 | * |
149 | * Important: in "Directory only" mode, a KDirSelectDialog is used |
150 | * instead, so calling this method is useless. |
151 | */ |
152 | virtual KFileDialog * fileDialog() const; |
153 | |
154 | /** |
155 | * @returns a pointer to the lineedit, either the default one, or the |
156 | * special one, if you used the special constructor. |
157 | * |
158 | * It is provided so that you can e.g. set an own completion object |
159 | * (e.g. KShellCompletion) into it. |
160 | */ |
161 | KLineEdit * lineEdit() const; |
162 | |
163 | /** |
164 | * @returns a pointer to the combobox, in case you have set one using the |
165 | * special constructor. Returns 0L otherwise. |
166 | */ |
167 | KComboBox * comboBox() const; |
168 | |
169 | /** |
170 | * @returns a pointer to the pushbutton. It is provided so that you can |
171 | * specify an own pixmap or a text, if you really need to. |
172 | */ |
173 | KPushButton * button() const; |
174 | |
175 | /** |
176 | * @returns the KUrlCompletion object used in the lineedit/combobox. |
177 | */ |
178 | KUrlCompletion *completionObject() const; |
179 | |
180 | /** |
181 | * @returns an object, suitable for use with KEditListWidget. It allows you |
182 | * to put this KUrlRequester into a KEditListWidget. |
183 | * Basically, do it like this: |
184 | * \code |
185 | * KUrlRequester *req = new KUrlRequester( someWidget ); |
186 | * [...] |
187 | * KEditListWidget *editListWidget = new KEditListWidget( req->customEditor(), someWidget ); |
188 | * \endcode |
189 | */ |
190 | #ifndef KDE_NO_DEPRECATED |
191 | const KEditListBox::CustomEditor &customEditor(); |
192 | #else |
193 | const KEditListWidget::CustomEditor &customEditor(); |
194 | #endif |
195 | |
196 | /** |
197 | * @returns the message set with setClickMessage |
198 | * @since 4.2 |
199 | */ |
200 | QString clickMessage() const; |
201 | |
202 | /** |
203 | * Set a click message @p msg |
204 | * @since 4.2 |
205 | */ |
206 | void setClickMessage(const QString& msg); |
207 | |
208 | /** |
209 | * @returns the window modality of the file dialog set with setFileDialogModality |
210 | * @since 4.4 |
211 | */ |
212 | Qt::WindowModality fileDialogModality() const; |
213 | |
214 | /** |
215 | * Set the window modality for the file dialog to @p modality |
216 | * Directory selection dialogs are always modal |
217 | * @since 4.4 |
218 | */ |
219 | void setFileDialogModality(Qt::WindowModality modality); |
220 | |
221 | public Q_SLOTS: |
222 | /** |
223 | * Sets the url in the lineedit to @p url. |
224 | */ |
225 | void setUrl( const KUrl& url ); |
226 | |
227 | /** |
228 | * Sets the start dir @p startDir. |
229 | * The start dir is only used when the URL isn't set. |
230 | * @since 4.3 |
231 | */ |
232 | void setStartDir( const KUrl& startDir ); |
233 | |
234 | /** |
235 | * Sets the url in the lineedit to @p KUrl::fromPath(path). |
236 | * This is only for local paths; do not pass a url here. |
237 | * This method is mostly for "local paths only" url requesters, |
238 | * for instance those set up with setMode(KFile::File|KFile::ExistingOnly|KFile::LocalOnly) |
239 | * |
240 | * @deprecated Use setUrl(KUrl(path)) instead. |
241 | */ |
242 | #ifndef KDE_NO_DEPRECATED |
243 | KDE_DEPRECATED void setPath(const QString& path); |
244 | #endif |
245 | |
246 | /** |
247 | * Sets the current text in the lineedit or combobox. |
248 | * This is used for cases where KUrlRequester is used to |
249 | * enter URL-or-something-else, like KOpenWithDialog where you |
250 | * can type a full command with arguments. |
251 | * |
252 | * @see text |
253 | * @since 4.3 |
254 | */ |
255 | void setText(const QString& text); |
256 | |
257 | /** |
258 | * Clears the lineedit/combobox. |
259 | */ |
260 | void clear(); |
261 | |
262 | Q_SIGNALS: |
263 | // forwards from LineEdit |
264 | /** |
265 | * Emitted when the text in the lineedit changes. |
266 | * The parameter contains the contents of the lineedit. |
267 | */ |
268 | void textChanged( const QString& ); |
269 | |
270 | /** |
271 | * Emitted when return or enter was pressed in the lineedit. |
272 | */ |
273 | void returnPressed(); |
274 | |
275 | /** |
276 | * Emitted when return or enter was pressed in the lineedit. |
277 | * The parameter contains the contents of the lineedit. |
278 | */ |
279 | void returnPressed( const QString& ); |
280 | |
281 | /** |
282 | * Emitted before the filedialog is going to open. Connect |
283 | * to this signal to "configure" the filedialog, e.g. set the |
284 | * filefilter, the mode, a preview-widget, etc. It's usually |
285 | * not necessary to set a URL for the filedialog, as it will |
286 | * get set properly from the editfield contents. |
287 | * |
288 | * If you use multiple KUrlRequesters, you can connect all of them |
289 | * to the same slot and use the given KUrlRequester pointer to know |
290 | * which one is going to open. |
291 | */ |
292 | void openFileDialog( KUrlRequester * ); |
293 | |
294 | /** |
295 | * Emitted when the user changed the URL via the file dialog. |
296 | * The parameter contains the contents of the lineedit. |
297 | */ |
298 | void urlSelected( const KUrl& ); |
299 | |
300 | protected: |
301 | virtual void changeEvent (QEvent *e); |
302 | bool eventFilter( QObject *obj, QEvent *ev ); |
303 | |
304 | private: |
305 | class KUrlRequesterPrivate; |
306 | KUrlRequesterPrivate* const d; |
307 | |
308 | Q_DISABLE_COPY(KUrlRequester) |
309 | |
310 | Q_PRIVATE_SLOT(d, void _k_slotUpdateUrl()) |
311 | Q_PRIVATE_SLOT(d, void _k_slotOpenDialog()) |
312 | Q_PRIVATE_SLOT(d, void _k_slotFileDialogFinished()) |
313 | |
314 | }; |
315 | |
316 | class KIO_EXPORT KUrlComboRequester : public KUrlRequester // krazy:exclude=dpointer (For use in Qt Designer) |
317 | { |
318 | Q_OBJECT |
319 | public: |
320 | /** |
321 | * Constructs a KUrlRequester widget with a combobox. |
322 | */ |
323 | explicit KUrlComboRequester(QWidget *parent = 0); |
324 | |
325 | private: |
326 | class Private; |
327 | Private* const d; |
328 | }; |
329 | |
330 | #endif // KURLREQUESTER_H |
331 | |