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

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