App
Elementary

Provide information in order to make Elementary determine the 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. More...

## Functions

void | elm_app_info_set (void *mainfunc, const char *dom, const char *checkfile)
| Re-locate the application somewhere else after compilation, if the developer wishes for easier distribution of pre-compiled binaries.
void | elm_app_name_set (const char *name)
| Set a formal name to be used with the elm application.
void | elm_app_desktop_entry_set (const char *path)
| Set the path to the '.desktop' file to be associated with the elm application.
void | elm_app_compile_bin_dir_set (const char *dir)
| Provide information on the fallback application's binaries directory, in scenarios where they get overridden by elm_app_info_set().
void | elm_app_compile_lib_dir_set (const char *dir)
| Provide information on the fallback application's libraries directory, on scenarios where they get overridden by elm_app_info_set().
void | elm_app_compile_data_dir_set (const char *dir)
| Provide information on the fallback application's data directory, on scenarios where they get overridden by elm_app_info_set().
void | elm_app_compile_locale_set (const char *dir)
| Provide information on the fallback application's locale directory, on scenarios where they get overridden by elm_app_info_set().
const char * | elm_app_name_get (void)
| Get the application formal name, as set by elm_app_name_set().
const char * | elm_app_desktop_entry_get (void)
| Get the path to the '.desktop' file, as set by elm_app_desktop_entry_set().
const char * | elm_app_prefix_dir_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.
const char * | elm_app_bin_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.
const char * | elm_app_lib_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.
const char * | elm_app_data_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.
const char * | elm_app_locale_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.
void | elm_app_base_scale_set (double base_scale)
| Set the base scale of the application.
double | elm_app_base_scale_get (void)
| Get the base scale of the application.

## Detailed Description

Provide information in order to make Elementary determine the 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.

## Function Documentation

## elm_app_info_set()

void elm_app_info_set | ( | void * | mainfunc,
|  | const char * | dom,
|  | const char * | checkfile )

Re-locate the application somewhere else after compilation, if the developer wishes for easier distribution of pre-compiled binaries.

Parameters

  mainfunc | This is your application's main function name, whose binary's location is to be found. Providing `NULL` will make Elementary not to use it
  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.
  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 `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 `elm_app_*_get`() family of functions.

Call elm_app_info_set() early on before you change working directory or anything about `argv`[0], so it gets accurate information.

It will then try and trace back which file `mainfunc` comes from, if provided, to determine the application's prefix directory.

The `dom` parameter provides a string prefix to prepend before environment variables, allowing a fallback to 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 `"myapp"` is provided as the prefix, then the program would expect `"MYAPP_PREFIX"` as a master environment variable to specify the exact install prefix for the software, or more specific environment variables like `"MYAPP_BIN_DIR"`, `"MYAPP_LIB_DIR"`, `"MYAPP_DATA_DIR"` and `"MYAPP_LOCALE_DIR"`, which could be set by the user or scripts before launching. If not provided (`NULL`), environment variables will not be used to override compiled-in defaults or auto detections.

The `dom` string also provides a subdirectory inside the system shared data directory for data files. For example, if the system directory is `/usr/local/share`, then this directory name is appended, creating `/usr/local/share/myapp`, if it `was` `"myapp"`. It is expected that the application installs data files in this directory.

The `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 `/usr/local/share/myapp/images/wallpaper`.jpg and so to check that this worked, provide `"images/wallpaper.jpg"` as the `checkfile` string.

See also
  elm_app_compile_bin_dir_set()
  elm_app_compile_lib_dir_set()
  elm_app_compile_data_dir_set()
  elm_app_compile_locale_set()
  elm_app_prefix_dir_get()
  elm_app_bin_dir_get()
  elm_app_lib_dir_get()
  elm_app_data_dir_get()
  elm_app_locale_dir_get()

Examples
  bg_example_02.c, bg_example_03.c, codegen_example.c, general_funcs_example.c, gengrid_example.c, image_example_01.c, index_example_02.c, layout_example_01.c, layout_example_03.c, map_example_02.c, photocam_example_01.c, popup_example_02.c, popup_example_03.c, progressbar_example.c, slideshow_example.c, theme_example_01.c, theme_example_02.c, thumb_example_01.c, transit_example_03.c, transit_example_04.c, and win_example.c.

References eina_stringshare_replace().

## elm_app_name_set()

void elm_app_name_set | ( | const char * | name | ) |

Set a formal name to be used with the elm application.

Parameters

  name | Application name.

Since
  1.8

References eina_stringshare_replace().

Referenced by elm_quicklaunch_init().

## elm_app_desktop_entry_set()

void elm_app_desktop_entry_set | ( | const char * | path | ) |

Set the path to the '.desktop' file to be associated with the elm application.

Parameters

  path | The path to the '.desktop' file

Warning
  Since this path is very environment dependent, this will hold whatever value is passed to it.

Since
  1.8

References eina_stringshare_replace().

## elm_app_compile_bin_dir_set()

void elm_app_compile_bin_dir_set | ( | const char * | dir | ) |

Provide information on the fallback application's binaries directory, in scenarios where they get overridden by elm_app_info_set().

Parameters

  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 `something/local/bin` instead of `something/bin`, only, for example.

Warning
  You should call this function before elm_app_info_set().

Examples
  general_funcs_example.c.

References eina_stringshare_replace().

## elm_app_compile_lib_dir_set()

void elm_app_compile_lib_dir_set | ( | const char * | dir | ) |

Provide information on the fallback application's libraries directory, on scenarios where they get overridden by elm_app_info_set().

Parameters

  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 `something/lib32` or `something/lib64` instead of `something/lib`, only, for example.

Warning
  You should call this function before elm_app_info_set().

Examples
  general_funcs_example.c.

References eina_stringshare_replace().

## elm_app_compile_data_dir_set()

void elm_app_compile_data_dir_set | ( | const char * | dir | ) |

Provide information on the fallback application's data directory, on scenarios where they get overridden by elm_app_info_set().

Parameters

  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 `something/local/share` instead of `something/share`, only, for example.

Warning
  You should call this function before elm_app_info_set().

Examples
  general_funcs_example.c, theme_example_01.c, and theme_example_02.c.

References eina_stringshare_replace().

## elm_app_compile_locale_set()

void elm_app_compile_locale_set | ( | const char * | dir | ) |

Provide information on the fallback application's locale directory, on scenarios where they get overridden by elm_app_info_set().

Parameters

  dir | The path to the default locale directory (compile time one)

Warning
  You should call this function before elm_app_info_set().

References eina_stringshare_replace().

## elm_app_name_get()

const char * elm_app_name_get | ( | void |  | ) |

Get the application formal name, as set by elm_app_name_set().

Returns
  The application formal name.

Since
  1.8

## elm_app_desktop_entry_get()

const char * elm_app_desktop_entry_get | ( | void |  | ) |

Get the path to the '.desktop' file, as set by elm_app_desktop_entry_set().

Returns
  The '.desktop' file path.

Since
  1.8

## elm_app_prefix_dir_get()

const char * elm_app_prefix_dir_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.

Returns
  The directory prefix the application is actually using.

Examples
  general_funcs_example.c.

References eina_prefix_get().

Referenced by elm_app_data_dir_get().

## elm_app_bin_dir_get()

const char * elm_app_bin_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.

Returns
  The binaries directory prefix the application is actually using.

References eina_prefix_bin_get().

## elm_app_lib_dir_get()

const char * elm_app_lib_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.

Returns
  The libraries directory prefix the application is actually using.

Examples
  general_funcs_example.c.

References eina_prefix_lib_get().

## elm_app_data_dir_get()

const char * elm_app_data_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.

Returns
  The data directory prefix the application is actually using.

Examples
  bg_example_02.c, bg_example_03.c, general_funcs_example.c, gengrid_example.c, image_example_01.c, index_example_02.c, layout_example_01.c, layout_example_03.c, map_example_02.c, photocam_example_01.c, popup_example_02.c, popup_example_03.c, progressbar_example.c, slideshow_example.c, theme_example_01.c, theme_example_02.c, thumb_example_01.c, transit_example_03.c, transit_example_04.c, and win_example.c.

References eina_prefix_data_get(), eina_strbuf_append(), eina_strbuf_append_length(), eina_strbuf_free(), eina_strbuf_new(), eina_strbuf_string_steal(), and elm_app_prefix_dir_get().

Referenced by elm_prefs_file_set().

## elm_app_locale_dir_get()

const char * elm_app_locale_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.

Returns
  The locale directory prefix the application is actually using.

Examples
  general_funcs_example.c.

References eina_prefix_locale_get().

## elm_app_base_scale_set()

void elm_app_base_scale_set | ( | double | base_scale | ) |

Set the base scale of the application.

Parameters

  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.
  You should call this function before using ELM_SCALE_SIZE macro.

Since
  1.12

## elm_app_base_scale_get()

double elm_app_base_scale_get | ( | void |  | ) |

Get the base scale of the application.

Returns
  The base scale which the application sets.

Since
  1.12