summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorXavi Artigas <xavierartigas@yahoo.es>2019-09-03 15:56:23 +0000
committerMarcel Hollerbach <mail@marcel-hollerbach.de>2019-09-03 18:41:34 +0200
commita2f846bffcecfec7d3d73b0f4994666f5dc930ff (patch)
treefdcc581f929b284395dd2b320a81cd56715c3ea5
parenta26efaeb57f7d2e196d002480952312c20d02267 (diff)
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
-rw-r--r--src/lib/elementary/efl_ui_collection_focus_manager.eo2
-rw-r--r--src/lib/elementary/efl_ui_focus_composition_adapter.eo15
-rw-r--r--src/lib/elementary/efl_ui_focus_layer.eo18
-rw-r--r--src/lib/elementary/efl_ui_focus_manager_calc.eo80
-rw-r--r--src/lib/elementary/efl_ui_focus_manager_root_focus.eo4
-rw-r--r--src/lib/elementary/efl_ui_focus_manager_sub.eo2
-rw-r--r--src/lib/elementary/efl_ui_focus_manager_window_root.eo2
-rw-r--r--src/lib/elementary/efl_ui_focus_parent_provider_standard.eo6
-rw-r--r--src/lib/elementary/efl_ui_focus_util.eo22
-rw-r--r--src/lib/elementary/efl_ui_widget_focus_manager.eo5
-rw-r--r--src/lib/evas/canvas/efl_input_focus.eo6
11 files changed, 87 insertions, 75 deletions
diff --git a/src/lib/elementary/efl_ui_collection_focus_manager.eo b/src/lib/elementary/efl_ui_collection_focus_manager.eo
index e015dea7c9..fb3978c5c0 100644
--- a/src/lib/elementary/efl_ui_collection_focus_manager.eo
+++ b/src/lib/elementary/efl_ui_collection_focus_manager.eo
@@ -1,5 +1,5 @@
1class @beta Efl.Ui.Collection_Focus_Manager extends Efl.Ui.Focus.Manager_Calc { 1class @beta Efl.Ui.Collection_Focus_Manager extends Efl.Ui.Focus.Manager_Calc {
2 [[Internal class which implements collection specific behaviour, cannot be used outside of collection]] 2 [[Internal class which implements collection specific behaviour, cannot be used outside of @Efl.Ui.Collection.]]
3 implements { 3 implements {
4 Efl.Ui.Focus.Manager.manager_focus { set; } 4 Efl.Ui.Focus.Manager.manager_focus { set; }
5 Efl.Ui.Focus.Manager.request_move; 5 Efl.Ui.Focus.Manager.request_move;
diff --git a/src/lib/elementary/efl_ui_focus_composition_adapter.eo b/src/lib/elementary/efl_ui_focus_composition_adapter.eo
index 118f4a3a2a..98d548c89e 100644
--- a/src/lib/elementary/efl_ui_focus_composition_adapter.eo
+++ b/src/lib/elementary/efl_ui_focus_composition_adapter.eo
@@ -1,23 +1,28 @@
1class @beta Efl.Ui.Focus.Composition_Adapter extends Efl.Object implements Efl.Ui.Focus.Object 1class @beta Efl.Ui.Focus.Composition_Adapter extends Efl.Object implements Efl.Ui.Focus.Object
2{ 2{
3 [[EFL UI Focus Composition Adapter class]] 3 [[This class allows an @Efl.Canvas.Object to receive focus as if they were @Efl.Ui.Widget.
4
5 Instantiate this class and manually set its properties to the appropriate objects.
6 ]]
4 methods { 7 methods {
5 @property canvas_object { 8 @property canvas_object {
6 [[Canvas Object Property]] 9 [[The canvas object that needs to receive focus.]]
7 values { 10 values {
8 v : Efl.Canvas.Object; [[EFL canvas object]] 11 v : Efl.Canvas.Object; [[The canvas object.]]
9 } 12 }
10 } 13 }
11 @property focus_manager_object { 14 @property focus_manager_object {
15 [[The focus manager handling the focus for the @.canvas_object.]]
12 set {} 16 set {}
13 values { 17 values {
14 v : Efl.Ui.Focus.Manager; 18 v : Efl.Ui.Focus.Manager; [[The focus manager.]]
15 } 19 }
16 } 20 }
17 @property focus_manager_parent { 21 @property focus_manager_parent {
22 [[The focus parent for the @.canvas_object.]]
18 set {} 23 set {}
19 values { 24 values {
20 parent : Efl.Ui.Focus.Object; 25 parent : Efl.Ui.Focus.Object; [[The focus parent.]]
21 } 26 }
22 } 27 }
23 } 28 }
diff --git a/src/lib/elementary/efl_ui_focus_layer.eo b/src/lib/elementary/efl_ui_focus_layer.eo
index 05d847ad98..3d07102422 100644
--- a/src/lib/elementary/efl_ui_focus_layer.eo
+++ b/src/lib/elementary/efl_ui_focus_layer.eo
@@ -1,24 +1,24 @@
1mixin @beta Efl.Ui.Focus.Layer requires Efl.Ui.Widget extends Efl.Ui.Widget_Focus_Manager { 1mixin @beta Efl.Ui.Focus.Layer requires Efl.Ui.Widget extends Efl.Ui.Widget_Focus_Manager {
2 [[This defines the inheriting widget as focus layer. 2 [[This defines the widget as a focus layer.
3 3
4 A focus layer is the uppermost one which receives input and handles all focus related events for as long as 4 A focus layer is the uppermost widget which receives input and handles all focus related events for as long as
5 it exists and is visible. It's NOT possible to escape this layer with focus movement. 5 it exists and is visible. It's not possible to escape this layer with focus movements.
6 6
7 Once the object is hidden or destroyed the focus will go back to the main window, where it was before. 7 Once the object is hidden or destroyed the focus will go back to the main window, where it was before.
8 ]] 8 ]]
9 methods { 9 methods {
10 @property enable @protected { 10 @property enable @protected {
11 [[Enable property]] 11 [[Whether the focus layer is enabled.
12 This can be handled automatically through @Efl.Gfx.Entity.visible and @.behaviour.]]
12 values { 13 values {
13 v : bool; [[$true to set enable the layer $false to disable it]] 14 v : bool; [[$true to set enable.]]
14 } 15 }
15 } 16 }
16 @property behaviour @protected { 17 @property behaviour @protected {
17 [[Constructor for setting the behaviour of the layer]] 18 [[Sets the behaviour of the focus layer.]]
18 values { 19 values {
19 enable_on_visible : bool; [[$true means layer will set itself once the inheriting widget becomes visible, 20 enable_on_visible : bool; [[$true means layer will enable itself once the widget becomes visible]]
20 $false means the layer isn't enabled automatically]] 21 cycle : bool; [[If $true the focus will cycle (from last object to first, and vice versa) in the layer.]]
21 cycle : bool; [[If $true the focus will cycle in the layer, if $false]]
22 } 22 }
23 } 23 }
24 } 24 }
diff --git a/src/lib/elementary/efl_ui_focus_manager_calc.eo b/src/lib/elementary/efl_ui_focus_manager_calc.eo
index d21b925559..279f6da106 100644
--- a/src/lib/elementary/efl_ui_focus_manager_calc.eo
+++ b/src/lib/elementary/efl_ui_focus_manager_calc.eo
@@ -1,81 +1,77 @@
1class @beta Efl.Ui.Focus.Manager_Calc extends Efl.Object implements Efl.Ui.Focus.Manager { 1class @beta Efl.Ui.Focus.Manager_Calc extends Efl.Object implements Efl.Ui.Focus.Manager {
2 [[Calculates the directions of Efl.Ui.Focus.Direction 2 [[Calculates the elements present in each @Efl.Ui.Focus.Direction.
3 3
4 Each registered item will get an other registered object in each 4 Each registered item will get a target item in each direction.
5 direction. You can get items for the currently focused item if 5 You can get the target items for the currently focused item by
6 you call request move. 6 calling @Efl.Ui.Focus.Manager.request_move.
7 ]] 7 ]]
8 methods { 8 methods {
9 register { 9 register {
10 [[Register a new item in the graph. 10 [[Registers a new item in the graph.
11 11
12 $parent can not be $null, it will be used as the parent in the 12 $parent can not be $null, it will be used as the parent in the logical tree.
13 logical tree. 13 $redirect will be set as redirect property on that manager, once $child gets focused.
14 $redirect will be set as redirect property on that manager, once
15 $child gets focused.
16 ]] 14 ]]
17 params { 15 params {
18 child : Efl.Ui.Focus.Object; [[The object to register]] 16 child : Efl.Ui.Focus.Object; [[The object to register.]]
19 parent : Efl.Ui.Focus.Object; [[The parent to use in 17 parent : Efl.Ui.Focus.Object; [[The parent to use in the logical tree.]]
20 the logical tree]] 18 redirect : Efl.Ui.Focus.Manager; [[The redirect manager to set once this child is focused.
21 redirect : Efl.Ui.Focus.Manager; [[The redirect manager to set 19 Can be $NULL for no redirect.]]
22 once this child is focused can be NULL for no redirect]]
23 } 20 }
24 return : bool; [[$true if successful, $false otherwise]] 21 return : bool; [[$true if successful, $false otherwise.]]
25 } 22 }
26 register_logical { 23 register_logical {
27 [[Register a new item only for the logical parent. 24 [[Registers a new logical item in the graph.
28 25
29 The item can never get focus, it just helps to build a tree out 26 The item can never get focus, it just helps to build the tree.
30 of the items that are. 27 Compare to @.register.
31 ]] 28 ]]
32 params { 29 params {
33 child : Efl.Ui.Focus.Object; [[The object to register]] 30 child : Efl.Ui.Focus.Object; [[The object to register.]]
34 parent : Efl.Ui.Focus.Object; [[The parent to use in 31 parent : Efl.Ui.Focus.Object; [[The parent to use in the logical tree.]]
35 the logical tree]] 32 redirect : Efl.Ui.Focus.Manager; [[The redirect manager to set once this child is focused.
36 redirect : Efl.Ui.Focus.Manager; [[The redirect manager to set 33 Can be $NULL for no redirect.]]
37 once this child is focused can be $null for no redirect]]
38 } 34 }
39 return : bool; [[$true if successful, $false otherwise]] 35 return : bool; [[$true if successful, $false otherwise.]]
40 } 36 }
41 update_redirect { 37 update_redirect {
42 [[Set a new redirect object for the given child. 38 [[Sets a new redirect object for the given child.
43 39
44 Once $child is focused the redirect manager will be set 40 Once $child is focused the redirect manager will be set
45 in the redirect property. Set redirect to $null if nothing should happen. 41 in the redirect property. Set redirect to $NULL if nothing should happen.
46 ]] 42 ]]
47 params { 43 params {
48 child : Efl.Ui.Focus.Object; [[The child to update]] 44 child : Efl.Ui.Focus.Object; [[The child to update.]]
49 redirect : Efl.Ui.Focus.Manager; [[Once $child is focused this 45 redirect : Efl.Ui.Focus.Manager; [[Once $child is focused this
50 element will be set as redirect]] 46 element will be set as redirect.]]
51 } 47 }
52 return : bool; [[$true if successful, $false otherwise]] 48 return : bool; [[$true if successful, $false otherwise.]]
53 } 49 }
54 update_parent { 50 update_parent {
55 [[Set a new logical parent for the given child.]] 51 [[Sets a new logical parent for the given child.]]
56 params { 52 params {
57 child : Efl.Ui.Focus.Object; [[The child to update]] 53 child : Efl.Ui.Focus.Object; [[The child to update.]]
58 parent : Efl.Ui.Focus.Object; [[The parent which now 54 parent : Efl.Ui.Focus.Object; [[The parent which now will be the logical parent of child.]]
59 will be the logical parent of child]]
60 } 55 }
61 return : bool; [[$true if successful, $false otherwise]] 56 return : bool; [[$true if successful, $false otherwise.]]
62 } 57 }
63 update_children { 58 update_children {
64 [[Give the list of children a different order.]] 59 [[Sets the list of children to a different order.]]
65 params { 60 params {
66 parent : Efl.Ui.Focus.Object; [[the parent to update]] 61 parent : Efl.Ui.Focus.Object; [[The parent to update.]]
67 children : list<Efl.Ui.Focus.Object> @owned; [[the list with the new order]] 62 children : list<Efl.Ui.Focus.Object> @owned; [[The list of children with the new order.]]
68 } 63 }
69 return : bool; [[$true if successful, $false otherwise]] 64 return : bool; [[$true if successful, $false otherwise.]]
70 } 65 }
71 update_order { 66 update_order {
72 [[Give the given order to the parent's child. 67 [[Sets the list of children to a different order.
73 68
74 Children from the list which are not true children are ignored. 69 Objects in the list which are not children of $parent are ignored.
70 Compare to @.update_children.
75 ]] 71 ]]
76 params { 72 params {
77 parent : Efl.Ui.Focus.Object; [[the parent to update]] 73 parent : Efl.Ui.Focus.Object; [[The parent to update.]]
78 children : list<Efl.Ui.Focus.Object> @owned; [[the order of items]] 74 children : list<Efl.Ui.Focus.Object> @owned; [[The list of objects with the new order.]]
79 } 75 }
80 } 76 }
81 unregister { 77 unregister {
diff --git a/src/lib/elementary/efl_ui_focus_manager_root_focus.eo b/src/lib/elementary/efl_ui_focus_manager_root_focus.eo
index 0accc6bbe0..1572e77214 100644
--- a/src/lib/elementary/efl_ui_focus_manager_root_focus.eo
+++ b/src/lib/elementary/efl_ui_focus_manager_root_focus.eo
@@ -2,8 +2,8 @@ class @beta Efl.Ui.Focus.Manager_Root_Focus extends Efl.Ui.Focus.Manager_Calc {
2 [[This class ensures that the root is at least focusable, if nothing else is focusable.]] 2 [[This class ensures that the root is at least focusable, if nothing else is focusable.]]
3 methods { 3 methods {
4 @property canvas_object { 4 @property canvas_object {
5 [[The default replacement object for the case that there is no focusable object inside the manager is the root 5 [[The default replacement object to use when there is no focusable object inside the manager.
6 object. However, you can change this by setting this value to something else. 6 You can change this object by setting this value to something else.
7 $null means that the same value as @Efl.Ui.Focus.Manager.root will be used. 7 $null means that the same value as @Efl.Ui.Focus.Manager.root will be used.
8 ]] 8 ]]
9 values { 9 values {
diff --git a/src/lib/elementary/efl_ui_focus_manager_sub.eo b/src/lib/elementary/efl_ui_focus_manager_sub.eo
index 9394080396..eaf00758e7 100644
--- a/src/lib/elementary/efl_ui_focus_manager_sub.eo
+++ b/src/lib/elementary/efl_ui_focus_manager_sub.eo
@@ -1,6 +1,6 @@
1mixin @beta Efl.Ui.Focus.Manager_Sub requires Efl.Object extends Efl.Ui.Focus.Manager 1mixin @beta Efl.Ui.Focus.Manager_Sub requires Efl.Object extends Efl.Ui.Focus.Manager
2{ 2{
3 [[A class that automatically registers its border elements in the parent manager 3 [[A class that automatically registers its border elements in the parent manager.
4 4
5 This sub manager will register its border elements on the parent manager. 5 This sub manager will register its border elements on the parent manager.
6 The parent manager is found with the @Efl.Ui.Focus.Object interface of the 6 The parent manager is found with the @Efl.Ui.Focus.Object interface of the
diff --git a/src/lib/elementary/efl_ui_focus_manager_window_root.eo b/src/lib/elementary/efl_ui_focus_manager_window_root.eo
index 278521345e..78e1469f86 100644
--- a/src/lib/elementary/efl_ui_focus_manager_window_root.eo
+++ b/src/lib/elementary/efl_ui_focus_manager_window_root.eo
@@ -2,7 +2,7 @@ interface Efl.Ui.Focus.Manager_Window_Root {
2 [[An interface to indicate the end of a focus chain. 2 [[An interface to indicate the end of a focus chain.
3 3
4 Focus managers are ensuring that if they give focus to something, that is registered in the upper focus manager. 4 Focus managers are ensuring that if they give focus to something, that is registered in the upper focus manager.
5 The most upper focus manager does not need to do that, and can implement this interface to indicate that. 5 The uppermost focus manager does not need to do that, and can implement this interface to indicate so.
6 6
7 @since 1.22 7 @since 1.22
8 ]] 8 ]]
diff --git a/src/lib/elementary/efl_ui_focus_parent_provider_standard.eo b/src/lib/elementary/efl_ui_focus_parent_provider_standard.eo
index 40cce41449..ba9745d1bb 100644
--- a/src/lib/elementary/efl_ui_focus_parent_provider_standard.eo
+++ b/src/lib/elementary/efl_ui_focus_parent_provider_standard.eo
@@ -1,5 +1,9 @@
1class @beta Efl.Ui.Focus.Parent_Provider_Standard extends Efl.Object implements Efl.Ui.Focus.Parent_Provider { 1class @beta Efl.Ui.Focus.Parent_Provider_Standard extends Efl.Object implements Efl.Ui.Focus.Parent_Provider {
2 [[EFL UI Focus Parent Provider Standard Class]] 2 [[EFL UI Focus Parent Provider Standard Class.
3
4 This is the default implementation for the @Efl.Ui.Focus.Parent_Provider interface. It simply uses
5 the widget's parent as the focus parent.
6 ]]
3 implements { 7 implements {
4 Efl.Ui.Focus.Parent_Provider.find_logical_parent; 8 Efl.Ui.Focus.Parent_Provider.find_logical_parent;
5 } 9 }
diff --git a/src/lib/elementary/efl_ui_focus_util.eo b/src/lib/elementary/efl_ui_focus_util.eo
index 40b38a540e..703ccf5b64 100644
--- a/src/lib/elementary/efl_ui_focus_util.eo
+++ b/src/lib/elementary/efl_ui_focus_util.eo
@@ -1,24 +1,32 @@
1class @beta Efl.Ui.Focus.Util extends Efl.Object { 1class @beta Efl.Ui.Focus.Util extends Efl.Object {
2 [[EFL UI Focus Util class]] 2 [[EFL UI Focus Utility class.
3
4 This class contains a series of static methods that simplify common focus management operations.
5 There's no need to instantiate this class.
6 ]]
3 methods { 7 methods {
4 focus @static { 8 focus @static {
5 [[Focus helper method]] 9 [[Sets the focus to the given object.]]
6 params { 10 params {
7 focus_elem : Efl.Ui.Focus.Object; [[Focus element]] 11 focus_elem : Efl.Ui.Focus.Object; [[Object to receive focus.]]
8 } 12 }
9 } 13 }
10 active_manager @static { 14 active_manager @static {
11 [[Get the highest manager in the redirect property]] 15 [[Gets the highest manager in the redirect chain.]]
12 params { 16 params {
13 manager : Efl.Ui.Focus.Manager; 17 manager : Efl.Ui.Focus.Manager; [[Manager to start looking from.]]
14 } 18 }
15 return: Efl.Ui.Focus.Manager; 19 return: Efl.Ui.Focus.Manager;
16 } 20 }
17 direction_complement @static { 21 direction_complement @static {
22 [[Returns the complementary (opposite) focus direction.
23
24 The defined opposites are Left-Right, Up-Down and Next-Previous.
25 ]]
18 params { 26 params {
19 dir : Efl.Ui.Focus.Direction; 27 dir : Efl.Ui.Focus.Direction; [[Direction to complement.]]
20 } 28 }
21 return: Efl.Ui.Focus.Direction; 29 return: Efl.Ui.Focus.Direction; [[The opposite direction.]]
22 } 30 }
23 } 31 }
24} 32}
diff --git a/src/lib/elementary/efl_ui_widget_focus_manager.eo b/src/lib/elementary/efl_ui_widget_focus_manager.eo
index af5a09212f..e5cc1a2691 100644
--- a/src/lib/elementary/efl_ui_widget_focus_manager.eo
+++ b/src/lib/elementary/efl_ui_widget_focus_manager.eo
@@ -1,13 +1,14 @@
1mixin Efl.Ui.Widget_Focus_Manager requires Efl.Ui.Widget extends Efl.Ui.Focus.Manager 1mixin Efl.Ui.Widget_Focus_Manager requires Efl.Ui.Widget extends Efl.Ui.Focus.Manager
2{ 2{
3 [[ 3 [[Helper mixin for widgets which also can act as focus managers.
4
4 @since 1.22 5 @since 1.22
5 ]] 6 ]]
6 methods { 7 methods {
7 focus_manager_create @protected @pure_virtual { 8 focus_manager_create @protected @pure_virtual {
8 [[If the widget needs a focus manager, this function will be called. 9 [[If the widget needs a focus manager, this function will be called.
9 10
10 It can be used and overriden to inject your own manager or set 11 It can be used and overridden to inject your own manager or set
11 custom options on the focus manager. 12 custom options on the focus manager.
12 ]] 13 ]]
13 params { 14 params {
diff --git a/src/lib/evas/canvas/efl_input_focus.eo b/src/lib/evas/canvas/efl_input_focus.eo
index eacc99fc79..5de997723f 100644
--- a/src/lib/evas/canvas/efl_input_focus.eo
+++ b/src/lib/evas/canvas/efl_input_focus.eo
@@ -6,11 +6,9 @@ class Efl.Input.Focus extends Efl.Object implements Efl.Input.Event
6 ]] 6 ]]
7 methods { 7 methods {
8 @property object { 8 @property object {
9 [[The focused object]] 9 [[The focused object.]]
10 values { 10 values {
11 object: Efl.Object; [[The focused object. 11 object: Efl.Object; [[The focused object, or $NULL if the event comes from the canvas.]]
12 In case this represents a canvas
13 focus the object will be $null]]
14 } 12 }
15 } 13 }
16 } 14 }