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.

Callbacks

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

or:

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.evas import EVAS_HINT_EXPAND, EVAS_HINT_FILL, EXPAND_BOTH
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",
               size_hint_weight=EXPAND_BOTH)
    dia.resize_object_add(lb)
    lb.show()

    dia.show()

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)
    win.resize_object_add(box)
    box.show()
    
    bt = Button(win, text="Create a new dialog")
    bt.callback_clicked_add(clicked_cb, win)
    box.pack_end(bt)
    bt.show()

    win.show()


if __name__ == "__main__":

    window_dialog_clicked(None)

    elementary.run()

API Reference

Enumerations

Object layers

New in version 1.14.

efl.elementary.ELM_OBJECT_LAYER_BACKGROUND

where to place backgrounds

efl.elementary.ELM_OBJECT_LAYER_DEFAULT

Evas_Object default layer (and thus for Elementary)

efl.elementary.ELM_OBJECT_LAYER_FOCUS

where focus object visualization is

efl.elementary.ELM_OBJECT_LAYER_TOOLTIP

where to show tooltips

efl.elementary.ELM_OBJECT_LAYER_CURSOR

where to show cursors

efl.elementary.ELM_OBJECT_LAYER_LAST

last layer known by Elementary

Policy types

efl.elementary.ELM_POLICY_QUIT

Under which circumstances the application should quit automatically.

efl.elementary.ELM_POLICY_EXIT

Defines elm_exit() behaviour. (since 1.8)

efl.elementary.ELM_POLICY_THROTTLE

Defines how throttling should work (since 1.8)

Quit policy types

efl.elementary.ELM_POLICY_QUIT_NONE

Never quit the application automatically

efl.elementary.ELM_POLICY_QUIT_LAST_WINDOW_CLOSED

Quit when the application’s last window is closed

efl.elementary.ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN

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.

efl.elementary.ELM_POLICY_EXIT_NONE

Just quit the main loop on exit().

efl.elementary.ELM_POLICY_EXIT_WINDOWS_DEL

Delete all the windows after quitting the main loop.

Throttle policy types

Possible values for the #ELM_POLICY_THROTTLE policy.

efl.elementary.ELM_POLICY_THROTTLE_CONFIG

Do whatever elementary config is configured to do.

efl.elementary.ELM_POLICY_THROTTLE_HIDDEN_ALWAYS

Always throttle when all windows are no longer visible.

efl.elementary.ELM_POLICY_THROTTLE_NEVER

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.

efl.elementary.ELM_OBJECT_MULTI_SELECT_MODE_DEFAULT

Default multiple select mode.

efl.elementary.ELM_OBJECT_MULTI_SELECT_MODE_WITH_CONTROL

Disallow mutiple selection when clicked without control key pressed.

Elm_Process_State

efl.elementary.ELM_PROCESS_STATE_FOREGROUND

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

New in version 1.12.

efl.elementary.ELM_PROCESS_STATE_BACKGROUND

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

efl.elementary.ELM_SYS_NOTIFY_CLOSED_EXPIRED

The notification expired.

New in version 1.10.

efl.elementary.ELM_SYS_NOTIFY_CLOSED_DISMISSED

The notification was dismissed by the user.

New in version 1.10.

efl.elementary.ELM_SYS_NOTIFY_CLOSED_REQUESTED

The notification was closed by a call to CloseNotification method.

New in version 1.10.

efl.elementary.ELM_SYS_NOTIFY_CLOSED_UNDEFINED

Undefined/reserved reasons.

New in version 1.10.

Notify urgency levels

Urgency levels of a notification

see

sys_notify_send()

efl.elementary.ELM_SYS_NOTIFY_URGENCY_LOW

Low

New in version 1.10.

efl.elementary.ELM_SYS_NOTIFY_URGENCY_NORMAL

Normal

New in version 1.10.

efl.elementary.ELM_SYS_NOTIFY_URGENCY_CRITICAL

Critical

New in version 1.10.

Glob matching

Glob matching bitfiled flags

efl.elementary.ELM_GLOB_MATCH_NO_ESCAPE

Treat backslash as an ordinary character instead of escape.

New in version 1.11.

efl.elementary.ELM_GLOB_MATCH_PATH

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.

efl.elementary.ELM_GLOB_MATCH_PERIOD

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.

efl.elementary.ELM_GLOB_MATCH_NOCASE

The pattern is matched case-insensitively.

New in version 1.11.

General

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

new_value: ‘int’

old_value

old_value: ‘int’

policy

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.

efl.elementary.init()

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.

efl.elementary.shutdown()

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.

Note

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.

efl.elementary.run()

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.

efl.elementary.exit()

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().

Note

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.

Parameters

• 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).

Returns

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

efl.elementary.policy_get(policy)

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

efl.elementary.language_set(lang)

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

efl.elementary.process_state_get()

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.

Fingers

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.

Parameters

• 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

Returns

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.

Note

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.

Caches

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

efl.elementary.cache_all_flush()

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.

Note

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

New in version 1.8.

Fonts

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).

efl.elementary.font_properties_get(font)

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

Note

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.

efl.elementary.font_properties_free(fp)

Free font properties return by font_properties_get().

Parameters

fp – the font properties struct

New in version 1.8.

Changed in version 1.19: Changed to no-op as we now do the free automatically when there are no more references to the FontProperties object

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

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

Parameters

• font_name – The font (family) name

• style – The given style (may be None)

Returns

the font name and style string

Note

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

Elementary font properties

name

Type

unicode

styles

Type

list of strings

Debug

Don’t use them unless you are sure.

efl.elementary.object_tree_dump(top)

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.

Parameters

• top – The root object

• path – The path of output file

New in version 1.8.

Sys Notify

efl.elementary.sys_notify_close(id)

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

Note

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.

Parameters

• 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

ID of the notification.

Type

int

reason

The Reason the notification was closed.

Type

Notify close reasons

class efl.elementary.SysNotifyActionInvoked

Bases: efl.ecore.Event

action_key

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

Type

string

id

ID of the notification.

Type

int

Widgets

• Actionslider
• Background
• Box
• Bubble
• Button
• Calendar
• Check
• Clock
• Colorselector
• Combobox
• Configuration
• Conformant
• Ctxpopup
• Datetime
• Dayselector
• Diskselector
• Entry
• Fileselector
• Fileselector Button
• Fileselector Entry
• Flip
• Flipselector
• Frame
• Gengrid
• Genlist
• Gesture Layer
• Grid
• Hover
• Hoversel
• Icon
• Image
• Index
• Innerwindow
• Label
• Layout
• List
• Map
• Mapbuf
• Menu
• MultiButtonEntry
• Naviframe
• Need
• Notify
• Object
• Object Item
• Panel
• Panes
• Photo
• Photocam
• Plug
• Popup
• Progressbar
• Radio
• Scroller
• Segment Control
• Separator
• Slider
• Slideshow
• Spinner
• Table
• Theme
• Thumb
• Toolbar
• Transit
• Video
• Web
• Window

Inheritance diagram