1/* This file is part of the KDE project
2 Copyright (C) 1998, 1999 Torben Weis <weis@kde.org>
3 Copyright (c) 1999, 2000 Preston Brown <pbrown@kde.org>
4 Copyright (c) 2000 Simon Hausmann <hausmann@kde.org>
5 Copyright (c) 2000 David Faure <faure@kde.org>
6
7 This library is free software; you can redistribute it and/or
8 modify it under the terms of the GNU Library General Public
9 License as published by the Free Software Foundation; either
10 version 2 of the License, or (at your option) any later version.
11
12 This library is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 Library General Public License for more details.
16
17 You should have received a copy of the GNU Library General Public License
18 along with this library; see the file COPYING.LIB. If not, write to
19 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
20 Boston, MA 02110-1301, USA.
21*/
22
23
24#ifndef KPROPERTIESDIALOG_H
25#define KPROPERTIESDIALOG_H
26
27#include <QtCore/QString>
28
29#include <kdemacros.h>
30#include <kurl.h>
31#include <kfileitem.h>
32#include <kpagedialog.h>
33
34class KPropertiesDialogPlugin;
35
36class KJob;
37namespace KIO { class Job; }
38
39/**
40 * The main properties dialog class.
41 * A Properties Dialog is a dialog which displays various information
42 * about a particular file or URL, or several files or URLs.
43 * This main class holds various related classes, which are instantiated in
44 * the form of tab entries in the tabbed dialog that this class provides.
45 * The various tabs themselves will let the user view, and sometimes change,
46 * information about the file or URL.
47 *
48 * \image html kpropertiesdialog.png "Typical KProperties Dialog"
49 *
50 * The best way to display the properties dialog is to use showDialog().
51 * Otherwise, you should use (void)new KPropertiesDialog(...)
52 * It will take care of deleting itself when closed.
53 *
54 * If you are looking for more flexibility, see KFileMetaInfo and
55 * KFileMetaInfoWidget.
56 */
57class KIO_EXPORT KPropertiesDialog : public KPageDialog
58{
59 Q_OBJECT
60
61public:
62
63 /**
64 * Determine whether there are any property pages available for the
65 * given file items.
66 * @param _items the list of items to check.
67 * @return true if there are any property pages, otherwise false.
68 */
69 static bool canDisplay( const KFileItemList& _items );
70
71 /**
72 * Brings up a Properties dialog, as shown above.
73 * This is the normal constructor for
74 * file-manager type applications, where you have a KFileItem instance
75 * to work with. Normally you will use this
76 * method rather than the one below.
77 *
78 * @param item file item whose properties should be displayed.
79 * @param parent is the parent of the dialog widget.
80 * @param name is the internal name.
81 */
82 explicit KPropertiesDialog( const KFileItem& item,
83 QWidget* parent = 0 );
84
85 /**
86 * \overload
87 *
88 * You use this constructor for cases where you have a number of items,
89 * rather than a single item. Be careful which methods you use
90 * when passing a list of files or URLs, since some of them will only
91 * work on the first item in a list.
92 *
93 * @param _items list of file items whose properties should be displayed.
94 * @param parent is the parent of the dialog widget.
95 * @param name is the internal name.
96 */
97 explicit KPropertiesDialog( const KFileItemList& _items,
98 QWidget *parent = 0 );
99
100 /**
101 * Brings up a Properties dialog. Convenience constructor for
102 * non-file-manager applications, where you have a KUrl rather than a
103 * KFileItem or KFileItemList.
104 *
105 * @param _url the URL whose properties should be displayed
106 * @param parent is the parent of the dialog widget.
107 * @param name is the internal name.
108 *
109 * IMPORTANT: This constructor, together with exec(), leads to a grave
110 * display bug (due to KIO::stat() being run before the dialog has all the
111 * necessary information). Do not use this combination for now.
112 * TODO: Check if the above is still true with Qt4.
113 * For local files with a known mimetype, simply create a KFileItem and pass
114 * it to the other constructor.
115 */
116 explicit KPropertiesDialog( const KUrl& _url,
117 QWidget* parent = 0 );
118
119 /**
120 * Creates a properties dialog for a new .desktop file (whose name
121 * is not known yet), based on a template. Special constructor for
122 * "File / New" in file-manager type applications.
123 *
124 * @param _tempUrl template used for reading only
125 * @param _currentDir directory where the file will be written to
126 * @param _defaultName something to put in the name field,
127 * like mimetype.desktop
128 * @param parent is the parent of the dialog widget.
129 * @param name is the internal name.
130 */
131 KPropertiesDialog( const KUrl& _tempUrl, const KUrl& _currentDir,
132 const QString& _defaultName,
133 QWidget* parent = 0 );
134
135 /**
136 * Creates an empty properties dialog (for applications that want use
137 * a standard dialog, but for things not doable via the plugin-mechanism).
138 *
139 * @param title is the string display as the "filename" in the caption of the dialog.
140 * @param parent is the parent of the dialog widget.
141 * @param name is the internal name.
142 * @param modal tells the dialog whether it should be modal.
143 */
144 explicit KPropertiesDialog(const QString& title,
145 QWidget* parent = 0);
146
147 /**
148 * Cleans up the properties dialog and frees any associated resources,
149 * including the dialog itself. Note that when a properties dialog is
150 * closed it cleans up and deletes itself.
151 */
152 virtual ~KPropertiesDialog();
153
154 /**
155 * Immediately displays a Properties dialog using constructor with
156 * the same parameters.
157 * On MS Windows, if @p item points to a local file, native (non modal) property
158 * dialog is displayed (@p parent and @p modal are ignored in this case).
159 *
160 * @return true on successful dialog displaying (can be false on win32).
161 */
162 static bool showDialog(const KFileItem& item, QWidget* parent = 0,
163 bool modal = true);
164
165 /**
166 * Immediately displays a Properties dialog using constructor with
167 * the same parameters.
168 * On MS Windows, if @p _url points to a local file, native (non modal) property
169 * dialog is displayed (@p parent and @p modal are ignored in this case).
170 *
171 * @return true on successful dialog displaying (can be false on win32).
172 */
173 static bool showDialog(const KUrl& _url, QWidget* parent = 0,
174 bool modal = true);
175
176 /**
177 * Immediately displays a Properties dialog using constructor with
178 * the same parameters.
179 * On MS Windows, if @p _items has one element and this element points
180 * to a local file, native (non modal) property dialog is displayed
181 * (@p parent and @p modal are ignored in this case).
182 *
183 * @return true on successful dialog displaying (can be false on win32).
184 */
185 static bool showDialog(const KFileItemList& _items, QWidget* parent = 0,
186 bool modal = true);
187
188 /**
189 * Adds a "3rd party" properties plugin to the dialog. Useful
190 * for extending the properties mechanism.
191 *
192 * To create a new plugin type, inherit from the base class KPropertiesDialogPlugin
193 * and implement all the methods. If you define a service .desktop file
194 * for your plugin, you do not need to call insertPlugin().
195 *
196 * @param plugin is a pointer to the KPropertiesDialogPlugin. The Properties
197 * dialog will do destruction for you. The KPropertiesDialogPlugin \b must
198 * have been created with the KPropertiesDialog as its parent.
199 * @see KPropertiesDialogPlugin
200 */
201 void insertPlugin (KPropertiesDialogPlugin *plugin);
202
203 /**
204 * The URL of the file that has its properties being displayed.
205 * This is only valid if the KPropertiesDialog was created/shown
206 * for one file or URL.
207 *
208 * @return a parsed URL.
209 */
210 KUrl kurl() const;
211
212 /**
213 * @return the file item for which the dialog is shown
214 *
215 * Warning: this method returns the first item of the list.
216 * This means that you should use this only if you are sure the dialog is used
217 * for a single item. Otherwise, you probably want items() instead.
218 */
219 KFileItem& item();
220
221 /**
222 * @return the items for which the dialog is shown
223 */
224 KFileItemList items() const;
225
226 /**
227 * If the dialog is being built from a template, this method
228 * returns the current directory. If no template, it returns QString().
229 * See the template form of the constructor.
230 *
231 * @return the current directory or QString()
232 */
233 KUrl currentDir() const;
234
235 /**
236 * If the dialog is being built from a template, this method
237 * returns the default name. If no template, it returns QString().
238 * See the template form of the constructor.
239 * @return the default name or QString()
240 */
241 QString defaultName() const;
242
243 /**
244 * Updates the item URL (either called by rename or because
245 * a global apps/mimelnk desktop file is being saved)
246 * Can only be called if the dialog applies to a single file or URL.
247 * @param _newUrl the new URL
248 */
249 void updateUrl( const KUrl& _newUrl );
250
251 /**
252 * Renames the item to the specified name. This can only be called if
253 * the dialog applies to a single file or URL.
254 * @param _name new filename, encoded.
255 * \see FilePropsDialogPlugin::applyChanges
256 */
257 void rename( const QString& _name );
258
259 /**
260 * To abort applying changes.
261 */
262 void abortApplying();
263
264 /**
265 * Shows the page that was previously set by
266 * setFileSharingPage(), or does nothing if no page
267 * was set yet.
268 * \see setFileSharingPage
269 */
270 void showFileSharingPage();
271
272 /**
273 * Sets the file sharing page.
274 * This page is shown when calling showFileSharingPage().
275 *
276 * @param page the page to set
277 * \see showFileSharingPage
278 */
279 void setFileSharingPage(QWidget* page);
280
281 /**
282 * Call this to make the filename lineedit readonly, to prevent the user
283 * from renaming the file.
284 * \param ro true if the lineedit should be read only
285 */
286 void setFileNameReadOnly( bool ro );
287
288public Q_SLOTS:
289 /**
290 * Called when the user presses 'Ok'.
291 */
292 virtual void slotOk(); // Deletes the PropertiesDialog instance
293 /**
294 * Called when the user presses 'Cancel'.
295 */
296 virtual void slotCancel(); // Deletes the PropertiesDialog instance
297
298Q_SIGNALS:
299 /**
300 * This signal is emitted when the Properties Dialog is closed (for
301 * example, with OK or Cancel buttons)
302 */
303 void propertiesClosed();
304
305 /**
306 * This signal is emitted when the properties changes are applied (for
307 * example, with the OK button)
308 */
309 void applied();
310
311 /**
312 * This signal is emitted when the properties changes are aborted (for
313 * example, with the Cancel button)
314 */
315
316 void canceled();
317 /**
318 * Emitted before changes to @p oldUrl are saved as @p newUrl.
319 * The receiver may change @p newUrl to point to an alternative
320 * save location.
321 */
322 void saveAs(const KUrl &oldUrl, KUrl &newUrl);
323
324Q_SIGNALS:
325 void leaveModality();
326private:
327 class KPropertiesDialogPrivate;
328 KPropertiesDialogPrivate* const d;
329
330 Q_DISABLE_COPY(KPropertiesDialog)
331};
332
333/**
334 * A Plugin in the Properties dialog
335 * This is an abstract class. You must inherit from this class
336 * to build a new kind of tabbed page for the KPropertiesDialog.
337 * A plugin in itself is just a library containing code, not a dialog's page.
338 * It's up to the plugin to insert pages into the parent dialog.
339 *
340 * To make a plugin available, define a service that implements the KPropertiesDialog/Plugin
341 * servicetype, as well as the mimetypes for which the plugin should be created.
342 * For instance, ServiceTypes=KPropertiesDialog/Plugin,text/html,application/x-mymimetype.
343 *
344 * You can also include X-KDE-Protocol=file if you want that plugin
345 * to be loaded only for local files, for instance.
346 */
347class KIO_EXPORT KPropertiesDialogPlugin : public QObject
348{
349 Q_OBJECT
350public:
351 /**
352 * Constructor
353 * To insert tabs into the properties dialog, use the add methods provided by
354 * KPageDialog (the properties dialog is a KPageDialog).
355 */
356 KPropertiesDialogPlugin( KPropertiesDialog *_props );
357 virtual ~KPropertiesDialogPlugin();
358
359 /**
360 * Applies all changes to the file.
361 * This function is called when the user presses 'Ok'. The last plugin inserted
362 * is called first.
363 */
364 virtual void applyChanges();
365
366 /**
367 * Convenience method for most ::supports methods
368 * @return true if the file is a local, regular, readable, desktop file
369 * @deprecated use KFileItem::isDesktopFile
370 */
371#ifndef KDE_NO_DEPRECATED
372 static KDE_DEPRECATED bool isDesktopFile( const KFileItem& _item );
373#endif
374
375 void setDirty( bool b );
376 bool isDirty() const;
377
378public Q_SLOTS:
379 void setDirty(); // same as setDirty( true ). TODO KDE5: void setDirty(bool dirty=true);
380
381Q_SIGNALS:
382 /**
383 * Emit this signal when the user changed anything in the plugin's tabs.
384 * The hosting PropertiesDialog will call applyChanges only if the
385 * PropsPlugin has emitted this signal or if you have called setDirty() before.
386 */
387 void changed();
388
389protected:
390 /**
391 * Pointer to the dialog
392 */
393 KPropertiesDialog *properties;
394
395 /**
396 * Returns the font height.
397 */
398 int fontHeight() const;
399
400private:
401 class KPropertiesDialogPluginPrivate;
402 KPropertiesDialogPluginPrivate* const d;
403};
404
405
406#endif
407
408