diff options
Diffstat (limited to 'src/lib/elementary/elm_app.h')
-rw-r--r-- | src/lib/elementary/elm_app.h | 297 |
1 files changed, 297 insertions, 0 deletions
diff --git a/src/lib/elementary/elm_app.h b/src/lib/elementary/elm_app.h new file mode 100644 index 0000000000..a169f7c988 --- /dev/null +++ b/src/lib/elementary/elm_app.h @@ -0,0 +1,297 @@ +/** + * @defgroup Elm_App App + * @ingroup Elementary + * Provide information in order to make Elementary determine the @b + * run time location of the software in question, so other data files + * such as images, sound files, executable utilities, libraries, + * modules and locale files can be found. + */ + +/** + * @addtogroup Elm_App + * @{ + */ + +/** + * Re-locate the application somewhere else after compilation, if the developer + * wishes for easier distribution of pre-compiled binaries. + * + * @param mainfunc This is your application's main function name, + * whose binary's location is to be found. Providing @c NULL + * will make Elementary not to use it + * @param dom This will be used as the application's "domain", in the + * form of a prefix to any environment variables that may + * override prefix detection and the directory name, inside the + * standard share or data directories, where the software's + * data files will be looked for. + * @param checkfile This is an (optional) magic file's path to check + * for existence (and it must be located in the data directory, + * under the share directory provided above). Its presence will + * help determine the prefix found was correct. Pass @c NULL if + * the check is not to be done. + * + * The prefix system is designed to locate where the given software is + * installed (under a common path prefix) at run time and then report + * specific locations of this prefix and common directories inside + * this prefix like the binary, library, data and locale directories, + * through the @c elm_app_*_get() family of functions. + * + * Call elm_app_info_set() early on before you change working + * directory or anything about @c argv[0], so it gets accurate + * information. + * + * It will then try and trace back which file @p mainfunc comes from, + * if provided, to determine the application's prefix directory. + * + * The @p dom parameter provides a string prefix to prepend before + * environment variables, allowing a fallback to @b specific + * environment variables to locate the software. You would most + * probably provide a lowercase string there, because it will also + * serve as directory domain, explained next. For environment + * variables purposes, this string is made uppercase. For example if + * @c "myapp" is provided as the prefix, then the program would expect + * @c "MYAPP_PREFIX" as a master environment variable to specify the + * exact install prefix for the software, or more specific environment + * variables like @c "MYAPP_BIN_DIR", @c "MYAPP_LIB_DIR", @c + * "MYAPP_DATA_DIR" and @c "MYAPP_LOCALE_DIR", which could be set by + * the user or scripts before launching. If not provided (@c NULL), + * environment variables will not be used to override compiled-in + * defaults or auto detections. + * + * The @p dom string also provides a subdirectory inside the system + * shared data directory for data files. For example, if the system + * directory is @c /usr/local/share, then this directory name is + * appended, creating @c /usr/local/share/myapp, if it @p was @c + * "myapp". It is expected that the application installs data files in + * this directory. + * + * The @p checkfile is a file name or path of something inside the + * share or data directory to be used to test that the prefix + * detection worked. For example, your app will install a wallpaper + * image as @c /usr/local/share/myapp/images/wallpaper.jpg and so to + * check that this worked, provide @c "images/wallpaper.jpg" as the @p + * checkfile string. + * + * @see elm_app_compile_bin_dir_set() + * @see elm_app_compile_lib_dir_set() + * @see elm_app_compile_data_dir_set() + * @see elm_app_compile_locale_set() + * @see elm_app_prefix_dir_get() + * @see elm_app_bin_dir_get() + * @see elm_app_lib_dir_get() + * @see elm_app_data_dir_get() + * @see elm_app_locale_dir_get() + * + * @ingroup Elm_App + */ +EAPI void elm_app_info_set(void *mainfunc, const char *dom, const char *checkfile); + +/** + * Set a formal name to be used with the elm application. + * + * @param name Application name. + * + * @ingroup Elm_App + * @since 1.8 + */ +EAPI void elm_app_name_set(const char *name); + +/** + * Set the path to the '.desktop' file to be associated + * with the elm application. + * + * @param path The path to the '.desktop' file + * + * @warning Since this path is very environment dependent, + * this will hold whatever value is passed to it. + * + * @ingroup Elm_App + * @since 1.8 + */ +EAPI void elm_app_desktop_entry_set(const char *path); + +/** + * Provide information on the @b fallback application's binaries + * directory, in scenarios where they get overridden by + * elm_app_info_set(). + * + * @param dir The path to the default binaries directory (compile time + * one) + * + * @note Elementary will as well use this path to determine actual + * names of binaries' directory paths, maybe changing it to be @c + * something/local/bin instead of @c something/bin, only, for + * example. + * + * @warning You should call this function @b before + * elm_app_info_set(). + * + * @ingroup Elm_App + */ +EAPI void elm_app_compile_bin_dir_set(const char *dir); + +/** + * Provide information on the @b fallback application's libraries + * directory, on scenarios where they get overridden by + * elm_app_info_set(). + * + * @param dir The path to the default libraries directory (compile + * time one) + * + * @note Elementary will as well use this path to determine actual + * names of libraries' directory paths, maybe changing it to be @c + * something/lib32 or @c something/lib64 instead of @c something/lib, + * only, for example. + * + * @warning You should call this function @b before + * elm_app_info_set(). + * + * @ingroup Elm_App + */ +EAPI void elm_app_compile_lib_dir_set(const char *dir); + +/** + * Provide information on the @b fallback application's data + * directory, on scenarios where they get overridden by + * elm_app_info_set(). + * + * @param dir The path to the default data directory (compile time + * one) + * + * @note Elementary will as well use this path to determine actual + * names of data directory paths, maybe changing it to be @c + * something/local/share instead of @c something/share, only, for + * example. + * + * @warning You should call this function @b before + * elm_app_info_set(). + * + * @ingroup Elm_App + */ +EAPI void elm_app_compile_data_dir_set(const char *dir); + +/** + * Provide information on the @b fallback application's locale + * directory, on scenarios where they get overridden by + * elm_app_info_set(). + * + * @param dir The path to the default locale directory (compile time + * one) + * + * @warning You should call this function @b before + * elm_app_info_set(). + * + * @ingroup Elm_App + */ +EAPI void elm_app_compile_locale_set(const char *dir); + +/** + * Get the application formal name, as set by elm_app_name_set(). + * + * @return The application formal name. + * + * @ingroup Elm_App + * @since 1.8 + */ +EAPI const char *elm_app_name_get(void); + +/** + * Get the path to the '.desktop' file, as set by + * elm_app_desktop_entry_set(). + * + * @return The '.desktop' file path. + * + * @ingroup Elm_App + * @since 1.8 + */ +EAPI const char *elm_app_desktop_entry_get(void); + +/** + * Get the application's run time prefix directory, as set by + * elm_app_info_set() and the way (environment) the application was + * run from. + * + * @return The directory prefix the application is actually using. + * + * @ingroup Elm_App + */ +EAPI const char *elm_app_prefix_dir_get(void); + +/** + * Get the application's run time binaries prefix directory, as + * set by elm_app_info_set() and the way (environment) the application + * was run from. + * + * @return The binaries directory prefix the application is actually + * using. + * + * @ingroup Elm_App + */ +EAPI const char *elm_app_bin_dir_get(void); + +/** + * Get the application's run time libraries prefix directory, as + * set by elm_app_info_set() and the way (environment) the application + * was run from. + * + * @return The libraries directory prefix the application is actually + * using. + * + * @ingroup Elm_App + */ +EAPI const char *elm_app_lib_dir_get(void); + +/** + * Get the application's run time data prefix directory, as + * set by elm_app_info_set() and the way (environment) the application + * was run from. + * + * @return The data directory prefix the application is actually + * using. + * + * @ingroup Elm_App + */ +EAPI const char *elm_app_data_dir_get(void); + +/** + * Get the application's run time locale prefix directory, as + * set by elm_app_info_set() and the way (environment) the application + * was run from. + * + * @return The locale directory prefix the application is actually + * using. + * + * @ingroup Elm_App + */ +EAPI const char *elm_app_locale_dir_get(void); + +/** + * Set the base scale of the application. + * + * @param base_scale The scale that the application is made on the basis of. + * + * @note The scale is used for the application to be scaled. + * If the application isn't made on the basis of scale 1.0, + * the application layout will be scaled inappositely. So if the application set + * the base scale, it is applied when the application is scaled. + * + * @note You should call this function @b before using ELM_SCALE_SIZE macro. + * + * @ingroup Elm_App + * @since 1.12 + */ +EAPI void elm_app_base_scale_set(double base_scale); + +/** + * Get the base scale of the application. + * + * @return The base scale which the application sets. + * + * @ingroup Elm_App + * @since 1.12 + */ +EAPI double elm_app_base_scale_get(void); + +/** + * @} + */ |