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

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