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
- 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
- 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 exampleen_US.utf8
ores_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
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.
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
- 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