zmike pushed a commit to branch efl-1.22. http://git.enlightenment.org/core/efl.git/commit/?id=e6cb121dc0324f2f050354160b9271d94ab5932d
commit e6cb121dc0324f2f050354160b9271d94ab5932d Author: Yeongjong Lee <[email protected]> Date: Fri Apr 12 07:03:28 2019 +0000 efl.pack_linear: Clarify behavior and docs Some APIs accept both positive and negative indices when accessing items. This patch changes the documentation for the lower limit from `-(count - 1)` to `-count` to allow accessing the very first item. For example (content_count = 5): | |first item| | | |last item| |positive index| 0 | 1| 2| 3| 4 | |negative index| -5 |-4|-3|-2| -1 | If negative indices are limited to be >= -4 the first item cannot be accessed using negative indices. Also, range limit of `pack_at` is removed for usability. Reviewed-by: Marcel Hollerbach <[email protected]> Reviewed-by: YeongJong Lee <[email protected]> Differential Revision: https://phab.enlightenment.org/D8433 --- src/lib/efl/interfaces/efl_pack_linear.eo | 62 ++++++++++++++++++++++--------- 1 file changed, 44 insertions(+), 18 deletions(-) diff --git a/src/lib/efl/interfaces/efl_pack_linear.eo b/src/lib/efl/interfaces/efl_pack_linear.eo index 423c6cbb6c..b82cee842f 100644 --- a/src/lib/efl/interfaces/efl_pack_linear.eo +++ b/src/lib/efl/interfaces/efl_pack_linear.eo @@ -13,12 +13,12 @@ interface @beta Efl.Pack_Linear extends Efl.Pack container without deleting it. ]] params { - @in subobj: Efl.Gfx.Entity; [[Item to pack.]] + @in subobj: Efl.Gfx.Entity; [[Item to pack at the beginning.]] } - return: bool; [[$false if $subobj could not be packed]] + return: bool; [[$false if $subobj could not be packed.]] } pack_end { - [[Append object at the end of this container. + [[Append item at the end of this container. This is the same as @.pack_at($subobj, -1). @@ -29,7 +29,7 @@ interface @beta Efl.Pack_Linear extends Efl.Pack params { @in subobj: Efl.Gfx.Entity; [[Item to pack at the end.]] } - return: bool; [[$false if $subobj could not be packed]] + return: bool; [[$false if $subobj could not be packed.]] } pack_before { [[Prepend item before other sub object. @@ -60,46 +60,72 @@ interface @beta Efl.Pack_Linear extends Efl.Pack could not be packed.]] } pack_at { - [[Inserts $subobj at the specified $index. + [[Inserts $subobj BEFORE the item at position $index. - Valid range: -$count to +$count. -1 refers to the last element. - Out of range indices will trigger an append. + $index ranges from -$count to $count-1, where positive numbers go + from first item (0) to last item ($count-1), and negative numbers go + from last item (-1) to first item (-$count). Where $count is + the number of items currently in the container. + + If $index is less than -$count, it will trigger @.pack_begin($subobj) + whereas $index greater than $count-1 will trigger @.pack_end($subobj). When this container is deleted, it will request deletion of the given $subobj. Use @Efl.Pack.unpack to remove $subobj from this container without deleting it. ]] params { - @in subobj: Efl.Gfx.Entity; [[Item to pack at given index.]] - @in index: int; [[A position.]] + @in subobj: Efl.Gfx.Entity; [[Item to pack.]] + @in index: int; [[Index of item to insert BEFORE. + Valid range is -$count to ($count-1). + ]] } return: bool; [[$false if $subobj could not be packed.]] } pack_content_get { - [[Content at a given index in this container. + [[Content at a given $index in this container. + + $index ranges from -$count to $count-1, where positive numbers go + from first item (0) to last item ($count-1), and negative numbers go + from last item (-1) to first item (-$count). Where $count is + the number of items currently in the container. - Index -1 refers to the last item. The valid range is -(count - 1) to - (count - 1). + If $index is less than -$count, it will return the first item + whereas $index greater than $count-1 will return the last item. ]] params { - index: int; [[Index number]] + @in index: int; [[Index of the item to retrieve. + Valid range is -$count to ($count-1). + ]] } return: Efl.Gfx.Entity; [[The object contained at the given $index.]] } pack_index_get { [[Get the index of a child in this container.]] params { - subobj: const(Efl.Gfx.Entity); [[An object contained in this pack.]] + @in subobj: const(Efl.Gfx.Entity); [[An object contained in this pack.]] } - return: int(-1); [[-1 in case of failure, or the index of this item.]] + return: int(-1); [[-1 in case $subobj is not a child of this object, + or the index of this item in the range 0 to ($count-1). + ]] } pack_unpack_at { - [[Pop out item at specified $index. + [[Pop out (remove) the item at the specified $index. + + $index ranges from -$count to $count-1, where positive numbers go + from first item (0) to last item ($count-1), and negative numbers go + from last item (-1) to first item (-$count). Where $count is + the number of items currently in the container. + + If $index is less than -$count, it will remove the first item + whereas $index greater than $count-1 will remove the last item. - Equivalent to unpack(content_at($index)). + Equivalent to @Efl.Pack.unpack(@.pack_content_get($index)). ]] params { - index: int; [[Index number]] + @in index: int; [[Index of item to remove. + Valid range is -$count to ($count-1). + ]] } return: Efl.Gfx.Entity; [[The child item if it could be removed.]] } --
