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  * @}
  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 unless 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 threshold
 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 threshold
 377  *
 378  * @see elm_thumbscroll_threshold_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 threshold
 389  *
 390  * @see elm_thumbscroll_threshold_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 threshold
 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 threshold
 413  *
 414  * @see elm_thumbscroll_momentum_threshold_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 threshold
 425  *
 426  * @see elm_thumbscroll_momentum_threshold_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  *        minimum 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  *        minimum 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 occurring 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 occurring 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);