xartigas pushed a commit to branch master.
http://git.enlightenment.org/core/efl.git/commit/?id=fb82b51d6a16b0726e5589209a182eb9928e7d2c
commit fb82b51d6a16b0726e5589209a182eb9928e7d2c
Author: Xavi Artigas <xavierarti...@yahoo.es>
Date: Fri Apr 26 13:01:41 2019 +0200
docs: Reword Efl.Container and family
Summary:
Avoid using "Item" since this is used by Grid and List items, or "Child"
since
this is what Efl.Object uses.
Also clarify what each container does.
Test Plan: Only changes in docs. Everything still builds and passes tests.
Reviewers: bu5hm4n, cedric, zmike
Reviewed By: bu5hm4n
Subscribers: #reviewers, #committers
Tags: #efl
Differential Revision: https://phab.enlightenment.org/D8720
---
src/lib/efl/interfaces/efl_container.eo | 14 +++---
src/lib/efl/interfaces/efl_pack.eo | 22 +++++----
src/lib/efl/interfaces/efl_pack_linear.eo | 81 ++++++++++++++++---------------
3 files changed, 62 insertions(+), 55 deletions(-)
diff --git a/src/lib/efl/interfaces/efl_container.eo
b/src/lib/efl/interfaces/efl_container.eo
index d45d0a1d75..e308e2e51f 100644
--- a/src/lib/efl/interfaces/efl_container.eo
+++ b/src/lib/efl/interfaces/efl_container.eo
@@ -1,8 +1,8 @@
interface Efl.Container
{
- [[Common interface for objects that have multiple contents (sub objects).
+ [[Common interface for objects (containers) that can have multiple contents
(sub-objects).
- APIs in this interface deal with containers of multiple sub objects, not
+ APIs in this interface deal with containers of multiple sub-objects, not
with individual parts.
@since 1.22
@@ -12,15 +12,15 @@ interface Efl.Container
methods {
content_iterate {
[[Begin iterating over this object's contents.]]
- return: iterator<Efl.Gfx.Entity> @owned @warn_unused; [[Iterator to
object content]]
+ return: iterator<Efl.Gfx.Entity> @owned @warn_unused; [[Iterator on
object's content.]]
}
content_count {
- [[Returns the number of UI elements packed in this container.]]
- return: int; [[Number of packed UI elements]]
+ [[Returns the number of contained sub-objects.]]
+ return: int; [[Number of sub-objects.]]
}
}
events {
- content,added: Efl.Gfx.Entity; [[Sent after a new item was added.]]
- content,removed: Efl.Gfx.Entity; [[Sent after an item was removed,
before unref.]]
+ content,added: Efl.Gfx.Entity; [[Sent after a new sub-object was
added.]]
+ content,removed: Efl.Gfx.Entity; [[Sent after a sub-object was removed,
before unref.]]
}
}
diff --git a/src/lib/efl/interfaces/efl_pack.eo
b/src/lib/efl/interfaces/efl_pack.eo
index f6a9b3aa79..39f686e20c 100644
--- a/src/lib/efl/interfaces/efl_pack.eo
+++ b/src/lib/efl/interfaces/efl_pack.eo
@@ -1,28 +1,30 @@
interface @beta Efl.Pack extends Efl.Container
{
- [[API common to all UI container objects.]]
+ [[Common interface for objects (containers) with multiple contents
+ (sub-objects) which can be added and removed at runtime.
+ ]]
methods
{
pack_clear {
- [[Removes all packed contents, and unreferences them.]]
- return: bool; [[$true on success, $false otherwise]]
+ [[Removes all packed sub-objects and unreferences them.]]
+ return: bool; [[$true on success, $false otherwise.]]
}
unpack_all {
- [[Removes all packed contents, without unreferencing them.
+ [[Removes all packed sub-objects without unreferencing them.
Use with caution.
]]
- return: bool; [[$true on success, $false otherwise]]
+ return: bool; [[$true on success, $false otherwise.]]
}
unpack {
- [[Removes an existing item from the container, without deleting it.]]
+ [[Removes an existing sub-object from the container without deleting
it.]]
params {
- subobj: Efl.Gfx.Entity; [[The unpacked object.]]
+ subobj: Efl.Gfx.Entity; [[The sub-object to unpack.]]
}
- return: bool; [[$false if $subobj wasn't a child or can't be removed]]
+ return: bool; [[$false if $subobj wasn't in the container or couldn't
be removed.]]
}
pack {
- [[Adds an item to this container.
+ [[Adds a sub-object to this container.
Depending on the container this will either fill in the default
spot, replacing any already existing element or append to the end
@@ -33,7 +35,7 @@ interface @beta Efl.Pack extends Efl.Container
without deleting it.
]]
params {
- subobj: Efl.Gfx.Entity; [[An object to pack.]]
+ subobj: Efl.Gfx.Entity; [[The object to pack.]]
}
return: bool; [[$false if $subobj could not be packed.]]
}
diff --git a/src/lib/efl/interfaces/efl_pack_linear.eo
b/src/lib/efl/interfaces/efl_pack_linear.eo
index b82cee842f..b98d3ec08a 100644
--- a/src/lib/efl/interfaces/efl_pack_linear.eo
+++ b/src/lib/efl/interfaces/efl_pack_linear.eo
@@ -1,6 +1,10 @@
interface @beta Efl.Pack_Linear extends Efl.Pack
{
- [[API for containers ]]
+ [[Common interface for objects (containers) with multiple contents
+ (sub-objects) which can be added and removed at runtime in a linear
fashion.
+
+ This means the sub-objects are internally organized in an ordered list.
+ ]]
eo_prefix: efl_pack;
methods {
pack_begin {
@@ -13,12 +17,12 @@ interface @beta Efl.Pack_Linear extends Efl.Pack
container without deleting it.
]]
params {
- @in subobj: Efl.Gfx.Entity; [[Item to pack at the beginning.]]
+ @in subobj: Efl.Gfx.Entity; [[Object to pack at the beginning.]]
}
return: bool; [[$false if $subobj could not be packed.]]
}
pack_end {
- [[Append item at the end of this container.
+ [[Append object at the end of this container.
This is the same as @.pack_at($subobj, -1).
@@ -27,45 +31,46 @@ interface @beta Efl.Pack_Linear extends Efl.Pack
container without deleting it.
]]
params {
- @in subobj: Efl.Gfx.Entity; [[Item to pack at the end.]]
+ @in subobj: Efl.Gfx.Entity; [[Object to pack at the end.]]
}
return: bool; [[$false if $subobj could not be packed.]]
}
pack_before {
- [[Prepend item before other sub object.
+ [[Prepend an object before an existing sub-object.
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 before $existing.]]
- @in existing: const(Efl.Gfx.Entity); [[Item to refer to.]]
+ @in subobj: Efl.Gfx.Entity; [[Object to pack before $existing.]]
+ @in existing: const(Efl.Gfx.Entity); [[Existing reference
sub-object.]]
}
return: bool; [[$false if $existing could not be found or $subobj
could not be packed.]]
}
pack_after {
- [[Append item after other sub object.
+ [[Append an object after an existing sub-object.
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 after $existing.]]
- @in existing: const(Efl.Gfx.Entity); [[Item to refer to.]]
+ @in subobj: Efl.Gfx.Entity; [[Object to pack after $existing.]]
+ @in existing: const(Efl.Gfx.Entity); [[Existing reference
sub-object.]]
}
return: bool; [[$false if $existing could not be found or $subobj
could not be packed.]]
}
pack_at {
- [[Inserts $subobj BEFORE the item at position $index.
+ [[Inserts $subobj BEFORE the sub-object at position $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.
+ from first sub-object (0) to last ($count-1), and negative numbers
go
+ from last sub-object (-1) to first (-$count). $count is
+ the number of sub-objects currently in the container as returned by
+ @Efl.Container.content_count.
If $index is less than -$count, it will trigger
@.pack_begin($subobj)
whereas $index greater than $count-1 will trigger
@.pack_end($subobj).
@@ -75,59 +80,59 @@ interface @beta Efl.Pack_Linear extends Efl.Pack
container without deleting it.
]]
params {
- @in subobj: Efl.Gfx.Entity; [[Item to pack.]]
- @in index: int; [[Index of item to insert BEFORE.
+ @in subobj: Efl.Gfx.Entity; [[Object to pack.]]
+ @in index: int; [[Index of existing sub-object 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.
+ [[Sub-object 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.
+ from first sub-object (0) to last ($count-1), and negative numbers
go
+ from last sub-object (-1) to first (-$count). $count is
+ the number of sub-objects currently in the container as returned by
+ @Efl.Container.content_count.
- If $index is less than -$count, it will return the first item
- whereas $index greater than $count-1 will return the last item.
+ If $index is less than -$count, it will return the first sub-object
+ whereas $index greater than $count-1 will return the last
sub-object.
]]
params {
- @in index: int; [[Index of the item to retrieve.
+ @in index: int; [[Index of the existing sub-object to retrieve.
Valid range is -$count to ($count-1).
]]
}
- return: Efl.Gfx.Entity; [[The object contained at the given $index.]]
+ return: Efl.Gfx.Entity; [[The sub-object contained at the given
$index.]]
}
pack_index_get {
- [[Get the index of a child in this container.]]
+ [[Get the index of a sub-object in this container.]]
params {
- @in subobj: const(Efl.Gfx.Entity); [[An object contained in this
pack.]]
+ @in subobj: const(Efl.Gfx.Entity); [[An existing sub-object in
this container.]]
}
- 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).
+ return: int(-1); [[-1 in case $subobj is not found,
+ or the index of $subobj in the range 0 to
($count-1).
]]
}
pack_unpack_at {
- [[Pop out (remove) the item at the specified $index.
+ [[Pop out (remove) the sub-object 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.
+ from first sub-object (0) to last ($count-1), and negative numbers
go
+ from last sub-object (-1) to first (-$count). $count is
+ the number of sub-objects currently in the container as returned by
+ @Efl.Container.content_count.
- Equivalent to @Efl.Pack.unpack(@.pack_content_get($index)).
+ If $index is less than -$count, it will remove the first sub-object
+ whereas $index greater than $count-1 will remove the last
sub-object.
]]
params {
- @in index: int; [[Index of item to remove.
+ @in index: int; [[Index of the sub-object to remove.
Valid range is -$count to ($count-1).
]]
}
- return: Efl.Gfx.Entity; [[The child item if it could be removed.]]
+ return: Efl.Gfx.Entity; [[The sub-object if it could be removed.]]
}
}
}
--
