From a2f846bffcecfec7d3d73b0f4994666f5dc930ff Mon Sep 17 00:00:00 2001 From: Xavi Artigas Date: Tue, 3 Sep 2019 15:56:23 +0000 Subject: [PATCH] docs: Update focus documentation Lots of improvements to the focus-related classes. Reviewed-by: Marcel Hollerbach Differential Revision: https://phab.enlightenment.org/D9828 --- .../efl_ui_collection_focus_manager.eo | 2 +- .../efl_ui_focus_composition_adapter.eo | 15 ++-- src/lib/elementary/efl_ui_focus_layer.eo | 18 ++--- .../elementary/efl_ui_focus_manager_calc.eo | 80 +++++++++---------- .../efl_ui_focus_manager_root_focus.eo | 4 +- .../elementary/efl_ui_focus_manager_sub.eo | 2 +- .../efl_ui_focus_manager_window_root.eo | 2 +- .../efl_ui_focus_parent_provider_standard.eo | 6 +- src/lib/elementary/efl_ui_focus_util.eo | 22 +++-- .../elementary/efl_ui_widget_focus_manager.eo | 5 +- src/lib/evas/canvas/efl_input_focus.eo | 6 +- 11 files changed, 87 insertions(+), 75 deletions(-) diff --git a/src/lib/elementary/efl_ui_collection_focus_manager.eo b/src/lib/elementary/efl_ui_collection_focus_manager.eo index e015dea7c9..fb3978c5c0 100644 --- a/src/lib/elementary/efl_ui_collection_focus_manager.eo +++ b/src/lib/elementary/efl_ui_collection_focus_manager.eo @@ -1,5 +1,5 @@ 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 { Efl.Ui.Focus.Manager.manager_focus { set; } Efl.Ui.Focus.Manager.request_move; diff --git a/src/lib/elementary/efl_ui_focus_composition_adapter.eo b/src/lib/elementary/efl_ui_focus_composition_adapter.eo index 118f4a3a2a..98d548c89e 100644 --- a/src/lib/elementary/efl_ui_focus_composition_adapter.eo +++ b/src/lib/elementary/efl_ui_focus_composition_adapter.eo @@ -1,23 +1,28 @@ 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 { @property canvas_object { - [[Canvas Object Property]] + [[The canvas object that needs to receive focus.]] values { - v : Efl.Canvas.Object; [[EFL canvas object]] + v : Efl.Canvas.Object; [[The canvas object.]] } } @property focus_manager_object { + [[The focus manager handling the focus for the @.canvas_object.]] set {} values { - v : Efl.Ui.Focus.Manager; + v : Efl.Ui.Focus.Manager; [[The focus manager.]] } } @property focus_manager_parent { + [[The focus parent for the @.canvas_object.]] set {} values { - parent : Efl.Ui.Focus.Object; + parent : Efl.Ui.Focus.Object; [[The focus parent.]] } } } diff --git a/src/lib/elementary/efl_ui_focus_layer.eo b/src/lib/elementary/efl_ui_focus_layer.eo index 05d847ad98..3d07102422 100644 --- a/src/lib/elementary/efl_ui_focus_layer.eo +++ b/src/lib/elementary/efl_ui_focus_layer.eo @@ -1,24 +1,24 @@ 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 - it exists and is visible. It's NOT possible to escape this layer with focus movement. + 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 movements. Once the object is hidden or destroyed the focus will go back to the main window, where it was before. ]] methods { @property enable @protected { - [[Enable property]] + [[Whether the focus layer is enabled. + This can be handled automatically through @Efl.Gfx.Entity.visible and @.behaviour.]] values { - v : bool; [[$true to set enable the layer $false to disable it]] + v : bool; [[$true to set enable.]] } } @property behaviour @protected { - [[Constructor for setting the behaviour of the layer]] + [[Sets the behaviour of the focus layer.]] values { - enable_on_visible : bool; [[$true means layer will set itself once the inheriting widget becomes visible, - $false means the layer isn't enabled automatically]] - cycle : bool; [[If $true the focus will cycle in the layer, if $false]] + enable_on_visible : bool; [[$true means layer will enable itself once the widget becomes visible]] + cycle : bool; [[If $true the focus will cycle (from last object to first, and vice versa) in the layer.]] } } } diff --git a/src/lib/elementary/efl_ui_focus_manager_calc.eo b/src/lib/elementary/efl_ui_focus_manager_calc.eo index d21b925559..279f6da106 100644 --- a/src/lib/elementary/efl_ui_focus_manager_calc.eo +++ b/src/lib/elementary/efl_ui_focus_manager_calc.eo @@ -1,81 +1,77 @@ 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 - direction. You can get items for the currently focused item if - you call request move. + Each registered item will get a target item in each direction. + You can get the target items for the currently focused item by + calling @Efl.Ui.Focus.Manager.request_move. ]] methods { 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 - logical tree. - $redirect will be set as redirect property on that manager, once - $child gets focused. + $parent can not be $null, it will be used as the parent in the logical tree. + $redirect will be set as redirect property on that manager, once $child gets focused. ]] params { - child : Efl.Ui.Focus.Object; [[The object to register]] - parent : Efl.Ui.Focus.Object; [[The parent to use in - the logical tree]] - redirect : Efl.Ui.Focus.Manager; [[The redirect manager to set - once this child is focused can be NULL for no redirect]] + child : Efl.Ui.Focus.Object; [[The object to register.]] + parent : Efl.Ui.Focus.Object; [[The parent to use in the logical tree.]] + redirect : Efl.Ui.Focus.Manager; [[The redirect manager to set 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 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 - of the items that are. + The item can never get focus, it just helps to build the tree. + Compare to @.register. ]] params { - child : Efl.Ui.Focus.Object; [[The object to register]] - parent : Efl.Ui.Focus.Object; [[The parent to use in - the logical tree]] - redirect : Efl.Ui.Focus.Manager; [[The redirect manager to set - once this child is focused can be $null for no redirect]] + child : Efl.Ui.Focus.Object; [[The object to register.]] + parent : Efl.Ui.Focus.Object; [[The parent to use in the logical tree.]] + redirect : Efl.Ui.Focus.Manager; [[The redirect manager to set 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 { - [[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 - 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 { - 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 - 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 { - [[Set a new logical parent for the given child.]] + [[Sets a new logical parent for the given child.]] params { - child : Efl.Ui.Focus.Object; [[The child to update]] - parent : Efl.Ui.Focus.Object; [[The parent which now - will be the logical parent of child]] + child : Efl.Ui.Focus.Object; [[The child to update.]] + parent : Efl.Ui.Focus.Object; [[The parent which now will be the logical parent of child.]] } - return : bool; [[$true if successful, $false otherwise]] + return : bool; [[$true if successful, $false otherwise.]] } update_children { - [[Give the list of children a different order.]] + [[Sets the list of children to a different order.]] params { - parent : Efl.Ui.Focus.Object; [[the parent to update]] - children : list @owned; [[the list with the new order]] + parent : Efl.Ui.Focus.Object; [[The parent to update.]] + children : list @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 { - [[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 { - parent : Efl.Ui.Focus.Object; [[the parent to update]] - children : list @owned; [[the order of items]] + parent : Efl.Ui.Focus.Object; [[The parent to update.]] + children : list @owned; [[The list of objects with the new order.]] } } unregister { diff --git a/src/lib/elementary/efl_ui_focus_manager_root_focus.eo b/src/lib/elementary/efl_ui_focus_manager_root_focus.eo index 0accc6bbe0..1572e77214 100644 --- a/src/lib/elementary/efl_ui_focus_manager_root_focus.eo +++ b/src/lib/elementary/efl_ui_focus_manager_root_focus.eo @@ -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.]] methods { @property canvas_object { - [[The default replacement object for the case that there is no focusable object inside the manager is the root - object. However, you can change this by setting this value to something else. + [[The default replacement object to use when there is no focusable object inside the manager. + 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. ]] values { diff --git a/src/lib/elementary/efl_ui_focus_manager_sub.eo b/src/lib/elementary/efl_ui_focus_manager_sub.eo index 9394080396..eaf00758e7 100644 --- a/src/lib/elementary/efl_ui_focus_manager_sub.eo +++ b/src/lib/elementary/efl_ui_focus_manager_sub.eo @@ -1,6 +1,6 @@ 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. The parent manager is found with the @Efl.Ui.Focus.Object interface of the diff --git a/src/lib/elementary/efl_ui_focus_manager_window_root.eo b/src/lib/elementary/efl_ui_focus_manager_window_root.eo index 278521345e..78e1469f86 100644 --- a/src/lib/elementary/efl_ui_focus_manager_window_root.eo +++ b/src/lib/elementary/efl_ui_focus_manager_window_root.eo @@ -2,7 +2,7 @@ interface Efl.Ui.Focus.Manager_Window_Root { [[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. - 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 ]] diff --git a/src/lib/elementary/efl_ui_focus_parent_provider_standard.eo b/src/lib/elementary/efl_ui_focus_parent_provider_standard.eo index 40cce41449..ba9745d1bb 100644 --- a/src/lib/elementary/efl_ui_focus_parent_provider_standard.eo +++ b/src/lib/elementary/efl_ui_focus_parent_provider_standard.eo @@ -1,5 +1,9 @@ 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 { Efl.Ui.Focus.Parent_Provider.find_logical_parent; } diff --git a/src/lib/elementary/efl_ui_focus_util.eo b/src/lib/elementary/efl_ui_focus_util.eo index 40b38a540e..703ccf5b64 100644 --- a/src/lib/elementary/efl_ui_focus_util.eo +++ b/src/lib/elementary/efl_ui_focus_util.eo @@ -1,24 +1,32 @@ 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 { focus @static { - [[Focus helper method]] + [[Sets the focus to the given object.]] params { - focus_elem : Efl.Ui.Focus.Object; [[Focus element]] + focus_elem : Efl.Ui.Focus.Object; [[Object to receive focus.]] } } active_manager @static { - [[Get the highest manager in the redirect property]] + [[Gets the highest manager in the redirect chain.]] params { - manager : Efl.Ui.Focus.Manager; + manager : Efl.Ui.Focus.Manager; [[Manager to start looking from.]] } return: Efl.Ui.Focus.Manager; } direction_complement @static { + [[Returns the complementary (opposite) focus direction. + + The defined opposites are Left-Right, Up-Down and Next-Previous. + ]] 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.]] } } } diff --git a/src/lib/elementary/efl_ui_widget_focus_manager.eo b/src/lib/elementary/efl_ui_widget_focus_manager.eo index af5a09212f..e5cc1a2691 100644 --- a/src/lib/elementary/efl_ui_widget_focus_manager.eo +++ b/src/lib/elementary/efl_ui_widget_focus_manager.eo @@ -1,13 +1,14 @@ 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 ]] methods { focus_manager_create @protected @pure_virtual { [[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. ]] params { diff --git a/src/lib/evas/canvas/efl_input_focus.eo b/src/lib/evas/canvas/efl_input_focus.eo index eacc99fc79..5de997723f 100644 --- a/src/lib/evas/canvas/efl_input_focus.eo +++ b/src/lib/evas/canvas/efl_input_focus.eo @@ -6,11 +6,9 @@ class Efl.Input.Focus extends Efl.Object implements Efl.Input.Event ]] methods { @property object { - [[The focused object]] + [[The focused object.]] values { - object: Efl.Object; [[The focused object. - In case this represents a canvas - focus the object will be $null]] + object: Efl.Object; [[The focused object, or $NULL if the event comes from the canvas.]] } } }