1 /** 2 * @defgroup Elm_App App 3 * @ingroup Elementary 4 * Provide information in order to make Elementary determine the @b 5 * run time location of the software in question, so other data files 6 * such as images, sound files, executable utilities, libraries, 7 * modules and locale files can be found. 8 */ 9 10 /** 11 * @addtogroup Elm_App 12 * @{ 13 */ 14 15 /** 16 * Re-locate the application somewhere else after compilation, if the developer 17 * wishes for easier distribution of pre-compiled binaries. 18 * 19 * @param mainfunc This is your application's main function name, 20 * whose binary's location is to be found. Providing @c NULL 21 * will make Elementary not to use it 22 * @param dom This will be used as the application's "domain", in the 23 * form of a prefix to any environment variables that may 24 * override prefix detection and the directory name, inside the 25 * standard share or data directories, where the software's 26 * data files will be looked for. 27 * @param checkfile This is an (optional) magic file's path to check 28 * for existence (and it must be located in the data directory, 29 * under the share directory provided above). Its presence will 30 * help determine the prefix found was correct. Pass @c NULL if 31 * the check is not to be done. 32 * 33 * The prefix system is designed to locate where the given software is 34 * installed (under a common path prefix) at run time and then report 35 * specific locations of this prefix and common directories inside 36 * this prefix like the binary, library, data and locale directories, 37 * through the @c elm_app_*_get() family of functions. 38 * 39 * Call elm_app_info_set() early on before you change working 40 * directory or anything about @c argv[0], so it gets accurate 41 * information. 42 * 43 * It will then try and trace back which file @p mainfunc comes from, 44 * if provided, to determine the application's prefix directory. 45 * 46 * The @p dom parameter provides a string prefix to prepend before 47 * environment variables, allowing a fallback to @b specific 48 * environment variables to locate the software. You would most 49 * probably provide a lowercase string there, because it will also 50 * serve as directory domain, explained next. For environment 51 * variables purposes, this string is made uppercase. For example if 52 * @c "myapp" is provided as the prefix, then the program would expect 53 * @c "MYAPP_PREFIX" as a master environment variable to specify the 54 * exact install prefix for the software, or more specific environment 55 * variables like @c "MYAPP_BIN_DIR", @c "MYAPP_LIB_DIR", @c 56 * "MYAPP_DATA_DIR" and @c "MYAPP_LOCALE_DIR", which could be set by 57 * the user or scripts before launching. If not provided (@c NULL), 58 * environment variables will not be used to override compiled-in 59 * defaults or auto detections. 60 * 61 * The @p dom string also provides a subdirectory inside the system 62 * shared data directory for data files. For example, if the system 63 * directory is @c /usr/local/share, then this directory name is 64 * appended, creating @c /usr/local/share/myapp, if it @p was @c 65 * "myapp". It is expected that the application installs data files in 66 * this directory. 67 * 68 * The @p checkfile is a file name or path of something inside the 69 * share or data directory to be used to test that the prefix 70 * detection worked. For example, your app will install a wallpaper 71 * image as @c /usr/local/share/myapp/images/wallpaper.jpg and so to 72 * check that this worked, provide @c "images/wallpaper.jpg" as the @p 73 * checkfile string. 74 * 75 * @see elm_app_compile_bin_dir_set() 76 * @see elm_app_compile_lib_dir_set() 77 * @see elm_app_compile_data_dir_set() 78 * @see elm_app_compile_locale_set() 79 * @see elm_app_prefix_dir_get() 80 * @see elm_app_bin_dir_get() 81 * @see elm_app_lib_dir_get() 82 * @see elm_app_data_dir_get() 83 * @see elm_app_locale_dir_get() 84 * 85 * @ingroup Elm_App 86 */ 87 EAPI void elm_app_info_set(void *mainfunc, const char *dom, const char *checkfile); 88 89 /** 90 * Set a formal name to be used with the elm application. 91 * 92 * @param name Application name. 93 * 94 * @ingroup Elm_App 95 * @since 1.8 96 */ 97 EAPI void elm_app_name_set(const char *name); 98 99 /** 100 * Set the path to the '.desktop' file to be associated 101 * with the elm application. 102 * 103 * @param path The path to the '.desktop' file 104 * 105 * @warning Since this path is very environment dependent, 106 * this will hold whatever value is passed to it. 107 * 108 * @ingroup Elm_App 109 * @since 1.8 110 */ 111 EAPI void elm_app_desktop_entry_set(const char *path); 112 113 /** 114 * Provide information on the @b fallback application's binaries 115 * directory, in scenarios where they get overridden by 116 * elm_app_info_set(). 117 * 118 * @param dir The path to the default binaries directory (compile time 119 * one) 120 * 121 * @note Elementary will as well use this path to determine actual 122 * names of binaries' directory paths, maybe changing it to be @c 123 * something/local/bin instead of @c something/bin, only, for 124 * example. 125 * 126 * @warning You should call this function @b before 127 * elm_app_info_set(). 128 * 129 * @ingroup Elm_App 130 */ 131 EAPI void elm_app_compile_bin_dir_set(const char *dir); 132 133 /** 134 * Provide information on the @b fallback application's libraries 135 * directory, on scenarios where they get overridden by 136 * elm_app_info_set(). 137 * 138 * @param dir The path to the default libraries directory (compile 139 * time one) 140 * 141 * @note Elementary will as well use this path to determine actual 142 * names of libraries' directory paths, maybe changing it to be @c 143 * something/lib32 or @c something/lib64 instead of @c something/lib, 144 * only, for example. 145 * 146 * @warning You should call this function @b before 147 * elm_app_info_set(). 148 * 149 * @ingroup Elm_App 150 */ 151 EAPI void elm_app_compile_lib_dir_set(const char *dir); 152 153 /** 154 * Provide information on the @b fallback application's data 155 * directory, on scenarios where they get overridden by 156 * elm_app_info_set(). 157 * 158 * @param dir The path to the default data directory (compile time 159 * one) 160 * 161 * @note Elementary will as well use this path to determine actual 162 * names of data directory paths, maybe changing it to be @c 163 * something/local/share instead of @c something/share, only, for 164 * example. 165 * 166 * @warning You should call this function @b before 167 * elm_app_info_set(). 168 * 169 * @ingroup Elm_App 170 */ 171 EAPI void elm_app_compile_data_dir_set(const char *dir); 172 173 /** 174 * Provide information on the @b fallback application's locale 175 * directory, on scenarios where they get overridden by 176 * elm_app_info_set(). 177 * 178 * @param dir The path to the default locale directory (compile time 179 * one) 180 * 181 * @warning You should call this function @b before 182 * elm_app_info_set(). 183 * 184 * @ingroup Elm_App 185 */ 186 EAPI void elm_app_compile_locale_set(const char *dir); 187 188 /** 189 * Get the application formal name, as set by elm_app_name_set(). 190 * 191 * @return The application formal name. 192 * 193 * @ingroup Elm_App 194 * @since 1.8 195 */ 196 EAPI const char *elm_app_name_get(void); 197 198 /** 199 * Get the path to the '.desktop' file, as set by 200 * elm_app_desktop_entry_set(). 201 * 202 * @return The '.desktop' file path. 203 * 204 * @ingroup Elm_App 205 * @since 1.8 206 */ 207 EAPI const char *elm_app_desktop_entry_get(void); 208 209 /** 210 * Get the application's run time prefix directory, as set by 211 * elm_app_info_set() and the way (environment) the application was 212 * run from. 213 * 214 * @return The directory prefix the application is actually using. 215 * 216 * @ingroup Elm_App 217 */ 218 EAPI const char *elm_app_prefix_dir_get(void); 219 220 /** 221 * Get the application's run time binaries prefix directory, as 222 * set by elm_app_info_set() and the way (environment) the application 223 * was run from. 224 * 225 * @return The binaries directory prefix the application is actually 226 * using. 227 * 228 * @ingroup Elm_App 229 */ 230 EAPI const char *elm_app_bin_dir_get(void); 231 232 /** 233 * Get the application's run time libraries prefix directory, as 234 * set by elm_app_info_set() and the way (environment) the application 235 * was run from. 236 * 237 * @return The libraries directory prefix the application is actually 238 * using. 239 * 240 * @ingroup Elm_App 241 */ 242 EAPI const char *elm_app_lib_dir_get(void); 243 244 /** 245 * Get the application's run time data prefix directory, as 246 * set by elm_app_info_set() and the way (environment) the application 247 * was run from. 248 * 249 * @return The data directory prefix the application is actually 250 * using. 251 * 252 * @ingroup Elm_App 253 */ 254 EAPI const char *elm_app_data_dir_get(void); 255 256 /** 257 * Get the application's run time locale prefix directory, as 258 * set by elm_app_info_set() and the way (environment) the application 259 * was run from. 260 * 261 * @return The locale directory prefix the application is actually 262 * using. 263 * 264 * @ingroup Elm_App 265 */ 266 EAPI const char *elm_app_locale_dir_get(void); 267 268 /** 269 * Set the base scale of the application. 270 * 271 * @param base_scale The scale that the application is made on the basis of. 272 * 273 * @note The scale is used for the application to be scaled. 274 * If the application isn't made on the basis of scale 1.0, 275 * the application layout will be scaled inappositely. So if the application set 276 * the base scale, it is applied when the application is scaled. 277 * 278 * @note You should call this function @b before using ELM_SCALE_SIZE macro. 279 * 280 * @ingroup Elm_App 281 * @since 1.12 282 */ 283 EAPI void elm_app_base_scale_set(double base_scale); 284 285 /** 286 * Get the base scale of the application. 287 * 288 * @return The base scale which the application sets. 289 * 290 * @ingroup Elm_App 291 * @since 1.12 292 */ 293 EAPI double elm_app_base_scale_get(void); 294 295 /** 296 * @} 297 */ 298
