summaryrefslogtreecommitdiff
path: root/src/lib/elementary/efl_ui_focus_manager.eo
blob: 1b9798c77e2c20ab2aba0d27a71a81146983ffb8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
import efl_ui;
import eina_types;

struct @beta @free(efl_ui_focus_relation_free) Efl.Ui.Focus.Relations {
    [[Structure holding the graph of relations between focusable objects.
    ]]
    right : list<Efl.Ui.Focus.Object> @owned; [[List of objects to the right.]]
    left : list<Efl.Ui.Focus.Object> @owned; [[List of objects to the left.]]
    top : list<Efl.Ui.Focus.Object> @owned; [[List of objects above.]]
    down : list<Efl.Ui.Focus.Object> @owned; [[List of objects below.]]
    next : Efl.Ui.Focus.Object; [[Next object.]]
    prev : Efl.Ui.Focus.Object; [[Previous object.]]
    parent : Efl.Ui.Focus.Object; [[Parent object.]]
    redirect : Efl.Ui.Focus.Manager; [[Redirect manager.]]
    node : Efl.Ui.Focus.Object; [[The node where this information is from.]]
    logical : bool; [[$true if this is a logical (non-regular) node.]]
    position_in_history : int; [[The position in the history stack.]]
}

struct Efl.Ui.Focus.Manager_Logical_End_Detail {
    [[Structure holding the focus object with extra information on logical end.

      @since 1.22
    ]]
    is_regular_end : bool; [[$true if element is registered as regular element in the @Efl.Ui.Focus.Manager object.]]
    element : Efl.Ui.Focus.Object; [[The last element of the logical chain in the @Efl.Ui.Focus.Manager.]]
}

interface Efl.Ui.Focus.Manager {
    [[Interface for managing focus objects.

      This interface is built in order to support movement of the focus property in a set of widgets.
      The movement of the focus property can happen in a tree manner, or a graph manner.
      The movement is also keeping track of the history of focused elements.
      The tree interpretation differentiates between logical and regular widgets:
      Logical widgets (typically containers) cannot receive focus, whereas Regular ones (like buttons) can.

      @since 1.22
    ]]
    methods {
        move {
            [[Moves the focus in the given direction to the next regular widget.

              This call flushes all changes.
              This means all changes since last flush are computed.
            ]]
            params {
                direction : Efl.Ui.Focus.Direction; [[The direction to move to.]]
            }
            return : Efl.Ui.Focus.Object; [[The element which is now focused.]]
        }
        request_move {
            [[Returns the object in the $direction from $child.]]
            params {
                direction : Efl.Ui.Focus.Direction; [[Direction to move focus.]]
                child : Efl.Ui.Focus.Object; [[The child to move from.
                                               Pass $null to indicate the currently focused child.]]
                logical : bool; [[Wether you want to have a logical node as result or a regular.
                                  Note that in a @.move call logical nodes will not get focus.]]
            }
            return : Efl.Ui.Focus.Object; [[Object that would receive focus if moved in the given direction.]]
        }
        @property manager_focus {
            [[The element which is currently focused by this manager.

              Use this property to retrieve the object currently being focused, or to set the focus
              to a new one.
              When $focus is a logical child (which cannot receive focus), the next regular
              object is selected instead. If there is no such object, focus does not change.
            ]]

            values {
                focus : Efl.Ui.Focus.Object; [[Currently focused element.]]
            }
        }
        @property redirect {
            [[Add 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.
            ]]
            values {
                redirect : Efl.Ui.Focus.Manager; [[The new focus manager.]]
            }
        }
        @property border_elements {
            [[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.
            ]]
            get {}
            values {
                border_elements : iterator<Efl.Ui.Focus.Object>; [[An iterator
                   over the border objects.]]
            }
        }
        @property viewport_elements {
            [[Elements that are at the border of the viewport

              Every element returned by this is located inside the viewport rectangle,
              but has a right, left, down or up neighbor outside the viewport.
            ]]
            get {}
            keys {
                viewport : Eina.Rect; [[The rectangle defining the viewport.]]
            }
            values {
              viewport_elements : iterator<Efl.Ui.Focus.Object>; [[An iterator over the viewport border objects.]]
            }
        }
        @property root {
            [[Root node for all logical sub-trees.

              This property can only be set once.
            ]]
            set {
                return : bool; [[$true on success, $false if it had already been set.]]
            }
            get {}

            values {
                root : Efl.Ui.Focus.Object; [[Object to register as the root of this manager object.]]
            }
        }
        request_subchild {
            [[Returns the widget in the direction next.

              The returned widget is a child of $root.
              It's guaranteed that child will not be prepared again,
              so you can call this function inside a @Efl.Ui.Focus.Object.setup_order call.
            ]]
              params {
                 root : Efl.Ui.Focus.Object; [[Parent for returned child.]]
              }
              return : Efl.Ui.Focus.Object; [[Child of passed parameter.]]
        }
        fetch @beta {
            [[Fetches the data from a registered node.

              Note: This function triggers a computation of all dirty nodes.
            ]]
            params {
                child : Efl.Ui.Focus.Object; [[The child object to inspect.]]
            }
            return : ptr(Efl.Ui.Focus.Relations) @owned; [[The list of relations
                starting from $child.]]
        }
        logical_end {
            [[Returns the last logical object.

              The returned object is the last object that would be returned if you start at the root
              and move in the "next" direction.
            ]]
            return : Efl.Ui.Focus.Manager_Logical_End_Detail; [[Last object.]]
        }
        reset_history {
            [[Resets the history stack of this manager object.
              This means the uppermost element will be unfocused, and all other elements
              will be removed from the remembered list.

              You should focus another element immediately after calling this, in order
              to always have a focused object.
            ]]
        }
        pop_history_stack {
            [[Removes the uppermost history element, and focuses the previous one.

              If there is an element that was focused before, it will be used.
              Otherwise, the best fitting element from the registered elements will be focused.
            ]]
        }
        setup_on_first_touch {
           [[Called when this manager is set as redirect.

             In case that this is called as a 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 manager as redirect property.
           ]]
           params {
             direction : Efl.Ui.Focus.Direction; [[The direction in which this should be setup.]]
             entry : Efl.Ui.Focus.Object; [[The object that caused this manager to be redirect.]]
           }
        }
        dirty_logic_freeze {
          [[Disables the cache invalidation when an object is moved.

            Even if an 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
            moved the same way, so the relations between the widgets in the set do not change
            and complex calculations can be avoided.
            Use @.dirty_logic_unfreeze to re-enable relationship calculation.
          ]]
        }
        dirty_logic_unfreeze {
          [[Enables the cache invalidation when an object is moved.

            This is the counterpart to @.dirty_logic_freeze.
          ]]
        }
    }
    events {
        redirect,changed : Efl.Ui.Focus.Manager; [[Redirect object has changed, the old manager is passed as
                                                   an event argument.]]
        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.]]
        coords,dirty: void; [[Cached relationship calculation results have been invalidated.]]
        manager_focus,changed : Efl.Ui.Focus.Object; [[The manager_focus property has changed.
                                                       The previously focused object is passed as an event argument.]]
        dirty_logic_freeze,changed : bool; [[Called when this focus manager is frozen or thawed,
                                             even_info being $true indicates that it is now frozen,
                                             $false indicates that it is thawed.]]
    }
}