1// -*- c++ -*-
2/* This file is part of the KDE libraries
3 Copyright (C) 1997, 1998 Richard Moore <rich@kde.org>
4 1998 Stephan Kulow <coolo@kde.org>
5 1998 Daniel Grana <grana@ie.iwi.unibe.ch>
6 2000,2001 Carsten Pfeiffer <pfeiffer@kde.org>
7 2001 Frerich Raabe <raabe@kde.org>
8 2007 David Faure <faure@kde.org>
9 2009 David Jarvie <djarvie@kde.org>
10
11 This library is free software; you can redistribute it and/or
12 modify it under the terms of the GNU Library General Public
13 License as published by the Free Software Foundation; either
14 version 2 of the License, or (at your option) any later version.
15
16 This library is distributed in the hope that it will be useful,
17 but WITHOUT ANY WARRANTY; without even the implied warranty of
18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 Library General Public License for more details.
20
21 You should have received a copy of the GNU Library General Public License
22 along with this library; see the file COPYING.LIB. If not, write to
23 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
24 Boston, MA 02110-1301, USA.
25*/
26
27#ifndef KFILEDIALOG_H
28#define KFILEDIALOG_H
29
30#include <kdialog.h>
31#include <kfile.h>
32#include <kurl.h>
33#include <kmimetype.h>
34
35class KAbstractFileWidget;
36class KFileWidget;
37
38class KActionCollection;
39class KUrlComboBox;
40class KFileFilterCombo;
41class KPushButton;
42class KToolBar;
43class KPreviewWidgetBase;
44
45class KFileDialogPrivate;
46
47/**
48 * Provides a user (and developer) friendly way to
49 * select files and directories.
50 *
51 * The widget can be used as a drop in replacement for the
52 * QFileDialog widget, but has greater functionality and a nicer GUI.
53 *
54 * You will usually want to use one of the static methods
55 * getOpenFileName(), getSaveFileName(), getOpenUrl()
56 * or for multiple files getOpenFileNames() or getOpenUrls().
57 *
58 * The dialog has been designed to allow applications to customize it
59 * by subclassing. It uses geometry management to ensure that subclasses
60 * can easily add children that will be incorporated into the layout.
61 *
62 * \image html kfiledialog.png "KDE File Dialog"
63 *
64 * @short A file selection dialog.
65 *
66 * @author Richard J. Moore <rich@kde.org>, Carsten Pfeiffer <pfeiffer@kde.org>
67 */
68class KIO_EXPORT KFileDialog : public KDialog
69{
70 Q_OBJECT
71
72public:
73
74 /**
75 * Defines some default behavior of the filedialog.
76 * E.g. in mode @p Opening and @p Saving, the selected files/urls will
77 * be added to the "recent documents" list. The Saving mode also implies
78 * setKeepLocation() being set.
79 *
80 * @p Other means that no default actions are performed.
81 *
82 * @see setOperationMode
83 * @see operationMode
84 */
85 enum OperationMode { Other = 0, Opening, Saving };
86
87 /**
88 * Defines the options to use when calling getSave* functions.
89 * @since 4.4
90 */
91 enum Option {
92 ConfirmOverwrite = 0x01, /**< Confirm whether to overwrite file to save. */
93 ShowInlinePreview = 0x02 /**< Always show an inline preview. */
94 };
95 Q_DECLARE_FLAGS(Options, Option)
96
97 /**
98 * Constructs a file dialog.
99 *
100 * @param startDir Specifies the starting directory and/or initially selected
101 * file name, or a last used directory and optional file name
102 * using the @c kfiledialog:/// syntax.
103 * Refer to the KFileWidget documentation for more information
104 * on this parameter.
105 *
106 * @param filter A shell glob or a mimetype filter that specifies
107 * which files to display. For better consistency across applications,
108 * it is recommended to use a mimetype filter.
109 * See setFilter() and setMimeFilter() for details on how to use this argument.
110 *
111 * @param parent The parent widget of this dialog
112 *
113 * @param widget A widget, or a widget of widgets, for displaying custom
114 * data in the dialog. This can be used, for example, to
115 * display a check box with the caption "Open as read-only".
116 * When creating this widget, you don't need to specify a parent,
117 * since the widget's parent will be set automatically by KFileDialog.
118 *
119 * @see KFileWidget::KFileWidget()
120 */
121 KFileDialog( const KUrl& startDir, const QString& filter,
122 QWidget *parent, QWidget* widget = 0 );
123
124
125 /**
126 * Destructs the file dialog.
127 */
128 ~KFileDialog();
129
130 /**
131 * @returns The selected fully qualified filename.
132 */
133 KUrl selectedUrl() const;
134
135 /**
136 * @returns The list of selected URLs.
137 */
138 KUrl::List selectedUrls() const;
139
140 /**
141 * @returns the currently shown directory.
142 */
143 KUrl baseUrl() const;
144
145 /**
146 * Returns the full path of the selected file in the local filesystem.
147 * (Local files only)
148 */
149 QString selectedFile() const;
150
151 /**
152 * Returns a list of all selected local files.
153 */
154 QStringList selectedFiles() const;
155
156 /**
157 * Sets the directory to view.
158 *
159 * @param url URL to show.
160 * @param clearforward Indicates whether the forward queue
161 * should be cleared.
162 */
163 void setUrl(const KUrl &url, bool clearforward = true);
164
165 /**
166 * Sets the file name to preselect to @p name
167 *
168 * This takes absolute URLs and relative file names.
169 */
170 void setSelection(const QString& name);
171
172 /**
173 * Sets the operational mode of the filedialog to @p Saving, @p Opening
174 * or @p Other. This will set some flags that are specific to loading
175 * or saving files. E.g. setKeepLocation() makes mostly sense for
176 * a save-as dialog. So setOperationMode( KFileDialog::Saving ); sets
177 * setKeepLocation for example.
178 *
179 * The mode @p Saving, together with a default filter set via
180 * setMimeFilter() will make the filter combobox read-only.
181 *
182 * The default mode is @p Opening.
183 *
184 * Call this method right after instantiating KFileDialog.
185 *
186 * @see operationMode
187 * @see KFileDialog::OperationMode
188 */
189 void setOperationMode( KFileDialog::OperationMode );
190
191 /**
192 * @returns the current operation mode, Opening, Saving or Other. Default
193 * is Other.
194 *
195 * @see operationMode
196 * @see KFileDialog::OperationMode
197 */
198 OperationMode operationMode() const;
199
200 /**
201 * Sets whether the filename/url should be kept when changing directories.
202 * This is for example useful when having a predefined filename where
203 * the full path for that file is searched.
204 *
205 * This is implicitly set when operationMode() is KFileDialog::Saving
206 *
207 * getSaveFileName() and getSaveUrl() set this to true by default, so that
208 * you can type in the filename and change the directory without having
209 * to type the name again.
210 */
211 void setKeepLocation( bool keep );
212
213 /**
214 * @returns whether the contents of the location edit are kept when
215 * changing directories.
216 */
217 bool keepsLocation() const;
218
219 /**
220 * Sets the filter to be used to @p filter.
221 *
222 * The filter can be either set as a space-separated list of
223 * mimetypes, which is recommended, or as a list of shell globs
224 * separated by @c '\\n'.
225 *
226 * If the filter contains an unescaped @c '/', a mimetype filter is assumed.
227 * If you would like a @c '/' visible in your filter it can be escaped with
228 * a @c '\'. You can specify multiple mimetypes like this (separated with
229 * space):
230 *
231 * \code
232 * kfile->setFilter( "image/png text/html text/plain" );
233 * \endcode
234 *
235 * When showing the filter to the user, the mimetypes will be automatically
236 * translated into their description like `PNG image'. Multiple mimetypes
237 * will be automatically summarized to a filter item `All supported files'.
238 * To add a filter item for all files matching @c '*', add @c all/allfiles
239 * as mimetype.
240 *
241 * If the filter contains no unescaped @c '/', it is assumed that
242 * the filter contains conventional shell globs. Several filter items
243 * to select from can be separated by @c '\\n'. Every
244 * filter entry is defined through @c namefilter|text to display.
245 * If no @c '|' is found in the expression, just the namefilter is
246 * shown. Examples:
247 *
248 * \code
249 * kfile->setFilter("*.cpp|C++ Source Files\n*.h|Header files");
250 * kfile->setFilter("*.cpp");
251 * kfile->setFilter("*.cpp|Sources (*.cpp)");
252 * kfile->setFilter("*.cpp|" + i18n("Sources (*.cpp)"));
253 * kfile->setFilter("*.cpp *.cc *.C|C++ Source Files\n*.h *.H|Header files");
254 * \endcode
255 *
256 * Note: The text to display is not parsed in any way. So, if you
257 * want to show the suffix to select by a specific filter, you must
258 * repeat it.
259 *
260 * For better consistency across applications, it is recommended to use a
261 * mimetype filter.
262 *
263 * @see filterChanged
264 * @see setMimeFilter
265 */
266 void setFilter(const QString& filter);
267
268 /**
269 * Returns the current filter as entered by the user or one of the
270 * predefined set via setFilter().
271 *
272 * @see setFilter()
273 * @see filterChanged()
274 */
275 QString currentFilter() const;
276
277 /**
278 * Returns the mimetype for the desired output format.
279 *
280 * This is only valid if setMimeFilter() has been called
281 * previously.
282 *
283 * @see setFilterMimeType()
284 */
285 KMimeType::Ptr currentFilterMimeType();
286
287 /**
288 * Sets the filter up to specify the output type.
289 *
290 * @param types a list of mimetypes that can be used as output format
291 * @param defaultType the default mimetype to use as output format, if any.
292 * If @p defaultType is set, it will be set as the current item.
293 * Otherwise, a first item showing all the mimetypes will be created.
294 * Typically, @p defaultType should be empty for loading and set for saving.
295 *
296 * Do not use in conjunction with setFilter()
297 */
298 void setMimeFilter( const QStringList& types,
299 const QString& defaultType = QString() );
300
301 /**
302 * The mimetype for the desired output format.
303 *
304 * This is only valid if setMimeFilter() has been called
305 * previously.
306 *
307 * @see setMimeFilter()
308 */
309 QString currentMimeFilter() const;
310
311 /**
312 * Clears any mime- or namefilter. Does not reload the directory.
313 */
314 void clearFilter();
315
316 /**
317 * Adds a preview widget and enters the preview mode.
318 *
319 * In this mode the dialog is split and the right part contains your
320 * preview widget.
321 *
322 * Ownership is transferred to KFileDialog. You need to create the
323 * preview-widget with "new", i.e. on the heap.
324 *
325 * @param w The widget to be used for the preview.
326 */
327 void setPreviewWidget(KPreviewWidgetBase *w);
328
329 /**
330 * Forces the inline previews to be shown or hidden, depending on @p show.
331 *
332 * @param show Whether to show inline previews or not.
333 * @since 4.2
334 */
335 void setInlinePreviewShown(bool show);
336
337 /**
338 * Sets whether the dialog should ask before accepting the selected file
339 * when KFileDialog::OperationMode is set to Saving.
340 *
341 * In this case a KMessageBox appears for confirmation.
342 *
343 * @param enable Set this to true to enable checking.
344 * @since 4.2
345 */
346 void setConfirmOverwrite(bool enable);
347
348 /** @see QWidget::sizeHint() */
349 virtual QSize sizeHint() const;
350
351 /**
352 * Creates a modal file dialog and return the selected
353 * filename or an empty string if none was chosen.
354 *
355 * Note that with
356 * this method the user must select an existing filename.
357 *
358 * @param startDir Starting directory or @c kfiledialog:/// URL.
359 * Refer to the KFileWidget documentation for more information
360 * on this parameter.
361 * @param filter A shell glob or a mimetype filter that specifies which files to display.
362 * The preferred option is to set a list of mimetype names, see setMimeFilter() for details.
363 * Otherwise you can set the text to be displayed for the each glob, and
364 * provide multiple globs, see setFilter() for details.
365 * @param parent The widget the dialog will be centered on initially.
366 * @param caption The name of the dialog widget.
367 *
368 * @see KFileWidget::KFileWidget()
369 */
370 static QString getOpenFileName( const KUrl& startDir= KUrl(),
371 const QString& filter= QString(),
372 QWidget *parent= 0,
373 const QString& caption = QString() );
374
375
376 /**
377 * Use this version only if you have no QWidget available as
378 * parent widget. This can be the case if the parent widget is
379 * a widget in another process or if the parent widget is a
380 * non-Qt widget. For example, in a GTK program.
381 */
382 static QString getOpenFileNameWId( const KUrl& startDir,
383 const QString& filter,
384 WId parent_id, const QString& caption );
385
386 /**
387 * Creates a modal file dialog and returns the selected
388 * filenames or an empty list if none was chosen.
389 *
390 * Note that with
391 * this method the user must select an existing filename.
392 *
393 * @param startDir Starting directory or @c kfiledialog:/// URL.
394 * Refer to the KFileWidget documentation for more information
395 * on this parameter.
396 * @param filter A shell glob or a mimetype filter that specifies which files to display.
397 * The preferred option is to set a list of mimetype names, see setMimeFilter() for details.
398 * Otherwise you can set the text to be displayed for the each glob, and
399 * provide multiple globs, see setFilter() for details.
400 * @param parent The widget the dialog will be centered on initially.
401 * @param caption The name of the dialog widget.
402 *
403 * @see KFileWidget::KFileWidget()
404 */
405 static QStringList getOpenFileNames( const KUrl& startDir= KUrl(),
406 const QString& filter = QString(),
407 QWidget *parent = 0,
408 const QString& caption= QString() );
409
410
411
412 /**
413 * Creates a modal file dialog and returns the selected
414 * URL or an empty string if none was chosen.
415 *
416 * Note that with
417 * this method the user must select an existing URL.
418 *
419 * @param startDir Starting directory or @c kfiledialog:/// URL.
420 * Refer to the KFileWidget documentation for more information
421 * on this parameter.
422 * @param filter A shell glob or a mimetype filter that specifies which files to display.
423 * The preferred option is to set a list of mimetype names, see setMimeFilter() for details.
424 * Otherwise you can set the text to be displayed for the each glob, and
425 * provide multiple globs, see setFilter() for details.
426 * @param parent The widget the dialog will be centered on initially.
427 * @param caption The name of the dialog widget.
428 *
429 * @see KFileWidget::KFileWidget()
430 */
431 static KUrl getOpenUrl( const KUrl& startDir = KUrl(),
432 const QString& filter = QString(),
433 QWidget *parent= 0,
434 const QString& caption = QString() );
435
436
437
438 /**
439 * Creates a modal file dialog and returns the selected
440 * URLs or an empty list if none was chosen.
441 *
442 * Note that with
443 * this method the user must select an existing filename.
444 *
445 * @param startDir Starting directory or @c kfiledialog:/// URL.
446 * Refer to the KFileWidget documentation for more information
447 * on this parameter.
448 * @param filter A shell glob or a mimetype filter that specifies which files to display.
449 * The preferred option is to set a list of mimetype names, see setMimeFilter() for details.
450 * Otherwise you can set the text to be displayed for the each glob, and
451 * provide multiple globs, see setFilter() for details.
452 * @param parent The widget the dialog will be centered on initially.
453 * @param caption The name of the dialog widget.
454 *
455 * @see KFileWidget::KFileWidget()
456 */
457 static KUrl::List getOpenUrls( const KUrl& startDir = KUrl(),
458 const QString& filter = QString(),
459 QWidget *parent = 0,
460 const QString& caption = QString() );
461
462
463
464 /**
465 * Creates a modal file dialog and returns the selected
466 * filename or an empty string if none was chosen.
467 *
468 * Note that with this
469 * method the user need not select an existing filename.
470 *
471 * @param startDir Starting directory or @c kfiledialog:/// URL.
472 * Refer to the KFileWidget documentation for more information
473 * on this parameter.
474 * @param filter A shell glob or a mimetype filter that specifies which files to display.
475 * The preferred option is to set a list of mimetype names, see setMimeFilter() for details.
476 * Otherwise you can set the text to be displayed for the each glob, and
477 * provide multiple globs, see setFilter() for details.
478 * @param parent The widget the dialog will be centered on initially.
479 * @param caption The name of the dialog widget.
480 *
481 * @see KFileWidget::KFileWidget()
482 */
483 static QString getSaveFileName( const KUrl& startDir = KUrl(),
484 const QString& filter = QString(),
485 QWidget *parent = 0,
486 const QString& caption = QString() );
487
488 /**
489 * Creates a modal file dialog and returns the selected
490 * filename or an empty string if none was chosen.
491 *
492 * Note that with this
493 * method the user need not select an existing filename.
494 *
495 * @param startDir Starting directory or @c kfiledialog:/// URL.
496 * Refer to the KFileWidget documentation for more information
497 * on this parameter.
498 * @param filter A shell glob or a mimetype filter that specifies which files to display.
499 * The preferred option is to set a list of mimetype names, see setMimeFilter() for details.
500 * Otherwise you can set the text to be displayed for the each glob, and
501 * provide multiple globs, see setFilter() for details.
502 * @param parent The widget the dialog will be centered on initially.
503 * @param caption The name of the dialog widget.
504 * @param options Dialog options.
505 *
506 * @see KFileWidget::KFileWidget()
507 *
508 * @since 4.4
509 */
510 static QString getSaveFileName( const KUrl& startDir,
511 const QString& filter,
512 QWidget *parent,
513 const QString& caption,
514 Options options );
515
516
517 /**
518 * This function accepts the window id of the parent window, instead
519 * of QWidget*. It should be used only when necessary.
520 */
521 static QString getSaveFileNameWId( const KUrl &startDir, const QString& filter,
522 WId parent_id,
523 const QString& caption );
524
525 /**
526 * This function accepts the window id of the parent window, instead
527 * of QWidget*. It should be used only when necessary.
528 *
529 * @since 4.4
530 */
531 static QString getSaveFileNameWId( const KUrl &startDir, const QString& filter,
532 WId parent_id,
533 const QString& caption,
534 Options options );
535
536 /**
537 * Creates a modal file dialog and returns the selected
538 * filename or an empty string if none was chosen.
539 *
540 * Note that with this
541 * method the user need not select an existing filename.
542 *
543 * @param startDir Starting directory or @c kfiledialog:/// URL.
544 * Refer to the KFileWidget documentation for more information
545 * on this parameter.
546 * @param filter A shell glob or a mimetype filter that specifies which files to display.
547 * The preferred option is to set a list of mimetype names, see setMimeFilter() for details.
548 * Otherwise you can set the text to be displayed for the each glob, and
549 * provide multiple globs, see setFilter() for details.
550 * @param parent The widget the dialog will be centered on initially.
551 * @param caption The name of the dialog widget.
552 *
553 * @see KFileWidget::KFileWidget()
554 */
555 static KUrl getSaveUrl( const KUrl& startDir = KUrl(),
556 const QString& filter = QString(),
557 QWidget *parent = 0,
558 const QString& caption = QString() );
559
560 /**
561 * Creates a modal file dialog and returns the selected
562 * filename or an empty string if none was chosen.
563 *
564 * Note that with this
565 * method the user need not select an existing filename.
566 *
567 * @param startDir Starting directory or @c kfiledialog:/// URL.
568 * Refer to the KFileWidget documentation for more information
569 * on this parameter.
570 * @param filter A shell glob or a mimetype filter that specifies which files to display.
571 * The preferred option is to set a list of mimetype names, see setMimeFilter() for details.
572 * Otherwise you can set the text to be displayed for the each glob, and
573 * provide multiple globs, see setFilter() for details.
574 * @param parent The widget the dialog will be centered on initially.
575 * @param caption The name of the dialog widget.
576 * @param options Dialog options.
577 *
578 * @see KFileWidget::KFileWidget()
579 *
580 * @since 4.4
581 */
582 static KUrl getSaveUrl( const KUrl& startDir,
583 const QString& filter,
584 QWidget *parent,
585 const QString& caption,
586 Options options );
587
588
589 /**
590 * Creates a modal directory-selection dialog and returns the selected
591 * directory (local only) or an empty string if none was chosen.
592 *
593 * @param startDir Starting directory or @c kfiledialog:/// URL.
594 * Refer to the KFileWidget documentation for more information
595 * on this parameter.
596 * @param parent The widget the dialog will be centered on initially.
597 * @param caption The name of the dialog widget.
598 * @return the path to an existing local directory.
599 *
600 * @see KFileWidget::KFileWidget()
601 */
602 static QString getExistingDirectory( const KUrl& startDir = KUrl(),
603 QWidget * parent = 0,
604 const QString& caption= QString() );
605
606 /**
607 * Creates a modal directory-selection dialog and returns the selected
608 * directory or an empty string if none was chosen.
609 * This version supports remote urls.
610 *
611 * @param startDir Starting directory or @c kfiledialog:/// URL.
612 * Refer to the KFileWidget documentation for more information
613 * on this parameter.
614 * @param parent The widget the dialog will be centered on initially.
615 * @param caption The name of the dialog widget.
616 * @return the url to an existing directory (local or remote).
617 *
618 * @see KFileWidget::KFileWidget()
619 */
620 static KUrl getExistingDirectoryUrl( const KUrl& startDir = KUrl(),
621 QWidget * parent = 0,
622 const QString& caption= QString() );
623
624 /**
625 * Creates a modal file dialog with an image previewer and returns the
626 * selected url or an empty string if none was chosen.
627 *
628 * @param startDir Starting directory or @c kfiledialog:/// URL.
629 * Refer to the KFileWidget documentation for more information
630 * on this parameter.
631 * @param parent The widget the dialog will be centered on initially.
632 * @param caption The name of the dialog widget.
633 *
634 * @see KFileWidget::KFileWidget()
635 */
636 static KUrl getImageOpenUrl( const KUrl& startDir = KUrl(),
637 QWidget *parent = 0,
638 const QString& caption = QString() );
639
640 /**
641 * Sets the mode of the dialog.
642 *
643 * The mode is defined as (in kfile.h):
644 * \code
645 * enum Mode {
646 * File = 1,
647 * Directory = 2,
648 * Files = 4,
649 * ExistingOnly = 8,
650 * LocalOnly = 16
651 * };
652 * \endcode
653 * You can OR the values, e.g.
654 * \code
655 * KFile::Modes mode = KFile::Files |
656 * KFile::ExistingOnly |
657 * KFile::LocalOnly );
658 * setMode( mode );
659 * \endcode
660 */
661 void setMode( KFile::Modes m );
662
663 /**
664 * Returns the mode of the filedialog.
665 * @see setMode()
666 */
667 KFile::Modes mode() const;
668
669 /**
670 * Sets the text to be displayed in front of the selection.
671 *
672 * The default is "Location".
673 * Most useful if you want to make clear what
674 * the location is used for.
675 */
676 void setLocationLabel(const QString& text);
677
678 /**
679 * Returns the KFileWidget that implements most of this file dialog.
680 * If you link to libkfile you can cast this to a KFileWidget*.
681 */
682 KAbstractFileWidget* fileWidget();
683
684 /**
685 * Returns a pointer to the toolbar.
686 *
687 * You can use this to insert custom
688 * items into it, e.g.:
689 * \code
690 * yourAction = new KAction( i18n("Your Action"), 0,
691 * this, SLOT( yourSlot() ),
692 * this, "action name" );
693 * yourAction->plug( kfileDialog->toolBar() );
694 * \endcode
695 */
696 KToolBar *toolBar() const;
697
698 /**
699 * @returns a pointer to the OK-Button in the filedialog. You may use it
700 * e.g. to set a custom text to it.
701 */
702 KPushButton *okButton() const;
703
704 /**
705 * @returns a pointer to the Cancel-Button in the filedialog. You may use
706 * it e.g. to set a custom text to it.
707 */
708 KPushButton *cancelButton() const;
709
710 /**
711 * @returns the combobox used to type the filename or full location of the file.
712 * You need to link to libkfile to use this widget.
713 */
714 KUrlComboBox *locationEdit() const;
715
716 /**
717 * @returns the combobox that contains the filters
718 * You need to link to libkfile to use this widget.
719 */
720 KFileFilterCombo *filterWidget() const;
721
722 /**
723 * @returns a pointer to the action collection, holding all the used KActions.
724 */
725 KActionCollection *actionCollection() const;
726
727 /**
728 * This method implements the logic to determine the user's default directory
729 * to be listed. E.g. the documents directory, home directory or a recently
730 * used directory.
731 *
732 * @param startDir Starting directory or @c kfiledialog:/// URL.
733 * Refer to the KFileWidget documentation for more information
734 * on this parameter.
735 * @param recentDirClass If the @c kfiledialog:/// syntax is used, this
736 * will return the string to be passed to KRecentDirs::dir() and
737 * KRecentDirs::add().
738 * @return The URL that should be listed by default (e.g. by KFileDialog or
739 * KDirSelectDialog).
740 *
741 * @see KFileWidget::KFileWidget()
742 * @see KFileWidget::getStartUrl( const KUrl& startDir, QString& recentDirClass );
743 */
744 static KUrl getStartUrl( const KUrl& startDir, QString& recentDirClass );
745
746 /**
747 * @internal
748 * Used by KDirSelectDialog to share the dialog's start directory.
749 */
750 static void setStartDir( const KUrl& directory );
751
752#ifdef Q_WS_WIN
753public Q_SLOTS:
754 int exec();
755#endif
756
757Q_SIGNALS:
758 /**
759 * Emitted when the user selects a file. It is only emitted in single-
760 * selection mode. The best way to get notified about selected file(s)
761 * is to connect to the okClicked() signal inherited from KDialog
762 * and call selectedFile(), selectedFiles(),
763 * selectedUrl() or selectedUrls().
764 *
765 * \since 4.4
766 */
767 void fileSelected(const KUrl&);
768 /**
769 * @deprecated, connect to fileSelected(const KUrl&) instead
770 */
771 QT_MOC_COMPAT void fileSelected(const QString&); // TODO KDE5: remove
772
773 /**
774 * Emitted when the user highlights a file.
775 *
776 * \since 4.4
777 */
778 void fileHighlighted(const KUrl&);
779 /**
780 * @deprecated, connect to fileSelected(const KUrl&) instead
781 */
782 QT_MOC_COMPAT void fileHighlighted(const QString&); // TODO KDE5: remove
783
784 /**
785 * Emitted when the user hilights one or more files in multiselection mode.
786 *
787 * Note: fileHighlighted() or fileSelected() are @em not
788 * emitted in multiselection mode. You may use selectedItems() to
789 * ask for the current highlighted items.
790 * @see fileSelected
791 */
792 void selectionChanged();
793
794 /**
795 * Emitted when the filter changed, i.e. the user entered an own filter
796 * or chose one of the predefined set via setFilter().
797 *
798 * @param filter contains the new filter (only the extension part,
799 * not the explanation), i.e. "*.cpp" or "*.cpp *.cc".
800 *
801 * @see setFilter()
802 * @see currentFilter()
803 */
804 void filterChanged( const QString& filter );
805
806protected:
807 /**
808 * Reimplemented to animate the cancel button.
809 */
810 virtual void keyPressEvent( QKeyEvent *e );
811
812 /**
813 * Reimplemented for saving the dialog geometry.
814 */
815 virtual void hideEvent( QHideEvent *event );
816
817protected Q_SLOTS:
818 virtual void slotOk();
819 virtual void accept();
820 virtual void slotCancel();
821
822private:
823 Q_DISABLE_COPY(KFileDialog)
824
825 KFileDialogPrivate * const d;
826};
827
828#endif
829