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 | |
28 | class KPreviewWidgetBase; |
29 | |
30 | #include "kurl.h" |
31 | #include "kfile.h" |
32 | #include <kmimetype.h> |
33 | |
34 | class KPushButton; |
35 | class KActionCollection; |
36 | class KToolBar; |
37 | class KFileWidgetPrivate; |
38 | class KUrlComboBox; |
39 | class 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 | */ |
57 | class KIO_EXPORT KAbstractFileWidget |
58 | { |
59 | public: |
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 | |
398 | Q_DECLARE_INTERFACE(KAbstractFileWidget, "org.kde.KAbstractFileWidget" ) |
399 | |
400 | #endif /* KABSTRACTFILEWIDGET_H */ |
401 | |
402 | |