FocusManager FocusManager FocusManager FocusManager Class

Definition

Some information relates to pre-released product which may be substantially modified before it’s commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Prerelease APIs are identified by a Prerelease label.

[Contains prerelease APIs.]
A helper class that enables getting and setting the UI element that has focus.

public : sealed class FocusManager : IFocusManager
struct winrt::Windows::UI::Xaml::Input::FocusManager : IFocusManager
public sealed class FocusManager : IFocusManager
Public NotInheritable Class FocusManager Implements IFocusManager
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Examples

Use TryMoveFocus to traverse between UI elements using the arrow keys.

private void Page_KeyUp(object sender, KeyRoutedEventArgs e)
{
   if (e.Key == Windows.System.VirtualKey.Up)
   {
      // Mimic Shift+Tab when user hits up arrow key.
      FocusManager.TryMoveFocus(FocusNavigationDirection.Previous);
   }
   else if (e.Key == Windows.System.VirtualKey.Down)
   {
      // Mimic Tab when user hits down arrow key.
      FocusManager.TryMoveFocus(FocusNavigationDirection.Next);
   }
}

Methods

FindFirstFocusableElement(DependencyObject) FindFirstFocusableElement(DependencyObject) FindFirstFocusableElement(DependencyObject) FindFirstFocusableElement(DependencyObject)

Retrieves the first element that can receive focus based on the specified scope.

public : static DependencyObject FindFirstFocusableElement(DependencyObject searchScope)
DependencyObject FindFirstFocusableElement(DependencyObject searchScope) const;
public static DependencyObject FindFirstFocusableElement(DependencyObject searchScope)
Public Static Function FindFirstFocusableElement(searchScope As DependencyObject) As DependencyObject
Parameters
searchScope
DependencyObject DependencyObject

The root object from which to search. If null, the search scope is the current window.

Returns

The first focusable object.

Additional features and requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)

FindLastFocusableElement(DependencyObject) FindLastFocusableElement(DependencyObject) FindLastFocusableElement(DependencyObject) FindLastFocusableElement(DependencyObject)

Retrieves the last element that can receive focus based on the specified scope.

public : static DependencyObject FindLastFocusableElement(DependencyObject searchScope)
DependencyObject FindLastFocusableElement(DependencyObject searchScope) const;
public static DependencyObject FindLastFocusableElement(DependencyObject searchScope)
Public Static Function FindLastFocusableElement(searchScope As DependencyObject) As DependencyObject
Parameters
searchScope
DependencyObject DependencyObject

The root object from which to search. If null, the search scope is the current window.

Returns

The last focusable object.

Additional features and requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)

FindNextElement(FocusNavigationDirection) FindNextElement(FocusNavigationDirection) FindNextElement(FocusNavigationDirection) FindNextElement(FocusNavigationDirection)

Retrieves the element that will receive focus based on the specified navigation direction.

public : static DependencyObject FindNextElement(FocusNavigationDirection focusNavigationDirection)
DependencyObject FindNextElement(FocusNavigationDirection focusNavigationDirection) const;
public static DependencyObject FindNextElement(FocusNavigationDirection focusNavigationDirection)
Public Static Function FindNextElement(focusNavigationDirection As FocusNavigationDirection) As DependencyObject
Parameters
focusNavigationDirection
FocusNavigationDirection FocusNavigationDirection

The direction that focus moves from element to element within the app UI.

Returns

The next object to receive focus.

Additional features and requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)

Remarks

We recommend using this method instead of FindNextFocusableElement(FocusNavigationDirection).

FindNextElement(FocusNavigationDirection, FindNextElementOptions) FindNextElement(FocusNavigationDirection, FindNextElementOptions) FindNextElement(FocusNavigationDirection, FindNextElementOptions) FindNextElement(FocusNavigationDirection, FindNextElementOptions)

Retrieves the element that will receive focus based on the specified navigation direction.

public : static DependencyObject FindNextElement(FocusNavigationDirection focusNavigationDirection, FindNextElementOptions focusNavigationOptions)
DependencyObject FindNextElement(FocusNavigationDirection focusNavigationDirection, FindNextElementOptions focusNavigationOptions) const;
public static DependencyObject FindNextElement(FocusNavigationDirection focusNavigationDirection, FindNextElementOptions focusNavigationOptions)
Public Static Function FindNextElement(focusNavigationDirection As FocusNavigationDirection, focusNavigationOptions As FindNextElementOptions) As DependencyObject
Parameters
focusNavigationDirection
FocusNavigationDirection FocusNavigationDirection

The direction that focus moves from element to element within the app UI.

focusNavigationOptions
FindNextElementOptions FindNextElementOptions

The options to help identify the next element to receive focus with keyboard/controller/remote navigation.

Returns

The next object to receive focus.

Additional features and requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)

Remarks

We recommend using this method instead of FindNextFocusableElement(FocusNavigationDirection, Rect).

FindNextFocusableElement(FocusNavigationDirection) FindNextFocusableElement(FocusNavigationDirection) FindNextFocusableElement(FocusNavigationDirection) FindNextFocusableElement(FocusNavigationDirection)

Retrieves the element that will receive focus based on the specified navigation direction.

public : static UIElement FindNextFocusableElement(FocusNavigationDirection focusNavigationDirection)
UIElement FindNextFocusableElement(FocusNavigationDirection focusNavigationDirection) const;
public static UIElement FindNextFocusableElement(FocusNavigationDirection focusNavigationDirection)
Public Static Function FindNextFocusableElement(focusNavigationDirection As FocusNavigationDirection) As UIElement
Parameters
focusNavigationDirection
FocusNavigationDirection FocusNavigationDirection

The direction that focus moves from element to element within the app UI.

Returns

null if focus cannot be set in the specified direction.

See Also

FindNextFocusableElement(FocusNavigationDirection, Rect) FindNextFocusableElement(FocusNavigationDirection, Rect) FindNextFocusableElement(FocusNavigationDirection, Rect) FindNextFocusableElement(FocusNavigationDirection, Rect)

Retrieves the element that will receive focus based on the specified navigation direction and hint rectangle.

public : static UIElement FindNextFocusableElement(FocusNavigationDirection focusNavigationDirection, Rect hintRect)
UIElement FindNextFocusableElement(FocusNavigationDirection focusNavigationDirection, Rect hintRect) const;
public static UIElement FindNextFocusableElement(FocusNavigationDirection focusNavigationDirection, Rect hintRect)
Public Static Function FindNextFocusableElement(focusNavigationDirection As FocusNavigationDirection, hintRect As Rect) As UIElement
Parameters
focusNavigationDirection
FocusNavigationDirection FocusNavigationDirection

The direction that focus moves from element to element within the app UI.

hintRect
Rect Rect

A bounding rectangle used to influence which element is most likely to be considered the next to receive focus. Examples where this can be useful include:

  • When no element currently has focus, specifying a small rectangle at a screen location of (-1, -1) starts focus from the upper left corner of the display.
  • In a program guide where you want to ensure programs at the current time receive focus. (The focus algorithm might favor shows at a later time based on a number of factors.)
Returns

null if focus cannot be set in the specified direction.

See Also

GetFocusedElement() GetFocusedElement() GetFocusedElement() GetFocusedElement()

Retrieves the element in the UI that has focus.

public : static Platform::Object GetFocusedElement()
winrt::Windows::Foundation::IInspectable GetFocusedElement() const;
public static object GetFocusedElement()
Public Static Function GetFocusedElement() As object
Returns
object object

The object that has focus. Typically, this is a Control class.

TryFocusAsync(DependencyObject, FocusState) TryFocusAsync(DependencyObject, FocusState) TryFocusAsync(DependencyObject, FocusState) TryFocusAsync(DependencyObject, FocusState)

Prerelease. Asynchronously attempts to set focus on an element when the application is initialized.

public : static IAsyncOperation<FocusMovementResult> TryFocusAsync(DependencyObject element, FocusState value)
IAsyncOperation<FocusMovementResult> TryFocusAsync(DependencyObject element, FocusState value) const;
public static IAsyncOperation<FocusMovementResult> TryFocusAsync(DependencyObject element, FocusState value)
Public Static Function TryFocusAsync(element As DependencyObject, value As FocusState) As IAsyncOperation( Of FocusMovementResult )
Parameters
element
DependencyObject DependencyObject

The object on which to set focus.

value
FocusState FocusState

One of the values from the FocusState enumeration that specify how an elemnent can obtain focus.

Returns
Additional features and requirements
Device family
Windows 10 Insider Preview (introduced v10.0.17095.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v6)

Examples

Here, we show how to set focus on a WebView object, and, if that fails, restore focus to the original element.

async void MoveFocus(WebView webView)) 
{ 
    FocusMovementResult result; 
    result = await FocusManager.TryFocusAsync(webView, FocusState.Programmatic); 
    if (!result.Succeeded) 
    { 
        // Restore focus to original element. 
        this.Focus(FocusState.Programmatic); 
    } 
}

Remarks

Some objects, such as a WebView, can run in either the app process or in a separate process (see WebViewExecutionMode.SeparateProcess ).

When an object runs in the app process, the following focus events occur as expected for both the previously focused object and the newly focused object:

However, if the newly focused object is running in a separate process some of these event behaviors can differ.

  • GetFocusedElement does not return the newly focused object until the TryFocusAsync operation completes.
  • The control losing focus receives its LosingFocus event synchronously, but does not receive LostFocus until the asynchronous operation completes.
  • The control getting focus receieves its GettingFocus event synchronously, but does not receive GotFocus until the asynchronous operation completes.

TryFocusAsync completes synchronously when called on an element running in the app process.

TryMoveFocus(FocusNavigationDirection) TryMoveFocus(FocusNavigationDirection) TryMoveFocus(FocusNavigationDirection) TryMoveFocus(FocusNavigationDirection)

Attempts to change focus from the element with focus to the next focusable element in the specified direction.

public : static Platform::Boolean TryMoveFocus(FocusNavigationDirection focusNavigationDirection)
bool TryMoveFocus(FocusNavigationDirection focusNavigationDirection) const;
public static bool TryMoveFocus(FocusNavigationDirection focusNavigationDirection)
Public Static Function TryMoveFocus(focusNavigationDirection As FocusNavigationDirection) As bool
Parameters
focusNavigationDirection
FocusNavigationDirection FocusNavigationDirection

The direction to traverse (in tab order).

Returns
bool bool

true if focus moved; otherwise, false.

Remarks

The tab order is the order in which a user moves from one control to another by pressing the Tab key (forward) or Shift+Tab (backward).

This method uses tab order sequence and behavior to traverse all focusable elements in the UI.

If the focus is on the first element in the tab order and FocusNavigationDirection.Previous is specified, focus moves to the last element.

If the focus is on the last element in the tab order and FocusNavigationDirection.Next is specified, focus moves to the first element.

TryMoveFocus(FocusNavigationDirection, FindNextElementOptions) TryMoveFocus(FocusNavigationDirection, FindNextElementOptions) TryMoveFocus(FocusNavigationDirection, FindNextElementOptions) TryMoveFocus(FocusNavigationDirection, FindNextElementOptions)

Attempts to change focus from the element with focus to the next focusable element in both the specified direction and using the specified navigation options.

public : static Platform::Boolean TryMoveFocus(FocusNavigationDirection focusNavigationDirection, FindNextElementOptions focusNavigationOptions)
bool TryMoveFocus(FocusNavigationDirection focusNavigationDirection, FindNextElementOptions focusNavigationOptions) const;
public static bool TryMoveFocus(FocusNavigationDirection focusNavigationDirection, FindNextElementOptions focusNavigationOptions)
Public Static Function TryMoveFocus(focusNavigationDirection As FocusNavigationDirection, focusNavigationOptions As FindNextElementOptions) As bool
Parameters
focusNavigationDirection
FocusNavigationDirection FocusNavigationDirection

The direction to traverse (in tab order).

focusNavigationOptions
FindNextElementOptions FindNextElementOptions

The options to help identify the next element to receive focus with keyboard/controller/remote navigation.

Returns
bool bool

true if focus moved; otherwise, false.

Additional features and requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)

Remarks

The tab order is the order in which a user moves from one control to another by pressing the Tab key (forward) or Shift+Tab (backward).

This method uses tab order sequence and behavior to traverse all focusable elements in the UI.

If the focus is on the first element in the tab order and FocusNavigationDirection.Previous is specified, focus moves to the last element.

If the focus is on the last element in the tab order and FocusNavigationDirection.Next is specified, focus moves to the first element.

TryMoveFocusAsync(FocusNavigationDirection) TryMoveFocusAsync(FocusNavigationDirection) TryMoveFocusAsync(FocusNavigationDirection) TryMoveFocusAsync(FocusNavigationDirection)

Prerelease. 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)
IAsyncOperation<FocusMovementResult> TryMoveFocusAsync(FocusNavigationDirection focusNavigationDirection) const;
public static IAsyncOperation<FocusMovementResult> TryMoveFocusAsync(FocusNavigationDirection focusNavigationDirection)
Public Static Function TryMoveFocusAsync(focusNavigationDirection As FocusNavigationDirection) As IAsyncOperation( Of FocusMovementResult )
Parameters
focusNavigationDirection
FocusNavigationDirection FocusNavigationDirection

The direction that focus moves from element to element within the app UI.

Returns
Additional features and requirements
Device family
Windows 10 Insider Preview (introduced v10.0.17095.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v6)

Examples

Here, we show how to set focus on a WebView object, and, if that fails, restore focus to the original element.

async void MoveFocus(WebView webView)) 
{ 
    FocusMovementResult result; 
    result = await FocusManager.TryFocusAsync(webView, FocusState.Programmatic); 
    if (!result.Succeeded) 
    { 
        // Restore focus to original element. 
        this.Focus(FocusState.Programmatic); 
    } 
}

Remarks

TryFocusAsync completes synchronously when called on an element running in the app process.

See Also

TryMoveFocusAsync(FocusNavigationDirection, FindNextElementOptions) TryMoveFocusAsync(FocusNavigationDirection, FindNextElementOptions) TryMoveFocusAsync(FocusNavigationDirection, FindNextElementOptions) TryMoveFocusAsync(FocusNavigationDirection, FindNextElementOptions)

Prerelease. 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)
IAsyncOperation<FocusMovementResult> TryMoveFocusAsync(FocusNavigationDirection focusNavigationDirection, FindNextElementOptions focusNavigationOptions) const;
public static IAsyncOperation<FocusMovementResult> TryMoveFocusAsync(FocusNavigationDirection focusNavigationDirection, FindNextElementOptions focusNavigationOptions)
Public Static Function TryMoveFocusAsync(focusNavigationDirection As FocusNavigationDirection, focusNavigationOptions As FindNextElementOptions) As IAsyncOperation( Of FocusMovementResult )
Parameters
focusNavigationDirection
FocusNavigationDirection FocusNavigationDirection

The direction that focus moves from element to element within the app UI.

focusNavigationOptions
FindNextElementOptions FindNextElementOptions

The navigation options used to identify the focus candidate.

Returns
Additional features and requirements
Device family
Windows 10 Insider Preview (introduced v10.0.17095.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v6)

Examples

Here, we show how to set focus on a WebView object, and, if that fails, restore focus to the original element.

async void MoveFocus(WebView webView)) 
{ 
    FocusMovementResult result; 
    result = await FocusManager.TryFocusAsync(webView, FocusState.Programmatic); 
    if (!result.Succeeded) 
    { 
        // Restore focus to original element. 
        this.Focus(FocusState.Programmatic); 
    } 
}

Remarks

TryFocusAsync completes synchronously when called on an element running in the app process.

See Also