Mobile native

Basic: Using Basic Interactions

This tutorial teaches the basics of UI components interactions. It builds upon the Hello World example.

This feature is supported in mobile applications only.

Warm-up

Become familiar with the Elementary and Evas API basics by learning about:

Using Buttons

The basic application code is the same as in the Hello World example.

Button Styles

Basic Text Button

To create a text-only button, use the following code.

Evas_Object* button;

button = elm_button_add(box);
elm_object_text_set(button, "Click me");
evas_object_size_hint_weight_set(button, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
evas_object_size_hint_align_set(button, EVAS_HINT_FILL, 0.5);
elm_box_pack_end(box, button);
evas_object_show(button);

Basic Icon Button

Instead of a button with text, create a button with an icon.

Evas_Object* button2;
Evas_Object* icon2;

button2 = elm_button_add(box);
icon2 = elm_icon_add(box);
elm_image_file_set(icon2, "icon.png", NULL);
elm_object_part_content_set(button2, "icon", icon2);
evas_object_size_hint_weight_set(button, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
evas_object_size_hint_align_set(button, EVAS_HINT_FILL, 0.5);
elm_box_pack_end(box, button);
evas_object_show(button);

Icon and Text Button

Create buttons with both an icon and a text label.

Evas_Object* button3;
Evas_Object* icon3;
button3 = elm_button_add(box);
icon3 = elm_icon_add(box);
elm_image_file_set(icon, "icon.png", NULL);
elm_object_part_content_set(button3, "icon", icon3);
elm_object_text_set(button3, "Press me");
evas_object_size_hint_weight_set(button, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
evas_object_size_hint_align_set(button, EVAS_HINT_FILL, 0.5);
elm_box_pack_end(box, button);
evas_object_show(button);

Disabled Button

To disable a button so that it is not in use, only shown.

elm_object_disabled_set(button2, EINA_TRUE);

Callbacks

The Elementary buttons respond to user interactions with several events.

Click Event

The "click" event is the most basic and well-known one. The following code snippet changes the text of a button upon a click event: a press followed by an unpress.

static void _button_click_cb(void *data, Evas_Object *button, void *ev) 
{
   elm_object_text_set(button, "Clicked!");
}
evas_object_smart_callback_add(button, "clicked", _button_click_cb, NULL);

Press/Unpress Events

The button can respond to the press and unpress events instead of the entire click event.

static void _button_press_cb(void *data, Evas_Object *button, void *ev) 
{
   elm_object_text_set(button, "Pressed!");
}
static void _button_unpress_cb(void *data, Evas_Object *button, void *ev) 
{
   elm_object_text_set(button, "Unpressed!");
}

evas_object_smart_callback_add(button3, "pressed", _button_press_cb, NULL);
evas_object_smart_callback_add(button3, "unpressed", _button_unpress_cb, NULL);

Repeated Events

The button can receive several events in case it is being held by the user. Timings, such as the initial timeout and the repeat interval, can be set. In this example, the initial timeout is set to 1 second, and the repeat interval to half a second.

static void _button_repeat_cb(void *data, Evas_Object *button, void *ev) 
{
   static int count = 0;
   char buf[16];

   snprintf(buf, sizeof(buf), "Repeat %d", count++);

   elm_object_text_set(button, buf);
}

elm_button_autorepeat_set(button3, EINA_TRUE);
elm_button_autorepeat_initial_timeout_set(button3, 1.0);
elm_button_autorepeat_gap_timeout_set(button3, 0.5);
evas_object_smart_callback_add(button3, "repeated", _button_repeat_cb, NULL);

Using Simple Text

Basic Text

To create a label object, use the following code.

label = elm_label_add(ad->win);
elm_object_text_set(label, "My label");
evas_object_show(label);

Sliding Text

If your text is too long, set it to slide. The duration of the slide is set to five seconds in the following example. There are several styles available:

  • slide_short: The text stops at an edge, reverts to its initial position and slides again.
  • slide_long: The text is originally empty. It slides in, all the way to the edge, continues sliding until the label is empty, and loops.
  • slide_bounce: The text moves backwards after stopping at the edge. In the example, it is set to bounce.
Evas_Object* label;
label = elm_label_add(->win);
elm_object_text_set(label, "This text is supposed to be really long.");
elm_label_slide_duration_set(label, 5.);
elm_object_style_set(label, "slide_bounce");
evas_object_show(label);

If needed, you can use the slide,end event to respond to the moment when the sliding text reaches its end.

Marker Text

A marker is a text that is centered and bold by default. As the default color is white, set the blue color in this example.

elm_object_style_set(label, "marker");
evas_object_color_set(label, 0, 0, 255, 255);

Styling the Text

You can apply basic styles to the text. For a bolded text, do as follows.

elm_object_text_set(label, "<b>This text is bold.</b>");

Using Simple Lists

Basic List

A list is a scrollable container, whose children are selected.

Evas_Object* list;
Evas_Object* icon;
list = elm_list_add(ad->win);
elm_list_item_append(list, "Text item", NULL, NULL, NULL, NULL);
icon = elm_icon_add(ad->win);
elm_icon_standard_set(icon, "chat");
elm_list_item_append(list, "Second item", icon, NULL, NULL, NULL);
Evas_Object* button;
button = elm_button_add();
elm_object_text_set(button, "Button");
elm_list_item_append(list, "Fourth item", NULL, button, NULL, NULL);
elm_list_go(list);

Any Evas Object can be added as an icon, either at the beginning (third parameter) or the end (fourth parameter).

List Orientation

By default, a list is set vertically. This is how to display it horizontally.

elm_list_horizontal_set(list, EINA_TRUE);

List Mode

There are several modes for the list item dimensions.

  • ELM_LIST_COMPRESS: The list does not set any size measures to inform the container how to resize it. If the list is not created as a "resize object", its dimensions are zeroed. The list respects the container's geometry and if any of the list items do not fit into the container transverse axis, the list does not scroll in that direction.
  • ELM_LIST_SCROLL: This is the default value. This list is the same as ELM_LIST_COMPRESS, with the exception that if any of the list items do not fit into the container transverse axis, the list still scrolls in that direction.
  • ELM_LIST_LIMIT: This list sets a minimum size measure on the list object, so that containers may respect it (and resize themselves to fit the child properly). More specifically, a minimum size measure is set for its transverse axis, so that the largest item in that direction fits well. This feature is bound by the list object's maximum size measures that are set externally.
  • ELM_LIST_EXPAND: Besides setting a minimum size on the transverse axis, as in ELM_LIST_LIMIT, this list sets a minimum size on the longitudinal axis to reserve space for all its children to be visible at the same time. This feature is bound by the list object's maximum size measures that are set externally.
elm_list_mode_set(list, ELM_LIST_COMPRESS);

Scroller Policy

Several effects are shown on a list.

For example, the scroller is set to bounce at the end on either direction.

elm_scroller_bounce_set(list, EINA_TRUE, EINA_TRUE);

This is how to control displaying scrollbars. The second argument is for the horizontal axis, the third one for the vertical axis.

elm_scroller_policy_set(list, ELM_SCROLLER_POLICY_AUTO, ELM_SCROLLER_POLICY_ON);

As for the bounce preference, the second argument is for the horizontal axis, the third one for the vertical axis.

  • ELM_SCROLLER_POLICY_OFF hides the scrollbar
  • ELM_SCROLLER_POLICY_ON shows the scrollbar
  • ELM_SCROLLER_POLICY_AUTO the scrollbar is shown only when needed and stays hidden at other times

Events

A list responds to several events:

  • activated: The user clicks or presses an item.
  • selected: The user selects an item.
  • unselected: The user unselects an item.
  • longpressed: The user long-presses an item.
  • edge,top: The user scrolls the list to the top edge.
  • edge,bottom: The user scrolls the list to the bottom edge.
  • edge,left: The user scrolls the list to the left edge.
  • edge,right: The user scrolls the list to the right edge.
  • highlighted: An item is pressed and highlighted.
  • unhighlighted: The press and highlight is removed on an item.
Go to top