Win - General API overview

For most users of the Elementary API, the Elm_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)
{
}
static void
_btn_lower_cb(void *data, Evas_Object *obj EINA_UNUSED, void *event EINA_UNUSED)
{
}
static void
_btn_raise_cb(void *data, Evas_Object *obj EINA_UNUSED, void *event EINA_UNUSED)
{
}
static void
_btn_borderless_cb(void *data, Evas_Object *obj EINA_UNUSED, void *event EINA_UNUSED)
{
elm_win_borderless_set(data, !flag);
}
static void
_btn_shaped_cb(void *data, Evas_Object *obj EINA_UNUSED, void *event EINA_UNUSED)
{
elm_win_shaped_set(data, !flag);
}
static void
_btn_alpha_cb(void *data, Evas_Object *obj EINA_UNUSED, void *event EINA_UNUSED)
{
elm_win_alpha_set(data, !flag);
}
static void
_btn_fullscreen_cb(void *data, Evas_Object *obj EINA_UNUSED, void *event EINA_UNUSED)
{
elm_win_fullscreen_set(data, !flag);
}
static void
_btn_maximized_cb(void *data, Evas_Object *obj EINA_UNUSED, void *event EINA_UNUSED)
{
elm_win_maximized_set(data, !flag);
}
static void
_btn_iconified_cb(void *data, Evas_Object *obj EINA_UNUSED, void *event EINA_UNUSED)
{
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;
}
static void
_btn_sticky_cb(void *data, Evas_Object *obj EINA_UNUSED, void *event EINA_UNUSED)
{
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)
{
}
static void
_no_quit_cb(void *data, Evas_Object *obj EINA_UNUSED, void *event EINA_UNUSED)
{
}
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);
box = elm_box_add(obj);
elm_object_content_set(msg, box);
lbl = elm_label_add(obj);
elm_object_text_set(lbl, "Really want quit?");
elm_box_pack_end(box, lbl);
sep = elm_separator_add(obj);
elm_separator_horizontal_set(sep, EINA_TRUE);
elm_box_pack_end(box, sep);
box2 = elm_box_add(obj);
elm_box_pack_end(box, box2);
btn = elm_button_add(obj);
elm_object_text_set(btn, "Yes");
elm_box_pack_end(box2, 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_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);
#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()
{
}
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");
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);
box = elm_box_add(win);
elm_box_pack_end(bigbox, 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_title_set(win2, "Managed window");
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);

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

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);
elm_box_pack_end(bigbox, box);
win2 = elm_win_util_standard_add("sub-win-example2", "Non-managed window");
evas_object_smart_callback_add(win2, "focus,in", _win_focused_cb,
"override");
bigbox = elm_box_add(win2);
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);
o = elm_entry_add(win2);
elm_object_text_set(o, "See if you can focus me");
elm_box_pack_end(bigbox, o);
o = elm_separator_add(win2);
elm_separator_horizontal_set(o, EINA_TRUE);
elm_box_pack_end(bigbox, o);
o = elm_button_add(win2);
elm_object_text_set(o, "Focus me");
elm_box_pack_end(bigbox, 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>");
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);
return 0;
}

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

Ecore_X.h
Ecore functions for dealing with the X Windows System.
elm_box_horizontal_set
void elm_box_horizontal_set(Elm_Box *obj, Eina_Bool horizontal)
Set the horizontal orientation.
Definition: elm_box_eo.legacy.c:27
elm_win_alpha_get
Eina_Bool elm_win_alpha_get(const Evas_Object *obj)
Get the alpha channel state of a window.
Definition: efl_ui_win.c:9795
elm_notify_add
EAPI Evas_Object * elm_notify_add(Evas_Object *parent)
Add a new notify to the parent.
Definition: elm_notify.c:478
ECORE_CALLBACK_PASS_ON
#define ECORE_CALLBACK_PASS_ON
Return value to pass event to next handler.
Definition: Ecore_Common.h:155
elm_win_resize_object_add
void elm_win_resize_object_add(Eo *obj, Evas_Object *subobj)
Add subobj as a resize object of window obj.
Definition: efl_ui_win.c:8995
elm_label_add
EAPI Evas_Object * elm_label_add(Evas_Object *parent)
Add a new label to the parent.
Definition: elm_label.c:421
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
EINA_UNUSED
#define EINA_UNUSED
Definition: eina_types.h:339
elm_win_shaped_set
void elm_win_shaped_set(Evas_Object *obj, Eina_Bool shaped)
Set the shaped state of a window.
Definition: efl_ui_win.c:8615
elm_win_raise
void elm_win_raise(Eo *obj)
Raise a window object.
Definition: efl_ui_win.c:6228
elm_win_fullscreen_get
Eina_Bool elm_win_fullscreen_get(const Evas_Object *obj)
Get the fullscreen state of a window.
Definition: efl_ui_win.c:9706
elm_win_lower
void elm_win_lower(Evas_Object *obj)
Lower a window object.
Definition: efl_ui_win.c:8048
elm_notify_allow_events_set
void elm_notify_allow_events_set(Elm_Notify *obj, Eina_Bool allow)
Sets whether events should be passed to by a click outside its area.
Definition: elm_notify_eo.legacy.c:15
elm_image_no_scale_set
EAPI void elm_image_no_scale_set(Evas_Object *obj, Eina_Bool no_scale)
Control scaling behaviour of this object.
Definition: efl_ui_image.c:2643
elm_win_iconified_get
Eina_Bool elm_win_iconified_get(const Evas_Object *obj)
Get the iconified state of a window.
Definition: efl_ui_win.c:9682
EINA_FALSE
#define EINA_FALSE
Definition: eina_types.h:533
elm_button_add
EAPI Evas_Object * elm_button_add(Evas_Object *parent)
Add a new button to the parent's canvas.
Definition: efl_ui_button.c:459
elm_image_resizable_set
EAPI void elm_image_resizable_set(Evas_Object *obj, Eina_Bool up, Eina_Bool down)
Control if the object is (up/down) resizable.
Definition: efl_ui_image.c:2661
EVAS_HINT_EXPAND
#define EVAS_HINT_EXPAND
Use with evas_object_size_hint_weight_set(), evas_object_size_hint_weight_get(), evas_object_size_hin...
Definition: Evas_Common.h:297
elm_win_xwindow_get
Ecore_X_Window elm_win_xwindow_get(const Evas_Object *obj)
Get the Ecore_X_Window of an Evas_Object.
Definition: efl_ui_win.c:7936
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.
elm_win_activate
void elm_win_activate(Evas_Object *obj)
Activate a window object.
Definition: efl_ui_win.c:9801
evas_object_smart_callback_add
void evas_object_smart_callback_add(Evas_Object *eo_obj, const char *event, Evas_Smart_Cb func, const void *data)
Add (register) a callback function to the smart event specified by event on the smart object obj.
Definition: evas_object_smart.c:1040
ecore_event_handler_add
Ecore_Event_Handler * ecore_event_handler_add(int type, Ecore_Event_Handler_Cb func, const void *data)
Adds an event handler.
Definition: ecore_events.c:13
Evas_Object
Efl_Canvas_Object Evas_Object
Definition: Evas_Common.h:185
elm_box_pack_end
void elm_box_pack_end(Elm_Box *obj, Efl_Canvas_Object *subobj)
Add an object at the end of the pack list.
Definition: elm_box_eo.legacy.c:57
elm_icon_add
Evas_Object * elm_icon_add(Evas_Object *parent)
Add a new icon object to the parent.
Definition: elm_icon.c:613
evas_object_resize
void evas_object_resize(Evas_Object *obj, Evas_Coord w, Evas_Coord h)
Changes the size of the given Evas object.
Definition: evas_object_main.c:1236
evas_object_size_hint_weight_set
void evas_object_size_hint_weight_set(Evas_Object *obj, double x, double y)
Sets the hints for an object's weight.
Definition: evas_object_main.c:2638
elm_win_add
Evas_Object * elm_win_add(Evas_Object *parent, const char *name, Elm_Win_Type type)
Adds a window object.
Definition: efl_ui_win.c:9547
elm_run
void elm_run(void)
Run Elementary's main loop.
Definition: elm_main.c:1362
elm_entry_add
EAPI Evas_Object * elm_entry_add(Evas_Object *parent)
This adds an entry to parent object.
Definition: elm_entry.c:4150
evas_object_size_hint_align_set
void evas_object_size_hint_align_set(Evas_Object *obj, double x, double y)
Sets the hints for an object's alignment.
Definition: evas_object_main.c:2650
ELM_MAIN
#define ELM_MAIN()
macro to be used after the elm_main() function
Definition: elm_general.h:528
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_image_file_set
EAPI Eina_Bool elm_image_file_set(Evas_Object *obj, const char *file, const char *group)
Set the file that will be used as the image's source.
Definition: efl_ui_image.c:2440
elm_win_maximized_set
void elm_win_maximized_set(Evas_Object *obj, Eina_Bool maximized)
Set the maximized state of a window.
Definition: efl_ui_win.c:9688
elm_exit
void elm_exit(void)
Ask to exit Elementary's main loop.
Definition: elm_main.c:1378
elm_win_title_set
void elm_win_title_set(Evas_Object *obj, const char *title)
Set the title of the window.
Definition: efl_ui_win.c:8639
evas_object_show
void evas_object_show(Evas_Object *eo_obj)
Makes the given Evas object visible.
Definition: evas_object_main.c:1814
EVAS_HINT_FILL
#define EVAS_HINT_FILL
Use with evas_object_size_hint_align_set(), evas_object_size_hint_align_get(), evas_object_size_hint_...
Definition: Evas_Common.h:298
elm_box_add
EAPI Evas_Object * elm_box_add(Evas_Object *parent)
Add a new box to the parent.
Definition: elm_box.c:363
EINA_TRUE
#define EINA_TRUE
Definition: eina_types.h:539
elm_win_iconified_set
void elm_win_iconified_set(Evas_Object *obj, Eina_Bool iconified)
Set the iconified state of a window.
Definition: efl_ui_win.c:9676
elm_win_override_set
void elm_win_override_set(Evas_Object *obj, Eina_Bool override)
Set the override state of a window.
Definition: efl_ui_win.c:8027
ELM_WIN_DIALOG_BASIC
@ ELM_WIN_DIALOG_BASIC
Used for simple dialog windows.
Definition: elm_win_legacy.h:67
elm_notify_align_set
void elm_notify_align_set(Elm_Notify *obj, double horizontal, double vertical)
Set the alignment of the notify object.
Definition: elm_notify_eo.legacy.c:3
elm_win_util_standard_add
Evas_Object * elm_win_util_standard_add(const char *name, const char *title)
Adds a window object with standard setup.
Definition: efl_ui_win.c:9579
elm_separator_add
Evas_Object * elm_separator_add(Evas_Object *parent)
Add a separator object to parent.
Definition: elm_separator.c:49
Eina_Bool
unsigned char Eina_Bool
Definition: eina_types.h:527
evas_object_del
void evas_object_del(Evas_Object *obj)
Marks the given Evas object for deletion (when Evas will free its memory).
Definition: evas_object_main.c:928
elm_win_rotation_set
void elm_win_rotation_set(Evas_Object *obj, int rotation)
Set the rotation of the window.
Definition: efl_ui_win.c:1782
elm_win_sticky_set
void elm_win_sticky_set(Evas_Object *obj, Eina_Bool sticky)
Set the sticky state of the window.
Definition: efl_ui_win.c:9712
elm_win_sticky_get
Eina_Bool elm_win_sticky_get(const Evas_Object *obj)
Get the sticky state of the window.
Definition: efl_ui_win.c:9718
ecore_x_window_focus
EAPI void ecore_x_window_focus(Ecore_X_Window win)
Sets the focus to the window win.
Definition: ecore_x_window.c:650
elm_win_borderless_get
Eina_Bool elm_win_borderless_get(const Evas_Object *obj)
Get the borderless state of a window.
Definition: efl_ui_win.c:9749
elm_win_borderless_set
void elm_win_borderless_set(Evas_Object *obj, Eina_Bool borderless)
Set the borderless state of a window.
Definition: efl_ui_win.c:9743
elm_win_rotation_get
int elm_win_rotation_get(const Evas_Object *obj)
Get the rotation of the window.
Definition: efl_ui_win.c:1788
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
elm_entry_scrollable_set
void elm_entry_scrollable_set(Elm_Entry *obj, Eina_Bool scroll)
Enable or disable scrolling in entry.
Definition: elm_entry_eo.legacy.c:3
elm_win_fullscreen_set
void elm_win_fullscreen_set(Evas_Object *obj, Eina_Bool fullscreen)
Set the fullscreen state of a window.
Definition: efl_ui_win.c:9700
elm_win_shaped_get
Eina_Bool elm_win_shaped_get(const Evas_Object *obj)
Get the shaped state of a window.
Definition: efl_ui_win.c:8630
elm_entry_single_line_set
void elm_entry_single_line_set(Elm_Entry *obj, Eina_Bool single_line)
Sets the entry to single line mode.
Definition: elm_entry_eo.legacy.c:123
elm_win_rotation_with_resize_set
void elm_win_rotation_with_resize_set(Evas_Object *obj, int rotation)
Rotates the window and resizes it.
Definition: efl_ui_win.c:8430
elm_win_alpha_set
void elm_win_alpha_set(Evas_Object *obj, Eina_Bool alpha)
Set the alpha channel state of a window.
Definition: efl_ui_win.c:9789
elm_win_maximized_get
Eina_Bool elm_win_maximized_get(const Evas_Object *obj)
Get the maximized state of a window.
Definition: efl_ui_win.c:9694