Theme

Description

Elementary uses Edje to theme its widgets, naturally. But for the most part this is hidden behind a simpler interface that lets the user set extensions and choose the style of widgets in a much easier way.

Instead of thinking in terms of paths to Edje files and their groups each time you want to change the appearance of a widget, Elementary works so you can add any theme file with extensions or replace the main theme at one point in the application, and then just set the style of widgets with Object.style and related functions. Elementary will then look in its list of themes for a matching group and apply it, and when the theme changes midway through the application, all widgets will be updated accordingly.

There are three concepts you need to know to understand how Elementary theming works: default theme, extensions and overlays.

Default theme, obviously enough, is the one that provides the default look of all widgets. End users can change the theme used by Elementary by setting the ELM_THEME environment variable before running an application, or globally for all programs using the elementary_config utility. Applications can change the default theme using Theme.order, but this can go against the user wishes, so it’s not an advised practice.

Ideally, applications should find everything they need in the already provided theme, but there may be occasions when that’s not enough and custom styles are required to correctly express the idea. For this cases, Elementary has extensions.

Extensions allow the application developer to write styles of its own to apply to some widgets. This requires knowledge of how each widget is themed, as extensions will always replace the entire group used by the widget, so important signals and parts need to be there for the object to behave properly (see documentation of Edje for details). Once the theme for the extension is done, the application needs to add it to the list of themes Elementary will look into, using Theme.extension_add(), and set the style of the desired widgets as he would normally with Object.style.

Overlays, on the other hand, can replace the look of all widgets by overriding the default style. Like extensions, it’s up to the application developer to write the theme for the widgets it wants, the difference being that when looking for the theme, Elementary will check first the list of overlays, then the set theme and lastly the list of extensions, so with overlays it’s possible to replace the default view and every widget will be affected. This is very much alike to setting the whole theme for the application and will probably clash with the end user options, not to mention the risk of ending up with not matching styles across the program. Unless there’s a very special reason to use them, overlays should be avoided for the reasons exposed before.

All these theme lists are handled by Theme instances. Elementary keeps one default internally. It’s possible to create a new instance of a Theme to set other theme for a specific widget (and all of its children), but this is as discouraged, if not even more so, than using overlays. Don’t use this unless you really know what you are doing.

Note

Remember to Theme.free() the instance when you’re done with it!

Inheritance diagram

class efl.elementary.Theme(default=False)

Bases: object

This is the class that actually implements the widget.

copy(dst)

Copy the theme from the source to the destination theme

This makes a one-time static copy of all the theme config, extensions and overlays from this theme to dst.

Parameters

dst (Theme) – The destination theme to copy data to

data_get(key)

Get a data item from a theme

This function is used to return data items from edc in theme, an overlay, or an extension. It works the same way as efl.edje.Edje.data_get().

Parameters

key (string) – The data key to search with

Returns

The data value, or None on failure

Return type

string

classmethod default_get(cls)

Return the default theme

This returns the internal default theme setup handle that all widgets use implicitly unless a specific theme is set.

elements

Return a list of theme elements to be used in a theme.

This returns the internal list of theme elements (will only be valid as long as the theme is not modified by elm_theme_set() or theme is not freed by elm_theme_free(). This is a list of strings which must not be altered as they are also internal.

A theme element can consist of a full or relative path to a .edj file, or a name, without extension, for a theme to be searched in the known theme paths for Elementary.

See also

order

Type

tuple of strings

elements_get()

extension_add(item)

Appends a theme extension to the list of extensions.

This is intended when an application needs more styles of widgets or new widget themes that the default does not provide (or may not provide). The application has “extended” usage by coming up with new custom style names for widgets for specific uses, but as these are not “standard”, they are not guaranteed to be provided by a default theme. This means the application is required to provide these extra elements itself in specific Edje files. This call adds one of those Edje files to the theme search path to be search after the default theme. The use of this call is encouraged when default styles do not meet the needs of the application. Use this call instead of elm_theme_overlay_add() for almost all cases.

See also

Object.style

Parameters

item (string) – The Edje file path to be used

extension_del(item)

Deletes a theme extension from the list of extensions.

See also

extension_add()

Parameters

item (string) – The name of the theme extension

extension_list

Get the list of registered extensions for the given theme

See also

extension_add()

Type

tuple of strings

extension_list_get()

flush()

Flush the current theme.

This flushes caches that let elementary know where to find theme elements in the given theme. Call this function if source theme data has changed in such a way as to make any caches Elementary kept invalid.

free()

Free the theme.

group_base_list_get(base)

Get a list of groups that match the initial base string given.

This function will walk all theme files configured in the theme and find all groups that BEGIN with the string begin and have that string as at LEAST their start.

Parameters

base (string) – The base string group collection to look for

Returns

The list of group names found (sorted)

Return type

list of strings

New in version 1.13.

classmethod new(cls)

Create a new specific theme

This creates an empty specific theme that only uses the default theme. A specific theme has its own private set of extensions and overlays too (which are empty by default). Specific themes do not fall back to themes of parent objects. They are not intended for this use. Use styles, overlays and extensions when needed, but avoid specific themes unless there is no other way (example: you want to have a preview of a new theme you are selecting in a “theme selector” window. The preview is inside a scroller and should display what the theme you selected will look like, but not actually apply it yet. The child of the scroller will have a specific theme set to show this preview before the user decides to apply it to all applications).

order

Set the theme search order for the given theme

This sets the search string for the theme in path-notation from first theme to search, to last, delimited by the : character. Example:

shiny:/path/to/file.edj:default

See the ELM_THEME environment variable for more information.

See also

elements

Type

string

order_get()

order_set(theme)

overlay_add(item)

Prepends a theme overlay to the list of overlays

Use this if your application needs to provide some custom overlay theme (An Edje file that replaces some default styles of widgets) where adding new styles, or changing system theme configuration is not possible. Do NOT use this instead of a proper system theme configuration. Use proper configuration files, profiles, environment variables etc. to set a theme so that the theme can be altered by simple configuration by a user. Using this call to achieve that effect is abusing the API and will create lots of trouble.

See also

extension_add()

Parameters

item (string) – The Edje file path to be used

overlay_del(item)

Delete a theme overlay from the list of overlays

See also

overlay_add()

Parameters

item (string) – The name of the theme overlay

overlay_list

Get the list of registered overlays for the given theme

See also

overlay_add()

Type

tuple of strings

overlay_list_get()

ref_get()

ref_set(thref)

reference

Theme reference

Setting this clears the theme to be empty and then sets it to refer to another theme. This way the theme acts as an override to the reference, but where its overrides don’t apply, it will fall through to reference for configuration.

Getting it returns the theme that is referred to.

Type

Theme