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