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 | |
24 | class 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 | */ |
51 | class KIOWIDGETS_EXPORT KPropertiesDialog : public KPageDialog |
52 | { |
53 | Q_OBJECT |
54 | |
55 | public: |
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 | |
304 | public 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 | |
316 | Q_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 | |
343 | private: |
344 | std::unique_ptr<KPropertiesDialogPrivate> d; |
345 | |
346 | Q_DISABLE_COPY(KPropertiesDialog) |
347 | }; |
348 | |
349 | #endif |
350 | |