1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 1999, 2000, 2001 Carsten Pfeiffer <pfeiffer@kde.org>
4 SPDX-FileCopyrightText: 2013 Teo Mrnjavac <teo@kde.org>
5
6 SPDX-License-Identifier: LGPL-2.0-only
7*/
8
9#ifndef KURLREQUESTER_H
10#define KURLREQUESTER_H
11
12#include "kiowidgets_export.h"
13
14#include <KEditListWidget>
15#include <kfile.h>
16
17#include <QFileDialog>
18#include <QPushButton>
19#include <QUrl>
20
21#include <memory>
22
23class KComboBox;
24class KLineEdit;
25class KUrlCompletion;
26
27class QEvent;
28class QString;
29
30/*!
31 * \class KUrlRequester
32 * \inmodule KIOWidgets
33 *
34 * \brief A widget to request a filename/url from the user.
35 *
36 * This class is a widget showing a lineedit and a button, which invokes a
37 * filedialog. File name completion is available in the lineedit.
38 *
39 * The default for the filedialog is to ask for one existing local file, i.e.
40 * the default mode is 'KFile::File | KFile::ExistingOnly | KFile::LocalOnly',
41 * which you can change by using setMode().
42 *
43 * The default filter is "*", i.e. show all files, which you can change by
44 * using setNameFilters() or setMimeTypeFilters().
45 *
46 * By default the start directory is the current working directory, or the
47 * last directory where a file has been selected previously, you can change
48 * this behavior by calling setStartDir().
49 *
50 * The default window modality for the file dialog is Qt::ApplicationModal
51 *
52 * \image kurlrequester.png "KUrlRequester"
53 */
54class KIOWIDGETS_EXPORT KUrlRequester : public QWidget
55{
56 Q_OBJECT
57 /*!
58 * \property KUrlRequester::url
59 */
60 Q_PROPERTY(QUrl url READ url WRITE setUrl NOTIFY textChanged USER true)
61 /*!
62 * \property KUrlRequester::nameFilters
63 * \since 5.108
64 */
65 Q_PROPERTY(QStringList nameFilters READ nameFilters WRITE setNameFilters)
66 /*!
67 * \property KUrlRequester::mode
68 */
69 Q_PROPERTY(KFile::Modes mode READ mode WRITE setMode)
70 /*!
71 * \property KUrlRequester::acceptMode
72 */
73 Q_PROPERTY(QFileDialog::AcceptMode acceptMode READ acceptMode WRITE setAcceptMode)
74 /*!
75 * \property KUrlRequester::placeholderText
76 */
77 Q_PROPERTY(QString placeholderText READ placeholderText WRITE setPlaceholderText)
78 /*!
79 * \property KUrlRequester::text
80 */
81 Q_PROPERTY(QString text READ text WRITE setText NOTIFY textChanged)
82 /*!
83 * \property KUrlRequester::fileDialogModality
84 */
85 Q_PROPERTY(Qt::WindowModality fileDialogModality READ fileDialogModality WRITE setFileDialogModality)
86
87public:
88 /*!
89 * Constructs a KUrlRequester widget.
90 */
91 explicit KUrlRequester(QWidget *parent = nullptr);
92
93 /*!
94 * Constructs a KUrlRequester widget with the initial URL \a url.
95 */
96 explicit KUrlRequester(const QUrl &url, QWidget *parent = nullptr);
97
98 /*!
99 * Special constructor, which creates a KUrlRequester widget with a custom
100 * edit-widget. The edit-widget can be either a KComboBox or a KLineEdit
101 * (or inherited thereof). Note: for geometry management reasons, the
102 * edit-widget is reparented to have the KUrlRequester as parent.
103 */
104 KUrlRequester(QWidget *editWidget, QWidget *parent);
105 ~KUrlRequester() override;
106
107 /*!
108 * Returns the current url in the lineedit. May be malformed, if the user
109 * entered something weird. For local files, ~user or environment variables
110 * are substituted, relative paths will be resolved against startDir()
111 */
112 QUrl url() const;
113
114 /*!
115 * Returns the current start dir
116 */
117 QUrl startDir() const;
118
119 /*!
120 * Returns the current text in the lineedit or combobox.
121 * This does not do the URL expansion that url() does, it's only provided
122 * for cases where KUrlRequester is used to enter URL-or-something-else,
123 * like KOpenWithDialog where you can type a full command with arguments.
124 *
125 */
126 QString text() const;
127
128 /*!
129 * Sets the mode of the file dialog.
130 *
131 * The default mode of the file dialog is 'KFile::File | KFile::ExistingOnly | KFile::LocalOnly',
132 * which you can change using this method.
133 *
134 * \note You can only select one file from the file dialog invoked
135 * by KUrlRequester, hence setting KFile::Files doesn't make
136 * much sense here.
137 *
138 * \a mode an OR'ed combination of KFile::Modes flags
139 *
140 * \sa QFileDialog::setFileMode()
141 */
142 void setMode(KFile::Modes mode);
143
144 /*!
145 * Returns the current mode
146 * \sa QFileDialog::fileMode()
147 */
148 KFile::Modes mode() const;
149
150 /*!
151 * Sets the open / save mode of the file dialog.
152 *
153 * The default is QFileDialog::AcceptOpen.
154 *
155 * \sa QFileDialog::setAcceptMode()
156 * \since 5.33
157 */
158 void setAcceptMode(QFileDialog::AcceptMode m);
159
160 /*!
161 * Returns the current open / save mode
162 * \sa QFileDialog::acceptMode()
163 * \since 5.33
164 */
165 QFileDialog::AcceptMode acceptMode() const;
166
167 /*!
168 * Sets the name \a filters for the file dialog.
169 * \sa QFileDialog::setNameFilters()
170 * \since 5.108
171 */
172 void setNameFilters(const QStringList &filters);
173
174 /*!
175 * Sets the name \a filter for the file dialog.
176 * \sa QFileDialog::setNameFilter()
177 * \since 5.108
178 */
179 void setNameFilter(const QString &filter);
180
181 /*!
182 * Returns the filters for the file dialog.
183 * \sa QFileDialog::nameFilters()
184 * \since 5.108
185 */
186 QStringList nameFilters() const;
187
188 /*!
189 * Sets the MIME type filters for the file dialog.
190 * \sa QFileDialog::setMimeTypeFilters()
191 * \since 5.31
192 */
193 void setMimeTypeFilters(const QStringList &mimeTypes);
194 /*!
195 * Returns the MIME type filters for the file dialog.
196 * \sa QFileDialog::mimeTypeFilters()
197 * \since 5.31
198 */
199 QStringList mimeTypeFilters() const;
200
201 /*!
202 * Returns a pointer to the filedialog.
203 * You can use this to customize the dialog, e.g. to call setLocationLabel
204 * or other things which are not accessible in the KUrlRequester API.
205 *
206 * Never returns 0. This method creates the file dialog on demand.
207 *
208 * Deprecated: The dialog will be created anyway when the user
209 * requests it, and will behave according to the properties of KUrlRequester.
210 * \deprecated 5.0.
211 */
212 KIOWIDGETS_DEPRECATED_VERSION(5, 0, "See API docs")
213 virtual QFileDialog *fileDialog() const;
214
215 /*!
216 * Returns a pointer to the lineedit, either the default one, or the
217 * special one, if you used the special constructor.
218 *
219 * It is provided so that you can e.g. set an own completion object
220 * (e.g. KShellCompletion) into it.
221 */
222 KLineEdit *lineEdit() const;
223
224 /*!
225 * Returns a pointer to the combobox, in case you have set one using the
226 * special constructor. Returns 0L otherwise.
227 */
228 KComboBox *comboBox() const;
229
230 /*!
231 * Returns a pointer to the pushbutton. It is provided so that you can
232 * specify an own pixmap or a text, if you really need to.
233 */
234 QPushButton *button() const;
235
236 /*!
237 * Returns the KUrlCompletion object used in the lineedit/combobox.
238 */
239 KUrlCompletion *completionObject() const;
240
241 /*!
242 * Returns an object, suitable for use with KEditListWidget. It allows you
243 * to put this KUrlRequester into a KEditListWidget.
244 * Basically, do it like this:
245 * \code
246 * KUrlRequester *req = new KUrlRequester( someWidget );
247 * [...]
248 * KEditListWidget *editListWidget = new KEditListWidget( req->customEditor(), someWidget );
249 * \endcode
250 */
251 const KEditListWidget::CustomEditor &customEditor();
252
253 /*!
254 * Returns the message set with setPlaceholderText
255 * \since 5.0
256 */
257 QString placeholderText() const;
258
259 /*!
260 * This makes the KUrlRequester line edit display a grayed-out hinting text as long as
261 * the user didn't enter any text. It is often used as indication about
262 * the purpose of the line edit.
263 * \since 5.0
264 */
265 void setPlaceholderText(const QString &msg);
266
267 /*!
268 * Returns the window modality of the file dialog set with setFileDialogModality
269 */
270 Qt::WindowModality fileDialogModality() const;
271
272 /*!
273 * Set the window modality for the file dialog to \a modality
274 * Directory selection dialogs are always modal
275 *
276 * The default is Qt::ApplicationModal.
277 *
278 */
279 void setFileDialogModality(Qt::WindowModality modality);
280
281public Q_SLOTS:
282 /*!
283 * Sets the url in the lineedit to \a url.
284 */
285 void setUrl(const QUrl &url);
286
287 /*!
288 * Sets the start dir \a startDir.
289 *
290 * The start dir is only used when the URL isn't set.
291 */
292 void setStartDir(const QUrl &startDir);
293
294 /*!
295 * Sets the current text in the lineedit or combobox.
296 *
297 * This is used for cases where KUrlRequester is used to
298 * enter URL-or-something-else, like KOpenWithDialog where you
299 * can type a full command with arguments.
300 *
301 * \sa text
302 */
303 void setText(const QString &text);
304
305 /*!
306 * Clears the lineedit/combobox.
307 */
308 void clear();
309
310Q_SIGNALS:
311 // forwards from LineEdit
312 /*!
313 * Emitted when the text in the lineedit changes.
314 * The parameter contains the contents of the lineedit.
315 */
316 void textChanged(const QString &);
317
318 /*!
319 * Emitted when the text in the lineedit was modified by the user.
320 * Unlike textChanged(), this signal is not emitted when the text is changed programmatically, for example, by calling setText().
321 * \since 5.21
322 */
323 void textEdited(const QString &);
324
325 /*!
326 * Emitted when return or enter was pressed in the lineedit.
327 * The parameter contains the contents of the lineedit.
328 */
329 void returnPressed(const QString &text);
330
331 /*!
332 * Emitted before the filedialog is going to open. Connect
333 * to this signal to "configure" the filedialog, e.g. set the
334 * filefilter, the mode, a preview-widget, etc. It's usually
335 * not necessary to set a URL for the filedialog, as it will
336 * get set properly from the editfield contents.
337 *
338 * If you use multiple KUrlRequesters, you can connect all of them
339 * to the same slot and use the given KUrlRequester pointer to know
340 * which one is going to open.
341 */
342 void openFileDialog(KUrlRequester *);
343
344 /*!
345 * Emitted when the user changed the URL via the file dialog.
346 * The parameter contains the contents of the lineedit.
347 */
348 void urlSelected(const QUrl &);
349
350protected:
351 void changeEvent(QEvent *e) override;
352 bool eventFilter(QObject *obj, QEvent *ev) override;
353
354private:
355 class KUrlRequesterPrivate;
356 std::unique_ptr<KUrlRequesterPrivate> const d;
357
358 Q_DISABLE_COPY(KUrlRequester)
359};
360
361/*!
362 * \class KUrlComboRequester
363 * \inheaderfile KUrlRequester
364 * \inmodule KIOWidgets
365 */
366class KIOWIDGETS_EXPORT KUrlComboRequester : public KUrlRequester // krazy:exclude=dpointer (For use in Qt Designer)
367{
368 Q_OBJECT
369public:
370 /*!
371 * Constructs a KUrlRequester widget with a combobox.
372 */
373 explicit KUrlComboRequester(QWidget *parent = nullptr);
374
375private:
376 class Private;
377 Private *const d;
378};
379
380#endif // KURLREQUESTER_H
381

source code of kio/src/widgets/kurlrequester.h