xartigas pushed a commit to branch master.
http://git.enlightenment.org/core/efl.git/commit/?id=2ce877d9147caf310622b60fb28670a3e5ef34fa
commit 2ce877d9147caf310622b60fb28670a3e5ef34fa
Author: Xavi Artigas <xavierarti...@yahoo.es>
Date: Fri Aug 30 11:53:40 2019 +0200
docs: Proper documentation for Collection and Item classes
Reviewers: bu5hm4n
Reviewed By: bu5hm4n
Subscribers: cedric, #reviewers, #committers
Tags: #efl, #documentation
Differential Revision: https://phab.enlightenment.org/D9798
---
src/lib/elementary/efl_ui_collection.eo | 40 ++++++++++++++++++--------
src/lib/elementary/efl_ui_default_item.eo | 20 +++++++------
src/lib/elementary/efl_ui_grid.eo | 14 +++++++--
src/lib/elementary/efl_ui_grid_default_item.eo | 7 +++--
src/lib/elementary/efl_ui_group_item.eo | 10 ++++++-
src/lib/elementary/efl_ui_item.eo | 9 ++++--
src/lib/elementary/efl_ui_list.eo | 14 +++++++--
src/lib/elementary/efl_ui_list_default_item.eo | 6 ++--
8 files changed, 85 insertions(+), 35 deletions(-)
diff --git a/src/lib/elementary/efl_ui_collection.eo
b/src/lib/elementary/efl_ui_collection.eo
index d566ff15e0..ecd0eb1e94 100644
--- a/src/lib/elementary/efl_ui_collection.eo
+++ b/src/lib/elementary/efl_ui_collection.eo
@@ -7,34 +7,50 @@ class @beta Efl.Ui.Collection extends Efl.Ui.Layout_Base
implements
Efl.Ui.Focus.Manager_Sub,
Efl.Ui.Widget_Focus_Manager
{
- [[This widget displays a list of items in an arrangement controlled by an
external $position_manager object. By using different $position_manager objects
this widget can show lists of items or two-dimensional grids of items, for
example.
+ [[This widget displays a list of items in an arrangement controlled by an
external @.position_manager
+ object. By using different @.position_manager objects this widget can
show unidimensional lists or
+ two-dimensional grids of items, for example.
- Items inside this widget can be selected according to the $select_mode
policy, and retrieved with $selected_items_get.
+ This class is intended to act as a base for widgets like @Efl.Ui.List or
@Efl.Ui.Grid, which hide
+ this complexity from the user.
+
+ Items are added using the @Efl.Pack_Linear interface and must be of
@Efl.Ui.Item type.
+
+ The direction of the arrangement can be controlled through
@Efl.Ui.Layout_Orientable.orientation.
+
+ If all items do not fit in the current widget size scrolling facilities
are provided.
+
+ Items inside this widget can be selected according to the
@Efl.Ui.Multi_Selectable.select_mode
+ policy, and the selection can be retrieved with
@Efl.Ui.Multi_Selectable.selected_items_get.
]]
event_prefix:efl_ui;
methods {
item_scroll {
- [[Bring the passed item into the viewport.]]
+ [[Brings the passed item into the viewport.]]
params {
- @in item: Efl.Ui.Item; [[The target to move in.]]
- @in animation: bool; [[If you want to have an animation or not.]]
+ @in item: Efl.Ui.Item; [[The target to move into view.]]
+ @in animation: bool; [[If you want to have an animated
transition.]]
}
}
item_scroll_align {
- [[Bring the passed item into the viewport, place the item accordingly
to align in the viewport.
+ [[Brings the passed item into the viewport and align it.
- $align selects the final position of the object inside the viewport.
0.0 will move the object to the first visible position inside the viewport, 1.0
will move it to the last visible position, and values in between will move it
accordingly to positions in between, along the scrolling axis.
+ $align selects the final position of the object inside the
viewport. 0.0 will move the object
+ to the first visible position inside the viewport, 1.0 will move it
to the last visible
+ position, and values in between will move it accordingly to
positions in between, along the
+ scrolling axis.
]]
params {
- @in item: Efl.Ui.Item; [[The target to move in.]]
- @in align: double; [[0.0 to have this item at the upper or left
side of the viewport, 1.0 to have this item at the lower or right side of the
viewport]]
- @in animation: bool; [[If you want to have an animation or not.]]
+ @in item: Efl.Ui.Item; [[The target to move into view.]]
+ @in align: double; [[0.0 to have this item at the upper or left
side of the viewport,
+ 1.0 to have this item at the lower or right
side of the viewport.]]
+ @in animation: bool; [[If you want to have an animated
transition.]]
}
}
@property position_manager {
[[Position manager object that handles placement of items.]]
values {
- position_manager : Efl.Ui.Position_Manager.Entity @owned; [[The
objects ownership is passed to the item container.]]
+ position_manager : Efl.Ui.Position_Manager.Entity @owned;
[[Ownership is passed to the item container.]]
}
}
}
@@ -74,7 +90,7 @@ class @beta Efl.Ui.Collection extends Efl.Ui.Layout_Base
implements
}
events {
item,pressed : Efl.Ui.Item; [[A $press event occurred over an item.]]
- item,unpressed : Efl.Ui.Item; [[A $unpress event occurred over an item.]]
+ item,unpressed : Efl.Ui.Item; [[An $unpress event occurred over an
item.]]
item,longpressed : Efl.Ui.Item; [[A $longpressed event occurred over an
item.]]
item,clicked : Efl.Ui.Item; [[A $clicked event occurred over an item.]]
item,clicked,any : Efl.Ui.Item; [[A $clicked,any event occurred over an
item.]]
diff --git a/src/lib/elementary/efl_ui_default_item.eo
b/src/lib/elementary/efl_ui_default_item.eo
index 374acc5de7..b11c20ab41 100644
--- a/src/lib/elementary/efl_ui_default_item.eo
+++ b/src/lib/elementary/efl_ui_default_item.eo
@@ -6,18 +6,20 @@ abstract @beta Efl.Ui.Default_Item extends Efl.Ui.Item
implements
{
[[Default Item Class.
- This class defines the standard parts of casual efl items.
- The details about placement or item layout preferences are left to the
extending classes.
- Every text property related changes are mirrored to the text part.
Content changes are mirrored to the content part.
-
+ This class defines the standard parts for most @Efl.Ui.Item: Text, Icon
and Extra.
+ Placement and layout details for these parts are left to the extending
classes like
+ @Efl.Ui.List_Default_Item and @Efl.Ui.Grid_Default_Item which should
normally be used.
+ Text-related changes are mirrored to the $text part for convenience.
+ Content-related changes are mirrored to the $icon part.
]]
data: null;
parts {
- text: Efl.Ui.Layout_Part_Text; [[The text part for default item.
- text part is the caption of the item.]]
- icon: Efl.Ui.Layout_Part_Content; [[The icon content part for default
item.
- icon part is the main content of item.]]
- extra : Efl.Ui.Layout_Part_Content; [[The extra content part for default
item.]]
+ text: Efl.Ui.Layout_Part_Text; [[The text part for default items.
+ This is the caption of the items.]]
+ icon: Efl.Ui.Layout_Part_Content; [[The icon part for default items.
+ This is the main content of the
items.]]
+ extra : Efl.Ui.Layout_Part_Content; [[The extra part for default items.
+ This is used for additional details
or badges.]]
}
implements {
Efl.Text.text { get; set; }
diff --git a/src/lib/elementary/efl_ui_grid.eo
b/src/lib/elementary/efl_ui_grid.eo
index c5921dfcd1..708d96f1c0 100644
--- a/src/lib/elementary/efl_ui_grid.eo
+++ b/src/lib/elementary/efl_ui_grid.eo
@@ -1,8 +1,18 @@
class @beta Efl.Ui.Grid extends Efl.Ui.Collection
{
- [[A scrollable grid of @Efl.Ui.Item objects.
+ [[A scrollable grid of @Efl.Ui.Item objects, typically
@Efl.Ui.Grid_Default_Item objects.
- @Efl.Ui.Grid supports group items. Group items are displayed in the top
of the viewport, if items of the group are in the viewport.
+ Items are added using the @Efl.Pack_Linear interface.
+
+ The orientation (vertical or horizontal) of the grid can be set with
+ @Efl.Ui.Layout_Orientable.orientation.
+
+ Items inside this widget can be selected according to the
@Efl.Ui.Multi_Selectable.select_mode
+ policy, and the selection can be retrieved with
@Efl.Ui.Multi_Selectable.selected_items_get.
+
+ @Efl.Ui.Grid supports grouping by using @Efl.Ui.Group_Item objects.
+ Group headers are displayed at the top of the viewport if items belonging
to the group
+ are visible in the viewport.
]]
data: null;
implements {
diff --git a/src/lib/elementary/efl_ui_grid_default_item.eo
b/src/lib/elementary/efl_ui_grid_default_item.eo
index 521a9bdf71..86000405cc 100644
--- a/src/lib/elementary/efl_ui_grid_default_item.eo
+++ b/src/lib/elementary/efl_ui_grid_default_item.eo
@@ -1,8 +1,9 @@
-
class @beta Efl.Ui.Grid_Default_Item extends Efl.Ui.Default_Item
{
- [[Grid default Item class.
- The icon part is in the middle, extra will overlap the icon part in its
right upper icon. The text is aligned below. Further details may differ between
themes.
+ [[Default Item class to be used inside @Efl.Ui.Grid containers.
+ The $icon part is in the middle, the $extra part overlaps it on its
upper-right corner.
+ The $text part is centered below the $icon.
+ Theming can change this arrangement.
]]
data: null;
implements {
diff --git a/src/lib/elementary/efl_ui_group_item.eo
b/src/lib/elementary/efl_ui_group_item.eo
index ee4cdd8e63..596c35c12a 100644
--- a/src/lib/elementary/efl_ui_group_item.eo
+++ b/src/lib/elementary/efl_ui_group_item.eo
@@ -1,6 +1,14 @@
class @beta Efl.Ui.Group_Item extends Efl.Ui.Default_Item implements
Efl.Pack_Linear
{
- [[Group item for grids and lists]]
+ [[Special @Efl.Ui.Item that acts as group header.
+
+ Items in this group have to be added directly to the @Efl.Ui.Group_Item
using the
+ @Efl.Pack_Linear interface, instead of being added to the container.
+ For example, an @Efl.Ui.List container where all items are inside a group
will contain only
+ @Efl.Ui.Group_Item objects. Normal @Efl.Ui.Item objects will be contained
inside the group items.
+
+ Each container chooses how group headers are rendered. See for example
@Efl.Ui.List or @Efl.Ui.Grid.
+ ]]
implements {
Efl.Object.constructor;
Efl.Object.invalidate;
diff --git a/src/lib/elementary/efl_ui_item.eo
b/src/lib/elementary/efl_ui_item.eo
index 82af0a5fe0..d84b919a37 100644
--- a/src/lib/elementary/efl_ui_item.eo
+++ b/src/lib/elementary/efl_ui_item.eo
@@ -4,6 +4,7 @@ abstract @beta Efl.Ui.Item extends Efl.Ui.Layout_Base
implements Efl.Ui.Selectab
This class serves as the basis to create widgets acting as selectable
items inside containers
like @Efl.Ui.List or @Efl.Ui.Grid, for example.
+
@Efl.Ui.Item provides user interaction through the @Efl.Input.Clickable
mixin.
Items can be pressed, long-pressed, etc, and appropriate events are
generated.
@Efl.Ui.Item also implements the @Efl.Ui.Selectable interface, meaning
that "selected" and
@@ -17,6 +18,8 @@ abstract @beta Efl.Ui.Item extends Efl.Ui.Layout_Base
implements Efl.Ui.Selectab
@[Efl.Input.Clickable.unpressed] -> "efl,state,unpressed",
@[Efl.Ui.Selectable.selected,changed] (true) -> "efl,state,selected",
@[Efl.Ui.Selectable.selected,changed] (false) -> "efl,state,unselected".
+
+ Item grouping inside containers is handled through the @Efl.Ui.Group_Item
class.
]]
methods {
@property index {
@@ -25,7 +28,7 @@ abstract @beta Efl.Ui.Item extends Efl.Ui.Layout_Base
implements Efl.Ui.Selectab
The container must be set through the @Efl.Ui.Item.container
property.]]
get {}
values {
- index : int; [[The index where to find this item in its
$container.]]
+ index : int; [[The index where to find this item in its
@.container.]]
}
}
@property container {
@@ -43,7 +46,9 @@ abstract @beta Efl.Ui.Item extends Efl.Ui.Layout_Base
implements Efl.Ui.Selectab
@property item_parent {
[[The parent of the item.
- This property expresses a tree structure of items. If the parent is
NULL the item is added in the root level of the content. The item parent can
only be set once, when the object is invalidated, the item parent is set to
NULL and still cannot be reset.
+ This property expresses a tree structure of items. If the parent is
NULL the item is added to
+ the root level of the content. The item parent can only be set once.
+ When the object is invalidated, the item parent is set to NULL and
still cannot be reset.
]]
values {
parent : Efl.Ui.Item;
diff --git a/src/lib/elementary/efl_ui_list.eo
b/src/lib/elementary/efl_ui_list.eo
index 058f6eca7b..4af260c190 100644
--- a/src/lib/elementary/efl_ui_list.eo
+++ b/src/lib/elementary/efl_ui_list.eo
@@ -1,11 +1,19 @@
class @beta Efl.Ui.List extends Efl.Ui.Collection
{
- [[A scrollable list of @Efl.Ui.Item objects.
+ [[A scrollable list of @Efl.Ui.Item objects, typically
@Efl.Ui.List_Default_Item objects.
- @Efl.Ui.List supports group items. Group items are displayed in the top
or right of the viewport, if the items belonging to them are in the viewport.
+ Items are added using the @Efl.Pack_Linear interface.
+ The orientation (vertical or horizontal) of the list can be set with
+ @Efl.Ui.Layout_Orientable.orientation.
- ]]
+ Items inside this widget can be selected according to the
@Efl.Ui.Multi_Selectable.select_mode
+ policy, and the selection can be retrieved with
@Efl.Ui.Multi_Selectable.selected_items_get.
+
+ @Efl.Ui.List supports grouping by using @Efl.Ui.Group_Item objects.
+ Group headers are displayed at the top or left side of the viewport if
items belonging to the group
+ are visible in the viewport.
+ ]]
data: null;
implements {
Efl.Object.constructor;
diff --git a/src/lib/elementary/efl_ui_list_default_item.eo
b/src/lib/elementary/efl_ui_list_default_item.eo
index 5ba0b3bc55..7e8e3cb3b0 100644
--- a/src/lib/elementary/efl_ui_list_default_item.eo
+++ b/src/lib/elementary/efl_ui_list_default_item.eo
@@ -1,9 +1,9 @@
class @beta Efl.Ui.List_Default_Item extends Efl.Ui.Default_Item
{
- [[List default Item class.
- It displays the three parts in horizintal order: icon, text, extra.
- Further details may differ between themes.
+ [[Default Item class to be used inside @Efl.Ui.List containers.
+ It displays the three parts in horizontal order: $icon, $text and $extra.
+ Theming can change this arrangement.
]]
data: null;
implements {
--
