elm_theme_all_set -> deprecate.
[framework/uifw/elementary.git] / src / lib / elm_theme.h
1 /**
2  * @defgroup Theme Theme
3  *
4  * Elementary uses Edje to theme its widgets, naturally. But for the most
5  * part this is hidden behind a simpler interface that lets the user set
6  * extensions and choose the style of widgets in a much easier way.
7  *
8  * Instead of thinking in terms of paths to Edje files and their groups
9  * each time you want to change the appearance of a widget, Elementary
10  * works so you can add any theme file with extensions or replace the
11  * main theme at one point in the application, and then just set the style
12  * of widgets with elm_object_style_set() and related functions. Elementary
13  * will then look in its list of themes for a matching group and apply it,
14  * and when the theme changes midway through the application, all widgets
15  * will be updated accordingly.
16  *
17  * There are three concepts you need to know to understand how Elementary
18  * theming works: default theme, extensions and overlays.
19  *
20  * Default theme, obviously enough, is the one that provides the default
21  * look of all widgets. End users can change the theme used by Elementary
22  * by setting the @c ELM_THEME environment variable before running an
23  * application, or globally for all programs using the @c elementary_config
24  * utility. Applications can change the default theme using elm_theme_set(),
25  * but this can go against the user wishes, so it's not an advised practice.
26  *
27  * Ideally, applications should find everything they need in the already
28  * provided theme, but there may be occasions when that's not enough and
29  * custom styles are required to correctly express the idea. For this
30  * cases, Elementary has extensions.
31  *
32  * Extensions allow the application developer to write styles of its own
33  * to apply to some widgets. This requires knowledge of how each widget
34  * is themed, as extensions will always replace the entire group used by
35  * the widget, so important signals and parts need to be there for the
36  * object to behave properly (see documentation of Edje for details).
37  * Once the theme for the extension is done, the application needs to add
38  * it to the list of themes Elementary will look into, using
39  * elm_theme_extension_add(), and set the style of the desired widgets as
40  * he would normally with elm_object_style_set().
41  *
42  * Overlays, on the other hand, can replace the look of all widgets by
43  * overriding the default style. Like extensions, it's up to the application
44  * developer to write the theme for the widgets it wants, the difference
45  * being that when looking for the theme, Elementary will check first the
46  * list of overlays, then the set theme and lastly the list of extensions,
47  * so with overlays it's possible to replace the default view and every
48  * widget will be affected. This is very much alike to setting the whole
49  * theme for the application and will probably clash with the end user
50  * options, not to mention the risk of ending up with not matching styles
51  * across the program. Unless there's a very special reason to use them,
52  * overlays should be avoided for the reasons exposed before.
53  *
54  * All these theme lists are handled by ::Elm_Theme instances. Elementary
55  * keeps one default internally and every function that receives one of
56  * these can be called with NULL to refer to this default (except for
57  * elm_theme_free()). It's possible to create a new instance of a
58  * ::Elm_Theme to set other theme for a specific widget (and all of its
59  * children), but this is as discouraged, if not even more so, than using
60  * overlays. Don't use this unless you really know what you are doing.
61  *
62  * But to be less negative about things, you can look at the following
63  * examples:
64  * @li @ref theme_example_01 "Using extensions"
65  * @li @ref theme_example_02 "Using overlays"
66  *
67  * @{
68  */
69 /**
70  * @typedef Elm_Theme
71  *
72  * Opaque handler for the list of themes Elementary looks for when
73  * rendering widgets.
74  *
75  * Stay out of this unless you really know what you are doing. For most
76  * cases, sticking to the default is all a developer needs.
77  */
78 typedef struct _Elm_Theme Elm_Theme;
79
80 /**
81  * Create a new specific theme
82  *
83  * This creates an empty specific theme that only uses the default theme. A
84  * specific theme has its own private set of extensions and overlays too
85  * (which are empty by default). Specific themes do not fall back to themes
86  * of parent objects. They are not intended for this use. Use styles, overlays
87  * and extensions when needed, but avoid specific themes unless there is no
88  * other way (example: you want to have a preview of a new theme you are
89  * selecting in a "theme selector" window. The preview is inside a scroller
90  * and should display what the theme you selected will look like, but not
91  * actually apply it yet. The child of the scroller will have a specific
92  * theme set to show this preview before the user decides to apply it to all
93  * applications).
94  */
95 EAPI Elm_Theme       *elm_theme_new(void);
96
97 /**
98  * Free a specific theme
99  *
100  * @param th The theme to free
101  *
102  * This frees a theme created with elm_theme_new().
103  */
104 EAPI void             elm_theme_free(Elm_Theme *th);
105
106 /**
107  * Copy the theme from the source to the destination theme
108  *
109  * @param th The source theme to copy from
110  * @param thdst The destination theme to copy data to
111  *
112  * This makes a one-time static copy of all the theme config, extensions
113  * and overlays from @p th to @p thdst. If @p th references a theme, then
114  * @p thdst is also set to reference it, with all the theme settings,
115  * overlays and extensions that @p th had.
116  */
117 EAPI void             elm_theme_copy(Elm_Theme *th, Elm_Theme *thdst);
118
119 /**
120  * Tell the source theme to reference the ref theme
121  *
122  * @param th The theme that will do the referencing
123  * @param thref The theme that is the reference source
124  *
125  * This clears @p th to be empty and then sets it to refer to @p thref
126  * so @p th acts as an override to @p thref, but where its overrides
127  * don't apply, it will fall through to @p thref for configuration.
128  */
129 EAPI void             elm_theme_ref_set(Elm_Theme *th, Elm_Theme *thref);
130
131 /**
132  * Return the theme referred to
133  *
134  * @param th The theme to get the reference from
135  * @return The referenced theme handle
136  *
137  * This gets the theme set as the reference theme by elm_theme_ref_set().
138  * If no theme is set as a reference, NULL is returned.
139  */
140 EAPI Elm_Theme       *elm_theme_ref_get(Elm_Theme *th);
141
142 /**
143  * Return the default theme
144  *
145  * @return The default theme handle
146  *
147  * This returns the internal default theme setup handle that all widgets
148  * use implicitly unless a specific theme is set. This is also often use
149  * as a shorthand of NULL.
150  */
151 EAPI Elm_Theme       *elm_theme_default_get(void);
152
153 /**
154  * Prepends a theme overlay to the list of overlays
155  *
156  * @param th The theme to add to, or if NULL, the default theme
157  * @param item The Edje file path to be used
158  *
159  * Use this if your application needs to provide some custom overlay theme
160  * (An Edje file that replaces some default styles of widgets) where adding
161  * new styles, or changing system theme configuration is not possible. Do
162  * NOT use this instead of a proper system theme configuration. Use proper
163  * configuration files, profiles, environment variables etc. to set a theme
164  * so that the theme can be altered by simple configuration by a user. Using
165  * this call to achieve that effect is abusing the API and will create lots
166  * of trouble.
167  *
168  * @see elm_theme_extension_add()
169  */
170 EAPI void             elm_theme_overlay_add(Elm_Theme *th, const char *item);
171
172 /**
173  * Delete a theme overlay from the list of overlays
174  *
175  * @param th The theme to delete from, or if NULL, the default theme
176  * @param item The name of the theme overlay
177  *
178  * @see elm_theme_overlay_add()
179  */
180 EAPI void             elm_theme_overlay_del(Elm_Theme *th, const char *item);
181
182 /**
183  * Appends a theme extension to the list of extensions.
184  *
185  * @param th The theme to add to, or if NULL, the default theme
186  * @param item The Edje file path to be used
187  *
188  * This is intended when an application needs more styles of widgets or new
189  * widget themes that the default does not provide (or may not provide). The
190  * application has "extended" usage by coming up with new custom style names
191  * for widgets for specific uses, but as these are not "standard", they are
192  * not guaranteed to be provided by a default theme. This means the
193  * application is required to provide these extra elements itself in specific
194  * Edje files. This call adds one of those Edje files to the theme search
195  * path to be search after the default theme. The use of this call is
196  * encouraged when default styles do not meet the needs of the application.
197  * Use this call instead of elm_theme_overlay_add() for almost all cases.
198  *
199  * @see elm_object_style_set()
200  */
201 EAPI void             elm_theme_extension_add(Elm_Theme *th, const char *item);
202
203 /**
204  * Deletes a theme extension from the list of extensions.
205  *
206  * @param th The theme to delete from, or if NULL, the default theme
207  * @param item The name of the theme extension
208  *
209  * @see elm_theme_extension_add()
210  */
211 EAPI void             elm_theme_extension_del(Elm_Theme *th, const char *item);
212
213 /**
214  * Set the theme search order for the given theme
215  *
216  * @param th The theme to set the search order, or if NULL, the default theme
217  * @param theme Theme search string
218  *
219  * This sets the search string for the theme in path-notation from first
220  * theme to search, to last, delimited by the : character. Example:
221  *
222  * "shiny:/path/to/file.edj:default"
223  *
224  * See the ELM_THEME environment variable for more information.
225  *
226  * @see elm_theme_get()
227  * @see elm_theme_list_get()
228  */
229 EAPI void             elm_theme_set(Elm_Theme *th, const char *theme);
230
231 /**
232  * Return the theme search order
233  *
234  * @param th The theme to get the search order, or if NULL, the default theme
235  * @return The internal search order path
236  *
237  * This function returns a colon separated string of theme elements as
238  * returned by elm_theme_list_get().
239  *
240  * @see elm_theme_set()
241  * @see elm_theme_list_get()
242  */
243 EAPI const char      *elm_theme_get(Elm_Theme *th);
244
245 /**
246  * Return a list of theme elements to be used in a theme.
247  *
248  * @param th Theme to get the list of theme elements from.
249  * @return The internal list of theme elements
250  *
251  * This returns the internal list of theme elements (will only be valid as
252  * long as the theme is not modified by elm_theme_set() or theme is not
253  * freed by elm_theme_free(). This is a list of strings which must not be
254  * altered as they are also internal. If @p th is NULL, then the default
255  * theme element list is returned.
256  *
257  * A theme element can consist of a full or relative path to a .edj file,
258  * or a name, without extension, for a theme to be searched in the known
259  * theme paths for Elementary.
260  *
261  * @see elm_theme_set()
262  * @see elm_theme_get()
263  */
264 EAPI const Eina_List *elm_theme_list_get(const Elm_Theme *th);
265
266 /**
267  * Return the full path for a theme element
268  *
269  * @param f The theme element name
270  * @param in_search_path Pointer to a boolean to indicate if item is in the search path or not
271  * @return The full path to the file found.
272  *
273  * This returns a string you should free with free() on success, NULL on
274  * failure. This will search for the given theme element, and if it is a
275  * full or relative path element or a simple search-able name. The returned
276  * path is the full path to the file, if searched, and the file exists, or it
277  * is simply the full path given in the element or a resolved path if
278  * relative to home. The @p in_search_path boolean pointed to is set to
279  * EINA_TRUE if the file was a search-able file and is in the search path,
280  * and EINA_FALSE otherwise.
281  */
282 EAPI char            *elm_theme_list_item_path_get(const char *f, Eina_Bool *in_search_path);
283
284 /**
285  * Flush the current theme.
286  *
287  * @param th Theme to flush
288  *
289  * This flushes caches that let elementary know where to find theme elements
290  * in the given theme. If @p th is NULL, then the default theme is flushed.
291  * Call this function if source theme data has changed in such a way as to
292  * make any caches Elementary kept invalid.
293  */
294 EAPI void             elm_theme_flush(Elm_Theme *th);
295
296 /**
297  * This flushes all themes (default and specific ones).
298  *
299  * This will flush all themes in the current application context, by calling
300  * elm_theme_flush() on each of them.
301  */
302 EAPI void             elm_theme_full_flush(void);
303
304 /**
305  * Return a list of theme elements in the theme search path
306  *
307  * @return A list of strings that are the theme element names.
308  *
309  * This lists all available theme files in the standard Elementary search path
310  * for theme elements, and returns them in alphabetical order as theme
311  * element names in a list of strings. Free this with
312  * elm_theme_name_available_list_free() when you are done with the list.
313  */
314 EAPI Eina_List       *elm_theme_name_available_list_new(void);
315
316 /**
317  * Free the list returned by elm_theme_name_available_list_new()
318  *
319  * This frees the list of themes returned by
320  * elm_theme_name_available_list_new(). Once freed the list should no longer
321  * be used. a new list mys be created.
322  */
323 EAPI void             elm_theme_name_available_list_free(Eina_List *list);
324
325 /**
326  * Set a specific theme to be used for this object and its children
327  *
328  * @param obj The object to set the theme on
329  * @param th The theme to set
330  *
331  * This sets a specific theme that will be used for the given object and any
332  * child objects it has. If @p th is NULL then the theme to be used is
333  * cleared and the object will inherit its theme from its parent (which
334  * ultimately will use the default theme if no specific themes are set).
335  *
336  * Use special themes with great care as this will annoy users and make
337  * configuration difficult. Avoid any custom themes at all if it can be
338  * helped.
339  */
340 EAPI void             elm_object_theme_set(Evas_Object *obj, Elm_Theme *th);
341
342 /**
343  * Get the specific theme to be used
344  *
345  * @param obj The object to get the specific theme from
346  * @return The specific theme set.
347  *
348  * This will return a specific theme set, or NULL if no specific theme is
349  * set on that object. It will not return inherited themes from parents, only
350  * the specific theme set for that specific object. See elm_object_theme_set()
351  * for more information.
352  */
353 EAPI Elm_Theme       *elm_object_theme_get(const Evas_Object *obj);
354
355 /**
356  * Get a data item from a theme
357  *
358  * @param th The theme, or NULL for default theme
359  * @param key The data key to search with
360  * @return The data value, or NULL on failure
361  *
362  * This function is used to return data items from edc in @p th, an overlay, or an extension.
363  * It works the same way as edje_file_data_get() except that the return is stringshared.
364  */
365 EAPI const char      *elm_theme_data_get(Elm_Theme *th, const char *key);
366
367 /**
368  * @}
369  */