KIO

kfileplacesmodel.h
1 /*
2  This file is part of the KDE project
3  SPDX-FileCopyrightText: 2007 Kevin Ottens <[email protected]>
4  SPDX-FileCopyrightText: 2007 David Faure <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-only
7 */
8 
9 #ifndef KFILEPLACESMODEL_H
10 #define KFILEPLACESMODEL_H
11 
12 #include "kiofilewidgets_export.h"
13 
14 #include <KBookmark>
15 #include <QAbstractItemModel>
16 #include <QUrl>
17 
18 #include <solid/device.h>
19 #include <solid/solidnamespace.h>
20 
21 #include <memory>
22 
23 class KFilePlacesModelPrivate;
24 
25 class QMimeData;
26 class QAction;
27 
28 /**
29  * @class KFilePlacesModel kfileplacesmodel.h <KFilePlacesModel>
30  *
31  * This class is a list view model. Each entry represents a "place"
32  * where user can access files. Only relevant when
33  * used with QListView or QTableView.
34  */
35 class KIOFILEWIDGETS_EXPORT KFilePlacesModel : public QAbstractItemModel
36 {
37  Q_OBJECT
38 
39  Q_PROPERTY(QStringList supportedSchemes READ supportedSchemes WRITE setSupportedSchemes NOTIFY supportedSchemesChanged)
40 
41 public:
42  // Note: run printf "0x%08X\n" $(($RANDOM*$RANDOM))
43  // to define additional roles.
45  /** roleName is "url". @see url() */
46  UrlRole = 0x069CD12B,
47 
48  /** roleName is "isHidden". @see isHidden() */
49  HiddenRole = 0x0741CAAC,
50 
51  /** roleName is "isSetupNeeded". @see setupNeeded() */
52  SetupNeededRole = 0x059A935D,
53 
54  /**
55  * Whether the place is a fixed device (neither hotpluggable nor removable).
56  * roleName is "isFixedDevice".
57  */
58  FixedDeviceRole = 0x332896C1,
59 
60  /**
61  * Whether the place should have its free space displayed in a capacity bar.
62  * roleName is "isCapacityBarRecommended".
63  */
64  CapacityBarRecommendedRole = 0x1548C5C4,
65 
66  /**
67  * The name of the group, for example "Remote" or "Devices". roleName is "group".
68  * @since 5.40
69  */
70  GroupRole = 0x0a5b64ee,
71 
72  /**
73  * roleName is "iconName".
74  * @see icon()
75  * @since 5.41
76  */
77  IconNameRole = 0x00a45c00,
78 
79  /** roleName is "isGroupHidden".
80  * @see isGroupHidden()
81  * @since 5.42
82  */
83  GroupHiddenRole = 0x21a4b936,
84 
85  /** roleName is "isTeardownAllowed".
86  * @see isTeardownAllowed().
87  * @since 5.91
88  */
89  TeardownAllowedRole = 0x02533364,
90 
91  /** roleName is "isEjectAllowed".
92  * @since 5.94.
93  */
94  EjectAllowedRole = 0x0A16AC5B,
95 
96  /**
97  * roleName is "isTeardownOverlayRecommended".
98  * @see isTeardownOverlayRecommended()
99  * @since 5.95
100  */
101  TeardownOverlayRecommendedRole = 0x032EDCCE,
102 
103  /**
104  * roleName is "deviceAccessibility".
105  * @see deviceAccessibility()
106  * @since 5.99
107  */
108  DeviceAccessibilityRole = 0x023FFD93,
109  };
110 
111  /**
112  * Describes the available group types used in this model.
113  * @since 5.42
114  */
115  enum GroupType {
116  PlacesType, ///< "Places" section
117  RemoteType, ///< "Remote" section
118  RecentlySavedType, ///< "Recent" section
119  SearchForType, ///< "Search for" section
120  DevicesType, ///< "Devices" section
121  RemovableDevicesType, ///< "Removable Devices" section
122  UnknownType, ///< Unknown GroupType
123  TagsType, ///< "Tags" section. @since 5.54
124  };
125  Q_ENUM(GroupType)
126 
127  enum DeviceAccessibility { SetupNeeded, SetupInProgress, Accessible, TeardownInProgress };
128  Q_ENUM(DeviceAccessibility)
129 
130  explicit KFilePlacesModel(QObject *parent = nullptr);
131  /**
132  * @brief Construct a new KFilePlacesModel with an alternativeApplicationName
133  * @param alternativeApplicationName This value will be used to filter bookmarks in addition to the actual application name
134  * @param parent Parent object
135  * @since 5.43
136  */
137  // TODO KF6: merge constructors
138  KFilePlacesModel(const QString &alternativeApplicationName, QObject *parent = nullptr);
139  ~KFilePlacesModel() override;
140 
141  /**
142  * @return The URL of the place at index @p index.
143  */
144  Q_INVOKABLE QUrl url(const QModelIndex &index) const;
145 
146  /**
147  * @return Whether the place at index @p index needs to be mounted before it can be used.
148  */
149  Q_INVOKABLE bool setupNeeded(const QModelIndex &index) const;
150 
151  /**
152  * @return Whether the place is a device that can be unmounted, e.g. it is
153  * mounted but does not point at system Root or the user's Home directory.
154  *
155  * It does not indicate whether the teardown can succeed.
156  * @since 5.91
157  */
158  Q_INVOKABLE bool isTeardownAllowed(const QModelIndex &index) const;
159 
160  /**
161  * @return Whether the place is a device that can be ejected, e.g. it is
162  * a CD, DVD, etc.
163  *
164  * It does not indicate whether the eject can succeed.
165  * @since 5.94
166  */
167  Q_INVOKABLE bool isEjectAllowed(const QModelIndex &index) const;
168 
169  /**
170  * @return Whether showing an inline teardown button is recommended,
171  * e.g. when it is a removable drive.
172  *
173  * @since 5.95
174  **/
175  Q_INVOKABLE bool isTeardownOverlayRecommended(const QModelIndex &index) const;
176 
177  /**
178  * @return Whether this device is currently accessible or being (un)mounted.
179  *
180  * @since 5.99
181  */
182  Q_INVOKABLE KFilePlacesModel::DeviceAccessibility deviceAccessibility(const QModelIndex &index) const;
183 
184  /**
185  * @return The icon of the place at index @p index.
186  */
187  Q_INVOKABLE QIcon icon(const QModelIndex &index) const;
188 
189  /**
190  * @return The user-visible text of the place at index @p index.
191  */
192  Q_INVOKABLE QString text(const QModelIndex &index) const;
193 
194  /**
195  * @return Whether the place at index @p index is hidden or is inside an hidden group.
196  */
197  Q_INVOKABLE bool isHidden(const QModelIndex &index) const;
198 
199  /**
200  * @return Whether the group type @p type is hidden.
201  * @since 5.42
202  */
203  Q_INVOKABLE bool isGroupHidden(const GroupType type) const;
204 
205  /**
206  * @return Whether the group of the place at index @p index is hidden.
207  * @since 5.42
208  */
209  Q_INVOKABLE bool isGroupHidden(const QModelIndex &index) const;
210 
211  /**
212  * @return Whether the place at index @p index is a device handled by Solid.
213  * @see deviceForIndex()
214  */
215  Q_INVOKABLE bool isDevice(const QModelIndex &index) const;
216 
217  /**
218  * @return The solid device of the place at index @p index, if it is a device. Otherwise a default Solid::Device() instance is returned.
219  * @see isDevice()
220  */
221  Solid::Device deviceForIndex(const QModelIndex &index) const;
222 
223  /**
224  * @return The KBookmark instance of the place at index @p index.
225  * If the index is not valid, a default KBookmark instance is returned.
226  */
227  KBookmark bookmarkForIndex(const QModelIndex &index) const;
228 
229  /**
230  * @return The KBookmark instance of the place with url @p searchUrl.
231  * If the bookmark corresponding to searchUrl is not found, a default KBookmark instance is returned.
232  * @since 5.63
233  */
234  KBookmark bookmarkForUrl(const QUrl &searchUrl) const;
235 
236  /**
237  * @return The group type of the place at index @p index.
238  * @since 5.42
239  */
240  Q_INVOKABLE GroupType groupType(const QModelIndex &index) const;
241 
242  /**
243  * @return The list of model indexes that have @ type as their group type.
244  * @see groupType()
245  * @since 5.42
246  */
247  Q_INVOKABLE QModelIndexList groupIndexes(const GroupType type) const;
248 
249  /**
250  * @return A QAction with a proper translated label that can be used to trigger the requestTeardown()
251  * method for the place at index @p index.
252  * @see requestTeardown()
253  */
254  Q_INVOKABLE QAction *teardownActionForIndex(const QModelIndex &index) const;
255 
256  /**
257  * @return A QAction with a proper translated label that can be used to trigger the requestEject()
258  * method for the place at index @p index.
259  * @see requestEject()
260  */
261  Q_INVOKABLE QAction *ejectActionForIndex(const QModelIndex &index) const;
262 
263  /**
264  * Unmounts the place at index @p index by triggering the teardown functionality of its Solid device.
265  * @see deviceForIndex()
266  */
267  Q_INVOKABLE void requestTeardown(const QModelIndex &index);
268 
269  /**
270  * Ejects the place at index @p index by triggering the eject functionality of its Solid device.
271  * @see deviceForIndex()
272  */
273  Q_INVOKABLE void requestEject(const QModelIndex &index);
274 
275  /**
276  * Mounts the place at index @p index by triggering the setup functionality of its Solid device.
277  * @see deviceForIndex()
278  */
279  Q_INVOKABLE void requestSetup(const QModelIndex &index);
280 
281  /**
282  * Adds a new place to the model.
283  * @param text The user-visible text for the place
284  * @param url The URL of the place. It will be stored in its QUrl::FullyEncoded string format.
285  * @param iconName The icon of the place
286  * @param appName If set as the value of QCoreApplication::applicationName(), will make the place visible only in this application.
287  */
288  Q_INVOKABLE void addPlace(const QString &text, const QUrl &url, const QString &iconName = QString(), const QString &appName = QString());
289 
290  /**
291  * Adds a new place to the model.
292  * @param text The user-visible text for the place
293  * @param url The URL of the place. It will be stored in its QUrl::FullyEncoded string format.
294  * @param iconName The icon of the place
295  * @param appName If set as the value of QCoreApplication::applicationName(), will make the place visible only in this application.
296  * @param after The index after which the new place will be added.
297  */
298  Q_INVOKABLE void addPlace(const QString &text, const QUrl &url, const QString &iconName, const QString &appName, const QModelIndex &after);
299 
300  /**
301  * Edits the place with index @p index.
302  * @param text The new user-visible text for the place
303  * @param url The new URL of the place
304  * @param iconName The new icon of the place
305  * @param appName The new application-local filter for the place (@see addPlace()).
306  */
307  Q_INVOKABLE void
308  editPlace(const QModelIndex &index, const QString &text, const QUrl &url, const QString &iconName = QString(), const QString &appName = QString());
309 
310  /**
311  * Deletes the place with index @p index from the model.
312  */
313  Q_INVOKABLE void removePlace(const QModelIndex &index) const;
314 
315  /**
316  * Changes the visibility of the place with index @p index, but only if the place is not inside an hidden group.
317  * @param hidden Whether the place should be hidden or visible.
318  * @see isGroupHidden()
319  */
320  Q_INVOKABLE void setPlaceHidden(const QModelIndex &index, bool hidden);
321 
322  /**
323  * Changes the visibility of the group with type @p type.
324  * @param hidden Whether the group should be hidden or visible.
325  * @see isGroupHidden()
326  * @since 5.42
327  */
328  Q_INVOKABLE void setGroupHidden(const GroupType type, bool hidden);
329 
330  /**
331  * @brief Move place at @p itemRow to a position before @p row
332  * @return Whether the place has been moved.
333  * @since 5.41
334  */
335  Q_INVOKABLE bool movePlace(int itemRow, int row);
336 
337  /**
338  * @return The number of hidden places in the model.
339  * @see isHidden()
340  */
341  Q_INVOKABLE int hiddenCount() const;
342 
343  /**
344  * @brief Get a visible data based on Qt role for the given index.
345  * Return the device information for the give index.
346  *
347  * @param index The QModelIndex which contains the row, column to fetch the data.
348  * @param role The Interview data role(ex: Qt::DisplayRole).
349  *
350  * @return the data for the given index and role.
351  */
352  QVariant data(const QModelIndex &index, int role) const override;
353 
354  /**
355  * @brief Get the children model index for the given row and column.
356  */
357  QModelIndex index(int row, int column, const QModelIndex &parent = QModelIndex()) const override;
358 
359  /**
360  * @brief Get the parent QModelIndex for the given model child.
361  */
362  QModelIndex parent(const QModelIndex &child) const override;
363 
364  /// Reimplemented from QAbstractItemModel.
365  /// @see AdditionalRoles
366  QHash<int, QByteArray> roleNames() const override;
367 
368  /**
369  * @brief Get the number of rows for a model index.
370  */
371  int rowCount(const QModelIndex &parent = QModelIndex()) const override;
372 
373  /**
374  * @brief Get the number of columns for a model index.
375  */
376  int columnCount(const QModelIndex &parent = QModelIndex()) const override;
377 
378  /**
379  * Returns the closest item for the URL \a url.
380  * The closest item is defined as item which is equal to
381  * the URL or at least is a parent URL. If there are more than
382  * one possible parent URL candidates, the item which covers
383  * the bigger range of the URL is returned.
384  *
385  * Example: the url is '/home/peter/Documents/Music'.
386  * Available items are:
387  * - /home/peter
388  * - /home/peter/Documents
389  *
390  * The returned item will the one for '/home/peter/Documents'.
391  */
392  QModelIndex closestItem(const QUrl &url) const;
393 
394  Qt::DropActions supportedDropActions() const override;
395  Qt::ItemFlags flags(const QModelIndex &index) const override;
396  QStringList mimeTypes() const override;
397  QMimeData *mimeData(const QModelIndexList &indexes) const override;
398  bool dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent) override;
399 
400  /**
401  * @brief Reload bookmark information
402  * @since 5.41
403  */
404  Q_INVOKABLE void refresh() const;
405 
406  /**
407  * @brief Converts the URL, which contains "virtual" URLs for system-items like
408  * "timeline:/lastmonth" into a Query-URL "timeline:/2017-10"
409  * that will be handled by the corresponding KIO worker.
410  * Virtual URLs for bookmarks are used to be independent from
411  * internal format changes.
412  * @param an url
413  * @return the converted URL, which can be handled by a KIO worker
414  * @since 5.41
415  */
416  static QUrl convertedUrl(const QUrl &url);
417 
418  /**
419  * Set the URL schemes that the file widget should allow navigating to.
420  *
421  * If the returned list is empty, all schemes are supported. Examples for
422  * schemes are @c "file" or @c "ftp".
423  *
424  * @sa QFileDialog::setSupportedSchemes
425  * @since 5.43
426  */
427  void setSupportedSchemes(const QStringList &schemes);
428 
429  /**
430  * Returns the URL schemes that the file widget should allow navigating to.
431  *
432  * If the returned list is empty, all schemes are supported.
433  *
434  * @sa QFileDialog::supportedSchemes
435  * @since 5.43
436  */
437  QStringList supportedSchemes() const;
438 
439 Q_SIGNALS:
440  /**
441  * @p message An error message explaining what went wrong.
442  */
443  void errorMessage(const QString &message);
444 
445  /**
446  * Emitted after the Solid setup ends.
447  * @param success Whether the Solid setup has been successful.
448  * @see requestSetup()
449  */
450  void setupDone(const QModelIndex &index, bool success);
451 
452  /**
453  * Emitted after the teardown of a device ends.
454  *
455  * @note In case of an error, the @p errorMessage signal
456  * will also be emitted with a message describing the error.
457  *
458  * @param error Type of error that occurred, if any.
459  * @param errorData More information about the error, if any.
460  * @since 5.100
461  */
462  void teardownDone(const QModelIndex &index, Solid::ErrorType error, const QVariant &errorData);
463 
464  /**
465  * Emitted whenever the visibility of the group @p group changes.
466  * @param hidden The new visibility of the group.
467  * @see setGroupHidden()
468  * @since 5.42
469  */
470  void groupHiddenChanged(KFilePlacesModel::GroupType group, bool hidden);
471 
472  /**
473  * Called once the model has been reloaded
474  *
475  * @since 5.71
476  */
477  void reloaded();
478 
479  /**
480  * Emitted whenever the list of supported schemes has been changed
481  *
482  * @since 5.94
483  */
484  void supportedSchemesChanged();
485 
486 private:
487  friend class KFilePlacesModelPrivate;
488  std::unique_ptr<KFilePlacesModelPrivate> d;
489 };
490 
491 #endif
virtual bool dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent)
Q_PROPERTY(...)
@ UnknownType
Unknown GroupType.
Q_ENUM(...)
@ RecentlySavedType
"Recent" section
virtual int rowCount(const QModelIndex &parent) const const=0
virtual QStringList mimeTypes() const const
virtual QVariant data(const QModelIndex &index, int role) const const=0
virtual Qt::DropActions supportedDropActions() const const
@ PlacesType
"Places" section
KCALUTILS_EXPORT QString errorMessage(const KCalendarCore::Exception &exception)
virtual QHash< int, QByteArray > roleNames() const const
@ TagsType
"Tags" section.
typedef ItemFlags
@ RemovableDevicesType
"Removable Devices" section
virtual int columnCount(const QModelIndex &parent) const const=0
virtual Qt::ItemFlags flags(const QModelIndex &index) const const
GroupType
Describes the available group types used in this model.
Q_SIGNALSQ_SIGNALS
typedef DropActions
@ RemoteType
"Remote" section
virtual QModelIndex index(int row, int column, const QModelIndex &parent) const const=0
@ SearchForType
"Search for" section
virtual QMimeData * mimeData(const QModelIndexList &indexes) const const
QObject * parent() const const
QString message
@ DevicesType
"Devices" section
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sat Sep 30 2023 03:50:08 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.