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

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.
This commit is contained in:
Jean-Philippe Andre 2017-04-21 14:24:45 +09:00
parent 57a960d26b
commit 966df3130a
4 changed files with 141 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

159
src/lib/elementary/efl_ui_focus_manager.eo
View File

@ -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]]
}
return : bool;
}
update_parent {
[[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]]
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.]]
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]]
}
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]]
}
}
}

25
src/lib/elementary/efl_ui_focus_manager_sub.eo
View File

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

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

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

29
src/lib/elementary/efl_ui_focus_user.eo
View File

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