Win - General API overview

For most users of the Elementary API, the Win widget has a lot more functions than what they need.

In general, a developer will create a window, set some content on it and forget about it for the rest of its program's life, letting whatever Window Manager is there to handle the window. Here, however, we are going to show how to generally manage a window.

We'll have a bit more than the usual includes here, since part of the example requires some low level fiddling.

#ifdef HAVE_ELEMENTARY_X
# include <Ecore_X.h>
#endif

#include <Elementary.h>

The program then, consists of one window with two lists of buttons, each of which operates on another two windows. One of them is a normal window, the other has the override flag set so the Window Manager ignores it.

Pressing each button will call the corresponding function to act on the corresponding window. These are pretty self explanatory, so we'll show them in one batch.

static void
_btn_activate_cb(void *data, Evas_Object *obj EINA_UNUSED, void *event EINA_UNUSED)
{
   elm_win_activate(data);
}

static void
_btn_lower_cb(void *data, Evas_Object *obj EINA_UNUSED, void *event EINA_UNUSED)
{
   elm_win_lower(data);
}

static void
_btn_raise_cb(void *data, Evas_Object *obj EINA_UNUSED, void *event EINA_UNUSED)
{
   elm_win_raise(data);
}

static void
_btn_borderless_cb(void *data, Evas_Object *obj EINA_UNUSED, void *event EINA_UNUSED)
{
   Eina_Bool flag = elm_win_borderless_get(data);
   elm_win_borderless_set(data, !flag);
}

static void
_btn_shaped_cb(void *data, Evas_Object *obj EINA_UNUSED, void *event EINA_UNUSED)
{
   Eina_Bool flag = elm_win_shaped_get(data);
   elm_win_shaped_set(data, !flag);
}

static void
_btn_alpha_cb(void *data, Evas_Object *obj EINA_UNUSED, void *event EINA_UNUSED)
{
   Eina_Bool flag = elm_win_alpha_get(data);
   elm_win_alpha_set(data, !flag);
}

static void
_btn_fullscreen_cb(void *data, Evas_Object *obj EINA_UNUSED, void *event EINA_UNUSED)
{
   Eina_Bool flag = elm_win_fullscreen_get(data);
   elm_win_fullscreen_set(data, !flag);
}

static void
_btn_maximized_cb(void *data, Evas_Object *obj EINA_UNUSED, void *event EINA_UNUSED)
{
   Eina_Bool flag = elm_win_maximized_get(data);
   elm_win_maximized_set(data, !flag);
}

static void
_btn_iconified_cb(void *data, Evas_Object *obj EINA_UNUSED, void *event EINA_UNUSED)
{
   Eina_Bool flag = elm_win_iconified_get(data);
   elm_win_iconified_set(data, !flag);
}

static void
_btn_rotation_cb(void *data, Evas_Object *obj EINA_UNUSED, void *event EINA_UNUSED)
{
   int angle = elm_win_rotation_get(data);
   angle = (angle + 90) % 360;
   elm_win_rotation_set(data, angle);
}

static void
_btn_rotation_resize_cb(void *data, Evas_Object *obj EINA_UNUSED, void *event EINA_UNUSED)
{
   int angle = elm_win_rotation_get(data);
   angle = (angle + 90) % 360;
   elm_win_rotation_with_resize_set(data, angle);
}

static void
_btn_sticky_cb(void *data, Evas_Object *obj EINA_UNUSED, void *event EINA_UNUSED)
{
   Eina_Bool flag = elm_win_sticky_get(data);
   elm_win_sticky_set(data, !flag);
}

Next, we handle the main window closing. We have a "delete,request" callback set to ask if really want to quit. If so, we end the main loop, otherwise just delete the popup message and continue running normally.

static void
_yes_quit_cb(void *data EINA_UNUSED, Evas_Object *obj EINA_UNUSED, void *event EINA_UNUSED)
{
   elm_exit();
}

static void
_no_quit_cb(void *data, Evas_Object *obj EINA_UNUSED, void *event EINA_UNUSED)
{
   evas_object_del(data);
}

static void
_main_win_del_cb(void *data EINA_UNUSED, Evas_Object *obj, void *event EINA_UNUSED)
{
   Evas_Object *msg, *box, *box2, *btn, *lbl, *sep;

   msg = elm_notify_add(obj);
   elm_notify_align_set(msg, 0.5, 0.5);
   elm_notify_allow_events_set(msg, EINA_FALSE);
   evas_object_show(msg);

   box = elm_box_add(obj);
   evas_object_size_hint_weight_set(box, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
   evas_object_size_hint_align_set(box, EVAS_HINT_FILL, EVAS_HINT_FILL);
   elm_object_content_set(msg, box);
   evas_object_show(box);

   lbl = elm_label_add(obj);
   elm_object_text_set(lbl, "Really want quit?");
   evas_object_size_hint_weight_set(lbl, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
   evas_object_size_hint_align_set(lbl, EVAS_HINT_FILL, EVAS_HINT_FILL);
   elm_box_pack_end(box, lbl);
   evas_object_show(lbl);

   sep = elm_separator_add(obj);
   elm_separator_horizontal_set(sep, EINA_TRUE);
   elm_box_pack_end(box, sep);
   evas_object_show(sep);

   box2 = elm_box_add(obj);
   elm_box_horizontal_set(box2, EINA_TRUE);
   evas_object_size_hint_weight_set(box2, EVAS_HINT_EXPAND, 0.0);
   evas_object_size_hint_align_set(box2, EVAS_HINT_FILL, EVAS_HINT_FILL);
   elm_box_pack_end(box, box2);
   evas_object_show(box2);

   btn = elm_button_add(obj);
   elm_object_text_set(btn, "Yes");
   elm_box_pack_end(box2, btn);
   evas_object_show(btn);

   evas_object_smart_callback_add(btn, "clicked", _yes_quit_cb, NULL);

   btn = elm_button_add(obj);
   elm_object_text_set(btn, "No");
   elm_box_pack_end(box2, btn);
   evas_object_show(btn);

   evas_object_smart_callback_add(btn, "clicked", _no_quit_cb, msg);
}

The non-managed window, being completely ignored by the Window Manager, is likely to never receive keyboard focus, even if we click on its entry to write something. So we have a button on it that will forcefully focus it by using some lower level functions to act directly on the X window. Then, each time one of the window is focused, we print some message on a console to show this more clearly.

static void
_force_focus_cb(void *data EINA_UNUSED, Evas_Object *obj EINA_UNUSED, void *event EINA_UNUSED)
{
#ifdef HAVE_ELEMENTARY_X
   Ecore_X_Window xwin = elm_win_xwindow_get(data);
   ecore_x_window_focus(xwin);
#endif
}

static void
_win_focused_cb(void *data, Evas_Object *obj EINA_UNUSED, void *event EINA_UNUSED)
{
   const char *name = data;
   printf("Window focused: %s\n", name);
}

And to finalize, the main function creates a window to hold all the action buttons and another two to show how (and what) works on each of them.

First, the main window will be a normal window, we'll enable the focus highlight regardless of how it is configured so it's easier to navigate the window with the keyboard. Then we hook our focus and delete callbacks and set up the rest of the window's content.

static Eina_Bool
key_down()
{
   elm_win_fullscreen_set(win2, 0);

   return ECORE_CALLBACK_PASS_ON;
}

EAPI_MAIN int
elm_main(int argc EINA_UNUSED, char **argv EINA_UNUSED)
{
   Evas_Object *win, *bigbox, *box, *btn, *o;
   char buf[256];

   elm_app_info_set(elm_main, "elementary", "images/logo.png");

   win = elm_win_util_standard_add("win-example", "Elm_Win Example");
   elm_win_focus_highlight_enabled_set(win, EINA_TRUE);

   evas_object_smart_callback_add(win, "focus,in", _win_focused_cb, "mainwin");

   evas_object_smart_callback_add(win, "delete,request", _main_win_del_cb,
                                  NULL);

   ecore_event_handler_add(ECORE_EVENT_KEY_DOWN, key_down, NULL);

   bigbox = elm_box_add(win);
   elm_box_horizontal_set(bigbox, EINA_TRUE);
   evas_object_size_hint_weight_set(bigbox, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
   elm_win_resize_object_add(win, bigbox);
   evas_object_show(bigbox);

   box = elm_box_add(win);
   evas_object_size_hint_weight_set(box, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
   evas_object_size_hint_align_set(box, EVAS_HINT_FILL, EVAS_HINT_FILL);
   elm_box_pack_end(bigbox, box);
   evas_object_show(box);

The first of our sub-windows is the managed one. We'll create it as a dialog, which should make the Window Manager treat it as a non-resizable window. We are also setting the window to be auto-deleted when the close button in the titlebar is pressed.

   win2 = elm_win_add(NULL, "sub-win-example", ELM_WIN_DIALOG_BASIC);
   elm_win_autodel_set(win2, EINA_TRUE);
   elm_win_title_set(win2, "Managed window");
   evas_object_show(win2);

   evas_object_smart_callback_add(win2, "focus,in", _win_focused_cb, "managed");

   o = elm_icon_add(win2);
   sprintf(buf, "%s/images/logo.png", elm_app_data_dir_get());
   elm_image_file_set(o, buf, NULL);
   elm_image_resizable_set(o, EINA_FALSE, EINA_FALSE);
   elm_image_no_scale_set(o, EINA_TRUE);
   elm_win_resize_object_add(win2, o);
   evas_object_show(o);

Now, we added an icon to the window as a resize object. We also set this icon to not scale, and no weight size hints have been set for it. This way, even if we hadn't created the window as a dialog, it would still not be resizable. The window size is defined by its content, so it would never be smaller than the smallest of its resize objects, and for it to be resizable, all of those objects have to allow it.

Next, we add the buttons with the actions to perform on this window. Using a macro saves us typing and makes the world a happier place.

   o = elm_label_add(win);
   elm_object_text_set(o, "<b>Managed Window</b>");
   elm_box_pack_end(box, o);
   evas_object_show(o);

#define WIN_ACTION(name) \
   do { \
        btn = elm_button_add(win); \
        elm_object_text_set(btn, #name); \
        elm_box_pack_end(box, btn); \
        evas_object_show(btn); \
        evas_object_smart_callback_add(btn, "clicked", _btn_##name##_cb, win2); \
   } while (0)

   WIN_ACTION(activate);
   WIN_ACTION(lower);
   WIN_ACTION(raise);
   WIN_ACTION(borderless);
   WIN_ACTION(shaped);
   WIN_ACTION(alpha);
   WIN_ACTION(fullscreen);
   WIN_ACTION(maximized);
   WIN_ACTION(iconified);
   WIN_ACTION(rotation);
   WIN_ACTION(rotation_resize);
   WIN_ACTION(sticky);

The maximize one is likely to not work, because the Window Manager will probably not enforce it upon a window that states its maximum size, much less a dialog. But that can be changed by editting the example to use ELM_WIN_BASIC when creating the window and adding the following line to the icon set as content

 evas_object_size_hint_weight_set(o, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);

Lastly, the second sub-window will have it's override flag set. In it we have a label with some text, and entry and a button. The entry can be clicked normally to set focus on it, but whether it actually gets keyboard input will also depend on the window getting focus, and since the window is an override one, it will probably not gain it by normal means. The button is there to force the focus at the X level to go to our window. And to finish, another list of buttons with actions to perform on this last window. Remember that most of them are requests or hints for the Window Manager, so they are likely to do nothing on this window. Similarly, there won't be any way to move it or resize it, because we haven't implemented that kind of control on this example and that's something controlled by Window Managers on windows they are tracking, which is not the case with this one.

   box = elm_box_add(win);
   evas_object_size_hint_weight_set(box, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
   evas_object_size_hint_align_set(box, EVAS_HINT_FILL, EVAS_HINT_FILL);
   elm_box_pack_end(bigbox, box);
   evas_object_show(box);

   win2 = elm_win_util_standard_add("sub-win-example2", "Non-managed window");
   elm_win_autodel_set(win2, EINA_TRUE);
   elm_win_override_set(win2, EINA_TRUE);
   evas_object_show(win2);

   evas_object_smart_callback_add(win2, "focus,in", _win_focused_cb,
                                  "override");

   bigbox = elm_box_add(win2);
   evas_object_size_hint_weight_set(bigbox, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
   elm_win_resize_object_add(win2, bigbox);
   evas_object_show(bigbox);

   o = elm_label_add(win2);
   elm_object_text_set(o, "This window should have no borders or titlebar.<ps>"
                       "It was set in override mode, so the Window Manager<ps>"
                       "should ignore everything about it.<ps>"
                       "It's up to the program to handle it properly, and some"
                       "of the actions performed on it may not have any effect."
                      );
   elm_box_pack_end(bigbox, o);
   evas_object_show(o);

   o = elm_entry_add(win2);
   elm_object_text_set(o, "See if you can focus me");
   elm_entry_single_line_set(o, EINA_TRUE);
   elm_entry_scrollable_set(o, EINA_TRUE);
   evas_object_size_hint_weight_set(o, EVAS_HINT_EXPAND, 0.0);
   evas_object_size_hint_align_set(o, EVAS_HINT_FILL, EVAS_HINT_FILL);
   elm_box_pack_end(bigbox, o);
   evas_object_show(o);

   o = elm_separator_add(win2);
   elm_separator_horizontal_set(o, EINA_TRUE);
   elm_box_pack_end(bigbox, o);
   evas_object_show(o);

   o = elm_button_add(win2);
   elm_object_text_set(o, "Focus me");
   elm_box_pack_end(bigbox, o);
   evas_object_show(o);

   evas_object_smart_callback_add(o, "clicked", _force_focus_cb, win2);

   o = elm_label_add(win);
   elm_object_text_set(o, "<b>Override Window</b>");
   elm_box_pack_end(box, o);
   evas_object_show(o);

   WIN_ACTION(activate);
   WIN_ACTION(lower);
   WIN_ACTION(raise);
   WIN_ACTION(borderless);
   WIN_ACTION(shaped);
   WIN_ACTION(alpha);
   WIN_ACTION(fullscreen);
   WIN_ACTION(maximized);
   WIN_ACTION(iconified);
   WIN_ACTION(rotation);
   WIN_ACTION(rotation_resize);
   WIN_ACTION(sticky);

   evas_object_resize(win, 400, 400);
   evas_object_show(win);

   elm_run();

   return 0;
}
ELM_MAIN()

The full code listing of this example can be found at win_example.c.