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 | |
26 | class QUrl; |
27 | class QPushButton; |
28 | class KActionCollection; |
29 | class KFileWidgetPrivate; |
30 | class KUrlComboBox; |
31 | class KFileFilterCombo; |
32 | |
33 | class KPreviewWidgetBase; |
34 | class QMimeType; |
35 | class KConfigGroup; |
36 | class KJob; |
37 | class KFileItem; |
38 | class 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 | */ |
49 | class KIOFILEWIDGETS_EXPORT KFileWidget : public QWidget |
50 | { |
51 | Q_OBJECT |
52 | public: |
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 | |
450 | public 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 | |
467 | protected: |
468 | void resizeEvent(QResizeEvent *event) override; |
469 | void showEvent(QShowEvent *event) override; |
470 | bool eventFilter(QObject *watched, QEvent *event) override; |
471 | |
472 | Q_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 | |
520 | public: |
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 | |
539 | private: |
540 | friend class KFileWidgetPrivate; |
541 | std::unique_ptr<KFileWidgetPrivate> const d; |
542 | }; |
543 | |
544 | #endif |
545 | |