kimcinoo
/
efl
forked from enlightenment/efl
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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
This commit is contained in:
Xavi Artigas 2019-08-30 11:53:40 +02:00
parent 37e5befd6b
commit 2ce877d914
8 changed files with 85 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
src/lib/elementary/efl_ui_collection.eo
View File

@ -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.]]

20
src/lib/elementary/efl_ui_default_item.eo
View File

@ -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; }

14
src/lib/elementary/efl_ui_grid.eo
View File

@ -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 {

7
src/lib/elementary/efl_ui_grid_default_item.eo
View File

@ -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 {

10
src/lib/elementary/efl_ui_group_item.eo
View File

@ -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;

9
src/lib/elementary/efl_ui_item.eo
View File

@ -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;

14
src/lib/elementary/efl_ui_list.eo
View File

@ -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;

6
src/lib/elementary/efl_ui_list_default_item.eo
View File

@ -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 {