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

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