2 * @defgroup Config Elementary Config
5 * Elementary configuration is formed by a set options bounded to a
6 * given @ref Profile profile, like @ref Theme theme, @ref Fingers
7 * "finger size", etc. These are functions with which one synchronizes
8 * changes made to those values to the configuration storing files, de
9 * facto. You most probably don't want to use the functions in this
10 * group unless you're writing an elementary configuration manager.
16 * Save back Elementary's configuration, so that it will persist on
19 * @return @c EINA_TRUE, when successful. @c EINA_FALSE, otherwise.
22 * This function will take effect -- thus, do I/O -- immediately. Use
23 * it when you want to save all configuration changes at once. The
24 * current configuration set will get saved onto the current profile
28 EAPI Eina_Bool elm_config_save(void);
31 * Reload Elementary's configuration, bounded to current selected
34 * @return @c EINA_TRUE, when successful. @c EINA_FALSE, otherwise.
37 * Useful when you want to force reloading of configuration values for
38 * a profile. If one removes user custom configuration directories,
39 * for example, it will force a reload with system values instead.
42 EAPI void elm_config_reload(void);
45 * Flush all config settings then apply those settings to all applications
46 * using elementary on the current display.
50 EAPI void elm_config_all_flush(void);
57 * @defgroup Profile Elementary Profile
60 * Profiles are pre-set options that affect the whole look-and-feel of
61 * Elementary-based applications. There are, for example, profiles
62 * aimed at desktop computer applications and others aimed at mobile,
63 * touchscreen-based ones. You most probably don't want to use the
64 * functions in this group unless you're writing an elementary
65 * configuration manager.
71 * Get Elementary's profile in use.
73 * This gets the global profile that is applied to all Elementary
76 * @return The profile's name
79 EAPI const char *elm_config_profile_get(void);
82 * Get an Elementary's profile directory path in the filesystem. One
83 * may want to fetch a system profile's dir or a user one (fetched
86 * @param profile The profile's name
87 * @param is_user Whether to lookup for a user profile (@c EINA_TRUE)
88 * or a system one (@c EINA_FALSE)
89 * @return The profile's directory path.
92 * @note You must free it with elm_config_profile_dir_free().
94 EAPI const char *elm_config_profile_dir_get(const char *profile, Eina_Bool is_user);
97 * Free an Elementary's profile directory path, as returned by
98 * elm_config_profile_dir_get().
100 * @param p_dir The profile's path
104 EAPI void elm_config_profile_dir_free(const char *p_dir);
107 * Get Elementary's list of available profiles.
109 * @return The profiles list. List node data are the profile name
113 * @note One must free this list, after usage, with the function
114 * elm_config_profile_list_free().
116 EAPI Eina_List *elm_config_profile_list_get(void);
119 * Free Elementary's list of available profiles.
121 * @param l The profiles list, as returned by elm_config_profile_list_get().
125 EAPI void elm_config_profile_list_free(Eina_List *l);
128 * Set Elementary's profile.
130 * This sets the global profile that is applied to Elementary
131 * applications. Just the process the call comes from will be
134 * @param profile The profile's name
138 EAPI void elm_config_profile_set(const char *profile);
141 * Check if the given Elementary's profile exists.
143 * @param profile The profile's name
144 * @return EINA_TRUE if the profile exists, EINA_FALSE otherwise.
148 EAPI Eina_Bool elm_config_profile_exists(const char *profile);
155 * @defgroup Scrolling Elementary Scrolling
156 * @ingroup Elementary
158 * These are functions setting how scrollable views in Elementary
159 * widgets should behave on user interaction.
165 * Get whether scrollers should bounce when they reach their
166 * viewport's edge during a scroll.
168 * @return the thumb scroll bouncing state
170 * This is the default behavior for touch screens, in general.
173 EAPI Eina_Bool elm_config_scroll_bounce_enabled_get(void);
176 * Set whether scrollers should bounce when they reach their
177 * viewport's edge during a scroll.
179 * @param enabled the thumb scroll bouncing state
181 * @see elm_config_scroll_bounce_enabled_get()
184 EAPI void elm_config_scroll_bounce_enabled_set(Eina_Bool enabled);
187 * Get the amount of inertia a scroller will impose at bounce
190 * @return the thumb scroll bounce friction
194 EAPI double elm_config_scroll_bounce_friction_get(void);
197 * Set the amount of inertia a scroller will impose at bounce
200 * @param friction the thumb scroll bounce friction
202 * @see elm_config_scroll_bounce_friction_get()
205 EAPI void elm_config_scroll_bounce_friction_set(double friction);
208 * Get the amount of inertia a <b>paged</b> scroller will impose at
209 * page fitting animations.
211 * @return the page scroll friction
215 EAPI double elm_config_scroll_page_scroll_friction_get(void);
218 * Set the amount of inertia a <b>paged</b> scroller will impose at
219 * page fitting animations.
221 * @param friction the page scroll friction
223 * @see elm_config_scroll_page_scroll_friction_get()
226 EAPI void elm_config_scroll_page_scroll_friction_set(double friction);
229 * Get the amount of inertia a scroller will impose at region bring
232 * @return the bring in scroll friction
236 EAPI double elm_config_scroll_bring_in_scroll_friction_get(void);
239 * Set the amount of inertia a scroller will impose at region bring
242 * @param friction the bring in scroll friction
244 * @see elm_config_scroll_bring_in_scroll_friction_get()
247 EAPI void elm_config_scroll_bring_in_scroll_friction_set(double friction);
250 * Get the amount of inertia scrollers will impose at animations
251 * triggered by Elementary widgets' zooming API.
253 * @return the zoom friction
257 EAPI double elm_config_scroll_zoom_friction_get(void);
260 * Set the amount of inertia scrollers will impose at animations
261 * triggered by Elementary widgets' zooming API.
263 * @param friction the zoom friction
265 * @see elm_config_scroll_zoom_friction_get()
268 EAPI void elm_config_scroll_zoom_friction_set(double friction);
271 * Get whether scrollers should be draggable from any point in their
274 * @return the thumb scroll state
276 * @note This is the default behavior for touch screens, in general.
277 * @note All other functions namespaced with "thumbscroll" will only
278 * have effect if this mode is enabled.
282 EAPI Eina_Bool elm_config_scroll_thumbscroll_enabled_get(void);
285 * Set whether scrollers should be draggable from any point in their
288 * @param enabled the thumb scroll state
290 * @see elm_config_scroll_thumbscroll_enabled_get()
293 EAPI void elm_config_scroll_thumbscroll_enabled_set(Eina_Bool enabled);
296 * Get the number of pixels one should travel while dragging a
297 * scroller's view to actually trigger scrolling.
299 * @return the thumb scroll threshold
301 * One would use higher values for touch screens, in general, because
302 * of their inherent imprecision.
305 EAPI unsigned int elm_config_scroll_thumbscroll_threshold_get(void);
308 * Set the number of pixels one should travel while dragging a
309 * scroller's view to actually trigger scrolling.
311 * @param threshold the thumb scroll threshold
313 * @see elm_config_thumbscroll_threshold_get()
316 EAPI void elm_config_scroll_thumbscroll_threshold_set(unsigned int threshold);
319 * Get the number of pixels the range which can be scrolled,
320 * while the scroller is holded.
322 * @return the thumb scroll hold threshold
326 EAPI unsigned int elm_config_scroll_thumbscroll_hold_threshold_get(void);
329 * Set the number of pixels the range which can be scrolled,
330 * while the scroller is holded.
332 * @param threshold the thumb scroll hold threshold
334 * @see elm_config_thumbscroll_hold_threshold_get()
337 EAPI void elm_config_scroll_thumbscroll_hold_threshold_set(unsigned int threshold);
340 * Get the minimum speed of mouse cursor movement which will trigger
341 * list self scrolling animation after a mouse up event
344 * @return the thumb scroll momentum threshold
348 EAPI double elm_config_scroll_thumbscroll_momentum_threshold_get(void);
351 * Set the minimum speed of mouse cursor movement which will trigger
352 * list self scrolling animation after a mouse up event
355 * @param threshold the thumb scroll momentum threshold
357 * @see elm_config_thumbscroll_momentum_threshold_get()
360 EAPI void elm_config_scroll_thumbscroll_momentum_threshold_set(double threshold);
363 * Get the amount of inertia a scroller will impose at self scrolling
366 * @return the thumb scroll friction
370 EAPI double elm_config_scroll_thumbscroll_friction_get(void);
373 * Set the amount of inertia a scroller will impose at self scrolling
376 * @param friction the thumb scroll friction
378 * @see elm_config_thumbscroll_friction_get()
381 EAPI void elm_config_scroll_thumbscroll_friction_set(double friction);
384 * Get the amount of lag between your actual mouse cursor dragging
385 * movement and a scroller's view movement itself, while pushing it
386 * into bounce state manually.
388 * @return the thumb scroll border friction
392 EAPI double elm_config_scroll_thumbscroll_border_friction_get(void);
395 * Set the amount of lag between your actual mouse cursor dragging
396 * movement and a scroller's view movement itself, while pushing it
397 * into bounce state manually.
399 * @param friction the thumb scroll border friction. @c 0.0 for
400 * perfect synchrony between two movements, @c 1.0 for maximum
403 * @see elm_config_thumbscroll_border_friction_get()
404 * @note parameter value will get bound to 0.0 - 1.0 interval, always
408 EAPI void elm_config_scroll_thumbscroll_border_friction_set(double friction);
411 * Get the sensitivity amount which is be multiplied by the length of
414 * @return the thumb scroll sensitivity friction
418 EAPI double elm_config_scroll_thumbscroll_sensitivity_friction_get(void);
421 * Set the sensitivity amount which is be multiplied by the length of
424 * @param friction the thumb scroll sensitivity friction. @c 0.1 for
425 * minimum sensitivity, @c 1.0 for maximum sensitivity. 0.25
428 * @see elm_config_thumbscroll_sensitivity_friction_get()
429 * @note parameter value will get bound to 0.1 - 1.0 interval, always
433 EAPI void elm_config_scroll_thumbscroll_sensitivity_friction_set(double friction);
440 * Get the duration for occurring long press event.
442 * @return Timeout for long press event
445 EAPI double elm_config_longpress_timeout_get(void);
448 * Set the duration for occurring long press event.
450 * @param lonpress_timeout Timeout for long press event
453 EAPI void elm_config_longpress_timeout_set(double longpress_timeout);
455 typedef enum _Elm_Softcursor_Mode
457 ELM_SOFTCURSOR_MODE_AUTO, /**< Auto-detect if a software cursor should be used (default) */
458 ELM_SOFTCURSOR_MODE_ON, /**< Always use a softcursor */
459 ELM_SOFTCURSOR_MODE_OFF /**< Never use a softcursor */
460 } Elm_Softcursor_Mode; /**< @since 1.7 */
463 * Set the mode used for software provided mouse cursors inline in the window
466 * A software rendered cursor can be provided for rendering inline inside the
467 * canvas windows in the event the native display system does not provide one
468 * or the native oneis not wanted.
470 * @param lonpress_timeout Timeout for long press event
471 * @ingroup Softcursor
473 * @see elm_config_softcursor_mode_get()
476 EAPI void elm_config_softcursor_mode_set(Elm_Softcursor_Mode mode);
479 * Get the software cursor mode
481 * @return The mode used for software cursors
482 * @ingroup Softcursor
484 * @see elm_config_softcursor_mode_set()
487 EAPI Elm_Softcursor_Mode elm_config_softcursor_mode_get(void);
491 * Get the duration after which tooltip will be shown.
493 * @return Duration after which tooltip will be shown.
495 EAPI double elm_config_tooltip_delay_get(void);
498 * Set the duration after which tooltip will be shown.
500 * @return EINA_TRUE if value is set.
502 EAPI void elm_config_tooltip_delay_set(double delay);
505 * Get the configured cursor engine only usage
507 * This gets the globally configured exclusive usage of engine cursors.
509 * @return 1 if only engine cursors should be used
512 EAPI Eina_Bool elm_config_cursor_engine_only_get(void);
515 * Set the configured cursor engine only usage
517 * This sets the globally configured exclusive usage of engine cursors.
518 * It won't affect cursors set before changing this value.
520 * @param engine_only If 1 only engine cursors will be enabled, if 0 will
521 * look for them on theme before.
524 EAPI void elm_config_cursor_engine_only_set(Eina_Bool engine_only);
527 * Get the global scaling factor
529 * This gets the globally configured scaling factor that is applied to all
532 * @return The scaling factor
535 EAPI double elm_config_scale_get(void);
536 EAPI double elm_scale_get(void);
539 * Set the global scaling factor
541 * This sets the globally configured scaling factor that is applied to all
544 * @param scale The scaling factor to set
547 EAPI void elm_config_scale_set(double scale);
548 EAPI void elm_scale_set(double scale);
551 * @defgroup Password_last_show Password show last
552 * @ingroup Elementary
554 * Show last feature of password mode enables user to view
555 * the last input entered for few seconds before masking it.
556 * These functions allow to set this feature in password mode
557 * of entry widget and also allow to manipulate the duration
558 * for which the input has to be visible.
564 * Get the "show last" setting of password mode.
566 * This gets the "show last" setting of password mode which might be
567 * enabled or disabled.
569 * @return @c EINA_TRUE, if the "show last" setting is enabled,
570 * @c EINA_FALSE if it's disabled.
572 * @ingroup Password_last_show
574 EAPI Eina_Bool elm_config_password_show_last_get(void);
577 * Set show last setting in password mode.
579 * This enables or disables show last setting of password mode.
581 * @param password_show_last If EINA_TRUE enables "show last" in password mode.
582 * @see elm_config_password_show_last_timeout_set()
583 * @ingroup Password_last_show
585 EAPI void elm_config_password_show_last_set(Eina_Bool password_show_last);
588 * Gets the timeout value in "show last" password mode.
590 * This gets the time out value for which the last input entered in password
591 * mode will be visible.
593 * @return The timeout value of "show last" password mode.
594 * @ingroup Password_last_show
596 EAPI double elm_config_password_show_last_timeout_get(void);
599 * Set's the timeout value in "show last" password mode.
601 * This sets the time out value for which the last input entered in password
602 * mode will be visible.
604 * @param password_show_last_timeout The timeout value.
605 * @see elm_config_password_show_last_set()
606 * @ingroup Password_last_show
608 EAPI void elm_config_password_show_last_timeout_set(double password_show_last_timeout);
615 * @defgroup Engine Elementary Engine
616 * @ingroup Elementary
618 * These are functions setting and querying which rendering engine
619 * Elementary will use for drawing its windows' pixels.
621 * The following are the available engines:
625 * @li "software_16_x11"
626 * @li "software_8_x11"
630 * @li "software_16_wince_gdi"
632 * @li "software_16_sdl"
643 * @brief Get Elementary's rendering engine in use.
645 * @return The rendering engine's name
646 * @note there's no need to free the returned string, here.
648 * This gets the global rendering engine that is applied to all Elementary
651 * @see elm_config_engine_set()
653 EAPI const char *elm_config_engine_get(void);
656 * @brief Set Elementary's rendering engine for use.
658 * @param engine The rendering engine's name
660 * Note that it will take effect only to Elementary windows created after
665 EAPI void elm_config_engine_set(const char *engine);
668 * @brief Get Elementary's preferred engine to use.
670 * @return The rendering engine's name
671 * @note there's no need to free the returned string, here.
673 * This gets the global rendering engine that is applied to all Elementary
674 * applications and is PREFERRED by the application. This can (and will)
675 * override the engine configured for all applications which.
677 * @see elm_config_preferred_engine_set()
679 EAPI const char *elm_config_preferred_engine_get(void);
682 * @brief Set Elementary's preferred rendering engine for use.
684 * @param engine The rendering engine's name
686 * Note that it will take effect only to Elementary windows created after
687 * this is called. This overrides the engine set by configuration at
688 * application startup. Note that it is a hint and may not be honored.
692 EAPI void elm_config_preferred_engine_set(const char *engine);
694 typedef struct _Elm_Text_Class
700 typedef struct _Elm_Font_Overlay
702 const char *text_class;
708 * Get Elementary's list of supported text classes.
710 * @return The text classes list, with @c Elm_Text_Class blobs as data.
713 * Release the list with elm_text_classes_list_free().
715 EAPI Eina_List *elm_config_text_classes_list_get(void);
718 * Free Elementary's list of supported text classes.
722 * @see elm_config_text_classes_list_get().
724 EAPI void elm_config_text_classes_list_free(Eina_List *list);
727 * Get Elementary's list of font overlays, set with
728 * elm_config_font_overlay_set().
730 * @return The font overlays list, with @c Elm_Font_Overlay blobs as
735 * For each text class, one can set a <b>font overlay</b> for it,
736 * overriding the default font properties for that class coming from
737 * the theme in use. There is no need to free this list.
739 * @see elm_config_font_overlay_set() and elm_config_font_overlay_unset().
741 EAPI const Eina_List *elm_config_font_overlay_list_get(void);
744 * Set a font overlay for a given Elementary text class.
746 * @param text_class Text class name
747 * @param font Font name and style string
748 * @param size Font size
752 * @p font has to be in the format returned by elm_font_fontconfig_name_get().
753 * @see elm_config_font_overlay_list_get()
754 * @see elm_config_font_overlay_unset()
755 * @see edje_object_text_class_set()
757 EAPI void elm_config_font_overlay_set(const char *text_class, const char *font, Evas_Font_Size size);
762 * @return the access mode bouncing state
768 * @see elm_config_access_set()
770 EAPI Eina_Bool elm_config_access_get(void);
775 * @param is_accesss If EINA_TRUE enables access mode
777 * @note Elementary objects may have information (e.g. label on the elm_button)
778 * to be read. This information is read by access module when an object
779 * receives EVAS_CALLBACK_MOUSE_IN event
785 * @see elm_config_access_get()
787 EAPI void elm_config_access_set(Eina_Bool is_access);
790 * Get whether selection should be cleared when entry widget is unfocused.
792 * @return if the selection would be cleared on unfocus.
798 * @see elm_config_selection_unfocused_clear_set()
800 EAPI Eina_Bool elm_config_selection_unfocused_clear_get(void);
803 * Set whether selection should be cleared when entry widget is unfocused.
805 * @param enabled If EINA_TRUE clear selection when unfocus,
806 * otherwise does not clear selection when unfocus.
812 * @see elm_config_selection_unfocused_clear_get()
814 EAPI void elm_config_selection_unfocused_clear_set(Eina_Bool enabled);
817 * Unset a font overlay for a given Elementary text class.
819 * @param text_class Text class name
823 * This will bring back text elements belonging to text class
824 * @p text_class back to their default font settings.
826 EAPI void elm_config_font_overlay_unset(const char *text_class);
829 * Apply the changes made with elm_config_font_overlay_set() and
830 * elm_config_font_overlay_unset() on the current Elementary window.
834 * This applies all font overlays set to all objects in the UI.
836 EAPI void elm_config_font_overlay_apply(void);
839 * Get the configured "finger size"
841 * @return The finger size
843 * This gets the globally configured finger size, <b>in pixels</b>
847 EAPI Evas_Coord elm_config_finger_size_get(void);
848 EAPI Evas_Coord elm_finger_size_get(void);
851 * Set the configured finger size
853 * This sets the globally configured finger size in pixels
855 * @param size The finger size
858 EAPI void elm_config_finger_size_set(Evas_Coord size);
859 EAPI void elm_finger_size_set(Evas_Coord size);
862 * Get the configured cache flush interval time
864 * This gets the globally configured cache flush interval time, in
867 * @return The cache flush interval time
870 * @see elm_cache_all_flush()
872 EAPI int elm_config_cache_flush_interval_get(void);
875 * Set the configured cache flush interval time
877 * This sets the globally configured cache flush interval time, in ticks
879 * @param size The cache flush interval time
881 * @note The @p size must be greater than 0. if not, the cache flush will be
886 * @see elm_cache_all_flush()
888 EAPI void elm_config_cache_flush_interval_set(int size);
891 * Get the configured cache flush enabled state
893 * This gets the globally configured cache flush state - if it is enabled
894 * or not. When cache flushing is enabled, elementary will regularly
895 * (see elm_config_cache_flush_interval_get() ) flush caches and dump data out of
896 * memory and allow usage to re-seed caches and data in memory where it
897 * can do so. An idle application will thus minimize its memory usage as
898 * data will be freed from memory and not be re-loaded as it is idle and
899 * not rendering or doing anything graphically right now.
901 * @return The cache flush state
904 * @see elm_cache_all_flush()
906 EAPI Eina_Bool elm_config_cache_flush_enabled_get(void);
909 * Set the configured cache flush enabled state
911 * This sets the globally configured cache flush enabled state.
913 * @param enabled The cache flush enabled state
916 * @see elm_cache_all_flush()
918 EAPI void elm_config_cache_flush_enabled_set(Eina_Bool enabled);
921 * Get the configured font cache size
923 * This gets the globally configured font cache size, in bytes.
925 * @return The font cache size
928 EAPI int elm_config_cache_font_cache_size_get(void);
931 * Set the configured font cache size
933 * This sets the globally configured font cache size, in bytes
935 * @param size The font cache size
938 EAPI void elm_config_cache_font_cache_size_set(int size);
941 * Get the configured image cache size
943 * This gets the globally configured image cache size, in bytes
945 * @return The image cache size
948 EAPI int elm_config_cache_image_cache_size_get(void);
951 * Set the configured image cache size
953 * This sets the globally configured image cache size, in bytes
955 * @param size The image cache size
958 EAPI void elm_config_cache_image_cache_size_set(int size);
962 * Get the configured edje file cache size.
964 * This gets the globally configured edje file cache size, in number
967 * @return The edje file cache size
970 EAPI int elm_config_cache_edje_file_cache_size_get(void);
973 * Set the configured edje file cache size
975 * This sets the globally configured edje file cache size, in number
978 * @param size The edje file cache size
981 EAPI void elm_config_cache_edje_file_cache_size_set(int size);
984 * Get the configured edje collections (groups) cache size.
986 * This gets the globally configured edje collections cache size, in
987 * number of collections.
989 * @return The edje collections cache size
992 EAPI int elm_config_cache_edje_collection_cache_size_get(void);
995 * Set the configured edje collections (groups) cache size
997 * This sets the globally configured edje collections cache size, in
998 * number of collections.
1000 * @param size The edje collections cache size
1003 EAPI void elm_config_cache_edje_collection_cache_size_set(int size);
1006 * Get the enable status of the focus highlight
1008 * This gets whether the highlight on focused objects is enabled or not
1010 * @see elm_config_focus_highlight_enabled_set()
1013 EAPI Eina_Bool elm_config_focus_highlight_enabled_get(void);
1016 * Set the enable status of the focus highlight
1018 * @param enable Enable highlight if EINA_TRUE, disable otherwise
1020 * Set whether to show or not the highlight on focused objects
1022 * Note that it will take effect only to Elementary windows created after
1025 * @see elm_win_add()
1029 EAPI void elm_config_focus_highlight_enabled_set(Eina_Bool enable);
1032 * Get the enable status of the highlight animation
1034 * @return The focus highlight mode set
1036 * Get whether the focus highlight, if enabled, will animate its switch from
1037 * one object to the next
1041 EAPI Eina_Bool elm_config_focus_highlight_animate_get(void);
1044 * Set the enable status of the highlight animation
1046 * @param animate Enable animation if EINA_TRUE, disable otherwise
1048 * Set whether the focus highlight, if enabled, will animate its switch from
1049 * one object to the next
1051 * Note that it will take effect only to Elementary windows created after
1054 * @see elm_win_add()
1058 EAPI void elm_config_focus_highlight_animate_set(Eina_Bool animate);
1061 * Get the system mirrored mode. This determines the default mirrored mode
1064 * @return EINA_TRUE if mirrored is set, EINA_FALSE otherwise
1066 EAPI Eina_Bool elm_config_mirrored_get(void);
1069 * Set the system mirrored mode. This determines the default mirrored mode
1072 * @param mirrored EINA_TRUE to set mirrored mode, EINA_FALSE to unset it.
1074 EAPI void elm_config_mirrored_set(Eina_Bool mirrored);
1077 * Get the indicator service name according to the rotation degree.
1079 * @param rotation The rotation which related with the indicator service name, in degrees (0-360),
1081 * @return The indicator service name according to the rotation degree.
1083 EAPI const char *elm_config_indicator_service_get(int rotation);