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