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
This commit is contained in:
parent
a26efaeb57
commit
a2f846bffc
|
@ -1,5 +1,5 @@
|
||||||
class @beta Efl.Ui.Collection_Focus_Manager extends Efl.Ui.Focus.Manager_Calc {
|
class @beta Efl.Ui.Collection_Focus_Manager extends Efl.Ui.Focus.Manager_Calc {
|
||||||
[[Internal class which implements collection specific behaviour, cannot be used outside of collection]]
|
[[Internal class which implements collection specific behaviour, cannot be used outside of @Efl.Ui.Collection.]]
|
||||||
implements {
|
implements {
|
||||||
Efl.Ui.Focus.Manager.manager_focus { set; }
|
Efl.Ui.Focus.Manager.manager_focus { set; }
|
||||||
Efl.Ui.Focus.Manager.request_move;
|
Efl.Ui.Focus.Manager.request_move;
|
||||||
|
|
|
@ -1,23 +1,28 @@
|
||||||
class @beta Efl.Ui.Focus.Composition_Adapter extends Efl.Object implements Efl.Ui.Focus.Object
|
class @beta Efl.Ui.Focus.Composition_Adapter extends Efl.Object implements Efl.Ui.Focus.Object
|
||||||
{
|
{
|
||||||
[[EFL UI Focus Composition Adapter class]]
|
[[This class allows an @Efl.Canvas.Object to receive focus as if they were @Efl.Ui.Widget.
|
||||||
|
|
||||||
|
Instantiate this class and manually set its properties to the appropriate objects.
|
||||||
|
]]
|
||||||
methods {
|
methods {
|
||||||
@property canvas_object {
|
@property canvas_object {
|
||||||
[[Canvas Object Property]]
|
[[The canvas object that needs to receive focus.]]
|
||||||
values {
|
values {
|
||||||
v : Efl.Canvas.Object; [[EFL canvas object]]
|
v : Efl.Canvas.Object; [[The canvas object.]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@property focus_manager_object {
|
@property focus_manager_object {
|
||||||
|
[[The focus manager handling the focus for the @.canvas_object.]]
|
||||||
set {}
|
set {}
|
||||||
values {
|
values {
|
||||||
v : Efl.Ui.Focus.Manager;
|
v : Efl.Ui.Focus.Manager; [[The focus manager.]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@property focus_manager_parent {
|
@property focus_manager_parent {
|
||||||
|
[[The focus parent for the @.canvas_object.]]
|
||||||
set {}
|
set {}
|
||||||
values {
|
values {
|
||||||
parent : Efl.Ui.Focus.Object;
|
parent : Efl.Ui.Focus.Object; [[The focus parent.]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
|
@ -1,24 +1,24 @@
|
||||||
mixin @beta Efl.Ui.Focus.Layer requires Efl.Ui.Widget extends Efl.Ui.Widget_Focus_Manager {
|
mixin @beta Efl.Ui.Focus.Layer requires Efl.Ui.Widget extends Efl.Ui.Widget_Focus_Manager {
|
||||||
[[This defines the inheriting widget as focus layer.
|
[[This defines the widget as a focus layer.
|
||||||
|
|
||||||
A focus layer is the uppermost one which receives input and handles all focus related events for as long as
|
A focus layer is the uppermost widget which receives input and handles all focus related events for as long as
|
||||||
it exists and is visible. It's NOT possible to escape this layer with focus movement.
|
it exists and is visible. It's not possible to escape this layer with focus movements.
|
||||||
|
|
||||||
Once the object is hidden or destroyed the focus will go back to the main window, where it was before.
|
Once the object is hidden or destroyed the focus will go back to the main window, where it was before.
|
||||||
]]
|
]]
|
||||||
methods {
|
methods {
|
||||||
@property enable @protected {
|
@property enable @protected {
|
||||||
[[Enable property]]
|
[[Whether the focus layer is enabled.
|
||||||
|
This can be handled automatically through @Efl.Gfx.Entity.visible and @.behaviour.]]
|
||||||
values {
|
values {
|
||||||
v : bool; [[$true to set enable the layer $false to disable it]]
|
v : bool; [[$true to set enable.]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@property behaviour @protected {
|
@property behaviour @protected {
|
||||||
[[Constructor for setting the behaviour of the layer]]
|
[[Sets the behaviour of the focus layer.]]
|
||||||
values {
|
values {
|
||||||
enable_on_visible : bool; [[$true means layer will set itself once the inheriting widget becomes visible,
|
enable_on_visible : bool; [[$true means layer will enable itself once the widget becomes visible]]
|
||||||
$false means the layer isn't enabled automatically]]
|
cycle : bool; [[If $true the focus will cycle (from last object to first, and vice versa) in the layer.]]
|
||||||
cycle : bool; [[If $true the focus will cycle in the layer, if $false]]
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
|
@ -1,81 +1,77 @@
|
||||||
class @beta Efl.Ui.Focus.Manager_Calc extends Efl.Object implements Efl.Ui.Focus.Manager {
|
class @beta Efl.Ui.Focus.Manager_Calc extends Efl.Object implements Efl.Ui.Focus.Manager {
|
||||||
[[Calculates the directions of Efl.Ui.Focus.Direction
|
[[Calculates the elements present in each @Efl.Ui.Focus.Direction.
|
||||||
|
|
||||||
Each registered item will get an other registered object in each
|
Each registered item will get a target item in each direction.
|
||||||
direction. You can get items for the currently focused item if
|
You can get the target items for the currently focused item by
|
||||||
you call request move.
|
calling @Efl.Ui.Focus.Manager.request_move.
|
||||||
]]
|
]]
|
||||||
methods {
|
methods {
|
||||||
register {
|
register {
|
||||||
[[Register a new item in the graph.
|
[[Registers a new item in the graph.
|
||||||
|
|
||||||
$parent can not be $null, it will be used as the parent in the
|
$parent can not be $null, it will be used as the parent in the logical tree.
|
||||||
logical tree.
|
$redirect will be set as redirect property on that manager, once $child gets focused.
|
||||||
$redirect will be set as redirect property on that manager, once
|
|
||||||
$child gets focused.
|
|
||||||
]]
|
]]
|
||||||
params {
|
params {
|
||||||
child : Efl.Ui.Focus.Object; [[The object to register]]
|
child : Efl.Ui.Focus.Object; [[The object to register.]]
|
||||||
parent : Efl.Ui.Focus.Object; [[The parent to use in
|
parent : Efl.Ui.Focus.Object; [[The parent to use in the logical tree.]]
|
||||||
the logical tree]]
|
redirect : Efl.Ui.Focus.Manager; [[The redirect manager to set once this child is focused.
|
||||||
redirect : Efl.Ui.Focus.Manager; [[The redirect manager to set
|
Can be $NULL for no redirect.]]
|
||||||
once this child is focused can be NULL for no redirect]]
|
|
||||||
}
|
}
|
||||||
return : bool; [[$true if successful, $false otherwise]]
|
return : bool; [[$true if successful, $false otherwise.]]
|
||||||
}
|
}
|
||||||
register_logical {
|
register_logical {
|
||||||
[[Register a new item only for the logical parent.
|
[[Registers a new logical item in the graph.
|
||||||
|
|
||||||
The item can never get focus, it just helps to build a tree out
|
The item can never get focus, it just helps to build the tree.
|
||||||
of the items that are.
|
Compare to @.register.
|
||||||
]]
|
]]
|
||||||
params {
|
params {
|
||||||
child : Efl.Ui.Focus.Object; [[The object to register]]
|
child : Efl.Ui.Focus.Object; [[The object to register.]]
|
||||||
parent : Efl.Ui.Focus.Object; [[The parent to use in
|
parent : Efl.Ui.Focus.Object; [[The parent to use in the logical tree.]]
|
||||||
the logical tree]]
|
redirect : Efl.Ui.Focus.Manager; [[The redirect manager to set once this child is focused.
|
||||||
redirect : Efl.Ui.Focus.Manager; [[The redirect manager to set
|
Can be $NULL for no redirect.]]
|
||||||
once this child is focused can be $null for no redirect]]
|
|
||||||
}
|
}
|
||||||
return : bool; [[$true if successful, $false otherwise]]
|
return : bool; [[$true if successful, $false otherwise.]]
|
||||||
}
|
}
|
||||||
update_redirect {
|
update_redirect {
|
||||||
[[Set a new redirect object for the given child.
|
[[Sets a new redirect object for the given child.
|
||||||
|
|
||||||
Once $child is focused the redirect manager will be set
|
Once $child is focused the redirect manager will be set
|
||||||
in the redirect property. Set redirect to $null if nothing should happen.
|
in the redirect property. Set redirect to $NULL if nothing should happen.
|
||||||
]]
|
]]
|
||||||
params {
|
params {
|
||||||
child : Efl.Ui.Focus.Object; [[The child to update]]
|
child : Efl.Ui.Focus.Object; [[The child to update.]]
|
||||||
redirect : Efl.Ui.Focus.Manager; [[Once $child is focused this
|
redirect : Efl.Ui.Focus.Manager; [[Once $child is focused this
|
||||||
element will be set as redirect]]
|
element will be set as redirect.]]
|
||||||
}
|
}
|
||||||
return : bool; [[$true if successful, $false otherwise]]
|
return : bool; [[$true if successful, $false otherwise.]]
|
||||||
}
|
}
|
||||||
update_parent {
|
update_parent {
|
||||||
[[Set a new logical parent for the given child.]]
|
[[Sets a new logical parent for the given child.]]
|
||||||
params {
|
params {
|
||||||
child : Efl.Ui.Focus.Object; [[The child to update]]
|
child : Efl.Ui.Focus.Object; [[The child to update.]]
|
||||||
parent : Efl.Ui.Focus.Object; [[The parent which now
|
parent : Efl.Ui.Focus.Object; [[The parent which now will be the logical parent of child.]]
|
||||||
will be the logical parent of child]]
|
|
||||||
}
|
}
|
||||||
return : bool; [[$true if successful, $false otherwise]]
|
return : bool; [[$true if successful, $false otherwise.]]
|
||||||
}
|
}
|
||||||
update_children {
|
update_children {
|
||||||
[[Give the list of children a different order.]]
|
[[Sets the list of children to a different order.]]
|
||||||
params {
|
params {
|
||||||
parent : Efl.Ui.Focus.Object; [[the parent to update]]
|
parent : Efl.Ui.Focus.Object; [[The parent to update.]]
|
||||||
children : list<Efl.Ui.Focus.Object> @owned; [[the list with the new order]]
|
children : list<Efl.Ui.Focus.Object> @owned; [[The list of children with the new order.]]
|
||||||
}
|
}
|
||||||
return : bool; [[$true if successful, $false otherwise]]
|
return : bool; [[$true if successful, $false otherwise.]]
|
||||||
}
|
}
|
||||||
update_order {
|
update_order {
|
||||||
[[Give the given order to the parent's child.
|
[[Sets the list of children to a different order.
|
||||||
|
|
||||||
Children from the list which are not true children are ignored.
|
Objects in the list which are not children of $parent are ignored.
|
||||||
|
Compare to @.update_children.
|
||||||
]]
|
]]
|
||||||
params {
|
params {
|
||||||
parent : Efl.Ui.Focus.Object; [[the parent to update]]
|
parent : Efl.Ui.Focus.Object; [[The parent to update.]]
|
||||||
children : list<Efl.Ui.Focus.Object> @owned; [[the order of items]]
|
children : list<Efl.Ui.Focus.Object> @owned; [[The list of objects with the new order.]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
unregister {
|
unregister {
|
||||||
|
|
|
@ -2,8 +2,8 @@ class @beta Efl.Ui.Focus.Manager_Root_Focus extends Efl.Ui.Focus.Manager_Calc {
|
||||||
[[This class ensures that the root is at least focusable, if nothing else is focusable.]]
|
[[This class ensures that the root is at least focusable, if nothing else is focusable.]]
|
||||||
methods {
|
methods {
|
||||||
@property canvas_object {
|
@property canvas_object {
|
||||||
[[The default replacement object for the case that there is no focusable object inside the manager is the root
|
[[The default replacement object to use when there is no focusable object inside the manager.
|
||||||
object. However, you can change this by setting this value to something else.
|
You can change this object by setting this value to something else.
|
||||||
$null means that the same value as @Efl.Ui.Focus.Manager.root will be used.
|
$null means that the same value as @Efl.Ui.Focus.Manager.root will be used.
|
||||||
]]
|
]]
|
||||||
values {
|
values {
|
||||||
|
|
|
@ -1,6 +1,6 @@
|
||||||
mixin @beta Efl.Ui.Focus.Manager_Sub requires Efl.Object extends Efl.Ui.Focus.Manager
|
mixin @beta Efl.Ui.Focus.Manager_Sub requires Efl.Object extends Efl.Ui.Focus.Manager
|
||||||
{
|
{
|
||||||
[[A class that automatically registers its border elements in the parent manager
|
[[A class that automatically registers its border elements in the parent manager.
|
||||||
|
|
||||||
This sub manager will register its border elements on the parent manager.
|
This sub manager will register its border elements on the parent manager.
|
||||||
The parent manager is found with the @Efl.Ui.Focus.Object interface of the
|
The parent manager is found with the @Efl.Ui.Focus.Object interface of the
|
||||||
|
|
|
@ -2,7 +2,7 @@ interface Efl.Ui.Focus.Manager_Window_Root {
|
||||||
[[An interface to indicate the end of a focus chain.
|
[[An interface to indicate the end of a focus chain.
|
||||||
|
|
||||||
Focus managers are ensuring that if they give focus to something, that is registered in the upper focus manager.
|
Focus managers are ensuring that if they give focus to something, that is registered in the upper focus manager.
|
||||||
The most upper focus manager does not need to do that, and can implement this interface to indicate that.
|
The uppermost focus manager does not need to do that, and can implement this interface to indicate so.
|
||||||
|
|
||||||
@since 1.22
|
@since 1.22
|
||||||
]]
|
]]
|
||||||
|
|
|
@ -1,5 +1,9 @@
|
||||||
class @beta Efl.Ui.Focus.Parent_Provider_Standard extends Efl.Object implements Efl.Ui.Focus.Parent_Provider {
|
class @beta Efl.Ui.Focus.Parent_Provider_Standard extends Efl.Object implements Efl.Ui.Focus.Parent_Provider {
|
||||||
[[EFL UI Focus Parent Provider Standard Class]]
|
[[EFL UI Focus Parent Provider Standard Class.
|
||||||
|
|
||||||
|
This is the default implementation for the @Efl.Ui.Focus.Parent_Provider interface. It simply uses
|
||||||
|
the widget's parent as the focus parent.
|
||||||
|
]]
|
||||||
implements {
|
implements {
|
||||||
Efl.Ui.Focus.Parent_Provider.find_logical_parent;
|
Efl.Ui.Focus.Parent_Provider.find_logical_parent;
|
||||||
}
|
}
|
||||||
|
|
|
@ -1,24 +1,32 @@
|
||||||
class @beta Efl.Ui.Focus.Util extends Efl.Object {
|
class @beta Efl.Ui.Focus.Util extends Efl.Object {
|
||||||
[[EFL UI Focus Util class]]
|
[[EFL UI Focus Utility class.
|
||||||
|
|
||||||
|
This class contains a series of static methods that simplify common focus management operations.
|
||||||
|
There's no need to instantiate this class.
|
||||||
|
]]
|
||||||
methods {
|
methods {
|
||||||
focus @static {
|
focus @static {
|
||||||
[[Focus helper method]]
|
[[Sets the focus to the given object.]]
|
||||||
params {
|
params {
|
||||||
focus_elem : Efl.Ui.Focus.Object; [[Focus element]]
|
focus_elem : Efl.Ui.Focus.Object; [[Object to receive focus.]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
active_manager @static {
|
active_manager @static {
|
||||||
[[Get the highest manager in the redirect property]]
|
[[Gets the highest manager in the redirect chain.]]
|
||||||
params {
|
params {
|
||||||
manager : Efl.Ui.Focus.Manager;
|
manager : Efl.Ui.Focus.Manager; [[Manager to start looking from.]]
|
||||||
}
|
}
|
||||||
return: Efl.Ui.Focus.Manager;
|
return: Efl.Ui.Focus.Manager;
|
||||||
}
|
}
|
||||||
direction_complement @static {
|
direction_complement @static {
|
||||||
|
[[Returns the complementary (opposite) focus direction.
|
||||||
|
|
||||||
|
The defined opposites are Left-Right, Up-Down and Next-Previous.
|
||||||
|
]]
|
||||||
params {
|
params {
|
||||||
dir : Efl.Ui.Focus.Direction;
|
dir : Efl.Ui.Focus.Direction; [[Direction to complement.]]
|
||||||
}
|
}
|
||||||
return: Efl.Ui.Focus.Direction;
|
return: Efl.Ui.Focus.Direction; [[The opposite direction.]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
|
@ -1,13 +1,14 @@
|
||||||
mixin Efl.Ui.Widget_Focus_Manager requires Efl.Ui.Widget extends Efl.Ui.Focus.Manager
|
mixin Efl.Ui.Widget_Focus_Manager requires Efl.Ui.Widget extends Efl.Ui.Focus.Manager
|
||||||
{
|
{
|
||||||
[[
|
[[Helper mixin for widgets which also can act as focus managers.
|
||||||
|
|
||||||
@since 1.22
|
@since 1.22
|
||||||
]]
|
]]
|
||||||
methods {
|
methods {
|
||||||
focus_manager_create @protected @pure_virtual {
|
focus_manager_create @protected @pure_virtual {
|
||||||
[[If the widget needs a focus manager, this function will be called.
|
[[If the widget needs a focus manager, this function will be called.
|
||||||
|
|
||||||
It can be used and overriden to inject your own manager or set
|
It can be used and overridden to inject your own manager or set
|
||||||
custom options on the focus manager.
|
custom options on the focus manager.
|
||||||
]]
|
]]
|
||||||
params {
|
params {
|
||||||
|
|
|
@ -6,11 +6,9 @@ class Efl.Input.Focus extends Efl.Object implements Efl.Input.Event
|
||||||
]]
|
]]
|
||||||
methods {
|
methods {
|
||||||
@property object {
|
@property object {
|
||||||
[[The focused object]]
|
[[The focused object.]]
|
||||||
values {
|
values {
|
||||||
object: Efl.Object; [[The focused object.
|
object: Efl.Object; [[The focused object, or $NULL if the event comes from the canvas.]]
|
||||||
In case this represents a canvas
|
|
||||||
focus the object will be $null]]
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
Loading…
Reference in New Issue