Elementary

This feature is supported in wearable applications only.

Elementary UI components are built in a hierarchical fashion. The idea is to factorize as much code as possible between UI components that behave in a similar manner to facilitate the creation of new UI components. The Elementary UI components inherit a lot of their code from the container UI components and the layout component (a container component that takes a standard Edje design file and wraps it very thinly). You can use the container and layout functions on the Elementary UI components, as well as the Elementary object functions, such as elm_object_part_content_set(), elm_object_part_content_get(), and elm_object_part_content_unset().

Getting Started with the Elementary Library

To use the Elementary library:

Initialize the Elementary library with the elm_init() function.
Start the Elementary main loop with the elm_run() function.
The function does not return, instead, it constantly loops and runs the event and the processing tasks.
Add Elementary UI components in the main loop.
Generally, an Elementary UI component can be added with the elm_<UI component name>_add() function, which returns an Evas object (Evas_Object*). The Evas object is passed to the functions that are used to configure the UI component.
Stop the main loop and return to the main() function with the elm_exit() function.
When your application terminates, shut down the Elementary library with the elm_shutdown() function.
The function frees the Elementary objects that were allocated in the main loop, so you do not need to separately deallocate them.

The following code snippet shows the main() function of a minimal Elementary application:

#include <Elementary.h>
int main(int argc, char **argv)
{
   elm_init(argc, argv);
   elm_run();
   elm_shutdown();

   return 0;
}

Note
An Elementary application must use the ELM_MAIN() macro, which calls the elm_init() function. The HelloWorld example shows a basic Elementary application that uses this macro.

Elementary Objects

All objects created using Elementary are of the Evas_Object* type. This means that both Evas and Elementary functions can be used on an Elementary object. However, use Elementary functions on Elementary objects only when you do not know which API to use.

Since an Elementary object can take up a lot of memory, the Elm_Object_Item type has been created for situations where you need to use a lot of items, such as in a genlist or gengrid component, and to save memory. Using the Elm_Object_Item type, an Elementary UI component can, in theory, contain a lot of items while maintaining a small memory footprint. In practice, the Elm_Object_Item instance is bigger than expected, but can still help in saving memory.

Elementary Callbacks

Several callbacks can be registered to handle Elementary object events:

Evas event callback
Use the evas_object_event_callback_add() function to add a callback for input events (key up, key down, mouse wheel) on an Evas object. In case of an Elementary object, the callback is registered on the underlying Evas object without considering the Elementary object infrastructure (no event propagation).
Evas smart callback
Use the evas_object_smart_callback_add() function to add a callback for a smart event emitted by an Elementary object. Smart callbacks can only be registered on smart objects, and the "smart event" to register must be implemented by the corresponding smart object. Otherwise, the callback does nothing. The callback does not apply to input events (keyboard or mouse).
Edje signal callback
Use the edje_object_signal_callback_add() function to add a callback for a signal coming from an Edje object (a theme object).
Elementary signal callback
Use the elm_object_signal_callback_add() function to add a callback for a signal coming from an Elementary UI component's theme. The callback does not apply to input events (keyboard or mouse).
Elementary event callback
Use the elm_object_event_callback_add() function to add a callback for an input event (keyboard or mouse) coming from an Elementary object. In contrast to the Evas event callback, the Elementary event callback takes the hierarchy of the object into account: the event can be propagated to the parents of the object, and the parents can process the event.

For more information about events related to Elementary objects, see Handling Events. For more information about Evas objects and smart objects, see Rendering Concept and Method in Evas.

Managing Elementary Profiles

An Elementary profile is a set of preconfigured options that affects the entire look and feel of an application. The options linked to a specific profile form an Elementary configuration, which can be used to store the desired set of options for use in multiple sessions. Once loaded, the Elementary profile configures all the options and sets the look and feel of your Elementary application.

To manage Elementary profiles:

List the existing profiles:

Eina_List *list = elm_config_profile_list_get();

Set a particular profile:
```
elm_config_profile_set("myprofile");
```

Get the current profile:

char *profile = elm_config_profile_get();

To reload the Elementary configuration saved for the current profile:
```
elm_config_reload();
```

Configuring Elementary Options

You can set the following options in the Elementary configuration. In addition, you can customize themes and manage focus.

To scale UI components:
You can configure UI component scaling in terms of both interactive and readable areas.
- Set the global scaling factor (for example, setting it to 2.0 doubles the size of all scalable UI components):
```
elm_config_scale_set(2.0);
```
- Set the finger size:
```
elm_config_finger_size_set(1.5);
```

To manage caches:

Enable the globally configured cache flush, and set the flush interval (in this example, to 60 seconds):
```
elm_config_cache_flush_enabled_set(EINA_TRUE);
elm_config_cache_flush_interval_set(60);
```

Configure the font and image cache sizes (to 500 and 5 000 000 bytes, respectively):

elm_config_cache_font_cache_size_set(500);
elm_config_cache_image_cache_size_set(5000000);

Set the Edje collection and Edje file cache sizes:

elm_config_cache_edje_file_cache_size_set(500);
elm_config_cache_edje_collection_cache_size_set(500);

To configure the gesture layer:
You can set the duration of the long tap and double tap events on the gesture layer objects. The following example sets the duration to 500 ms.
```
elm_config_glayer_long_tap_start_timeout_set(0.5);
elm_config_glayer_double_tap_timeout_set(0.5);
```
To manage scrolling:
- Make the scroller bounce when it reaches its viewport's edge during scrolling by using the elm_config_scroll_bounce_enabled_set() function:
```
elm_config_scroll_bounce_enabled_set(EINA_TRUE);
```
- Control the inertia of the bounce animation by using the elm_config_scroll_bounce_friction_set() function:
```
elm_config_scroll_bounce_friction_set(0.5);
```
  You can also set the friction for a page scroll, include animations, and zoom animations.
- Set the scroller to be draggable by using the elm_config_scroll_thumbscroll_enabled_set() function. You can configure several drag options, such as friction, sensitivity, acceleration, and momentum.
  The following example sets the scroller to be draggable, defines that the number of pixels one must travel while dragging the scroller view to actually trigger scrolling is 20 pixels.
```
elm_config_scroll_thumbscroll_enabled_set(EINA_TRUE);
elm_config_scroll_thumbscroll_threshold_set(20);
```
To configure long press events:
Get the current timeout before a long press event is retrieved, and modify it. The following example increases the timeout by 1 second.
```
double lp_timeout = elm_config_longpress_timeout_get();
elm_config_longpress_timeout_set(lp_timeout + 1.0);
```
To configure the password show last feature:
The password show last feature enables the user to view the last input entered for a few seconds before it is masked.
- Enable the password show last feature:
```
elm_config_password_show_last_set(EINA_TRUE);
```
- Set the visibility timeout (how many seconds the input is visible):
```
elm_config_password_show_last_timeout_set(5.0);
```
To set the Elementary engine:
You can define the rendering engine that Elementary uses to draw the windows. The following rendering engines are supported:
- "software_x11"
- "fb"
- "directfb"
- "software_16_x11"
- "software_8_x11"
- "xrender_x11"
- "opengl_x11"
- "software_gdi"
- "software_16_wince_gdi"
- "sdl"
- "software_16_sdl"
- "opengl_sdl"
- "buffer"
- "ews"
- "opengl_cocoa"
- "psl1ght"
```
elm_config_engine_set("opengl_x11");
```
To configure the selection mode:
Set the selection mode so that the selection is cleared when the entry component is unfocused:
```
elm_config_selection_unfocused_clear_set(EINA_TRUE);
```
To enable mirroring:
Elementary allows UI mirroring both on a single object and on the entire UI. If mirroring is enabled, an Elementary UI component displays as if there was a vertical mirror in the middle of it. Only the controls and the disposition of the UI component are mirrored. Text is not mirrored.
```
elm_config_mirrored_set(EINA_TRUE);
```

Customizing Themes

Elementary uses Edje to theme its UI components. Edje provides a default theme for each UI component in an application. You can change the theme using the ELM_THEME environment variable. You can also modify the theme globally with the elementary_config utility.

For custom styles, use extensions. Extensions allow you to write styles for specific UI components. Add a new extension to the list of Elementary themes with the elm_theme_extension_add() function, and apply the new style to the UI component with the elm_object_style_set() function. Once set, the extension replaces the default theme of the UI component.

Note
When developing an extension, to respect the signals emitted and the elements that need to be in place, you must know how the UI component is themed. If something is missing from the extension, it can break the UI component's behavior.

To modify Elementary themes, you can also use overlays. An overlay can replace the look of all UI components by overriding the default styles. As with extensions, you must write the correct overlay theme for a UI component. When looking for a theme to apply, Elementary first checks the list of overlays, then the set theme, and finally the list of extensions. To add or remove an overlay, use the elm_theme_overlay_add() and elm_theme_overlay_del() functions.

Note
With overlays, you can replace the default view and affect every UI component. This is very similar to setting the theme for the whole application, and probably clashes with end user options. Using overlays also runs the risk of non-matching styles across the application. Unless you have a very good reason to use them, avoid overlays.

Managing Focus

When an Elementary object has the focus, input events are directly passed to that object in the application window. The focused object can also change its decoration to show the user where the focus is. In an Elementary application, only one object can have the focus at a time.

To set the focus to a new Elementary object and take the focus away from the previous focused object, use the elm_object_focus_set() function. You can make an object unfocusable with the elm_object_focus_allow_set() function.

Note
Only visible objects can have the focus.

Elementary supports focus chains that allow you to cycle through all the focusable objects in a window. By default, the focus chain is defined by the order in which the UI components are added to the code. It is also possible to define custom focus chains, when needed.

For more information on focus, see Managing UI Component Focus.

To manage the focus:

To define a custom focus chain, create an Eina_List, and add the Elementary objects to it in the desired focus order. Use the elm_object_focus_custom_chain_set() function to set the final list as the custom focus chain of the parent object (in the following example, container_object is the parent object).
```
Eina_List *obj_list = NULL;

list = eina_list_append(list, obj1); 
list = eina_list_append(list, obj4);
list = eina_list_append(list, obj2); 
list = eina_list_append(list, obj3);

elm_object_focus_custom_chain_set(container_object, list);
```
To remove the custom focus chain and use the default focus chain instead, use the elm_object_focus_custom_chain_unset() function.
To programmatically cycle through the focus chain, use the elm_object_focus_next() function.

To show a highlight on the focused object:

elm_config_focus_highlight_enabled_set(EINA_TRUE);

To activate an animation when the focus shifts from one object to another:
```
elm_config_focus_highlight_animate_set(EINA_TRUE);
```