File indexing completed on 2023-09-24 04:08:35

0001 /*
0002     This file is part of the KDE project
0003     SPDX-FileCopyrightText: 1999 David Faure <faure@kde.org>
0004     SPDX-FileCopyrightText: 2001, 2002, 2004-2006 Michael Brade <brade@kde.org>
0005 
0006     SPDX-License-Identifier: LGPL-2.0-or-later
0007 */
0008 
0009 #ifndef KCOREDIRLISTER_H
0010 #define KCOREDIRLISTER_H
0011 
0012 #include "kdirnotify.h" // TODO KF6: remove
0013 #include "kfileitem.h"
0014 
0015 #include <QString>
0016 #include <QStringList>
0017 #include <QUrl>
0018 
0019 #include <memory>
0020 
0021 class KJob;
0022 namespace KIO
0023 {
0024 class Job;
0025 class ListJob;
0026 }
0027 
0028 class KCoreDirListerPrivate;
0029 
0030 /**
0031  * @class KCoreDirLister kcoredirlister.h <KCoreDirLister>
0032  *
0033  * @short Helper class for the kiojob used to list and update a directory.
0034  *
0035  * The dir lister deals with the kiojob used to list and update a directory
0036  * and has signals for the user of this class (e.g. konqueror view or
0037  * kdesktop) to create/destroy its items when asked.
0038  *
0039  * This class is independent from the graphical representation of the dir
0040  * (icon container, tree view, ...) and it stores the items (as KFileItems).
0041  *
0042  * Typical usage :
0043  * @li Create an instance.
0044  * @li Connect to at least update, clear, itemsAdded, and itemsDeleted.
0045  * @li Call openUrl - the signals will be called.
0046  * @li Reuse the instance when opening a new url (openUrl).
0047  * @li Destroy the instance when not needed anymore (usually destructor).
0048  *
0049  * Advanced usage : call openUrl with OpenUrlFlag::Keep to list directories
0050  * without forgetting the ones previously read (e.g. for a tree view)
0051  *
0052  * @author Michael Brade <brade@kde.org>
0053  */
0054 class KIOCORE_EXPORT KCoreDirLister : public QObject
0055 {
0056     friend class KCoreDirListerCache;
0057     friend struct KCoreDirListerCacheDirectoryData;
0058 
0059     Q_OBJECT
0060     Q_PROPERTY(bool autoUpdate READ autoUpdate WRITE setAutoUpdate)
0061 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 100)
0062     Q_PROPERTY(bool showingDotFiles READ showingDotFiles WRITE setShowingDotFiles)
0063 #endif
0064     Q_PROPERTY(bool showHiddenFiles READ showHiddenFiles WRITE setShowHiddenFiles)
0065     Q_PROPERTY(bool dirOnlyMode READ dirOnlyMode WRITE setDirOnlyMode)
0066     Q_PROPERTY(bool delayedMimeTypes READ delayedMimeTypes WRITE setDelayedMimeTypes)
0067     Q_PROPERTY(bool requestMimeTypeWhileListing READ requestMimeTypeWhileListing WRITE setRequestMimeTypeWhileListing)
0068     Q_PROPERTY(QString nameFilter READ nameFilter WRITE setNameFilter)
0069     Q_PROPERTY(QStringList mimeFilter READ mimeFilters WRITE setMimeFilter RESET clearMimeFilter)
0070     Q_PROPERTY(bool autoErrorHandlingEnabled READ autoErrorHandlingEnabled WRITE setAutoErrorHandlingEnabled)
0071 
0072 public:
0073     /**
0074      * @see OpenUrlFlags
0075      */
0076     enum OpenUrlFlag {
0077         NoFlags = 0x0, ///< No additional flags specified.
0078 
0079         Keep = 0x1, ///< Previous directories aren't forgotten
0080         ///< (they are still watched by kdirwatch and their items
0081         ///< are kept for this KCoreDirLister). This is useful for e.g.
0082         ///< a treeview.
0083 
0084         Reload = 0x2, ///< Indicates whether to use the cache or to reread
0085                       ///< the directory from the disk.
0086                       ///< Use only when opening a dir not yet listed by this lister
0087                       ///< without using the cache. Otherwise use updateDirectory.
0088     };
0089 
0090     /**
0091      * Stores a combination of #OpenUrlFlag values.
0092      */
0093     Q_DECLARE_FLAGS(OpenUrlFlags, OpenUrlFlag)
0094 
0095     /**
0096      * Create a directory lister.
0097      */
0098     KCoreDirLister(QObject *parent = nullptr);
0099 
0100     /**
0101      * Destroy the directory lister.
0102      */
0103     ~KCoreDirLister() override;
0104 
0105     /**
0106      * Run the directory lister on the given url.
0107      *
0108      * This method causes KCoreDirLister to emit @em all the items of @p dirUrl, in any case.
0109      * Depending on @p flags, either clear() or clearDir(const QUrl &) will be emitted first.
0110      *
0111      * The newItems() signal may be emitted more than once to supply you with KFileItems, up
0112      * until the signal completed() is emitted (and isFinished() returns @c true).
0113      *
0114      * @param dirUrl the directory URL.
0115      * @param flags whether to keep previous directories, and whether to reload, see OpenUrlFlags
0116      * @return @c true if successful, @c false otherwise (e.g. if @p dirUrl is invalid)
0117      *
0118      * @note clearDir(const QUrl &) is emitted since 5.79; before that it was clear(const QUrl &)
0119      * which has been deprecated.
0120      */
0121     virtual bool openUrl(const QUrl &dirUrl, OpenUrlFlags flags = NoFlags); // TODO KF6: remove virtual, change bool to void
0122 
0123     /**
0124      * Stop listing all directories currently being listed.
0125      *
0126      * Emits canceled() if there was at least one job running.
0127      * Emits listingDirCanceled(const QUrl &) for each stopped job if there is more than one
0128      * directory being watched by this KCoreDirLister.
0129      *
0130      * @note listingDirCanceled(const QUrl &) is emitted since 5.79; before that it was
0131      * canceled(const QUrl &) which has been deprecated.
0132      */
0133     virtual void stop(); // TODO KF6: remove virtual
0134 
0135     /**
0136      * Stop listing the given directory.
0137      *
0138      * Emits canceled() if the killed job was the last running one.
0139      * Emits listingDirCanceled(const QUrl &) for the killed job if there is more than one
0140      * directory being watched by this KCoreDirLister.
0141      *
0142      * No signal is emitted if there was no job running for @p dirUrl.
0143      *
0144      * @param dirUrl the directory URL
0145      *
0146      * @note listingDirCanceled(const QUrl &) is emitted since 5.79; before that it was
0147      * canceled(const QUrl &) which has been deprecated.
0148      */
0149     virtual void stop(const QUrl &dirUrl); // TODO KF6: remove virtual
0150 
0151     /**
0152      * Stop listening for further changes in the given directory.
0153      * 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.
0154      * This call selectively removes a directory from sending future notifications to this KCoreDirLister.
0155      *
0156      * @param dirUrl the directory URL.
0157      * @since 5.91
0158      */
0159     void forgetDirs(const QUrl &dirUrl);
0160 
0161     /**
0162      * @return @c true if the "delayed MIME types" feature was enabled
0163      * @see setDelayedMimeTypes
0164      */
0165     bool delayedMimeTypes() const;
0166 
0167     /**
0168      * Delayed MIME types feature:
0169      * If enabled, MIME types will be fetched on demand, which leads to a
0170      * faster initial directory listing, where icons get progressively replaced
0171      * with the correct one while KMimeTypeResolver is going through the items
0172      * with unknown or imprecise MIME type (e.g. files with no extension or an
0173      * unknown extension).
0174      */
0175     void setDelayedMimeTypes(bool delayedMimeTypes);
0176 
0177     /**
0178      * Checks whether KDirWatch will automatically update directories. This is
0179      * enabled by default.
0180      *
0181      * @return @c true if KDirWatch is used to automatically update directories
0182      */
0183     bool autoUpdate() const;
0184 
0185     /**
0186      * Toggle automatic directory updating, when a directory changes (using KDirWatch).
0187      *
0188      * @param enable set to @c true to enable or @c false to disable
0189      */
0190     virtual void setAutoUpdate(bool enable); // TODO KF6: remove virtual
0191 
0192 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 100)
0193     /**
0194      * Checks whether hidden files (files whose name start with '.') will be shown.
0195      * By default this option is disabled (hidden files are not shown).
0196      *
0197      * @return @c true if dot files are shown, @c false otherwise
0198      *
0199      * @deprecated since 5.100, use showHiddenFiles instead.
0200      *
0201      * @see setShowingDotFiles()
0202      */
0203     KIOCORE_DEPRECATED_VERSION(5, 100, "Use showHiddenFiles instead.")
0204     bool showingDotFiles() const;
0205 #endif
0206 
0207     /**
0208      * Checks whether hidden files (e.g. files whose name start with '.' on Unix) will be shown.
0209      * By default this option is disabled (hidden files are not shown).
0210      *
0211      * @return @c true if hidden files are shown, @c false otherwise
0212      *
0213      * @see setShowHiddenFiles()
0214      * @since 5.100
0215      */
0216     bool showHiddenFiles() const;
0217 
0218     // Not _ENABLED_ because this is a virtual method
0219 #if KIOCORE_BUILD_DEPRECATED_SINCE(5, 100)
0220     /**
0221      * Toggles whether hidden files (files whose name start with '.') are shown, by default
0222      * hidden files are not shown.
0223      *
0224      * You need to call emitChanges() afterwards.
0225      *
0226      * @param showDotFiles set to @c true/false to show/hide hidden files respectively
0227      *
0228      * @deprecated since 5.100, use setShowHiddenFiles() instead.
0229      *
0230      * @see showingDotFiles()
0231      */
0232     KIOCORE_DEPRECATED_VERSION(5, 100, "Use setShowHiddenFiles instead.")
0233     virtual void setShowingDotFiles(bool showDotFiles);
0234 #endif
0235 
0236     /**
0237      * Toggles whether hidden files (e.g. files whose name start with '.' on Unix) are shown/
0238      * By default hidden files are not shown.
0239      *
0240      * You need to call emitChanges() afterwards.
0241      *
0242      * @param showHiddenFiles set to @c true/false to show/hide hidden files respectively
0243      *
0244      * @see showHiddenFiles()
0245      * @since 5.100
0246      */
0247     void setShowHiddenFiles(bool showHiddenFiles);
0248 
0249     /**
0250      * Checks whether this KCoreDirLister only lists directories or all items (directories and
0251      * files), by default all items are listed.
0252      *
0253      * @return @c true if only directories are listed, @c false otherwise
0254      *
0255      * @see setDirOnlyMode(bool)
0256      */
0257     bool dirOnlyMode() const;
0258 
0259     /**
0260      * Call this to list only directories (by default all items (directories and files)
0261      * are listed).
0262      *
0263      * You need to call emitChanges() afterwards.
0264      *
0265      * @param dirsOnly set to @c true to list only directories
0266      */
0267     virtual void setDirOnlyMode(bool dirsOnly); // TODO KF6: remove virtual
0268 
0269     /**
0270      * Checks whether this KCoreDirLister requests the MIME type of files from the worker.
0271      *
0272      * Enabling this will tell the worker used for listing that it should try to
0273      * determine the mime type of entries while listing them. This potentially
0274      * reduces the speed at which entries are listed but ensures mime types are
0275      * immediately available when an entry is added, greatly speeding up things
0276      * like mime type filtering.
0277      *
0278      * By default this is disabled.
0279      *
0280      * @return @c true if the worker is asked for MIME types, @c false otherwise.
0281      *
0282      * @see setRequestMimeTypeWhileListing(bool)
0283      *
0284      * @since 5.82
0285      */
0286     bool requestMimeTypeWhileListing() const;
0287 
0288     /**
0289      * Toggles whether to request MIME types from the worker or in-process.
0290      *
0291      * @param request set to @c true to request MIME types from the worker.
0292      *
0293      * @note If this is changed while the lister is already listing a directory,
0294      * it will only have an effect the next time openUrl() is called.
0295      *
0296      * @see requestMimeTypeWhileListing()
0297      *
0298      * @since 5.82
0299      */
0300     void setRequestMimeTypeWhileListing(bool request);
0301 
0302     /**
0303      * Returns the top level URL that is listed by this KCoreDirLister.
0304      *
0305      * It might be different from the one given with openUrl() if there was a
0306      * redirection. If you called openUrl() with OpenUrlFlag::Keep this is the
0307      * first url opened (e.g. in a treeview this is the root).
0308      *
0309      * @return the url used by this instance to list the files
0310      */
0311     QUrl url() const;
0312 
0313     /**
0314      * Returns all URLs that are listed by this KCoreDirLister. This is only
0315      * useful if you called openUrl() with OpenUrlFlag::Keep, as it happens in a
0316      * treeview, for example. (Note that the base url is included in the list
0317      * as well, of course.)
0318      *
0319      * @return a list of all listed URLs
0320      */
0321     QList<QUrl> directories() const;
0322 
0323     /**
0324      * Actually emit the changes made with setShowHiddenFiles, setDirOnlyMode,
0325      * setNameFilter and setMimeFilter.
0326      */
0327     virtual void emitChanges(); // TODO KF6: remove virtual
0328 
0329     /**
0330      * Update the directory @p dirUrl. This method causes KCoreDirLister to @em only emit
0331      * the items of @p dirUrl that actually changed compared to the current state in the
0332      * cache, and updates the cache.
0333      *
0334      * The current implementation calls updateDirectory automatically for local files, using
0335      * KDirWatch (if autoUpdate() is @c true), but it might be useful to force an update manually.
0336      *
0337      * @param dirUrl the directory URL
0338      */
0339     virtual void updateDirectory(const QUrl &dirUrl); // TODO KF6: remove virtual
0340 
0341     /**
0342      * Returns @c true if no I/O operation is currently in progress.
0343      *
0344      * @return @c true if finished, @c false otherwise
0345      */
0346     bool isFinished() const;
0347 
0348     /**
0349      * Returns the file item of the URL.
0350      *
0351      * Can return an empty KFileItem.
0352      * @return the file item for url() itself (".")
0353      */
0354     KFileItem rootItem() const;
0355 
0356     /**
0357      * Find an item by its URL.
0358      * @param url the item URL
0359      * @return the KFileItem
0360      */
0361     virtual KFileItem findByUrl(const QUrl &url) const; // TODO KF6: remove virtual
0362 
0363     /**
0364      * Find an item by its name.
0365      * @param name the item name
0366      * @return the KFileItem
0367      */
0368     virtual KFileItem findByName(const QString &name) const; // TODO KF6: remove virtual
0369 
0370     /**
0371      * Set a name filter to only list items matching this name, e.g.\ "*.cpp".
0372      *
0373      * You can set more than one filter by separating them with whitespace, e.g
0374      * "*.cpp *.h".
0375      * Note: the directory is not automatically reloaded.
0376      * You need to call emitChanges() afterwards.
0377      *
0378      * @param filter the new filter, QString() to disable filtering
0379      * @see matchesFilter
0380      */
0381     virtual void setNameFilter(const QString &filter); // TODO KF6: remove virtual
0382 
0383     /**
0384      * Returns the current name filter, as set via setNameFilter()
0385      * @return the current name filter, can be QString() if filtering
0386      *         is turned off
0387      */
0388     QString nameFilter() const;
0389 
0390     /**
0391      * Set MIME type based filter to only list items matching the given MIME types.
0392      *
0393      * NOTE: setting the filter does not automatically reload directory.
0394      * Also calling this function will not affect any named filter already set.
0395      *
0396      * You need to call emitChanges() afterwards.
0397      *
0398      * @param mimeList a list of MIME types
0399      *
0400      * @see clearMimeFilter
0401      * @see matchesMimeFilter
0402      */
0403     virtual void setMimeFilter(const QStringList &mimeList); // TODO KF6: remove virtual
0404 
0405 #if KIOCORE_BUILD_DEPRECATED_SINCE(5, 100)
0406     /**
0407      * Filtering should be done with KFileFilter. This will be implemented in a later
0408      * revision of KCoreDirLister. This method may be removed then.
0409      *
0410      * Set MIME type based exclude filter to only list items not matching the given MIME types
0411      *
0412      * NOTE: setting the filter does not automatically reload directory.
0413      * Also calling this function will not affect any named filter already set.
0414      *
0415      * @param mimeList a list of MIME types
0416      * @see clearMimeFilter
0417      * @see matchesMimeFilter
0418      * @internal
0419      * @deprecated since 5.100, no known users.
0420      */
0421     KIOCORE_DEPRECATED_VERSION(5, 100, "No known users.")
0422     void setMimeExcludeFilter(const QStringList &mimeList);
0423 #endif
0424 
0425     /**
0426      * Clears the MIME type based filter.
0427      *
0428      * You need to call emitChanges() afterwards.
0429      *
0430      * @see setMimeFilter
0431      */
0432     virtual void clearMimeFilter(); // TODO KF6: remove virtual
0433 
0434     /**
0435      * Returns the list of MIME type based filters, as set via setMimeFilter().
0436      * @return the list of MIME type based filters. Empty, when no MIME type filter is set.
0437      */
0438     QStringList mimeFilters() const;
0439 
0440 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 94)
0441     /**
0442      * Checks whether @p name matches a filter in the list of name filters.
0443      *
0444      * @return @c true if @p name matches a filter in the list, otherwise @c false.
0445      *
0446      * @deprecated since 5.94, no known users.
0447      *
0448      * @see setNameFilter()
0449      */
0450     KIOCORE_DEPRECATED_VERSION(5, 94, "No known users.")
0451     bool matchesFilter(const QString &name) const;
0452 #endif
0453 
0454 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 94)
0455     /**
0456      * Checks whether @p mimeType matches a filter in the list of MIME types.
0457      *
0458      * @param mimeType the MIME type to find in the filter list
0459      *
0460      * @return @c true if @p mimeType matches a filter in the list, otherwise @c false
0461      *
0462      * @deprecated since 5.94, no known users.
0463      *
0464      * @see setMimeFilter.
0465      */
0466     KIOCORE_DEPRECATED_VERSION(5, 94, "No known users.")
0467     bool matchesMimeFilter(const QString &mimeType) const;
0468 #endif
0469 
0470     /**
0471      * Used by items() and itemsForDir() to specify whether you want
0472      * all items for a directory or just the filtered ones.
0473      */
0474     enum WhichItems {
0475         AllItems = 0,
0476         FilteredItems = 1,
0477     };
0478 
0479     /**
0480      * Returns the items listed for the current url().
0481      *
0482      * This method will @em not start listing a directory, you should only call
0483      * this in a slot connected to the finished() signal.
0484      *
0485      * The items in the KFileItemList are copies of the items used by KCoreDirLister.
0486      *
0487      * @param which specifies whether the returned list will contain all entries
0488      *              or only the ones that passed the nameFilter(), mimeFilter(),
0489      *              etc. Note that the latter causes iteration over all the
0490      *              items, filtering them. If this is too slow for you, use the
0491      *              newItems() signal, sending out filtered items in chunks
0492      * @return the items listed for the current url()
0493      */
0494     KFileItemList items(WhichItems which = FilteredItems) const;
0495 
0496     /**
0497      * Returns the items listed for the given @p dirUrl.
0498      * This method will @em not start listing @p dirUrl, you should only call
0499      * this in a slot connected to the finished() signal.
0500      *
0501      * The items in the KFileItemList are copies of the items used by KCoreDirLister.
0502      *
0503      * @param dirUrl specifies the url for which the items should be returned. This
0504      *            is only useful if you use KCoreDirLister with multiple URLs
0505      *            i.e. using bool OpenUrlFlag::Keep in openUrl()
0506      * @param which specifies whether the returned list will contain all entries
0507      *              or only the ones that passed the nameFilter, mimeFilter, etc.
0508      *              Note that the latter causes iteration over all the items,
0509      *              filtering them. If this is too slow for you, use the
0510      * newItems() signal, sending out filtered items in chunks
0511      *
0512      * @return the items listed for @p dirUrl
0513      */
0514     KFileItemList itemsForDir(const QUrl &dirUrl, WhichItems which = FilteredItems) const;
0515 
0516     /**
0517      * Return the KFileItem for the given URL, if it was listed recently and it's
0518      * still in the cache, which is always the case if a directory view is currently
0519      * showing this item. If not, then it might be in the cache; if not in the cache a
0520      * a null KFileItem will be returned.
0521      *
0522      * If you really need a KFileItem for this URL in all cases, then use KIO::stat() instead.
0523      *
0524      * @since 4.2
0525      */
0526     static KFileItem cachedItemForUrl(const QUrl &url);
0527 
0528     /**
0529      * Checks whether auto error handling is enabled.
0530      * If enabled, it will show an error dialog to the user when an
0531      * error occurs (assuming the application links to KIOWidgets).
0532      * It is turned on by default.
0533      * @return @c true if auto error handling is enabled, @c false otherwise
0534      * @see setAutoErrorHandlingEnabled()
0535      * @since 5.82
0536      */
0537     bool autoErrorHandlingEnabled() const;
0538 
0539     /**
0540      * Enable or disable auto error handling.
0541      * If enabled, it will show an error dialog to the user when an
0542      * error occurs. It is turned on by default.
0543      * @param enable true to enable auto error handling, false to disable
0544      * @param parent the parent widget for the error dialogs, can be @c nullptr for
0545      *               top-level
0546      * @see autoErrorHandlingEnabled()
0547      * @since 5.82
0548      */
0549     void setAutoErrorHandlingEnabled(bool enable);
0550 
0551 Q_SIGNALS:
0552     /**
0553      * Tell the view that this KCoreDirLister has started to list @p dirUrl. Note that this
0554      * does @em not imply that there is really a job running! I.e. KCoreDirLister::jobs()
0555      * may return an empty list, in which case the items are taken from the cache.
0556      *
0557      * The view knows that openUrl should start it, so this might seem useless, but the view
0558      * also needs to know when an automatic update happens.
0559      * @param dirUrl the URL to list
0560      */
0561     void started(const QUrl &dirUrl);
0562 
0563     /**
0564      * Tell the view that listing is finished. There are no jobs running anymore.
0565      */
0566     void completed(); // clazy:exclude=overloaded-signal
0567 
0568 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 79)
0569     /**
0570      * Tell the view that the listing of the directory @p dirUrl is finished.
0571      * There might be other running jobs left.
0572      *
0573      * @param dirUrl the directory URL
0574      *
0575      * @deprecated since 5.79, use KCoreDirLister::listingDirCompleted(const QUrl &)
0576      */
0577     KIOCORE_DEPRECATED_VERSION(5, 79, "Use KCoreDirLister::listingDirCompleted(const QUrl &)")
0578     void completed(const QUrl &dirUrl); // clazy:exclude=overloaded-signal
0579 #endif
0580 
0581     /**
0582      * Tell the view that the listing of the directory @p dirUrl is finished.
0583      * There might be other running jobs left.
0584      *
0585      * @param dirUrl the directory URL
0586      *
0587      * @since 5.79
0588      */
0589     void listingDirCompleted(const QUrl &dirUrl);
0590 
0591     /**
0592      * Tell the view that the user canceled the listing. No running jobs are left.
0593      */
0594     void canceled(); // clazy:exclude=overloaded-signal
0595 
0596 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 79)
0597     /**
0598      * Tell the view that the listing of the directory @p dirUrl was canceled.
0599      * There might be other running jobs left.
0600      *
0601      * @param dirUrl the directory URL
0602      *
0603      * @deprecated since 5.79, use KCoreDirLister::listingDirCanceled(const QUrl &)
0604      */
0605     KIOCORE_DEPRECATED_VERSION(5, 79, "use KCoreDirLister::listingDirCanceled(const QUrl &)")
0606     void canceled(const QUrl &dirUrl); // clazy:exclude=overloaded-signal
0607 #endif
0608 
0609     /**
0610      * Tell the view that the listing of the directory @p dirUrl was canceled.
0611      * There might be other running jobs left.
0612      *
0613      * @param dirUrl the directory URL
0614      *
0615      * @since 5.79
0616      */
0617     void listingDirCanceled(const QUrl &dirUrl);
0618 
0619 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 80)
0620     /**
0621      * Signal a redirection.
0622      * Only emitted if there's just one directory to list, i.e. most
0623      * probably openUrl() has been called without OpenUrlFlag::Keep.
0624      *
0625      * @param dirUrl the new URL
0626      *
0627      * @deprecated since 5.80, use redirection(const QUrl &, const QUrl &)
0628      */
0629     KIOCORE_DEPRECATED_VERSION(5, 80, "Use redirection(const QUrl &, const QUrl &)")
0630     void redirection(const QUrl &_url); // clazy:exclude=overloaded-signal
0631 #endif
0632 
0633     /**
0634      * Signals a redirection.
0635      *
0636      * @param oldUrl the original URL
0637      * @param newUrl the new URL
0638      */
0639     void redirection(const QUrl &oldUrl, const QUrl &newUrl); // clazy:exclude=overloaded-signal
0640 
0641     /**
0642      * Signals to the view to remove all items (when e.g.\ going from dirA to dirB).
0643      * Make sure to connect to this signal to avoid having duplicate items in the view.
0644      */
0645     void clear(); // clazy:exclude=overloaded-signal
0646 
0647 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 79)
0648     /**
0649      * Signals to the view to clear all items from directory @p dirUrl.
0650      *
0651      * This is only emitted if the lister is holding more than one directory.
0652      *
0653      * @param dirUrl the directory that the view should clear all items from
0654      *
0655      * @deprecated since 5.79, use clearDir(const QUrl &)
0656      */
0657     KIOCORE_DEPRECATED_VERSION(5, 79, "Use clearDir(const QUrl &)")
0658     void clear(const QUrl &dirUrl); // clazy:exclude=overloaded-signal
0659 #endif
0660 
0661     /**
0662      * Signals to the view to clear all items from directory @p dirUrl.
0663      *
0664      * This is only emitted if the lister is holding more than one directory.
0665      *
0666      * @param dirUrl the directory that the view should clear all items from
0667      *
0668      * @since 5.79
0669      */
0670     void clearDir(const QUrl &dirUrl);
0671 
0672     /**
0673      * Signal new items.
0674      *
0675      * @param items a list of new items
0676      */
0677     void newItems(const KFileItemList &items);
0678 
0679     /**
0680      * Signal that new items were found during directory listing.
0681      * Alternative signal emitted at the same time as newItems(),
0682      * but itemsAdded also passes the url of the parent directory.
0683      *
0684      * @param items a list of new items
0685      * @since 4.2
0686      */
0687     void itemsAdded(const QUrl &directoryUrl, const KFileItemList &items);
0688 
0689 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 100)
0690     /**
0691      * Send a list of items filtered-out by MIME type.
0692      * @param items the list of filtered items
0693      *
0694      * @deprecated since 5.100, no known users.
0695      */
0696     KIOCORE_DEPRECATED_VERSION(5, 100, "No known users.")
0697     void itemsFilteredByMime(const KFileItemList &items);
0698 #endif
0699 
0700     /**
0701      * Signal that items have been deleted
0702      *
0703      * @since 4.1.2
0704      * @param items the list of deleted items
0705      */
0706     void itemsDeleted(const KFileItemList &items);
0707 
0708     /**
0709      * Signal an item to refresh (its MIME-type/icon/name has changed).
0710      * Note: KFileItem::refresh has already been called on those items.
0711      * @param items the items to refresh. This is a list of pairs, where
0712      * the first item in the pair is the OLD item, and the second item is the
0713      * NEW item. This allows to track which item has changed, especially after
0714      * a renaming.
0715      */
0716     void refreshItems(const QList<QPair<KFileItem, KFileItem>> &items);
0717 
0718     /**
0719      * Emitted to display information about running jobs.
0720      * Examples of message are "Resolving host", "Connecting to host...", etc.
0721      * @param msg the info message
0722      */
0723     void infoMessage(const QString &msg);
0724 
0725     /**
0726      * Progress signal showing the overall progress of the KCoreDirLister.
0727      * This allows using a progress bar very easily. (see QProgressBar)
0728      * @param percent the progress in percent
0729      */
0730     void percent(int percent);
0731 
0732     /**
0733      * Emitted when we know the size of the jobs.
0734      * @param size the total size in bytes
0735      */
0736     void totalSize(KIO::filesize_t size);
0737 
0738     /**
0739      * Regularly emitted to show the progress of this KCoreDirLister.
0740      * @param size the processed size in bytes
0741      */
0742     void processedSize(KIO::filesize_t size);
0743 
0744     /**
0745      * Emitted to display information about the speed of the jobs.
0746      * @param bytes_per_second the speed in bytes/s
0747      */
0748     void speed(int bytes_per_second);
0749 
0750     /**
0751      * Emitted if listing a directory fails with an error.
0752      * A typical implementation in a widgets-based application
0753      * would show a message box by calling this in a slot connected to this signal:
0754      * <tt>job->uiDelegate()->showErrorMessage()</tt>
0755      * Many applications might prefer to embed the error message though
0756      * (e.g. by using the KMessageWidget class, from the KWidgetsAddons Framework).
0757      * @param the job with an error
0758      * @since 5.82
0759      */
0760     void jobError(KIO::Job *job);
0761 
0762 protected:
0763 #if KIOCORE_ENABLE_DEPRECATED_SINCE(4, 3)
0764     /// @deprecated Since 4.3, and unused, ignore this
0765     enum Changes { NONE = 0, NAME_FILTER = 1, MIME_FILTER = 2, DOT_FILES = 4, DIR_ONLY_MODE = 8 };
0766 #endif
0767 
0768     /**
0769      * Called for every new item before emitting newItems().
0770      * You may reimplement this method in a subclass to implement your own
0771      * filtering.
0772      * The default implementation filters out ".." and everything not matching
0773      * the name filter(s)
0774      * @return @c true if the item is "ok".
0775      *         @c false if the item shall not be shown in a view, e.g.
0776      * files not matching a pattern *.cpp ( KFileItem::isHidden())
0777      * @see matchesFilter
0778      * @see setNameFilter
0779      */
0780     virtual bool matchesFilter(const KFileItem &) const;
0781 
0782     /**
0783      * Called for every new item before emitting newItems().
0784      * You may reimplement this method in a subclass to implement your own
0785      * filtering.
0786      * The default implementation filters out everything not matching
0787      * the mime filter(s)
0788      * @return @c true if the item is "ok".
0789      *         @c false if the item shall not be shown in a view, e.g.
0790      * files not matching the mime filter
0791      * @see matchesMimeFilter
0792      * @see setMimeFilter
0793      */
0794     virtual bool matchesMimeFilter(const KFileItem &) const;
0795 
0796 #if KIOCORE_BUILD_DEPRECATED_SINCE(5, 90)
0797     /**
0798      * Called by the public matchesFilter() to do the
0799      * actual filtering. Those methods may be reimplemented to customize
0800      * filtering.
0801      * @param name the name to filter
0802      * @param filters a list of regular expressions for filtering
0803      *
0804      * @deprecated Since 5.90, removed from the public API as it has no users.
0805      */
0806     // TODO KF6 remove
0807     KIOCORE_DEPRECATED_VERSION(5, 90, "Removed from the public API as it has no users.")
0808     virtual bool doNameFilter(const QString &name, const QList<QRegExp> &filters) const;
0809 #endif
0810 
0811     /**
0812      * Called by the public matchesMimeFilter() to do the
0813      * actual filtering. Those methods may be reimplemented to customize
0814      * filtering.
0815      * @param mimeType the MIME type to filter
0816      * @param filters the list of MIME types to filter
0817      */
0818     // TODO KF6 remove
0819     virtual bool doMimeFilter(const QString &mimeType, const QStringList &filters) const;
0820 
0821     // Not _ENABLED_ because this is a virtual method
0822 #if KIOCORE_BUILD_DEPRECATED_SINCE(5, 82)
0823     /**
0824      * Reimplement to customize error handling
0825      * @deprecated since 5.82, connect to the jobError() signal instead
0826      */
0827     KIOCORE_DEPRECATED_VERSION(5, 82, "Connect to the jobError() signal instead")
0828     virtual void handleError(KIO::Job *);
0829 #endif
0830 
0831     // Not _ENABLED_ because this is a virtual method
0832 #if KIOCORE_BUILD_DEPRECATED_SINCE(5, 81)
0833     /**
0834      * Reimplement to customize error handling
0835      * @deprecated since 5.81, use handleError. Since 5.82, jobError() is emitted instead for the two
0836      * cases where handleErrorMessage was emitted (invalid URL, protocol not supporting listing).
0837      */
0838     KIOCORE_DEPRECATED_VERSION(5, 81, "For 5.81 and older releases use handleError(); since 5.82 connect to the jobError() signal instead")
0839     virtual void handleErrorMessage(const QString &message);
0840 #endif
0841 
0842     /**
0843      * Reimplemented by KDirLister to associate windows with jobs
0844      * @since 5.0
0845      */
0846     virtual void jobStarted(KIO::ListJob *);
0847 
0848 private:
0849     friend class KCoreDirListerPrivate;
0850     std::unique_ptr<KCoreDirListerPrivate> d;
0851 };
0852 
0853 Q_DECLARE_OPERATORS_FOR_FLAGS(KCoreDirLister::OpenUrlFlags)
0854 
0855 #endif