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 | |
35 | class KAbstractFileWidget; |
36 | class KFileWidget; |
37 | |
38 | class KActionCollection; |
39 | class KUrlComboBox; |
40 | class KFileFilterCombo; |
41 | class KPushButton; |
42 | class KToolBar; |
43 | class KPreviewWidgetBase; |
44 | |
45 | class 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 | */ |
68 | class KIO_EXPORT KFileDialog : public KDialog |
69 | { |
70 | Q_OBJECT |
71 | |
72 | public: |
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 |
753 | public Q_SLOTS: |
754 | int exec(); |
755 | #endif |
756 | |
757 | Q_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 | |
806 | protected: |
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 | |
817 | protected Q_SLOTS: |
818 | virtual void slotOk(); |
819 | virtual void accept(); |
820 | virtual void slotCancel(); |
821 | |
822 | private: |
823 | Q_DISABLE_COPY(KFileDialog) |
824 | |
825 | KFileDialogPrivate * const d; |
826 | }; |
827 | |
828 | #endif |
829 | |