1// -*- c++ -*-
2/*
3 This file is part of the KDE libraries
4 SPDX-FileCopyrightText: 1997, 1998 Richard Moore <rich@kde.org>
5 SPDX-FileCopyrightText: 1998 Stephan Kulow <coolo@kde.org>
6 SPDX-FileCopyrightText: 1998 Daniel Grana <grana@ie.iwi.unibe.ch>
7 SPDX-FileCopyrightText: 2000, 2001 Carsten Pfeiffer <pfeiffer@kde.org>
8 SPDX-FileCopyrightText: 2001 Frerich Raabe <raabe@kde.org>
9 SPDX-FileCopyrightText: 2007 David Faure <faure@kde.org>
10 SPDX-FileCopyrightText: 2008 Rafael Fernández López <ereslibre@kde.org>
11
12 SPDX-License-Identifier: LGPL-2.0-or-later
13*/
14
15#ifndef KFILEWIDGET_H
16#define KFILEWIDGET_H
17
18#include "kfile.h"
19#include "kiofilewidgets_export.h"
20#include <QWidget>
21
22#include <KFileFilter>
23
24#include <memory>
25
26class QUrl;
27class QPushButton;
28class KActionCollection;
29class KFileWidgetPrivate;
30class KUrlComboBox;
31class KFileFilterCombo;
32
33class KPreviewWidgetBase;
34class QMimeType;
35class KConfigGroup;
36class KJob;
37class KFileItem;
38class KDirOperator;
39
40/*!
41 * \class KFileWidget
42 * \inmodule KIOFileWidgets
43 *
44 * \brief File selector widget.
45 *
46 * This is the contents of the KDE file dialog, without the actual QDialog around it.
47 * It can be embedded directly into applications.
48 */
49class KIOFILEWIDGETS_EXPORT KFileWidget : public QWidget
50{
51 Q_OBJECT
52public:
53 /*!
54 * Constructs a file selector widget.
55 *
56 * \a startDir This can either be:
57 * \list
58 * \li An empty URL (QUrl()) to start in the current working directory,
59 * or the last directory where a file has been selected.
60 * \li The path or URL of a starting directory.
61 * \li An initial file name to select, with the starting directory being
62 * the current working directory or the last directory where a file
63 * has been selected.
64 * \li The path or URL of a file, specifying both the starting directory and
65 * an initially selected file name.
66 * \li A URL of the form \c kfiledialog:///<keyword>; to start in the
67 * directory last used by a filedialog in the same application that
68 * specified the same keyword.
69 * \li A URL of the form \c kfiledialog:///<keyword>/<filename>;
70 * to start in the directory last used by a filedialog in the same
71 * application that specified the same keyword, and to initially
72 * select the specified filename.
73 * \li Deprecated: A URL of the form \c kfiledialog:///<keyword>?global to start
74 * in the directory last used by a filedialog in any application that
75 * specified the same keyword.
76 * \li Deprecated: A URL of the form \c kfiledialog:///<keyword>/<filename>?global
77 * to start in the directory last used by a filedialog in any
78 * application that specified the same keyword, and to initially
79 * select the specified filename.
80 * \endlist
81 *
82 * \note Since 5.96, the "?global" syntax is deprecated, for lack of usage.
83 *
84 * \a parent The parent widget of this widget
85 *
86 */
87 explicit KFileWidget(const QUrl &startDir, QWidget *parent = nullptr);
88
89 ~KFileWidget() override;
90
91 /*!
92 * Defines some default behavior of the filedialog.
93 *
94 * E.g. in mode Opening and Saving, the selected files/urls will
95 * be added to the "recent documents" list. The Saving mode also implies
96 * setKeepLocation() being set.
97 *
98 * Other means that no default actions are performed.
99 *
100 * \value Other
101 * \value Opening
102 * \value Saving
103 *
104 * \sa setOperationMode
105 * \sa operationMode
106 */
107 enum OperationMode {
108 Other = 0,
109 Opening,
110 Saving
111 };
112
113 /*!
114 * Returns The selected fully qualified filename.
115 */
116 QUrl selectedUrl() const;
117
118 /*!
119 * Returns The list of selected URLs.
120 */
121 QList<QUrl> selectedUrls() const;
122
123 /*!
124 * Returns the currently shown directory.
125 */
126 QUrl baseUrl() const;
127
128 /*!
129 * Returns the full path of the selected file in the local filesystem.
130 * (Local files only)
131 */
132 QString selectedFile() const;
133
134 /*!
135 * Returns a list of all selected local files.
136 */
137 QStringList selectedFiles() const;
138
139 /*!
140 * Sets the directory to view.
141 *
142 * \a url URL to show.
143 *
144 * \a clearforward Indicates whether the forward queue
145 * should be cleared.
146 */
147 void setUrl(const QUrl &url, bool clearforward = true);
148
149 /*!
150 * Sets the URL to preselect to \a url
151 *
152 * This method handles absolute URLs (remember to use fromLocalFile for local paths).
153 * It also handles relative URLs, which you should construct like this:
154 * QUrl relativeUrl; relativeUrl.setPath(fileName);
155 *
156 * \since 5.33
157 */
158 void setSelectedUrl(const QUrl &url);
159
160 /*!
161 * Sets a list of URLs as preselected
162 *
163 * \sa setSelectedUrl
164 * \since 5.75
165 */
166 void setSelectedUrls(const QList<QUrl> &urls);
167
168 /*!
169 * Sets the operational mode of the filedialog to Saving, Opening
170 * or Other. This will set some flags that are specific to loading
171 * or saving files. E.g. setKeepLocation() makes mostly sense for
172 * a save-as dialog. So setOperationMode( KFileWidget::Saving ); sets
173 * setKeepLocation for example.
174 *
175 * The mode Saving, together with a default filter set via
176 * setMimeFilter() will make the filter combobox read-only.
177 *
178 * The default mode is Opening.
179 *
180 * Call this method right after instantiating KFileWidget.
181 *
182 * \sa operationMode
183 * \sa KFileWidget::OperationMode
184 */
185 void setOperationMode(OperationMode);
186
187 /*!
188 * Returns the current operation mode, Opening, Saving or Other. Default
189 * is Other.
190 *
191 * \sa operationMode
192 * \sa KFileWidget::OperationMode
193 */
194 OperationMode operationMode() const;
195
196 /*!
197 * Sets whether the filename/url should be kept when changing directories.
198 * This is for example useful when having a predefined filename where
199 * the full path for that file is searched.
200 *
201 * This is implicitly set when operationMode() is KFileWidget::Saving
202 *
203 * getSaveFileName() and getSaveUrl() set this to true by default, so that
204 * you can type in the filename and change the directory without having
205 * to type the name again.
206 */
207 void setKeepLocation(bool keep);
208
209 /*!
210 * Returns whether the contents of the location edit are kept when
211 * changing directories.
212 */
213 bool keepsLocation() const;
214
215 /*!
216 * Set the filters to be used.
217 *
218 * Each item of the list corresponds to a selectable filter.
219 *
220 * Only one filter is active at a time.
221 *
222 * \a activeFilter the initially active filter
223 *
224 * \since 6.0
225 */
226 void setFilters(const QList<KFileFilter> &filters, const KFileFilter &activeFilter = KFileFilter());
227
228 /*!
229 * Returns the current filter as entered by the user or one of the
230 * predefined set via setFilters().
231 *
232 * \sa setFilters()
233 * \sa filterChanged()
234 *
235 * \since 6.0
236 */
237 KFileFilter currentFilter() const;
238
239 /*!
240 * Clears any MIME type or name filter. Does not reload the directory.
241 */
242 void clearFilter();
243
244 /*!
245 * Adds a preview widget and enters the preview mode.
246 *
247 * In this mode the dialog is split and the right part contains your
248 * preview widget.
249 *
250 * Ownership is transferred to KFileWidget. You need to create the
251 * preview-widget with "new", i.e. on the heap.
252 *
253 * \a w The widget to be used for the preview.
254 */
255 void setPreviewWidget(KPreviewWidgetBase *w);
256
257 /*!
258 * Sets the mode of the dialog.
259 *
260 * The mode is defined as (in kfile.h):
261 * \code
262 * enum Mode {
263 * File = 1,
264 * Directory = 2,
265 * Files = 4,
266 * ExistingOnly = 8,
267 * LocalOnly = 16,
268 * };
269 * \endcode
270 * You can OR the values, e.g.
271 * \code
272 * KFile::Modes mode = KFile::Files |
273 * KFile::ExistingOnly |
274 * KFile::LocalOnly );
275 * setMode( mode );
276 * \endcode
277 */
278 void setMode(KFile::Modes m);
279
280 /*!
281 * Returns the mode of the filedialog.
282 * \sa setMode()
283 */
284 KFile::Modes mode() const;
285
286 /*!
287 * Sets the text to be displayed in front of the selection.
288 *
289 * The default is "Location".
290 * Most useful if you want to make clear what
291 * the location is used for.
292 */
293 void setLocationLabel(const QString &text);
294
295 /*!
296 * Returns a pointer to the OK-Button in the filedialog.
297 * Note that the button is hidden and unconnected when using KFileWidget alone;
298 * KFileDialog shows it and connects to it.
299 */
300 QPushButton *okButton() const;
301
302 /*!
303 * Returns a pointer to the Cancel-Button in the filedialog.
304 * Note that the button is hidden and unconnected when using KFileWidget alone;
305 * KFileDialog shows it and connects to it.
306 */
307 QPushButton *cancelButton() const;
308
309 /*!
310 * Returns the combobox used to type the filename or full location of the file.
311 */
312 KUrlComboBox *locationEdit() const;
313
314 /*!
315 * Returns the combobox that contains the filters
316 */
317 KFileFilterCombo *filterWidget() const;
318
319 /*!
320 * This method implements the logic to determine the user's default directory
321 * to be listed. E.g. the documents directory, home directory or a recently
322 * used directory.
323 *
324 * \a startDir A URL specifying the initial directory, or using the
325 * \c kfiledialog:/// syntax to specify a last used
326 * directory. If this URL specifies a file name, it is
327 * ignored. Refer to the KFileWidget::KFileWidget()
328 * documentation for the \c kfiledialog:/// URL syntax.
329 *
330 * \a recentDirClass If the \c kfiledialog:/// syntax is used, this
331 * will return the string to be passed to KRecentDirs::dir() and
332 * KRecentDirs::add().
333 *
334 * Returns The URL that should be listed by default (e.g. by KFileDialog or
335 * KDirSelectDialog).
336 * \sa KFileWidget::KFileWidget()
337 */
338 static QUrl getStartUrl(const QUrl &startDir, QString &recentDirClass);
339
340 /*!
341 * Similar to getStartUrl(const QUrl& startDir,QString& recentDirClass),
342 * but allows both the recent start directory keyword and a suggested file name
343 * to be returned.
344 *
345 * \a startDir A URL specifying the initial directory and/or filename,
346 * or using the \c kfiledialog:/// syntax to specify a
347 * last used location.
348 * Refer to the KFileWidget::KFileWidget()
349 * documentation for the \c kfiledialog:/// URL syntax.
350 *
351 * \a recentDirClass If the \c kfiledialog:/// syntax is used, this
352 * will return the string to be passed to KRecentDirs::dir() and
353 * KRecentDirs::add().
354 *
355 * \a fileName The suggested file name, if specified as part of the
356 * \a startDir URL.
357 *
358 * Returns The URL that should be listed by default (e.g. by KFileDialog or
359 * KDirSelectDialog).
360 *
361 * \sa KFileWidget::KFileWidget()
362 */
363 static QUrl getStartUrl(const QUrl &startDir, QString &recentDirClass, QString &fileName);
364
365 /*!
366 * \internal
367 * Used by KDirSelectDialog to share the dialog's start directory.
368 */
369 static void setStartDir(const QUrl &directory);
370
371 /*!
372 * Set a custom widget that should be added to the file dialog.
373 *
374 * \a widget A widget, or a widget of widgets, for displaying custom
375 * data in the file widget. This can be used, for example, to
376 * display a check box with the title "Open as read-only".
377 * When creating this widget, you don't need to specify a parent,
378 * since the widget's parent will be set automatically by KFileWidget.
379 */
380 void setCustomWidget(QWidget *widget);
381
382 /*!
383 * Sets a custom widget that should be added below the location and the filter
384 * editors.
385 *
386 * \a text Label of the custom widget, which is displayed below the labels
387 * "Location:" and "Filter:".
388 *
389 * \a widget Any kind of widget, but preferable a combo box or a line editor
390 * to be compliant with the location and filter layout.
391 * When creating this widget, you don't need to specify a parent,
392 * since the widget's parent will be set automatically by KFileWidget.
393 */
394 void setCustomWidget(const QString &text, QWidget *widget);
395
396 /*!
397 * Sets whether the user should be asked for confirmation
398 * when an overwrite might occur.
399 *
400 * \a enable Set this to true to enable checking.
401 */
402 void setConfirmOverwrite(bool enable);
403
404 /*!
405 * Forces the inline previews to be shown or hidden, depending on \a show.
406 *
407 * \a show Whether to show inline previews or not.
408 */
409 void setInlinePreviewShown(bool show);
410
411 /*!
412 * Provides a size hint, useful for dialogs that embed the widget.
413 *
414 * Returns a QSize, calculated to be optimal for a dialog.
415 * \since 5.0
416 */
417 QSize dialogSizeHint() const;
418
419 /*!
420 * Sets how the view should be displayed.
421 *
422 * \sa KFile::FileView
423 * \since 5.0
424 */
425 void setViewMode(KFile::FileView mode);
426
427 QSize sizeHint() const override;
428
429 /*!
430 * Set the URL schemes that the file widget should allow navigating to.
431 *
432 * If the returned list is empty, all schemes are supported.
433 *
434 * \sa QFileDialog::setSupportedSchemes
435 * \since 5.43
436 */
437 void setSupportedSchemes(const QStringList &schemes);
438
439 /*!
440 * Returns the URL schemes that the file widget should allow navigating to.
441 *
442 * If the returned list is empty, all schemes are supported. Examples for
443 * schemes are \c "file" or \c "ftp".
444 *
445 * \sa QFileDialog::supportedSchemes
446 * \since 5.43
447 */
448 QStringList supportedSchemes() const;
449
450public Q_SLOTS:
451 /*!
452 * Called when clicking ok (when this widget is used in KFileDialog)
453 * Might or might not call accept().
454 */
455 void slotOk();
456
457 /*!
458 *
459 */
460 void accept();
461
462 /*!
463 *
464 */
465 void slotCancel();
466
467protected:
468 void resizeEvent(QResizeEvent *event) override;
469 void showEvent(QShowEvent *event) override;
470 bool eventFilter(QObject *watched, QEvent *event) override;
471
472Q_SIGNALS:
473 /*!
474 * Emitted when the user selects a file. It is only emitted in single-
475 * selection mode. The best way to get notified about selected file(s)
476 * is to connect to the okClicked() signal inherited from KDialog
477 * and call selectedFile(), selectedFiles(),
478 * selectedUrl() or selectedUrls().
479 *
480 * \since 4.4
481 */
482 void fileSelected(const QUrl &);
483
484 /*!
485 * Emitted when the user highlights a file.
486 * \since 4.4
487 */
488 void fileHighlighted(const QUrl &);
489
490 /*!
491 * Emitted when the user highlights one or more files in multiselection mode.
492 *
493 * Note: fileHighlighted() or fileSelected() are @em not
494 * emitted in multiselection mode. You may use selectedItems() to
495 * ask for the current highlighted items.
496 * \sa fileSelected
497 */
498 void selectionChanged();
499
500 /*!
501 * Emitted when the filter changed, i.e.\ the user entered an own filter
502 * or chose one of the predefined set via setFilters().
503 *
504 * \a filter contains the new filter (only the extension part,
505 * not the explanation), i.e. "*.cpp" or "*.cpp *.cc".
506 *
507 * \sa setFilters()
508 * \sa currentFilter()
509 *
510 * \since 6.0
511 */
512 void filterChanged(const KFileFilter &filter);
513
514 /*!
515 * Emitted by slotOk() (directly or asynchronously) once everything has
516 * been done. Should be used by the caller to call accept().
517 */
518 void accepted();
519
520public:
521 /*!
522 * Returns the KDirOperator used to navigate the filesystem
523 */
524 KDirOperator *dirOperator();
525
526#if KIOFILEWIDGETS_ENABLE_DEPRECATED_SINCE(6, 3)
527 /*!
528 * reads the configuration for this widget from the given config group
529 * \a group the KConfigGroup to read from
530 *
531 * Deprecated: No known use case
532 *
533 * \deprecated[6.3]
534 */
535 KIOFILEWIDGETS_DEPRECATED_VERSION(6, 3, "No known use case")
536 void readConfig(KConfigGroup &group);
537#endif
538
539private:
540 friend class KFileWidgetPrivate;
541 std::unique_ptr<KFileWidgetPrivate> const d;
542};
543
544#endif
545

source code of kio/src/filewidgets/kfilewidget.h