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");

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());

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);

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);

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);
}

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);
}

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);
}

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);
}

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));
}

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.