forked from enlightenment/efl
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:
parent
57a960d26b
commit
966df3130a
|
@ -1,15 +1,23 @@
|
||||||
enum Efl.Ui.Focus.Direction {
|
enum Efl.Ui.Focus.Direction {
|
||||||
[[Those values are desribing a direction from the position of view from one item]]
|
[[Those values are describing a direction from the position of view from
|
||||||
right = 0, [[Coorinate-wise the next element on the right hand side ]]
|
one item.
|
||||||
left = 1, [[Coorinate-wise the next element on the left hand side ]]
|
|
||||||
down = 2, [[Coorinate-wise the next element on the down hand side ]]
|
@since 1.20
|
||||||
up = 3, [[Coorinate-wise the next element on the up hand side ]]
|
]]
|
||||||
|
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]]
|
next = 4, [[Logically-wise the next item in the logical tree]]
|
||||||
prev = 5, [[Logically-wise the prev 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>;
|
right : list<Efl.Ui.Focus.Object>;
|
||||||
left : list<Efl.Ui.Focus.Object>;
|
left : list<Efl.Ui.Focus.Object>;
|
||||||
top : 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) {
|
class Efl.Ui.Focus.Manager (Efl.Object) {
|
||||||
[[Calculates the directions of Efl.Ui.Focus.Direction
|
[[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 {
|
methods {
|
||||||
move {
|
move {
|
||||||
[[Move the focus into the given direction
|
[[Move the focus into the given direction.
|
||||||
|
|
||||||
This call flushes all changes.
|
This call flushes all changes.
|
||||||
This means all changes between the last flush and now are computed
|
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]]
|
return : Efl.Ui.Focus.Object; [[The element which is now focused]]
|
||||||
}
|
}
|
||||||
request_move {
|
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 {
|
params {
|
||||||
direction : Efl.Ui.Focus.Direction;
|
direction : Efl.Ui.Focus.Direction;
|
||||||
}
|
}
|
||||||
|
@ -48,102 +62,117 @@ class Efl.Ui.Focus.Manager (Efl.Object) {
|
||||||
register {
|
register {
|
||||||
[[Register a new item in the graph.
|
[[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.
|
$parent can not be $null, it will be used as the parent in the
|
||||||
The redirect argument will be set as redirect property on that manager, once child gets focused.
|
logical tree.
|
||||||
|
$redirect will be set as redirect property on that manager, once
|
||||||
|
$child gets focused.
|
||||||
]]
|
]]
|
||||||
params {
|
params {
|
||||||
child : Efl.Ui.Focus.Object @nonull; [[The object to register]]
|
child : Efl.Ui.Focus.Object @nonull; [[The object to register]]
|
||||||
parent : Efl.Ui.Focus.Object @nonull; [[The parent to use in the logical tree]]
|
parent : Efl.Ui.Focus.Object @nonull; [[The parent to use in
|
||||||
redirect : Efl.Ui.Focus.Manager; [[The redirect manager to set once this child is focused can be NULL for no redirect]]
|
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_logical {
|
||||||
[[Register a new item just for the logical parent.
|
[[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 {
|
params {
|
||||||
child : Efl.Ui.Focus.Object @nonull;
|
child : Efl.Ui.Focus.Object @nonull; [[The object to register]]
|
||||||
parent : Efl.Ui.Focus.Object @nonull;
|
parent : Efl.Ui.Focus.Object @nonull; [[The parent to use in
|
||||||
redirect : Efl.Ui.Focus.Manager; [[The redirect manager to set once this child is focused can be NULL for no redirect]]
|
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 {
|
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.
|
Once $child is focused the redirect manager will be set
|
||||||
Set to $null if nothing should happen
|
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 {
|
params {
|
||||||
child : Efl.Ui.Focus.Object @nonull; [[The child to update]]
|
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 {
|
update_children {
|
||||||
[[Give the list of children a different order]]
|
[[Give the list of children a different order.]]
|
||||||
params {
|
params {
|
||||||
parent : Efl.Ui.Focus.Object @nonull; [[the parent to update]]
|
parent : Efl.Ui.Focus.Object @nonull; [[the parent to update]]
|
||||||
children : list<Efl.Ui.Focus.Object>; [[the list with the new order]]
|
children : list<Efl.Ui.Focus.Object>; [[the list with the new order]]
|
||||||
}
|
}
|
||||||
return : bool;
|
return : bool; [[$true if successful, $false otherwise]]
|
||||||
}
|
}
|
||||||
update_order {
|
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 {
|
params {
|
||||||
parent : Efl.Ui.Focus.Object @nonull; [[the parent to update]]
|
parent : Efl.Ui.Focus.Object @nonull; [[the parent to update]]
|
||||||
children : list<Efl.Ui.Focus.Object>; [[the order of items]]
|
children : list<Efl.Ui.Focus.Object>; [[the order of items]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
unregister {
|
unregister {
|
||||||
[[unregister the given item from the graph]]
|
[[Unregister the given item from the focus graph.]]
|
||||||
params {
|
params {
|
||||||
child : Efl.Ui.Focus.Object;
|
child : Efl.Ui.Focus.Object; [[The child to unregister.]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
focus {
|
focus {
|
||||||
[[Make the given object the currently focused object in this manager.
|
[[Make the given object the currently focused object in this manager.
|
||||||
|
|
||||||
The object has to be part of this manager object.
|
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]]
|
If you want to focus something in the redirect manager, just call
|
||||||
|
the function on the redirect manager.
|
||||||
|
]]
|
||||||
params {
|
params {
|
||||||
focus : Efl.Ui.Focus.Object @nonull;
|
focus : Efl.Ui.Focus.Object @nonull; [[The object to be focused.]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
focused {
|
focused {
|
||||||
[[Return the current focused element of this manager]]
|
[[Return the currently focused element of this manager.]]
|
||||||
return : Efl.Ui.Focus.Object;
|
return : Efl.Ui.Focus.Object; [[The object that has focus.]]
|
||||||
}
|
}
|
||||||
@property redirect {
|
@property redirect {
|
||||||
[[Add a another manager to serve the move requests.
|
[[Add a another manager to serve the move requests.
|
||||||
|
|
||||||
If this value is set all move requests are redirected to this manager object.
|
If this value is set, all move requests are redirected to this
|
||||||
Set it to $null once nothing should be redirected anymore.]]
|
manager object. Set it to $null once nothing should be redirected
|
||||||
|
anymore.
|
||||||
|
]]
|
||||||
values {
|
values {
|
||||||
redirect : Efl.Ui.Focus.Manager;
|
redirect : Efl.Ui.Focus.Manager; [[The redirect manager.]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@property border_elements {
|
@property border_elements {
|
||||||
[[The list of elements which are at the border of the graph
|
[[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.
|
|
||||||
|
|
||||||
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 {
|
values {
|
||||||
border_elements : iterator<Efl.Ui.Focus.Object>;
|
border_elements : iterator<Efl.Ui.Focus.Object>; [[An iterator
|
||||||
|
over the border objects.]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@property root {
|
@property root {
|
||||||
|
@ -152,19 +181,20 @@ class Efl.Ui.Focus.Manager (Efl.Object) {
|
||||||
This property can only be set once.
|
This property can only be set once.
|
||||||
]]
|
]]
|
||||||
values {
|
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 {
|
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
|
Be aware this function will trigger all dirty nodes to be computed
|
||||||
]]
|
]]
|
||||||
params {
|
params {
|
||||||
child : Efl.Ui.Focus.Object;
|
child : Efl.Ui.Focus.Object; [[The child object to inspect.]]
|
||||||
}
|
}
|
||||||
|
return : own(ptr(Efl.Ui.Focus.Relations)); [[The list of relations
|
||||||
return : own(ptr(Efl.Ui.Focus.Relations));
|
starting from $child.]]
|
||||||
}
|
}
|
||||||
logical_end {
|
logical_end {
|
||||||
return : Efl.Ui.Focus.Object;
|
return : Efl.Ui.Focus.Object;
|
||||||
|
@ -179,9 +209,12 @@ class Efl.Ui.Focus.Manager (Efl.Object) {
|
||||||
Efl.Object.destructor;
|
Efl.Object.destructor;
|
||||||
}
|
}
|
||||||
events {
|
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]]
|
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]]
|
coords,dirty; [[Emitted once the graph is dirty, this means there are
|
||||||
focused : Efl.Ui.Focus.Object; [[Emitted if the manager has focused a object]]
|
potential changes in border_elements you want to know about]]
|
||||||
|
focused : Efl.Ui.Focus.Object; [[Emitted if the manager has focused an
|
||||||
|
object]]
|
||||||
}
|
}
|
||||||
}
|
}
|
|
@ -1,19 +1,26 @@
|
||||||
class Efl.Ui.Focus.Manager.Sub (Efl.Ui.Focus.Manager, Efl.Object)
|
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 {
|
implements {
|
||||||
Efl.Object.constructor;
|
Efl.Object.constructor;
|
||||||
Efl.Object.destructor;
|
Efl.Object.destructor;
|
||||||
|
|
|
@ -2,20 +2,26 @@ import eina_types;
|
||||||
|
|
||||||
mixin Efl.Ui.Focus.Object
|
mixin Efl.Ui.Focus.Object
|
||||||
{
|
{
|
||||||
[[Functions of focusable objects]]
|
[[Functions of focusable objects.
|
||||||
|
|
||||||
|
@since 1.20
|
||||||
|
]]
|
||||||
methods {
|
methods {
|
||||||
geometry_get {
|
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 {
|
params {
|
||||||
@out rect : Eina.Rectangle; [[the geometry to use]]
|
@out rect : Eina.Rectangle; [[The geometry to use.]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@property focus {
|
@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 {
|
values {
|
||||||
focus : bool; [[The state in which the object should be put]]
|
focus : bool; [[The state in which the object should be put]]
|
||||||
|
|
|
@ -1,27 +1,30 @@
|
||||||
interface Efl.Ui.Focus.User {
|
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 {
|
methods {
|
||||||
@property manager {
|
@property manager {
|
||||||
[[describes which manager is used to register or should be used to register this user]]
|
[[Describes which manager is used to register or should be used
|
||||||
get {
|
to register this user.
|
||||||
|
]]
|
||||||
}
|
get {}
|
||||||
values {
|
values {
|
||||||
manager : Efl.Ui.Focus.Manager; [[The manager object]]
|
manager : Efl.Ui.Focus.Manager; [[The manager object]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@property parent {
|
@property parent {
|
||||||
[[Describes which logical parent is used by this object]]
|
[[Describes which logical parent is used by this object.]]
|
||||||
get {
|
get {}
|
||||||
|
|
||||||
}
|
|
||||||
values {
|
values {
|
||||||
logical_parent : Efl.Ui.Focus.Object;
|
logical_parent : Efl.Ui.Focus.Object; [[The focus parent.]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
events {
|
events {
|
||||||
manager,changed : Efl.Ui.Focus.Manager; [[emitted if a new manager is the parent for this one]]
|
manager,changed: Efl.Ui.Focus.Manager; [[Emitted when a new manager is
|
||||||
logical,changed : Efl.Ui.Focus.Object; [[emitted if a new logical_parent should be used]]
|
the parent for this object.]]
|
||||||
|
logical,changed: Efl.Ui.Focus.Object; [[Emitted when a new logical
|
||||||
|
parent should be used.]]
|
||||||
}
|
}
|
||||||
}
|
}
|
Loading…
Reference in New Issue