KIO

kpropertiesdialog.h
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
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
297 /**
298 * This signal is emitted when the Properties Dialog is closed (for
299 * example, with OK or Cancel buttons)
300 */
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
326};
327
328#endif
List of KFileItems, which adds a few helper methods to QList<KFileItem>.
Definition kfileitem.h:630
A KFileItem is a generic class to handle a file, local or remote.
Definition kfileitem.h:36
QDialogButtonBox * buttonBox()
The main properties dialog class.
void applied()
This signal is emitted when the properties changes are applied (for example, with the OK button)
void saveAs(const QUrl &oldUrl, QUrl &newUrl)
Emitted before changes to oldUrl are saved as newUrl.
void propertiesClosed()
This signal is emitted when the Properties Dialog is closed (for example, with OK or Cancel buttons)
void canceled()
This signal is emitted when the properties changes are aborted (for example, with the Cancel button)
virtual void accept()
virtual void reject()
Q_DISABLE_COPY(Class)
Q_SIGNALSQ_SIGNALS
Q_SLOTSQ_SLOTS
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sun Feb 25 2024 18:45:23 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.