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  * Set Elementary's profile.
 164  *
 165  * This sets the global profile that is applied to all Elementary
 166  * applications. All running Elementary windows will be affected.
 167  *
 168  * @param profile The profile's name
 169  * @ingroup Profile
 170  *
 171  */
 172 EAPI void        elm_profile_all_set(const char *profile);
 173
 174 /**
 175  * @}
 176  */
 177
 178 /**
 179  * @defgroup Scrolling Scrolling
 180  *
 181  * These are functions setting how scrollable views in Elementary
 182  * widgets should behave on user interaction.
 183  *
 184  * @{
 185  */
 186
 187 /**
 188  * Get whether scrollers should bounce when they reach their
 189  * viewport's edge during a scroll.
 190  *
 191  * @return the thumb scroll bouncing state
 192  *
 193  * This is the default behavior for touch screens, in general.
 194  * @ingroup Scrolling
 195  */
 196 EAPI Eina_Bool    elm_scroll_bounce_enabled_get(void);
 197
 198 /**
 199  * Set whether scrollers should bounce when they reach their
 200  * viewport's edge during a scroll.
 201  *
 202  * @param enabled the thumb scroll bouncing state
 203  *
 204  * @see elm_thumbscroll_bounce_enabled_get()
 205  * @ingroup Scrolling
 206  */
 207 EAPI void         elm_scroll_bounce_enabled_set(Eina_Bool enabled);
 208
 209 /**
 210  * Set whether scrollers should bounce when they reach their
 211  * viewport's edge during a scroll, for all Elementary application
 212  * windows.
 213  *
 214  * @param enabled the thumb scroll bouncing state
 215  *
 216  * @see elm_thumbscroll_bounce_enabled_get()
 217  * @ingroup Scrolling
 218  */
 219 // XXX: deprecate and replace with elm_config_all_flush()
 220 EAPI void         elm_scroll_bounce_enabled_all_set(Eina_Bool enabled);
 221
 222 /**
 223  * Get the amount of inertia a scroller will impose at bounce
 224  * animations.
 225  *
 226  * @return the thumb scroll bounce friction
 227  *
 228  * @ingroup Scrolling
 229  */
 230 EAPI double       elm_scroll_bounce_friction_get(void);
 231
 232 /**
 233  * Set the amount of inertia a scroller will impose at bounce
 234  * animations.
 235  *
 236  * @param friction the thumb scroll bounce friction
 237  *
 238  * @see elm_thumbscroll_bounce_friction_get()
 239  * @ingroup Scrolling
 240  */
 241 EAPI void         elm_scroll_bounce_friction_set(double friction);
 242
 243 /**
 244  * Set the amount of inertia a scroller will impose at bounce
 245  * animations, for all Elementary application windows.
 246  *
 247  * @param friction the thumb scroll bounce friction
 248  *
 249  * @see elm_thumbscroll_bounce_friction_get()
 250  * @ingroup Scrolling
 251  */
 252 // XXX: deprecate and replace with elm_config_all_flush()
 253 EAPI void         elm_scroll_bounce_friction_all_set(double friction);
 254
 255 /**
 256  * Get the amount of inertia a <b>paged</b> scroller will impose at
 257  * page fitting animations.
 258  *
 259  * @return the page scroll friction
 260  *
 261  * @ingroup Scrolling
 262  */
 263 EAPI double       elm_scroll_page_scroll_friction_get(void);
 264
 265 /**
 266  * Set the amount of inertia a <b>paged</b> scroller will impose at
 267  * page fitting animations.
 268  *
 269  * @param friction the page scroll friction
 270  *
 271  * @see elm_thumbscroll_page_scroll_friction_get()
 272  * @ingroup Scrolling
 273  */
 274 EAPI void         elm_scroll_page_scroll_friction_set(double friction);
 275
 276 /**
 277  * Set the amount of inertia a <b>paged</b> scroller will impose at
 278  * page fitting animations, for all Elementary application windows.
 279  *
 280  * @param friction the page scroll friction
 281  *
 282  * @see elm_thumbscroll_page_scroll_friction_get()
 283  * @ingroup Scrolling
 284  */
 285 // XXX: deprecate and replace with elm_config_all_flush()
 286 EAPI void         elm_scroll_page_scroll_friction_all_set(double friction);
 287
 288 /**
 289  * Get the amount of inertia a scroller will impose at region bring
 290  * animations.
 291  *
 292  * @return the bring in scroll friction
 293  *
 294  * @ingroup Scrolling
 295  */
 296 EAPI double       elm_scroll_bring_in_scroll_friction_get(void);
 297
 298 /**
 299  * Set the amount of inertia a scroller will impose at region bring
 300  * animations.
 301  *
 302  * @param friction the bring in scroll friction
 303  *
 304  * @see elm_thumbscroll_bring_in_scroll_friction_get()
 305  * @ingroup Scrolling
 306  */
 307 EAPI void         elm_scroll_bring_in_scroll_friction_set(double friction);
 308
 309 /**
 310  * Set the amount of inertia a scroller will impose at region bring
 311  * animations, for all Elementary application windows.
 312  *
 313  * @param friction the bring in scroll friction
 314  *
 315  * @see elm_thumbscroll_bring_in_scroll_friction_get()
 316  * @ingroup Scrolling
 317  */
 318 // XXX: deprecate and replace with elm_config_all_flush()
 319 EAPI void         elm_scroll_bring_in_scroll_friction_all_set(double friction);
 320
 321 /**
 322  * Get the amount of inertia scrollers will impose at animations
 323  * triggered by Elementary widgets' zooming API.
 324  *
 325  * @return the zoom friction
 326  *
 327  * @ingroup Scrolling
 328  */
 329 EAPI double       elm_scroll_zoom_friction_get(void);
 330
 331 /**
 332  * Set the amount of inertia scrollers will impose at animations
 333  * triggered by Elementary widgets' zooming API.
 334  *
 335  * @param friction the zoom friction
 336  *
 337  * @see elm_thumbscroll_zoom_friction_get()
 338  * @ingroup Scrolling
 339  */
 340 EAPI void         elm_scroll_zoom_friction_set(double friction);
 341
 342 /**
 343  * Set the amount of inertia scrollers will impose at animations
 344  * triggered by Elementary widgets' zooming API, for all Elementary
 345  * application windows.
 346  *
 347  * @param friction the zoom friction
 348  *
 349  * @see elm_thumbscroll_zoom_friction_get()
 350  * @ingroup Scrolling
 351  */
 352 // XXX: deprecate and replace with elm_config_all_flush()
 353 EAPI void         elm_scroll_zoom_friction_all_set(double friction);
 354
 355 /**
 356  * Get whether scrollers should be draggable from any point in their
 357  * views.
 358  *
 359  * @return the thumb scroll state
 360  *
 361  * @note This is the default behavior for touch screens, in general.
 362  * @note All other functions namespaced with "thumbscroll" will only
 363  *       have effect if this mode is enabled.
 364  *
 365  * @ingroup Scrolling
 366  */
 367 EAPI Eina_Bool    elm_scroll_thumbscroll_enabled_get(void);
 368
 369 /**
 370  * Set whether scrollers should be draggable from any point in their
 371  * views.
 372  *
 373  * @param enabled the thumb scroll state
 374  *
 375  * @see elm_thumbscroll_enabled_get()
 376  * @ingroup Scrolling
 377  */
 378 EAPI void         elm_scroll_thumbscroll_enabled_set(Eina_Bool enabled);
 379
 380 /**
 381  * Set whether scrollers should be draggable from any point in their
 382  * views, for all Elementary application windows.
 383  *
 384  * @param enabled the thumb scroll state
 385  *
 386  * @see elm_thumbscroll_enabled_get()
 387  * @ingroup Scrolling
 388  */
 389 // XXX: deprecate and replace with elm_config_all_flush()
 390 EAPI void         elm_scroll_thumbscroll_enabled_all_set(Eina_Bool enabled);
 391
 392 /**
 393  * Get the number of pixels one should travel while dragging a
 394  * scroller's view to actually trigger scrolling.
 395  *
 396  * @return the thumb scroll threshold
 397  *
 398  * One would use higher values for touch screens, in general, because
 399  * of their inherent imprecision.
 400  * @ingroup Scrolling
 401  */
 402 EAPI unsigned int elm_scroll_thumbscroll_threshold_get(void);
 403
 404 /**
 405  * Set the number of pixels one should travel while dragging a
 406  * scroller's view to actually trigger scrolling.
 407  *
 408  * @param threshold the thumb scroll threshold
 409  *
 410  * @see elm_thumbscroll_threshold_get()
 411  * @ingroup Scrolling
 412  */
 413 EAPI void         elm_scroll_thumbscroll_threshold_set(unsigned int threshold);
 414
 415 /**
 416  * Set the number of pixels one should travel while dragging a
 417  * scroller's view to actually trigger scrolling, for all Elementary
 418  * application windows.
 419  *
 420  * @param threshold the thumb scroll threshold
 421  *
 422  * @see elm_thumbscroll_threshold_get()
 423  * @ingroup Scrolling
 424  */
 425 // XXX: deprecate and replace with elm_config_all_flush()
 426 EAPI void         elm_scroll_thumbscroll_threshold_all_set(unsigned int threshold);
 427
 428 /**
 429  * Get the minimum speed of mouse cursor movement which will trigger
 430  * list self scrolling animation after a mouse up event
 431  * (pixels/second).
 432  *
 433  * @return the thumb scroll momentum threshold
 434  *
 435  * @ingroup Scrolling
 436  */
 437 EAPI double       elm_scroll_thumbscroll_momentum_threshold_get(void);
 438
 439 /**
 440  * Set the minimum speed of mouse cursor movement which will trigger
 441  * list self scrolling animation after a mouse up event
 442  * (pixels/second).
 443  *
 444  * @param threshold the thumb scroll momentum threshold
 445  *
 446  * @see elm_thumbscroll_momentum_threshold_get()
 447  * @ingroup Scrolling
 448  */
 449 EAPI void         elm_scroll_thumbscroll_momentum_threshold_set(double threshold);
 450
 451 /**
 452  * Set the minimum speed of mouse cursor movement which will trigger
 453  * list self scrolling animation after a mouse up event
 454  * (pixels/second), for all Elementary application windows.
 455  *
 456  * @param threshold the thumb scroll momentum threshold
 457  *
 458  * @see elm_thumbscroll_momentum_threshold_get()
 459  * @ingroup Scrolling
 460  */
 461 // XXX: deprecate and replace with elm_config_all_flush()
 462 EAPI void         elm_scroll_thumbscroll_momentum_threshold_all_set(double threshold);
 463
 464 /**
 465  * Get the amount of inertia a scroller will impose at self scrolling
 466  * animations.
 467  *
 468  * @return the thumb scroll friction
 469  *
 470  * @ingroup Scrolling
 471  */
 472 EAPI double       elm_scroll_thumbscroll_friction_get(void);
 473
 474 /**
 475  * Set the amount of inertia a scroller will impose at self scrolling
 476  * animations.
 477  *
 478  * @param friction the thumb scroll friction
 479  *
 480  * @see elm_thumbscroll_friction_get()
 481  * @ingroup Scrolling
 482  */
 483 EAPI void         elm_scroll_thumbscroll_friction_set(double friction);
 484
 485 /**
 486  * Set the amount of inertia a scroller will impose at self scrolling
 487  * animations, for all Elementary application windows.
 488  *
 489  * @param friction the thumb scroll friction
 490  *
 491  * @see elm_thumbscroll_friction_get()
 492  * @ingroup Scrolling
 493  */
 494 // XXX: deprecate and replace with elm_config_all_flush()
 495 EAPI void         elm_scroll_thumbscroll_friction_all_set(double friction);
 496
 497 /**
 498  * Get the amount of lag between your actual mouse cursor dragging
 499  * movement and a scroller's view movement itself, while pushing it
 500  * into bounce state manually.
 501  *
 502  * @return the thumb scroll border friction
 503  *
 504  * @ingroup Scrolling
 505  */
 506 EAPI double       elm_scroll_thumbscroll_border_friction_get(void);
 507
 508 /**
 509  * Set the amount of lag between your actual mouse cursor dragging
 510  * movement and a scroller's view movement itself, while pushing it
 511  * into bounce state manually.
 512  *
 513  * @param friction the thumb scroll border friction. @c 0.0 for
 514  *        perfect synchrony between two movements, @c 1.0 for maximum
 515  *        lag.
 516  *
 517  * @see elm_thumbscroll_border_friction_get()
 518  * @note parameter value will get bound to 0.0 - 1.0 interval, always
 519  *
 520  * @ingroup Scrolling
 521  */
 522 EAPI void         elm_scroll_thumbscroll_border_friction_set(double friction);
 523
 524 /**
 525  * Set the amount of lag between your actual mouse cursor dragging
 526  * movement and a scroller's view movement itself, while pushing it
 527  * into bounce state manually, for all Elementary application windows.
 528  *
 529  * @param friction the thumb scroll border friction. @c 0.0 for
 530  *        perfect synchrony between two movements, @c 1.0 for maximum
 531  *        lag.
 532  *
 533  * @see elm_thumbscroll_border_friction_get()
 534  * @note parameter value will get bound to 0.0 - 1.0 interval, always
 535  *
 536  * @ingroup Scrolling
 537  */
 538 // XXX: deprecate and replace with elm_config_all_flush()
 539 EAPI void         elm_scroll_thumbscroll_border_friction_all_set(double friction);
 540
 541 /**
 542  * Get the sensitivity amount which is be multiplied by the length of
 543  * mouse dragging.
 544  *
 545  * @return the thumb scroll sensitivity friction
 546  *
 547  * @ingroup Scrolling
 548  */
 549 EAPI double       elm_scroll_thumbscroll_sensitivity_friction_get(void);
 550
 551 /**
 552  * Set the sensitivity amount which is be multiplied by the length of
 553  * mouse dragging.
 554  *
 555  * @param friction the thumb scroll sensitivity friction. @c 0.1 for
 556  *        minimum sensitivity, @c 1.0 for maximum sensitivity. 0.25
 557  *        is proper.
 558  *
 559  * @see elm_thumbscroll_sensitivity_friction_get()
 560  * @note parameter value will get bound to 0.1 - 1.0 interval, always
 561  *
 562  * @ingroup Scrolling
 563  */
 564 EAPI void         elm_scroll_thumbscroll_sensitivity_friction_set(double friction);
 565
 566 /**
 567  * Set the sensitivity amount which is be multiplied by the length of
 568  * mouse dragging, for all Elementary application windows.
 569  *
 570  * @param friction the thumb scroll sensitivity friction. @c 0.1 for
 571  *        minimum sensitivity, @c 1.0 for maximum sensitivity. 0.25
 572  *        is proper.
 573  *
 574  * @see elm_thumbscroll_sensitivity_friction_get()
 575  * @note parameter value will get bound to 0.1 - 1.0 interval, always
 576  *
 577  * @ingroup Scrolling
 578  */
 579 // XXX: deprecate and replace with elm_config_all_flush()
 580 EAPI void         elm_scroll_thumbscroll_sensitivity_friction_all_set(double friction);
 581
 582 /**
 583  * @}
 584  */
 585
 586 /**
 587  * Get the duration for occurring long press event.
 588  *
 589  * @return Timeout for long press event
 590  * @ingroup Longpress
 591  */
 592 EAPI double       elm_longpress_timeout_get(void);
 593
 594 /**
 595  * Set the duration for occurring long press event.
 596  *
 597  * @param lonpress_timeout Timeout for long press event
 598  * @ingroup Longpress
 599  */
 600 EAPI void         elm_longpress_timeout_set(double longpress_timeout);