src/lib/elm_scroller.h

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