summaryrefslogtreecommitdiff
path: root/src/lib/elementary/elm_theme.h
diff options
context:
space:
mode:
authorCedric BAIL <cedric@osg.samsung.com>2016-03-23 12:56:14 -0700
committerCedric BAIL <cedric@osg.samsung.com>2016-03-23 13:24:41 -0700
commitc2a1c49ab2042f559b28e840e54feb8494888e0e (patch)
treec6eb110b7c479499854eede9d0c3ab0a80c9a11a /src/lib/elementary/elm_theme.h
parent9340855597e7e465435c69b6278650346688da14 (diff)
elementary: move all legacy files to their expected new location.
Diffstat (limited to 'src/lib/elementary/elm_theme.h')
-rw-r--r--src/lib/elementary/elm_theme.h585
1 files changed, 585 insertions, 0 deletions
diff --git a/src/lib/elementary/elm_theme.h b/src/lib/elementary/elm_theme.h
new file mode 100644
index 0000000..cb524b2
--- /dev/null
+++ b/src/lib/elementary/elm_theme.h
@@ -0,0 +1,585 @@
1/**
2 * @defgroup Elm_Theme Theme
3 * @ingroup Elementary
4 *
5 * Elementary uses Edje to theme its widgets, naturally. But for the most
6 * part this is hidden behind a simpler interface that lets the user set
7 * extensions and choose the style of widgets in a much easier way.
8 *
9 * Instead of thinking in terms of paths to Edje files and their groups
10 * each time you want to change the appearance of a widget, Elementary
11 * works so you can add any theme file with extensions or replace the
12 * main theme at one point in the application, and then just set the style
13 * of widgets with elm_object_style_set() and related functions. Elementary
14 * will then look in its list of themes for a matching group and apply it,
15 * and when the theme changes midway through the application, all widgets
16 * will be updated accordingly.
17 *
18 * There are three concepts you need to know to understand how Elementary
19 * theming works: default theme, extensions and overlays.
20 *
21 * Default theme, obviously enough, is the one that provides the default
22 * look of all widgets. End users can change the theme used by Elementary
23 * by setting the @c ELM_THEME environment variable before running an
24 * application, or globally for all programs using the @c elementary_config
25 * utility. Applications can change the default theme using elm_theme_set(),
26 * but this can go against the user wishes, so it's not an advised practice.
27 *
28 * Ideally, applications should find everything they need in the already
29 * provided theme, but there may be occasions when that's not enough and
30 * custom styles are required to correctly express the idea. For this
31 * cases, Elementary has extensions.
32 *
33 * Extensions allow the application developer to write styles of its own
34 * to apply to some widgets. This requires knowledge of how each widget
35 * is themed, as extensions will always replace the entire group used by
36 * the widget, so important signals and parts need to be there for the
37 * object to behave properly (see documentation of Edje for details).
38 * Once the theme for the extension is done, the application needs to add
39 * it to the list of themes Elementary will look into, using
40 * elm_theme_extension_add(), and set the style of the desired widgets as
41 * he would normally with elm_object_style_set().
42 *
43 * Overlays, on the other hand, can replace the look of all widgets by
44 * overriding the default style. Like extensions, it's up to the application
45 * developer to write the theme for the widgets it wants, the difference
46 * being that when looking for the theme, Elementary will check first the
47 * list of overlays, then the set theme and lastly the list of extensions,
48 * so with overlays it's possible to replace the default view and every
49 * widget will be affected. This is very much alike to setting the whole
50 * theme for the application and will probably clash with the end user
51 * options, not to mention the risk of ending up with not matching styles
52 * across the program. Unless there's a very special reason to use them,
53 * overlays should be avoided for the reasons exposed before.
54 *
55 * All these theme lists are handled by ::Elm_Theme instances. Elementary
56 * keeps one default internally and every function that receives one of
57 * these can be called with NULL to refer to this default (except for
58 * elm_theme_free()). It's possible to create a new instance of a
59 * ::Elm_Theme to set other theme for a specific widget (and all of its
60 * children), but this is as discouraged, if not even more so, than using
61 * overlays. Don't use this unless you really know what you are doing.
62 *
63 * But to be less negative about things, you can look at the following
64 * examples:
65 * @li @ref theme_example_01 "Using extensions"
66 * @li @ref theme_example_02 "Using overlays"
67 *
68 * @{
69 */
70/**
71 * @typedef Elm_Theme
72 *
73 * Opaque handler for the list of themes Elementary looks for when
74 * rendering widgets.
75 *
76 * Stay out of this unless you really know what you are doing. For most
77 * cases, sticking to the default is all a developer needs.
78 */
79typedef struct _Elm_Theme Elm_Theme;
80
81/**
82 * Create a new specific theme
83 *
84 * This creates an empty specific theme that only uses the default theme. A
85 * specific theme has its own private set of extensions and overlays too
86 * (which are empty by default). Specific themes do not fall back to themes
87 * of parent objects. They are not intended for this use. Use styles, overlays
88 * and extensions when needed, but avoid specific themes unless there is no
89 * other way (example: you want to have a preview of a new theme you are
90 * selecting in a "theme selector" window. The preview is inside a scroller
91 * and should display what the theme you selected will look like, but not
92 * actually apply it yet. The child of the scroller will have a specific
93 * theme set to show this preview before the user decides to apply it to all
94 * applications).
95 *
96 * @ingroup Elm_Theme
97 */
98EAPI Elm_Theme *elm_theme_new(void);
99
100/**
101 * Free a specific theme
102 *
103 * @param th The theme to free
104 *
105 * This frees a theme created with elm_theme_new().
106 *
107 * @ingroup Elm_Theme
108 */
109EAPI void elm_theme_free(Elm_Theme *th);
110
111/**
112 * Copy the theme from the source to the destination theme
113 *
114 * @param th The source theme to copy from
115 * @param thdst The destination theme to copy data to
116 *
117 * This makes a one-time static copy of all the theme config, extensions
118 * and overlays from @p th to @p thdst. If @p th references a theme, then
119 * @p thdst is also set to reference it, with all the theme settings,
120 * overlays and extensions that @p th had.
121 *
122 * @ingroup Elm_Theme
123 */
124EAPI void elm_theme_copy(Elm_Theme *th, Elm_Theme *thdst);
125
126/**
127 * Tell the source theme to reference the ref theme
128 *
129 * @param th The theme that will do the referencing
130 * @param thref The theme that is the reference source
131 *
132 * This clears @p th to be empty and then sets it to refer to @p thref
133 * so @p th acts as an override to @p thref, but where its overrides
134 * don't apply, it will fall through to @p thref for configuration.
135 *
136 * @ingroup Elm_Theme
137 */
138EAPI void elm_theme_ref_set(Elm_Theme *th, Elm_Theme *thref);
139
140/**
141 * Return the theme referred to
142 *
143 * @param th The theme to get the reference from
144 * @return The referenced theme handle
145 *
146 * This gets the theme set as the reference theme by elm_theme_ref_set().
147 * If no theme is set as a reference, NULL is returned.
148 *
149 * @ingroup Elm_Theme
150 */
151EAPI Elm_Theme *elm_theme_ref_get(const Elm_Theme *th);
152
153/**
154 * Return the default theme
155 *
156 * @return The default theme handle
157 *
158 * This returns the internal default theme setup handle that all widgets
159 * use implicitly unless a specific theme is set. This is also often use
160 * as a shorthand of NULL.
161 *
162 * @ingroup Elm_Theme
163 */
164EAPI Elm_Theme *elm_theme_default_get(void);
165
166/**
167 * Prepends a theme overlay to the list of overlays
168 *
169 * @param th The theme to add to, or if NULL, the default theme
170 * @param item The Edje file path to be used
171 *
172 * Use this if your application needs to provide some custom overlay theme
173 * (An Edje file that replaces some default styles of widgets) where adding
174 * new styles, or changing system theme configuration is not possible. Do
175 * NOT use this instead of a proper system theme configuration. Use proper
176 * configuration files, profiles, environment variables etc. to set a theme
177 * so that the theme can be altered by simple configuration by a user. Using
178 * this call to achieve that effect is abusing the API and will create lots
179 * of trouble.
180 *
181 * @see elm_theme_extension_add()
182 * @see elm_theme_overlay_mmap_add()
183 *
184 * @ingroup Elm_Theme
185 */
186EAPI void elm_theme_overlay_add(Elm_Theme *th, const char *item);
187
188/**
189 * Delete a theme overlay from the list of overlays
190 *
191 * @param th The theme to delete from, or if NULL, the default theme
192 * @param item The name of the theme overlay
193 *
194 * @see elm_theme_overlay_add()
195 *
196 * @ingroup Elm_Theme
197 */
198EAPI void elm_theme_overlay_del(Elm_Theme *th, const char *item);
199
200/**
201 * Prepends a theme overlay to the list of overlays
202 *
203 * @param th The theme to add to, or if NULL, the default theme
204 * @param f The Edje file handle to be used
205 *
206 * Use this if your application needs to provide some custom overlay theme
207 * (An Edje file that replaces some default styles of widgets) where adding
208 * new styles, or changing system theme configuration is not possible. Do
209 * NOT use this instead of a proper system theme configuration. Use proper
210 * configuration files, profiles, environment variables etc. to set a theme
211 * so that the theme can be altered by simple configuration by a user. Using
212 * this call to achieve that effect is abusing the API and will create lots
213 * of trouble.
214 *
215 * @see elm_theme_extension_add()
216 * @see elm_theme_overlay_add()
217 *
218 * @ingroup Elm_Theme
219 */
220EAPI void elm_theme_overlay_mmap_add(Elm_Theme *th, const Eina_File *f);
221
222/**
223 * Delete a theme overlay from the list of overlays
224 *
225 * @param th The theme to delete from, or if NULL, the default theme
226 * @param f The file handle of the theme overlay
227 *
228 * @see elm_theme_overlay_mmap_add()
229 *
230 * @ingroup Elm_Theme
231 */
232EAPI void elm_theme_overlay_mmap_del(Elm_Theme *th, const Eina_File *f);
233
234/**
235 * Get the list of registered overlays for the given theme
236 *
237 * @param th The theme from which to get the overlays
238 * @return List of theme overlays. Do not free it.
239 *
240 * @see elm_theme_overlay_add()
241 *
242 * @ingroup Elm_Theme
243 */
244EAPI const Eina_List *elm_theme_overlay_list_get(const Elm_Theme *th);
245
246/**
247 * Appends a theme extension to the list of extensions.
248 *
249 * @param th The theme to add to, or if NULL, the default theme
250 * @param item The Edje file path to be used
251 *
252 * This is intended when an application needs more styles of widgets or new
253 * widget themes that the default does not provide (or may not provide). The
254 * application has "extended" usage by coming up with new custom style names
255 * for widgets for specific uses, but as these are not "standard", they are
256 * not guaranteed to be provided by a default theme. This means the
257 * application is required to provide these extra elements itself in specific
258 * Edje files. This call adds one of those Edje files to the theme search
259 * path to be search after the default theme. The use of this call is
260 * encouraged when default styles do not meet the needs of the application.
261 * Use this call instead of elm_theme_overlay_add() for almost all cases.
262 *
263 * @see elm_object_style_set()
264 *
265 * @ingroup Elm_Theme
266 */
267EAPI void elm_theme_extension_add(Elm_Theme *th, const char *item);
268
269/**
270 * Deletes a theme extension from the list of extensions.
271 *
272 * @param th The theme to delete from, or if NULL, the default theme
273 * @param item The name of the theme extension
274 *
275 * @see elm_theme_extension_add()
276 *
277 * @ingroup Elm_Theme
278 */
279EAPI void elm_theme_extension_del(Elm_Theme *th, const char *item);
280
281/**
282 * Appends a theme extension to the list of extensions.
283 *
284 * @param th The theme to add to, or if NULL, the default theme
285 * @param f The Edje file handle to be used
286 *
287 * This is intended when an application needs more styles of widgets or new
288 * widget themes that the default does not provide (or may not provide). The
289 * application has "extended" usage by coming up with new custom style names
290 * for widgets for specific uses, but as these are not "standard", they are
291 * not guaranteed to be provided by a default theme. This means the
292 * application is required to provide these extra elements itself in specific
293 * Edje files. This call adds one of those Edje files to the theme search
294 * path to be search after the default theme. The use of this call is
295 * encouraged when default styles do not meet the needs of the application.
296 * Use this call instead of elm_theme_overlay_add() for almost all cases.
297 *
298 * @see elm_object_style_set()
299 *
300 * @ingroup Elm_Theme
301 */
302EAPI void elm_theme_extension_mmap_add(Elm_Theme *th, const Eina_File *f);
303
304/**
305 * Deletes a theme extension from the list of extensions.
306 *
307 * @param th The theme to delete from, or if NULL, the default theme
308 * @param f The file handle of the theme extension
309 *
310 * @see elm_theme_extension_add()
311 *
312 * @ingroup Elm_Theme
313 */
314EAPI void elm_theme_extension_mmap_del(Elm_Theme *th, const Eina_File *f);
315
316/**
317 * Get the list of registered extensions for the given theme
318 *
319 * @param th The theme from which to get the extensions
320 * @return List of theme extensions. Do not free it.
321 *
322 * @see elm_theme_extension_add()
323 *
324 * @ingroup Elm_Theme
325 */
326EAPI const Eina_List *elm_theme_extension_list_get(const Elm_Theme *th);
327
328/**
329 * Set the theme search order for the given theme
330 *
331 * @param th The theme to set the search order, or if NULL, the default theme
332 * @param theme Theme search string
333 *
334 * This sets the search string for the theme in path-notation from first
335 * theme to search, to last, delimited by the : character. Example:
336 *
337 * "shiny:/path/to/file.edj:default"
338 *
339 * See the ELM_THEME environment variable for more information.
340 *
341 * @see elm_theme_get()
342 * @see elm_theme_list_get()
343 *
344 * @ingroup Elm_Theme
345 */
346EAPI void elm_theme_set(Elm_Theme *th, const char *theme);
347
348/**
349 * Return the theme search order
350 *
351 * @param th The theme to get the search order, or if NULL, the default theme
352 * @return The internal search order path
353 *
354 * This function returns a colon separated string of theme elements as
355 * returned by elm_theme_list_get().
356 *
357 * @see elm_theme_set()
358 * @see elm_theme_list_get()
359 *
360 * @ingroup Elm_Theme
361 */
362EAPI const char *elm_theme_get(Elm_Theme *th);
363
364/**
365 * Return a list of theme elements to be used in a theme.
366 *
367 * @param th Theme to get the list of theme elements from.
368 * @return The internal list of theme elements
369 *
370 * This returns the internal list of theme elements (will only be valid as
371 * long as the theme is not modified by elm_theme_set() or theme is not
372 * freed by elm_theme_free(). This is a list of strings which must not be
373 * altered as they are also internal. If @p th is NULL, then the default
374 * theme element list is returned.
375 *
376 * A theme element can consist of a full or relative path to a .edj file,
377 * or a name, without extension, for a theme to be searched in the known
378 * theme paths for Elementary.
379 *
380 * @see elm_theme_set()
381 * @see elm_theme_get()
382 *
383 * @ingroup Elm_Theme
384 */
385EAPI const Eina_List *elm_theme_list_get(const Elm_Theme *th);
386
387/**
388 * Return the full path for a theme element
389 *
390 * @param f The theme element name
391 * @param in_search_path Pointer to a boolean to indicate if item is in the search path or not
392 * @return The full path to the file found.
393 *
394 * This returns a string you should free with free() on success, NULL on
395 * failure. This will search for the given theme element, and if it is a
396 * full or relative path element or a simple search-able name. The returned
397 * path is the full path to the file, if searched, and the file exists, or it
398 * is simply the full path given in the element or a resolved path if
399 * relative to home. The @p in_search_path boolean pointed to is set to
400 * @c EINA_TRUE if the file was a search-able file and is in the search path,
401 * and @c EINA_FALSE otherwise.
402 *
403 * @ingroup Elm_Theme
404 */
405EAPI char *elm_theme_list_item_path_get(const char *f, Eina_Bool *in_search_path);
406
407/**
408 * Flush the current theme.
409 *
410 * @param th Theme to flush
411 *
412 * This flushes caches that let elementary know where to find theme elements
413 * in the given theme. If @p th is NULL, then the default theme is flushed.
414 * Call this function if source theme data has changed in such a way as to
415 * make any caches Elementary kept invalid.
416 *
417 * @ingroup Elm_Theme
418 */
419EAPI void elm_theme_flush(Elm_Theme *th);
420
421/**
422 * This flushes all themes (default and specific ones).
423 *
424 * This will flush all themes in the current application context, by calling
425 * elm_theme_flush() on each of them.
426 *
427 * @ingroup Elm_Theme
428 */
429EAPI void elm_theme_full_flush(void);
430
431/**
432 * Return a list of theme elements in the theme search path
433 *
434 * @return A list of strings that are the theme element names.
435 *
436 * This lists all available theme files in the standard Elementary search path
437 * for theme elements, and returns them in alphabetical order as theme
438 * element names in a list of strings. Free this with
439 * elm_theme_name_available_list_free() when you are done with the list.
440 *
441 * @ingroup Elm_Theme
442 */
443EAPI Eina_List *elm_theme_name_available_list_new(void);
444
445/**
446 * Free the list returned by elm_theme_name_available_list_new()
447 *
448 * This frees the list of themes returned by
449 * elm_theme_name_available_list_new(). Once freed the list should no longer
450 * be used. a new list mys be created.
451 *
452 * @ingroup Elm_Theme
453 */
454EAPI void elm_theme_name_available_list_free(Eina_List *list);
455
456/**
457 * Set a specific theme to be used for this object and its children
458 *
459 * @param obj The object to set the theme on
460 * @param th The theme to set
461 *
462 * This sets a specific theme that will be used for the given object and any
463 * child objects it has. If @p th is NULL then the theme to be used is
464 * cleared and the object will inherit its theme from its parent (which
465 * ultimately will use the default theme if no specific themes are set).
466 *
467 * Use special themes with great care as this will annoy users and make
468 * configuration difficult. Avoid any custom themes at all if it can be
469 * helped.
470 *
471 * @ingroup Elm_Theme
472 */
473EAPI void elm_object_theme_set(Evas_Object *obj, Elm_Theme *th);
474
475/**
476 * Get the specific theme to be used
477 *
478 * @param obj The object to get the specific theme from
479 * @return The specific theme set.
480 *
481 * This will return a specific theme set, or NULL if no specific theme is
482 * set on that object. It will not return inherited themes from parents, only
483 * the specific theme set for that specific object. See elm_object_theme_set()
484 * for more information.
485 *
486 * @ingroup Elm_Theme
487 */
488EAPI Elm_Theme *elm_object_theme_get(const Evas_Object *obj);
489
490/**
491 * Get a data item from a theme
492 *
493 * @param th The theme, or NULL for default theme
494 * @param key The data key to search with
495 * @return The data value, or NULL on failure
496 *
497 * This function is used to return data items from edc in @p th, an overlay, or an extension.
498 * It works the same way as edje_file_data_get() except that the return is stringshared.
499 *
500 * @ingroup Elm_Theme
501 */
502EAPI const char *elm_theme_data_get(Elm_Theme *th, const char *key);
503
504/**
505 * Get the file path for an edje file for the group and theme given
506 *
507 * @param th The theme, or NULL for default theme
508 * @param group The group in the edje file to look for
509 * @return The full path to the file as a string
510 *
511 * This function looks up the given edje @p group in the set of theme edje
512 * files configured for the theme @p th (which if NULL indicates the default
513 * theme). If not found in any, NULL wil be returned. If found, the string
514 * returned is internal and should not be freed, but will only be valid
515 * until the theme is re-configured, or cache flushed, so if the string needs
516 * to be kept, duplicate it and store that. The string will be a stringshare
517 * string that is returned by functions like eina_stringshare_add() so it can
518 * be just references via stringshare functions if desired.
519 *
520 * If group is NULL, then nothing can be looked up, so it is a non-sensical
521 * request.
522 *
523 * @since 1.8
524 * @ingroup Elm_Theme
525 */
526EAPI const char *elm_theme_group_path_find(Elm_Theme *th, const char *group);
527
528/**
529 * Get a list of groups that match the initial base string given within all themes
530 *
531 * @param th The theme, or NULL for default theme
532 * @param base The base string group collection to look for
533 * @return A list of collection names (sorted) or NULL if none found
534 *
535 * This function will walk all theme files configured in the theme @p th (or
536 * NULL if its the default) and find all groups that BEGIN with the string
537 * @p begin and have that string as at LEAST their start, and then add the
538 * fulll group name that matches to the list and return that full group
539 * group string.
540 *
541 * The list returned must be freed by the caller, with each string being a
542 * stringshared string to be freed with eina_stringshare_del(). Not doing so
543 * may result in a leak.
544 *
545 * @since 1.8
546 * @ingroup Elm_Theme
547 */
548 EAPI Eina_List *elm_theme_group_base_list(Elm_Theme *th, const char *base);
549
550/**
551 * Get the file path where elementary system theme files are found
552 *
553 * @return A string that holds the path where system themes are
554 *
555 * This returns the location in the filesystem where the system themes are
556 * to be found that elementary looks for. This is useful for something
557 * that wishes toiterate over the files in this folder and display them, for
558 * example a theme selector.
559 *
560 * @since 1.8
561 * @ingroup Elm_Theme
562 */
563EAPI const char *elm_theme_system_dir_get(void);
564
565/**
566 * Get the file path where elementary user theme files are found
567 *
568 * @return A string that holds the path where user themes are
569 *
570 * This returns the location in the filesystem where the user themes are
571 * to be found that elementary looks for. This is useful for something
572 * that wishes toiterate over the files in this folder and display them, for
573 * example a theme selector.
574 *
575 * User themes are always looked for before system themes. The user theme
576 * directory is normally expected to be writable by the user.
577 *
578 * @since 1.8
579 * @ingroup Elm_Theme
580 */
581EAPI const char *elm_theme_user_dir_get(void);
582
583/**
584 * @}
585 */