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