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 {
|
||||
[[Structure holding the graph of relations between focusable objects.
|
||||
]]
|
||||
right : list<Efl.Ui.Focus.Object> @owned; [[List of objects on the right side]]
|
||||
left : list<Efl.Ui.Focus.Object> @owned; [[List of objects on the left side]]
|
||||
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 is the information from]]
|
||||
logical : bool; [[$true if this node is only logical]]
|
||||
position_in_history : int; [[The position in the history stack]]
|
||||
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
|
||||
[[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]]
|
||||
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
|
||||
[[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 non-logical widgets,
|
||||
a logical widget cannot receive focus whereas a non-logical one can.
|
||||
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 {
|
||||
[[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 means all changes between the last flush and now are computed.
|
||||
This means all changes since last flush are computed.
|
||||
]]
|
||||
params {
|
||||
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.]]
|
||||
}
|
||||
request_move {
|
||||
[[Return the object in the $direction from $child.]]
|
||||
[[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 non-logical.
|
||||
Note, in a @.move call no logical node will get focus.]]
|
||||
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
|
||||
[[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 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.
|
||||
]]
|
||||
|
||||
|
@ -81,14 +81,14 @@ interface Efl.Ui.Focus.Manager {
|
|||
anymore.
|
||||
]]
|
||||
values {
|
||||
redirect : Efl.Ui.Focus.Manager; [[The redirect manager.]]
|
||||
redirect : Efl.Ui.Focus.Manager; [[The new focus manager.]]
|
||||
}
|
||||
}
|
||||
@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 call flushes all changes. See @Efl.Ui.Focus.Manager.move
|
||||
This call flushes all changes. See @Efl.Ui.Focus.Manager.move.
|
||||
]]
|
||||
get {}
|
||||
values {
|
||||
|
@ -97,7 +97,7 @@ interface Efl.Ui.Focus.Manager {
|
|||
}
|
||||
}
|
||||
@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,
|
||||
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.]]
|
||||
}
|
||||
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 {
|
||||
|
@ -116,21 +116,19 @@ interface Efl.Ui.Focus.Manager {
|
|||
This property can only be set once.
|
||||
]]
|
||||
set {
|
||||
return : bool; [[If $true, this is the root node]]
|
||||
return : bool; [[$true on success, $false if it had already been set.]]
|
||||
}
|
||||
|
||||
get {}
|
||||
|
||||
values {
|
||||
root : Efl.Ui.Focus.Object; [[Will be registered into
|
||||
this manager object.]]
|
||||
root : Efl.Ui.Focus.Object; [[Object to register as the root of this manager object.]]
|
||||
}
|
||||
}
|
||||
request_subchild {
|
||||
[[Return the widget in the direction next.
|
||||
[[Returns the widget in the direction next.
|
||||
|
||||
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.
|
||||
]]
|
||||
params {
|
||||
|
@ -139,9 +137,9 @@ interface Efl.Ui.Focus.Manager {
|
|||
return : Efl.Ui.Focus.Object; [[Child of passed parameter.]]
|
||||
}
|
||||
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 {
|
||||
child : Efl.Ui.Focus.Object; [[The child object to inspect.]]
|
||||
|
@ -150,7 +148,7 @@ interface Efl.Ui.Focus.Manager {
|
|||
starting from $child.]]
|
||||
}
|
||||
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
|
||||
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.]]
|
||||
}
|
||||
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
|
||||
will be removed from the remembered list.
|
||||
|
||||
|
@ -167,7 +165,7 @@ interface Efl.Ui.Focus.Manager {
|
|||
]]
|
||||
}
|
||||
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.
|
||||
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 {
|
||||
[[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
|
||||
set to the object that had this manager as redirect property.
|
||||
]]
|
||||
|
@ -186,17 +184,17 @@ interface Efl.Ui.Focus.Manager {
|
|||
}
|
||||
}
|
||||
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.
|
||||
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 the complex calculations can be avoided.
|
||||
and complex calculations can be avoided.
|
||||
Use @.dirty_logic_unfreeze to re-enable relationship calculation.
|
||||
]]
|
||||
}
|
||||
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.
|
||||
]]
|
||||
|
|
|
@ -33,17 +33,17 @@ mixin Efl.Ui.Focus.Object
|
|||
}
|
||||
@property focus_manager {
|
||||
[[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
|
||||
have this focus manager as this object, but rather the second focus
|
||||
manager where it is registered in.
|
||||
The element which is the $root of an @Efl.Ui.Focus.Manager will not
|
||||
have this focus manager as this object, but rather the focus manager
|
||||
where that is registered in.
|
||||
]]
|
||||
get {}
|
||||
values {
|
||||
manager : Efl.Ui.Focus.Manager; [[The manager object]]
|
||||
manager : Efl.Ui.Focus.Manager; [[The manager object.]]
|
||||
}
|
||||
}
|
||||
@property focus_parent {
|
||||
[[Describes which logical parent is used by this object.]]
|
||||
[[The logical parent used by this object.]]
|
||||
get {}
|
||||
values {
|
||||
logical_parent : Efl.Ui.Focus.Object; [[The focus parent.]]
|
||||
|
@ -57,8 +57,8 @@ mixin Efl.Ui.Focus.Object
|
|||
}
|
||||
setup_order {
|
||||
[[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
|
||||
result in undefined behaviour and may cause your system to crash.
|
||||
Overwrite this to have a chance to update the order of the children.
|
||||
Deleting items in this call will result in undefined behaviour and may cause your system to crash.
|
||||
]]
|
||||
}
|
||||
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.]]
|
||||
}
|
||||
on_focus_update @protected {
|
||||
[[Virtual function handling focus in/out events on the widget]]
|
||||
return: bool; [[$true if this widget can handle focus, $false otherwise]]
|
||||
[[Virtual function handling focus in/out events on the widget.]]
|
||||
return: bool; [[$true if this widget can handle focus, $false otherwise.]]
|
||||
}
|
||||
}
|
||||
implements {
|
||||
|
@ -79,10 +79,8 @@ mixin Efl.Ui.Focus.Object
|
|||
}
|
||||
events {
|
||||
focus,changed : bool; [[Emitted if the focus state has changed.]]
|
||||
focus_manager,changed: Efl.Ui.Focus.Manager; [[Emitted when a new manager is
|
||||
the parent for this object.]]
|
||||
focus_parent,changed: Efl.Ui.Focus.Object; [[Emitted when a new logical
|
||||
parent should be used.]]
|
||||
focus_manager,changed: Efl.Ui.Focus.Manager; [[Emitted when a new manager is the parent for this object.]]
|
||||
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.]]
|
||||
focus_geometry,changed: Eina.Rect; [[Emitted if focus geometry of this object has changed.]]
|
||||
}
|
||||
|
|
Loading…
Reference in New Issue