forked from enlightenment/efl
docs: Update focus documentation
This commit is contained in:
parent
98da00cfd2
commit
d1dbb791e8
|
@ -4,45 +4,45 @@ import eina_types;
|
||||||
struct @beta @free(efl_ui_focus_relation_free) Efl.Ui.Focus.Relations {
|
struct @beta @free(efl_ui_focus_relation_free) Efl.Ui.Focus.Relations {
|
||||||
[[Structure holding the graph of relations between focusable objects.
|
[[Structure holding the graph of relations between focusable objects.
|
||||||
]]
|
]]
|
||||||
right : list<Efl.Ui.Focus.Object> @owned; [[List of objects on the right side]]
|
right : list<Efl.Ui.Focus.Object> @owned; [[List of objects to the right.]]
|
||||||
left : list<Efl.Ui.Focus.Object> @owned; [[List of objects on the left side]]
|
left : list<Efl.Ui.Focus.Object> @owned; [[List of objects to the left.]]
|
||||||
top : list<Efl.Ui.Focus.Object> @owned; [[List of objects above]]
|
top : list<Efl.Ui.Focus.Object> @owned; [[List of objects above.]]
|
||||||
down : list<Efl.Ui.Focus.Object> @owned; [[List of objects below]]
|
down : list<Efl.Ui.Focus.Object> @owned; [[List of objects below.]]
|
||||||
next : Efl.Ui.Focus.Object; [[Next object]]
|
next : Efl.Ui.Focus.Object; [[Next object.]]
|
||||||
prev : Efl.Ui.Focus.Object; [[Previous object]]
|
prev : Efl.Ui.Focus.Object; [[Previous object.]]
|
||||||
parent : Efl.Ui.Focus.Object; [[Parent object]]
|
parent : Efl.Ui.Focus.Object; [[Parent object.]]
|
||||||
redirect : Efl.Ui.Focus.Manager; [[Redirect manager]]
|
redirect : Efl.Ui.Focus.Manager; [[Redirect manager.]]
|
||||||
node : Efl.Ui.Focus.Object; [[The node where this is the information from]]
|
node : Efl.Ui.Focus.Object; [[The node where this information is from.]]
|
||||||
logical : bool; [[$true if this node is only logical]]
|
logical : bool; [[$true if this is a logical (non-regular) node.]]
|
||||||
position_in_history : int; [[The position in the history stack]]
|
position_in_history : int; [[The position in the history stack.]]
|
||||||
}
|
}
|
||||||
|
|
||||||
struct Efl.Ui.Focus.Manager_Logical_End_Detail {
|
struct Efl.Ui.Focus.Manager_Logical_End_Detail {
|
||||||
[[Structure holding the focus object with extra information on logical end
|
[[Structure holding the focus object with extra information on logical end.
|
||||||
|
|
||||||
@since 1.22
|
@since 1.22
|
||||||
]]
|
]]
|
||||||
is_regular_end : bool; [[$true if element is registered as regular element in the @Efl.Ui.Focus.Manager object.]]
|
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]]
|
element : Efl.Ui.Focus.Object; [[The last element of the logical chain in the @Efl.Ui.Focus.Manager.]]
|
||||||
}
|
}
|
||||||
|
|
||||||
interface Efl.Ui.Focus.Manager {
|
interface Efl.Ui.Focus.Manager {
|
||||||
[[Interface for managing focus objects
|
[[Interface for managing focus objects.
|
||||||
|
|
||||||
This interface is built in order to support movement of the focus property in a set of widgets.
|
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 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 movement is also keeping track of the history of focused elements.
|
||||||
The tree interpretation differentiates between logical and non-logical widgets,
|
The tree interpretation differentiates between logical and regular widgets:
|
||||||
a logical widget cannot receive focus whereas a non-logical one can.
|
Logical widgets (typically containers) cannot receive focus, whereas Regular ones (like buttons) can.
|
||||||
|
|
||||||
@since 1.22
|
@since 1.22
|
||||||
]]
|
]]
|
||||||
methods {
|
methods {
|
||||||
move {
|
move {
|
||||||
[[Move the focus in the given direction.
|
[[Moves the focus in the given direction to the next regular widget.
|
||||||
|
|
||||||
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 since last flush are computed.
|
||||||
]]
|
]]
|
||||||
params {
|
params {
|
||||||
direction : Efl.Ui.Focus.Direction; [[The direction to move to.]]
|
direction : Efl.Ui.Focus.Direction; [[The direction to move to.]]
|
||||||
|
@ -50,22 +50,22 @@ interface Efl.Ui.Focus.Manager {
|
||||||
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 {
|
||||||
[[Return the object in the $direction from $child.]]
|
[[Returns the object in the $direction from $child.]]
|
||||||
params {
|
params {
|
||||||
direction : Efl.Ui.Focus.Direction; [[Direction to move focus.]]
|
direction : Efl.Ui.Focus.Direction; [[Direction to move focus.]]
|
||||||
child : Efl.Ui.Focus.Object; [[The child to move from.
|
child : Efl.Ui.Focus.Object; [[The child to move from.
|
||||||
Pass $null to indicate the currently focused child.]]
|
Pass $null to indicate the currently focused child.]]
|
||||||
logical : bool; [[Wether you want to have a logical node as result or a non-logical.
|
logical : bool; [[Wether you want to have a logical node as result or a regular.
|
||||||
Note, in a @.move call no logical node will get focus.]]
|
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.]]
|
return : Efl.Ui.Focus.Object; [[Object that would receive focus if moved in the given direction.]]
|
||||||
}
|
}
|
||||||
@property manager_focus {
|
@property manager_focus {
|
||||||
[[The element which is currently focused by this manager
|
[[The element which is currently focused by this manager.
|
||||||
|
|
||||||
Use this property to retrieve the object currently being focused, or to set the focus
|
Use this property to retrieve the object currently being focused, or to set the focus
|
||||||
to a new one.
|
to a new one.
|
||||||
When $focus is a logical child (which cannot receive focus), the next non-logical
|
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.
|
object is selected instead. If there is no such object, focus does not change.
|
||||||
]]
|
]]
|
||||||
|
|
||||||
|
@ -81,14 +81,14 @@ interface Efl.Ui.Focus.Manager {
|
||||||
anymore.
|
anymore.
|
||||||
]]
|
]]
|
||||||
values {
|
values {
|
||||||
redirect : Efl.Ui.Focus.Manager; [[The redirect manager.]]
|
redirect : Efl.Ui.Focus.Manager; [[The new focus manager.]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@property border_elements {
|
@property border_elements {
|
||||||
[[The list of elements which are at the border of the graph.
|
[[Elements which are at the border of the graph.
|
||||||
|
|
||||||
This means one of the relations right,left or down,up are not set.
|
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 call flushes all changes. See @Efl.Ui.Focus.Manager.move.
|
||||||
]]
|
]]
|
||||||
get {}
|
get {}
|
||||||
values {
|
values {
|
||||||
|
@ -97,7 +97,7 @@ interface Efl.Ui.Focus.Manager {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@property viewport_elements {
|
@property viewport_elements {
|
||||||
[[Get all elements that are at the border of the viewport
|
[[Elements that are at the border of the viewport
|
||||||
|
|
||||||
Every element returned by this is located inside the viewport rectangle,
|
Every element returned by this is located inside the viewport rectangle,
|
||||||
but has a right, left, down or up neighbor outside the viewport.
|
but has a right, left, down or up neighbor outside the viewport.
|
||||||
|
@ -107,7 +107,7 @@ interface Efl.Ui.Focus.Manager {
|
||||||
viewport : Eina.Rect; [[The rectangle defining the viewport.]]
|
viewport : Eina.Rect; [[The rectangle defining the viewport.]]
|
||||||
}
|
}
|
||||||
values {
|
values {
|
||||||
viewport_elements : iterator<Efl.Ui.Focus.Object>; [[The list of border objects.]]
|
viewport_elements : iterator<Efl.Ui.Focus.Object>; [[An iterator over the viewport border objects.]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@property root {
|
@property root {
|
||||||
|
@ -116,21 +116,19 @@ interface Efl.Ui.Focus.Manager {
|
||||||
This property can only be set once.
|
This property can only be set once.
|
||||||
]]
|
]]
|
||||||
set {
|
set {
|
||||||
return : bool; [[If $true, this is the root node]]
|
return : bool; [[$true on success, $false if it had already been set.]]
|
||||||
}
|
}
|
||||||
|
|
||||||
get {}
|
get {}
|
||||||
|
|
||||||
values {
|
values {
|
||||||
root : Efl.Ui.Focus.Object; [[Will be registered into
|
root : Efl.Ui.Focus.Object; [[Object to register as the root of this manager object.]]
|
||||||
this manager object.]]
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
request_subchild {
|
request_subchild {
|
||||||
[[Return the widget in the direction next.
|
[[Returns the widget in the direction next.
|
||||||
|
|
||||||
The returned widget is a child of $root.
|
The returned widget is a child of $root.
|
||||||
It's guaranteed that child will not be prepared once again,
|
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.
|
so you can call this function inside a @Efl.Ui.Focus.Object.setup_order call.
|
||||||
]]
|
]]
|
||||||
params {
|
params {
|
||||||
|
@ -139,9 +137,9 @@ interface Efl.Ui.Focus.Manager {
|
||||||
return : Efl.Ui.Focus.Object; [[Child of passed parameter.]]
|
return : Efl.Ui.Focus.Object; [[Child of passed parameter.]]
|
||||||
}
|
}
|
||||||
fetch @beta {
|
fetch @beta {
|
||||||
[[This will fetch the data from a registered node.
|
[[Fetches the data from a registered node.
|
||||||
|
|
||||||
Be aware this function will trigger a computation of all dirty nodes.
|
Note: This function triggers a computation of all dirty nodes.
|
||||||
]]
|
]]
|
||||||
params {
|
params {
|
||||||
child : Efl.Ui.Focus.Object; [[The child object to inspect.]]
|
child : Efl.Ui.Focus.Object; [[The child object to inspect.]]
|
||||||
|
@ -150,7 +148,7 @@ interface Efl.Ui.Focus.Manager {
|
||||||
starting from $child.]]
|
starting from $child.]]
|
||||||
}
|
}
|
||||||
logical_end {
|
logical_end {
|
||||||
[[Return the last logical object.
|
[[Returns the last logical object.
|
||||||
|
|
||||||
The returned object is the last object that would be returned if you start at the root
|
The returned object is the last object that would be returned if you start at the root
|
||||||
and move in the "next" direction.
|
and move in the "next" direction.
|
||||||
|
@ -158,7 +156,7 @@ interface Efl.Ui.Focus.Manager {
|
||||||
return : Efl.Ui.Focus.Manager_Logical_End_Detail; [[Last object.]]
|
return : Efl.Ui.Focus.Manager_Logical_End_Detail; [[Last object.]]
|
||||||
}
|
}
|
||||||
reset_history {
|
reset_history {
|
||||||
[[Reset the history stack of this manager object.
|
[[Resets the history stack of this manager object.
|
||||||
This means the uppermost element will be unfocused, and all other elements
|
This means the uppermost element will be unfocused, and all other elements
|
||||||
will be removed from the remembered list.
|
will be removed from the remembered list.
|
||||||
|
|
||||||
|
@ -167,7 +165,7 @@ interface Efl.Ui.Focus.Manager {
|
||||||
]]
|
]]
|
||||||
}
|
}
|
||||||
pop_history_stack {
|
pop_history_stack {
|
||||||
[[Remove the uppermost history element, and focus the previous one.
|
[[Removes the uppermost history element, and focuses the previous one.
|
||||||
|
|
||||||
If there is an element that was focused before, it will be used.
|
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.
|
Otherwise, the best fitting element from the registered elements will be focused.
|
||||||
|
@ -176,7 +174,7 @@ interface Efl.Ui.Focus.Manager {
|
||||||
setup_on_first_touch {
|
setup_on_first_touch {
|
||||||
[[Called when this manager is set as redirect.
|
[[Called when this manager is set as redirect.
|
||||||
|
|
||||||
In case that this is called as an result of a move call, $direction and $entry
|
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
|
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.
|
set to the object that had this manager as redirect property.
|
||||||
]]
|
]]
|
||||||
|
@ -186,17 +184,17 @@ interface Efl.Ui.Focus.Manager {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
dirty_logic_freeze {
|
dirty_logic_freeze {
|
||||||
[[This disables the cache invalidation when an object is moved.
|
[[Disables the cache invalidation when an object is moved.
|
||||||
|
|
||||||
Even if an object is moved, the focus manager will not recalculate its relations.
|
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
|
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
|
moved the same way, so the relations between the widgets in the set do not change
|
||||||
and the complex calculations can be avoided.
|
and complex calculations can be avoided.
|
||||||
Use @.dirty_logic_unfreeze to re-enable relationship calculation.
|
Use @.dirty_logic_unfreeze to re-enable relationship calculation.
|
||||||
]]
|
]]
|
||||||
}
|
}
|
||||||
dirty_logic_unfreeze {
|
dirty_logic_unfreeze {
|
||||||
[[This enables the cache invalidation when an object is moved.
|
[[Enables the cache invalidation when an object is moved.
|
||||||
|
|
||||||
This is the counterpart to @.dirty_logic_freeze.
|
This is the counterpart to @.dirty_logic_freeze.
|
||||||
]]
|
]]
|
||||||
|
|
|
@ -33,17 +33,17 @@ mixin Efl.Ui.Focus.Object
|
||||||
}
|
}
|
||||||
@property focus_manager {
|
@property focus_manager {
|
||||||
[[This is the focus manager where this focus object is registered in.
|
[[This is the focus manager where this focus object is registered in.
|
||||||
The element which is the $root of a Efl.Ui.Focus.Manager will not
|
The element which is the $root of an @Efl.Ui.Focus.Manager will not
|
||||||
have this focus manager as this object, but rather the second focus
|
have this focus manager as this object, but rather the focus manager
|
||||||
manager where it is registered in.
|
where that is registered in.
|
||||||
]]
|
]]
|
||||||
get {}
|
get {}
|
||||||
values {
|
values {
|
||||||
manager : Efl.Ui.Focus.Manager; [[The manager object]]
|
manager : Efl.Ui.Focus.Manager; [[The manager object.]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@property focus_parent {
|
@property focus_parent {
|
||||||
[[Describes which logical parent is used by this object.]]
|
[[The logical parent used by this object.]]
|
||||||
get {}
|
get {}
|
||||||
values {
|
values {
|
||||||
logical_parent : Efl.Ui.Focus.Object; [[The focus parent.]]
|
logical_parent : Efl.Ui.Focus.Object; [[The focus parent.]]
|
||||||
|
@ -57,8 +57,8 @@ mixin Efl.Ui.Focus.Object
|
||||||
}
|
}
|
||||||
setup_order {
|
setup_order {
|
||||||
[[Tells the object that its children will be queried soon by the focus manager.
|
[[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
|
Overwrite this to have a chance to update the order of the children.
|
||||||
result in undefined behaviour and may cause your system to crash.
|
Deleting items in this call will result in undefined behaviour and may cause your system to crash.
|
||||||
]]
|
]]
|
||||||
}
|
}
|
||||||
setup_order_non_recursive @protected {
|
setup_order_non_recursive @protected {
|
||||||
|
@ -66,8 +66,8 @@ mixin Efl.Ui.Focus.Object
|
||||||
additional recursive calls to @.setup_order will not call this function again.]]
|
additional recursive calls to @.setup_order will not call this function again.]]
|
||||||
}
|
}
|
||||||
on_focus_update @protected {
|
on_focus_update @protected {
|
||||||
[[Virtual function handling focus in/out events on the widget]]
|
[[Virtual function handling focus in/out events on the widget.]]
|
||||||
return: bool; [[$true if this widget can handle focus, $false otherwise]]
|
return: bool; [[$true if this widget can handle focus, $false otherwise.]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
implements {
|
implements {
|
||||||
|
@ -79,10 +79,8 @@ mixin Efl.Ui.Focus.Object
|
||||||
}
|
}
|
||||||
events {
|
events {
|
||||||
focus,changed : bool; [[Emitted if the focus state has changed.]]
|
focus,changed : bool; [[Emitted if the focus state has changed.]]
|
||||||
focus_manager,changed: Efl.Ui.Focus.Manager; [[Emitted when a new manager is
|
focus_manager,changed: Efl.Ui.Focus.Manager; [[Emitted when a new manager is the parent for this object.]]
|
||||||
the parent for this object.]]
|
focus_parent,changed: Efl.Ui.Focus.Object; [[Emitted when a new logical parent should be used.]]
|
||||||
focus_parent,changed: Efl.Ui.Focus.Object; [[Emitted when a new logical
|
|
||||||
parent should be used.]]
|
|
||||||
child_focus,changed: bool; [[Emitted if child_focus has changed.]]
|
child_focus,changed: bool; [[Emitted if child_focus has changed.]]
|
||||||
focus_geometry,changed: Eina.Rect; [[Emitted if focus geometry of this object has changed.]]
|
focus_geometry,changed: Eina.Rect; [[Emitted if focus geometry of this object has changed.]]
|
||||||
}
|
}
|
||||||
|
|
Loading…
Reference in New Issue