| 1 |
/* |
| 2 |
* SPDX-FileCopyrightText: 2015 Boudewijn Rempt <[email protected]> |
| 3 |
* SPDX-FileCopyrightText: 2015 Friedrich W. H. Kossebau <[email protected]> |
| 4 |
* |
| 5 |
* SPDX-License-Identifier: LGPL-2.1-or-later |
| 6 |
*/ |
| 7 |
|
| 8 |
#ifndef KORESOURCEPATHS_H |
| 9 |
#define KORESOURCEPATHS_H |
| 10 |
|
| 11 |
#include <QString> |
| 12 |
|
| 13 |
#include <kowidgets_export.h> |
| 14 |
|
| 15 |
|
| 16 |
|
| 17 |
namespace KoResourcePaths |
| 18 |
{ |
| 19 |
enum SearchOption { NoSearchOptions = 0, |
| 20 |
Recursive = 1, |
| 21 |
NoDuplicates = 2, |
| 22 |
IgnoreExecBit = 4 |
| 23 |
}; |
| 24 |
Q_DECLARE_FLAGS(SearchOptions, SearchOption) |
| 25 |
|
| 26 |
/** |
| 27 |
* Adds suffixes for types. |
| 28 |
* |
| 29 |
* You may add as many as you need, but it is advised that there |
| 30 |
* is exactly one to make writing definite. |
| 31 |
* |
| 32 |
* The later a suffix is added, the higher its priority. Note, that the |
| 33 |
* suffix should end with / but doesn't have to start with one (as prefixes |
| 34 |
* should end with one). So adding a suffix for app_pics would look |
| 35 |
* like KoStandardPaths::addResourceType("app_pics", "data", "app/pics"); |
| 36 |
* |
| 37 |
* @param type Specifies a short descriptive string to access |
| 38 |
* files of this type. |
| 39 |
* @param basetype Specifies an already known type, or 0 if none |
| 40 |
* @param relativeName Specifies a directory relative to the basetype |
| 41 |
* @param priority if true, the directory is added before any other, |
| 42 |
* otherwise after |
| 43 |
*/ |
| 44 |
KOWIDGETS_EXPORT void addResourceType(const char *type, const char *basetype, |
| 45 |
const QString &relativeName, bool priority = true); |
| 46 |
|
| 47 |
|
| 48 |
/** |
| 49 |
* Adds absolute path at the beginning of the search path for |
| 50 |
* particular types (for example in case of icons where |
| 51 |
* the user specifies extra paths). |
| 52 |
* |
| 53 |
* You shouldn't need this function in 99% of all cases besides |
| 54 |
* adding user-given paths. |
| 55 |
* |
| 56 |
* @param type Specifies a short descriptive string to access files |
| 57 |
* of this type. |
| 58 |
* @param dir Points to directory where to look for this specific |
| 59 |
* type. Non-existent directories may be saved but pruned. |
| 60 |
* @param priority if true, the directory is added before any other, |
| 61 |
* otherwise after |
| 62 |
*/ |
| 63 |
KOWIDGETS_EXPORT void addResourceDir(const char *type, const QString &dir, bool priority = true); |
| 64 |
|
| 65 |
/** |
| 66 |
* Tries to find a resource in the following order: |
| 67 |
* @li All PREFIX/\<relativename> paths (most recent first). |
| 68 |
* @li All absolute paths (most recent first). |
| 69 |
* |
| 70 |
* The filename should be a filename relative to the base dir |
| 71 |
* for resources. So is a way to get the path to libkdecore.la |
| 72 |
* to findResource("lib", "libkdecore.la"). KStandardDirs will |
| 73 |
* then look into the subdir lib of all elements of all prefixes |
| 74 |
* ($KDEDIRS) for a file libkdecore.la and return the path to |
| 75 |
* the first one it finds (e.g. /opt/kde/lib/libkdecore.la). |
| 76 |
* |
| 77 |
* Example: |
| 78 |
* @code |
| 79 |
* QString iconfilename = KStandardPaths::findResource("icon",QString("oxygen/22x22/apps/ktip.png")); |
| 80 |
* @endcode |
| 81 |
* |
| 82 |
* @param type The type of the wanted resource |
| 83 |
* @param fileName A relative filename of the resource. |
| 84 |
* |
| 85 |
* @return A full path to the filename specified in the second |
| 86 |
* argument, or QString() if not found. |
| 87 |
*/ |
| 88 |
|
| 89 |
KOWIDGETS_EXPORT QString findResource(const char *type, const QString &fileName); |
| 90 |
|
| 91 |
/** |
| 92 |
* Tries to find all directories whose names consist of the |
| 93 |
* specified type and a relative path. So |
| 94 |
* findDirs("xdgdata-apps", "Settings") would return |
| 95 |
* @li /home/joe/.local/share/applications/Settings/ |
| 96 |
* @li /usr/share/applications/Settings/ |
| 97 |
* |
| 98 |
* (from the most local to the most global) |
| 99 |
* |
| 100 |
* Note that it appends @c / to the end of the directories, |
| 101 |
* so you can use this right away as directory names. |
| 102 |
* |
| 103 |
* @param type The type of the base directory. |
| 104 |
* @param reldir Relative directory. |
| 105 |
* |
| 106 |
* @return A list of matching directories, or an empty |
| 107 |
* list if the resource specified is not found. |
| 108 |
*/ |
| 109 |
KOWIDGETS_EXPORT QStringList findDirs(const char *type, const QString &reldir); |
| 110 |
|
| 111 |
/** |
| 112 |
* Tries to find all resources with the specified type. |
| 113 |
* |
| 114 |
* The function will look into all specified directories |
| 115 |
* and return all filenames in these directories. |
| 116 |
* |
| 117 |
* The "most local" files are returned before the "more global" files. |
| 118 |
* |
| 119 |
* @param type The type of resource to locate directories for. |
| 120 |
* @param filter Only accept filenames that fit to filter. The filter |
| 121 |
* may consist of an optional directory and a QRegExp |
| 122 |
* wildcard expression. E.g. <tt>"images\*.jpg"</tt>. |
| 123 |
* Use QString() if you do not want a filter. |
| 124 |
* @param options if the flags passed include Recursive, subdirectories |
| 125 |
* will also be search; if NoDuplicates is passed then only entries with |
| 126 |
* unique filenames will be returned eliminating duplicates. |
| 127 |
* |
| 128 |
* @return List of all the files whose filename matches the |
| 129 |
* specified filter. |
| 130 |
*/ |
| 131 |
KOWIDGETS_EXPORT QStringList findAllResources(const char *type, |
| 132 |
const QString &filter = QString(), |
| 133 |
SearchOptions options = NoSearchOptions); |
| 134 |
|
| 135 |
/** |
| 136 |
* @param type The type of resource |
| 137 |
* @return The list of possible directories for the specified @p type. |
| 138 |
* The function updates the cache if possible. If the resource |
| 139 |
* type specified is unknown, it will return an empty list. |
| 140 |
* Note, that the directories are assured to exist beside the save |
| 141 |
* location, which may not exist, but is returned anyway. |
| 142 |
*/ |
| 143 |
KOWIDGETS_EXPORT QStringList resourceDirs(const char *type); |
| 144 |
|
| 145 |
/** |
| 146 |
* Finds a location to save files into for the given type |
| 147 |
* in the user's home directory. |
| 148 |
* |
| 149 |
* @param type The type of location to return. |
| 150 |
* @param suffix A subdirectory name. |
| 151 |
* Makes it easier for you to create subdirectories. |
| 152 |
* You can't pass filenames here, you _have_ to pass |
| 153 |
* directory names only and add possible filename in |
| 154 |
* that directory yourself. A directory name always has a |
| 155 |
* trailing slash ('/'). |
| 156 |
* @param create If set, saveLocation() will create the directories |
| 157 |
* needed (including those given by @p suffix). |
| 158 |
* |
| 159 |
* @return A path where resources of the specified type should be |
| 160 |
* saved, or QString() if the resource type is unknown. |
| 161 |
*/ |
| 162 |
KOWIDGETS_EXPORT QString saveLocation(const char *type, const QString &suffix = QString(), bool create = true); |
| 163 |
|
| 164 |
/** |
| 165 |
* This function is just for convenience. It simply calls |
| 166 |
* KoResourcePaths::findResource((type, filename). |
| 167 |
* |
| 168 |
* @param type The type of the wanted resource, see KStandardDirs |
| 169 |
* @param filename A relative filename of the resource |
| 170 |
* |
| 171 |
* @return A full path to the filename specified in the second |
| 172 |
* argument, or QString() if not found |
| 173 |
**/ |
| 174 |
KOWIDGETS_EXPORT QString locate(const char *type, const QString &filename); |
| 175 |
|
| 176 |
/** |
| 177 |
* This function is much like locate. However it returns a |
| 178 |
* filename suitable for writing to. No check is made if the |
| 179 |
* specified @p filename actually exists. Missing directories |
| 180 |
* can be created. If @p filename is only a directory, without a |
| 181 |
* specific file, @p filename must have a trailing slash. |
| 182 |
* |
| 183 |
* @param type The type of the wanted resource, see KStandardDirs |
| 184 |
* @param filename A relative filename of the resource |
| 185 |
* @param createDir Whether to create missing directory |
| 186 |
* |
| 187 |
* @return A full path to the filename specified in the second |
| 188 |
* argument, or QString() if not found |
| 189 |
**/ |
| 190 |
KOWIDGETS_EXPORT QString locateLocal(const char *type, const QString &filename, bool createDir = false); |
| 191 |
} |
| 192 |
|
| 193 |
Q_DECLARE_OPERATORS_FOR_FLAGS(KoResourcePaths::SearchOptions) |
| 194 |
|
| 195 |
#endif // KORESOURCEPATHS_H |