KIO

kpropertiesdialog.h
1 /*
2  This file is part of the KDE project
3  SPDX-FileCopyrightText: 1998, 1999 Torben Weis <[email protected]>
4  SPDX-FileCopyrightText: 1999, 2000 Preston Brown <[email protected]>
5  SPDX-FileCopyrightText: 2000 Simon Hausmann <[email protected]>
6  SPDX-FileCopyrightText: 2000 David Faure <[email protected]>
7 
8  SPDX-License-Identifier: LGPL-2.0-or-later
9 */
10 
11 #ifndef KPROPERTIESDIALOG_H
12 #define KPROPERTIESDIALOG_H
13 
14 #include <QString>
15 #include <QUrl>
16 
17 #include "kiowidgets_export.h"
18 #include <KPageDialog>
19 #include <kfileitem.h>
20 
21 #include <memory>
22 
23 class KPropertiesDialogPrivate;
25 
26 class KJob;
27 namespace KIO
28 {
29 class Job;
30 }
31 
32 /**
33  * @class KPropertiesDialog kpropertiesdialog.h <KPropertiesDialog>
34  *
35  * The main properties dialog class.
36  * A Properties Dialog is a dialog which displays various information
37  * about a particular file or URL, or several files or URLs.
38  * This main class holds various related classes, which are instantiated in
39  * the form of tab entries in the tabbed dialog that this class provides.
40  * The various tabs themselves will let the user view, and sometimes change,
41  * information about the file or URL.
42  *
43  * \image html kpropertiesdialog.png "Example of KPropertiesDialog"
44  *
45  * The best way to display the properties dialog is to use showDialog().
46  * Otherwise, you should use (void)new KPropertiesDialog(...)
47  * It will take care of deleting itself when closed.
48  *
49  * If you are looking for more flexibility, see KFileMetaInfo and
50  * KFileMetaInfoWidget.
51  *
52  * This respects the "editfiletype", "run_desktop_files" and "shell_access"
53  * Kiosk action restrictions (see KAuthorized::authorize()).
54  */
55 class KIOWIDGETS_EXPORT KPropertiesDialog : public KPageDialog
56 {
57  Q_OBJECT
58 
59 public:
60  /**
61  * Determine whether there are any property pages available for the
62  * given file items.
63  * @param _items the list of items to check.
64  * @return true if there are any property pages, otherwise false.
65  */
66  static bool canDisplay(const KFileItemList &_items);
67 
68  /**
69  * Brings up a Properties dialog, as shown above.
70  * This is the normal constructor for
71  * file-manager type applications, where you have a KFileItem instance
72  * to work with. Normally you will use this
73  * method rather than the one below.
74  *
75  * @param item file item whose properties should be displayed.
76  * @param parent is the parent of the dialog widget.
77  */
78  explicit KPropertiesDialog(const KFileItem &item, QWidget *parent = nullptr);
79 
80  /**
81  * \overload
82  *
83  * You use this constructor for cases where you have a number of items,
84  * rather than a single item. Be careful which methods you use
85  * when passing a list of files or URLs, since some of them will only
86  * work on the first item in a list.
87  *
88  * @param _items list of file items whose properties should be displayed.
89  * @param parent is the parent of the dialog widget.
90  */
91  explicit KPropertiesDialog(const KFileItemList &_items, QWidget *parent = nullptr);
92 
93  /**
94  * Brings up a Properties dialog. Convenience constructor for
95  * non-file-manager applications, where you have a QUrl rather than a
96  * KFileItem or KFileItemList.
97  *
98  * @param url the URL whose properties should be displayed
99  * @param parent is the parent of the dialog widget.
100  *
101  * For local files with a known MIME type, simply create a KFileItem
102  * and pass it to the other constructor.
103  */
104  explicit KPropertiesDialog(const QUrl &url, QWidget *parent = nullptr);
105 
106  /**
107  * Brings up a Properties dialog. Convenience constructor for
108  * non-file-manager applications, where you have a list of QUrls rather
109  * than a KFileItemList.
110  *
111  * @param urls list of URLs whose properties should be displayed (must
112  * contain at least one non-empty URL)
113  * @param parent is the parent of the dialog widget.
114  *
115  * For local files with a known MIME type, simply create a KFileItemList
116  * and pass it to the other constructor.
117  *
118  * @since 5.10
119  */
120  explicit KPropertiesDialog(const QList<QUrl> &urls, QWidget *parent = nullptr);
121 
122  /**
123  * Creates a properties dialog for a new .desktop file (whose name
124  * is not known yet), based on a template. Special constructor for
125  * "File / New" in file-manager type applications.
126  *
127  * @param _tempUrl template used for reading only
128  * @param _currentDir directory where the file will be written to
129  * @param _defaultName something to put in the name field,
130  * like mimetype.desktop
131  * @param parent is the parent of the dialog widget.
132  */
133  KPropertiesDialog(const QUrl &_tempUrl, const QUrl &_currentDir, const QString &_defaultName, QWidget *parent = nullptr);
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  */
142  explicit KPropertiesDialog(const QString &title, QWidget *parent = nullptr);
143 
144  /**
145  * Cleans up the properties dialog and frees any associated resources,
146  * including the dialog itself. Note that when a properties dialog is
147  * closed it cleans up and deletes itself.
148  */
149  virtual ~KPropertiesDialog();
150 
151  /**
152  * Immediately displays a Properties dialog using constructor with
153  * the same parameters.
154  * On MS Windows, if @p item points to a local file, native (non modal) property
155  * dialog is displayed (@p parent and @p modal are ignored in this case).
156  *
157  * @return true on successful dialog displaying (can be false on win32).
158  */
159  static bool showDialog(const KFileItem &item, QWidget *parent = nullptr, bool modal = true);
160 
161  /**
162  * Immediately displays a Properties dialog using constructor with
163  * the same parameters.
164  * On MS Windows, if @p _url points to a local file, native (non modal) property
165  * dialog is displayed (@p parent and @p modal are ignored in this case).
166  *
167  * @return true on successful dialog displaying (can be false on win32).
168  */
169  static bool showDialog(const QUrl &_url, QWidget *parent = nullptr, bool modal = true);
170 
171  /**
172  * Immediately displays a Properties dialog using constructor with
173  * the same parameters.
174  * On MS Windows, if @p _items has one element and this element points
175  * to a local file, native (non modal) property dialog is displayed
176  * (@p parent and @p modal are ignored in this case).
177  *
178  * @return true on successful dialog displaying (can be false on win32).
179  */
180  static bool showDialog(const KFileItemList &_items, QWidget *parent = nullptr, bool modal = true);
181 
182  /**
183  * Immediately displays a Properties dialog using constructor with
184  * the same parameters.
185  *
186  * On MS Windows, if @p _urls has one element and this element points
187  * to a local file, native (non modal) property dialog is displayed
188  * (@p parent and @p modal are ignored in this case).
189  *
190  * @param urls list of URLs whose properties should be displayed (must
191  * contain at least one non-empty URL)
192  * @param parent is the parent of the dialog widget.
193  * @param modal tells the dialog whether it should be modal.
194  *
195  * @return true on successful dialog displaying (can be false on win32).
196  *
197  * @since 5.10
198  */
199  static bool showDialog(const QList<QUrl> &urls, QWidget *parent = nullptr, bool modal = true);
200 
201  /**
202  * Adds a "3rd party" properties plugin to the dialog. Useful
203  * for extending the properties mechanism.
204  *
205  * To create a new plugin type, inherit from the base class KPropertiesDialogPlugin
206  * and implement all the methods. If you define a service .desktop file
207  * for your plugin, you do not need to call insertPlugin().
208  *
209  * @param plugin is a pointer to the KPropertiesDialogPlugin. The Properties
210  * dialog will do destruction for you. The KPropertiesDialogPlugin \b must
211  * have been created with the KPropertiesDialog as its parent.
212  * @see KPropertiesDialogPlugin
213  */
214  void insertPlugin(KPropertiesDialogPlugin *plugin);
215 
216 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 0)
217  /**
218  * @deprecated since 5.0, use url()
219  */
220  KIOWIDGETS_DEPRECATED_VERSION(5, 0, "Use KPropertiesDialog::url()")
221  QUrl kurl() const
222  {
223  return url();
224  }
225 #endif
226 
227  /**
228  * The URL of the file that has its properties being displayed.
229  * This is only valid if the KPropertiesDialog was created/shown
230  * for one file or URL.
231  *
232  * @return the single URL.
233  */
234  QUrl url() const;
235 
236  /**
237  * @return the file item for which the dialog is shown
238  *
239  * Warning: this method returns the first item of the list.
240  * This means that you should use this only if you are sure the dialog is used
241  * for a single item. Otherwise, you probably want items() instead.
242  */
243  KFileItem &item();
244 
245  /**
246  * @return the items for which the dialog is shown
247  */
248  KFileItemList items() const;
249 
250  /**
251  * If the dialog is being built from a template, this method
252  * returns the current directory. If no template, it returns QString().
253  * See the template form of the constructor.
254  *
255  * @return the current directory or QString()
256  */
257  QUrl currentDir() const;
258 
259  /**
260  * If the dialog is being built from a template, this method
261  * returns the default name. If no template, it returns QString().
262  * See the template form of the constructor.
263  * @return the default name or QString()
264  */
265  QString defaultName() const;
266 
267  /**
268  * Updates the item URL (either called by rename or because
269  * a global apps/mimelnk desktop file is being saved)
270  * Can only be called if the dialog applies to a single file or URL.
271  * @param newUrl the new URL
272  */
273  void updateUrl(const QUrl &newUrl);
274 
275  /**
276  * Renames the item to the specified name. This can only be called if
277  * the dialog applies to a single file or URL.
278  * @param _name new filename, encoded.
279  * \see FilePropsDialogPlugin::applyChanges
280  */
281  void rename(const QString &_name);
282 
283  /**
284  * To abort applying changes.
285  */
286  void abortApplying();
287 
288  /**
289  * Shows the page that was previously set by
290  * setFileSharingPage(), or does nothing if no page
291  * was set yet.
292  * \see setFileSharingPage
293  */
294  void showFileSharingPage();
295 
296  /**
297  * Sets the file sharing page.
298  * This page is shown when calling showFileSharingPage().
299  *
300  * @param page the page to set
301  *
302  * \note This should only be called by KPropertiesDialog plugins.
303  * \see showFileSharingPage
304  */
305  void setFileSharingPage(QWidget *page);
306 
307  /**
308  * Call this to make the filename lineedit readonly, to prevent the user
309  * from renaming the file.
310  * \param ro true if the lineedit should be read only
311  */
312  void setFileNameReadOnly(bool ro);
313 
315 
316 public Q_SLOTS:
317  /**
318  * Called when the user presses 'Ok'.
319  * @deprecated since 5.25, use accept()
320  */
321  KIOWIDGETS_DEPRECATED_VERSION(5, 25, "Use KPropertiesDialog::accept()")
322  virtual void slotOk();
323  /**
324  * Called when the user presses 'Cancel'.
325  * @deprecated since 5.25, use reject()
326  */
327  KIOWIDGETS_DEPRECATED_VERSION(5, 25, "Use KPropertiesDialog::reject()")
328  virtual void slotCancel();
329 
330  /**
331  * Called when the user presses 'Ok'.
332  * @since 5.25
333  */
334  void accept() override;
335  /**
336  * Called when the user presses 'Cancel' or Esc.
337  * @since 5.25
338  */
339  void reject() override;
340 
341 Q_SIGNALS:
342  /**
343  * This signal is emitted when the Properties Dialog is closed (for
344  * example, with OK or Cancel buttons)
345  */
346  void propertiesClosed();
347 
348  /**
349  * This signal is emitted when the properties changes are applied (for
350  * example, with the OK button)
351  */
352  void applied();
353 
354  /**
355  * This signal is emitted when the properties changes are aborted (for
356  * example, with the Cancel button)
357  */
358 
359  void canceled();
360  /**
361  * Emitted before changes to @p oldUrl are saved as @p newUrl.
362  * The receiver may change @p newUrl to point to an alternative
363  * save location.
364  */
365  void saveAs(const QUrl &oldUrl, QUrl &newUrl);
366 
367 Q_SIGNALS:
368  // TODO KF6: remove this, not used anymore
369  void leaveModality();
370 
371 private:
372  std::unique_ptr<KPropertiesDialogPrivate> d;
373 
374  Q_DISABLE_COPY(KPropertiesDialog)
375 };
376 
377 class KPropertiesDialogPluginPrivate;
378 /**
379  * A Plugin in the Properties dialog
380  * This is an abstract class. You must inherit from this class
381  * to build a new kind of tabbed page for the KPropertiesDialog.
382  * A plugin in itself is just a library containing code, not a dialog's page.
383  * It's up to the plugin to insert pages into the parent dialog.
384  *
385  * To make a plugin available, define a service that implements the KPropertiesDialog/Plugin
386  * servicetype, as well as the MIME types for which the plugin should be created.
387  * For instance, X-KDE-ServiceTypes=KPropertiesDialog/Plugin,text/html,application/x-mymimetype.
388  *
389  * You can also include X-KDE-Protocol=file if you want that plugin
390  * to be loaded only for local files, for instance.
391  */
392 class KIOWIDGETS_EXPORT KPropertiesDialogPlugin : public QObject
393 {
394  Q_OBJECT
395 public:
396  /**
397  * Constructor
398  * To insert tabs into the properties dialog, use the add methods provided by
399  * KPageDialog (the properties dialog is a KPageDialog).
400  */
402  virtual ~KPropertiesDialogPlugin();
403 
404  /**
405  * Applies all changes to the file.
406  * This function is called when the user presses 'Ok'. The last plugin inserted
407  * is called first.
408  */
409  virtual void applyChanges();
410 
411 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(4, 1)
412  /**
413  * Convenience method for most ::supports methods
414  * @return true if the file is a local, regular, readable, desktop file
415  * @deprecated Since 4.1, use KFileItem::isDesktopFile
416  */
417  KIOWIDGETS_DEPRECATED_VERSION(4, 1, "Use KFileItem::isDesktopFile()")
418  static bool isDesktopFile(const KFileItem &_item);
419 #endif
420 
421  void setDirty(bool b);
422  bool isDirty() const;
423 
424 public Q_SLOTS:
425  void setDirty(); // same as setDirty( true ). TODO KDE5: void setDirty(bool dirty=true);
426 
427 Q_SIGNALS:
428  /**
429  * Emit this signal when the user changed anything in the plugin's tabs.
430  * The hosting PropertiesDialog will call applyChanges only if the
431  * PropsPlugin has emitted this signal or if you have called setDirty() before.
432  */
433  void changed();
434 
435 protected:
436  /**
437  * Pointer to the dialog
438  */
440 
441  /**
442  * Returns the font height.
443  */
444  int fontHeight() const;
445 
446 private:
447  std::unique_ptr<KPropertiesDialogPluginPrivate> d;
448 };
449 
450 #endif
A namespace for KIO globals.
KPropertiesDialog * properties
Pointer to the dialog.
QDialogButtonBox * buttonBox()
A Plugin in the Properties dialog This is an abstract class.
KIOCORE_EXPORT SimpleJob * rename(const QUrl &src, const QUrl &dest, JobFlags flags=DefaultFlags)
Rename a file or directory.
Definition: simplejob.cpp:369
List of KFileItems, which adds a few helper methods to QList<KFileItem>.
Definition: kfileitem.h:601
The main properties dialog class.
A KFileItem is a generic class to handle a file, local or remote.
Definition: kfileitem.h:35
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Fri Jul 30 2021 23:01:20 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.