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
10 This library is free software; you can redistribute it and/or
11 modify it under the terms of the GNU Library General Public
12 License as published by the Free Software Foundation; either
13 version 2 of the License, or (at your option) any later version.
14
15 This library is distributed in the hope that it will be useful,
16 but WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Library General Public License for more details.
19
20 You should have received a copy of the GNU Library General Public License
21 along with this library; see the file COPYING.LIB. If not, write to
22 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
23 Boston, MA 02110-1301, USA.
24*/
25#ifndef KABSTRACTFILEWIDGET_H
26#define KABSTRACTFILEWIDGET_H
27
28class KPreviewWidgetBase;
29
30#include "kurl.h"
31#include "kfile.h"
32#include <kmimetype.h>
33
34class KPushButton;
35class KActionCollection;
36class KToolBar;
37class KFileWidgetPrivate;
38class KUrlComboBox;
39class KFileFilterCombo;
40
41/**
42 * Base class for KFileWidget.
43 *
44 * This abstract interface allows KFileDialog (in kio) to call methods
45 * on the dlopened KFileWidget (from kfilemodule.so)
46 *
47 * In addition to the pure virtual methods defined below, the implementations
48 * of KAbstractFileWidget are expected to define the following signals:
49 * <ul>
50 * <li>fileSelected(const KUrl&)</li>
51 * <li>fileHighlighted(const KUrl&)</li>
52 * <li>selectionChanged()</li>
53 * <li>filterChanged(const QString&)</li>
54 * <li>accepted()</li>
55 * </ul>
56 */
57class KIO_EXPORT KAbstractFileWidget
58{
59public:
60 virtual ~KAbstractFileWidget() {}
61
62 /**
63 * Defines some default behavior of the filedialog.
64 * E.g. in mode @p Opening and @p Saving, the selected files/urls will
65 * be added to the "recent documents" list. The Saving mode also implies
66 * setKeepLocation() being set.
67 *
68 * @p Other means that no default actions are performed.
69 *
70 * @see setOperationMode
71 * @see operationMode
72 */
73 enum OperationMode { Other = 0, Opening, Saving };
74
75 /**
76 * @returns The selected fully qualified filename.
77 */
78 virtual KUrl selectedUrl() const = 0;
79
80 /**
81 * @returns The list of selected URLs.
82 */
83 virtual KUrl::List selectedUrls() const = 0;
84
85 /**
86 * @returns the currently shown directory.
87 */
88 virtual KUrl baseUrl() const = 0;
89
90 /**
91 * Returns the full path of the selected file in the local filesystem.
92 * (Local files only)
93 */
94 virtual QString selectedFile() const = 0;
95
96 /**
97 * Returns a list of all selected local files.
98 */
99 virtual QStringList selectedFiles() const = 0;
100
101 /**
102 * Sets the directory to view.
103 *
104 * @param url URL to show.
105 * @param clearforward Indicates whether the forward queue
106 * should be cleared.
107 */
108 virtual void setUrl(const KUrl &url, bool clearforward = true) = 0;
109
110 /**
111 * Sets the file name to preselect to @p name
112 *
113 * This takes absolute URLs and relative file names.
114 */
115 virtual void setSelection(const QString& name) = 0;
116
117 /**
118 * Sets the operational mode of the filedialog to @p Saving, @p Opening
119 * or @p Other. This will set some flags that are specific to loading
120 * or saving files. E.g. setKeepLocation() makes mostly sense for
121 * a save-as dialog. So setOperationMode( KFileDialog::Saving ); sets
122 * setKeepLocation for example.
123 *
124 * The mode @p Saving, together with a default filter set via
125 * setMimeFilter() will make the filter combobox read-only.
126 *
127 * The default mode is @p Opening.
128 *
129 * Call this method right after instantiating KFileDialog.
130 *
131 * @see operationMode
132 * @see KFileDialog::OperationMode
133 */
134 virtual void setOperationMode( OperationMode ) = 0;
135
136 /**
137 * @returns the current operation mode, Opening, Saving or Other. Default
138 * is Other.
139 *
140 * @see operationMode
141 * @see KFileDialog::OperationMode
142 */
143 virtual OperationMode operationMode() const = 0;
144
145 /**
146 * Sets whether the filename/url should be kept when changing directories.
147 * This is for example useful when having a predefined filename where
148 * the full path for that file is searched.
149 *
150 * This is implicitly set when operationMode() is KFileDialog::Saving
151 *
152 * getSaveFileName() and getSaveUrl() set this to true by default, so that
153 * you can type in the filename and change the directory without having
154 * to type the name again.
155 */
156 virtual void setKeepLocation( bool keep ) = 0;
157
158 /**
159 * @returns whether the contents of the location edit are kept when
160 * changing directories.
161 */
162 virtual bool keepsLocation() const = 0;
163
164 /**
165 * Sets the filter to be used to @p filter.
166 *
167 * You can set more
168 * filters for the user to select separated by '\n'. Every
169 * filter entry is defined through namefilter|text to display.
170 * If no | is found in the expression, just the namefilter is
171 * shown. Examples:
172 *
173 * \code
174 * kfile->setFilter("*.cpp|C++ Source Files\n*.h|Header files");
175 * kfile->setFilter("*.cpp");
176 * kfile->setFilter("*.cpp|Sources (*.cpp)");
177 * kfile->setFilter("*.cpp|" + i18n("Sources (*.cpp)"));
178 * kfile->setFilter("*.cpp *.cc *.C|C++ Source Files\n*.h *.H|Header files");
179 * \endcode
180 *
181 * Note: The text to display is not parsed in any way. So, if you
182 * want to show the suffix to select by a specific filter, you must
183 * repeat it.
184 *
185 * If the filter contains an unescaped '/', a mimetype-filter is assumed.
186 * If you would like a '/' visible in your filter it can be escaped with
187 * a '\'. You can specify multiple mimetypes like this (separated with
188 * space):
189 *
190 * \code
191 * kfile->setFilter( "image/png text/html text/plain" );
192 * kfile->setFilter( "*.cue|CUE\\/BIN Files (*.cue)" );
193 * \endcode
194 *
195 * @see filterChanged
196 * @see setMimeFilter
197 */
198 virtual void setFilter(const QString& filter) = 0;
199
200 /**
201 * Returns the current filter as entered by the user or one of the
202 * predefined set via setFilter().
203 *
204 * @see setFilter()
205 * @see filterChanged()
206 */
207 virtual QString currentFilter() const = 0;
208
209 /**
210 * Returns the mimetype for the desired output format.
211 *
212 * This is only valid if setFilterMimeType() has been called
213 * previously.
214 *
215 * @see setFilterMimeType()
216 */
217 virtual KMimeType::Ptr currentFilterMimeType() = 0;
218
219 /**
220 * Sets the filter up to specify the output type.
221 *
222 * @param types a list of mimetypes that can be used as output format
223 * @param defaultType the default mimetype to use as output format, if any.
224 * If @p defaultType is set, it will be set as the current item.
225 * Otherwise, a first item showing all the mimetypes will be created.
226 * Typically, @p defaultType should be empty for loading and set for saving.
227 *
228 * Do not use in conjunction with setFilter()
229 */
230 virtual void setMimeFilter( const QStringList& types,
231 const QString& defaultType = QString() ) = 0;
232
233 /**
234 * The mimetype for the desired output format.
235 *
236 * This is only valid if setMimeFilter() has been called
237 * previously.
238 *
239 * @see setMimeFilter()
240 */
241 virtual QString currentMimeFilter() const = 0;
242
243 /**
244 * Clears any mime- or namefilter. Does not reload the directory.
245 */
246 virtual void clearFilter() = 0;
247
248 /**
249 * Adds a preview widget and enters the preview mode.
250 *
251 * In this mode the dialog is split and the right part contains your
252 * preview widget.
253 *
254 * Ownership is transferred to KFileDialog. You need to create the
255 * preview-widget with "new", i.e. on the heap.
256 *
257 * @param w The widget to be used for the preview.
258 */
259 virtual void setPreviewWidget(KPreviewWidgetBase *w) = 0;
260
261 /**
262 * Sets the mode of the dialog.
263 *
264 * The mode is defined as (in kfile.h):
265 * \code
266 * enum Mode {
267 * File = 1,
268 * Directory = 2,
269 * Files = 4,
270 * ExistingOnly = 8,
271 * LocalOnly = 16
272 * };
273 * \endcode
274 * You can OR the values, e.g.
275 * \code
276 * KFile::Modes mode = KFile::Files |
277 * KFile::ExistingOnly |
278 * KFile::LocalOnly );
279 * setMode( mode );
280 * \endcode
281 */
282 virtual void setMode( KFile::Modes m ) = 0;
283
284 /**
285 * Returns the mode of the filedialog.
286 * @see setMode()
287 */
288 virtual KFile::Modes mode() const = 0;
289
290 /**
291 * Sets the text to be displayed in front of the selection.
292 *
293 * The default is "Location".
294 * Most useful if you want to make clear what
295 * the location is used for.
296 */
297 virtual void setLocationLabel(const QString& text) = 0;
298
299 /**
300 * Returns a pointer to the toolbar.
301 *
302 * You can use this to insert custom
303 * items into it, e.g.:
304 * \code
305 * yourAction = new KAction( i18n("Your Action"), 0,
306 * this, SLOT( yourSlot() ),
307 * this, "action name" );
308 * yourAction->plug( kfileDialog->toolBar() );
309 * \endcode
310 */
311 virtual KToolBar *toolBar() const = 0;
312
313 /**
314 * @returns a pointer to the OK-Button in the filedialog.
315 * Note that the button is hidden and unconnected when using KFileWidget alone;
316 * KFileDialog shows it and connects to it.
317 */
318 virtual KPushButton *okButton() const = 0;
319
320 /**
321 * @returns a pointer to the Cancel-Button in the filedialog.
322 * Note that the button is hidden and unconnected when using KFileWidget alone;
323 * KFileDialog shows it and connects to it.
324 */
325 virtual KPushButton *cancelButton() const = 0;
326
327 /**
328 * @returns the combobox used to type the filename or full location of the file.
329 */
330 virtual KUrlComboBox *locationEdit() const = 0;
331
332 /**
333 * @returns the combobox that contains the filters
334 */
335 virtual KFileFilterCombo *filterWidget() const = 0;
336
337 /**
338 * @returns a pointer to the action collection, holding all the used
339 * KActions.
340 */
341 virtual KActionCollection *actionCollection() const = 0;
342
343 /**
344 * Set a custom widget that should be added to the bottom of the file dialog.
345 * @param widget A widget, or a widget of widgets, for displaying custom
346 * data in the file widget. This can be used, for example, to
347 * display a check box with the caption "Open as read-only".
348 * When creating this widget, you don't need to specify a parent,
349 * since the widget's parent will be set automatically by KFileWidget.
350 */
351 virtual void setCustomWidget(QWidget* widget) = 0;
352
353 /**
354 * Sets a custom widget that should be added below the location and the filter
355 * editors.
356 * @param text Label of the custom widget, which is displayed below the labels
357 * "Location:" and "Filter:".
358 * @param widget Any kind of widget, but preferable a combo box or a line editor
359 * to be compliant with the location and filter layout.
360 * When creating this widget, you don't need to specify a parent,
361 * since the widget's parent will be set automatically by KFileWidget.
362 */
363 virtual void setCustomWidget(const QString& text, QWidget* widget) = 0;
364
365 /**
366 * Called when clicking ok (when this widget is used in KFileDialog)
367 * Might or might not call accept().
368 */
369 virtual void slotOk() = 0;
370 virtual void accept() = 0;
371 virtual void slotCancel() = 0;
372
373 /// @internal for future extensions
374 virtual void virtual_hook( int id, void* data ) = 0;
375
376 /**
377 * Sets whether the user should be asked for confirmation
378 * when an overwrite might occurr.
379 *
380 * @param enable Set this to true to enable checking.
381 * @since 4.2
382 */
383 void setConfirmOverwrite(bool enable){ // KDE5 TODO: make this virtual
384 virtual_hook(0, static_cast<void*>(&enable));
385 }
386
387 /**
388 * Forces the inline previews to be shown or hidden, depending on @p show.
389 *
390 * @param show Whether to show inline previews or not.
391 * @since 4.2
392 */
393 void setInlinePreviewShown(bool show) { // KDE5 TODO: make this virtual
394 virtual_hook(1, static_cast<void*>(&show));
395 }
396};
397
398Q_DECLARE_INTERFACE(KAbstractFileWidget, "org.kde.KAbstractFileWidget")
399
400#endif /* KABSTRACTFILEWIDGET_H */
401
402