Configuration

Description

Elementary configuration is formed by a set options bounded to a given profile, like theme, “finger size”, etc.

These are functions with which one synchronizes changes made to those values to the configuration storing files, de facto. You most probably don’t want to use the functions in this group unless you’re writing an elementary configuration manager.

Profiles

Profiles are pre-set options that affect the whole look-and-feel of Elementary-based applications. There are, for example, profiles aimed at desktop computer applications and others aimed at mobile, touchscreen-based ones. You most probably don’t want to use the functions in this group unless you’re writing an elementary configuration manager.

Elementary Scrolling

These set how scrollable views in Elementary widgets should behave on user interaction.

Password show last

Show last feature of password mode enables user to view the last input entered for few seconds before masking it. These functions allow to set this feature in password mode of entry widget and also allow to manipulate the duration for which the input has to be visible.

Elementary Engine

These are functions setting and querying which rendering engine Elementary will use for drawing its windows’ pixels.

The following are the available engines:

• “software_x11”
• “fb”
• “directfb”
• “software_16_x11”
• “software_8_x11”
• “xrender_x11”
• “opengl_x11”
• “software_gdi”
• “software_16_wince_gdi”
• “sdl”
• “software_16_sdl”
• “opengl_sdl”
• “buffer”
• “ews”
• “opengl_cocoa”
• “psl1ght”

ATSPI AT-SPI2 Accessibility

Elementary widgets support Linux Accessibility standard. For more information please visit: http://www.linuxfoundation.org/collaborate/workgroups/accessibility/atk/at-spi/at-spi_on_d-bus

Enumerations

Elm_Softcursor_Mode

efl.elementary.ELM_SOFTCURSOR_MODE_AUTO

Auto-detect if a software cursor should be used (default)

efl.elementary.ELM_SOFTCURSOR_MODE_ON

Always use a softcursor

efl.elementary.ELM_SOFTCURSOR_MODE_OFF

Never use a softcursor

Elm_Slider_Indicator_Visible_Mode

efl.elementary.ELM_SLIDER_INDICATOR_VISIBLE_MODE_DEFAULT

show indicator on mouse down or change in slider value

efl.elementary.ELM_SLIDER_INDICATOR_VISIBLE_MODE_ALWAYS

Always show the indicator

efl.elementary.ELM_SLIDER_INDICATOR_VISIBLE_MODE_ON_FOCUS

Show the indicator on focus

efl.elementary.ELM_SLIDER_INDICATOR_VISIBLE_MODE_NONE

Never show the indicator

Audio Channels

efl.elementary.EDJE_CHANNEL_EFFECT

Standard audio effects

efl.elementary.EDJE_CHANNEL_BACKGROUND

Background audio sounds

efl.elementary.EDJE_CHANNEL_MUSIC

Music audio

efl.elementary.EDJE_CHANNEL_FOREGROUND

Foreground audio sounds

efl.elementary.EDJE_CHANNEL_INTERFACE

Sounds related to the interface

efl.elementary.EDJE_CHANNEL_INPUT

Sounds related to regular input

efl.elementary.EDJE_CHANNEL_ALERT

Sounds for major alerts

efl.elementary.EDJE_CHANNEL_ALL

All audio channels (convenience)

Inheritance diagram

class efl.elementary.Configuration

Bases: object

accel_preference

Elementary’s acceleration preferences for new windows

Note that it will take effect only to Elementary windows created after this is called. The value is a freeform string that indicates what kind of acceleration is preferred. This may or may not be honored, but a best attempt will be made. Known strings are as follows:

• “gl”, “opengl”: try use opengl.
• “3d”: try and use a 3d acceleration unit.
• “hw”, “hardware”, “accel”: try any acceleration unit (best possible)

Note

This takes precedence over engine preferences set with preferred_engine

Type:string

New in version 1.10.

accel_preference_override

The acceleration override preference flag

This is a flag that has the global system acceleration preference configuration forcibly override whatever acceleration preference the application may want.

Type:bool

New in version 1.18.

all_flush()

Flush all config settings then apply those settings to all applications using elementary on the current display.

atspi_mode

ATSPI mode

Type:bool

Note

Enables Linux Accessibility support for Elementary widgets.

New in version 1.10.

audio_mute_get(channel)

Get the mute state of an audio channel for effects

Parameters:channel – The channel to get the mute state of Returns:The mute state

New in version 1.10.

audio_mute_set(channel, mute)

Set the mute state of the specified channel

Parameters:

• channel – The channel to set the mute state of
• mute – The mute state to set

New in version 1.10.

cache_edje_collection_cache_size

The globally configured edje collections cache size, in number of collections.

Type:int

cache_edje_file_cache_size

The globally configured edje file cache size, in number of files.

Type:int

cache_flush_enabled

The configured cache flush enabled state

This property reflects the globally configured cache flush state - if it is enabled or not. When cache flushing is enabled, elementary will regularly (see cache_flush_interval) flush caches and dump data out of memory and allow usage to re-seed caches and data in memory where it can do so. An idle application will thus minimize its memory usage as data will be freed from memory and not be re-loaded as it is idle and not rendering or doing anything graphically right now.

See also

efl.elementary.general.cache_all_flush()

Type:bool

cache_flush_interval

The globally configured cache flush interval time, in ticks

See also

efl.elementary.general.cache_all_flush()

Note

The size must be greater than 0. if not, the cache flush will be ignored.

Type:int

cache_font_cache_size

The globally configured font cache size, in bytes.

Type:int

cache_image_cache_size

The globally configured image cache size, in bytes

Type:int

clouseau_enabled

Clouseau state. True if clouseau was tried to be run.

Returns:True if clouseau was tried to run, False otherwise

New in version 1.8.

color_classes_list

Get Elementary’s list of supported color classes.

Type:list of tuples (color_class_name, color_class_description)

New in version 1.10.

color_overlay_apply()

Apply the changes made with color_overlay_set() and color_overlay_unset() on the current Elementary window.

New in version 1.10.

color_overlay_list

Get Elementary’s list of color overlays

Return the overlays setted using color_overlay_set()

Type:list of tuples (color_class, (r, g, b, a), (r2, g2, b2, a2), (r3, g3, b3, a3))

New in version 1.10.

color_overlay_set(cc, r, g, b, a, r2, g2, b2, a2, r3, g3, b3, a3)

Set a color overlay for a given Elementary color class.

The first color is the object, the second is the text outline, and the third is the text shadow. (Note that the second two only apply to text parts).

Setting color emits a signal “color_class,set” with source being the given color class in all edje objects.

Parameters:

• cc (string) – The color class name
• r (int) – Object Red value
• g (int) – Object Green value
• b (int) – Object Blue value
• a (int) – Object Alpha value
• r2 (int) – Outline Red value
• g2 (int) – Outline Green value
• b2 (int) – Outline Blue value
• a2 (int) – Outline Alpha value
• r3 (int) – Shadow Red value
• g3 (int) – Shadow Green value
• b3 (int) – Shadow Blue value
• a3 (int) – Shadow Alpha value

New in version 1.10.

color_overlay_unset(cc)

Unset a color overlay for a given Elementary color class.

This will bring back color elements belonging to color_class back to their default color settings.

Parameters:cc – The color class name

New in version 1.10.

context_menu_disabled

Enable or disable context menu in entries.

Type:bool

New in version 1.17.

cursor_engine_only

The globally configured exclusive usage of engine cursors.

If True only engine cursors will be enabled, if False will look for them on theme before.

Type:bool

engine

Elementary’s rendering engine in use.

This gets the global rendering engine that is applied to all Elementary applications.

Note that it will take effect only to Elementary windows created after this is set.

Type:string

Deprecated since version 1.13: Use accel_preference instead.

finger_size

The configured “finger size”

This gets the globally configured finger size, in pixels

Type:int

first_item_focus_on_first_focusin

The first item focus on first focusin feature.

If this is enabled, then on the first focus of the widget the first item in lists will be automatically selected.

Type:bool

New in version 1.18.

focus_autoscroll_mode

Focus Autoscroll Mode

When a region or an item is focused and it resides inside any scroller, elementary will automatically scroll the focused area to the visible viewport.

Type:Focus autoscroll mode

New in version 1.10.

focus_highlight_animate

Whether the focus highlight, if enabled, will animate its switch from one object to the next

Note that it will take effect only to Elementary windows created after this is set.

See also

Window

Type:bool

focus_highlight_clip_disabled

Whether the focus highlight clip feature is disabled.

If disabled return True, else return False. If focus highlight clip feature is not disabled the focus highlight can be clipped.

Type:bool

New in version 1.10.

focus_highlight_enabled

Whether the highlight on focused objects is enabled or not

Note that it will take effect only to Elementary windows created after this is set.

Type:bool

focus_move_policy

The focus movement policy.

How the focus is moved to another object. It can be ELM_FOCUS_MOVE_POLICY_CLICK or ELM_FOCUS_MOVE_POLICY_IN. The first means elementary focus is moved on elementary object click. The second means elementary focus is moved on elementary object mouse in.

Type:Focus move policy

New in version 1.10.

font_hint_type

Apply the specified font hinting type.

Type:Evas_Font_Hinting_Flags (writeonly)

New in version 1.18.

font_overlay_apply()

Apply the changes made with font_overlay_set() and font_overlay_unset() on the current Elementary window.

This applies all font overlays set to all objects in the UI.

font_overlay_list

Get Elementary’s list of font overlays, set with font_overlay_set().

For each text class, one can set a font overlay for it, overriding the default font properties for that class coming from the theme in use. There is no need to free this list.

Type:list of tuples (text_class, font, size)

font_overlay_set(text_class, font, size)

Set a font overlay for a given Elementary text class.

font has to be in the format returned by efl.elementary.general.font_fontconfig_name_get().

See also

font_overlay_list font_overlay_unset() efl.edje.Edje.text_class_set()

Parameters:

• text_class (string) – Text class name
• font (string) – Font name and style string
• size (int) – Font size

font_overlay_unset(text_class)

Unset a font overlay for a given Elementary text class.

This will bring back text elements belonging to text class text_class back to their default font settings.

Parameters:text_class (string) – Text class name

glayer_double_tap_timeout

Get the duration for occurring double tap event of gesture layer.

Returns:Timeout for double tap event of gesture layer.

New in version 1.8.

glayer_long_tap_start_timeout

The duration for occurring long tap event of gesture layer.

Type:float

New in version 1.8.

icon_theme

The FDO icon theme for all elementary apps.

This property control the icon theme for all efl.elementary.Icon.standard calls. Valid parameters are the name of an installed freedesktop.org icon theme or ELM_CONFIG_ICON_THEME_ELEMENTARY for the built in theme.

Type:string

New in version 1.18.

indicator_service_get(rotation)

Get the indicator service name according to the rotation degree.

Parameters:rotation – The rotation which is related with the indicator service name, in degrees (0-360), Returns:The indicator service name according to the rotation degree.

New in version 1.8.

item_select_on_focus_disabled

Elementary item focus on selection.

Type:bool

New in version 1.10.

longpress_timeout

The duration for occurring long press event.

Type:float

magnifier_enabled

The magnifier enabled state for entries

Type:bool

New in version 1.10.

magnifier_scale

The amount of scaling the magnifer does

Type:float

New in version 1.10.

mirrored

Get the system mirrored mode. This determines the default mirrored mode of widgets.

type: bool

password_show_last

The “show last” setting of password mode.

Type:bool

password_show_last_timeout

The timeout value for which the last input entered in password mode will be visible.

Type:float

popup_scrollable

The popup scrollable flag

If scrollable is True, popup’s contents is wrapped in a scroller container in order to popup shouldn’t be larger than its parent.

Type:bool

New in version 1.18.

preferred_engine

Get Elementary’s preferred engine to use.

This gets the global rendering engine that is applied to all Elementary applications and is PREFERRED by the application.

Note that it will take effect only to Elementary windows created after this is called. This overrides the engine set by configuration at application startup. Note that it is a hint and may not be honored.

Type:string

Deprecated since version 1.13: Use accel_preference instead.

profile

Elementary’s profile in use.

The global profile that is applied to all Elementary applications.

Type:string

profile_derived_add(profile, derive_options)

Add a new profile of the given name to be derived from the current profile

This creates a new profile of name profile that will be derived from the currently used profile using the modification commands encoded in the derive_options string.

At this point it is not expected that anyone would generally use this API except if you are a destktop environment and so the user base of this API will be enlightenment itself.

Parameters:

• profile (str) – The new profile’s name
• derive_options (str) – Derive options detailing how to modify

New in version 1.17.

profile_derived_del(profile)

Deletes a profile that is derived from the current one

This deletes a derived profile added by profile_derived_add(). This will delete the profile of the given name profile that is derived from the current profile.

At this point it is not expected that anyone would generally use this API except if you are a destktop environment and so the user base of this API will be enlightenment itself.

Parameters:profile (str) – The profile’s name that is to be deleted

New in version 1.17.

profile_dir_get(profile, is_user)

Get an Elementary’s profile directory path in the filesystem. One may want to fetch a system profile’s dir or a user one (fetched inside $HOME).

Parameters:

• profile (unicode) – The profile’s name
• is_user (bool) – Whether to lookup for a user profile (True) or a system one (False)

Returns:

The profile’s directory path.

Return type:

string

profile_exists(profile)

Check if a profile of the given name exists.

Parameters:profile (str) – Name of the pofile to search Returns:True if the profile exists, or False if not Return type:bool

New in version 1.17.

profile_list

Get Elementary’s list of available profiles.

Type:tuple of strings (readonly)

profile_list_full

Get Elementary’s list of available profiles, including hidden ones.

This gets a full list of profiles even with hidden names that should not be user-visible.

Type:tuple of strings (readonly)

New in version 1.17.

profile_save(profile)

Take the current config and write it out to the named profile.

This will take the current in-memory config and write it out to the named profile specified by profile. This will not change profile for the application or make other processes switch profile.

Parameters:profile (str) – The profile’s name

New in version 1.17.

reload()

Reload Elementary’s configuration, bounded to current selected profile.

Useful when you want to force reloading of configuration values for a profile. If one removes user custom configuration directories, for example, it will force a reload with system values instead.

Returns:True, when successful. False, otherwise. Return type:bool

save()

Save back Elementary’s configuration, so that it will persist on future sessions.

This function will take effect – thus, do I/O – immediately. Use it when you want to save all configuration changes at once. The current configuration set will get saved onto the current profile configuration file.

Returns:True, when successful. False, otherwise. Return type:bool

scale

The global scaling factor

This gets the globally configured scaling factor that is applied to all objects.

Type:float

scroll_accel_factor

Scroll acceleration factor.

Using a mouse wheel or touchpad to scroll will result in events being processed. If events occur quickly, the scroll amount will be multiplied by this value to accelerate the scrolling. Accepted value range from 0 to 10, where 0 means no accelleration and 10 means maximum acceleration.

Type:float

New in version 1.18.

scroll_animation_disabled

Disable scroller animations at all.

This option disables timed animations during scrolling and forces scroll actions to be performed immediately.

Type:bool

New in version 1.18.

scroll_bounce_enabled

Whether scrollers should bounce when they reach their viewport’s edge during a scroll.

Type:bool

scroll_bounce_friction

The amount of inertia a scroller will impose at bounce animations.

Type:float

scroll_bring_in_scroll_friction

The amount of inertia a scroller will impose at region bring animations.

Type:float

scroll_page_scroll_friction

The amount of inertia a paged scroller will impose at page fitting animations.

Type:float

scroll_thumbscroll_acceleration_threshold

The minimum speed of mouse cursor movement which will accelerate scrolling velocity after a mouse up event (pixels/second).

Type:float

New in version 1.8.

scroll_thumbscroll_acceleration_time_limit

The time limit for accelerating velocity.

Type:float

New in version 1.8.

scroll_thumbscroll_acceleration_weight

The weight for the acceleration.

Type:float

New in version 1.8.

scroll_thumbscroll_border_friction

The amount of lag between your actual mouse cursor dragging movement and a scroller’s view movement itself, while pushing it into bounce state manually.

Note

parameter value will get bound to 0.0 - 1.0 interval, always

Type:float

New in version 1.8.

scroll_thumbscroll_enabled

Whether scrollers should be draggable from any point in their views.

Note

This is the default behavior for touch screens, in general.

Note

All other functions namespaced with “thumbscroll” will only have effect if this mode is enabled.

Type:bool

scroll_thumbscroll_flick_distance_tolerance

The number of pixels the maximum distance which can be flicked. If it is flicked more than this, the flick distance is same with maximum distance.

Type:int

New in version 1.8.

scroll_thumbscroll_friction

The amount of inertia a scroller will impose at self scrolling animations.

Type:float

scroll_thumbscroll_friction_standard

The standard velocity of the scroller. The scroll animation time is same with thumbscroll friction, if the velocity is same with standard velocity.

Type:float

scroll_thumbscroll_hold_threshold

The number of pixels the range which can be scrolled, while the scroller is held.

Type:int

New in version 1.8.

scroll_thumbscroll_min_friction

The min amount of inertia a scroller will impose at self scrolling animations.

Type:float

New in version 1.8.

scroll_thumbscroll_momentum_threshold

The minimum speed of mouse cursor movement which will trigger list self scrolling animation after a mouse up event (pixels/second).

Type:float

scroll_thumbscroll_sensitivity_friction

The sensitivity amount which is be multiplied by the length of mouse dragging.

0.1 for minimum sensitivity, 1.0 for maximum sensitivity. 0.25 is proper.

Type:float

scroll_thumbscroll_smooth_amount

The amount of smoothing to apply to scrolling.

Scrolling with your finger can be smoothed out and the amount to smooth is determined by this parameter. 0.0 means to not smooth at all and 1.0 is to smoth as much as possible.

Type:float

New in version 1.16.

scroll_thumbscroll_smooth_start

The smooth start mode for scrolling with your finger.

Type:bool

New in version 1.16.

scroll_thumbscroll_smooth_time_window

The time window to look back at for events for smoothing.

Scrolling with your finger can be smoothed out and the window of time to look at is determined by this config. The value is in seconds and is from 0.0 to 1.0

Type:float

New in version 1.16.

scroll_thumbscroll_threshold

The number of pixels one should travel while dragging a scroller’s view to actually trigger scrolling.

One would use higher values for touch screens, in general, because of their inherent imprecision.

Type:int

scroll_zoom_friction

The amount of inertia scrollers will impose at animations triggered by Elementary widgets’ zooming API.

Type:float

selection_unfocused_clear

Whether selection should be cleared when entry widget is unfocused.

Type:bool

New in version 1.8.

slider_indicator_visible_mode

Slider’s indicator visiblity mode.

Type:Elm_Slider_Indicator_Visible_Mode

New in version 1.13.

softcursor_mode

The mode used for software provided mouse cursors inline in the window canvas.

A software rendered cursor can be provided for rendering inline inside the canvas windows in the event the native display system does not provide one or the native oneis not wanted.

Type:Elm_Softcursor_Mode

New in version 1.8.

text_classes_list

Get Elementary’s list of supported text classes.

Type:list of tuples (name, desc)

tooltip_delay

The duration after which tooltip will be shown.

Type:float

transition_duration_factor

The transitions duration factor.

This set the edje transition duration factor, it will affect the duration of edje animations.

Type:float

New in version 1.15.

vsync

The configured vsync flag

This is the globally configured vsync flag that asks some backend engines to use vsync display if possible.

Type:bool

New in version 1.18.

web_backend

The backend engine used by Elm_Web widget

This is the name of the external module used by elm_web to render web page.

Type:string

New in version 1.18.

window_auto_focus_animate

The auto focus animate flag

If auto focus is enabled then this will determine if the focus display will be animated or not.

Type:bool

New in version 1.14.

window_auto_focus_enable

The auto focus enable flag

This determines if elementary will show a focus box indicating the focused widget automatically if keyboard controls like “Tab” are used to switch focus between widgets. Mouse or touch control will hide this auto shown focus, unless focus display has been explicitly forced on for the window.

Type:bool

New in version 1.14.