diff options
Diffstat (limited to '')
-rw-r--r-- | libraries/elementary/src/lib/elm_app.h | 193 |
1 files changed, 193 insertions, 0 deletions
diff --git a/libraries/elementary/src/lib/elm_app.h b/libraries/elementary/src/lib/elm_app.h new file mode 100644 index 0000000..86dba27 --- /dev/null +++ b/libraries/elementary/src/lib/elm_app.h | |||
@@ -0,0 +1,193 @@ | |||
1 | /** | ||
2 | * Provide information in order to make Elementary determine the @b | ||
3 | * run time location of the software in question, so other data files | ||
4 | * such as images, sound files, executable utilities, libraries, | ||
5 | * modules and locale files can be found. | ||
6 | * | ||
7 | * @param mainfunc This is your application's main function name, | ||
8 | * whose binary's location is to be found. Providing @c NULL | ||
9 | * will make Elementary not to use it | ||
10 | * @param dom This will be used as the application's "domain", in the | ||
11 | * form of a prefix to any environment variables that may | ||
12 | * override prefix detection and the directory name, inside the | ||
13 | * standard share or data directories, where the software's | ||
14 | * data files will be looked for. | ||
15 | * @param checkfile This is an (optional) magic file's path to check | ||
16 | * for existence (and it must be located in the data directory, | ||
17 | * under the share directory provided above). Its presence will | ||
18 | * help determine the prefix found was correct. Pass @c NULL if | ||
19 | * the check is not to be done. | ||
20 | * | ||
21 | * This function allows one to re-locate the application somewhere | ||
22 | * else after compilation, if the developer wishes for easier | ||
23 | * distribution of pre-compiled binaries. | ||
24 | * | ||
25 | * The prefix system is designed to locate where the given software is | ||
26 | * installed (under a common path prefix) at run time and then report | ||
27 | * specific locations of this prefix and common directories inside | ||
28 | * this prefix like the binary, library, data and locale directories, | ||
29 | * through the @c elm_app_*_get() family of functions. | ||
30 | * | ||
31 | * Call elm_app_info_set() early on before you change working | ||
32 | * directory or anything about @c argv[0], so it gets accurate | ||
33 | * information. | ||
34 | * | ||
35 | * It will then try and trace back which file @p mainfunc comes from, | ||
36 | * if provided, to determine the application's prefix directory. | ||
37 | * | ||
38 | * The @p dom parameter provides a string prefix to prepend before | ||
39 | * environment variables, allowing a fallback to @b specific | ||
40 | * environment variables to locate the software. You would most | ||
41 | * probably provide a lowercase string there, because it will also | ||
42 | * serve as directory domain, explained next. For environment | ||
43 | * variables purposes, this string is made uppercase. For example if | ||
44 | * @c "myapp" is provided as the prefix, then the program would expect | ||
45 | * @c "MYAPP_PREFIX" as a master environment variable to specify the | ||
46 | * exact install prefix for the software, or more specific environment | ||
47 | * variables like @c "MYAPP_BIN_DIR", @c "MYAPP_LIB_DIR", @c | ||
48 | * "MYAPP_DATA_DIR" and @c "MYAPP_LOCALE_DIR", which could be set by | ||
49 | * the user or scripts before launching. If not provided (@c NULL), | ||
50 | * environment variables will not be used to override compiled-in | ||
51 | * defaults or auto detections. | ||
52 | * | ||
53 | * The @p dom string also provides a subdirectory inside the system | ||
54 | * shared data directory for data files. For example, if the system | ||
55 | * directory is @c /usr/local/share, then this directory name is | ||
56 | * appended, creating @c /usr/local/share/myapp, if it @p was @c | ||
57 | * "myapp". It is expected that the application installs data files in | ||
58 | * this directory. | ||
59 | * | ||
60 | * The @p checkfile is a file name or path of something inside the | ||
61 | * share or data directory to be used to test that the prefix | ||
62 | * detection worked. For example, your app will install a wallpaper | ||
63 | * image as @c /usr/local/share/myapp/images/wallpaper.jpg and so to | ||
64 | * check that this worked, provide @c "images/wallpaper.jpg" as the @p | ||
65 | * checkfile string. | ||
66 | * | ||
67 | * @see elm_app_compile_bin_dir_set() | ||
68 | * @see elm_app_compile_lib_dir_set() | ||
69 | * @see elm_app_compile_data_dir_set() | ||
70 | * @see elm_app_compile_locale_set() | ||
71 | * @see elm_app_prefix_dir_get() | ||
72 | * @see elm_app_bin_dir_get() | ||
73 | * @see elm_app_lib_dir_get() | ||
74 | * @see elm_app_data_dir_get() | ||
75 | * @see elm_app_locale_dir_get() | ||
76 | */ | ||
77 | EAPI void elm_app_info_set(void *mainfunc, const char *dom, const char *checkfile); | ||
78 | |||
79 | /** | ||
80 | * Provide information on the @b fallback application's binaries | ||
81 | * directory, in scenarios where they get overridden by | ||
82 | * elm_app_info_set(). | ||
83 | * | ||
84 | * @param dir The path to the default binaries directory (compile time | ||
85 | * one) | ||
86 | * | ||
87 | * @note Elementary will as well use this path to determine actual | ||
88 | * names of binaries' directory paths, maybe changing it to be @c | ||
89 | * something/local/bin instead of @c something/bin, only, for | ||
90 | * example. | ||
91 | * | ||
92 | * @warning You should call this function @b before | ||
93 | * elm_app_info_set(). | ||
94 | */ | ||
95 | EAPI void elm_app_compile_bin_dir_set(const char *dir); | ||
96 | |||
97 | /** | ||
98 | * Provide information on the @b fallback application's libraries | ||
99 | * directory, on scenarios where they get overridden by | ||
100 | * elm_app_info_set(). | ||
101 | * | ||
102 | * @param dir The path to the default libraries directory (compile | ||
103 | * time one) | ||
104 | * | ||
105 | * @note Elementary will as well use this path to determine actual | ||
106 | * names of libraries' directory paths, maybe changing it to be @c | ||
107 | * something/lib32 or @c something/lib64 instead of @c something/lib, | ||
108 | * only, for example. | ||
109 | * | ||
110 | * @warning You should call this function @b before | ||
111 | * elm_app_info_set(). | ||
112 | */ | ||
113 | EAPI void elm_app_compile_lib_dir_set(const char *dir); | ||
114 | |||
115 | /** | ||
116 | * Provide information on the @b fallback application's data | ||
117 | * directory, on scenarios where they get overridden by | ||
118 | * elm_app_info_set(). | ||
119 | * | ||
120 | * @param dir The path to the default data directory (compile time | ||
121 | * one) | ||
122 | * | ||
123 | * @note Elementary will as well use this path to determine actual | ||
124 | * names of data directory paths, maybe changing it to be @c | ||
125 | * something/local/share instead of @c something/share, only, for | ||
126 | * example. | ||
127 | * | ||
128 | * @warning You should call this function @b before | ||
129 | * elm_app_info_set(). | ||
130 | */ | ||
131 | EAPI void elm_app_compile_data_dir_set(const char *dir); | ||
132 | |||
133 | /** | ||
134 | * Provide information on the @b fallback application's locale | ||
135 | * directory, on scenarios where they get overridden by | ||
136 | * elm_app_info_set(). | ||
137 | * | ||
138 | * @param dir The path to the default locale directory (compile time | ||
139 | * one) | ||
140 | * | ||
141 | * @warning You should call this function @b before | ||
142 | * elm_app_info_set(). | ||
143 | */ | ||
144 | EAPI void elm_app_compile_locale_set(const char *dir); | ||
145 | |||
146 | /** | ||
147 | * Retrieve the application's run time prefix directory, as set by | ||
148 | * elm_app_info_set() and the way (environment) the application was | ||
149 | * run from. | ||
150 | * | ||
151 | * @return The directory prefix the application is actually using. | ||
152 | */ | ||
153 | EAPI const char *elm_app_prefix_dir_get(void); | ||
154 | |||
155 | /** | ||
156 | * Retrieve the application's run time binaries prefix directory, as | ||
157 | * set by elm_app_info_set() and the way (environment) the application | ||
158 | * was run from. | ||
159 | * | ||
160 | * @return The binaries directory prefix the application is actually | ||
161 | * using. | ||
162 | */ | ||
163 | EAPI const char *elm_app_bin_dir_get(void); | ||
164 | |||
165 | /** | ||
166 | * Retrieve the application's run time libraries prefix directory, as | ||
167 | * set by elm_app_info_set() and the way (environment) the application | ||
168 | * was run from. | ||
169 | * | ||
170 | * @return The libraries directory prefix the application is actually | ||
171 | * using. | ||
172 | */ | ||
173 | EAPI const char *elm_app_lib_dir_get(void); | ||
174 | |||
175 | /** | ||
176 | * Retrieve the application's run time data prefix directory, as | ||
177 | * set by elm_app_info_set() and the way (environment) the application | ||
178 | * was run from. | ||
179 | * | ||
180 | * @return The data directory prefix the application is actually | ||
181 | * using. | ||
182 | */ | ||
183 | EAPI const char *elm_app_data_dir_get(void); | ||
184 | |||
185 | /** | ||
186 | * Retrieve the application's run time locale prefix directory, as | ||
187 | * set by elm_app_info_set() and the way (environment) the application | ||
188 | * was run from. | ||
189 | * | ||
190 | * @return The locale directory prefix the application is actually | ||
191 | * using. | ||
192 | */ | ||
193 | EAPI const char *elm_app_locale_dir_get(void); | ||