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 Get scroll current page number.
 291  *
 292  * @param obj The scroller object
 293  * @param h_pagenumber The horizontal page number
 294  * @param v_pagenumber The vertical page number
 295  *
 296  * The page number starts from 0. 0 is the first page.
 297  * Current page means the page which meets the top-left of the viewport.
 298  * If there are two or more pages in the viewport, it returns the number of the page
 299  * which meets the top-left of the viewport.
 300  *
 301  * @see elm_scroller_last_page_get()
 302  * @see elm_scroller_page_show()
 303  * @see elm_scroller_page_bring_in()
 304  *
 305  * @ingroup Scroller
 306  */
 307 EAPI void                         elm_scroller_current_page_get(const Evas_Object *obj, int *h_pagenumber, int *v_pagenumber);
 308
 309 /**
 310  * @brief Get scroll last 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  * The page number starts from 0. 0 is the first page.
 317  * This returns the last page number among the pages.
 318  *
 319  * @see elm_scroller_current_page_get()
 320  * @see elm_scroller_page_show()
 321  * @see elm_scroller_page_bring_in()
 322  *
 323  * @ingroup Scroller
 324  */
 325 EAPI void                         elm_scroller_last_page_get(const Evas_Object *obj, int *h_pagenumber, int *v_pagenumber);
 326
 327 /**
 328  * Show a specific virtual region within the scroller content object by page number.
 329  *
 330  * @param obj The scroller object
 331  * @param h_pagenumber The horizontal page number
 332  * @param v_pagenumber The vertical page number
 333  *
 334  * 0, 0 of the indicated page is located at the top-left of the viewport.
 335  * This will jump to the page directly without animation.
 336  *
 337  * Example of usage:
 338  *
 339  * @code
 340  * sc = elm_scroller_add(win);
 341  * elm_object_content_set(sc, content);
 342  * elm_scroller_page_relative_set(sc, 1, 0);
 343  * elm_scroller_current_page_get(sc, &h_page, &v_page);
 344  * elm_scroller_page_show(sc, h_page + 1, v_page);
 345  * @endcode
 346  *
 347  * @see elm_scroller_page_bring_in()
 348  *
 349  * @ingroup Scroller
 350  */
 351 EAPI void                         elm_scroller_page_show(Evas_Object *obj, int h_pagenumber, int v_pagenumber);
 352
 353 /**
 354  * Show a specific virtual region within the scroller content object by page number.
 355  *
 356  * @param obj The scroller object
 357  * @param h_pagenumber The horizontal page number
 358  * @param v_pagenumber The vertical page number
 359  *
 360  * 0, 0 of the indicated page is located at the top-left of the viewport.
 361  * This will slide to the page with animation.
 362  *
 363  * Example of usage:
 364  *
 365  * @code
 366  * sc = elm_scroller_add(win);
 367  * elm_object_content_set(sc, content);
 368  * elm_scroller_page_relative_set(sc, 1, 0);
 369  * elm_scroller_last_page_get(sc, &h_page, &v_page);
 370  * elm_scroller_page_bring_in(sc, h_page, v_page);
 371  * @endcode
 372  *
 373  * @see elm_scroller_page_show()
 374  *
 375  * @ingroup Scroller
 376  */
 377 EAPI void                         elm_scroller_page_bring_in(Evas_Object *obj, int h_pagenumber, int v_pagenumber);
 378
 379 /**
 380  * @brief Show a specific virtual region within the scroller content object.
 381  *
 382  * @param obj The scroller object
 383  * @param x X coordinate of the region
 384  * @param y Y coordinate of the region
 385  * @param w Width of the region
 386  * @param h Height of the region
 387  *
 388  * This will ensure all (or part if it does not fit) of the designated
 389  * region in the virtual content object (0, 0 starting at the top-left of the
 390  * virtual content object) is shown within the scroller. Unlike
 391  * elm_scroller_region_show(), this allow the scroller to "smoothly slide"
 392  * to this location (if configuration in general calls for transitions). It
 393  * may not jump immediately to the new location and make take a while and
 394  * show other content along the way.
 395  *
 396  * @see elm_scroller_region_show()
 397  *
 398  * @ingroup Scroller
 399  */
 400 EAPI void                         elm_scroller_region_bring_in(Evas_Object *obj, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h);
 401
 402 /**
 403  * @brief Set event propagation on a scroller
 404  *
 405  * @param obj The scroller object
 406  * @param propagation If propagation is enabled or not
 407  *
 408  * This enables or disables event propagation from the scroller
 409  * content to the scroller and its parent. By default event
 410  * propagation is @b enabled.
 411  *
 412  * @ingroup Scroller
 413  */
 414 EAPI void                         elm_scroller_propagate_events_set(Evas_Object *obj, Eina_Bool propagation);
 415
 416 /**
 417  * @brief Get event propagation for a scroller
 418  *
 419  * @param obj The scroller object
 420  * @return The propagation state
 421  *
 422  * This gets the event propagation for a scroller.
 423  *
 424  * @see elm_scroller_propagate_events_set()
 425  *
 426  * @ingroup Scroller
 427  */
 428 EAPI Eina_Bool                    elm_scroller_propagate_events_get(const Evas_Object *obj);
 429
 430 /**
 431  * @brief Set scrolling gravity on a scroller
 432  *
 433  * @param obj The scroller object
 434  * @param x The scrolling horizontal gravity
 435  * @param y The scrolling vertical gravity
 436  *
 437  * The gravity, defines how the scroller will adjust its view
 438  * when the size of the scroller contents increase.
 439  *
 440  * The scroller will adjust the view to glue itself as follows.
 441  *
 442  *  x=0.0, for showing the left most region of the content.
 443  *  x=1.0, for showing the right most region of the content.
 444  *  y=0.0, for showing the bottom most region of the content.
 445  *  y=1.0, for showing the top most region of the content.
 446  *
 447  * Default values for x and y are 0.0
 448  *
 449  * @ingroup Scroller
 450  */
 451 EAPI void                         elm_scroller_gravity_set(Evas_Object *obj, double x, double y);
 452
 453 /**
 454  * @brief Get scrolling gravity values for a scroller
 455  *
 456  * @param obj The scroller object
 457  * @param x The scrolling horizontal gravity
 458  * @param y The scrolling vertical gravity
 459  *
 460  * This gets gravity values for a scroller.
 461  *
 462  * @see elm_scroller_gravity_set()
 463  *
 464  * @ingroup Scroller
 465  */
 466 EAPI void                         elm_scroller_gravity_get(const Evas_Object *obj, double *x, double *y);
 467
 468 /**
 469  * @}
 470  */