Debian Codegraph @

src/libs/widgets/KoResourcePaths.h

raw
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