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 | |
35 | class KJob; |
36 | class KFileItem; |
37 | class KDirOperator; |
38 | |
39 | class KFILE_EXPORT KFileWidget : public QWidget, public KAbstractFileWidget |
40 | { |
41 | Q_OBJECT |
42 | Q_INTERFACES(KAbstractFileWidget) |
43 | public: |
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:///<keyword> 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:///<keyword>/<filename> |
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:///<keyword>?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:///<keyword>/<filename>?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 | |
420 | public 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 | |
429 | protected: |
430 | virtual void resizeEvent(QResizeEvent* event); |
431 | virtual void showEvent(QShowEvent* event); |
432 | virtual bool eventFilter(QObject* watched, QEvent* event); |
433 | |
434 | Q_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 | |
489 | public: |
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 | |
503 | private: |
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 | |