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 | |
34 | class KPropertiesDialogPlugin; |
35 | |
36 | class KJob; |
37 | namespace 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 | */ |
57 | class KIO_EXPORT KPropertiesDialog : public KPageDialog |
58 | { |
59 | Q_OBJECT |
60 | |
61 | public: |
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 | |
288 | public 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 | |
298 | Q_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 | |
324 | Q_SIGNALS: |
325 | void leaveModality(); |
326 | private: |
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 | */ |
347 | class KIO_EXPORT KPropertiesDialogPlugin : public QObject |
348 | { |
349 | Q_OBJECT |
350 | public: |
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 | |
378 | public Q_SLOTS: |
379 | void setDirty(); // same as setDirty( true ). TODO KDE5: void setDirty(bool dirty=true); |
380 | |
381 | Q_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 | |
389 | protected: |
390 | /** |
391 | * Pointer to the dialog |
392 | */ |
393 | KPropertiesDialog *properties; |
394 | |
395 | /** |
396 | * Returns the font height. |
397 | */ |
398 | int fontHeight() const; |
399 | |
400 | private: |
401 | class KPropertiesDialogPluginPrivate; |
402 | KPropertiesDialogPluginPrivate* const d; |
403 | }; |
404 | |
405 | |
406 | #endif |
407 | |
408 | |