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#include <MauiKit4/Core/fmh.h>
28
29#include "filebrowsing_export.h"
30
31namespace FMH
32{
33 /**
34 * @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.
35 *
36 * 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.
37 * @see informer
38 *
39 * The following code snippet demonstrates the usage, by listing all the content in the downloads and pictures local directories.
40 *
41 * @code
42 * #include <QCoreApplication>
43 * #include <QDebug>
44 * #include <QUrl>
45 * #include <QObject>
46 * #include <iostream>
47 *
48 * #include <MauiKit4/FileBrowsing/fileloader.h>
49 * #include <MauiKit4/FileBrowsing/fmstatic.h>
50 *
51 * int main(int argc, char *argv[])
52 * {
53 * QCoreApplication a(argc, argv);
54 *
55 * FMH::FileLoader loader;
56 * QStringList urls = {FMStatic::DownloadsPath, FMStatic::PicturesPath};
57 *
58 * QObject::connect(&loader, &FMH::FileLoader::itemsReady, [=](FMH::MODEL_LIST items, QList<QUrl> urls) {
59 * for(const auto &item : items)
60 * qDebug() << item[FMH::MODEL_KEY::NAME];
61 *
62 * qDebug() << "items ready for:" << urls << items.length(); });
63 *
64 * QObject::connect(&loader, &FMH::FileLoader::finished, [=](FMH::MODEL_LIST items, QList<QUrl> urls) {
65 * qDebug() << "Finished process" << urls << items.length(); });
66 *
67 * loader.setBatchCount(10);
68 * loader.requestPath(QUrl::fromStringList(urls), true);
69 *
70 * return a.exec();
71 * }
72 * @endcode
73 *
74 */
75 class FILEBROWSING_EXPORT FileLoader : public QObject
76 {
77 Q_OBJECT
78
79 public:
80
81 /**
82 * @brief Creates a new instance, the execution will be moved to a different thread.
83 */
84 FileLoader(QObject *parent = nullptr);
86
87 /**
88 * @brief Set the amount of items to be dispatched via the `itemReady` signal.
89 * 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.
90 * @see itemsReady
91 * @param count the amount of items
92 */
93 void setBatchCount(const uint &count);
94
95 /**
96 * @brief The amount of items which will be dispatched while iterating throughout all the given directories.
97 */
98 uint batchCount() const;
99
100 /**
101 * @brief Sends the request to start iterating throughout all the given location URLs, and with the given parameters.
102 * @param urls the list of directories or locations to iterate. This operation only supports local directories and tags.
103 * @param recursive Whether the iteration should be done recursively and navigate sub-folder structures
104 * @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.
105 * @param filters the possible QDir filters. By default this is set to `QDir::Files`.
106 * @param limit the limit of files to retrieve. By default this is is set to `99999`.
107 */
108 void requestPath(const QList<QUrl> &urls, const bool &recursive, const QStringList &nameFilters = {}, const QDir::Filters &filters = QDir::Files, const uint &limit = 99999);
109
110 /**
111 * @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.
112 * @see FMStatic::getFileInfoModel
113 * @param url the file URL retrieved
114 * @return the formed data model based on the given file URL
115 */
116 static std::function<FMH::MODEL(const QUrl &url)> informer;
117
118 private Q_SLOTS:
119 /**
120 * @private
121 */
122 void getFiles(QList<QUrl> paths, bool recursive, const QStringList &nameFilters, const QDir::Filters &filters, uint limit);
123
124 Q_SIGNALS:
125 /**
126 * @brief Emitted once the operation has completely finished retrieving all the existing files or reached the limit number of requested files.
127 * @param items all of the retrieved items. The items data model is created using the `informer` callback function.
128 * @see informer
129 * @param urls the list of directories given for which the item were retrieved.
130 */
132
133 /**
134 * @private
135 */
136 void start(QList<QUrl> urls, bool recursive, QStringList nameFilters, QDir::Filters filters, uint limit);
137
138 /**
139 * @brief Emitted when the batch of file items is ready.
140 * @see setBatchCount
141 * @param items the packaged list of items, formed by the `informer` callback function.
142 * @param urls the list of directories given for which the item were retrieved.
143 */
145
146 /**
147 * @brief Emitted for every single item that becomes available.
148 * @param item the packaged item, formed by the `informer` callback function.
149 * @param urls the list of directories given for which the item were retrieved.
150 */
152
153 private:
154 QThread *m_thread;
155 uint m_batchCount = 1500;
156 };
157}
158
The FileLoader class asynchronously loads batches of files from a given list of local directories or ...
Definition fileloader.h:76
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:116
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
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Mon Nov 4 2024 16:32:33 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.