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