1/*
2 This file is part of the KDE project
3 SPDX-FileCopyrightText: 1998, 1999 Torben Weis <weis@kde.org>
4 SPDX-FileCopyrightText: 1999, 2000 Preston Brown <pbrown@kde.org>
5 SPDX-FileCopyrightText: 2000 Simon Hausmann <hausmann@kde.org>
6 SPDX-FileCopyrightText: 2000 David Faure <faure@kde.org>
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 <kfileitem.h>
19
20#include <KPageDialog>
21
22#include <memory>
23
24class KPropertiesDialogPrivate;
25
26/**
27 * @class KPropertiesDialog kpropertiesdialog.h <KPropertiesDialog>
28 *
29 * The main properties dialog class.
30 * A Properties Dialog is a dialog which displays various information
31 * about a particular file or URL, or several files or URLs.
32 * This main class holds various related classes, which are instantiated in
33 * the form of tab entries in the tabbed dialog that this class provides.
34 * The various tabs themselves will let the user view, and sometimes change,
35 * information about the file or URL.
36 *
37 * \image html kpropertiesdialog.png "Example of KPropertiesDialog"
38 *
39 * The best way to display the properties dialog is to use showDialog().
40 * Otherwise, you should use (void)new KPropertiesDialog(...)
41 * It will take care of deleting itself when closed.
42 *
43 * If you are looking for more flexibility, see KFileMetaInfo and
44 * KFileMetaInfoWidget.
45 *
46 * This respects the "editfiletype", "run_desktop_files" and "shell_access"
47 * Kiosk action restrictions (see KAuthorized::authorize()).
48 */
49class KIOWIDGETS_EXPORT KPropertiesDialog : public KPageDialog
50{
51 Q_OBJECT
52
53public:
54 /**
55 * Determine whether there are any property pages available for the
56 * given file items.
57 * @param _items the list of items to check.
58 * @return true if there are any property pages, otherwise false.
59 */
60 static bool canDisplay(const KFileItemList &_items);
61
62 /**
63 * Brings up a Properties dialog, as shown above.
64 * This is the normal constructor for
65 * file-manager type applications, where you have a KFileItem instance
66 * to work with. Normally you will use this
67 * method rather than the one below.
68 *
69 * @param item file item whose properties should be displayed.
70 * @param parent is the parent of the dialog widget.
71 */
72 explicit KPropertiesDialog(const KFileItem &item, QWidget *parent = nullptr);
73
74 /**
75 * \overload
76 *
77 * You use this constructor for cases where you have a number of items,
78 * rather than a single item. Be careful which methods you use
79 * when passing a list of files or URLs, since some of them will only
80 * work on the first item in a list.
81 *
82 * @param _items list of file items whose properties should be displayed.
83 * @param parent is the parent of the dialog widget.
84 */
85 explicit KPropertiesDialog(const KFileItemList &_items, QWidget *parent = nullptr);
86
87 /**
88 * Brings up a Properties dialog. Convenience constructor for
89 * non-file-manager applications, where you have a QUrl rather than a
90 * KFileItem or KFileItemList.
91 *
92 * @param url the URL whose properties should be displayed
93 * @param parent is the parent of the dialog widget.
94 *
95 * For local files with a known MIME type, simply create a KFileItem
96 * and pass it to the other constructor.
97 */
98 explicit KPropertiesDialog(const QUrl &url, QWidget *parent = nullptr);
99
100 /**
101 * Brings up a Properties dialog. Convenience constructor for
102 * non-file-manager applications, where you have a list of QUrls rather
103 * than a KFileItemList.
104 *
105 * @param urls list of URLs whose properties should be displayed (must
106 * contain at least one non-empty URL)
107 * @param parent is the parent of the dialog widget.
108 *
109 * For local files with a known MIME type, simply create a KFileItemList
110 * and pass it to the other constructor.
111 *
112 * @since 5.10
113 */
114 explicit KPropertiesDialog(const QList<QUrl> &urls, QWidget *parent = nullptr);
115
116 /**
117 * Creates a properties dialog for a new .desktop file (whose name
118 * is not known yet), based on a template. Special constructor for
119 * "File / New" in file-manager type applications.
120 *
121 * @param _tempUrl template used for reading only
122 * @param _currentDir directory where the file will be written to
123 * @param _defaultName something to put in the name field,
124 * like mimetype.desktop
125 * @param parent is the parent of the dialog widget.
126 */
127 KPropertiesDialog(const QUrl &_tempUrl, const QUrl &_currentDir, const QString &_defaultName, QWidget *parent = nullptr);
128
129 /**
130 * Creates an empty properties dialog (for applications that want use
131 * a standard dialog, but for things not doable via the plugin-mechanism).
132 *
133 * @param title is the string display as the "filename" in the title of the dialog.
134 * @param parent is the parent of the dialog widget.
135 */
136 explicit KPropertiesDialog(const QString &title, QWidget *parent = nullptr);
137
138 /**
139 * Cleans up the properties dialog and frees any associated resources,
140 * including the dialog itself. Note that when a properties dialog is
141 * closed it cleans up and deletes itself.
142 */
143 ~KPropertiesDialog() override;
144
145 /**
146 * Immediately displays a Properties dialog using constructor with
147 * the same parameters.
148 * On MS Windows, if @p item points to a local file, native (non modal) property
149 * dialog is displayed (@p parent and @p modal are ignored in this case).
150 *
151 * @return true on successful dialog displaying (can be false on win32).
152 */
153 static bool showDialog(const KFileItem &item, QWidget *parent = nullptr, bool modal = true);
154
155 /**
156 * Immediately displays a Properties dialog using constructor with
157 * the same parameters.
158 * On MS Windows, if @p _url points to a local file, native (non modal) property
159 * dialog is displayed (@p parent and @p modal are ignored in this case).
160 *
161 * @return true on successful dialog displaying (can be false on win32).
162 */
163 static bool showDialog(const QUrl &_url, QWidget *parent = nullptr, bool modal = true);
164
165 /**
166 * Immediately displays a Properties dialog using constructor with
167 * the same parameters.
168 * On MS Windows, if @p _items has one element and this element points
169 * to a local file, native (non modal) property dialog is displayed
170 * (@p parent and @p modal are ignored in this case).
171 *
172 * @return true on successful dialog displaying (can be false on win32).
173 */
174 static bool showDialog(const KFileItemList &_items, QWidget *parent = nullptr, bool modal = true);
175
176 /**
177 * Immediately displays a Properties dialog using constructor with
178 * the same parameters.
179 *
180 * On MS Windows, if @p _urls has one element and this element points
181 * to a local file, native (non modal) property dialog is displayed
182 * (@p parent and @p modal are ignored in this case).
183 *
184 * @param urls list of URLs whose properties should be displayed (must
185 * contain at least one non-empty URL)
186 * @param parent is the parent of the dialog widget.
187 * @param modal tells the dialog whether it should be modal.
188 *
189 * @return true on successful dialog displaying (can be false on win32).
190 *
191 * @since 5.10
192 */
193 static bool showDialog(const QList<QUrl> &urls, QWidget *parent = nullptr, bool modal = true);
194
195 /**
196 * The URL of the file that has its properties being displayed.
197 * This is only valid if the KPropertiesDialog was created/shown
198 * for one file or URL.
199 *
200 * @return the single URL.
201 */
202 QUrl url() const;
203
204 /**
205 * @return the file item for which the dialog is shown
206 *
207 * Warning: this method returns the first item of the list.
208 * This means that you should use this only if you are sure the dialog is used
209 * for a single item. Otherwise, you probably want items() instead.
210 */
211 KFileItem &item();
212
213 /**
214 * @return the items for which the dialog is shown
215 */
216 KFileItemList items() const;
217
218 /**
219 * If the dialog is being built from a template, this method
220 * returns the current directory. If no template, it returns QString().
221 * See the template form of the constructor.
222 *
223 * @return the current directory or QString()
224 */
225 QUrl currentDir() const;
226
227 /**
228 * If the dialog is being built from a template, this method
229 * returns the default name. If no template, it returns QString().
230 * See the template form of the constructor.
231 * @return the default name or QString()
232 */
233 QString defaultName() const;
234
235 /**
236 * Updates the item URL (either called by rename or because
237 * a global apps/mimelnk desktop file is being saved)
238 * Can only be called if the dialog applies to a single file or URL.
239 * @param newUrl the new URL
240 */
241 void updateUrl(const QUrl &newUrl);
242
243 /**
244 * Renames the item to the specified name. This can only be called if
245 * the dialog applies to a single file or URL.
246 * @param _name new filename, encoded.
247 * \see FilePropsDialogPlugin::applyChanges
248 */
249 void rename(const QString &_name);
250
251 /**
252 * To abort applying changes.
253 */
254 void abortApplying();
255
256 /**
257 * Shows the page that was previously set by
258 * setFileSharingPage(), or does nothing if no page
259 * was set yet.
260 * \see setFileSharingPage
261 */
262 void showFileSharingPage();
263
264 /**
265 * Sets the file sharing page.
266 * This page is shown when calling showFileSharingPage().
267 *
268 * @param page the page to set
269 *
270 * \note This should only be called by KPropertiesDialog plugins.
271 * \see showFileSharingPage
272 */
273 void setFileSharingPage(QWidget *page);
274
275 /**
276 * Call this to make the filename lineedit readonly, to prevent the user
277 * from renaming the file.
278 * \param ro true if the lineedit should be read only
279 */
280 void setFileNameReadOnly(bool ro);
281
282 using KPageDialog::buttonBox;
283
284public Q_SLOTS:
285 /**
286 * Called when the user presses 'Ok'.
287 * @since 5.25
288 */
289 void accept() override;
290 /**
291 * Called when the user presses 'Cancel' or Esc.
292 * @since 5.25
293 */
294 void reject() override;
295
296Q_SIGNALS:
297 /**
298 * This signal is emitted when the Properties Dialog is closed (for
299 * example, with OK or Cancel buttons)
300 */
301 void propertiesClosed();
302
303 /**
304 * This signal is emitted when the properties changes are applied (for
305 * example, with the OK button)
306 */
307 void applied();
308
309 /**
310 * This signal is emitted when the properties changes are aborted (for
311 * example, with the Cancel button)
312 */
313 void canceled();
314
315 /**
316 * Emitted before changes to @p oldUrl are saved as @p newUrl.
317 * The receiver may change @p newUrl to point to an alternative
318 * save location.
319 */
320 void saveAs(const QUrl &oldUrl, QUrl &newUrl);
321
322private:
323 std::unique_ptr<KPropertiesDialogPrivate> d;
324
325 Q_DISABLE_COPY(KPropertiesDialog)
326};
327
328#endif
329

source code of kio/src/widgets/kpropertiesdialog.h