This group provides functions to handle look and feel of Elementary Widgets.

Elementary uses Edje to theme its widgets, naturally. But for most of the 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 elm_object_style_set() and related functions. Elementary then looks in its list of themes for a matching group and applies it, and when the theme changes midway through the application, all widgets are updated accordingly.

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

Default theme, obviously, is the one that provides the default look for 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 elm_theme_set(), but this can go against the user's 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 such 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 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 that Elementary will look into, using elm_theme_extension_add(), and set the style of the desired widgets as he would normally do using elm_object_style_set().

Overlays, on the other hand, can replace the look of all the 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 checks 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 is affected. This is very much similar to setting the whole theme for the application and probably clashing with the end user options, not to mention the risk of ending up with non-matching styles across the program. Unless there's a very special reason to use them, overlays should be avoided for the reasons mentioned previously.

All these theme lists are handled by Elm_Theme instances. Elementary keeps one default theme internally and every function that receives one of these can be called with NULL to refer to this default theme(except for elm_theme_free()). It's possible to create a new instance of a Elm_Theme to set other themes for a specific widget (and all of its children), but this is as bad as, if not more than, using overlays. Don't use this unless you really know what you are doing.

Functions
Elm_Theme *	elm_theme_new (void)
	Creates a new specific theme.
void	elm_theme_free (Elm_Theme *th)
	Frees a specific theme.
void	elm_theme_copy (Elm_Theme th, Elm_Theme thdst)
	Copies the theme from the source to the destination theme.
void	elm_theme_ref_set (Elm_Theme th, Elm_Theme thref)
	Sets the source theme to reference the ref theme.
Elm_Theme *	elm_theme_ref_get (Elm_Theme *th)
	Gets the theme referred to.
Elm_Theme *	elm_theme_default_get (void)
	Gets the default theme.
void	elm_theme_overlay_add (Elm_Theme th, const char item)
	Prepends a theme overlay to the list of overlays.
void	elm_theme_overlay_del (Elm_Theme th, const char item)
	Deletes a theme overlay from the list of overlays.
const Eina_List *	elm_theme_overlay_list_get (const Elm_Theme *th)
	Gets the list of registered overlays for the given theme.
void	elm_theme_extension_add (Elm_Theme th, const char item)
	Appends a theme extension to the list of extensions.
void	elm_theme_extension_del (Elm_Theme th, const char item)
	Deletes a theme extension from the list of extensions.
const Eina_List *	elm_theme_extension_list_get (const Elm_Theme *th)
	Gets the list of registered extensions for the given theme.
void	elm_theme_set (Elm_Theme th, const char theme)
	Sets the theme search order for the given theme.
const char *	elm_theme_get (Elm_Theme *th)
	Gets the theme search order.
const Eina_List *	elm_theme_list_get (const Elm_Theme *th)
	Gets a list of theme elements to be used in a theme.
char *	elm_theme_list_item_path_get (const char f, Eina_Bool in_search_path)
	Gets the full path for a theme element.
void	elm_theme_flush (Elm_Theme *th)
	Flushes the current theme.
void	elm_theme_full_flush (void)
	Flushes all themes (default and specific ones).
Eina_List *	elm_theme_name_available_list_new (void)
	Returns a list of theme elements in the theme search path.
void	elm_theme_name_available_list_free (Eina_List *list)
	Frees the list returned by elm_theme_name_available_list_new().
void	elm_object_theme_set (Evas_Object obj, Elm_Theme th)
	Sets a specific theme to be used for this object and its children.
Elm_Theme *	elm_object_theme_get (const Evas_Object *obj)
	Gets the specific theme to be used.
const char *	elm_theme_data_get (Elm_Theme th, const char key)
	Gets a data item from a theme.
Typedefs
typedef struct _Elm_Theme	Elm_Theme
	The structure type which is an opaque handler for the list of themes that Elementary looks for when rendering widgets.

Typedef Documentation

Elm_Theme

The structure type which is an opaque handler for the list of themes that Elementary looks for when rendering widgets.

Since :: 2.3.1

Remarks:: Avoid this unless you really know what you are doing. For most cases, sticking to the default is all a developer needs.

Function Documentation

Elm_Theme* elm_object_theme_get ( const Evas_Object * obj )

Gets the specific theme to be used.

This returns a specific theme set, otherwise NULL if no specific theme is set on that object. It returns inherited themes from parents, only the specific theme set for that specific object. See elm_object_theme_set() for more information.

Since :: 2.3.1

Parameters:

[in] obj The object to get the specific theme from

Returns:: The specific theme set

void elm_object_theme_set	(	Evas_Object *	obj,
		Elm_Theme *	th
	)

Sets a specific theme to be used for this object and its children.

This sets a specific theme that is used for the given object and any child objects it has. If th is NULL then the theme to be used is cleared and the object inherits its theme from its parent (which ultimately uses the default theme if no specific themes are set).

Since :: 2.3.1

Remarks:: Use special themes with great care as this annoys users and makes configuration difficult. Avoid any custom themes if at all possible.

Parameters:

[in]	obj	The object to set the theme on
[in]	th	The theme to set

void elm_theme_copy	(	Elm_Theme *	th,
		Elm_Theme *	thdst
	)

Copies the theme from the source to the destination theme.

Since :: 2.3.1

Remarks:: This makes a one-time static copy of all the theme config, extensions and overlays from th to thdst. If th references a theme, then thdst is also set to reference it, with all the theme settings, overlays, and extensions that th has.

Parameters:

[in]	th	The source theme to copy from
[out]	thdst	The destination theme to copy data to

const char* elm_theme_data_get	(	Elm_Theme *	th,
		const char *	key
	)

Gets a data item from a theme.

This function is used to return data items from edc in th, an overlay, or an extension. It works in the same way as edje_file_data_get() except that the returned value is stringshared.

Since :: 2.3.1

Parameters:

[in]	th	The theme, otherwise `NULL` for the default theme
[in]	key	The data key to search with

Returns:: The data value, otherwise NULL on failure

Elm_Theme* elm_theme_default_get ( void )

Gets the default theme.

Since :: 2.3.1

Remarks:: This returns the internal default theme setup handle that all widgets use implicitly unless a specific theme is set. This is also often used as a shorthand for NULL.

Returns:: The default theme handle

void elm_theme_extension_add	(	Elm_Theme *	th,
		const char *	item
	)

Appends a theme extension to the list of extensions.

Since :: 2.3.1

Remarks:: 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.

Parameters:

[in]	th	The theme to add, otherwise `NULL` for the default theme
[in]	item	The Edje file path to be used

See also:: elm_object_style_set()

void elm_theme_extension_del	(	Elm_Theme *	th,
		const char *	item
	)

Deletes a theme extension from the list of extensions.

Since :: 2.3.1

Parameters:

[in]	th	The theme to delete, otherwise `NULL` for the default theme
[in]	item	The name of the theme extension

See also:: elm_theme_extension_add()

const Eina_List* elm_theme_extension_list_get ( const Elm_Theme * th )

Gets the list of registered extensions for the given theme.

Since :: 2.3.1

Parameters:

[in] th The theme from which to get the extensions

Returns:: The list of theme extensions, do not free it

See also:: elm_theme_extension_add()

void elm_theme_flush ( Elm_Theme * th )

Flushes the current theme.

This flushes caches that let elementary know where to find theme elements in the given theme. If th is NULL, then the default theme is flushed. Call this function if the source theme data has changed in such a way so as to make any caches Elementary invalid.

Since :: 2.3.1

Parameters:

[in] th The theme to flush

void elm_theme_free ( Elm_Theme * th )

Frees a specific theme.

This frees a theme created with elm_theme_new().

Since :: 2.3.1

Parameters:

[in] th The theme to free

void elm_theme_full_flush ( void )

Flushes all themes (default and specific ones).

This flushes all the themes in the current application context, by calling elm_theme_flush() on each of them.

Since :: 2.3.1

const char* elm_theme_get ( Elm_Theme * th )

Gets the theme search order.

Since :: 2.3.1

Remarks:: This function returns a colon separated string of theme elements as returned by elm_theme_list_get().

Parameters:

[in] th The theme to get the search order for, otherwise NULL for the default theme

Returns:: The internal search order path

See also:: elm_theme_set(); elm_theme_list_get()

const Eina_List* elm_theme_list_get ( const Elm_Theme * th )

Gets 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. If th is NULL, then the default theme element list is returned.

Since :: 2.3.1

Remarks:: 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.

Parameters:

[in] th The theme to get the list of theme elements from

Returns:: The internal list of theme elements

See also:: elm_theme_set(); elm_theme_get()

char* elm_theme_list_item_path_get	(	const char *	f,
		Eina_Bool *	in_search_path
	)

Gets the full path for a theme element.

Since :: 2.3.1

Remarks:: This returns a string you should free with free() on success, NULL on failure. This searches for the given theme element, and if it is a full or relative path element or a simple searchable name. The returned path is the full path to the file, if searched, and the file exists, or it is simply the full path given in the element or a resolved path if relative to home. The in_search_path boolean that it is pointing to is set to EINA_TRUE if the file is a searchable file and is in the search path, otherwise the value is EINA_FALSE.

Parameters:

[in]	f	The theme element name
[out]	in_search_path	The pointer to a boolean that indicate if the item is in the search path

Returns:: The full path to the file found

void elm_theme_name_available_list_free ( Eina_List * list )

Frees the list returned by elm_theme_name_available_list_new().

This frees the list of themes returned by elm_theme_name_available_list_new(). Once freed the list should no longer be used. A new list must be created.

Parameters:

[in] list The list to be freed

Since :: 2.3.1

Eina_List* elm_theme_name_available_list_new ( void )

Returns a list of theme elements in the theme search path.

This lists all the available theme files in the standard Elementary search path for the theme elements, and returns them in an alphabetical order as theme element names in a list of strings. Free this with elm_theme_name_available_list_free() when you are done with the list.

Since :: 2.3.1

Returns:: The list of strings that are the theme element names

Elm_Theme* elm_theme_new ( void )

Creates 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 (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 how the theme you selected will look, but should not actually apply it. The child of the scroller have a specific theme set to show this preview before the user decides to apply it to all applications).

Returns:: A new theme

Since :: 2.3.1

void elm_theme_overlay_add	(	Elm_Theme *	th,
		const char *	item
	)

Prepends a theme overlay to the list of overlays.

Since :: 2.3.1

Remarks:: 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 overusing the API and creates lots of issues.

Parameters:

[in]	th	The theme to add to, otherwise `NULL` for the default theme
[in]	item	The Edje file path to be used

See also:: elm_theme_extension_add()

void elm_theme_overlay_del	(	Elm_Theme *	th,
		const char *	item
	)

Deletes a theme overlay from the list of overlays.

Since :: 2.3.1

Parameters:

[in]	th	The theme to delete, otherwise `NULL` for the default theme
[in]	item	The name of the theme overlay

See also:: elm_theme_overlay_add()

const Eina_List* elm_theme_overlay_list_get ( const Elm_Theme * th )

Gets the list of registered overlays for the given theme.

Since :: 2.3.1

Parameters:

[in] th The theme from which to get the overlays

Returns:: The list of theme overlays, do not free it

See also:: elm_theme_overlay_add()

Elm_Theme* elm_theme_ref_get ( Elm_Theme * th )

Gets the theme referred to.

This gets the theme set as the reference theme by elm_theme_ref_set(). If no theme is set as a reference, NULL is returned.

Since :: 2.3.1

Parameters:

[in] th The theme to get the reference from

Returns:: The referenced theme handle

void elm_theme_ref_set	(	Elm_Theme *	th,
		Elm_Theme *	thref
	)

Sets the source theme to reference the ref theme.

Since :: 2.3.1

Remarks:: This clears th to be empty and then sets it to refer to thref so th acts as an override to thref, but where its overriding doesn't apply, it falls through to thref for configuration.

Parameters:

[in]	th	The theme that does the referencing
[out]	thref	The theme that is the reference source

void elm_theme_set	(	Elm_Theme *	th,
		const char *	theme
	)

Sets the theme search order for the given theme.

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

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

Since :: 2.3.1

Remarks:: See the ELM_THEME environment variable for more information.

Parameters:

[in]	th	The theme to set the search order for, otherwise `NULL` for the default theme
[in]	theme	The theme search string

See also:: elm_theme_get(); elm_theme_list_get()

Functions

Typedefs

Typedef Documentation

Function Documentation