What is elementary?

Elementary is a the high level toolkit based on the underlying efl technologies (Evas, Edje, Ecore, etc...). It provide all the widget you need to build a full application.

It is meant to make the programmers work almost brainless but give them lots of flexibility.


Widget callbacks

Widget callbacks are set with callback_*_add methods which take a callable, and optional args, kwargs as data.

The callbacks have a signature of either:

obj, *args, **kwargs


obj, event_info, *args, **kwargs

Event callbacks

Event callbacks have signature of:

object, source_object, event_type, event_info, *args, **kwargs

A sample Python Elementary program

#!/usr/bin/env python
# encoding: utf-8

from efl import elementary
from efl.elementary.window import StandardWindow, DialogWindow
from efl.elementary.box import Box
from efl.elementary.button import Button
from efl.elementary.label import Label

def clicked_cb(btn, parent):
    dia = DialogWindow(parent, "window-dia", "DialogWindow",
                       size=(200,150), autodel=True)

    lb = Label(dia, text="This is a DialogWindow",


def window_dialog_clicked(obj):
    win = StandardWindow("window-states", "This is a StandardWindow",
                         autodel=True, size=(400, 400))
    if obj is None:
        win.callback_delete_request_add(lambda o: elementary.exit())

    box = Box(win, size_hint_weight=EXPAND_BOTH)
    bt = Button(win, text="Create a new dialog")
    bt.callback_clicked_add(clicked_cb, win)


if __name__ == "__main__":



API Reference


Object layers

New in version 1.14.


where to place backgrounds


Evas_Object default layer (and thus for Elementary)


where focus object visualization is


where to show tooltips


where to show cursors


last layer known by Elementary

Policy types


Under which circumstances the application should quit automatically.


Defines elm_exit() behaviour. (since 1.8)


Defines how throttling should work (since 1.8)

Quit policy types


Never quit the application automatically


Quit when the application’s last window is closed


Quit when the application’s last window is hidden

New in version 1.15.

Exit policy types

Possible values for the ELM_POLICY_EXIT policy.


Just quit the main loop on exit().


Delete all the windows after quitting the main loop.

Throttle policy types

Possible values for the #ELM_POLICY_THROTTLE policy.


Do whatever elementary config is configured to do.


Always throttle when all windows are no longer visible.


Never throttle when windows are all hidden, regardless of config settings.

Object multi select policy values

Possible values for the #ELM_OBJECT_MULTI_SELECT_MODE policy.

New in version 1.18.


Default multiple select mode.


Disallow mutiple selection when clicked without control key pressed.



The process is in a foreground/active/running state - work as normal.

New in version 1.12.


The process is in the bacgkround, so you may want to stop animating, fetching data as often etc.

New in version 1.12.

Notify close reasons

The reason the notification was closed


The notification expired.

New in version 1.10.


The notification was dismissed by the user.

New in version 1.10.


The notification was closed by a call to CloseNotification method.

New in version 1.10.


Undefined/reserved reasons.

New in version 1.10.

Notify urgency levels

Urgency levels of a notification



New in version 1.10.



New in version 1.10.



New in version 1.10.

Glob matching

Glob matching bitfiled flags


Treat backslash as an ordinary character instead of escape.

New in version 1.11.


Match a slash in string only with a slash in pattern and not by an asterisk (*) or a question mark (?) metacharacter, nor by a bracket expression ([]) containing a slash.

New in version 1.11.


Leading period in string has to be matched exactly by a period in pattern. A period is considered to be leading if it is the first character in string, or if both ELM_GLOB_MATCH_PATH is set and the period immediately follows a slash.

New in version 1.11.


The pattern is matched case-insensitively.

New in version 1.11.


General Elementary API. Functions that don’t relate to Elementary objects specifically.

Here are documented functions which init/shutdown the library, that apply to generic Elementary objects, that deal with configuration, et cetera.

class efl.elementary.EthumbConnect

Bases: efl.ecore.Event

class efl.elementary.ConfigAllChanged

Bases: efl.ecore.Event

class efl.elementary.PolicyChanged

Bases: efl.ecore.Event


new_value: ‘int’


old_value: ‘int’


policy: ‘unsigned int’

class efl.elementary.ProcessBackground

Bases: efl.ecore.Event

class efl.elementary.ProcessForeground

Bases: efl.ecore.Event

efl.elementary.on_ethumb_connect(func, *args, **kwargs)

Use this to set a handler for the ethumb connect event.

New in version 1.14.

efl.elementary.on_config_all_changed(func, *args, **kwargs)

Use this to set a handler for the config all changed event.

Emitted when the application has reconfigured elementary settings due to an external configuration tool asking it to.

New in version 1.14.

efl.elementary.on_policy_changed(func, *args, **kwargs)

Use this to set a handler for the policy changed event.

Emitted when any Elementary’s policy value is changed.

New in version 1.14.

efl.elementary.on_process_background(func, *args, **kwargs)

Use this to set a handler for the process background event.

Emitted when nothing is visible and the process as a whole should go into a background state.

New in version 1.14.

efl.elementary.on_process_foreground(func, *args, **kwargs)

Use this to set a handler for the process foreground event.

Emitted when going from nothing being visible to at least one window being visible.

New in version 1.14.


Initialize Elementary

Return int:The init counter value.

This function initializes Elementary and increments a counter of the number of calls to it. It returns the new counter’s value.

Changed in version 1.14: The Python module calls this function when it is imported so you should no longer have any need to call this manually. Calling it does not carry any penalty though.


Shut down Elementary

Return int:The init counter value.

This should be called at the end of your application, just before it ceases to do any more processing. This will clean up any permanent resources your application may have allocated via Elementary that would otherwise persist.


shutdown() will iterate main loop until all ecore_evas are freed. There is a possibility to call your ecore callbacks(timer, animator, event, job, and etc.) in shutdown()

Changed in version 1.14: The Python module calls this function when it is exiting so you should no longer have any need to call this manually. Calling it does not carry any penalty though.


Run Elementary’s main loop

This call should be issued just after all initialization is completed. This function will not return until exit() is called. It will keep looping, running the main (event/processing) loop for Elementary.


Ask to exit Elementary’s main loop

If this call is issued, it will flag the main loop to cease processing and return back to its parent function (usually your elm_main() function). This does not mean the main loop instantly quits. So your ecore callbacks(timer, animator, event, job, and etc.) have chances to be called even after exit().


By using the appropriate ELM_POLICY_QUIT on your Elementary applications, you’ll be able to get this function called automatically for you.

efl.elementary.policy_set(policy, value)

Set new policy value.

This will emit the ecore event ELM_EVENT_POLICY_CHANGED in the main loop giving the event information Elm_Event_Policy_Changed with policy identifier, new and old values.

  • policy (Policy types) – policy identifier as in Elm_Policy.
  • value (Quit policy types) – policy value, depends on identifiers, usually there is an enumeration with the same prefix as the policy name, for example: ELM_POLICY_QUIT and Elm_Policy_Quit (ELM_POLICY_QUIT_NONE, ELM_POLICY_QUIT_LAST_WINDOW_CLOSED).

True on success or False on error (right now just invalid policy identifier, but in future policy value might be enforced).


Gets the policy value set for given identifier.

Parameters:policy (Policy types) – policy identifier as in Elm_Policy.
Returns:policy value. Will be 0 if policy identifier is invalid.
Return type:Quit policy types

Change the language of the current application

The lang passed must be the full name of the locale to use, for example en_US.utf8 or es_ES@euro.

Changing language with this function will make Elementary run through all its widgets, translating strings set with elm_object_domain_translatable_part_text_set(). This way, an entire UI can have its language changed without having to restart the program.

For more complex cases, like having formatted strings that need translation, widgets will also emit a “language,changed” signal that the user can listen to and manually translate the text.

Parameters:lang – Language to set, must be the full name of the locale

Get the process state as a while.

The process may logically be some runnable state. a “foreground” application runs as normal and may be user-visible or “active” in some way. A background application is not user-visible or otherwise important and likely should release resources and not wake up often or process much.

Returns:The current process state
Return type:Elm_Process_State

New in version 1.12.


Elementary is designed to be finger-friendly for touchscreens, and so in addition to scaling for display resolution, it can also scale based on finger “resolution” (or size). You can then customize the granularity of the areas meant to receive clicks on touchscreens.

Different profiles may have pre-set values for finger sizes.

efl.elementary.coords_finger_size_adjust(times_w, w, times_h, h)

Adjust size of an element for finger usage.

  • times_w (int) – How many fingers should fit horizontally
  • w (int) – Width size to adjust
  • times_h (int) – How many fingers should fit vertically
  • h (int) – Height size to adjust

The adjusted width and height

Return type:

(int w, int h)

This takes width and height sizes (in pixels) as input and a size multiple (which is how many fingers you want to place within the area, being “finger” the size set by elm_config_finger_size_set()), and adjusts the size to be large enough to accommodate the resulting size – if it doesn’t already accommodate it.


This is kind of low level Elementary call, most useful on size evaluation times for widgets. An external user wouldn’t be calling, most of the time.


These are functions which let one fine-tune some cache values for Elementary applications, thus allowing for performance adjustments.


Frees all data that was in cache and is not currently being used to reduce memory usage. This frees Edje’s, Evas’ and Eet’s cache.


Evas caches are flushed for every canvas associated with a window.

New in version 1.8.


These are functions dealing with font rendering, selection and the like for Elementary applications. One might fetch which system fonts are there to use and set custom fonts for individual classes of UI items containing text (text classes).


Translate a font (family) name string in fontconfig’s font names syntax into a FontProperties object.

Parameters:font – The font name and styles string
Returns:the font properties object


The reverse translation can be achieved with font_fontconfig_name_get(), for one style only (single font instance, not family).

New in version 1.8.


Free font properties return by font_properties_get().

Parameters:fp – the font properties struct

New in version 1.8.

efl.elementary.font_fontconfig_name_get(font_name, style=None)

Translate a font name, bound to a style, into fontconfig’s font names syntax.

  • font_name – The font (family) name
  • style – The given style (may be None)

the font name and style string


The reverse translation can be achieved with font_properties_get(), for one style only (single font instance, not family).

New in version 1.8.

class efl.elementary.FontProperties

Bases: object

Type:list of strings


Don’t use them unless you are sure.


Print Tree object hierarchy in stdout

Parameters:top – The root object

New in version 1.8.

efl.elementary.object_tree_dot_dump(top, path)

Print Elm Objects tree hierarchy in file as dot(graphviz) syntax.

  • top – The root object
  • path – The path of output file

New in version 1.8.

Sys Notify


Causes a notification to be forcefully closed and removed from the user’s view. It can be used, for example, in the event that what the notification pertains to is no longer relevant, or to cancel a notification * with no expiration time.

Parameters:id – Notification id


If the notification no longer exists, an empty D-BUS Error message is sent back.

New in version 1.10.

efl.elementary.sys_notify_send(replaces_id=0, icon=None, summary=None, body=None, urgency=enums.ELM_SYS_NOTIFY_URGENCY_NORMAL, timeout=-1, cb=None, cb_data=None)

Sends a notification to the notification server.

  • replaces_id – Notification ID that this notification replaces. The value 0 means a new notification.
  • icon – The optional program icon of the calling application.
  • summary – The summary text briefly describing the notification.
  • body – The optional detailed body text. Can be empty.
  • urgency – The urgency level.
  • timeout – Timeout display in milliseconds.
  • cb – Callback used to retrieve the notification id return by the Notification Server.
  • cb_data – Optional context data

New in version 1.10.

efl.elementary.on_sys_notify_notification_closed(func, *args, **kargs)
efl.elementary.on_sys_notify_action_invoked(func, *args, **kargs)
class efl.elementary.SysNotifyNotificationClosed

Bases: efl.ecore.Event


ID of the notification.


The Reason the notification was closed.

Type:Notify close reasons
class efl.elementary.SysNotifyActionInvoked

Bases: efl.ecore.Event


The key of the action invoked. These match the keys sent over in the list of actions.


ID of the notification.


Inheritance diagram

Inheritance diagram of efl.elementary.Actionslider, efl.elementary.Background, efl.elementary.Box, efl.elementary.Bubble, efl.elementary.Button, efl.elementary.Calendar, efl.elementary.Check, efl.elementary.Clock, efl.elementary.Colorselector, efl.elementary.Combobox, efl.elementary.Configuration, efl.elementary.Conformant, efl.elementary.Ctxpopup, efl.elementary.Datetime, efl.elementary.Dayselector, efl.elementary.Diskselector, efl.elementary.Entry, efl.elementary.Fileselector, efl.elementary.FileselectorButton, efl.elementary.FileselectorEntry, efl.elementary.Flip, efl.elementary.FlipSelector, efl.elementary.Frame, efl.elementary.Gengrid, efl.elementary.Genlist, efl.elementary.GestureLayer, efl.elementary.Grid, efl.elementary.Hover, efl.elementary.Hoversel, efl.elementary.Icon, efl.elementary.Image, efl.elementary.Index, efl.elementary.InnerWindow, efl.elementary.Label, efl.elementary.Layout, efl.elementary.List, efl.elementary.Map, efl.elementary.Mapbuf, efl.elementary.Menu, efl.elementary.MultiButtonEntry, efl.elementary.Naviframe, efl.elementary.Notify, efl.elementary.Object, efl.elementary.ObjectItem, efl.elementary.Panel, efl.elementary.Panes, efl.elementary.Photo, efl.elementary.Photocam, efl.elementary.Plug, efl.elementary.Popup, efl.elementary.Progressbar, efl.elementary.Radio, efl.elementary.Scroller, efl.elementary.SegmentControl, efl.elementary.Separator, efl.elementary.Slider, efl.elementary.Slideshow, efl.elementary.Spinner, efl.elementary.Systray, efl.elementary.Table, efl.elementary.Theme, efl.elementary.Thumb, efl.elementary.Toolbar, efl.elementary.Transit, efl.elementary.Video, efl.elementary.Web, efl.elementary.Window