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 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 have signature of:
object, source_object, event_type, event_info, *args, **kwargs
#!/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()
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
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)
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.
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.
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.
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.
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.
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.
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 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 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.
efl.elementary.
EthumbConnect
¶Bases: efl.ecore.Event
efl.elementary.
ConfigAllChanged
¶Bases: efl.ecore.Event
efl.elementary.
PolicyChanged
¶Bases: efl.ecore.Event
new_value
¶new_value: ‘int’
old_value
¶old_value: ‘int’
policy
¶policy: ‘unsigned int’
efl.elementary.
ProcessBackground
¶Bases: efl.ecore.Event
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: |
|
---|---|
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.
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: |
|
---|---|
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.
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.
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.
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: |
|
---|---|
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.
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: |
|
---|
New in version 1.8.
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: |
|
---|
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)¶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 |
---|
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 |
---|