enlightenment/efl
enlightenment
/
efl
8
7
Fork 14
Code Issues 13 Pull Requests 3 Projects Releases Wiki Activity

docs: Update focus documentation 

Lots of improvements to the focus-related classes.

Reviewed-by: Marcel Hollerbach <mail@marcel-hollerbach.de>
Differential Revision: https://phab.enlightenment.org/D9828
This commit is contained in:
Xavi Artigas 2019-09-03 15:56:23 +00:00 committed by Marcel Hollerbach
parent a26efaeb57
commit a2f846bffc
11 changed files with 87 additions and 75 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
src/lib/elementary/efl_ui_collection_focus_manager.eo
View File

@ -1,5 +1,5 @@
class @beta Efl.Ui.Collection_Focus_Manager extends Efl.Ui.Focus.Manager_Calc {
[[Internal class which implements collection specific behaviour, cannot be used outside of collection]]
[[Internal class which implements collection specific behaviour, cannot be used outside of @Efl.Ui.Collection.]]
implements {
Efl.Ui.Focus.Manager.manager_focus { set; }
Efl.Ui.Focus.Manager.request_move;

15
src/lib/elementary/efl_ui_focus_composition_adapter.eo
View File

@ -1,23 +1,28 @@
class @beta Efl.Ui.Focus.Composition_Adapter extends Efl.Object implements Efl.Ui.Focus.Object
{
[[EFL UI Focus Composition Adapter class]]
[[This class allows an @Efl.Canvas.Object to receive focus as if they were @Efl.Ui.Widget.
Instantiate this class and manually set its properties to the appropriate objects.
]]
methods {
@property canvas_object {
[[Canvas Object Property]]
[[The canvas object that needs to receive focus.]]
values {
v : Efl.Canvas.Object; [[EFL canvas object]]
v : Efl.Canvas.Object; [[The canvas object.]]
}
}
@property focus_manager_object {
[[The focus manager handling the focus for the @.canvas_object.]]
set {}
values {
v : Efl.Ui.Focus.Manager;
v : Efl.Ui.Focus.Manager; [[The focus manager.]]
}
}
@property focus_manager_parent {
[[The focus parent for the @.canvas_object.]]
set {}
values {
parent : Efl.Ui.Focus.Object;
parent : Efl.Ui.Focus.Object; [[The focus parent.]]
}
}
}

18
src/lib/elementary/efl_ui_focus_layer.eo
View File

@ -1,24 +1,24 @@
mixin @beta Efl.Ui.Focus.Layer requires Efl.Ui.Widget extends Efl.Ui.Widget_Focus_Manager {
[[This defines the inheriting widget as focus layer.
[[This defines the widget as a focus layer.
A focus layer is the uppermost one which receives input and handles all focus related events for as long as
it exists and is visible. It's NOT possible to escape this layer with focus movement.
A focus layer is the uppermost widget which receives input and handles all focus related events for as long as
it exists and is visible. It's not possible to escape this layer with focus movements.
Once the object is hidden or destroyed the focus will go back to the main window, where it was before.
]]
methods {
@property enable @protected {
[[Enable property]]
[[Whether the focus layer is enabled.
This can be handled automatically through @Efl.Gfx.Entity.visible and @.behaviour.]]
values {
v : bool; [[$true to set enable the layer $false to disable it]]
v : bool; [[$true to set enable.]]
}
}
@property behaviour @protected {
[[Constructor for setting the behaviour of the layer]]
[[Sets the behaviour of the focus layer.]]
values {
enable_on_visible : bool; [[$true means layer will set itself once the inheriting widget becomes visible,
$false means the layer isn't enabled automatically]]
cycle : bool; [[If $true the focus will cycle in the layer, if $false]]
enable_on_visible : bool; [[$true means layer will enable itself once the widget becomes visible]]
cycle : bool; [[If $true the focus will cycle (from last object to first, and vice versa) in the layer.]]
}
}
}

80
src/lib/elementary/efl_ui_focus_manager_calc.eo
View File

@ -1,81 +1,77 @@
class @beta Efl.Ui.Focus.Manager_Calc extends Efl.Object implements Efl.Ui.Focus.Manager {
[[Calculates the directions of Efl.Ui.Focus.Direction
[[Calculates the elements present in each @Efl.Ui.Focus.Direction.
Each registered item will get an other registered object in each
direction. You can get items for the currently focused item if
you call request move.
Each registered item will get a target item in each direction.
You can get the target items for the currently focused item by
calling @Efl.Ui.Focus.Manager.request_move.
]]
methods {
register {
[[Register a new item in the graph.
[[Registers a new item in the graph.
$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.
$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; [[The object to register]]
parent : Efl.Ui.Focus.Object; [[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]]
child : Efl.Ui.Focus.Object; [[The object to register.]]
parent : Efl.Ui.Focus.Object; [[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 successful, $false otherwise]]
return : bool; [[$true if successful, $false otherwise.]]
}
register_logical {
[[Register a new item only for the logical parent.
[[Registers a new logical item in the graph.
The item can never get focus, it just helps to build a tree out
of the items that are.
The item can never get focus, it just helps to build the tree.
Compare to @.register.
]]
params {
child : Efl.Ui.Focus.Object; [[The object to register]]
parent : Efl.Ui.Focus.Object; [[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]]
child : Efl.Ui.Focus.Object; [[The object to register.]]
parent : Efl.Ui.Focus.Object; [[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 successful, $false otherwise]]
return : bool; [[$true if successful, $false otherwise.]]
}
update_redirect {
[[Set a new redirect object for the given child.
[[Sets a new redirect object for the given child.
Once $child is focused the redirect manager will be set
in the redirect property. Set redirect to $null if nothing should happen.
in the redirect property. Set redirect to $NULL if nothing should happen.
]]
params {
child : Efl.Ui.Focus.Object; [[The child to update]]
child : Efl.Ui.Focus.Object; [[The child to update.]]
redirect : Efl.Ui.Focus.Manager; [[Once $child is focused this
element will be set as redirect]]
element will be set as redirect.]]
}
return : bool; [[$true if successful, $false otherwise]]
return : bool; [[$true if successful, $false otherwise.]]
}
update_parent {
[[Set a new logical parent for the given child.]]
[[Sets a new logical parent for the given child.]]
params {
child : Efl.Ui.Focus.Object; [[The child to update]]
parent : Efl.Ui.Focus.Object; [[The parent which now
will be the logical parent of child]]
child : Efl.Ui.Focus.Object; [[The child to update.]]
parent : Efl.Ui.Focus.Object; [[The parent which now will be the logical parent of child.]]
}
return : bool; [[$true if successful, $false otherwise]]
return : bool; [[$true if successful, $false otherwise.]]
}
update_children {
[[Give the list of children a different order.]]
[[Sets the list of children to a different order.]]
params {
parent : Efl.Ui.Focus.Object; [[the parent to update]]
children : list<Efl.Ui.Focus.Object> @owned; [[the list with the new order]]
parent : Efl.Ui.Focus.Object; [[The parent to update.]]
children : list<Efl.Ui.Focus.Object> @owned; [[The list of children with the new order.]]
}
return : bool; [[$true if successful, $false otherwise]]
return : bool; [[$true if successful, $false otherwise.]]
}
update_order {
[[Give the given order to the parent's child.
[[Sets the list of children to a different order.
Children from the list which are not true children are ignored.
Objects in the list which are not children of $parent are ignored.
Compare to @.update_children.
]]
params {
parent : Efl.Ui.Focus.Object; [[the parent to update]]
children : list<Efl.Ui.Focus.Object> @owned; [[the order of items]]
parent : Efl.Ui.Focus.Object; [[The parent to update.]]
children : list<Efl.Ui.Focus.Object> @owned; [[The list of objects with the new order.]]
}
}
unregister {

4
src/lib/elementary/efl_ui_focus_manager_root_focus.eo
View File

@ -2,8 +2,8 @@ class @beta Efl.Ui.Focus.Manager_Root_Focus extends Efl.Ui.Focus.Manager_Calc {
[[This class ensures that the root is at least focusable, if nothing else is focusable.]]
methods {
@property canvas_object {
[[The default replacement object for the case that there is no focusable object inside the manager is the root
object. However, you can change this by setting this value to something else.
[[The default replacement object to use when there is no focusable object inside the manager.
You can change this object by setting this value to something else.
$null means that the same value as @Efl.Ui.Focus.Manager.root will be used.
]]
values {

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

@ -1,6 +1,6 @@
mixin @beta Efl.Ui.Focus.Manager_Sub requires Efl.Object extends Efl.Ui.Focus.Manager
{
[[A class that automatically registers its border elements in the parent manager
[[A class that automatically registers its border elements in the parent manager.
This sub manager will register its border elements on the parent manager.
The parent manager is found with the @Efl.Ui.Focus.Object interface of the

2
src/lib/elementary/efl_ui_focus_manager_window_root.eo
View File

@ -2,7 +2,7 @@ interface Efl.Ui.Focus.Manager_Window_Root {
[[An interface to indicate the end of a focus chain.
Focus managers are ensuring that if they give focus to something, that is registered in the upper focus manager.
The most upper focus manager does not need to do that, and can implement this interface to indicate that.
The uppermost focus manager does not need to do that, and can implement this interface to indicate so.
@since 1.22
]]

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

@ -1,5 +1,9 @@
class @beta Efl.Ui.Focus.Parent_Provider_Standard extends Efl.Object implements Efl.Ui.Focus.Parent_Provider {
[[EFL UI Focus Parent Provider Standard Class]]
[[EFL UI Focus Parent Provider Standard Class.
This is the default implementation for the @Efl.Ui.Focus.Parent_Provider interface. It simply uses
the widget's parent as the focus parent.
]]
implements {
Efl.Ui.Focus.Parent_Provider.find_logical_parent;
}

22
src/lib/elementary/efl_ui_focus_util.eo
View File

@ -1,24 +1,32 @@
class @beta Efl.Ui.Focus.Util extends Efl.Object {
[[EFL UI Focus Util class]]
[[EFL UI Focus Utility class.
This class contains a series of static methods that simplify common focus management operations.
There's no need to instantiate this class.
]]
methods {
focus @static {
[[Focus helper method]]
[[Sets the focus to the given object.]]
params {
focus_elem : Efl.Ui.Focus.Object; [[Focus element]]
focus_elem : Efl.Ui.Focus.Object; [[Object to receive focus.]]
}
}
active_manager @static {
[[Get the highest manager in the redirect property]]
[[Gets the highest manager in the redirect chain.]]
params {
manager : Efl.Ui.Focus.Manager;
manager : Efl.Ui.Focus.Manager; [[Manager to start looking from.]]
}
return: Efl.Ui.Focus.Manager;
}
direction_complement @static {
[[Returns the complementary (opposite) focus direction.
The defined opposites are Left-Right, Up-Down and Next-Previous.
]]
params {
dir : Efl.Ui.Focus.Direction;
dir : Efl.Ui.Focus.Direction; [[Direction to complement.]]
}
return: Efl.Ui.Focus.Direction;
return: Efl.Ui.Focus.Direction; [[The opposite direction.]]
}
}
}

5
src/lib/elementary/efl_ui_widget_focus_manager.eo
View File

@ -1,13 +1,14 @@
mixin Efl.Ui.Widget_Focus_Manager requires Efl.Ui.Widget extends Efl.Ui.Focus.Manager
{
[[
[[Helper mixin for widgets which also can act as focus managers.
@since 1.22
]]
methods {
focus_manager_create @protected @pure_virtual {
[[If the widget needs a focus manager, this function will be called.
It can be used and overriden to inject your own manager or set
It can be used and overridden to inject your own manager or set
custom options on the focus manager.
]]
params {

6
src/lib/evas/canvas/efl_input_focus.eo
View File

@ -6,11 +6,9 @@ class Efl.Input.Focus extends Efl.Object implements Efl.Input.Event
]]
methods {
@property object {
[[The focused object]]
[[The focused object.]]
values {
object: Efl.Object; [[The focused object.
In case this represents a canvas
focus the object will be $null]]
object: Efl.Object; [[The focused object, or $NULL if the event comes from the canvas.]]
}
}
}