src/lib/elm_scroller.h

   1 /**
   2  * @defgroup Scroller Scroller
   3  *
   4  * A scroller holds a single object and "scrolls it around". This means that
   5  * it allows the user to use a scrollbar (or a finger) to drag the viewable
   6  * region around, allowing to move through a much larger object that is
   7  * contained in the scroller. The scroller will always have a small minimum
   8  * size by default as it won't be limited by the contents of the scroller.
   9  *
  10  * Signals that you can add callbacks for are:
  11  * @li "edge,left" - the left edge of the content has been reached
  12  * @li "edge,right" - the right edge of the content has been reached
  13  * @li "edge,top" - the top edge of the content has been reached
  14  * @li "edge,bottom" - the bottom edge of the content has been reached
  15  * @li "scroll" - the content has been scrolled (moved)
  16  * @li "scroll,anim,start" - scrolling animation has started
  17  * @li "scroll,anim,stop" - scrolling animation has stopped
  18  * @li "scroll,drag,start" - dragging the contents around has started
  19  * @li "scroll,drag,stop" - dragging the contents around has stopped
  20  * @note The "scroll,anim,*" and "scroll,drag,*" signals are only emitted by
  21  * user intervetion.
  22  *
  23  * @note When Elemementary is in embedded mode the scrollbars will not be
  24  * dragable, they appear merely as indicators of how much has been scrolled.
  25  * @note When Elementary is in desktop mode the thumbscroll(a.k.a.
  26  * fingerscroll) won't work.
  27  *
  28  * Default contents parts of the scroller widget that you can use for are:
  29  * @li "default" - A content of the scroller
  30  *
  31  * In @ref tutorial_scroller you'll find an example of how to use most of
  32  * this API.
  33  * @{
  34  */
  35
  36 /**
  37  * @brief Type that controls when scrollbars should appear.
  38  *
  39  * @see elm_scroller_policy_set()
  40  */
  41 typedef enum _Elm_Scroller_Policy
  42 {
  43    ELM_SCROLLER_POLICY_AUTO = 0, /**< Show scrollbars as needed */
  44    ELM_SCROLLER_POLICY_ON, /**< Always show scrollbars */
  45    ELM_SCROLLER_POLICY_OFF, /**< Never show scrollbars */
  46    ELM_SCROLLER_POLICY_LAST
  47 } Elm_Scroller_Policy;
  48
  49 /**
  50  * @brief Add a new scroller to the parent
  51  *
  52  * @param parent The parent object
  53  * @return The new object or NULL if it cannot be created
  54  */
  55 EAPI Evas_Object *
  56                                   elm_scroller_add(Evas_Object *parent)
  57 EINA_ARG_NONNULL(1);
  58
  59 /**
  60  * @brief Set the content of the scroller widget (the object to be scrolled around).
  61  *
  62  * @param obj The scroller object
  63  * @param content The new content object
  64  *
  65  * Once the content object is set, a previously set one will be deleted.
  66  * If you want to keep that old content object, use the
  67  * elm_scroller_content_unset() function.
  68  * @deprecated use elm_object_content_set() instead
  69  */
  70 EINA_DEPRECATED EAPI void         elm_scroller_content_set(Evas_Object *obj, Evas_Object *child) EINA_ARG_NONNULL(1);
  71
  72 /**
  73  * @brief Get the content of the scroller widget
  74  *
  75  * @param obj The slider object
  76  * @return The content that is being used
  77  *
  78  * Return the content object which is set for this widget
  79  *
  80  * @see elm_scroller_content_set()
  81  * @deprecated use elm_object_content_get() instead.
  82  */
  83 EINA_DEPRECATED EAPI Evas_Object *elm_scroller_content_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
  84
  85 /**
  86  * @brief Unset the content of the scroller widget
  87  *
  88  * @param obj The slider object
  89  * @return The content that was being used
  90  *
  91  * Unparent and return the content object which was set for this widget
  92  *
  93  * @see elm_scroller_content_set()
  94  * @deprecated use elm_object_content_unset() instead.
  95  */
  96 EINA_DEPRECATED EAPI Evas_Object *elm_scroller_content_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
  97
  98 /**
  99  * @brief Set custom theme elements for the scroller
 100  *
 101  * @param obj The scroller object
 102  * @param widget The widget name to use (default is "scroller")
 103  * @param base The base name to use (default is "base")
 104  */
 105 EAPI void                         elm_scroller_custom_widget_base_theme_set(Evas_Object *obj, const char *widget, const char *base) EINA_ARG_NONNULL(1, 2, 3);
 106
 107 /**
 108  * @brief Make the scroller minimum size limited to the minimum size of the content
 109  *
 110  * @param obj The scroller object
 111  * @param w Enable limiting minimum size horizontally
 112  * @param h Enable limiting minimum size vertically
 113  *
 114  * By default the scroller will be as small as its design allows,
 115  * irrespective of its content. This will make the scroller minimum size the
 116  * right size horizontally and/or vertically to perfectly fit its content in
 117  * that direction.
 118  */
 119 EAPI void                         elm_scroller_content_min_limit(Evas_Object *obj, Eina_Bool w, Eina_Bool h) EINA_ARG_NONNULL(1);
 120
 121 /**
 122  * @brief Show a specific virtual region within the scroller content object
 123  *
 124  * @param obj The scroller object
 125  * @param x X coordinate of the region
 126  * @param y Y coordinate of the region
 127  * @param w Width of the region
 128  * @param h Height of the region
 129  *
 130  * This will ensure all (or part if it does not fit) of the designated
 131  * region in the virtual content object (0, 0 starting at the top-left of the
 132  * virtual content object) is shown within the scroller.
 133  */
 134 EAPI void                         elm_scroller_region_show(Evas_Object *obj, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
 135
 136 /**
 137  * @brief Set the scrollbar visibility policy
 138  *
 139  * @param obj The scroller object
 140  * @param policy_h Horizontal scrollbar policy
 141  * @param policy_v Vertical scrollbar policy
 142  *
 143  * This sets the scrollbar visibility policy for the given scroller.
 144  * ELM_SCROLLER_POLICY_AUTO means the scrollbar is made visible if it is
 145  * needed, and otherwise kept hidden. ELM_SCROLLER_POLICY_ON turns it on all
 146  * the time, and ELM_SCROLLER_POLICY_OFF always keeps it off. This applies
 147  * respectively for the horizontal and vertical scrollbars.
 148  */
 149 EAPI void                         elm_scroller_policy_set(Evas_Object *obj, Elm_Scroller_Policy policy_h, Elm_Scroller_Policy policy_v) EINA_ARG_NONNULL(1);
 150
 151 /**
 152  * @brief Gets scrollbar visibility policy
 153  *
 154  * @param obj The scroller object
 155  * @param policy_h Horizontal scrollbar policy
 156  * @param policy_v Vertical scrollbar policy
 157  *
 158  * @see elm_scroller_policy_set()
 159  */
 160 EAPI void                         elm_scroller_policy_get(const Evas_Object *obj, Elm_Scroller_Policy *policy_h, Elm_Scroller_Policy *policy_v) EINA_ARG_NONNULL(1);
 161
 162 /**
 163  * @brief Get the currently visible content region
 164  *
 165  * @param obj The scroller object
 166  * @param x X coordinate of the region
 167  * @param y Y coordinate of the region
 168  * @param w Width of the region
 169  * @param h Height of the region
 170  *
 171  * This gets the current region in the content object that is visible through
 172  * the scroller. The region co-ordinates are returned in the @p x, @p y, @p
 173  * w, @p h values pointed to.
 174  *
 175  * @note All coordinates are relative to the content.
 176  *
 177  * @see elm_scroller_region_show()
 178  */
 179 EAPI void                         elm_scroller_region_get(const Evas_Object *obj, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
 180
 181 /**
 182  * @brief Get the size of the content object
 183  *
 184  * @param obj The scroller object
 185  * @param w Width of the content object.
 186  * @param h Height of the content object.
 187  *
 188  * This gets the size of the content object of the scroller.
 189  */
 190 EAPI void                         elm_scroller_child_size_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
 191
 192 /**
 193  * @brief Set bouncing behavior
 194  *
 195  * @param obj The scroller object
 196  * @param h_bounce Allow bounce horizontally
 197  * @param v_bounce Allow bounce vertically
 198  *
 199  * When scrolling, the scroller may "bounce" when reaching an edge of the
 200  * content object. This is a visual way to indicate the end has been reached.
 201  * This is enabled by default for both axis. This API will set if it is enabled
 202  * for the given axis with the boolean parameters for each axis.
 203  */
 204 EAPI void                         elm_scroller_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce) EINA_ARG_NONNULL(1);
 205
 206 /**
 207  * @brief Get the bounce behaviour
 208  *
 209  * @param obj The Scroller object
 210  * @param h_bounce Will the scroller bounce horizontally or not
 211  * @param v_bounce Will the scroller bounce vertically or not
 212  *
 213  * @see elm_scroller_bounce_set()
 214  */
 215 EAPI void                         elm_scroller_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce) EINA_ARG_NONNULL(1);
 216
 217 /**
 218  * @brief Set scroll page size relative to viewport size.
 219  *
 220  * @param obj The scroller object
 221  * @param h_pagerel The horizontal page relative size
 222  * @param v_pagerel The vertical page relative size
 223  *
 224  * The scroller is capable of limiting scrolling by the user to "pages". That
 225  * is to jump by and only show a "whole page" at a time as if the continuous
 226  * area of the scroller content is split into page sized pieces. This sets
 227  * the size of a page relative to the viewport of the scroller. 1.0 is "1
 228  * viewport" is size (horizontally or vertically). 0.0 turns it off in that
 229  * axis. This is mutually exclusive with page size
 230  * (see elm_scroller_page_size_set()  for more information). Likewise 0.5
 231  * is "half a viewport". Sane usable values are normally between 0.0 and 1.0
 232  * including 1.0. If you only want 1 axis to be page "limited", use 0.0 for
 233  * the other axis.
 234  */
 235 EAPI void                         elm_scroller_page_relative_set(Evas_Object *obj, double h_pagerel, double v_pagerel) EINA_ARG_NONNULL(1);
 236
 237 /**
 238  * @brief Set scroll page size.
 239  *
 240  * @param obj The scroller object
 241  * @param h_pagesize The horizontal page size
 242  * @param v_pagesize The vertical page size
 243  *
 244  * This sets the page size to an absolute fixed value, with 0 turning it off
 245  * for that axis.
 246  *
 247  * @see elm_scroller_page_relative_set()
 248  */
 249 EAPI void                         elm_scroller_page_size_set(Evas_Object *obj, Evas_Coord h_pagesize, Evas_Coord v_pagesize) EINA_ARG_NONNULL(1);
 250
 251 /**
 252  * @brief Get scroll current page number.
 253  *
 254  * @param obj The scroller object
 255  * @param h_pagenumber The horizontal page number
 256  * @param v_pagenumber The vertical page number
 257  *
 258  * The page number starts from 0. 0 is the first page.
 259  * Current page means the page which meets the top-left of the viewport.
 260  * If there are two or more pages in the viewport, it returns the number of the page
 261  * which meets the top-left of the viewport.
 262  *
 263  * @see elm_scroller_last_page_get()
 264  * @see elm_scroller_page_show()
 265  * @see elm_scroller_page_brint_in()
 266  */
 267 EAPI void                         elm_scroller_current_page_get(const Evas_Object *obj, int *h_pagenumber, int *v_pagenumber) EINA_ARG_NONNULL(1);
 268
 269 /**
 270  * @brief Get scroll last page number.
 271  *
 272  * @param obj The scroller object
 273  * @param h_pagenumber The horizontal page number
 274  * @param v_pagenumber The vertical page number
 275  *
 276  * The page number starts from 0. 0 is the first page.
 277  * This returns the last page number among the pages.
 278  *
 279  * @see elm_scroller_current_page_get()
 280  * @see elm_scroller_page_show()
 281  * @see elm_scroller_page_brint_in()
 282  */
 283 EAPI void                         elm_scroller_last_page_get(const Evas_Object *obj, int *h_pagenumber, int *v_pagenumber) EINA_ARG_NONNULL(1);
 284
 285 /**
 286  * Show a specific virtual region within the scroller content object by page number.
 287  *
 288  * @param obj The scroller object
 289  * @param h_pagenumber The horizontal page number
 290  * @param v_pagenumber The vertical page number
 291  *
 292  * 0, 0 of the indicated page is located at the top-left of the viewport.
 293  * This will jump to the page directly without animation.
 294  *
 295  * Example of usage:
 296  *
 297  * @code
 298  * sc = elm_scroller_add(win);
 299  * elm_scroller_content_set(sc, content);
 300  * elm_scroller_page_relative_set(sc, 1, 0);
 301  * elm_scroller_current_page_get(sc, &h_page, &v_page);
 302  * elm_scroller_page_show(sc, h_page + 1, v_page);
 303  * @endcode
 304  *
 305  * @see elm_scroller_page_bring_in()
 306  */
 307 EAPI void                         elm_scroller_page_show(Evas_Object *obj, int h_pagenumber, int v_pagenumber) EINA_ARG_NONNULL(1);
 308
 309 /**
 310  * Show a specific virtual region within the scroller content object by page number.
 311  *
 312  * @param obj The scroller object
 313  * @param h_pagenumber The horizontal page number
 314  * @param v_pagenumber The vertical page number
 315  *
 316  * 0, 0 of the indicated page is located at the top-left of the viewport.
 317  * This will slide to the page with animation.
 318  *
 319  * Example of usage:
 320  *
 321  * @code
 322  * sc = elm_scroller_add(win);
 323  * elm_scroller_content_set(sc, content);
 324  * elm_scroller_page_relative_set(sc, 1, 0);
 325  * elm_scroller_last_page_get(sc, &h_page, &v_page);
 326  * elm_scroller_page_bring_in(sc, h_page, v_page);
 327  * @endcode
 328  *
 329  * @see elm_scroller_page_show()
 330  */
 331 EAPI void                         elm_scroller_page_bring_in(Evas_Object *obj, int h_pagenumber, int v_pagenumber) EINA_ARG_NONNULL(1);
 332
 333 /**
 334  * @brief Show a specific virtual region within the scroller content object.
 335  *
 336  * @param obj The scroller object
 337  * @param x X coordinate of the region
 338  * @param y Y coordinate of the region
 339  * @param w Width of the region
 340  * @param h Height of the region
 341  *
 342  * This will ensure all (or part if it does not fit) of the designated
 343  * region in the virtual content object (0, 0 starting at the top-left of the
 344  * virtual content object) is shown within the scroller. Unlike
 345  * elm_scroller_region_show(), this allow the scroller to "smoothly slide"
 346  * to this location (if configuration in general calls for transitions). It
 347  * may not jump immediately to the new location and make take a while and
 348  * show other content along the way.
 349  *
 350  * @see elm_scroller_region_show()
 351  */
 352 EAPI void                         elm_scroller_region_bring_in(Evas_Object *obj, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
 353
 354 /**
 355  * @brief Set event propagation on a scroller
 356  *
 357  * @param obj The scroller object
 358  * @param propagation If propagation is enabled or not
 359  *
 360  * This enables or disabled event propagation from the scroller content to
 361  * the scroller and its parent. By default event propagation is disabled.
 362  */
 363 EAPI void                         elm_scroller_propagate_events_set(Evas_Object *obj, Eina_Bool propagation) EINA_ARG_NONNULL(1);
 364
 365 /**
 366  * @brief Get event propagation for a scroller
 367  *
 368  * @param obj The scroller object
 369  * @return The propagation state
 370  *
 371  * This gets the event propagation for a scroller.
 372  *
 373  * @see elm_scroller_propagate_events_set()
 374  */
 375 EAPI Eina_Bool                    elm_scroller_propagate_events_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 376
 377 /**
 378  * @brief Set scrolling gravity on a scroller
 379  *
 380  * @param obj The scroller object
 381  * @param x The scrolling horizontal gravity
 382  * @param y The scrolling vertical gravity
 383  *
 384  * The gravity, defines how the scroller will adjust its view
 385  * when the size of the scroller contents increase.
 386  *
 387  * The scroller will adjust the view to glue itself as follows.
 388  *
 389  *  x=0.0, for showing the left most region of the content.
 390  *  x=1.0, for showing the right most region of the content.
 391  *  y=0.0, for showing the bottom most region of the content.
 392  *  y=1.0, for showing the top most region of the content.
 393  *
 394  * Default values for x and y are 0.0
 395  */
 396 EAPI void                         elm_scroller_gravity_set(Evas_Object *obj, double x, double y) EINA_ARG_NONNULL(1);
 397
 398 /**
 399  * @brief Get scrolling gravity values for a scroller
 400  *
 401  * @param obj The scroller object
 402  * @param x The scrolling horizontal gravity
 403  * @param y The scrolling vertical gravity
 404  *
 405  * This gets gravity values for a scroller.
 406  *
 407  * @see elm_scroller_gravity_set()
 408  *
 409  */
 410 EAPI void                         elm_scroller_gravity_get(const Evas_Object *obj, double *x, double *y) EINA_ARG_NONNULL(1);
 411
 412 /**
 413  * @}
 414  */