diff options
author | Adrien Nader <adrien@notk.org> | 2014-10-13 16:07:24 +0200 |
---|---|---|
committer | Nicolas Aguirre <aguirre.nicolas@gmail.com> | 2014-10-20 10:27:29 +0200 |
commit | e7e25c4892c7054c5f6994d22274f6b72ee9ab73 (patch) | |
tree | 0fe4397691ebf3fc27f2630d627232710917f621 | |
parent | 1cc7fc32d4b3473319133034cf7ee5aa9fa229ea (diff) | |
download | elementary-devs/captainigloo/doc.tar.gz |
doc: add API docs in elm_interface_scrollable.devs/captainigloo/doc
This adds
- gravity_set
- gravity_get
- bounce_allow_set
- bounce_allow_get
- movement_block_set
- movement_block_get
- policy_get
- policy_set
- content_region_get
- content_region_set
- page_size_set
- page_size_get
- page_snap_allow_set
- page_snap_allow_get
- single_direction_get
- single_direction_set
- last_page_get
- current_page_get
- content_size_get
- scroll_up_cb
- hbar_drag_cb
- drag_start_cb
- scroll_left_cb
- vbar_press_cb
- hbar_press_cb
- hbar_unpress_cb
- drag_stop_cb
- page_change_cb
- animate_start_cb
- scroll_down_cb
- scroll_cb
- animate_stop_cb
- scroll_right_cb
- edge_left_cb
- vbar_drag_cb
- vbar_unpress_cb
- edge_bottom_cb
- edge_top_cb
- page_show
- region_bring_in
- page_bring_in
- content_region_show
- content_min_limit
-rw-r--r-- | src/lib/elm_interface_scrollable.eo | 470 |
1 files changed, 369 insertions, 101 deletions
diff --git a/src/lib/elm_interface_scrollable.eo b/src/lib/elm_interface_scrollable.eo index 16d398146..320651cee 100644 --- a/src/lib/elm_interface_scrollable.eo +++ b/src/lib/elm_interface_scrollable.eo @@ -2,30 +2,67 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart) { legacy_prefix: null; eo_prefix: elm_interface_scrollable; - data: Elm_Scrollable_Smart_Interface_Data; + data: Elm_Scrollable_Smart_Interface_Data; properties { gravity { set { - /*@ No description supplied by the EAPI. */ + /*@ Set scrolling gravity on the scrollable + + The gravity defines how the scroller will adjust its view + when the size of the scroller contents increases. + + The scroller will adjust the view to glue itself as follows. + + x=0.0, for staying where it is relative to the left edge of the content + x=1.0, for staying where it is relative to the rigth edge of the content + y=0.0, for staying where it is relative to the top edge of the content + y=1.0, for staying where it is relative to the bottom edge of the content + + Default values for x and y are 0.0 + + @ingroup Widget + */ } get { - /*@ No description supplied by the EAPI. */ + /*@ Get scrolling gravity on the scrollable + + The gravity defines how the scroller will adjust its view + when the size of the scroller contents increases. + + The scroller will adjust the view to glue itself as follows. + + x=0.0, for staying where it is relative to the left edge of the content + x=1.0, for staying where it is relative to the rigth edge of the content + y=0.0, for staying where it is relative to the top edge of the content + y=1.0, for staying where it is relative to the bottom edge of the content + + Default values for x and y are 0.0 + + @ingroup Widget + */ } values { - double x; - double y; + double x; /*@ Horizontal scrolling gravity */ + double y; /*@ Vertical scrolling gravity */ } } bounce_allow { + /* @brief Bouncing behavior + * + * When scrolling, the scroller may "bounce" when reaching an edge of the + * content object. This is a visual way to indicate the end has been reached. + * This is enabled by default for both axis. This API will set if it is enabled + * for the given axis with the boolean parameters for each axis. + * + * @ingroup Widget + */ set { - /*@ No description supplied by the EAPI. */ } get { - /*@ No description supplied by the EAPI. */ } values { - bool horiz; - bool vert; + bool horiz; /*@ Horizontal bounce policy. */ + bool vert; /*@ Vertical bounce policy. */ } } wheel_disabled { @@ -40,14 +77,30 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart) } } movement_block { + /*@ + * @brief Blocking of scrolling (per axis) + * + * This function will block scrolling movement (by input of a user) in + * a given direction. One can disable movements in the X axis, the Y + * axis or both. The default value is #ELM_SCROLLER_MOVEMENT_NO_BLOCK, + * where movements are allowed in both directions. + * + * What makes this function different from + * freeze_push(), hold_push() and lock_x_set() (or lock_y_set()) + * is that it @b doesn't propagate its effects to any parent or child + * widget of @a obj. Only the target scrollable widget will be locked + * with regard to scrolling. + * + * @since 1.8 + * + * @ingroup Widget + */ set { - /*@ No description supplied by the EAPI. */ } get { - /*@ No description supplied by the EAPI. */ } values { - Elm_Scroller_Movement_Block block; + Elm_Scroller_Movement_Block block; /*@ Which axis (or axes) to block */ } } momentum_animator_disabled { @@ -62,29 +115,48 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart) } } policy { + /*@ + * @brief Scrollbar visibility policy + * + * #ELM_SCROLLER_POLICY_AUTO means the scrollbar is made visible if it is + * needed, and otherwise kept hidden. #ELM_SCROLLER_POLICY_ON turns it on all + * the time, and #ELM_SCROLLER_POLICY_OFF always keeps it off. This applies + * respectively for the horizontal and vertical scrollbars. + * + * @ingroup Widget + */ set { - /*@ No description supplied by the EAPI. */ } get { - /*@ No description supplied by the EAPI. */ } values { - Elm_Scroller_Policy hbar; - Elm_Scroller_Policy vbar; + Elm_Scroller_Policy hbar; /*@ Horizontal scrollbar policy */ + Elm_Scroller_Policy vbar; /*@ Vertical scrollbar policy */ } } content_region { + /*@ + * @brief Currently visible content region + * + * This gets the current region in the content object that is visible through + * the scroller. The region co-ordinates are returned in the @p x, @p y, @p + * w, @p h values pointed to. + * + * @note All coordinates are relative to the content. + * + * @see elm_scroller_region_show() + * + * @ingroup Widget + */ set { - /*@ No description supplied by the EAPI. */ } get { - /*@ No description supplied by the EAPI. */ } values { - Evas_Coord x; - Evas_Coord y; - Evas_Coord w; - Evas_Coord h; + Evas_Coord x; /*@ X coordinate of the region */ + Evas_Coord y; /*@ Y coordinate of the region */ + Evas_Coord w; /*@ Width of the region */ + Evas_Coord h; /*@ Height of the region */ } } repeat_events { @@ -99,15 +171,29 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart) } } page_size { + /*@ + * @brief Scroll page size relative to viewport size. + * + * The scroller is capable of limiting scrolling by the user to "pages". That + * is to jump by and only show a "whole page" at a time as if the continuous + * area of the scroller content is split into page sized pieces. This sets + * the size of a page relative to the viewport of the scroller. 1.0 is "1 + * viewport" is size (horizontally or vertically). 0.0 turns it off in that + * axis. This is mutually exclusive with page size + * (see elm_scroller_page_size_set() for more information). Likewise 0.5 + * is "half a viewport". Sane usable values are normally between 0.0 and 1.0 + * including 1.0. If you only want 1 axis to be page "limited", use 0.0 for + * the other axis. + * + * @ingroup Widget + */ set { - /*@ No description supplied by the EAPI. */ } get { - /*@ No description supplied by the EAPI. */ } values { - Evas_Coord x; - Evas_Coord y; + Evas_Coord x; /*@ The horizontal page relative size */ + Evas_Coord y; /*@ The vertical page relative size */ } } bounce_animator_disabled { @@ -134,15 +220,30 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart) } } page_snap_allow { + /*@ + * @brief Page snapping behavior + * + * When scrolling, if a scroller is paged (see + * elm_scroller_page_size_set() and elm_scroller_page_relative_set()), + * the scroller may snap to pages when being scrolled, i.e., even if + * it had momentum to scroll further, it will stop at the next page + * boundaries. This is @b disabled, by default, for both axis. This + * function will set if it that is enabled or not, for each axis. + * + * @note If @a obj is not set to have pages, nothing will happen after + * this call. + * + * @since 1.8 + * + * @ingroup Widget + */ set { - /*@ Enable/disable page bouncing, for paged scrollers, on each axis. */ } get { - /*@ Get wether page bouncing is enabled, for paged scrollers, on each axis. */ } values { - bool horiz; - bool vert; + bool horiz; /*@ Allow snap horizontally */ + bool vert; /*@ Allow snap vertically */ } } paging { @@ -160,14 +261,28 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart) } } single_direction { + /*@ + * @brief Single direction scroll configuration + * + * This makes it possible to restrict scrolling to a single direction, + * with a "soft" or "hard" behavior. + * + * The hard behavior restricts the scrolling to a single direction all + * of the time while the soft one will restrict depending on factors + * such as the movement angle. If the user scrolls roughly in one + * direction only, it will only move according to it while if the move + * was clearly wanted on both axes, it will happen on both of them. + * + * @since 1.8 + * + * @ingroup Widget + */ set { - /*@ No description supplied by the EAPI. */ } get { - /*@ No description supplied by the EAPI. */ } values { - Elm_Scroller_Single_Direction single_dir; + Elm_Scroller_Single_Direction single_dir; /*@ The single direction scroll policy */ } } step_size { @@ -184,26 +299,38 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart) } scroll_up_cb { set { - /*@ No description supplied by the EAPI. */ + /*@ Set the callback to run when the content has been moved up. + + @ingroup Widget + + */ } values { - Elm_Interface_Scrollable_Cb scroll_up_cb; + Elm_Interface_Scrollable_Cb scroll_up_cb; /*@ The callback */ } } hbar_drag_cb { set { - /*@ No description supplied by the EAPI. */ + /*@ Set the callback to run when the horizontal scrollbar is dragged. + + @ingroup Widget + + */ } values { - Elm_Interface_Scrollable_Cb hbar_drag_cb; + Elm_Interface_Scrollable_Cb hbar_drag_cb; /*@ The callback */ } } drag_start_cb { set { - /*@ No description supplied by the EAPI. */ + /*@ Set the callback to run when dragging of the contents has started. + + @ingroup Widget + + */ } values { - Elm_Interface_Scrollable_Cb drag_start_cb; + Elm_Interface_Scrollable_Cb drag_start_cb; /*@ The callback */ } } freeze { @@ -224,42 +351,63 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart) } scroll_left_cb { set { - /*@ No description supplied by the EAPI. */ + /*@ Set the callback to run when the content has been moved to the left + + @ingroup Widget + + */ } values { - Elm_Interface_Scrollable_Cb scroll_left_cb; + Elm_Interface_Scrollable_Cb scroll_left_cb; /*@ The callback */ } } vbar_press_cb { set { - /*@ No description supplied by the EAPI. */ + /*@ Set the callback to run when the vertical scrollbar is pressed. + + @ingroup Widget + + */ } values { - Elm_Interface_Scrollable_Cb vbar_press_cb; + Elm_Interface_Scrollable_Cb vbar_press_cb; /*@ The callback */ } } hbar_press_cb { set { - /*@ No description supplied by the EAPI. */ + /*@ Set the callback to run when the horizontal scrollbar is pressed. + + @ingroup Widget + + */ } values { - Elm_Interface_Scrollable_Cb hbar_press_cb; + Elm_Interface_Scrollable_Cb hbar_press_cb; /*@ The callback */ } } hbar_unpress_cb { set { - /*@ No description supplied by the EAPI. */ + /*@ Set the callback to run when the horizontal scrollbar is unpressed. + + @ingroup Widget + + */ } values { - Elm_Interface_Scrollable_Cb hbar_unpress_cb; + Elm_Interface_Scrollable_Cb hbar_unpress_cb; /*@ The callback */ } } drag_stop_cb { set { - /*@ No description supplied by the EAPI. */ + /*@ Set the callback to run when dragging of the contents has stopped. + * + + @ingroup Widget + + */ } values { - Elm_Interface_Scrollable_Cb drag_stop_cb; + Elm_Interface_Scrollable_Cb drag_stop_cb; /*@ The callback */ } } extern_pan { @@ -272,10 +420,14 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart) } page_change_cb { set { - /*@ No description supplied by the EAPI. */ + /*@ Set the callback to run when the visible page changes. + + @ingroup Widget + + */ } values { - Elm_Interface_Scrollable_Cb page_change_cb; + Elm_Interface_Scrollable_Cb page_change_cb; /*@ The callback */ } } hold { @@ -288,18 +440,26 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart) } animate_start_cb { set { - /*@ No description supplied by the EAPI. */ + /*@ Set the callback to run when the scrolling animation has started. + + @ingroup Widget + + */ } values { - Elm_Interface_Scrollable_Cb animate_start_cb; + Elm_Interface_Scrollable_Cb animate_start_cb; /*@ The callback */ } } scroll_down_cb { set { - /*@ No description supplied by the EAPI. */ + /*@ Set the callback to run when the content has been moved down. + + @ingroup Widget + + */ } values { - Elm_Interface_Scrollable_Cb scroll_down_cb; + Elm_Interface_Scrollable_Cb scroll_down_cb; /*@ The callback */ } } page_relative { @@ -313,18 +473,26 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart) } scroll_cb { set { - /*@ No description supplied by the EAPI. */ + /*@ Set the callback to run when the content has been moved. + + @ingroup Widget + + */ } values { - Elm_Interface_Scrollable_Cb scroll_cb; + Elm_Interface_Scrollable_Cb scroll_cb; /*@ The callback */ } } animate_stop_cb { set { - /*@ No description supplied by the EAPI. */ + /*@ Set the callback to run when the scrolling animation has stopped. + + @ingroup Widget + + */ } values { - Elm_Interface_Scrollable_Cb animate_stop_cb; + Elm_Interface_Scrollable_Cb animate_stop_cb; /*@ The callback */ } } mirrored { @@ -345,10 +513,14 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart) } scroll_right_cb { set { - /*@ No description supplied by the EAPI. */ + /*@ Set the callback to run when the content has been moved to the right. + + @ingroup Widget + + */ } values { - Elm_Interface_Scrollable_Cb scroll_right_cb; + Elm_Interface_Scrollable_Cb scroll_right_cb; /*@ The callback */ } } content { @@ -361,50 +533,74 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart) } edge_left_cb { set { - /*@ No description supplied by the EAPI. */ + /*@ Set the callback to run when the left edge of the content has been reached. + + @ingroup Widget + + */ } values { - Elm_Interface_Scrollable_Cb edge_left_cb; + Elm_Interface_Scrollable_Cb edge_left_cb; /*@ The callback */ } } vbar_drag_cb { set { - /*@ No description supplied by the EAPI. */ + /*@ Set the callback to run when the horizontal scrollbar is dragged. + + @ingroup Widget + + */ } values { - Elm_Interface_Scrollable_Cb vbar_drag_cb; + Elm_Interface_Scrollable_Cb vbar_drag_cb; /*@ The callback */ } } vbar_unpress_cb { set { - /*@ No description supplied by the EAPI. */ + /*@ Set the callback to run when the horizontal scrollbar is unpressed. + + @ingroup Widget + + */ } values { - Elm_Interface_Scrollable_Cb vbar_unpress_cb; + Elm_Interface_Scrollable_Cb vbar_unpress_cb; /*@ The callback */ } } edge_bottom_cb { set { - /*@ No description supplied by the EAPI. */ + /*@ Set the callback to run when the bottom edge of the content has been reached. + + @ingroup Widget + + */ } values { - Elm_Interface_Scrollable_Cb edge_bottom_cb; + Elm_Interface_Scrollable_Cb edge_bottom_cb; /*@ The callback */ } } edge_right_cb { set { - /*@ No description supplied by the EAPI. */ + /*@ Set the callback to run when the right edge of the content has been reached. + + @ingroup Widget + + */ } values { - Elm_Interface_Scrollable_Cb edge_right_cb; + Elm_Interface_Scrollable_Cb edge_right_cb; /*@ The callback */ } } edge_top_cb { set { - /*@ No description supplied by the EAPI. */ + /*@ Set the callback to run when the top edge of the content has been reached. + + @ingroup Widget + + */ } values { - Elm_Interface_Scrollable_Cb edge_top_cb; + Elm_Interface_Scrollable_Cb edge_top_cb; /*@ The callback */ } } objects { @@ -418,20 +614,42 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart) } last_page { get { - /*@ No description supplied by the EAPI. */ + /*@ Get scroll last page number. + + The page number starts from 0. 0 is the first page. + This returns the last page number among the pages. + + @see elm_scroller_current_page_get() + @see elm_scroller_page_show() + @see elm_scroller_page_bring_in() + + @ingroup Widget + */ } values { - int pagenumber_h; - int pagenumber_v; + int pagenumber_h; /*@ The horizontal page number */ + int pagenumber_v; /*@ The vertical page number */ } } current_page { get { - /*@ No description supplied by the EAPI. */ + /*@ Get scroll current page number. + + The page number starts from 0. 0 is the first page. + Current page means the page which meets the top-left of the viewport. + If there are two or more pages in the viewport, it returns the number of the page + which meets the top-left of the viewport. + + @see elm_scroller_last_page_get() + @see elm_scroller_page_show() + @see elm_scroller_page_bring_in() + + @ingroup Widget + */ } values { - int pagenumber_h; - int pagenumber_v; + int pagenumber_h; /*@ The horizontal page number */ + int pagenumber_v; /*@ The vertical page number */ } } content_viewport_geometry { @@ -447,11 +665,17 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart) } content_size { get { - /*@ No description supplied by the EAPI. */ + /*@ Get the size of the content object + + This gets the size of the content object of the scroller. + + @ingroup Scroller + */ } values { - Evas_Coord w; - Evas_Coord h; + Evas_Coord w; /*@ Width of the content object. */ + Evas_Coord h; /*@ Height of the content object. */ + } } } @@ -472,42 +696,86 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart) } } page_show { - /*@ No description supplied by the EAPI. */ + /*@ Show a specific virtual region within the scroller content object by page number. + + 0, 0 of the indicated page is located at the top-left of the viewport. + This will jump to the page directly without animation. + + @see elm_scroller_page_bring_in() + + @ingroup Widget + */ params { - @in int pagenumber_h; - @in int pagenumber_v; + @in int pagenumber_h; /*@ The horizontal page number */ + @in int pagenumber_v; /*@ The vertical page number */ } } region_bring_in { - /*@ No description supplied by the EAPI. */ + /*@ Show a specific virtual region within the scroller content object. + + This will ensure all (or part if it does not fit) of the designated + region in the virtual content object (0, 0 starting at the top-left of the + virtual content object) is shown within the scroller. Unlike + elm_scroller_region_show(), this allows the scroller to "smoothly slide" + to this location (if configuration in general calls for transitions). It + may not jump immediately to the new location and make take a while and + show other content along the way. + + @see elm_scroller_region_show() + + @ingroup Widget + */ params { - @in Evas_Coord x; - @in Evas_Coord y; - @in Evas_Coord w; - @in Evas_Coord h; + @in Evas_Coord x; /*@ X coordinate of the region */ + @in Evas_Coord y; /*@ Y coordinate of the region */ + @in Evas_Coord w; /*@ Width of the region */ + @in Evas_Coord h; /*@ Height of the region */ } } page_bring_in { - /*@ No description supplied by the EAPI. */ + /*@ Show a specific virtual region within the scroller content object by page number. + + 0, 0 of the indicated page is located at the top-left of the viewport. + This will slide to the page with animation. + + @see elm_scroller_page_show() + + @ingroup Scroller + */ params { - @in int pagenumber_h; - @in int pagenumber_v; + @in int pagenumber_h; /*@ The horizontal page number */ + @in int pagenumber_v; /*@ The vertical page number */ } } content_region_show { - /*@ No description supplied by the EAPI. */ + /*@ Show a specific virtual region within the scroller content object + + This will ensure all (or part if it does not fit) of the designated + region in the virtual content object (0, 0 starting at the top-left of the + virtual content object) is shown within the scroller. + + @ingroup Widget + */ params { - @in Evas_Coord x; - @in Evas_Coord y; - @in Evas_Coord w; - @in Evas_Coord h; + @in Evas_Coord x; /*@ X coordinate of the region */ + @in Evas_Coord y; /*@ Y coordinate of the region */ + @in Evas_Coord w; /*@ Width of the region */ + @in Evas_Coord h; /*@ Height of the region */ } } content_min_limit { - /*@ No description supplied by the EAPI. */ + /*@ Prevent the scrollable from being smaller than the minimum size of the content. + + By default the scroller will be as small as its design allows, + irrespective of its content. This will make the scroller minimum size the + right size horizontally and/or vertically to perfectly fit its content in + that direction. + + @ingroup Widget + */ params { - @in bool w; - @in bool h; + @in bool w; /*@ whether to limit the minimum horizontal size */ + @in bool h; /*@ whether to limit the minimum vertical size */ } } } |