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