MauiKit File Browsing

fileloader.h
1/***
2 * Copyright (C) 2018 Camilo Higuita
3 * This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
4 * This is free software, and you are welcome to redistribute it
5 * under certain conditions; type `show c' for details.
6 *
7 * This program is free software: you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License as published by
9 * the Free Software Foundation, either version 3 of the License, or
10 * (at your option) any later version.
11 *
12 * This program is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
16 *
17 * You should have received a copy of the GNU General Public License
18 * along with this program. If not, see <http://www.gnu.org/licenses/>.
19 ***/
20#pragma once
21
22#include <QDir>
23#include <QObject>
24#include <QThread>
25#include <QUrl>
26
27
28#if QT_VERSION < QT_VERSION_CHECK(6, 0, 0)
29#include <MauiKit3/Core/fmh.h>
30#else
31#include <MauiKit4/Core/fmh.h>
32#endif
33
34#include "filebrowsing_export.h"
35
36namespace FMH
37{
38 /**
39 * @brief The FileLoader class asynchronously loads batches of files from a given list of local directories or tags, allowing to filter them by name, mime-types, and much more.
40 *
41 * The execution of the file listing will be moved into a different thread, - so to retrieve the information you will depend on the exposed signals and the `informer` callback function to give structure to the data.
42 * @see informer
43 *
44 * The following code snippet demonstrates the usage, by listing all the content in the downloads and pictures local directories.
45 *
46 * @code
47 * #include <QCoreApplication>
48 * #include <QDebug>
49 * #include <QUrl>
50 * #include <QObject>
51 * #include <iostream>
52 *
53 * #include <MauiKit4/FileBrowsing/fileloader.h>
54 * #include <MauiKit4/FileBrowsing/fmstatic.h>
55 *
56 * int main(int argc, char *argv[])
57 * {
58 * QCoreApplication a(argc, argv);
59 *
60 * FMH::FileLoader loader;
61 * QStringList urls = {FMStatic::DownloadsPath, FMStatic::PicturesPath};
62 *
63 * QObject::connect(&loader, &FMH::FileLoader::itemsReady, [=](FMH::MODEL_LIST items, QList<QUrl> urls) {
64 * for(const auto &item : items)
65 * qDebug() << item[FMH::MODEL_KEY::NAME];
66 *
67 * qDebug() << "items ready for:" << urls << items.length(); });
68 *
69 * QObject::connect(&loader, &FMH::FileLoader::finished, [=](FMH::MODEL_LIST items, QList<QUrl> urls) {
70 * qDebug() << "Finished process" << urls << items.length(); });
71 *
72 * loader.setBatchCount(10);
73 * loader.requestPath(QUrl::fromStringList(urls), true);
74 *
75 * return a.exec();
76 * }
77 * @endcode
78 *
79 */
80 class FILEBROWSING_EXPORT FileLoader : public QObject
81 {
82 Q_OBJECT
83
84 public:
85
86 /**
87 * @brief Creates a new instance, the execution will be moved to a different thread.
88 */
89 FileLoader(QObject *parent = nullptr);
91
92 /**
93 * @brief Set the amount of items to be dispatched via the `itemReady` signal.
94 * This allows to dispatch item files which are ready and don't have to wait for the operation to finished completely, in case there are too many files to wait for.
95 * @see itemsReady
96 * @param count the amount of items
97 */
98 void setBatchCount(const uint &count);
99
100 /**
101 * @brief The amount of items which will be dispatched while iterating throughout all the given directories.
102 */
103 uint batchCount() const;
104
105 /**
106 * @brief Sends the request to start iterating throughout all the given location URLs, and with the given parameters.
107 * @param urls the list of directories or locations to iterate. This operation only supports local directories and tags.
108 * @param recursive Whether the iteration should be done recursively and navigate sub-folder structures
109 * @param nameFilters a list of filtering strings, this can be used with regular expressions, for example `*.jpg` to only list files ending with the given suffix. Dy default this is set to an empty array, so nothing will be filtered.
110 * @param filters the possible QDir filters. By default this is set to `QDir::Files`.
111 * @param limit the limit of files to retrieve. By default this is is set to `99999`.
112 */
113 void requestPath(const QList<QUrl> &urls, const bool &recursive, const QStringList &nameFilters = {}, const QDir::Filters &filters = QDir::Files, const uint &limit = 99999);
114
115 /**
116 * @brief A callback function which structures the retrieved file URLs, with the required information. This callback function will receive the file URL, and expects a FMH::MODEL to be formed and returned. By default this informer callback function is set to `FMStatic::getFileInfoModel`, which retrieves basic information about a file.
117 * @see FMStatic::getFileInfoModel
118 * @param url the file URL retrieved
119 * @return the formed data model based on the given file URL
120 */
121 static std::function<FMH::MODEL(const QUrl &url)> informer;
122
123 private Q_SLOTS:
124 /**
125 * @private
126 */
127 void getFiles(QList<QUrl> paths, bool recursive, const QStringList &nameFilters, const QDir::Filters &filters, uint limit);
128
129 Q_SIGNALS:
130 /**
131 * @brief Emitted once the operation has completely finished retrieving all the existing files or reached the limit number of requested files.
132 * @param items all of the retrieved items. The items data model is created using the `informer` callback function.
133 * @see informer
134 * @param urls the list of directories given for which the item were retrieved.
135 */
137
138 /**
139 * @private
140 */
141 void start(QList<QUrl> urls, bool recursive, QStringList nameFilters, QDir::Filters filters, uint limit);
142
143 /**
144 * @brief Emitted when the batch of file items is ready.
145 * @see setBatchCount
146 * @param items the packaged list of items, formed by the `informer` callback function.
147 * @param urls the list of directories given for which the item were retrieved.
148 */
150
151 /**
152 * @brief Emitted for every single item that becomes available.
153 * @param item the packaged item, formed by the `informer` callback function.
154 * @param urls the list of directories given for which the item were retrieved.
155 */
157
158 private:
159 QThread *m_thread;
160 uint m_batchCount = 1500;
161 };
162}
163
The FileLoader class asynchronously loads batches of files from a given list of local directories or ...
Definition fileloader.h:81
static std::function< FMH::MODEL(const QUrl &url) informer)
A callback function which structures the retrieved file URLs, with the required information.
Definition fileloader.h:121
void finished(FMH::MODEL_LIST items, QList< QUrl > urls)
Emitted once the operation has completely finished retrieving all the existing files or reached the l...
void itemReady(FMH::MODEL item, QList< QUrl > urls)
Emitted for every single item that becomes available.
void itemsReady(FMH::MODEL_LIST items, QList< QUrl > urls)
Emitted when the batch of file items is ready.
Q_SCRIPTABLE Q_NOREPLY void start()
QHash< MODEL_KEY, QString > MODEL
typedef Filters
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:15:24 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.