summaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
authorMarcel Hollerbach <mail@marcel-hollerbach.de>2019-02-22 10:41:38 +0100
committerXavi Artigas <xavierartigas@yahoo.es>2019-02-22 15:58:03 +0100
commit45b46781a260d1d2f56a39abccc4d41d5cf26336 (patch)
tree89a54c29aeeb6f53ea840990fe68c825f1ca8626 /src
parenta6d256cb6a53571d399b40c01c71d249b70a037c (diff)
docs: Polish focus documentation.
Summary: Depends on D7994 Reviewers: bu5hm4n Reviewed By: bu5hm4n Subscribers: cedric, #reviewers, #committers Tags: #efl Differential Revision: https://phab.enlightenment.org/D7998
Diffstat (limited to 'src')
-rw-r--r--src/lib/elementary/efl_ui_focus_manager.eo102
-rw-r--r--src/lib/elementary/efl_ui_focus_object.eo22
2 files changed, 69 insertions, 55 deletions
diff --git a/src/lib/elementary/efl_ui_focus_manager.eo b/src/lib/elementary/efl_ui_focus_manager.eo
index 5eb2e17d59..7db8439048 100644
--- a/src/lib/elementary/efl_ui_focus_manager.eo
+++ b/src/lib/elementary/efl_ui_focus_manager.eo
@@ -2,7 +2,7 @@ import efl_ui;
2import eina_types; 2import eina_types;
3 3
4struct @free(efl_ui_focus_relation_free) Efl.Ui.Focus.Relations { 4struct @free(efl_ui_focus_relation_free) Efl.Ui.Focus.Relations {
5 [[Structure holding the graph of relations between focussable objects. 5 [[Structure holding the graph of relations between focusable objects.
6 6
7 @since 1.20 7 @since 1.20
8 ]] 8 ]]
@@ -31,44 +31,51 @@ struct Efl.Ui.Focus.Manager_Logical_End_Detail {
31interface @beta Efl.Ui.Focus.Manager { 31interface @beta Efl.Ui.Focus.Manager {
32 [[Interface for managing focus objects 32 [[Interface for managing focus objects
33 33
34 This interface is build in order to support movement of the focus property in a set of widgets. 34 This interface is built in order to support movement of the focus property in a set of widgets.
35 The movement of the focus property can happen in a tree manner, or a graph manner. The movements is also keeping track of the history of focused elements. The tree interpretation differentiates between logical and none-logical widgets, a logical widget cannot receive focus, a none-logical can. 35 The movement of the focus property can happen in a tree manner, or a graph manner.
36 The movement is also keeping track of the history of focused elements.
37 The tree interpretation differentiates between logical and non-logical widgets,
38 a logical widget cannot receive focus whereas a non-logical one can.
36 39
37 @since 1.20 40 @since 1.20
38 ]] 41 ]]
39 methods { 42 methods {
40 move { 43 move {
41 [[Move the focus into the given direction. 44 [[Move the focus in the given direction.
42 45
43 This call flushes all changes. 46 This call flushes all changes.
44 This means all changes between the last flush and now are computed 47 This means all changes between the last flush and now are computed.
45 ]] 48 ]]
46 params { 49 params {
47 direction : Efl.Ui.Focus.Direction; [[The direction to move to]] 50 direction : Efl.Ui.Focus.Direction; [[The direction to move to.]]
48 } 51 }
49 return : Efl.Ui.Focus.Object; [[The element which is now focused]] 52 return : Efl.Ui.Focus.Object; [[The element which is now focused.]]
50 } 53 }
51 request_move { 54 request_move {
52 [[Return the object next in the $direction from $child.]] 55 [[Return the object in the $direction from $child.]]
53 params { 56 params {
54 direction : Efl.Ui.Focus.Direction; [[Direction to move focus]] 57 direction : Efl.Ui.Focus.Direction; [[Direction to move focus.]]
55 child : Efl.Ui.Focus.Object; [[The child where to look from. Pass $null to indicate the last focused child.]] 58 child : Efl.Ui.Focus.Object; [[The child to move from. Pass $null to indicate the currently focused child.]]
56 logical : bool; [[Weather you want to have a logical node as result or a logical. Note, at a move call no logical node will get focus, and this is passed as $false there.]] 59 logical : bool; [[Wether you want to have a logical node as result or a non-logical.
60 Note, in a @.move call no logical node will get focus.]]
57 } 61 }
58 return : Efl.Ui.Focus.Object; [[Next object to focus]] 62 return : Efl.Ui.Focus.Object; [[Object that would receive focus if moved in the given direction.]]
59 } 63 }
60 @property manager_focus { 64 @property manager_focus {
61 [[The element which is currently focused by this manager 65 [[The element which is currently focused by this manager
62 66
63 For the case focus is a logical child, then the item will go to the next none logical element. If there is none, focus will stay where it is right now. 67 Use this property to retrieve the object currently being focused, or to set the focus
68 to a new one.
69 When $focus is a logical child (which cannot receive focus), the next non-logical
70 object is selected instead. If there is no such object, focus does not change.
64 ]] 71 ]]
65 72
66 values { 73 values {
67 focus : Efl.Ui.Focus.Object @nonull; [[Focused element]] 74 focus : Efl.Ui.Focus.Object @nonull; [[Currently focused element.]]
68 } 75 }
69 } 76 }
70 @property redirect { 77 @property redirect {
71 [[Add a another manager to serve the move requests. 78 [[Add another manager to serve the move requests.
72 79
73 If this value is set, all move requests are redirected to this 80 If this value is set, all move requests are redirected to this
74 manager object. Set it to $null once nothing should be redirected 81 manager object. Set it to $null once nothing should be redirected
@@ -93,15 +100,15 @@ interface @beta Efl.Ui.Focus.Manager {
93 @property viewport_elements { 100 @property viewport_elements {
94 [[Get all elements that are at the border of the viewport 101 [[Get all elements that are at the border of the viewport
95 102
96 Every element returned by this is located in the viewport rectangle, 103 Every element returned by this is located inside the viewport rectangle,
97 but has a right,left,down or up relation outside the viewport. 104 but has a right, left, down or up neighbor outside the viewport.
98 ]] 105 ]]
99 get {} 106 get {}
100 keys { 107 keys {
101 viewport : Eina.Rect; 108 viewport : Eina.Rect; [[The rectangle defining the viewport.]]
102 } 109 }
103 values { 110 values {
104 viewport_elements : iterator<Efl.Ui.Focus.Object>; 111 viewport_elements : iterator<Efl.Ui.Focus.Object>; [[The list of border objects.]]
105 } 112 }
106 } 113 }
107 @property root { 114 @property root {
@@ -113,9 +120,7 @@ interface @beta Efl.Ui.Focus.Manager {
113 return : bool; [[If $true, this is the root node]] 120 return : bool; [[If $true, this is the root node]]
114 } 121 }
115 122
116 get { 123 get {}
117
118 }
119 124
120 values { 125 values {
121 root : Efl.Ui.Focus.Object @nonull; [[Will be registered into 126 root : Efl.Ui.Focus.Object @nonull; [[Will be registered into
@@ -126,18 +131,18 @@ interface @beta Efl.Ui.Focus.Manager {
126 [[Return the widget in the direction next. 131 [[Return the widget in the direction next.
127 132
128 The returned widget is a child of $root. 133 The returned widget is a child of $root.
129 Its garanteed that child will not be prepared once again, 134 It's guaranteed that child will not be prepared once again,
130 so you can call this function out of a prepare call. 135 so you can call this function inside a @Efl.Ui.Focus.Object.setup_order call.
131 ]] 136 ]]
132 params { 137 params {
133 root : Efl.Ui.Focus.Object; [[Parent for returned child]] 138 root : Efl.Ui.Focus.Object; [[Parent for returned child.]]
134 } 139 }
135 return : Efl.Ui.Focus.Object; [[Child of passed parameter]] 140 return : Efl.Ui.Focus.Object; [[Child of passed parameter.]]
136 } 141 }
137 fetch { 142 fetch {
138 [[This will fetch the data from a registered node. 143 [[This will fetch the data from a registered node.
139 144
140 Be aware this function will trigger all dirty nodes to be computed 145 Be aware this function will trigger a computation of all dirty nodes.
141 ]] 146 ]]
142 params { 147 params {
143 child : Efl.Ui.Focus.Object; [[The child object to inspect.]] 148 child : Efl.Ui.Focus.Object; [[The child object to inspect.]]
@@ -150,49 +155,58 @@ interface @beta Efl.Ui.Focus.Manager {
150 155
151 The returned object is the last object that would be returned if you start at the root and move the direction into next. 156 The returned object is the last object that would be returned if you start at the root and move the direction into next.
152 ]] 157 ]]
153 return : Efl.Ui.Focus.Manager_Logical_End_Detail; [[Last object]] 158 return : Efl.Ui.Focus.Manager_Logical_End_Detail; [[Last object.]]
154 } 159 }
155 reset_history { 160 reset_history {
156 [[Reset the history stack of this manager object. 161 [[Reset the history stack of this manager object.
157 This means the most upper element will be unfocused, all other elements will be removed from the remembered before. 162 This means the uppermost element will be unfocused, and all other elements
163 will be removed from the remembered list.
158 164
159 To not break the assertion that there should be always a focused element, you should focus a other element immidiatly after calling this. 165 You should focus another element immediately after calling this, in order
166 to always have a focused object.
160 ]] 167 ]]
161 } 168 }
162 pop_history_stack { 169 pop_history_stack {
163 [[Remove the most upper history element, and focus the next possible element 170 [[Remove the uppermost history element, and focus the previous one.
164 171
165 If there is a element that was focused before, it will be taken. Otherwise, the best fitting element from the registered elements will be focused. 172 If there is an element that was focused before, it will be used.
173 Otherwise, the best fitting element from the registered elements will be focused.
166 ]] 174 ]]
167 } 175 }
168 setup_on_first_touch { 176 setup_on_first_touch {
169 [[Called when this manager is set as redirect. 177 [[Called when this manager is set as redirect.
170 178
171 In case that this is called as an result of a move call, $direction and $entry will be set to the direction of the move call, and the entry object will be set to the object, that had this object as redirect property. 179 In case that this is called as an result of a move call, $direction and $entry
180 will be set to the direction of the move call, and the $entry object will be
181 set to the object that had this manager as redirect property.
172 ]] 182 ]]
173 params { 183 params {
174 direction : Efl.Ui.Focus.Direction; [[The direction in which this should be setup]] 184 direction : Efl.Ui.Focus.Direction; [[The direction in which this should be setup.]]
175 entry : Efl.Ui.Focus.Object; [[The object that caused this manager to be redirect]] 185 entry : Efl.Ui.Focus.Object; [[The object that caused this manager to be redirect.]]
176 } 186 }
177 } 187 }
178 dirty_logic_freeze { 188 dirty_logic_freeze {
179 [[This disables the cache invalidation when a object is moved. 189 [[This disables the cache invalidation when an object is moved.
180 190
181 Even the object is moved, the focus manager will not recalculate its relations, this can be used when you know that the set of widgets in the focus manager is equally moved. so the relations between the widets in the set do not change. 191 Even if an object is moved, the focus manager will not recalculate its relations.
192 This can be used when you know that the set of widgets in the focus manager is
193 moved the same way, so the relations between the widets in the set do not change
194 and the complex calculations can be avoided.
195 Use @.dirty_logic_unfreeze to re-enable relationship calculation.
182 ]] 196 ]]
183 } 197 }
184 dirty_logic_unfreeze { 198 dirty_logic_unfreeze {
185 [[This enables the cache invalidation when a object is moved. 199 [[This enables the cache invalidation when an object is moved.
186 200
187 This is the counter part to @.dirty_logic_freeze 201 This is the counterpart to @.dirty_logic_freeze.
188 ]] 202 ]]
189 } 203 }
190 } 204 }
191 events { 205 events {
192 redirect,changed : Efl.Ui.Focus.Manager; [[Redirect object has changed, the old manager is passed as event info]] 206 redirect,changed : Efl.Ui.Focus.Manager; [[Redirect object has changed, the old manager is passed as an event argument.]]
193 flush,pre: void; [[Next to this event, the manager object will calculate relations in the graph. Can be used to add / remove children in a lazy manner]] 207 flush,pre: void; [[After this event, the manager object will calculate relations in the graph. Can be used to add / remove children in a lazy fashion.]]
194 coords,dirty: void; [[Cached calculation results have been invalidated]] 208 coords,dirty: void; [[Cached relationship calculation results have been invalidated.]]
195 manager_focus,changed : Efl.Ui.Focus.Object; [[the manager_focus property has changed, the previous focused object is passed as event argument]] 209 manager_focus,changed : Efl.Ui.Focus.Object; [[The manager_focus property has changed. The previously focused object is passed as an event argument.]]
196 dirty_logic_freeze,changed : bool; [[Called when this focus manager is frozen or unfrozen, even_info beeing $true indicates that it is now frozen, $false indicates that it is unfrozen.]] 210 dirty_logic_freeze,changed : bool; [[Called when this focus manager is frozen or thawed, even_info beeing $true indicates that it is now frozen, $false indicates that it is thawed.]]
197 } 211 }
198} 212}
diff --git a/src/lib/elementary/efl_ui_focus_object.eo b/src/lib/elementary/efl_ui_focus_object.eo
index f9e3c41830..d80c0a2754 100644
--- a/src/lib/elementary/efl_ui_focus_object.eo
+++ b/src/lib/elementary/efl_ui_focus_object.eo
@@ -8,10 +8,9 @@ mixin @beta Efl.Ui.Focus.Object
8 ]] 8 ]]
9 methods { 9 methods {
10 @property focus_geometry { 10 @property focus_geometry {
11 [[The geometry used to calculate relationships between other objects.]] 11 [[The geometry (that is, the bounding rectangle) used to calculate the
12 get { 12 relationship with other objects.]]
13 13 get {}
14 }
15 values { 14 values {
16 rect : Eina.Rect; [[The geometry to use.]] 15 rect : Eina.Rect; [[The geometry to use.]]
17 } 16 }
@@ -29,7 +28,7 @@ mixin @beta Efl.Ui.Focus.Object
29 ]] 28 ]]
30 } 29 }
31 values { 30 values {
32 focus : bool; [[The focused state of the object]] 31 focus : bool; [[The focused state of the object.]]
33 } 32 }
34 } 33 }
35 @property focus_manager { 34 @property focus_manager {
@@ -49,13 +48,14 @@ mixin @beta Efl.Ui.Focus.Object
49 } 48 }
50 } 49 }
51 @property child_focus @protected { 50 @property child_focus @protected {
52 [[Indicates if a child of this object has focus setted to true.]] 51 [[Indicates if a child of this object has focus set to true.]]
53 values { 52 values {
54 child_focus : bool; 53 child_focus : bool; [[$true if a child has focus.]]
55 } 54 }
56 } 55 }
57 setup_order { 56 setup_order {
58 [[Tells the object that its children will be queried soon by the focus manager. Overwrite this to update the order of the children. Deleting items in this call will 57 [[Tells the object that its children will be queried soon by the focus manager.
58 Overwrite this to update the order of the children. Deleting items in this call will
59 result in undefined behaviour and may cause your system to crash. 59 result in undefined behaviour and may cause your system to crash.
60 ]] 60 ]]
61 } 61 }
@@ -75,12 +75,12 @@ mixin @beta Efl.Ui.Focus.Object
75 @empty .on_focus_update; 75 @empty .on_focus_update;
76 } 76 }
77 events { 77 events {
78 focus,changed : bool; [[Emitted if the focus state has changed]] 78 focus,changed : bool; [[Emitted if the focus state has changed.]]
79 focus_manager,changed: Efl.Ui.Focus.Manager; [[Emitted when a new manager is 79 focus_manager,changed: Efl.Ui.Focus.Manager; [[Emitted when a new manager is
80 the parent for this object.]] 80 the parent for this object.]]
81 focus_parent,changed: Efl.Ui.Focus.Object; [[Emitted when a new logical 81 focus_parent,changed: Efl.Ui.Focus.Object; [[Emitted when a new logical
82 parent should be used.]] 82 parent should be used.]]
83 child_focus,changed: bool; [[Emitted if child_focus has changed]] 83 child_focus,changed: bool; [[Emitted if child_focus has changed.]]
84 focus_geometry,changed: void; [[Emitted if focus geometry of this object has changed]] 84 focus_geometry,changed: void; [[Emitted if focus geometry of this object has changed.]]
85 } 85 }
86} 86}