general Module

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.

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.

Enumerations

Policy types

efl.elementary.general.ELM_POLICY_QUIT

Under which circumstances the application should quit automatically.

efl.elementary.general.ELM_POLICY_EXIT

Defines elm_exit() behaviour. (since 1.8)

efl.elementary.general.ELM_POLICY_THROTTLE

Defines how throttling should work (since 1.8)

Quit policy types

efl.elementary.general.ELM_POLICY_QUIT_NONE

Never quit the application automatically

efl.elementary.general.ELM_POLICY_QUIT_LAST_WINDOW_CLOSED

Quit when the application’s last window is closed

Exit policy types

Possible values for the ELM_POLICY_EXIT policy.

efl.elementary.general.ELM_POLICY_EXIT_NONE

Just quit the main loop on exit().

efl.elementary.general.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.general.ELM_POLICY_THROTTLE_CONFIG

Do whatever elementary config is configured to do.

efl.elementary.general.ELM_POLICY_THROTTLE_HIDDEN_ALWAYS

Always throttle when all windows are no longer visible.

efl.elementary.general.ELM_POLICY_THROTTLE_NEVER

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

class efl.elementary.general.FontProperties

Bases: object

Elementary font properties

name

Type :unicode

styles

Type :list of strings

efl.elementary.general.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.

efl.elementary.general.coords_finger_size_adjust(int times_w, int w, int times_h, int h) → tuple

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.

efl.elementary.general.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.general.font_fontconfig_name_get(unicode font_name, unicode style = None) → unicode

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.

efl.elementary.general.font_properties_free()

Free font properties return by font_properties_get().

Parameters:fp – the font properties struct

New in version 1.8.

efl.elementary.general.font_properties_get(unicode font) → FontProperties

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.general.init() → int

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.

efl.elementary.general.language_set(unicode 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.general.object_tree_dot_dump(Object top, unicode 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.

efl.elementary.general.object_tree_dump(Object top)

Print Tree object hierarchy in stdout

Parameters:top – The root object

New in version 1.8.

efl.elementary.general.policy_get(Elm_Policy policy) → value

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.general.policy_set(Elm_Policy policy, value) → bool

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.general.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.general.shutdown() → int

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