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 2008 Rafael Fernández López <ereslibre@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
28#ifndef KFILEWIDGET_H
29#define KFILEWIDGET_H
30
31#include "kfile_export.h"
32#include "kabstractfilewidget.h"
33#include <QtGui/QWidget>
34
35class KJob;
36class KFileItem;
37class KDirOperator;
38
39class KFILE_EXPORT KFileWidget : public QWidget, public KAbstractFileWidget
40{
41 Q_OBJECT
42 Q_INTERFACES(KAbstractFileWidget)
43public:
44 /**
45 * Constructs a file selector widget.
46 *
47 * @param startDir This can either be:
48 * @li An empty URL (KUrl()) to start in the current working directory,
49 * or the last directory where a file has been selected.
50 * @li The path or URL of a starting directory.
51 * @li An initial file name to select, with the starting directory being
52 * the current working directory or the last directory where a file
53 * has been selected.
54 * @li The path or URL of a file, specifying both the starting directory and
55 * an initially selected file name.
56 * @li A URL of the form @c kfiledialog:///&lt;keyword&gt; to start in the
57 * directory last used by a filedialog in the same application that
58 * specified the same keyword.
59 * @li A URL of the form @c kfiledialog:///&lt;keyword&gt;/&lt;filename&gt;
60 * to start in the directory last used by a filedialog in the same
61 * application that specified the same keyword, and to initially
62 * select the specified filename.
63 * @li A URL of the form @c kfiledialog:///&lt;keyword&gt;?global to start
64 * in the directory last used by a filedialog in any application that
65 * specified the same keyword.
66 * @li A URL of the form @c kfiledialog:///&lt;keyword&gt;/&lt;filename&gt;?global
67 * to start in the directory last used by a filedialog in any
68 * application that specified the same keyword, and to initially
69 * select the specified filename.
70 *
71 * @param parent The parent widget of this widget
72 *
73 */
74 KFileWidget(const KUrl& startDir, QWidget *parent);
75
76 /**
77 * Destructor
78 */
79 virtual ~KFileWidget();
80
81 /**
82 * @returns The selected fully qualified filename.
83 */
84 virtual KUrl selectedUrl() const;
85
86 /**
87 * @returns The list of selected URLs.
88 */
89 virtual KUrl::List selectedUrls() const;
90
91 /**
92 * @returns the currently shown directory.
93 */
94 virtual KUrl baseUrl() const;
95
96 /**
97 * Returns the full path of the selected file in the local filesystem.
98 * (Local files only)
99 */
100 virtual QString selectedFile() const;
101
102 /**
103 * Returns a list of all selected local files.
104 */
105 virtual QStringList selectedFiles() const;
106
107 /**
108 * Sets the directory to view.
109 *
110 * @param url URL to show.
111 * @param clearforward Indicates whether the forward queue
112 * should be cleared.
113 */
114 virtual void setUrl(const KUrl &url, bool clearforward = true);
115
116 /**
117 * Sets the file name to preselect to @p name
118 *
119 * This takes absolute URLs and relative file names.
120 */
121 virtual void setSelection(const QString& name);
122
123 /**
124 * Sets the operational mode of the filedialog to @p Saving, @p Opening
125 * or @p Other. This will set some flags that are specific to loading
126 * or saving files. E.g. setKeepLocation() makes mostly sense for
127 * a save-as dialog. So setOperationMode( KFileWidget::Saving ); sets
128 * setKeepLocation for example.
129 *
130 * The mode @p Saving, together with a default filter set via
131 * setMimeFilter() will make the filter combobox read-only.
132 *
133 * The default mode is @p Opening.
134 *
135 * Call this method right after instantiating KFileWidget.
136 *
137 * @see operationMode
138 * @see KFileWidget::OperationMode
139 */
140 virtual void setOperationMode( OperationMode );
141
142 /**
143 * @returns the current operation mode, Opening, Saving or Other. Default
144 * is Other.
145 *
146 * @see operationMode
147 * @see KFileWidget::OperationMode
148 */
149 virtual OperationMode operationMode() const;
150
151 /**
152 * Sets whether the filename/url should be kept when changing directories.
153 * This is for example useful when having a predefined filename where
154 * the full path for that file is searched.
155 *
156 * This is implicitly set when operationMode() is KFileWidget::Saving
157 *
158 * getSaveFileName() and getSaveUrl() set this to true by default, so that
159 * you can type in the filename and change the directory without having
160 * to type the name again.
161 */
162 virtual void setKeepLocation( bool keep );
163
164 /**
165 * @returns whether the contents of the location edit are kept when
166 * changing directories.
167 */
168 virtual bool keepsLocation() const;
169
170 /**
171 * Sets the filter to be used to @p filter.
172 *
173 * You can set more
174 * filters for the user to select separated by '\n'. Every
175 * filter entry is defined through namefilter|text to display.
176 * If no | is found in the expression, just the namefilter is
177 * shown. Examples:
178 *
179 * \code
180 * kfile->setFilter("*.cpp|C++ Source Files\n*.h|Header files");
181 * kfile->setFilter("*.cpp");
182 * kfile->setFilter("*.cpp|Sources (*.cpp)");
183 * kfile->setFilter("*.cpp|" + i18n("Sources (*.cpp)"));
184 * kfile->setFilter("*.cpp *.cc *.C|C++ Source Files\n*.h *.H|Header files");
185 * \endcode
186 *
187 * Note: The text to display is not parsed in any way. So, if you
188 * want to show the suffix to select by a specific filter, you must
189 * repeat it.
190 *
191 * If the filter contains an unescaped '/', a mimetype-filter is assumed.
192 * If you would like a '/' visible in your filter it can be escaped with
193 * a '\'. You can specify multiple mimetypes like this (separated with
194 * space):
195 *
196 * \code
197 * kfile->setFilter( "image/png text/html text/plain" );
198 * kfile->setFilter( "*.cue|CUE\\/BIN Files (*.cue)" );
199 * \endcode
200 *
201 * @see filterChanged
202 * @see setMimeFilter
203 */
204 virtual void setFilter(const QString& filter);
205
206 /**
207 * Returns the current filter as entered by the user or one of the
208 * predefined set via setFilter().
209 *
210 * @see setFilter()
211 * @see filterChanged()
212 */
213 virtual QString currentFilter() const;
214
215 /**
216 * Returns the mimetype for the desired output format.
217 *
218 * This is only valid if setFilterMimeType() has been called
219 * previously.
220 *
221 * @see setFilterMimeType()
222 */
223 virtual KMimeType::Ptr currentFilterMimeType();
224
225 /**
226 * Sets the filter up to specify the output type.
227 *
228 * @param types a list of mimetypes that can be used as output format
229 * @param defaultType the default mimetype to use as output format, if any.
230 * If @p defaultType is set, it will be set as the current item.
231 * Otherwise, a first item showing all the mimetypes will be created.
232 * Typically, @p defaultType should be empty for loading and set for saving.
233 *
234 * Do not use in conjunction with setFilter()
235 */
236 virtual void setMimeFilter( const QStringList& types,
237 const QString& defaultType = QString() );
238
239 /**
240 * The mimetype for the desired output format.
241 *
242 * This is only valid if setMimeFilter() has been called
243 * previously.
244 *
245 * @see setMimeFilter()
246 */
247 virtual QString currentMimeFilter() const;
248
249 /**
250 * Clears any mime- or namefilter. Does not reload the directory.
251 */
252 virtual void clearFilter();
253
254 /**
255 * Adds a preview widget and enters the preview mode.
256 *
257 * In this mode the dialog is split and the right part contains your
258 * preview widget.
259 *
260 * Ownership is transferred to KFileWidget. You need to create the
261 * preview-widget with "new", i.e. on the heap.
262 *
263 * @param w The widget to be used for the preview.
264 */
265 virtual void setPreviewWidget(KPreviewWidgetBase *w);
266
267 /**
268 * Sets the mode of the dialog.
269 *
270 * The mode is defined as (in kfile.h):
271 * \code
272 * enum Mode {
273 * File = 1,
274 * Directory = 2,
275 * Files = 4,
276 * ExistingOnly = 8,
277 * LocalOnly = 16
278 * };
279 * \endcode
280 * You can OR the values, e.g.
281 * \code
282 * KFile::Modes mode = KFile::Files |
283 * KFile::ExistingOnly |
284 * KFile::LocalOnly );
285 * setMode( mode );
286 * \endcode
287 */
288 virtual void setMode( KFile::Modes m );
289
290 /**
291 * Returns the mode of the filedialog.
292 * @see setMode()
293 */
294 virtual KFile::Modes mode() const;
295
296 /**
297 * Sets the text to be displayed in front of the selection.
298 *
299 * The default is "Location".
300 * Most useful if you want to make clear what
301 * the location is used for.
302 */
303 virtual void setLocationLabel(const QString& text);
304
305 /**
306 * Returns a pointer to the toolbar.
307 *
308 * You can use this to insert custom
309 * items into it, e.g.:
310 * \code
311 * yourAction = new KAction( i18n("Your Action"), 0,
312 * this, SLOT( yourSlot() ),
313 * this, "action name" );
314 * yourAction->plug( kfileDialog->toolBar() );
315 * \endcode
316 */
317 KToolBar *toolBar() const;
318
319 /**
320 * @returns a pointer to the OK-Button in the filedialog.
321 * Note that the button is hidden and unconnected when using KFileWidget alone;
322 * KFileDialog shows it and connects to it.
323 */
324 KPushButton *okButton() const;
325
326 /**
327 * @returns a pointer to the Cancel-Button in the filedialog.
328 * Note that the button is hidden and unconnected when using KFileWidget alone;
329 * KFileDialog shows it and connects to it.
330 */
331 KPushButton *cancelButton() const;
332
333 /**
334 * @returns the combobox used to type the filename or full location of the file.
335 */
336 KUrlComboBox *locationEdit() const;
337
338 /**
339 * @returns the combobox that contains the filters
340 */
341 KFileFilterCombo *filterWidget() const;
342
343 /**
344 * @returns a pointer to the action collection, holding all the used
345 * KActions.
346 */
347 KActionCollection *actionCollection() const;
348
349 /**
350 * This method implements the logic to determine the user's default directory
351 * to be listed. E.g. the documents directory, home directory or a recently
352 * used directory.
353 * @param startDir A URL specifying the initial directory, or using the
354 * @c kfiledialog:/// syntax to specify a last used
355 * directory. If this URL specifies a file name, it is
356 * ignored. Refer to the KFileWidget::KFileWidget()
357 * documentation for the @c kfiledialog:/// URL syntax.
358 * @param recentDirClass If the @c kfiledialog:/// syntax is used, this
359 * will return the string to be passed to KRecentDirs::dir() and
360 * KRecentDirs::add().
361 * @return The URL that should be listed by default (e.g. by KFileDialog or
362 * KDirSelectDialog).
363 * @see KFileWidget::KFileWidget()
364 */
365 static KUrl getStartUrl( const KUrl& startDir, QString& recentDirClass );
366
367 /**
368 * Similar to getStartUrl(const KUrl& startDir,QString& recentDirClass),
369 * but allows both the recent start directory keyword and a suggested file name
370 * to be returned.
371 * @param startDir A URL specifying the initial directory and/or filename,
372 * or using the @c kfiledialog:/// syntax to specify a
373 * last used location.
374 * Refer to the KFileWidget::KFileWidget()
375 * documentation for the @c kfiledialog:/// URL syntax.
376 * @param recentDirClass If the @c kfiledialog:/// syntax is used, this
377 * will return the string to be passed to KRecentDirs::dir() and
378 * KRecentDirs::add().
379 * @param fileName The suggested file name, if specified as part of the
380 * @p StartDir URL.
381 * @return The URL that should be listed by default (e.g. by KFileDialog or
382 * KDirSelectDialog).
383 *
384 * @see KFileWidget::KFileWidget()
385 * @since 4.3
386 */
387 static KUrl getStartUrl( const KUrl& startDir, QString& recentDirClass, QString& fileName );
388
389 /**
390 * @internal
391 * Used by KDirSelectDialog to share the dialog's start directory.
392 */
393 static void setStartDir( const KUrl& directory );
394
395 /**
396 * Set a custom widget that should be added to the file dialog.
397 * @param widget A widget, or a widget of widgets, for displaying custom
398 * data in the file widget. This can be used, for example, to
399 * display a check box with the caption "Open as read-only".
400 * When creating this widget, you don't need to specify a parent,
401 * since the widget's parent will be set automatically by KFileWidget.
402 */
403 virtual void setCustomWidget(QWidget* widget);
404
405 /**
406 * Sets a custom widget that should be added below the location and the filter
407 * editors.
408 * @param text Label of the custom widget, which is displayed below the labels
409 * "Location:" and "Filter:".
410 * @param widget Any kind of widget, but preferable a combo box or a line editor
411 * to be compliant with the location and filter layout.
412 * When creating this widget, you don't need to specify a parent,
413 * since the widget's parent will be set automatically by KFileWidget.
414 */
415 virtual void setCustomWidget(const QString& text, QWidget* widget);
416
417 /// @internal for future extensions
418 virtual void virtual_hook( int id, void* data );
419
420public Q_SLOTS:
421 /**
422 * Called when clicking ok (when this widget is used in KFileDialog)
423 * Might or might not call accept().
424 */
425 virtual void slotOk();
426 virtual void accept();
427 virtual void slotCancel();
428
429protected:
430 virtual void resizeEvent(QResizeEvent* event);
431 virtual void showEvent(QShowEvent* event);
432 virtual bool eventFilter(QObject* watched, QEvent* event);
433
434Q_SIGNALS:
435 /**
436 * Emitted when the user selects a file. It is only emitted in single-
437 * selection mode. The best way to get notified about selected file(s)
438 * is to connect to the okClicked() signal inherited from KDialog
439 * and call selectedFile(), selectedFiles(),
440 * selectedUrl() or selectedUrls().
441 *
442 * \since 4.4
443 */
444 void fileSelected(const KUrl&);
445
446 /**
447 * @deprecated, connect to fileSelected(const KUrl&) instead
448 */
449 QT_MOC_COMPAT void fileSelected(const QString&); // TODO KDE5: remove
450
451 /**
452 * Emitted when the user highlights a file.
453 * \since 4.4
454 */
455 void fileHighlighted(const KUrl&);
456 /**
457 * @deprecated, connect to fileSelected(const KUrl&) instead
458 */
459 QT_MOC_COMPAT void fileHighlighted(const QString&); // TODO KDE5: remove
460
461 /**
462 * Emitted when the user hilights one or more files in multiselection mode.
463 *
464 * Note: fileHighlighted() or fileSelected() are @em not
465 * emitted in multiselection mode. You may use selectedItems() to
466 * ask for the current highlighted items.
467 * @see fileSelected
468 */
469 void selectionChanged();
470
471 /**
472 * Emitted when the filter changed, i.e. the user entered an own filter
473 * or chose one of the predefined set via setFilter().
474 *
475 * @param filter contains the new filter (only the extension part,
476 * not the explanation), i.e. "*.cpp" or "*.cpp *.cc".
477 *
478 * @see setFilter()
479 * @see currentFilter()
480 */
481 void filterChanged( const QString& filter );
482
483 /**
484 * Emitted by slotOk() (directly or asynchronously) once everything has
485 * been done. Should be used by the caller to call accept().
486 */
487 void accepted();
488
489public:
490 /**
491 * @returns the KDirOperator used to navigate the filesystem
492 * @since 4.3
493 */
494 KDirOperator* dirOperator();
495
496 /**
497 * reads the configuration for this widget from the given config group
498 * @param group the KConfigGroup to read from
499 * @since 4.4
500 */
501 void readConfig( KConfigGroup& group );
502
503private:
504 friend class KFileWidgetPrivate;
505 KFileWidgetPrivate* const d;
506
507 Q_PRIVATE_SLOT(d, void _k_slotLocationChanged(const QString&))
508 Q_PRIVATE_SLOT(d, void _k_urlEntered(const KUrl&))
509 Q_PRIVATE_SLOT(d, void _k_enterUrl(const KUrl&))
510 Q_PRIVATE_SLOT(d, void _k_enterUrl(const QString&))
511 Q_PRIVATE_SLOT(d, void _k_locationAccepted(const QString&))
512 Q_PRIVATE_SLOT(d, void _k_slotFilterChanged())
513 Q_PRIVATE_SLOT(d, void _k_fileHighlighted(const KFileItem&))
514 Q_PRIVATE_SLOT(d, void _k_fileSelected(const KFileItem&))
515 Q_PRIVATE_SLOT(d, void _k_slotLoadingFinished())
516 Q_PRIVATE_SLOT(d, void _k_fileCompletion(const QString&))
517 Q_PRIVATE_SLOT(d, void _k_toggleSpeedbar(bool))
518 Q_PRIVATE_SLOT(d, void _k_toggleBookmarks(bool))
519 Q_PRIVATE_SLOT(d, void _k_slotAutoSelectExtClicked())
520 Q_PRIVATE_SLOT(d, void _k_placesViewSplitterMoved(int, int))
521 Q_PRIVATE_SLOT(d, void _k_activateUrlNavigator())
522 Q_PRIVATE_SLOT(d, void _k_zoomOutIconsSize())
523 Q_PRIVATE_SLOT(d, void _k_zoomInIconsSize())
524 Q_PRIVATE_SLOT(d, void _k_slotIconSizeSliderMoved(int))
525 Q_PRIVATE_SLOT(d, void _k_slotIconSizeChanged(int))
526};
527
528#endif /* KABSTRACTFILEWIDGET_H */
529
530