jpeg pushed a commit to branch master.
http://git.enlightenment.org/core/efl.git/commit/?id=966df3130aa84b837e8cd3ab3fc954eb0927cf74
commit 966df3130aa84b837e8cd3ab3fc954eb0927cf74
Author: Jean-Philippe Andre <jp.an...@samsung.com>
Date: Fri Apr 21 14:24:45 2017 +0900
focus: Review EO file and adjust doc a bit
I was reading it to understand this new focus system. So I also
made some cosmetic changes here and there in the file: wrap, fix
a few typos, add missing docs. I'm not pretending that the doc
is perfect now. This really was just a personal review.
---
src/lib/elementary/efl_ui_focus_manager.eo | 151 +++++++++++++++----------
src/lib/elementary/efl_ui_focus_manager_sub.eo | 25 ++--
src/lib/elementary/efl_ui_focus_object.eo | 20 ++--
src/lib/elementary/efl_ui_focus_user.eo | 29 ++---
4 files changed, 137 insertions(+), 88 deletions(-)
diff --git a/src/lib/elementary/efl_ui_focus_manager.eo
b/src/lib/elementary/efl_ui_focus_manager.eo
index 4c5f0fb..1fb4f65 100644
--- a/src/lib/elementary/efl_ui_focus_manager.eo
+++ b/src/lib/elementary/efl_ui_focus_manager.eo
@@ -1,15 +1,23 @@
enum Efl.Ui.Focus.Direction {
- [[Those values are desribing a direction from the position of view from
one item]]
- right = 0, [[Coorinate-wise the next element on the right hand side ]]
- left = 1, [[Coorinate-wise the next element on the left hand side ]]
- down = 2, [[Coorinate-wise the next element on the down hand side ]]
- up = 3, [[Coorinate-wise the next element on the up hand side ]]
+ [[Those values are describing a direction from the position of view from
+ one item.
+
+ @since 1.20
+ ]]
+ right = 0, [[Coordinate-wise the next element on the right-hand side]]
+ left = 1, [[Coordinate-wise the next element on the left-hand side]]
+ down = 2, [[Coordinate-wise the next element downward]]
+ up = 3, [[Coorinate-wise the next element upwards]]
next = 4, [[Logically-wise the next item in the logical tree]]
prev = 5, [[Logically-wise the prev item in the logical tree]]
- last = 6
+ last = 6 [[Last value for this enum, do not use]]
}
-struct Efl.Ui.Focus.Relations{
+struct Efl.Ui.Focus.Relations {
+ [[Structure holding the graph of relations between focussable objects.
+
+ @since 1.20
+ ]]
right : list<Efl.Ui.Focus.Object>;
left : list<Efl.Ui.Focus.Object>;
top : list<Efl.Ui.Focus.Object>;
@@ -24,11 +32,15 @@ struct Efl.Ui.Focus.Relations{
class Efl.Ui.Focus.Manager (Efl.Object) {
[[Calculates the directions of Efl.Ui.Focus.Direction
- Each registered item will get a other registered object into each
direction, you can get those items for the currently focused item if you call
request move
+ Each registered item will get a other registered object into each
+ direction, you can get those items for the currently focused item if
+ you call request move.
+
+ @since 1.20
]]
methods {
move {
- [[Move the focus into the given direction
+ [[Move the focus into the given direction.
This call flushes all changes.
This means all changes between the last flush and now are
computed
@@ -39,7 +51,9 @@ class Efl.Ui.Focus.Manager (Efl.Object) {
return : Efl.Ui.Focus.Object; [[The element which is now focused]]
}
request_move {
- [[Returns the object which would be the next object to focus in
the given direction]]
+ [[Returns the object which would be the next object to focus in the
+ given direction.
+ ]]
params {
direction : Efl.Ui.Focus.Direction;
}
@@ -48,102 +62,117 @@ class Efl.Ui.Focus.Manager (Efl.Object) {
register {
[[Register a new item in the graph.
- The parent has to be none null, it will be used as the parent in
the logical tree.
- The redirect argument will be set as redirect property on that
manager, once child gets focused.
+ $parent can not be $null, it will be used as the parent in the
+ logical tree.
+ $redirect will be set as redirect property on that manager, once
+ $child gets focused.
]]
params {
child : Efl.Ui.Focus.Object @nonull; [[The object to register]]
- parent : Efl.Ui.Focus.Object @nonull; [[The parent to use in
the logical tree]]
- redirect : Efl.Ui.Focus.Manager; [[The redirect manager to set
once this child is focused can be NULL for no redirect]]
+ parent : Efl.Ui.Focus.Object @nonull; [[The parent to use in
+ the logical tree]]
+ redirect : Efl.Ui.Focus.Manager; [[The redirect manager to set
+ once this child is focused can be NULL for no redirect]]
}
- return : bool; [[$true if it was successfull $false if not]]
+ return : bool; [[$true if successful, $false otherwise]]
}
register_logical {
[[Register a new item just for the logical parent.
- The item can never get focus, it just help to build a tree out
of the items who are getting focus.
+ The item can never get focus, it just helps to build a tree out
+ of the items that are getting focus.
]]
params {
- child : Efl.Ui.Focus.Object @nonull;
- parent : Efl.Ui.Focus.Object @nonull;
- redirect : Efl.Ui.Focus.Manager; [[The redirect manager to set
once this child is focused can be NULL for no redirect]]
+ child : Efl.Ui.Focus.Object @nonull; [[The object to register]]
+ parent : Efl.Ui.Focus.Object @nonull; [[The parent to use in
+ the logical tree]]
+ redirect : Efl.Ui.Focus.Manager; [[The redirect manager to set
+ once this child is focused can be $null for no redirect]]
}
- return : bool; [[$true if it was successfull $false if not]]
+ return : bool; [[$true if successful, $false otherwise]]
}
-
update_redirect {
- [[Set a new redirect object for the given child
+ [[Set a new redirect object for the given child.
- Once the child is focused the redirect manager will be set in the
redirect property.
- Set to $null if nothing should happen
+ Once $child is focused the redirect manager will be set
+ in the redirect property. Set to $null if nothing should happen.
]]
params {
- child : Efl.Ui.Focus.Object @nonull;
- redirect : Efl.Ui.Focus.Manager; [[Once $child got focused
this element will be set as redirect]]
+ child : Efl.Ui.Focus.Object @nonull; [[The child to update]]
+ redirect : Efl.Ui.Focus.Manager; [[Once $child got focused this
+ element will be set as redirect]]
}
- return : bool;
+ return : bool; [[$true if successful, $false otherwise]]
}
update_parent {
- [[Set a new logical parent for the given child]]
+ [[Set a new logical parent for the given child.]]
params {
child : Efl.Ui.Focus.Object @nonull; [[The child to update]]
- parent : Efl.Ui.Focus.Object @nonull; [[The parent which now
will be the logical parent of child]]
+ parent : Efl.Ui.Focus.Object @nonull; [[The parent which now
+ will be the logical parent of child]]
}
- return : bool;
+ return : bool; [[$true if successful, $false otherwise]]
}
update_children {
- [[Give the list of children a different order]]
+ [[Give the list of children a different order.]]
params {
parent : Efl.Ui.Focus.Object @nonull; [[the parent to update]]
children : list<Efl.Ui.Focus.Object>; [[the list with the new
order]]
}
- return : bool;
+ return : bool; [[$true if successful, $false otherwise]]
}
update_order {
- [[Give the given order to the parent's child. Children from the
list which are no real children are ignored]]
+ [[Give the given order to the parent's child.
+
+ Children from the list which are no real children are ignored.
+ ]]
params {
parent : Efl.Ui.Focus.Object @nonull; [[the parent to update]]
children : list<Efl.Ui.Focus.Object>; [[the order of items]]
}
}
unregister {
- [[unregister the given item from the graph]]
+ [[Unregister the given item from the focus graph.]]
params {
- child : Efl.Ui.Focus.Object;
+ child : Efl.Ui.Focus.Object; [[The child to unregister.]]
}
}
focus {
[[Make the given object the currently focused object in this
manager.
The object has to be part of this manager object.
- If you want to focus something in the redirect manager, just
call the function on the redirect manager]]
- params {
- focus : Efl.Ui.Focus.Object @nonull;
- }
+ If you want to focus something in the redirect manager, just call
+ the function on the redirect manager.
+ ]]
+ params {
+ focus : Efl.Ui.Focus.Object @nonull; [[The object to be
focused.]]
+ }
}
focused {
- [[Return the current focused element of this manager]]
- return : Efl.Ui.Focus.Object;
+ [[Return the currently focused element of this manager.]]
+ return : Efl.Ui.Focus.Object; [[The object that has focus.]]
}
@property redirect {
[[Add a another manager to serve the move requests.
- If this value is set all move requests are redirected to this
manager object.
- Set it to $null once nothing should be redirected anymore.]]
+ If this value is set, all move requests are redirected to this
+ manager object. Set it to $null once nothing should be redirected
+ anymore.
+ ]]
values {
- redirect : Efl.Ui.Focus.Manager;
+ redirect : Efl.Ui.Focus.Manager; [[The redirect manager.]]
}
}
@property border_elements {
- [[The list of elements which are at the border of the graph
- This means one of the relations right,left or down,up are not
set.
+ [[The list of elements which are at the border of the graph.
- This call flushes all changes. see @Efl.Ui.Focus.Manager.move
+ This means one of the relations right,left or down,up are not
set.
+ This call flushes all changes. See @Efl.Ui.Focus.Manager.move
]]
- get {
- }
+ get {}
values {
- border_elements : iterator<Efl.Ui.Focus.Object>;
+ border_elements : iterator<Efl.Ui.Focus.Object>; [[An iterator
+ over the border objects.]]
}
}
@property root {
@@ -152,19 +181,20 @@ class Efl.Ui.Focus.Manager (Efl.Object) {
This property can only be set once.
]]
values {
- root : Efl.Ui.Focus.Object @nonull; [[Will be registered into
this manager object]]
+ root : Efl.Ui.Focus.Object @nonull; [[Will be registered into
+ this manager object.]]
}
}
fetch {
- [[This will fetch the data from a registered node
+ [[This will fetch the data from a registered node.
Be aware this function will trigger all dirty nodes to be
computed
]]
params {
- child : Efl.Ui.Focus.Object;
+ child : Efl.Ui.Focus.Object; [[The child object to inspect.]]
}
-
- return : own(ptr(Efl.Ui.Focus.Relations));
+ return : own(ptr(Efl.Ui.Focus.Relations)); [[The list of relations
+ starting from $child.]]
}
logical_end {
return : Efl.Ui.Focus.Object;
@@ -179,9 +209,12 @@ class Efl.Ui.Focus.Manager (Efl.Object) {
Efl.Object.destructor;
}
events {
- redirect,changed : Efl.Ui.Focus.Manager; [[Emitted when the redirect
object has changed, the old manager is passed as event info]]
+ redirect,changed : Efl.Ui.Focus.Manager; [[Emitted when the redirect
+ object has changed, the old manager is passed as event info]]
pre,flush; [[Emitted once the graph calculationg will be performed]]
- coords,dirty; [[Emitted once the graph is dirty, this means there are
potential changes in border_elements you want to know about]]
- focused : Efl.Ui.Focus.Object; [[Emitted if the manager has focused a
object]]
+ coords,dirty; [[Emitted once the graph is dirty, this means there are
+ potential changes in border_elements you want to know about]]
+ focused : Efl.Ui.Focus.Object; [[Emitted if the manager has focused an
+ object]]
}
-}
\ No newline at end of file
+}
diff --git a/src/lib/elementary/efl_ui_focus_manager_sub.eo
b/src/lib/elementary/efl_ui_focus_manager_sub.eo
index 9496d0e..0a1f481 100644
--- a/src/lib/elementary/efl_ui_focus_manager_sub.eo
+++ b/src/lib/elementary/efl_ui_focus_manager_sub.eo
@@ -1,22 +1,29 @@
class Efl.Ui.Focus.Manager.Sub (Efl.Ui.Focus.Manager, Efl.Object)
{
- [[A abstract class to have a sub manager
+ [[An abstract class to have a sub manager.
- This submanager will register its border elements on the parent manager.
The parent manager is found with the Efl.Ui.Focus.User interface of the eo
parent.
+ This sub manager will register its border elements on the parent manager.
+ The parent manager is found with the @Efl.Ui.Focus.User interface of the
+ @Efl.Object.parent.
- Each submanager also has to be a focus object, the object itself will be
registered into the parent manager. It will be used as logical parent while
registering the border elements.
+ Each sub manager also has to be a focus object, the object itself will be
+ registered into the parent manager. It will be used as logical parent
+ while registering the border elements.
- You can filter the border elements by overriding the border_elements
property of the manager.
+ You can filter the border elements by overriding the property
+ @Efl.Ui.Focus.Manager.border_elements.
- This class is only working as composite object to a Efl.Ui.Focus.User
and Efl.Ui.Focus.Object.
+ This class is only working as composite object to a @Efl.Ui.Focus.User
+ and @Efl.Ui.Focus.Object.
- The object itself does redirect the managers events to the object where
this object is attached
+ The object itself redirects the manager's events to the object where this
+ object is attached.
+
+ @since 1.20
]]
- methods {
- }
implements {
Efl.Object.constructor;
Efl.Object.destructor;
Efl.Object.parent { set; }
}
-}
\ No newline at end of file
+}
diff --git a/src/lib/elementary/efl_ui_focus_object.eo
b/src/lib/elementary/efl_ui_focus_object.eo
index 362ec3e..144da44 100644
--- a/src/lib/elementary/efl_ui_focus_object.eo
+++ b/src/lib/elementary/efl_ui_focus_object.eo
@@ -2,20 +2,26 @@ import eina_types;
mixin Efl.Ui.Focus.Object
{
- [[Functions of focusable objects]]
+ [[Functions of focusable objects.
+
+ @since 1.20
+ ]]
methods {
geometry_get {
- [[The geometry which should be used to calculate the relations to
others]]
+ [[The geometry to use to calculate the relations to other
objects.]]
params {
- @out rect : Eina.Rectangle; [[the geometry to use]]
+ @out rect : Eina.Rectangle; [[The geometry to use.]]
}
}
@property focus {
- [[This gets called by the manager and should never be called by
someone else
+ [[This gets called by the manager and should never be called by
+ someone else.
- It can be used by a implementation of a focus object to adapt to
changes which are needed.
+ It can be used by an implementation of a focus object to adapt to
+ changes that are needed.
- The function is emitting the focus state events, if focus is
different to the state before.
+ The function is emitting the focus state events, if focus is
+ different to the previous state.
]]
values {
focus : bool; [[The state in which the object should be put]]
@@ -29,4 +35,4 @@ mixin Efl.Ui.Focus.Object
events {
focus,changed : bool; [[Emitted if the focus state has changed]]
}
-}
\ No newline at end of file
+}
diff --git a/src/lib/elementary/efl_ui_focus_user.eo
b/src/lib/elementary/efl_ui_focus_user.eo
index da7389b..c78a104 100644
--- a/src/lib/elementary/efl_ui_focus_user.eo
+++ b/src/lib/elementary/efl_ui_focus_user.eo
@@ -1,27 +1,30 @@
interface Efl.Ui.Focus.User {
- [[Interface which is used to handle the manager of a user]]
+ [[Interface which is used to handle the manager of a user.
+
+ @since 1.20
+ ]]
methods {
@property manager {
- [[describes which manager is used to register or should be used to
register this user]]
- get {
-
- }
+ [[Describes which manager is used to register or should be used
+ to register this user.
+ ]]
+ get {}
values {
manager : Efl.Ui.Focus.Manager; [[The manager object]]
}
}
@property parent {
- [[Describes which logical parent is used by this object]]
- get {
-
- }
+ [[Describes which logical parent is used by this object.]]
+ get {}
values {
- logical_parent : Efl.Ui.Focus.Object;
+ logical_parent : Efl.Ui.Focus.Object; [[The focus parent.]]
}
}
}
events {
- manager,changed : Efl.Ui.Focus.Manager; [[emitted if a new manager is
the parent for this one]]
- logical,changed : Efl.Ui.Focus.Object; [[emitted if a new
logical_parent should be used]]
+ manager,changed: Efl.Ui.Focus.Manager; [[Emitted when a new manager is
+ the parent for this object.]]
+ logical,changed: Efl.Ui.Focus.Object; [[Emitted when a new logical
+ parent should be used.]]
}
-}
\ No newline at end of file
+}
--
