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 | |
23 | class KComboBox; |
24 | class KLineEdit; |
25 | class KUrlCompletion; |
26 | |
27 | class QEvent; |
28 | class 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 | */ |
54 | class 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 | |
87 | public: |
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 | |
281 | public 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 | |
310 | Q_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 | |
350 | protected: |
351 | void changeEvent(QEvent *e) override; |
352 | bool eventFilter(QObject *obj, QEvent *ev) override; |
353 | |
354 | private: |
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 | */ |
366 | class KIOWIDGETS_EXPORT KUrlComboRequester : public KUrlRequester // krazy:exclude=dpointer (For use in Qt Designer) |
367 | { |
368 | Q_OBJECT |
369 | public: |
370 | /*! |
371 | * Constructs a KUrlRequester widget with a combobox. |
372 | */ |
373 | explicit KUrlComboRequester(QWidget *parent = nullptr); |
374 | |
375 | private: |
376 | class Private; |
377 | Private *const d; |
378 | }; |
379 | |
380 | #endif // KURLREQUESTER_H |
381 | |