src/lib/elm_config.h

   1 /**
   2  * @defgroup Config Elementary Config
   3  *
   4  * Elementary configuration is formed by a set options bounded to a
   5  * given @ref Profile profile, like @ref Theme theme, @ref Fingers
   6  * "finger size", etc. These are functions with which one synchronizes
   7  * changes made to those values to the configuration storing files, de
   8  * facto. You most probably don't want to use the functions in this
   9  * group unless you're writing an elementary configuration manager.
  10  *
  11  * @{
  12  */
  13
  14 /**
  15  * Save back Elementary's configuration, so that it will persist on
  16  * future sessions.
  17  *
  18  * @return @c EINA_TRUE, when successful. @c EINA_FALSE, otherwise.
  19  * @ingroup Config
  20  *
  21  * This function will take effect -- thus, do I/O -- immediately. Use
  22  * it when you want to apply all configuration changes at once. The
  23  * current configuration set will get saved onto the current profile
  24  * configuration file.
  25  *
  26  */
  27 EAPI Eina_Bool elm_config_save(void);
  28
  29 /**
  30  * Reload Elementary's configuration, bounded to current selected
  31  * profile.
  32  *
  33  * @return @c EINA_TRUE, when successful. @c EINA_FALSE, otherwise.
  34  * @ingroup Config
  35  *
  36  * Useful when you want to force reloading of configuration values for
  37  * a profile. If one removes user custom configuration directories,
  38  * for example, it will force a reload with system values instead.
  39  *
  40  */
  41 EAPI void      elm_config_reload(void);
  42
  43 /**
  44  * Flush all config settings then apply those settings to all applications
  45  * using elementary on the current display.
  46  * Following functions will update the config settings
  47  * @li elm_cache_flush_interval_set()
  48  * @li elm_cache_flush_enabled_set()
  49  * @li elm_edje_file_cache_set()
  50  * @li elm_edje_collection_cache_set()
  51  * @li elm_finger_size_set()
  52  * @li elm_focus_highlight_enabled_set()
  53  * @li elm_focus_highlight_animate_set()
  54  * @li elm_font_overlay_set()
  55  * @li elm_font_cache_set()
  56  * @li elm_image_cache_set()
  57  * @li elm_profile_set()
  58  * @li elm_scale_set()
  59  * @li elm_scroll_bounce_enabled_set()
  60  * @li elm_scroll_bounce_friction_set()
  61  * @li elm_scroll_page_scroll_friction_set()
  62  * @li elm_scroll_bring_in_scroll_friction_set()
  63  * @li elm_scroll_zoom_friction_set()
  64  * @li elm_scroll_thumbscroll_enabled_set()
  65  * @li elm_scroll_thumbscroll_threshold_set()
  66  * @li elm_scroll_thumbscroll_momentum_threshold_set()
  67  * @li elm_scroll_thumbscroll_friction_set()
  68  * @li elm_scroll_thumbscroll_border_friction_set()
  69  * @li elm_scroll_thumbscroll_sensitivity_friction_set()
  70  * @li elm_theme_set()
  71  *
  72  * @ingroup Config
  73  *
  74  */
  75 EAPI void      elm_config_all_flush(void);
  76
  77 /**
  78  * @}
  79  */
  80
  81 /**
  82  * @defgroup Profile Elementary Profile
  83  *
  84  * Profiles are pre-set options that affect the whole look-and-feel of
  85  * Elementary-based applications. There are, for example, profiles
  86  * aimed at desktop computer applications and others aimed at mobile,
  87  * touchscreen-based ones. You most probably don't want to use the
  88  * functions in this group unless you're writing an elementary
  89  * configuration manager.
  90  *
  91  * @{
  92  */
  93
  94 /**
  95  * Get Elementary's profile in use.
  96  *
  97  * This gets the global profile that is applied to all Elementary
  98  * applications.
  99  *
 100  * @return The profile's name
 101  * @ingroup Profile
 102  */
 103 EAPI const char *elm_profile_current_get(void);
 104
 105 /**
 106  * Get an Elementary's profile directory path in the filesystem. One
 107  * may want to fetch a system profile's dir or a user one (fetched
 108  * inside $HOME).
 109  *
 110  * @param profile The profile's name
 111  * @param is_user Whether to lookup for a user profile (@c EINA_TRUE)
 112  *                or a system one (@c EINA_FALSE)
 113  * @return The profile's directory path.
 114  * @ingroup Profile
 115  *
 116  * @note You must free it with elm_profile_dir_free().
 117  */
 118 EAPI const char *elm_profile_dir_get(const char *profile, Eina_Bool is_user);
 119
 120 /**
 121  * Free an Elementary's profile directory path, as returned by
 122  * elm_profile_dir_get().
 123  *
 124  * @param p_dir The profile's path
 125  * @ingroup Profile
 126  *
 127  */
 128 EAPI void        elm_profile_dir_free(const char *p_dir);
 129
 130 /**
 131  * Get Elementary's list of available profiles.
 132  *
 133  * @return The profiles list. List node data are the profile name
 134  *         strings.
 135  * @ingroup Profile
 136  *
 137  * @note One must free this list, after usage, with the function
 138  *       elm_profile_list_free().
 139  */
 140 EAPI Eina_List  *elm_profile_list_get(void);
 141
 142 /**
 143  * Free Elementary's list of available profiles.
 144  *
 145  * @param l The profiles list, as returned by elm_profile_list_get().
 146  * @ingroup Profile
 147  *
 148  */
 149 EAPI void        elm_profile_list_free(Eina_List *l);
 150
 151 /**
 152  * Set Elementary's profile.
 153  *
 154  * This sets the global profile that is applied to Elementary
 155  * applications. Just the process the call comes from will be
 156  * affected.
 157  *
 158  * @param profile The profile's name
 159  * @ingroup Profile
 160  *
 161  */
 162 EAPI void        elm_profile_set(const char *profile);
 163
 164 /**
 165  * @}
 166  */
 167
 168 /**
 169  * @defgroup Scrolling Scrolling
 170  *
 171  * These are functions setting how scrollable views in Elementary
 172  * widgets should behave on user interaction.
 173  *
 174  * @{
 175  */
 176
 177 /**
 178  * Get whether scrollers should bounce when they reach their
 179  * viewport's edge during a scroll.
 180  *
 181  * @return the thumb scroll bouncing state
 182  *
 183  * This is the default behavior for touch screens, in general.
 184  * @ingroup Scrolling
 185  */
 186 EAPI Eina_Bool    elm_scroll_bounce_enabled_get(void);
 187
 188 /**
 189  * Set whether scrollers should bounce when they reach their
 190  * viewport's edge during a scroll.
 191  *
 192  * @param enabled the thumb scroll bouncing state
 193  *
 194  * @see elm_thumbscroll_bounce_enabled_get()
 195  * @ingroup Scrolling
 196  */
 197 EAPI void         elm_scroll_bounce_enabled_set(Eina_Bool enabled);
 198
 199 /**
 200  * Get the amount of inertia a scroller will impose at bounce
 201  * animations.
 202  *
 203  * @return the thumb scroll bounce friction
 204  *
 205  * @ingroup Scrolling
 206  */
 207 EAPI double       elm_scroll_bounce_friction_get(void);
 208
 209 /**
 210  * Set the amount of inertia a scroller will impose at bounce
 211  * animations.
 212  *
 213  * @param friction the thumb scroll bounce friction
 214  *
 215  * @see elm_thumbscroll_bounce_friction_get()
 216  * @ingroup Scrolling
 217  */
 218 EAPI void         elm_scroll_bounce_friction_set(double friction);
 219
 220 /**
 221  * Get the amount of inertia a <b>paged</b> scroller will impose at
 222  * page fitting animations.
 223  *
 224  * @return the page scroll friction
 225  *
 226  * @ingroup Scrolling
 227  */
 228 EAPI double       elm_scroll_page_scroll_friction_get(void);
 229
 230 /**
 231  * Set the amount of inertia a <b>paged</b> scroller will impose at
 232  * page fitting animations.
 233  *
 234  * @param friction the page scroll friction
 235  *
 236  * @see elm_thumbscroll_page_scroll_friction_get()
 237  * @ingroup Scrolling
 238  */
 239 EAPI void         elm_scroll_page_scroll_friction_set(double friction);
 240
 241 /**
 242  * Get the amount of inertia a scroller will impose at region bring
 243  * animations.
 244  *
 245  * @return the bring in scroll friction
 246  *
 247  * @ingroup Scrolling
 248  */
 249 EAPI double       elm_scroll_bring_in_scroll_friction_get(void);
 250
 251 /**
 252  * Set the amount of inertia a scroller will impose at region bring
 253  * animations.
 254  *
 255  * @param friction the bring in scroll friction
 256  *
 257  * @see elm_thumbscroll_bring_in_scroll_friction_get()
 258  * @ingroup Scrolling
 259  */
 260 EAPI void         elm_scroll_bring_in_scroll_friction_set(double friction);
 261
 262 /**
 263  * Get the amount of inertia scrollers will impose at animations
 264  * triggered by Elementary widgets' zooming API.
 265  *
 266  * @return the zoom friction
 267  *
 268  * @ingroup Scrolling
 269  */
 270 EAPI double       elm_scroll_zoom_friction_get(void);
 271
 272 /**
 273  * Set the amount of inertia scrollers will impose at animations
 274  * triggered by Elementary widgets' zooming API.
 275  *
 276  * @param friction the zoom friction
 277  *
 278  * @see elm_thumbscroll_zoom_friction_get()
 279  * @ingroup Scrolling
 280  */
 281 EAPI void         elm_scroll_zoom_friction_set(double friction);
 282
 283 /**
 284  * Get whether scrollers should be draggable from any point in their
 285  * views.
 286  *
 287  * @return the thumb scroll state
 288  *
 289  * @note This is the default behavior for touch screens, in general.
 290  * @note All other functions namespaced with "thumbscroll" will only
 291  *       have effect if this mode is enabled.
 292  *
 293  * @ingroup Scrolling
 294  */
 295 EAPI Eina_Bool    elm_scroll_thumbscroll_enabled_get(void);
 296
 297 /**
 298  * Set whether scrollers should be draggable from any point in their
 299  * views.
 300  *
 301  * @param enabled the thumb scroll state
 302  *
 303  * @see elm_thumbscroll_enabled_get()
 304  * @ingroup Scrolling
 305  */
 306 EAPI void         elm_scroll_thumbscroll_enabled_set(Eina_Bool enabled);
 307
 308 /**
 309  * Get the number of pixels one should travel while dragging a
 310  * scroller's view to actually trigger scrolling.
 311  *
 312  * @return the thumb scroll threshold
 313  *
 314  * One would use higher values for touch screens, in general, because
 315  * of their inherent imprecision.
 316  * @ingroup Scrolling
 317  */
 318 EAPI unsigned int elm_scroll_thumbscroll_threshold_get(void);
 319
 320 /**
 321  * Set the number of pixels one should travel while dragging a
 322  * scroller's view to actually trigger scrolling.
 323  *
 324  * @param threshold the thumb scroll threshold
 325  *
 326  * @see elm_thumbscroll_threshold_get()
 327  * @ingroup Scrolling
 328  */
 329 EAPI void         elm_scroll_thumbscroll_threshold_set(unsigned int threshold);
 330
 331 /**
 332  * Get the minimum speed of mouse cursor movement which will trigger
 333  * list self scrolling animation after a mouse up event
 334  * (pixels/second).
 335  *
 336  * @return the thumb scroll momentum threshold
 337  *
 338  * @ingroup Scrolling
 339  */
 340 EAPI double       elm_scroll_thumbscroll_momentum_threshold_get(void);
 341
 342 /**
 343  * Set the minimum speed of mouse cursor movement which will trigger
 344  * list self scrolling animation after a mouse up event
 345  * (pixels/second).
 346  *
 347  * @param threshold the thumb scroll momentum threshold
 348  *
 349  * @see elm_thumbscroll_momentum_threshold_get()
 350  * @ingroup Scrolling
 351  */
 352 EAPI void         elm_scroll_thumbscroll_momentum_threshold_set(double threshold);
 353
 354 /**
 355  * Get the amount of inertia a scroller will impose at self scrolling
 356  * animations.
 357  *
 358  * @return the thumb scroll friction
 359  *
 360  * @ingroup Scrolling
 361  */
 362 EAPI double       elm_scroll_thumbscroll_friction_get(void);
 363
 364 /**
 365  * Set the amount of inertia a scroller will impose at self scrolling
 366  * animations.
 367  *
 368  * @param friction the thumb scroll friction
 369  *
 370  * @see elm_thumbscroll_friction_get()
 371  * @ingroup Scrolling
 372  */
 373 EAPI void         elm_scroll_thumbscroll_friction_set(double friction);
 374
 375 /**
 376  * Get the amount of lag between your actual mouse cursor dragging
 377  * movement and a scroller's view movement itself, while pushing it
 378  * into bounce state manually.
 379  *
 380  * @return the thumb scroll border friction
 381  *
 382  * @ingroup Scrolling
 383  */
 384 EAPI double       elm_scroll_thumbscroll_border_friction_get(void);
 385
 386 /**
 387  * Set the amount of lag between your actual mouse cursor dragging
 388  * movement and a scroller's view movement itself, while pushing it
 389  * into bounce state manually.
 390  *
 391  * @param friction the thumb scroll border friction. @c 0.0 for
 392  *        perfect synchrony between two movements, @c 1.0 for maximum
 393  *        lag.
 394  *
 395  * @see elm_thumbscroll_border_friction_get()
 396  * @note parameter value will get bound to 0.0 - 1.0 interval, always
 397  *
 398  * @ingroup Scrolling
 399  */
 400 EAPI void         elm_scroll_thumbscroll_border_friction_set(double friction);
 401
 402 /**
 403  * Get the sensitivity amount which is be multiplied by the length of
 404  * mouse dragging.
 405  *
 406  * @return the thumb scroll sensitivity friction
 407  *
 408  * @ingroup Scrolling
 409  */
 410 EAPI double       elm_scroll_thumbscroll_sensitivity_friction_get(void);
 411
 412 /**
 413  * Set the sensitivity amount which is be multiplied by the length of
 414  * mouse dragging.
 415  *
 416  * @param friction the thumb scroll sensitivity friction. @c 0.1 for
 417  *        minimum sensitivity, @c 1.0 for maximum sensitivity. 0.25
 418  *        is proper.
 419  *
 420  * @see elm_thumbscroll_sensitivity_friction_get()
 421  * @note parameter value will get bound to 0.1 - 1.0 interval, always
 422  *
 423  * @ingroup Scrolling
 424  */
 425 EAPI void         elm_scroll_thumbscroll_sensitivity_friction_set(double friction);
 426
 427 /**
 428  * @}
 429  */
 430
 431 /**
 432  * Get the duration for occurring long press event.
 433  *
 434  * @return Timeout for long press event
 435  * @ingroup Longpress
 436  */
 437 EAPI double       elm_longpress_timeout_get(void);
 438
 439 /**
 440  * Set the duration for occurring long press event.
 441  *
 442  * @param lonpress_timeout Timeout for long press event
 443  * @ingroup Longpress
 444  */
 445 EAPI void         elm_longpress_timeout_set(double longpress_timeout);
 446
 447 /**
 448  * Get the duration after which tooltip will be shown.
 449  *
 450  * @return Duration after which tooltip will be shown.
 451  */
 452 EAPI double      elm_config_tooltip_delay_get(void);
 453
 454 /**
 455  * Set the duration after which tooltip will be shown.
 456  *
 457  * @return EINA_TRUE if value is set.
 458  */
 459 EAPI Eina_Bool   elm_config_tooltip_delay_set(double delay);