General (top-level) functions example

As told in their documentation blocks, the elm_app_compile_*_dir_set() family of functions have to be called before elm_app_info_set():

/* tell elm about our app so it can figure out where to get files */
elm_app_compile_bin_dir_set(BIN_DIR);
elm_app_compile_data_dir_set(DATA_DIR);
elm_app_compile_lib_dir_set(LIB_DIR);
elm_app_info_set(elm_main, "elementary", "images/logo.png");
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 distri...
Definition: elm_main.c:496
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 overrid...
Definition: elm_main.c:528
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 ov...
Definition: elm_main.c:522
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 ove...
Definition: elm_main.c:516

We are here setting the fallback paths to the compiling time target paths, naturally. If you're building the example out of the project's build system, we're assuming they are the canonical ones.

After the program starts, elm_app_info_set() will actually run and then you'll see a problem: Elementary does the prefix lookup twice. This is so because of the quicklaunch infrastructure in Elementary (Start), which will register a predefined prefix for possible users of the launch schema. We're not hooking into a quick launch, so this first call can't be avoided.

If you ran this example from your "bindir" installation directory, no output will emerge from these both attempts – it will find the "magic" file there registered and set the prefixes silently. Otherwise, you could get something like:

    WARNING: Could not determine its installed prefix for 'ELM'
          so am falling back on the compiled in default:
            usr
          implied by the following:
            bindir    = usr/lib
            libdir    = usr/lib
            datadir   = usr/share/elementary
            localedir = usr/share/locale
          Try setting the following environment variables:
            ELM_PREFIX     - points to the base prefix of install
          or the next 4 variables
            ELM_BIN_DIR    - provide a specific binary directory
            ELM_LIB_DIR    - provide a specific library directory
            ELM_DATA_DIR   - provide a specific data directory
            ELM_LOCALE_DIR - provide a specific locale directory

if you also didn't change those environment variables (remember they are also a valid way of communicating your prefix to the binary) - this is the scenario where it fallbacks to the paths set for compile time.

Then, you can check the prefixes set on the standard output:

printf("prefix was set to: %s\n", elm_app_prefix_dir_get());
printf("data directory is: %s\n", elm_app_data_dir_get());
printf("library directory is: %s\n", elm_app_lib_dir_get());
printf("locale directory is: %s\n", elm_app_locale_dir_get());
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 (env...
Definition: elm_main.c:611
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 (envir...
Definition: elm_main.c:586
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 (...
Definition: elm_main.c:576
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 (environmen...
Definition: elm_main.c:556

In the fragment

/* by using this policy value, we avoid having to
* evas_object_smart_callback_add(win, "delete,request", _on_exit, NULL),
* calling elm_exit() on that callback ourselves.
*/
elm_policy_set(ELM_POLICY_QUIT, ELM_POLICY_QUIT_LAST_WINDOW_CLOSED);
elm_win_autodel_set(win, EINA_TRUE);
EINA_TRUE
#define EINA_TRUE
boolean value TRUE (numerical value 1)
Definition: eina_types.h:539
elm_policy_set
Eina_Bool elm_policy_set(unsigned int policy, int value)
Set a new policy's value (for a given policy group/identifier).
Definition: elm_main.c:1380
ELM_POLICY_QUIT_LAST_WINDOW_CLOSED
@ ELM_POLICY_QUIT_LAST_WINDOW_CLOSED
quit when the application's last window is closed
Definition: elm_general.h:248
ELM_POLICY_QUIT
@ ELM_POLICY_QUIT
under which circumstances the application should quit automatically.
Definition: elm_general.h:227
elm_win_autodel_set
void elm_win_autodel_set(Eo *obj, Eina_Bool autodel)
Set the window's autodel state.
Definition: efl_ui_win.c:6189

we demonstrate the use of Elementary policies. The policy defining under which circumstances our application should quit automatically is set to when its last window is closed (this one has just one window, though). This will save us from having to set a callback ourselves on the window, like done in this example. Note that we need to tell the window to delete itself's object on a request to destroy the canvas coming, with elm_win_autodel_set().

What follows is some boilerplate code, creating a frame with a button, our object of interest, and, below, widgets to change the button's behavior and exemplify the group of functions in question.

We enabled the focus highlight object for this window, so that you can keep track of the current focused object better:

elm_win_focus_highlight_enabled_set(win, EINA_TRUE);
evas_object_show(win);
elm_win_focus_highlight_enabled_set
void elm_win_focus_highlight_enabled_set(Elm_Win *obj, Eina_Bool enabled)
Set the enabled status for the focus highlight in a window.
evas_object_show
EVAS_API void evas_object_show(Evas_Object *eo_obj)
Makes the given Evas object visible.
Definition: evas_object_main.c:1814

Use the tab key to navigate through the focus chain.

While creating the button, we exemplify how to use Elementary's finger size information to scale our UI:

The first checkbox's callback is:

static void
_btn_enabled_cb(void *data EINA_UNUSED,
Evas_Object *obj EINA_UNUSED,
void *event EINA_UNUSED)
{
elm_object_disabled_set(d.btn, !d.btn_enabled);
}
EINA_UNUSED
#define EINA_UNUSED
Used to indicate that a function parameter is purposely unused.
Definition: eina_types.h:339
elm_object_disabled_set
void elm_object_disabled_set(Evas_Object *obj, Eina_Bool disabled)
Set the disabled state of an Elementary object.
Definition: elm_main.c:1613
Evas_Object
Efl_Canvas_Object Evas_Object
An Evas Object handle.
Definition: Evas_Common.h:185

When unsetting the checkbox, we disable the button, which will get a new decoration (greyed out) and stop receiving events. The focus chain will also ignore it.

Following, there are 2 more buttons whose actions are focus/unfocus the top button, respectively:

/* focus callback */
_btn_focus_cb(void *data EINA_UNUSED,
Evas_Object *obj EINA_UNUSED,
void *event EINA_UNUSED)
{
elm_object_focus_set(d.btn, EINA_TRUE);
}
elm_object_focus_set
void elm_object_focus_set(Evas_Object *obj, Eina_Bool focus)
Set/unset focus to a given Elementary object.
Definition: elm_focus_legacy.c:374

and

/* unfocus callback */
_btn_unfocus_cb(void *data EINA_UNUSED,
Evas_Object *obj EINA_UNUSED,
void *event EINA_UNUSED)
{
elm_object_focus_set(d.btn, EINA_FALSE);
}
EINA_FALSE
#define EINA_FALSE
boolean value FALSE (numerical value 0)
Definition: eina_types.h:533

Note the situations in which they won't take effect:

- the button is not allowed to get focus or
- the button is disabled

The first restriction above you'll get by a second checkbox, whose callback is:

/* focus allow callback */
_btn_focus_allow_cb(void *data EINA_UNUSED,
Evas_Object *obj EINA_UNUSED,
void *event EINA_UNUSED)
{
elm_object_focus_allow_set(d.btn, d.btn_gets_focus);
}
elm_object_focus_allow_set
void elm_object_focus_allow_set(Evas_Object *obj, Eina_Bool enable)
Set the ability for an Elementary object to be focused.
Definition: elm_main.c:1661

Note that the button will still get mouse events, though.

Next, there's a slider controlling the button's scale:

static void /* scaling callback */
_btn_scale_cb(void *data EINA_UNUSED,
Evas_Object *obj,
void *event EINA_UNUSED)
{
elm_object_scale_set(d.btn, elm_slider_value_get(obj));
}
elm_object_scale_set
void elm_object_scale_set(Evas_Object *obj, double scale)
Set the scaling factor for a given Elementary object.
Definition: elm_main.c:1470
elm_slider_value_get
double elm_slider_value_get(const Evas_Object *obj)
Get the value displayed by the slider.
Definition: elm_slider.c:1534

Experiment with it, so you understand the effect better. If you change its value, it will mess with the button's original size, naturally.

The full code for this example can be found here.