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