Warning, file /maui/mauikit-filebrowsing/src/code/tagging.h was not indexed or was modified since last indexation (in which case cross-reference links may be missing, inaccurate or erroneous).
0001 /* 0002 * Copyright 2018 Camilo Higuita <milo.h@aol.com> 0003 * 0004 * This program is free software; you can redistribute it and/or modify 0005 * it under the terms of the GNU Library General Public License as 0006 * published by the Free Software Foundation; either version 2, or 0007 * (at your option) any later version. 0008 * 0009 * This program is distributed in the hope that it will be useful, 0010 * but WITHOUT ANY WARRANTY; without even the implied warranty of 0011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 0012 * GNU General Public License for more details 0013 * 0014 * You should have received a copy of the GNU Library General Public 0015 * License along with this program; if not, write to the 0016 * Free Software Foundation, Inc., 0017 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 0018 */ 0019 0020 #pragma once 0021 0022 #include <QObject> 0023 0024 #include "filebrowsing_export.h" 0025 0026 #if QT_VERSION < QT_VERSION_CHECK(6, 0, 0) 0027 #include <MauiKit3/Core/fmh.h> 0028 #else 0029 #include <MauiKit4/Core/fmh.h> 0030 #endif 0031 0032 #define MAX_LIMIT 9999 0033 0034 class TAGDB; 0035 0036 /** 0037 * @brief The Tagging class provides quick methods to access and modify the tags associated to the files. 0038 * 0039 * @note This class follows a singleton pattern and it is thread safe, by creating a new instance for each new thread that request access to the singleton. All of the internal instances are self-handled and destroyed when the application quits. 0040 * 0041 * Graphical interfaces are provided which implement most of this class functionality and can be quickly used: 0042 * - TagsBar 0043 * - TagsDialog 0044 */ 0045 class FILEBROWSING_EXPORT Tagging : public QObject 0046 { 0047 Q_OBJECT 0048 Q_DISABLE_COPY(Tagging) 0049 0050 public: 0051 /** 0052 * @brief Returns an instance to the tagging object. 0053 * @return 0054 */ 0055 static Tagging *getInstance() 0056 { 0057 if (m_instance) 0058 return m_instance; 0059 0060 m_instance = new Tagging; 0061 return m_instance; 0062 } 0063 0064 0065 public Q_SLOTS: 0066 0067 /** 0068 * @brief Retrieve the information into a model, optionally you can pass a modifier callback function to manipulate or discard items in the model 0069 * @param query the query to be retrieved 0070 * @param modifier a callback function that sends as an argument a reference to the current item being retrieved, which can be modified in-place, and expects a boolean value to be returned to decide if such item should de added to the model or not 0071 * @return the resulting model 0072 */ 0073 const QVariantList get(const QString &query, std::function<bool(QVariantMap &item)> modifier = nullptr); 0074 0075 /** 0076 * @brief Checks if a given tag exists, it can be strictly enforced, meaning it is checked if the tag was created by the application making the request 0077 * @param tag the tag to search 0078 * @param strict whether the search should be strictly enforced. If strict is true then the tag should have been created by the app making the request, otherwise checks if the tag exists and could have been created by any other application. 0079 * @return 0080 */ 0081 bool tagExists(const QString &tag, const bool &strict = false); 0082 0083 /** 0084 * @brief Checks if a given tag is associated to a give file URL. The check can be strictly enforced, meaning the given URL was tagged by the application making the request 0085 * @param url the file URL 0086 * @param tag the tag to perform the check 0087 * @param strict strictly enforced check 0088 * @return 0089 */ 0090 bool urlTagExists(const QString &url, const QString &tag); 0091 0092 // INSERTIONS 0093 /** 0094 * @brief Adds a new tag, the newly created tag gets associated to the app making the call. If the tag already exists nothing is changed. If the tag exists the app making the request will get associated to the tag too 0095 * @param tag the name of the tag 0096 * @param color optional color for the tag 0097 * @param comment optional comment for the tag @deprecated 0098 * @return whether the operation was successful, meaning the tag was created 0099 */ 0100 bool tag(const QString &tag, const QString &color = QString(), const QString &comment = QString()); 0101 0102 /** 0103 * @brief Adds a tag to a given file URL, if the given tag doesn't exists then it gets created 0104 * @param url the file URL to be tagged 0105 * @param tag the tag to be added to the file URL 0106 * @param color @deprecated Optional color 0107 * @param comment optional comment 0108 * @return whether the operation was successful 0109 */ 0110 bool tagUrl(const QString &url, const QString &tag, const QString &color = QString(), const QString &comment = QString()); 0111 0112 // UPDATES 0113 /** 0114 * @brief Updates the tags associated to a file URL. If any of the given tags doesn't exists then they get created, if a tag associated to the current file URL is missing in the new passed tags then those get removed 0115 * @param url the file URL 0116 * @param tags the new set of tags to be associated to the file URL 0117 * @return whether the operation was successful 0118 */ 0119 bool updateUrlTags(const QString &url, const QStringList &tags, const bool &strict = false); 0120 0121 /** 0122 * @brief Updates a file URL to a new URL, preserving all associated tags. This is useful if a file is rename or moved to a new location 0123 * @param url previous file URL 0124 * @param newUrl new file URL 0125 * @return whether the operation was successful 0126 */ 0127 bool updateUrl(const QString &url, const QString &newUrl); 0128 0129 // QUERIES 0130 0131 /** 0132 * @brief Give a list of all tags associated to files @deprecated 0133 * @param strict 0134 * @return whether the operation was successful 0135 */ 0136 QVariantList getUrlsTags(const bool &strict = false); 0137 0138 /** 0139 * @brief Returns a list model of all the tags. The model can be strictly enforced to only tags that were created by the application making the call 0140 * @param strict if true returns only tags created by the application making the request 0141 * @return the model with the info of all the requested tags 0142 */ 0143 QVariantList getAllTags(const bool &strict = false); 0144 0145 /** 0146 * @brief Returns a model of all the file URLs associated to a tag, the result can be strictly enforced to only file URLs associated to a tag created by the application making the request, restrict it to a maximum limit, filter by the mime-type or just add a modifier function 0147 * @param tag the tag name to perform the search 0148 * @param strict strictly enforced to only file URLs associated to the given tag created by the application making the request 0149 * @param limit maximum limit of results 0150 * @param mimeType filter by mime-type, for example: `"image/\*"` or `"image/png"` 0151 * @param modifier a callback function that sends as an argument a reference to the current item being retrieved, which can be modified, and expects a boolean value to be returned to decide if such item should be added to the model or not 0152 * @return the result model 0153 */ 0154 QVariantList getUrls(const QString &tag, const bool &strict = false, const int &limit = MAX_LIMIT, const QString &mimeType = QStringLiteral(""), std::function<bool(QVariantMap &item)> modifier = nullptr); 0155 0156 /** 0157 * @brief Returns a model list of all the tags associated to a file URL. The result can be strictly enforced to only tags created by the application making the call 0158 * @param url the file URL 0159 * @param strict strictly enforced to only tags created by the application making the request 0160 * @return the result model 0161 */ 0162 QVariantList getUrlTags(const QString &url, const bool &strict = false); 0163 0164 // DELETE 0165 /** 0166 * @brief Given a file URL remove all the tags associated to it 0167 * @param url the file URL 0168 * @return whether the operation was successful 0169 */ 0170 bool removeUrlTags(const QString &url, const bool &strict = false); 0171 0172 /** 0173 * @brief Removes a given tag associated to a given file URL 0174 * @param url file URL 0175 * @param tag tag associated to file URL to be removed 0176 * @return whether the operation was successful 0177 */ 0178 bool removeUrlTag(const QString &url, const QString &tag); 0179 0180 /** 0181 * @brief Removes a URL with its associated tags 0182 * @param url the file URL 0183 * @return whether the operation was successful 0184 */ 0185 bool removeUrl(const QString &url); 0186 0187 /** 0188 * @brief Remove a tag 0189 */ 0190 bool removeTag(const QString &tag, const bool &strict = false); 0191 0192 /** 0193 * @brief Checks if a file URL has been marked as favorite. This works if the tagging component has been enabled, otherwise returns false as default. 0194 * @param url the file URL to be checked 0195 * @param strict strictly check if the file has been marked as favorite by the app making the request or not 0196 * @return 0197 */ 0198 bool isFav(const QUrl &url, const bool &strict = false); 0199 0200 /** 0201 * @brief If the given file has been marked as favorite then the tag is removed. This works if the tagging component has been enabled, otherwise returns false as default. 0202 * @param url the file URL 0203 * @return whether the operation has been successful 0204 */ 0205 bool unFav(const QUrl &url); 0206 0207 /** 0208 * @brief Marks a file URL as favorite. This works if the tagging component has been enabled, otherwise returns false as default. 0209 * @param url the file URL 0210 * @return whether the operation has been successful 0211 */ 0212 bool fav(const QUrl &url); 0213 0214 /** 0215 * @brief Toggle the fav tag of a given file, meaning, if a file is marked as fav then the tag gets removed and if it is not marked then the fav tag gets added. 0216 * @param url the file URL 0217 * @return whether the operation has been successful 0218 */ 0219 bool toggleFav(const QUrl &url); 0220 0221 /** 0222 * @brief Shortcut for getting a list of file URLs associated to a tag, the resulting list of URLs can be filtered by regular expression or by mime-type and limited 0223 * @param tag the tag to look up 0224 * @param filters the regular expressions list 0225 * @param strict if strict then the URLs returned are only associated to the application making the call, meaning, that such tag was added by such application only. 0226 * @param limit the maximum limit number of URLs to be returned 0227 * @param mime the mime-type filtering, for example, `"image/\*"` or `"image/png"`, `"audio/mp4"` 0228 * @return the list of file URLs 0229 */ 0230 QList<QUrl> getTagUrls(const QString &tag, const QStringList &filters, const bool &strict = false, const int &limit = 9999, const QString &mime = QStringLiteral("")); 0231 0232 /** 0233 * @brief Get all the tags available with detailed information packaged as a FMH::MODEL_LIST 0234 * @param limit the maximum numbers of tags 0235 * @return the model of tags 0236 */ 0237 FMH::MODEL_LIST getTags(const int &limit = 5); 0238 0239 /** 0240 * @brief Returns a model of tags associated to a file URL 0241 * @param url the file URL 0242 * @return model of the tags 0243 */ 0244 FMH::MODEL_LIST getUrlTags(const QUrl &url); 0245 0246 /** 0247 * @brief Adds a tag to a given file URL 0248 * @param tag the wanted tag, if the tag doesn't exists it is created 0249 * @param url the file URL 0250 * @return whether the operation has been successful 0251 */ 0252 bool addTagToUrl(const QString tag, const QUrl &url); 0253 0254 /** 0255 * @brief Removes a tag from a file URL if the tags exists 0256 * @param tag the lookup tag 0257 * @param url the file URL 0258 * @return whether the operation has been successful 0259 */ 0260 bool removeTagToUrl(const QString tag, const QUrl &url); 0261 0262 private: 0263 static Tagging *m_instance; 0264 0265 Tagging(); 0266 ~Tagging(); 0267 0268 Tagging(Tagging &&) = delete; 0269 Tagging &operator=(Tagging &&) = delete; 0270 0271 void setApp(); 0272 0273 QString appName; 0274 QString appComment; 0275 QString appOrg; 0276 0277 //register the app to the db 0278 bool app(); 0279 0280 QHash<Qt::HANDLE, TAGDB *> m_dbs; 0281 TAGDB *db(); 0282 0283 protected: 0284 static bool setTagIconName(QVariantMap &item); 0285 0286 Q_SIGNALS: 0287 void urlTagged(QString url, QString tag); 0288 void tagged(QVariantMap tag); 0289 void tagRemoved(QString tag); 0290 void urlTagRemoved(QString tag, QString url); 0291 void urlRemoved(QString url); 0292 }; 0293