Improving FocusManager and keyboard navigation (original) (raw)
Is your feature request related to a problem? Please describe.
Handling focus and keyboard navigation in Avalonia is somewhat lacking and often (when porting controls from WinUI) leads to re-inventing the wheel to get a desired behavior. Some panels implement INavigableContainer to try to make it easier, and there's also ICustomKeyboardNavigation, but these feel more like temporary solutions. They also require you to create an entirely new control to get a desired behavior. It'd be a much better solution to implement a better FocusManager and port XYFocusKeyboardNavigation over to make most of this work out of the box. There's also other things like focus type isn't preserved when moving focus scopes (launch a popup with the keyboard, and focus moves as normal pointer/programmatic focus)
I've been reading the UWP docs on all this so I'm mostly raising this issue (besides starting an API spec) to see if there were plans to do this for 11.0 - as I don't want to start looking into this if there are plans already underway. Otherwise, or if nothings been started, I want to look to see how hard it would be and if successful I'll make a PR.
Looking at UWP/WinUI's API for this:
public class FocusManager { // Find the first focusable element within a scope (a specific control, e.g., a grid) or null starts from root public static DependencyObject FindFirstFocusableElement(DependencyObject searchScope);
// Find the last focusable element within a scope (a specific control, e.g., a grid) or null starts from root
public static DependencyObject FindLastFocusableElement(DependencyObject searchScope);
// Retrieves the element that should receive focus based on the specified navigation direction.
public static DependencyObject FindNextElement(FocusNavigationDirection focusNavigationDirection);
// Retrieves the element that should receive focus based on the specified navigation direction (cannot be used with tab navigation, see remarks).
public static DependencyObject FindNextElement(FocusNavigationDirection focusNavigationDirection, FindNextElementOptions focusNavigationOptions);
// Retrieves the element that should receive focus based on the specified navigation direction.
public static UIElement FindNextFocusableElement(FocusNavigationDirection focusNavigationDirection);
// Retrieves the element that should receive focus based on the specified navigation direction and hint rectangle.
public static UIElement FindNextFocusableElement(FocusNavigationDirection focusNavigationDirection, Rect hintRect);
// Retrieves the element in the UI that has focus.
public static object GetFocusedElement();
// Retrieves the focused element within the Xaml island container. (not needed)
public static object GetFocusedElement(XamlRoot xamlRoot);
// Asynchronously attempts to set focus on an element when the application is initialized.
public static IAsyncOperation<FocusMovementResult> TryFocusAsync(DependencyObject element, FocusState value);
// Attempts to change focus from the element with focus to the next focusable element in the specified direction.
public static bool TryMoveFocus(FocusNavigationDirection focusNavigationDirection);
// Attempts to change focus from the element with focus to the next focusable element in the specified direction, using the specified navigation options.
public static bool TryMoveFocus(FocusNavigationDirection focusNavigationDirection, FindNextElementOptions focusNavigationOptions);
// Asynchronously attempts to change focus from the current element with focus to the next focusable element in the specified direction.
public static IAsyncOperation<FocusMovementResult> TryMoveFocusAsync(FocusNavigationDirection focusNavigationDirection);
//Asynchronously attempts to change focus from the current element with focus to the next focusable element in the specified direction and subject to the specified navigation options.
public static IAsyncOperation<FocusMovementResult> TryMoveFocusAsync(FocusNavigationDirection focusNavigationDirection, FindNextElementOptions focusNavigationOptions);
// Occurs before an element actually receives focus. This event is raised synchronously to ensure focus isn't moved while the event is bubbling.
public static event EventHandler<GettingFocusEventArgs> GettingFocus;
// Occurs when an element within a container element (a focus scope) receives focus. This event is raised asynchronously, so focus might move before bubbling is complete.
public static event EventHandler<FocusManagerGotFocusEventArgs> GotFocus;
// Occurs before focus moves from the current element with focus to the target element. This event is raised synchronously to ensure focus isn't moved while the event is bubbling.
public static event EventHandler<LosingFocusEventArgs> LosingFocus;
// Occurs when an element within a container element (a focus scope) loses focus. This event is raised asynchronously, so focus might move again before bubbling is complete.
public static event EventHandler<FocusManagerLostFocusEventArgs> LostFocus;}
The events in FocusManager also exist in UIElement and are raised in the order, where UIElement bubbles up to the FocusManager.
1- UIElement.LosingFocus ->FocusManager.LosingFocus
2- UIElement.GettingFocus -> FocusManager.GettingFocus
3- UIElement.LostFocus (raised by element that lost focus)
4- FocusManager.LostFocus (raised even if UIElement.LostFocus is handled)
5- UIElement.GotFocus (raised by element that received focus)
6- FocusManager.GotFocus (raised even if UIElement.GotFocus is handled)
The duplicate events in UIElement and FocusManger are to handle the case where focus changes scope from main window to a popup, since a new visual tree is created for the popup and the event bubbling wouldn't properly propagate:
https://docs.microsoft.com/en-us/uwp/api/windows.ui.xaml.input.focusmanager?view=winrt-22000
More on focus:
https://github.com/MicrosoftDocs/windows-uwp/blob/docs/hub/apps/design/input/focus-navigation-programmatic.md
XYFocusKeyboardNavigation provides an easy way to activate navigation via the keyboard arrows (or gamepad in UWP) within a specified scope, for example a grid. It can be set to Auto: inherited from a parent control, Disabled: no arrow key 2D navigation, or Enabled: use arrow keys for 2D navigation.
Different strategies exist and can be set for determining how focus moves within an app
Auto: Indicates that navigation strategy is inherited from the element's ancestors. If all ancestors have a value of Auto, the fallback strategy is Projection.NavigationDirectionDistance: Indicates that focus moves to the element closest to the axis of the navigation direction.Projection: Indicates that focus moves to the first element encountered when projecting the edge of the currently focused element in the direction of navigation.RectilinearDistance: Indicates that focus moves to the closest element based on the shortest 2D distance (Manhattan metric).
And for more complex navigation scenarios, XYFocusLeft, XYFocusRight, XYFocusDown, and XYFocusUp exist to specify how XYFocus should move in the given navigation direction