KIO

kcoredirlister.h
1 /*
2  This file is part of the KDE project
3  SPDX-FileCopyrightText: 1999 David Faure <[email protected]>
4  SPDX-FileCopyrightText: 2001, 2002, 2004-2006 Michael Brade <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8 
9 #ifndef KCOREDIRLISTER_H
10 #define KCOREDIRLISTER_H
11 
12 #include "kdirnotify.h" // TODO KF6: remove
13 #include "kfileitem.h"
14 
15 #include <QString>
16 #include <QStringList>
17 #include <QUrl>
18 
19 #include <memory>
20 
21 class KJob;
22 namespace KIO
23 {
24 class Job;
25 class ListJob;
26 }
27 
28 class KCoreDirListerPrivate;
29 
30 /**
31  * @class KCoreDirLister kcoredirlister.h <KCoreDirLister>
32  *
33  * @short Helper class for the kiojob used to list and update a directory.
34  *
35  * The dir lister deals with the kiojob used to list and update a directory
36  * and has signals for the user of this class (e.g. konqueror view or
37  * kdesktop) to create/destroy its items when asked.
38  *
39  * This class is independent from the graphical representation of the dir
40  * (icon container, tree view, ...) and it stores the items (as KFileItems).
41  *
42  * Typical usage :
43  * @li Create an instance.
44  * @li Connect to at least update, clear, itemsAdded, and itemsDeleted.
45  * @li Call openUrl - the signals will be called.
46  * @li Reuse the instance when opening a new url (openUrl).
47  * @li Destroy the instance when not needed anymore (usually destructor).
48  *
49  * Advanced usage : call openUrl with OpenUrlFlag::Keep to list directories
50  * without forgetting the ones previously read (e.g. for a tree view)
51  *
52  * @author Michael Brade <[email protected]>
53  */
54 class KIOCORE_EXPORT KCoreDirLister : public QObject
55 {
56  friend class KCoreDirListerCache;
57  friend struct KCoreDirListerCacheDirectoryData;
58 
59  Q_OBJECT
60  Q_PROPERTY(bool autoUpdate READ autoUpdate WRITE setAutoUpdate)
61 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 100)
62  Q_PROPERTY(bool showingDotFiles READ showingDotFiles WRITE setShowingDotFiles)
63 #endif
64  Q_PROPERTY(bool showHiddenFiles READ showHiddenFiles WRITE setShowHiddenFiles)
65  Q_PROPERTY(bool dirOnlyMode READ dirOnlyMode WRITE setDirOnlyMode)
66  Q_PROPERTY(bool delayedMimeTypes READ delayedMimeTypes WRITE setDelayedMimeTypes)
67  Q_PROPERTY(bool requestMimeTypeWhileListing READ requestMimeTypeWhileListing WRITE setRequestMimeTypeWhileListing)
68  Q_PROPERTY(QString nameFilter READ nameFilter WRITE setNameFilter)
69  Q_PROPERTY(QStringList mimeFilter READ mimeFilters WRITE setMimeFilter RESET clearMimeFilter)
70  Q_PROPERTY(bool autoErrorHandlingEnabled READ autoErrorHandlingEnabled WRITE setAutoErrorHandlingEnabled)
71 
72 public:
73  /**
74  * @see OpenUrlFlags
75  */
76  enum OpenUrlFlag {
77  NoFlags = 0x0, ///< No additional flags specified.
78 
79  Keep = 0x1, ///< Previous directories aren't forgotten
80  ///< (they are still watched by kdirwatch and their items
81  ///< are kept for this KCoreDirLister). This is useful for e.g.
82  ///< a treeview.
83 
84  Reload = 0x2, ///< Indicates whether to use the cache or to reread
85  ///< the directory from the disk.
86  ///< Use only when opening a dir not yet listed by this lister
87  ///< without using the cache. Otherwise use updateDirectory.
88  };
89 
90  /**
91  * Stores a combination of #OpenUrlFlag values.
92  */
93  Q_DECLARE_FLAGS(OpenUrlFlags, OpenUrlFlag)
94 
95  /**
96  * Create a directory lister.
97  */
98  KCoreDirLister(QObject *parent = nullptr);
99 
100  /**
101  * Destroy the directory lister.
102  */
103  ~KCoreDirLister() override;
104 
105  /**
106  * Run the directory lister on the given url.
107  *
108  * This method causes KCoreDirLister to emit @em all the items of @p dirUrl, in any case.
109  * Depending on @p flags, either clear() or clearDir(const QUrl &) will be emitted first.
110  *
111  * The newItems() signal may be emitted more than once to supply you with KFileItems, up
112  * until the signal completed() is emitted (and isFinished() returns @c true).
113  *
114  * @param dirUrl the directory URL.
115  * @param flags whether to keep previous directories, and whether to reload, see OpenUrlFlags
116  * @return @c true if successful, @c false otherwise (e.g. if @p dirUrl is invalid)
117  *
118  * @note clearDir(const QUrl &) is emitted since 5.79; before that it was clear(const QUrl &)
119  * which has been deprecated.
120  */
121  virtual bool openUrl(const QUrl &dirUrl, OpenUrlFlags flags = NoFlags); // TODO KF6: remove virtual, change bool to void
122 
123  /**
124  * Stop listing all directories currently being listed.
125  *
126  * Emits canceled() if there was at least one job running.
127  * Emits listingDirCanceled(const QUrl &) for each stopped job if there is more than one
128  * directory being watched by this KCoreDirLister.
129  *
130  * @note listingDirCanceled(const QUrl &) is emitted since 5.79; before that it was
131  * canceled(const QUrl &) which has been deprecated.
132  */
133  virtual void stop(); // TODO KF6: remove virtual
134 
135  /**
136  * Stop listing the given directory.
137  *
138  * Emits canceled() if the killed job was the last running one.
139  * Emits listingDirCanceled(const QUrl &) for the killed job if there is more than one
140  * directory being watched by this KCoreDirLister.
141  *
142  * No signal is emitted if there was no job running for @p dirUrl.
143  *
144  * @param dirUrl the directory URL
145  *
146  * @note listingDirCanceled(const QUrl &) is emitted since 5.79; before that it was
147  * canceled(const QUrl &) which has been deprecated.
148  */
149  virtual void stop(const QUrl &dirUrl); // TODO KF6: remove virtual
150 
151  /**
152  * Stop listening for further changes in the given directory.
153  * When a new directory is opened with OpenUrlFlag::Keep the caller will keep being notified of file changes for all directories that were kept open.
154  * This call selectively removes a directory from sending future notifications to this KCoreDirLister.
155  *
156  * @param dirUrl the directory URL.
157  * @since 5.91
158  */
159  void forgetDirs(const QUrl &dirUrl);
160 
161  /**
162  * @return @c true if the "delayed MIME types" feature was enabled
163  * @see setDelayedMimeTypes
164  */
165  bool delayedMimeTypes() const;
166 
167  /**
168  * Delayed MIME types feature:
169  * If enabled, MIME types will be fetched on demand, which leads to a
170  * faster initial directory listing, where icons get progressively replaced
171  * with the correct one while KMimeTypeResolver is going through the items
172  * with unknown or imprecise MIME type (e.g. files with no extension or an
173  * unknown extension).
174  */
175  void setDelayedMimeTypes(bool delayedMimeTypes);
176 
177  /**
178  * Checks whether KDirWatch will automatically update directories. This is
179  * enabled by default.
180  *
181  * @return @c true if KDirWatch is used to automatically update directories
182  */
183  bool autoUpdate() const;
184 
185  /**
186  * Toggle automatic directory updating, when a directory changes (using KDirWatch).
187  *
188  * @param enable set to @c true to enable or @c false to disable
189  */
190  virtual void setAutoUpdate(bool enable); // TODO KF6: remove virtual
191 
192 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 100)
193  /**
194  * Checks whether hidden files (files whose name start with '.') will be shown.
195  * By default this option is disabled (hidden files are not shown).
196  *
197  * @return @c true if dot files are shown, @c false otherwise
198  *
199  * @deprecated since 5.100, use showHiddenFiles instead.
200  *
201  * @see setShowingDotFiles()
202  */
203  KIOCORE_DEPRECATED_VERSION(5, 100, "Use showHiddenFiles instead.")
204  bool showingDotFiles() const;
205 #endif
206 
207  /**
208  * Checks whether hidden files (e.g. files whose name start with '.' on Unix) will be shown.
209  * By default this option is disabled (hidden files are not shown).
210  *
211  * @return @c true if hidden files are shown, @c false otherwise
212  *
213  * @see setShowHiddenFiles()
214  * @since 5.100
215  */
216  bool showHiddenFiles() const;
217 
218  // Not _ENABLED_ because this is a virtual method
219 #if KIOCORE_BUILD_DEPRECATED_SINCE(5, 100)
220  /**
221  * Toggles whether hidden files (files whose name start with '.') are shown, by default
222  * hidden files are not shown.
223  *
224  * You need to call emitChanges() afterwards.
225  *
226  * @param showDotFiles set to @c true/false to show/hide hidden files respectively
227  *
228  * @deprecated since 5.100, use setShowHiddenFiles() instead.
229  *
230  * @see showingDotFiles()
231  */
232  KIOCORE_DEPRECATED_VERSION(5, 100, "Use setShowHiddenFiles instead.")
233  virtual void setShowingDotFiles(bool showDotFiles);
234 #endif
235 
236  /**
237  * Toggles whether hidden files (e.g. files whose name start with '.' on Unix) are shown/
238  * By default hidden files are not shown.
239  *
240  * You need to call emitChanges() afterwards.
241  *
242  * @param showHiddenFiles set to @c true/false to show/hide hidden files respectively
243  *
244  * @see showHiddenFiles()
245  * @since 5.100
246  */
247  void setShowHiddenFiles(bool showHiddenFiles);
248 
249  /**
250  * Checks whether this KCoreDirLister only lists directories or all items (directories and
251  * files), by default all items are listed.
252  *
253  * @return @c true if only directories are listed, @c false otherwise
254  *
255  * @see setDirOnlyMode(bool)
256  */
257  bool dirOnlyMode() const;
258 
259  /**
260  * Call this to list only directories (by default all items (directories and files)
261  * are listed).
262  *
263  * You need to call emitChanges() afterwards.
264  *
265  * @param dirsOnly set to @c true to list only directories
266  */
267  virtual void setDirOnlyMode(bool dirsOnly); // TODO KF6: remove virtual
268 
269  /**
270  * Checks whether this KCoreDirLister requests the MIME type of files from the worker.
271  *
272  * Enabling this will tell the worker used for listing that it should try to
273  * determine the mime type of entries while listing them. This potentially
274  * reduces the speed at which entries are listed but ensures mime types are
275  * immediately available when an entry is added, greatly speeding up things
276  * like mime type filtering.
277  *
278  * By default this is disabled.
279  *
280  * @return @c true if the worker is asked for MIME types, @c false otherwise.
281  *
282  * @see setRequestMimeTypeWhileListing(bool)
283  *
284  * @since 5.82
285  */
286  bool requestMimeTypeWhileListing() const;
287 
288  /**
289  * Toggles whether to request MIME types from the worker or in-process.
290  *
291  * @param request set to @c true to request MIME types from the worker.
292  *
293  * @note If this is changed while the lister is already listing a directory,
294  * it will only have an effect the next time openUrl() is called.
295  *
296  * @see requestMimeTypeWhileListing()
297  *
298  * @since 5.82
299  */
300  void setRequestMimeTypeWhileListing(bool request);
301 
302  /**
303  * Returns the top level URL that is listed by this KCoreDirLister.
304  *
305  * It might be different from the one given with openUrl() if there was a
306  * redirection. If you called openUrl() with OpenUrlFlag::Keep this is the
307  * first url opened (e.g. in a treeview this is the root).
308  *
309  * @return the url used by this instance to list the files
310  */
311  QUrl url() const;
312 
313  /**
314  * Returns all URLs that are listed by this KCoreDirLister. This is only
315  * useful if you called openUrl() with OpenUrlFlag::Keep, as it happens in a
316  * treeview, for example. (Note that the base url is included in the list
317  * as well, of course.)
318  *
319  * @return a list of all listed URLs
320  */
321  QList<QUrl> directories() const;
322 
323  /**
324  * Actually emit the changes made with setShowHiddenFiles, setDirOnlyMode,
325  * setNameFilter and setMimeFilter.
326  */
327  virtual void emitChanges(); // TODO KF6: remove virtual
328 
329  /**
330  * Update the directory @p dirUrl. This method causes KCoreDirLister to @em only emit
331  * the items of @p dirUrl that actually changed compared to the current state in the
332  * cache, and updates the cache.
333  *
334  * The current implementation calls updateDirectory automatically for local files, using
335  * KDirWatch (if autoUpdate() is @c true), but it might be useful to force an update manually.
336  *
337  * @param dirUrl the directory URL
338  */
339  virtual void updateDirectory(const QUrl &dirUrl); // TODO KF6: remove virtual
340 
341  /**
342  * Returns @c true if no I/O operation is currently in progress.
343  *
344  * @return @c true if finished, @c false otherwise
345  */
346  bool isFinished() const;
347 
348  /**
349  * Returns the file item of the URL.
350  *
351  * Can return an empty KFileItem.
352  * @return the file item for url() itself (".")
353  */
354  KFileItem rootItem() const;
355 
356  /**
357  * Find an item by its URL.
358  * @param url the item URL
359  * @return the KFileItem
360  */
361  virtual KFileItem findByUrl(const QUrl &url) const; // TODO KF6: remove virtual
362 
363  /**
364  * Find an item by its name.
365  * @param name the item name
366  * @return the KFileItem
367  */
368  virtual KFileItem findByName(const QString &name) const; // TODO KF6: remove virtual
369 
370  /**
371  * Set a name filter to only list items matching this name, e.g.\ "*.cpp".
372  *
373  * You can set more than one filter by separating them with whitespace, e.g
374  * "*.cpp *.h".
375  * Note: the directory is not automatically reloaded.
376  * You need to call emitChanges() afterwards.
377  *
378  * @param filter the new filter, QString() to disable filtering
379  * @see matchesFilter
380  */
381  virtual void setNameFilter(const QString &filter); // TODO KF6: remove virtual
382 
383  /**
384  * Returns the current name filter, as set via setNameFilter()
385  * @return the current name filter, can be QString() if filtering
386  * is turned off
387  */
388  QString nameFilter() const;
389 
390  /**
391  * Set MIME type based filter to only list items matching the given MIME types.
392  *
393  * NOTE: setting the filter does not automatically reload directory.
394  * Also calling this function will not affect any named filter already set.
395  *
396  * You need to call emitChanges() afterwards.
397  *
398  * @param mimeList a list of MIME types
399  *
400  * @see clearMimeFilter
401  * @see matchesMimeFilter
402  */
403  virtual void setMimeFilter(const QStringList &mimeList); // TODO KF6: remove virtual
404 
405 #if KIOCORE_BUILD_DEPRECATED_SINCE(5, 100)
406  /**
407  * Filtering should be done with KFileFilter. This will be implemented in a later
408  * revision of KCoreDirLister. This method may be removed then.
409  *
410  * Set MIME type based exclude filter to only list items not matching the given MIME types
411  *
412  * NOTE: setting the filter does not automatically reload directory.
413  * Also calling this function will not affect any named filter already set.
414  *
415  * @param mimeList a list of MIME types
416  * @see clearMimeFilter
417  * @see matchesMimeFilter
418  * @internal
419  * @deprecated since 5.100, no known users.
420  */
421  KIOCORE_DEPRECATED_VERSION(5, 100, "No known users.")
422  void setMimeExcludeFilter(const QStringList &mimeList);
423 #endif
424 
425  /**
426  * Clears the MIME type based filter.
427  *
428  * You need to call emitChanges() afterwards.
429  *
430  * @see setMimeFilter
431  */
432  virtual void clearMimeFilter(); // TODO KF6: remove virtual
433 
434  /**
435  * Returns the list of MIME type based filters, as set via setMimeFilter().
436  * @return the list of MIME type based filters. Empty, when no MIME type filter is set.
437  */
438  QStringList mimeFilters() const;
439 
440 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 94)
441  /**
442  * Checks whether @p name matches a filter in the list of name filters.
443  *
444  * @return @c true if @p name matches a filter in the list, otherwise @c false.
445  *
446  * @deprecated since 5.94, no known users.
447  *
448  * @see setNameFilter()
449  */
450  KIOCORE_DEPRECATED_VERSION(5, 94, "No known users.")
451  bool matchesFilter(const QString &name) const;
452 #endif
453 
454 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 94)
455  /**
456  * Checks whether @p mimeType matches a filter in the list of MIME types.
457  *
458  * @param mimeType the MIME type to find in the filter list
459  *
460  * @return @c true if @p mimeType matches a filter in the list, otherwise @c false
461  *
462  * @deprecated since 5.94, no known users.
463  *
464  * @see setMimeFilter.
465  */
466  KIOCORE_DEPRECATED_VERSION(5, 94, "No known users.")
467  bool matchesMimeFilter(const QString &mimeType) const;
468 #endif
469 
470  /**
471  * Used by items() and itemsForDir() to specify whether you want
472  * all items for a directory or just the filtered ones.
473  */
474  enum WhichItems {
475  AllItems = 0,
476  FilteredItems = 1,
477  };
478 
479  /**
480  * Returns the items listed for the current url().
481  *
482  * This method will @em not start listing a directory, you should only call
483  * this in a slot connected to the finished() signal.
484  *
485  * The items in the KFileItemList are copies of the items used by KCoreDirLister.
486  *
487  * @param which specifies whether the returned list will contain all entries
488  * or only the ones that passed the nameFilter(), mimeFilter(),
489  * etc. Note that the latter causes iteration over all the
490  * items, filtering them. If this is too slow for you, use the
491  * newItems() signal, sending out filtered items in chunks
492  * @return the items listed for the current url()
493  */
494  KFileItemList items(WhichItems which = FilteredItems) const;
495 
496  /**
497  * Returns the items listed for the given @p dirUrl.
498  * This method will @em not start listing @p dirUrl, you should only call
499  * this in a slot connected to the finished() signal.
500  *
501  * The items in the KFileItemList are copies of the items used by KCoreDirLister.
502  *
503  * @param dirUrl specifies the url for which the items should be returned. This
504  * is only useful if you use KCoreDirLister with multiple URLs
505  * i.e. using bool OpenUrlFlag::Keep in openUrl()
506  * @param which specifies whether the returned list will contain all entries
507  * or only the ones that passed the nameFilter, mimeFilter, etc.
508  * Note that the latter causes iteration over all the items,
509  * filtering them. If this is too slow for you, use the
510  * newItems() signal, sending out filtered items in chunks
511  *
512  * @return the items listed for @p dirUrl
513  */
514  KFileItemList itemsForDir(const QUrl &dirUrl, WhichItems which = FilteredItems) const;
515 
516  /**
517  * Return the KFileItem for the given URL, if it was listed recently and it's
518  * still in the cache, which is always the case if a directory view is currently
519  * showing this item. If not, then it might be in the cache; if not in the cache a
520  * a null KFileItem will be returned.
521  *
522  * If you really need a KFileItem for this URL in all cases, then use KIO::stat() instead.
523  *
524  * @since 4.2
525  */
526  static KFileItem cachedItemForUrl(const QUrl &url);
527 
528  /**
529  * Checks whether auto error handling is enabled.
530  * If enabled, it will show an error dialog to the user when an
531  * error occurs (assuming the application links to KIOWidgets).
532  * It is turned on by default.
533  * @return @c true if auto error handling is enabled, @c false otherwise
534  * @see setAutoErrorHandlingEnabled()
535  * @since 5.82
536  */
537  bool autoErrorHandlingEnabled() const;
538 
539  /**
540  * Enable or disable auto error handling.
541  * If enabled, it will show an error dialog to the user when an
542  * error occurs. It is turned on by default.
543  * @param enable true to enable auto error handling, false to disable
544  * @param parent the parent widget for the error dialogs, can be @c nullptr for
545  * top-level
546  * @see autoErrorHandlingEnabled()
547  * @since 5.82
548  */
549  void setAutoErrorHandlingEnabled(bool enable);
550 
551 Q_SIGNALS:
552  /**
553  * Tell the view that this KCoreDirLister has started to list @p dirUrl. Note that this
554  * does @em not imply that there is really a job running! I.e. KCoreDirLister::jobs()
555  * may return an empty list, in which case the items are taken from the cache.
556  *
557  * The view knows that openUrl should start it, so this might seem useless, but the view
558  * also needs to know when an automatic update happens.
559  * @param dirUrl the URL to list
560  */
561  void started(const QUrl &dirUrl);
562 
563  /**
564  * Tell the view that listing is finished. There are no jobs running anymore.
565  */
566  void completed(); // clazy:exclude=overloaded-signal
567 
568 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 79)
569  /**
570  * Tell the view that the listing of the directory @p dirUrl is finished.
571  * There might be other running jobs left.
572  *
573  * @param dirUrl the directory URL
574  *
575  * @deprecated since 5.79, use KCoreDirLister::listingDirCompleted(const QUrl &)
576  */
577  KIOCORE_DEPRECATED_VERSION(5, 79, "Use KCoreDirLister::listingDirCompleted(const QUrl &)")
578  void completed(const QUrl &dirUrl); // clazy:exclude=overloaded-signal
579 #endif
580 
581  /**
582  * Tell the view that the listing of the directory @p dirUrl is finished.
583  * There might be other running jobs left.
584  *
585  * @param dirUrl the directory URL
586  *
587  * @since 5.79
588  */
589  void listingDirCompleted(const QUrl &dirUrl);
590 
591  /**
592  * Tell the view that the user canceled the listing. No running jobs are left.
593  */
594  void canceled(); // clazy:exclude=overloaded-signal
595 
596 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 79)
597  /**
598  * Tell the view that the listing of the directory @p dirUrl was canceled.
599  * There might be other running jobs left.
600  *
601  * @param dirUrl the directory URL
602  *
603  * @deprecated since 5.79, use KCoreDirLister::listingDirCanceled(const QUrl &)
604  */
605  KIOCORE_DEPRECATED_VERSION(5, 79, "use KCoreDirLister::listingDirCanceled(const QUrl &)")
606  void canceled(const QUrl &dirUrl); // clazy:exclude=overloaded-signal
607 #endif
608 
609  /**
610  * Tell the view that the listing of the directory @p dirUrl was canceled.
611  * There might be other running jobs left.
612  *
613  * @param dirUrl the directory URL
614  *
615  * @since 5.79
616  */
617  void listingDirCanceled(const QUrl &dirUrl);
618 
619 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 80)
620  /**
621  * Signal a redirection.
622  * Only emitted if there's just one directory to list, i.e. most
623  * probably openUrl() has been called without OpenUrlFlag::Keep.
624  *
625  * @param dirUrl the new URL
626  *
627  * @deprecated since 5.80, use redirection(const QUrl &, const QUrl &)
628  */
629  KIOCORE_DEPRECATED_VERSION(5, 80, "Use redirection(const QUrl &, const QUrl &)")
630  void redirection(const QUrl &_url); // clazy:exclude=overloaded-signal
631 #endif
632 
633  /**
634  * Signals a redirection.
635  *
636  * @param oldUrl the original URL
637  * @param newUrl the new URL
638  */
639  void redirection(const QUrl &oldUrl, const QUrl &newUrl); // clazy:exclude=overloaded-signal
640 
641  /**
642  * Signals to the view to remove all items (when e.g.\ going from dirA to dirB).
643  * Make sure to connect to this signal to avoid having duplicate items in the view.
644  */
645  void clear(); // clazy:exclude=overloaded-signal
646 
647 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 79)
648  /**
649  * Signals to the view to clear all items from directory @p dirUrl.
650  *
651  * This is only emitted if the lister is holding more than one directory.
652  *
653  * @param dirUrl the directory that the view should clear all items from
654  *
655  * @deprecated since 5.79, use clearDir(const QUrl &)
656  */
657  KIOCORE_DEPRECATED_VERSION(5, 79, "Use clearDir(const QUrl &)")
658  void clear(const QUrl &dirUrl); // clazy:exclude=overloaded-signal
659 #endif
660 
661  /**
662  * Signals to the view to clear all items from directory @p dirUrl.
663  *
664  * This is only emitted if the lister is holding more than one directory.
665  *
666  * @param dirUrl the directory that the view should clear all items from
667  *
668  * @since 5.79
669  */
670  void clearDir(const QUrl &dirUrl);
671 
672  /**
673  * Signal new items.
674  *
675  * @param items a list of new items
676  */
677  void newItems(const KFileItemList &items);
678 
679  /**
680  * Signal that new items were found during directory listing.
681  * Alternative signal emitted at the same time as newItems(),
682  * but itemsAdded also passes the url of the parent directory.
683  *
684  * @param items a list of new items
685  * @since 4.2
686  */
687  void itemsAdded(const QUrl &directoryUrl, const KFileItemList &items);
688 
689 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 100)
690  /**
691  * Send a list of items filtered-out by MIME type.
692  * @param items the list of filtered items
693  *
694  * @deprecated since 5.100, no known users.
695  */
696  KIOCORE_DEPRECATED_VERSION(5, 100, "No known users.")
697  void itemsFilteredByMime(const KFileItemList &items);
698 #endif
699 
700  /**
701  * Signal that items have been deleted
702  *
703  * @since 4.1.2
704  * @param items the list of deleted items
705  */
706  void itemsDeleted(const KFileItemList &items);
707 
708  /**
709  * Signal an item to refresh (its MIME-type/icon/name has changed).
710  * Note: KFileItem::refresh has already been called on those items.
711  * @param items the items to refresh. This is a list of pairs, where
712  * the first item in the pair is the OLD item, and the second item is the
713  * NEW item. This allows to track which item has changed, especially after
714  * a renaming.
715  */
716  void refreshItems(const QList<QPair<KFileItem, KFileItem>> &items);
717 
718  /**
719  * Emitted to display information about running jobs.
720  * Examples of message are "Resolving host", "Connecting to host...", etc.
721  * @param msg the info message
722  */
723  void infoMessage(const QString &msg);
724 
725  /**
726  * Progress signal showing the overall progress of the KCoreDirLister.
727  * This allows using a progress bar very easily. (see QProgressBar)
728  * @param percent the progress in percent
729  */
730  void percent(int percent);
731 
732  /**
733  * Emitted when we know the size of the jobs.
734  * @param size the total size in bytes
735  */
736  void totalSize(KIO::filesize_t size);
737 
738  /**
739  * Regularly emitted to show the progress of this KCoreDirLister.
740  * @param size the processed size in bytes
741  */
742  void processedSize(KIO::filesize_t size);
743 
744  /**
745  * Emitted to display information about the speed of the jobs.
746  * @param bytes_per_second the speed in bytes/s
747  */
748  void speed(int bytes_per_second);
749 
750  /**
751  * Emitted if listing a directory fails with an error.
752  * A typical implementation in a widgets-based application
753  * would show a message box by calling this in a slot connected to this signal:
754  * <tt>job->uiDelegate()->showErrorMessage()</tt>
755  * Many applications might prefer to embed the error message though
756  * (e.g. by using the KMessageWidget class, from the KWidgetsAddons Framework).
757  * @param the job with an error
758  * @since 5.82
759  */
760  void jobError(KIO::Job *job);
761 
762 protected:
763 #if KIOCORE_ENABLE_DEPRECATED_SINCE(4, 3)
764  /// @deprecated Since 4.3, and unused, ignore this
765  enum Changes { NONE = 0, NAME_FILTER = 1, MIME_FILTER = 2, DOT_FILES = 4, DIR_ONLY_MODE = 8 };
766 #endif
767 
768  /**
769  * Called for every new item before emitting newItems().
770  * You may reimplement this method in a subclass to implement your own
771  * filtering.
772  * The default implementation filters out ".." and everything not matching
773  * the name filter(s)
774  * @return @c true if the item is "ok".
775  * @c false if the item shall not be shown in a view, e.g.
776  * files not matching a pattern *.cpp ( KFileItem::isHidden())
777  * @see matchesFilter
778  * @see setNameFilter
779  */
780  virtual bool matchesFilter(const KFileItem &) const;
781 
782  /**
783  * Called for every new item before emitting newItems().
784  * You may reimplement this method in a subclass to implement your own
785  * filtering.
786  * The default implementation filters out everything not matching
787  * the mime filter(s)
788  * @return @c true if the item is "ok".
789  * @c false if the item shall not be shown in a view, e.g.
790  * files not matching the mime filter
791  * @see matchesMimeFilter
792  * @see setMimeFilter
793  */
794  virtual bool matchesMimeFilter(const KFileItem &) const;
795 
796 #if KIOCORE_BUILD_DEPRECATED_SINCE(5, 90)
797  /**
798  * Called by the public matchesFilter() to do the
799  * actual filtering. Those methods may be reimplemented to customize
800  * filtering.
801  * @param name the name to filter
802  * @param filters a list of regular expressions for filtering
803  *
804  * @deprecated Since 5.90, removed from the public API as it has no users.
805  */
806  // TODO KF6 remove
807  KIOCORE_DEPRECATED_VERSION(5, 90, "Removed from the public API as it has no users.")
808  virtual bool doNameFilter(const QString &name, const QList<QRegExp> &filters) const;
809 #endif
810 
811  /**
812  * Called by the public matchesMimeFilter() to do the
813  * actual filtering. Those methods may be reimplemented to customize
814  * filtering.
815  * @param mimeType the MIME type to filter
816  * @param filters the list of MIME types to filter
817  */
818  // TODO KF6 remove
819  virtual bool doMimeFilter(const QString &mimeType, const QStringList &filters) const;
820 
821  // Not _ENABLED_ because this is a virtual method
822 #if KIOCORE_BUILD_DEPRECATED_SINCE(5, 82)
823  /**
824  * Reimplement to customize error handling
825  * @deprecated since 5.82, connect to the jobError() signal instead
826  */
827  KIOCORE_DEPRECATED_VERSION(5, 82, "Connect to the jobError() signal instead")
828  virtual void handleError(KIO::Job *);
829 #endif
830 
831  // Not _ENABLED_ because this is a virtual method
832 #if KIOCORE_BUILD_DEPRECATED_SINCE(5, 81)
833  /**
834  * Reimplement to customize error handling
835  * @deprecated since 5.81, use handleError. Since 5.82, jobError() is emitted instead for the two
836  * cases where handleErrorMessage was emitted (invalid URL, protocol not supporting listing).
837  */
838  KIOCORE_DEPRECATED_VERSION(5, 81, "For 5.81 and older releases use handleError(); since 5.82 connect to the jobError() signal instead")
839  virtual void handleErrorMessage(const QString &message);
840 #endif
841 
842  /**
843  * Reimplemented by KDirLister to associate windows with jobs
844  * @since 5.0
845  */
846  virtual void jobStarted(KIO::ListJob *);
847 
848 private:
849  friend class KCoreDirListerPrivate;
850  std::unique_ptr<KCoreDirListerPrivate> d;
851 };
852 
853 Q_DECLARE_OPERATORS_FOR_FLAGS(KCoreDirLister::OpenUrlFlags)
854 
855 #endif
Q_PROPERTY(...)
void stop(Ekos::AlignState mode)
qulonglong filesize_t
64-bit file size
Definition: global.h:39
Helper class for the kiojob used to list and update a directory.
WhichItems
Used by items() and itemsForDir() to specify whether you want all items for a directory or just the f...
Q_SIGNALSQ_SIGNALS
A namespace for KIO globals.
QString message
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon Feb 6 2023 04:00:00 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.