KIO

kcoredirlister.h
1/*
2 This file is part of the KDE project
3 SPDX-FileCopyrightText: 1999 David Faure <faure@kde.org>
4 SPDX-FileCopyrightText: 2001, 2002, 2004-2006 Michael Brade <brade@kde.org>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8
9#ifndef KCOREDIRLISTER_H
10#define KCOREDIRLISTER_H
11
12#include "kfileitem.h"
13
14#include <QString>
15#include <QStringList>
16#include <QUrl>
17
18#include <memory>
19
20class KJob;
21namespace KIO
22{
23class Job;
24class ListJob;
25}
26
27class KCoreDirListerPrivate;
28
29/**
30 * @class KCoreDirLister kcoredirlister.h <KCoreDirLister>
31 *
32 * @short Helper class for the kiojob used to list and update a directory.
33 *
34 * The dir lister deals with the kiojob used to list and update a directory
35 * and has signals for the user of this class (e.g. konqueror view or
36 * kdesktop) to create/destroy its items when asked.
37 *
38 * This class is independent from the graphical representation of the dir
39 * (icon container, tree view, ...) and it stores the items (as KFileItems).
40 *
41 * Typical usage :
42 * @li Create an instance.
43 * @li Connect to at least update, clear, itemsAdded, and itemsDeleted.
44 * @li Call openUrl - the signals will be called.
45 * @li Reuse the instance when opening a new url (openUrl).
46 * @li Destroy the instance when not needed anymore (usually destructor).
47 *
48 * Advanced usage : call openUrl with OpenUrlFlag::Keep to list directories
49 * without forgetting the ones previously read (e.g. for a tree view)
50 *
51 * @author Michael Brade <brade@kde.org>
52 */
53class KIOCORE_EXPORT KCoreDirLister : public QObject
54{
55 friend class KCoreDirListerCache;
56 friend struct KCoreDirListerCacheDirectoryData;
57
58 Q_OBJECT
59 Q_PROPERTY(bool autoUpdate READ autoUpdate WRITE setAutoUpdate)
60 Q_PROPERTY(bool showHiddenFiles READ showHiddenFiles WRITE setShowHiddenFiles)
61 Q_PROPERTY(bool dirOnlyMode READ dirOnlyMode WRITE setDirOnlyMode)
62 Q_PROPERTY(bool delayedMimeTypes READ delayedMimeTypes WRITE setDelayedMimeTypes)
63 Q_PROPERTY(bool requestMimeTypeWhileListing READ requestMimeTypeWhileListing WRITE setRequestMimeTypeWhileListing)
64 Q_PROPERTY(QString nameFilter READ nameFilter WRITE setNameFilter)
65 Q_PROPERTY(QStringList mimeFilter READ mimeFilters WRITE setMimeFilter RESET clearMimeFilter)
66 Q_PROPERTY(bool autoErrorHandlingEnabled READ autoErrorHandlingEnabled WRITE setAutoErrorHandlingEnabled)
67
68public:
69 /**
70 * @see OpenUrlFlags
71 */
73 NoFlags = 0x0, ///< No additional flags specified.
74
75 Keep = 0x1, ///< Previous directories aren't forgotten
76 ///< (they are still watched by kdirwatch and their items
77 ///< are kept for this KCoreDirLister). This is useful for e.g.
78 ///< a treeview.
79
80 Reload = 0x2, ///< Indicates whether to use the cache or to reread
81 ///< the directory from the disk.
82 ///< Use only when opening a dir not yet listed by this lister
83 ///< without using the cache. Otherwise use updateDirectory.
84 };
85
86 /**
87 * Stores a combination of #OpenUrlFlag values.
88 */
89 Q_DECLARE_FLAGS(OpenUrlFlags, OpenUrlFlag)
90
91 /**
92 * Create a directory lister.
93 */
94 KCoreDirLister(QObject *parent = nullptr);
95
96 /**
97 * Destroy the directory lister.
98 */
99 ~KCoreDirLister() override;
100
101 /**
102 * Run the directory lister on the given url.
103 *
104 * This method causes KCoreDirLister to emit @em all the items of @p dirUrl, in any case.
105 * Depending on @p flags, either clear() or clearDir(const QUrl &) will be emitted first.
106 *
107 * The newItems() signal may be emitted more than once to supply you with KFileItems, up
108 * until the signal completed() is emitted (and isFinished() returns @c true).
109 *
110 * @param dirUrl the directory URL.
111 * @param flags whether to keep previous directories, and whether to reload, see OpenUrlFlags
112 * @return @c true if successful, @c false otherwise (e.g. if @p dirUrl is invalid)
113 */
114 bool openUrl(const QUrl &dirUrl, OpenUrlFlags flags = NoFlags); // TODO KF6: change bool to void
115
116 /**
117 * Stop listing all directories currently being listed.
118 *
119 * Emits canceled() if there was at least one job running.
120 * Emits listingDirCanceled(const QUrl &) for each stopped job if there is more than one
121 * directory being watched by this KCoreDirLister.
122 */
123 void stop();
124
125 /**
126 * Stop listing the given directory.
127 *
128 * Emits canceled() if the killed job was the last running one.
129 * Emits listingDirCanceled(const QUrl &) for the killed job if there is more than one
130 * directory being watched by this KCoreDirLister.
131 *
132 * No signal is emitted if there was no job running for @p dirUrl.
133 *
134 * @param dirUrl the directory URL
135 */
136 void stop(const QUrl &dirUrl);
137
138 /**
139 * Stop listening for further changes in the given directory.
140 * 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.
141 * This call selectively removes a directory from sending future notifications to this KCoreDirLister.
142 *
143 * @param dirUrl the directory URL.
144 * @since 5.91
145 */
146 void forgetDirs(const QUrl &dirUrl);
147
148 /**
149 * @return @c true if the "delayed MIME types" feature was enabled
150 * @see setDelayedMimeTypes
151 */
152 bool delayedMimeTypes() const;
153
154 /**
155 * Delayed MIME types feature:
156 * If enabled, MIME types will be fetched on demand, which leads to a
157 * faster initial directory listing, where icons get progressively replaced
158 * with the correct one while KMimeTypeResolver is going through the items
159 * with unknown or imprecise MIME type (e.g. files with no extension or an
160 * unknown extension).
161 */
162 void setDelayedMimeTypes(bool delayedMimeTypes);
163
164 /**
165 * Checks whether KDirWatch will automatically update directories. This is
166 * enabled by default.
167 *
168 * @return @c true if KDirWatch is used to automatically update directories
169 */
170 bool autoUpdate() const;
171
172 /**
173 * Toggle automatic directory updating, when a directory changes (using KDirWatch).
174 *
175 * @param enable set to @c true to enable or @c false to disable
176 */
177 void setAutoUpdate(bool enable);
178
179 /**
180 * Checks whether hidden files (e.g. files whose name start with '.' on Unix) will be shown.
181 * By default this option is disabled (hidden files are not shown).
182 *
183 * @return @c true if hidden files are shown, @c false otherwise
184 *
185 * @see setShowHiddenFiles()
186 * @since 5.100
187 */
188 bool showHiddenFiles() const;
189
190 /**
191 * Toggles whether hidden files (e.g. files whose name start with '.' on Unix) are shown/
192 * By default hidden files are not shown.
193 *
194 * You need to call emitChanges() afterwards.
195 *
196 * @param showHiddenFiles set to @c true/false to show/hide hidden files respectively
197 *
198 * @see showHiddenFiles()
199 * @since 5.100
200 */
201 void setShowHiddenFiles(bool showHiddenFiles);
202
203 /**
204 * Checks whether this KCoreDirLister only lists directories or all items (directories and
205 * files), by default all items are listed.
206 *
207 * @return @c true if only directories are listed, @c false otherwise
208 *
209 * @see setDirOnlyMode(bool)
210 */
211 bool dirOnlyMode() const;
212
213 /**
214 * Call this to list only directories (by default all items (directories and files)
215 * are listed).
216 *
217 * You need to call emitChanges() afterwards.
218 *
219 * @param dirsOnly set to @c true to list only directories
220 */
221 void setDirOnlyMode(bool dirsOnly);
222
223 /**
224 * Checks whether this KCoreDirLister requests the MIME type of files from the worker.
225 *
226 * Enabling this will tell the worker used for listing that it should try to
227 * determine the mime type of entries while listing them. This potentially
228 * reduces the speed at which entries are listed but ensures mime types are
229 * immediately available when an entry is added, greatly speeding up things
230 * like mime type filtering.
231 *
232 * By default this is disabled.
233 *
234 * @return @c true if the worker is asked for MIME types, @c false otherwise.
235 *
236 * @see setRequestMimeTypeWhileListing(bool)
237 *
238 * @since 5.82
239 */
240 bool requestMimeTypeWhileListing() const;
241
242 /**
243 * Toggles whether to request MIME types from the worker or in-process.
244 *
245 * @param request set to @c true to request MIME types from the worker.
246 *
247 * @note If this is changed while the lister is already listing a directory,
248 * it will only have an effect the next time openUrl() is called.
249 *
250 * @see requestMimeTypeWhileListing()
251 *
252 * @since 5.82
253 */
254 void setRequestMimeTypeWhileListing(bool request);
255
256 /**
257 * Returns the top level URL that is listed by this KCoreDirLister.
258 *
259 * It might be different from the one given with openUrl() if there was a
260 * redirection. If you called openUrl() with OpenUrlFlag::Keep this is the
261 * first url opened (e.g. in a treeview this is the root).
262 *
263 * @return the url used by this instance to list the files
264 */
265 QUrl url() const;
266
267 /**
268 * Returns all URLs that are listed by this KCoreDirLister. This is only
269 * useful if you called openUrl() with OpenUrlFlag::Keep, as it happens in a
270 * treeview, for example. (Note that the base url is included in the list
271 * as well, of course.)
272 *
273 * @return a list of all listed URLs
274 */
275 QList<QUrl> directories() const;
276
277 /**
278 * Actually emit the changes made with setShowHiddenFiles, setDirOnlyMode,
279 * setNameFilter and setMimeFilter.
280 */
281 void emitChanges();
282
283 /**
284 * Update the directory @p dirUrl. This method causes KCoreDirLister to @em only emit
285 * the items of @p dirUrl that actually changed compared to the current state in the
286 * cache, and updates the cache.
287 *
288 * The current implementation calls updateDirectory automatically for local files, using
289 * KDirWatch (if autoUpdate() is @c true), but it might be useful to force an update manually.
290 *
291 * @param dirUrl the directory URL
292 */
293 void updateDirectory(const QUrl &dirUrl);
294
295 /**
296 * Returns @c true if no I/O operation is currently in progress.
297 *
298 * @return @c true if finished, @c false otherwise
299 */
300 bool isFinished() const;
301
302 /**
303 * Returns the file item of the URL.
304 *
305 * Can return an empty KFileItem.
306 * @return the file item for url() itself (".")
307 */
308 KFileItem rootItem() const;
309
310 /**
311 * Find an item by its URL.
312 * @param url the item URL
313 * @return the KFileItem
314 */
315 KFileItem findByUrl(const QUrl &url) const;
316
317 /**
318 * Find an item by its name.
319 * @param name the item name
320 * @return the KFileItem
321 */
322 KFileItem findByName(const QString &name) const;
323
324 /**
325 * Set a name filter to only list items matching this name, e.g.\ "*.cpp".
326 *
327 * You can set more than one filter by separating them with whitespace, e.g
328 * "*.cpp *.h".
329 * Note: the directory is not automatically reloaded.
330 * You need to call emitChanges() afterwards.
331 *
332 * @param filter the new filter, QString() to disable filtering
333 * @see matchesFilter
334 */
335 void setNameFilter(const QString &filter);
336
337 /**
338 * Returns the current name filter, as set via setNameFilter()
339 * @return the current name filter, can be QString() if filtering
340 * is turned off
341 */
342 QString nameFilter() const;
343
344 /**
345 * Set MIME type based filter to only list items matching the given MIME types.
346 *
347 * NOTE: setting the filter does not automatically reload directory.
348 * Also calling this function will not affect any named filter already set.
349 *
350 * You need to call emitChanges() afterwards.
351 *
352 * @param mimeList a list of MIME types
353 *
354 * @see clearMimeFilter
355 * @see matchesMimeFilter
356 */
357 void setMimeFilter(const QStringList &mimeList);
358
359 /**
360 * Filtering should be done with KFileFilter. This will be implemented in a later
361 * revision of KCoreDirLister. This method may be removed then.
362 *
363 * Set MIME type based exclude filter to only list items not matching the given MIME types
364 *
365 * NOTE: setting the filter does not automatically reload directory.
366 * Also calling this function will not affect any named filter already set.
367 *
368 * @param mimeList a list of MIME types
369 * @see clearMimeFilter
370 * @see matchesMimeFilter
371 */
372 void setMimeExcludeFilter(const QStringList &mimeList);
373
374 /**
375 * Clears the MIME type based filter.
376 *
377 * You need to call emitChanges() afterwards.
378 *
379 * @see setMimeFilter
380 */
381 void clearMimeFilter();
382
383 /**
384 * Returns the list of MIME type based filters, as set via setMimeFilter().
385 * @return the list of MIME type based filters. Empty, when no MIME type filter is set.
386 */
387 QStringList mimeFilters() const;
388
389 /**
390 * Used by items() and itemsForDir() to specify whether you want
391 * all items for a directory or just the filtered ones.
392 */
394 AllItems = 0,
395 FilteredItems = 1,
396 };
397
398 /**
399 * Returns the items listed for the current url().
400 *
401 * This method will @em not start listing a directory, you should only call
402 * this in a slot connected to the finished() signal.
403 *
404 * The items in the KFileItemList are copies of the items used by KCoreDirLister.
405 *
406 * @param which specifies whether the returned list will contain all entries
407 * or only the ones that passed the nameFilter(), mimeFilter(),
408 * etc. Note that the latter causes iteration over all the
409 * items, filtering them. If this is too slow for you, use the
410 * newItems() signal, sending out filtered items in chunks
411 * @return the items listed for the current url()
412 */
413 KFileItemList items(WhichItems which = FilteredItems) const;
414
415 /**
416 * Returns the items listed for the given @p dirUrl.
417 * This method will @em not start listing @p dirUrl, you should only call
418 * this in a slot connected to the finished() signal.
419 *
420 * The items in the KFileItemList are copies of the items used by KCoreDirLister.
421 *
422 * @param dirUrl specifies the url for which the items should be returned. This
423 * is only useful if you use KCoreDirLister with multiple URLs
424 * i.e. using bool OpenUrlFlag::Keep in openUrl()
425 * @param which specifies whether the returned list will contain all entries
426 * or only the ones that passed the nameFilter, mimeFilter, etc.
427 * Note that the latter causes iteration over all the items,
428 * filtering them. If this is too slow for you, use the
429 * newItems() signal, sending out filtered items in chunks
430 *
431 * @return the items listed for @p dirUrl
432 */
433 KFileItemList itemsForDir(const QUrl &dirUrl, WhichItems which = FilteredItems) const;
434
435 /**
436 * Return the KFileItem for the given URL, if it was listed recently and it's
437 * still in the cache, which is always the case if a directory view is currently
438 * showing this item. If not, then it might be in the cache; if not in the cache a
439 * a null KFileItem will be returned.
440 *
441 * If you really need a KFileItem for this URL in all cases, then use KIO::stat() instead.
442 *
443 */
444 static KFileItem cachedItemForUrl(const QUrl &url);
445
446 /**
447 * Checks whether auto error handling is enabled.
448 * If enabled, it will show an error dialog to the user when an
449 * error occurs (assuming the application links to KIOWidgets).
450 * It is turned on by default.
451 * @return @c true if auto error handling is enabled, @c false otherwise
452 * @see setAutoErrorHandlingEnabled()
453 * @since 5.82
454 */
455 bool autoErrorHandlingEnabled() const;
456
457 /**
458 * Enable or disable auto error handling.
459 * If enabled, it will show an error dialog to the user when an
460 * error occurs. It is turned on by default.
461 * @param enable true to enable auto error handling, false to disable
462 * @param parent the parent widget for the error dialogs, can be @c nullptr for
463 * top-level
464 * @see autoErrorHandlingEnabled()
465 * @since 5.82
466 */
467 void setAutoErrorHandlingEnabled(bool enable);
468
470 /**
471 * Tell the view that this KCoreDirLister has started to list @p dirUrl. Note that this
472 * does @em not imply that there is really a job running! I.e. KCoreDirLister::jobs()
473 * may return an empty list, in which case the items are taken from the cache.
474 *
475 * The view knows that openUrl should start it, so this might seem useless, but the view
476 * also needs to know when an automatic update happens.
477 * @param dirUrl the URL to list
478 */
479 void started(const QUrl &dirUrl);
480
481 /**
482 * Tell the view that listing is finished. There are no jobs running anymore.
483 */
484 void completed();
485
486 /**
487 * Tell the view that the listing of the directory @p dirUrl is finished.
488 * There might be other running jobs left.
489 *
490 * @param dirUrl the directory URL
491 *
492 * @since 5.79
493 */
494 void listingDirCompleted(const QUrl &dirUrl);
495
496 /**
497 * Tell the view that the user canceled the listing. No running jobs are left.
498 */
499 void canceled();
500
501 /**
502 * Tell the view that the listing of the directory @p dirUrl was canceled.
503 * There might be other running jobs left.
504 *
505 * @param dirUrl the directory URL
506 *
507 * @since 5.79
508 */
509 void listingDirCanceled(const QUrl &dirUrl);
510
511 /**
512 * Signals a redirection.
513 *
514 * @param oldUrl the original URL
515 * @param newUrl the new URL
516 */
517 void redirection(const QUrl &oldUrl, const QUrl &newUrl);
518
519 /**
520 * Signals to the view to remove all items (when e.g.\ going from dirA to dirB).
521 * Make sure to connect to this signal to avoid having duplicate items in the view.
522 */
523 void clear();
524
525 /**
526 * Signals to the view to clear all items from directory @p dirUrl.
527 *
528 * This is only emitted if the lister is holding more than one directory.
529 *
530 * @param dirUrl the directory that the view should clear all items from
531 *
532 * @since 5.79
533 */
534 void clearDir(const QUrl &dirUrl);
535
536 /**
537 * Signal new items.
538 *
539 * @param items a list of new items
540 */
541 void newItems(const KFileItemList &items);
542
543 /**
544 * Signal that new items were found during directory listing.
545 * Alternative signal emitted at the same time as newItems(),
546 * but itemsAdded also passes the url of the parent directory.
547 *
548 * @param items a list of new items
549 */
550 void itemsAdded(const QUrl &directoryUrl, const KFileItemList &items);
551
552 /**
553 * Send a list of items filtered-out by MIME type.
554 * @param items the list of filtered items
555 *
556 */
558
559 /**
560 * Signal that items have been deleted
561 *
562 * @since 4.1.2
563 * @param items the list of deleted items
564 */
565 void itemsDeleted(const KFileItemList &items);
566
567 /**
568 * Signal an item to refresh (its MIME-type/icon/name has changed).
569 * Note: KFileItem::refresh has already been called on those items.
570 * @param items the items to refresh. This is a list of pairs, where
571 * the first item in the pair is the OLD item, and the second item is the
572 * NEW item. This allows to track which item has changed, especially after
573 * a renaming.
574 */
575 void refreshItems(const QList<QPair<KFileItem, KFileItem>> &items);
576
577 /**
578 * Emitted to display information about running jobs.
579 * Examples of message are "Resolving host", "Connecting to host...", etc.
580 * @param msg the info message
581 */
582 void infoMessage(const QString &msg);
583
584 /**
585 * Progress signal showing the overall progress of the KCoreDirLister.
586 * This allows using a progress bar very easily. (see QProgressBar)
587 * @param percent the progress in percent
588 */
589 void percent(int percent);
590
591 /**
592 * Emitted when we know the size of the jobs.
593 * @param size the total size in bytes
594 */
596
597 /**
598 * Regularly emitted to show the progress of this KCoreDirLister.
599 * @param size the processed size in bytes
600 */
602
603 /**
604 * Emitted to display information about the speed of the jobs.
605 * @param bytes_per_second the speed in bytes/s
606 */
607 void speed(int bytes_per_second);
608
609 /**
610 * Emitted if listing a directory fails with an error.
611 * A typical implementation in a widgets-based application
612 * would show a message box by calling this in a slot connected to this signal:
613 * <tt>job->uiDelegate()->showErrorMessage()</tt>
614 * Many applications might prefer to embed the error message though
615 * (e.g. by using the KMessageWidget class, from the KWidgetsAddons Framework).
616 * @param the job with an error
617 * @since 5.82
618 */
619 void jobError(KIO::Job *job);
620
621protected:
622 /**
623 * Reimplemented by KDirLister to associate windows with jobs
624 * @since 5.0
625 */
626 virtual void jobStarted(KIO::ListJob *);
627
628private:
629 friend class KCoreDirListerPrivate;
630 std::unique_ptr<KCoreDirListerPrivate> d;
631};
632
633Q_DECLARE_OPERATORS_FOR_FLAGS(KCoreDirLister::OpenUrlFlags)
634
635#endif
Helper class for the kiojob used to list and update a directory.
void speed(int bytes_per_second)
Emitted to display information about the speed of the jobs.
void percent(int percent)
Progress signal showing the overall progress of the KCoreDirLister.
void totalSize(KIO::filesize_t size)
Emitted when we know the size of the jobs.
void listingDirCompleted(const QUrl &dirUrl)
Tell the view that the listing of the directory dirUrl is finished.
WhichItems
Used by items() and itemsForDir() to specify whether you want all items for a directory or just the f...
void clear()
Signals to the view to remove all items (when e.g. going from dirA to dirB).
void itemsFilteredByMime(const KFileItemList &items)
Send a list of items filtered-out by MIME type.
void jobError(KIO::Job *job)
Emitted if listing a directory fails with an error.
void started(const QUrl &dirUrl)
Tell the view that this KCoreDirLister has started to list dirUrl.
void clearDir(const QUrl &dirUrl)
Signals to the view to clear all items from directory dirUrl.
void refreshItems(const QList< QPair< KFileItem, KFileItem > > &items)
Signal an item to refresh (its MIME-type/icon/name has changed).
void redirection(const QUrl &oldUrl, const QUrl &newUrl)
Signals a redirection.
void itemsDeleted(const KFileItemList &items)
Signal that items have been deleted.
void listingDirCanceled(const QUrl &dirUrl)
Tell the view that the listing of the directory dirUrl was canceled.
void infoMessage(const QString &msg)
Emitted to display information about running jobs.
void canceled()
Tell the view that the user canceled the listing.
void newItems(const KFileItemList &items)
Signal new items.
void completed()
Tell the view that listing is finished.
void itemsAdded(const QUrl &directoryUrl, const KFileItemList &items)
Signal that new items were found during directory listing.
void processedSize(KIO::filesize_t size)
Regularly emitted to show the progress of this KCoreDirLister.
List of KFileItems, which adds a few helper methods to QList<KFileItem>.
Definition kfileitem.h:630
A KFileItem is a generic class to handle a file, local or remote.
Definition kfileitem.h:36
The base class for all jobs.
A ListJob is allows you to get the get the content of a directory.
void stop(Ekos::AlignState mode)
A namespace for KIO globals.
qulonglong filesize_t
64-bit file size
Definition global.h:35
Q_PROPERTY(...)
Q_SIGNALSQ_SIGNALS
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jul 19 2024 11:57:18 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.