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
33class KComboBox;
34class KFileDialog;
35class KLineEdit;
36class KUrlCompletion;
37
38class QString;
39class 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 */
60class 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
70public:
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
221public 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
262Q_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
300protected:
301 virtual void changeEvent (QEvent *e);
302 bool eventFilter( QObject *obj, QEvent *ev );
303
304private:
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
316class KIO_EXPORT KUrlComboRequester : public KUrlRequester // krazy:exclude=dpointer (For use in Qt Designer)
317{
318 Q_OBJECT
319public:
320 /**
321 * Constructs a KUrlRequester widget with a combobox.
322 */
323 explicit KUrlComboRequester(QWidget *parent = 0);
324
325private:
326 class Private;
327 Private* const d;
328};
329
330#endif // KURLREQUESTER_H
331