src/lib/elm_scroller.h

   1 /**
   2  * @defgroup Scroller Scroller
   3  * @ingroup Elementary
   4  *
   5  * @image html scroller_inheritance_tree.png
   6  * @image latex scroller_inheritance_tree.eps
   7  *
   8  * A scroller holds (and clips) a single object and "scrolls it
   9  * around". This means that it allows the user to use a scroll bar (or
  10  * a finger) to drag the viewable region around, moving through a much
  11  * larger object that is contained in the scroller. The scroller will
  12  * always have a small minimum size by default as it won't be limited
  13  * by the contents of the scroller.
  14  *
  15  * This widget inherits from the @ref Layout one, so that all the
  16  * functions acting on it also work for scroller objects.
  17  *
  18  * This widget emits the following signals, besides the ones sent from
  19  * @li @c "edge,left" - the left edge of the content has been reached
  20  * @li @c "edge,right" - the right edge of the content has been reached
  21  * @li @c "edge,top" - the top edge of the content has been reached
  22  * @li @c "edge,bottom" - the bottom edge of the content has been reached
  23  * @li @c "scroll" - the content has been scrolled (moved)
  24  * @li @c "scroll,anim,start" - scrolling animation has started
  25  * @li @c "scroll,anim,stop" - scrolling animation has stopped
  26  * @li @c "scroll,drag,start" - dragging the contents around has started
  27  * @li @c "scroll,drag,stop" - dragging the contents around has stopped
  28  *
  29  * This widget implements the @ref elm-scrollable-interface interface.
  30  * Its (non-deprecated) API functions, except for elm_scroller_add(),
  31  * which gives basic scroller objects, are meant to be a basis for all
  32  * other scrollable widgets (i.e. widgets implementing @ref
  33  * elm-scrollable-interface). So, they will work both on pristine
  34  * scroller widgets and on other "specialized" scrollable widgets.
  35  *
  36  * @note The @c "scroll,anim,*" and @c "scroll,drag,*" signals are
  37  * only emitted by user intervention.
  38  *
  39  * @note When Elementary is under its default profile and theme (meant
  40  * for touch interfaces), scroll bars will @b not be draggable --
  41  * their function is merely to indicate how much has been scrolled.
  42  *
  43  * @note When Elementary is under its desktop/standard profile and
  44  * theme, the thumb scroll (a.k.a. finger scroll) won't work.
  45  *
  46  * Default content parts of the scroller widget that you can use are:
  47  * @li @c "default" - Content of the scroller
  48  *
  49  * In @ref tutorial_scroller you'll find an example on how to use most
  50  * of this API.
  51  * @{
  52  */
  53
  54 /**
  55  * @brief Type that controls when scrollbars should appear.
  56  *
  57  * @see elm_scroller_policy_set()
  58  */
  59 typedef enum
  60 {
  61    ELM_SCROLLER_POLICY_AUTO = 0, /**< Show scrollbars as needed */
  62    ELM_SCROLLER_POLICY_ON, /**< Always show scrollbars */
  63    ELM_SCROLLER_POLICY_OFF, /**< Never show scrollbars */
  64    ELM_SCROLLER_POLICY_LAST
  65 } Elm_Scroller_Policy;
  66
  67 /**
  68  * @brief Add a new scroller to the parent
  69  *
  70  * @param parent The parent object
  71  * @return The new object or NULL if it cannot be created
  72  *
  73  * @ingroup Scroller
  74  */
  75 EAPI Evas_Object                 *elm_scroller_add(Evas_Object *parent);
  76
  77 /**
  78  * @brief Set custom theme elements for the scroller
  79  *
  80  * @param obj The scroller object
  81  * @param widget The widget name to use (default is "scroller")
  82  * @param base The base name to use (default is "base")
  83  *
  84  * @deprecated Use elm_layout_theme_set() instead.
  85  *
  86  * @ingroup Scroller
  87  */
  88 EINA_DEPRECATED EAPI void         elm_scroller_custom_widget_base_theme_set(Evas_Object *obj, const char *widget, const char *base);
  89
  90 /**
  91  * @brief Make the scroller minimum size limited to the minimum size of the content
  92  *
  93  * @param obj The scroller object
  94  * @param w Enable limiting minimum size horizontally
  95  * @param h Enable limiting minimum size vertically
  96  *
  97  * By default the scroller will be as small as its design allows,
  98  * irrespective of its content. This will make the scroller minimum size the
  99  * right size horizontally and/or vertically to perfectly fit its content in
 100  * that direction.
 101  *
 102  * @ingroup Scroller
 103  */
 104 EAPI void                         elm_scroller_content_min_limit(Evas_Object *obj, Eina_Bool w, Eina_Bool h);
 105
 106 /**
 107  * @brief Show a specific virtual region within the scroller content object
 108  *
 109  * @param obj The scroller object
 110  * @param x X coordinate of the region
 111  * @param y Y coordinate of the region
 112  * @param w Width of the region
 113  * @param h Height of the region
 114  *
 115  * This will ensure all (or part if it does not fit) of the designated
 116  * region in the virtual content object (0, 0 starting at the top-left of the
 117  * virtual content object) is shown within the scroller.
 118  *
 119  * @ingroup Scroller
 120  */
 121 EAPI void                         elm_scroller_region_show(Evas_Object *obj, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h);
 122
 123 /**
 124  * @brief Set the scrollbar visibility policy
 125  *
 126  * @param obj The scroller object
 127  * @param policy_h Horizontal scrollbar policy
 128  * @param policy_v Vertical scrollbar policy
 129  *
 130  * This sets the scrollbar visibility policy for the given scroller.
 131  * ELM_SCROLLER_POLICY_AUTO means the scrollbar is made visible if it is
 132  * needed, and otherwise kept hidden. ELM_SCROLLER_POLICY_ON turns it on all
 133  * the time, and ELM_SCROLLER_POLICY_OFF always keeps it off. This applies
 134  * respectively for the horizontal and vertical scrollbars.
 135  *
 136  * @ingroup Scroller
 137  */
 138 EAPI void                         elm_scroller_policy_set(Evas_Object *obj, Elm_Scroller_Policy policy_h, Elm_Scroller_Policy policy_v);
 139
 140 /**
 141  * @brief Gets scrollbar visibility policy
 142  *
 143  * @param obj The scroller object
 144  * @param policy_h Horizontal scrollbar policy
 145  * @param policy_v Vertical scrollbar policy
 146  *
 147  * @see elm_scroller_policy_set()
 148  *
 149  * @ingroup Scroller
 150  */
 151 EAPI void                         elm_scroller_policy_get(const Evas_Object *obj, Elm_Scroller_Policy *policy_h, Elm_Scroller_Policy *policy_v);
 152
 153 /**
 154  * @brief Get the currently visible content region
 155  *
 156  * @param obj The scroller object
 157  * @param x X coordinate of the region
 158  * @param y Y coordinate of the region
 159  * @param w Width of the region
 160  * @param h Height of the region
 161  *
 162  * This gets the current region in the content object that is visible through
 163  * the scroller. The region co-ordinates are returned in the @p x, @p y, @p
 164  * w, @p h values pointed to.
 165  *
 166  * @note All coordinates are relative to the content.
 167  *
 168  * @see elm_scroller_region_show()
 169  *
 170  * @ingroup Scroller
 171  */
 172 EAPI void                         elm_scroller_region_get(const Evas_Object *obj, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h);
 173
 174 /**
 175  * @brief Get the size of the content object
 176  *
 177  * @param obj The scroller object
 178  * @param w Width of the content object.
 179  * @param h Height of the content object.
 180  *
 181  * This gets the size of the content object of the scroller.
 182  *
 183  * @ingroup Scroller
 184  */
 185 EAPI void                         elm_scroller_child_size_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h);
 186
 187 /**
 188  * @brief Set bouncing behavior
 189  *
 190  * @param obj The scroller object
 191  * @param h_bounce Allow bounce horizontally
 192  * @param v_bounce Allow bounce vertically
 193  *
 194  * When scrolling, the scroller may "bounce" when reaching an edge of the
 195  * content object. This is a visual way to indicate the end has been reached.
 196  * This is enabled by default for both axis. This API will set if it is enabled
 197  * for the given axis with the boolean parameters for each axis.
 198  *
 199  * @ingroup Scroller
 200  */
 201 EAPI void                         elm_scroller_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce);
 202
 203 /**
 204  * @brief Get the bounce behaviour
 205  *
 206  * @param obj The Scroller object
 207  * @param h_bounce Will the scroller bounce horizontally or not
 208  * @param v_bounce Will the scroller bounce vertically or not
 209  *
 210  * @see elm_scroller_bounce_set()
 211  *
 212  * @ingroup Scroller
 213  */
 214 EAPI void                         elm_scroller_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce);
 215
 216 /**
 217  * @brief Set scroll page size relative to viewport size.
 218  *
 219  * @param obj The scroller object
 220  * @param h_pagerel The horizontal page relative size
 221  * @param v_pagerel The vertical page relative size
 222  *
 223  * The scroller is capable of limiting scrolling by the user to "pages". That
 224  * is to jump by and only show a "whole page" at a time as if the continuous
 225  * area of the scroller content is split into page sized pieces. This sets
 226  * the size of a page relative to the viewport of the scroller. 1.0 is "1
 227  * viewport" is size (horizontally or vertically). 0.0 turns it off in that
 228  * axis. This is mutually exclusive with page size
 229  * (see elm_scroller_page_size_set()  for more information). Likewise 0.5
 230  * is "half a viewport". Sane usable values are normally between 0.0 and 1.0
 231  * including 1.0. If you only want 1 axis to be page "limited", use 0.0 for
 232  * the other axis.
 233  *
 234  * @ingroup Scroller
 235  */
 236 EAPI void                         elm_scroller_page_relative_set(Evas_Object *obj, double h_pagerel, double v_pagerel);
 237
 238 /**
 239  * Get a given scroller widget's scrolling page size, relative to
 240  * its viewport size.
 241  *
 242  * @param obj The scroller object
 243  * @param h_pagerel Pointer to a variable where to store the
 244  * horizontal page (relative) size
 245  * @param v_pagerel Pointer to a variable where to store the
 246  * vertical page (relative) size
 247  *
 248  * @see elm_scroller_page_relative_set() for more details
 249  *
 250  * @since 1.7
 251  *
 252  * @ingroup Scroller
 253  */
 254 EAPI void                         elm_scroller_page_relative_get(const Evas_Object *obj, double *h_pagerel, double *v_pagerel);
 255
 256 /**
 257  * @brief Set scroll page size.
 258  *
 259  * @param obj The scroller object
 260  * @param h_pagesize The horizontal page size
 261  * @param v_pagesize The vertical page size
 262  *
 263  * This sets the page size to an absolute fixed value, with 0 turning it off
 264  * for that axis.
 265  *
 266  * @see elm_scroller_page_relative_set()
 267  * @see elm_scroller_page_size_get()
 268  *
 269  * @ingroup Scroller
 270  */
 271 EAPI void                         elm_scroller_page_size_set(Evas_Object *obj, Evas_Coord h_pagesize, Evas_Coord v_pagesize);
 272
 273 /**
 274  * @brief Retrieve a scroller widget's current page size.
 275  *
 276  * @param obj The scroller object
 277  * @param h_pagesize Where to store its horizontal page size
 278  * @param v_pagesize Where to store its vertical page size
 279  *
 280  * @see elm_scroller_page_size_set() for more details
 281  * @see elm_scroller_page_relative_set()
 282  *
 283  * @since 1.7
 284  *
 285  * @ingroup Scroller
 286  */
 287 EAPI void                         elm_scroller_page_size_get(const Evas_Object *obj, Evas_Coord *h_pagesize, Evas_Coord *v_pagesize);
 288
 289 /**
 290  * @brief Set the maxium of the movable page at a flicking.
 291  *
 292  * @param obj The scroller object
 293  * @param page_limit_h The maxium of the movable horizontal page
 294  * @param page_limit_v The maxium of the movable vertical page
 295  *
 296  * The value of maxium movable page should be more than 1.
 297  *
 298  * @see elm_scroller_page_scroll_limit_get()
 299  *
 300  * @since 1.8
 301  *
 302  * @ingroup Scroller
 303  */
 304 EAPI void                         elm_scroller_page_scroll_limit_set(Evas_Object *obj, int page_limit_h, int page_limit_v);
 305
 306 /**
 307  * @brief Get the maxium of the movable page at a flicking.
 308  *
 309  * @param obj The scroller object
 310  * @param page_limit_h The maxium of the movable horizontal page
 311  * @param page_limit_v The maxium of the movable vertical page
 312  *
 313  *
 314  * @see elm_scroller_page_scroll_limit_set()
 315  *
 316  * @since 1.8
 317  *
 318  * @ingroup Scroller
 319  */
 320 EAPI void                         elm_scroller_page_scroll_limit_get(Evas_Object *obj, int *page_limit_h, int *page_limit_v);
 321
 322 /**
 323  * @brief Get scroll current page number.
 324  *
 325  * @param obj The scroller object
 326  * @param h_pagenumber The horizontal page number
 327  * @param v_pagenumber The vertical page number
 328  *
 329  * The page number starts from 0. 0 is the first page.
 330  * Current page means the page which meets the top-left of the viewport.
 331  * If there are two or more pages in the viewport, it returns the number of the page
 332  * which meets the top-left of the viewport.
 333  *
 334  * @see elm_scroller_last_page_get()
 335  * @see elm_scroller_page_show()
 336  * @see elm_scroller_page_bring_in()
 337  *
 338  * @ingroup Scroller
 339  */
 340 EAPI void                         elm_scroller_current_page_get(const Evas_Object *obj, int *h_pagenumber, int *v_pagenumber);
 341
 342 /**
 343  * @brief Get scroll last page number.
 344  *
 345  * @param obj The scroller object
 346  * @param h_pagenumber The horizontal page number
 347  * @param v_pagenumber The vertical page number
 348  *
 349  * The page number starts from 0. 0 is the first page.
 350  * This returns the last page number among the pages.
 351  *
 352  * @see elm_scroller_current_page_get()
 353  * @see elm_scroller_page_show()
 354  * @see elm_scroller_page_bring_in()
 355  *
 356  * @ingroup Scroller
 357  */
 358 EAPI void                         elm_scroller_last_page_get(const Evas_Object *obj, int *h_pagenumber, int *v_pagenumber);
 359
 360 /**
 361  * Show a specific virtual region within the scroller content object by page number.
 362  *
 363  * @param obj The scroller object
 364  * @param h_pagenumber The horizontal page number
 365  * @param v_pagenumber The vertical page number
 366  *
 367  * 0, 0 of the indicated page is located at the top-left of the viewport.
 368  * This will jump to the page directly without animation.
 369  *
 370  * Example of usage:
 371  *
 372  * @code
 373  * sc = elm_scroller_add(win);
 374  * elm_object_content_set(sc, content);
 375  * elm_scroller_page_relative_set(sc, 1, 0);
 376  * elm_scroller_current_page_get(sc, &h_page, &v_page);
 377  * elm_scroller_page_show(sc, h_page + 1, v_page);
 378  * @endcode
 379  *
 380  * @see elm_scroller_page_bring_in()
 381  *
 382  * @ingroup Scroller
 383  */
 384 EAPI void                         elm_scroller_page_show(Evas_Object *obj, int h_pagenumber, int v_pagenumber);
 385
 386 /**
 387  * Show a specific virtual region within the scroller content object by page number.
 388  *
 389  * @param obj The scroller object
 390  * @param h_pagenumber The horizontal page number
 391  * @param v_pagenumber The vertical page number
 392  *
 393  * 0, 0 of the indicated page is located at the top-left of the viewport.
 394  * This will slide to the page with animation.
 395  *
 396  * Example of usage:
 397  *
 398  * @code
 399  * sc = elm_scroller_add(win);
 400  * elm_object_content_set(sc, content);
 401  * elm_scroller_page_relative_set(sc, 1, 0);
 402  * elm_scroller_last_page_get(sc, &h_page, &v_page);
 403  * elm_scroller_page_bring_in(sc, h_page, v_page);
 404  * @endcode
 405  *
 406  * @see elm_scroller_page_show()
 407  *
 408  * @ingroup Scroller
 409  */
 410 EAPI void                         elm_scroller_page_bring_in(Evas_Object *obj, int h_pagenumber, int v_pagenumber);
 411
 412 /**
 413  * @brief Show a specific virtual region within the scroller content object.
 414  *
 415  * @param obj The scroller object
 416  * @param x X coordinate of the region
 417  * @param y Y coordinate of the region
 418  * @param w Width of the region
 419  * @param h Height of the region
 420  *
 421  * This will ensure all (or part if it does not fit) of the designated
 422  * region in the virtual content object (0, 0 starting at the top-left of the
 423  * virtual content object) is shown within the scroller. Unlike
 424  * elm_scroller_region_show(), this allow the scroller to "smoothly slide"
 425  * to this location (if configuration in general calls for transitions). It
 426  * may not jump immediately to the new location and make take a while and
 427  * show other content along the way.
 428  *
 429  * @see elm_scroller_region_show()
 430  *
 431  * @ingroup Scroller
 432  */
 433 EAPI void                         elm_scroller_region_bring_in(Evas_Object *obj, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h);
 434
 435 /**
 436  * @brief Set event propagation on a scroller
 437  *
 438  * @param obj The scroller object
 439  * @param propagation If propagation is enabled or not
 440  *
 441  * This enables or disables event propagation from the scroller
 442  * content to the scroller and its parent. By default event
 443  * propagation is @b enabled.
 444  *
 445  * @ingroup Scroller
 446  */
 447 EAPI void                         elm_scroller_propagate_events_set(Evas_Object *obj, Eina_Bool propagation);
 448
 449 /**
 450  * @brief Get event propagation for a scroller
 451  *
 452  * @param obj The scroller object
 453  * @return The propagation state
 454  *
 455  * This gets the event propagation for a scroller.
 456  *
 457  * @see elm_scroller_propagate_events_set()
 458  *
 459  * @ingroup Scroller
 460  */
 461 EAPI Eina_Bool                    elm_scroller_propagate_events_get(const Evas_Object *obj);
 462
 463 /**
 464  * @brief Set scrolling gravity on a scroller
 465  *
 466  * @param obj The scroller object
 467  * @param x The scrolling horizontal gravity
 468  * @param y The scrolling vertical gravity
 469  *
 470  * The gravity, defines how the scroller will adjust its view
 471  * when the size of the scroller contents increase.
 472  *
 473  * The scroller will adjust the view to glue itself as follows.
 474  *
 475  *  x=0.0, for showing the left most region of the content.
 476  *  x=1.0, for showing the right most region of the content.
 477  *  y=0.0, for showing the bottom most region of the content.
 478  *  y=1.0, for showing the top most region of the content.
 479  *
 480  * Default values for x and y are 0.0
 481  *
 482  * @ingroup Scroller
 483  */
 484 EAPI void                         elm_scroller_gravity_set(Evas_Object *obj, double x, double y);
 485
 486 /**
 487  * @brief Get scrolling gravity values for a scroller
 488  *
 489  * @param obj The scroller object
 490  * @param x The scrolling horizontal gravity
 491  * @param y The scrolling vertical gravity
 492  *
 493  * This gets gravity values for a scroller.
 494  *
 495  * @see elm_scroller_gravity_set()
 496  *
 497  * @ingroup Scroller
 498  */
 499 EAPI void                         elm_scroller_gravity_get(const Evas_Object *obj, double *x, double *y);
 500
 501 /**
 502  * @}
 503  */