Frame Frame Frame Class

Definition

Displays Page instances, supports navigation to new pages, and maintains a navigation history to support forward and backward navigation.

public class Frame : ContentControl, IFrame, IFrame2, IFrame3, IFrame4, INavigatepublic class Frame : ContentControl, IFrame, IFrame2, IFrame3, IFrame4, INavigatePublic Class Frame Inherits ContentControl Implements IFrame, IFrame2, IFrame3, IFrame4, INavigate
<Frame .../>
Inheritance
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Inherited Members

Inherited properties

Inherited events

Inherited methods

Remarks

You use the Frame control to support navigation to Page instances. You create as many different page types as needed to present the content in your app, and then navigate to those pages by calling the Navigate method and passing in the type of the page to navigate to. You can also pass in a parameter object to initialize the page to a particular state.

The frame maintains a history of pages it has navigated to. You can get the type of the current page through the CurrentSourcePageType property, and navigate forward or backward with the GoBack and GoForward methods. The CanGoBack and CanGoForward properties indicate whether a page is available in the desired direction. One common practice is to bind the IsEnabled properties of navigation buttons to CanGoBack and CanGoForward so that users can't navigate to a page that doesn't exist.

You can handle the Navigating, Navigated, NavigationStopped, and NavigationFailed events to perform high-level tasks such as starting and stopping a "navigation in progress" animation or displaying an error message. For page-level tasks, override the page OnNavigatedTo, OnNavigatingFrom, and OnNavigatedFrom methods. This is useful to perform tasks such as initializing and saving the page state.

By default, each navigation creates a new instance of the specific Page subclass requested, and disposes the previous page instance. This happens even when navigating back to a previously visited page or when the new page type is the same as the previous page type. Apps that involve frequent navigation to the same pages can cache and reuse the page instances to make navigation more efficient. To do this, set the CacheSize property to specify how many pages to cache. For each page type that you want to cache, you must also set the Page.NavigationCacheMode property to either Enabled or Required. Pages with a Required cache mode are cached regardless of the CacheSize value, and do not count against the CacheSize total.

INavigate

The INavigate interface is mainly infrastructure. It's not expected that typical app will implement this interface.

Examples

The following code example is from the blank app template in Microsoft Visual Studio. This code shows how an OnLaunched method override initializes the app window. If the app is resuming after being suspended, then the window might already be initialized. If not, this code sets the app window to a new Frame, then navigates the frame to the default initial page.

protected override void OnLaunched(LaunchActivatedEventArgs e)
{
    Frame rootFrame = Window.Current.Content as Frame;

    // Do not repeat app initialization when the Window already has content,
    // just ensure that the window is active.
    if (rootFrame == null)
    {
        // Create a Frame to act as the navigation context and navigate to the first page.
        rootFrame = new Frame();

        rootFrame.NavigationFailed += OnNavigationFailed;

        if (e.PreviousExecutionState == ApplicationExecutionState.Terminated)
        {
            //TODO: Load state from previously suspended application.
        }

        // Place the frame in the current Window.
        Window.Current.Content = rootFrame;
    }

    if (rootFrame.Content == null)
    {
        // When the navigation stack isn't restored navigate to the first page,
        // configuring the new page by passing required information as a navigation
        // parameter.
        rootFrame.Navigate(typeof(MainPage), e.Arguments);
    }

    // Ensure the current window is active.
    Window.Current.Activate();
}

void OnNavigationFailed(object sender, NavigationFailedEventArgs e)
{
    throw new Exception("Failed to load Page " + e.SourcePageType.FullName);
}
Protected Overrides Sub OnLaunched(e As LaunchActivatedEventArgs)
    Dim rootFrame As Frame = TryCast(Window.Current.Content, Frame)

    ' Do not repeat app initialization when the Window already has content,
    ' just ensure that the window is active.

    If rootFrame Is Nothing Then
        ' Create a Frame to act as the navigation context and navigate to the first page.
        rootFrame = New Frame()

        AddHandler rootFrame.NavigationFailed, AddressOf OnNavigationFailed

        If e.PreviousExecutionState = ApplicationExecutionState.Terminated Then
            ' TODO: Load state from previously suspended application.
        End If
        ' Place the frame in the current Window.
        Window.Current.Content = rootFrame
    End If
    If rootFrame.Content Is Nothing Then
        ' When the navigation stack isn't restored navigate to the first page,
        ' configuring the new page by passing required information as a navigation
        ' parameter.
        rootFrame.Navigate(GetType(MainPage), e.Arguments)
    End If

    ' Ensure the current window is active.
    Window.Current.Activate()
End Sub

Private Sub OnNavigationFailed(sender As Object, e As NavigationFailedEventArgs)
    Throw New Exception("Failed to load Page " + e.SourcePageType.FullName)
End Sub
void App::OnLaunched(LaunchActivatedEventArgs^ e)
{
 auto rootFrame = dynamic_cast<Frame^>(Window::Current->Content);

 // Do not repeat app initialization when the Window already has content,
 // just ensure that the window is active
 if (rootFrame == nullptr)
 {
  // Create a Frame to act as the navigation context and associate it with
  // a SuspensionManager key
  rootFrame = ref new Frame();

  rootFrame->NavigationFailed += ref new Windows::UI::Xaml::Navigation::NavigationFailedEventHandler(this, &App::OnNavigationFailed);

  if (e->PreviousExecutionState == ApplicationExecutionState::Terminated)
  {
   // TODO: Restore the saved session state only when appropriate, scheduling the
   // final launch steps after the restore is complete
  }

  if (rootFrame->Content == nullptr)
  {
   // When the navigation stack isn't restored navigate to the first page,
   // configuring the new page by passing required information as a navigation
   // parameter
   rootFrame->Navigate(TypeName(MainPage::typeid), e->Arguments);
  }
  // Place the frame in the current Window
  Window::Current->Content = rootFrame;
  // Ensure the current window is active
  Window::Current->Activate();
 }
 else
 {
  if (rootFrame->Content == nullptr)
  {
   // When the navigation stack isn't restored navigate to the first page,
   // configuring the new page by passing required information as a navigation
   // parameter
   rootFrame->Navigate(TypeName(MainPage::typeid), e->Arguments);
  }
  // Ensure the current window is active
  Window::Current->Activate();
 }
}

void App::OnNavigationFailed(Platform::Object ^sender, Windows::UI::Xaml::Navigation::NavigationFailedEventArgs ^e)
{
 throw ref new FailureException("Failed to load Page " + e->SourcePageType.Name);
}

For a complete sample that uses many of the Page and Frame features together, see XAML Navigation sample.

Constructors

Frame() Frame() Frame()

Initializes a new instance of the Frame class.

public Frame()public Frame()Public Sub New()
Attributes

Properties

BackStack BackStack BackStack

Gets a collection of PageStackEntry instances representing the backward navigation history of the Frame.

public IVector<PageStackEntry> BackStack { get; }public IVector<PageStackEntry> BackStack { get; }Public ReadOnly Property BackStack As IVector<PageStackEntry>
Value

The backward navigation stack.

Attributes

BackStackDepth BackStackDepth BackStackDepth

Gets the number of entries in the navigation back stack.

public int BackStackDepth { get; }public int BackStackDepth { get; }Public ReadOnly Property BackStackDepth As int
Value
int int int

The number of entries in the navigation back stack.

Attributes

BackStackDepthProperty BackStackDepthProperty BackStackDepthProperty

Identifies the BackStackDepth dependency property.

public static DependencyProperty BackStackDepthProperty { get; }public static DependencyProperty BackStackDepthProperty { get; }Public Static ReadOnly Property BackStackDepthProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the BackStackDepth dependency property.

Attributes

BackStackProperty BackStackProperty BackStackProperty

Identifies the BackStack dependency property.

public static DependencyProperty BackStackProperty { get; }public static DependencyProperty BackStackProperty { get; }Public Static ReadOnly Property BackStackProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the BackStack dependency property.

Attributes

CacheSize CacheSize CacheSize

Gets or sets the number of pages in the navigation history that can be cached for the frame.

public int CacheSize { get; set; }public int CacheSize { get; set; }Public ReadWrite Property CacheSize As int
<Frame CacheSize="int" />
Value
int int int

The number of pages that can be in the navigation history.

Attributes

CacheSizeProperty CacheSizeProperty CacheSizeProperty

Identifies the CacheSize dependency property.

public static DependencyProperty CacheSizeProperty { get; }public static DependencyProperty CacheSizeProperty { get; }Public Static ReadOnly Property CacheSizeProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the CacheSize dependency property.

Attributes

CanGoBack CanGoBack CanGoBack

Gets a value that indicates whether there is at least one entry in back navigation history.

public bool CanGoBack { get; }public bool CanGoBack { get; }Public ReadOnly Property CanGoBack As bool
Value
bool bool bool

true if there is at least one entry in back navigation history; false if there are no entries in back navigation history or the Frame does not own its own navigation history.

Attributes

CanGoBackProperty CanGoBackProperty CanGoBackProperty

Identifies the CanGoBack dependency property.

public static DependencyProperty CanGoBackProperty { get; }public static DependencyProperty CanGoBackProperty { get; }Public Static ReadOnly Property CanGoBackProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the CanGoBack dependency property.

Attributes

CanGoForward CanGoForward CanGoForward

Gets a value that indicates whether there is at least one entry in forward navigation history.

public bool CanGoForward { get; }public bool CanGoForward { get; }Public ReadOnly Property CanGoForward As bool
Value
bool bool bool

true if there is at least one entry in forward navigation history; false if there are no entries in forward navigation history or the Frame does not own its own navigation history.

Attributes

CanGoForwardProperty CanGoForwardProperty CanGoForwardProperty

Identifies the CanGoForward dependency property.

public static DependencyProperty CanGoForwardProperty { get; }public static DependencyProperty CanGoForwardProperty { get; }Public Static ReadOnly Property CanGoForwardProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the CanGoForward dependency property.

Attributes

CurrentSourcePageType CurrentSourcePageType CurrentSourcePageType

Gets a type reference for the content that is currently displayed.

public TypeName CurrentSourcePageType { get; }public Type CurrentSourcePageType { get; }Public ReadOnly Property CurrentSourcePageType As Type
Value
TypeName TypeName TypeName

A type reference for the content that is currently displayed.

Attributes

Remarks

CurrentSourcePageType and SourcePageType are normally the same value. However, if the frame calls Navigate and the navigation is still in progress, the CurrentSourcePageType is the value before the navigation and the SourcePageType is the value being navigated to.

Tip

If you are programming using a Microsoft .NET language (C# or Microsoft Visual Basic), the TypeName type projects as System.Type. When programming using C#, it is common to use the typeof operator to get references to the System.Type of a type. In Microsoft Visual Basic, use GetType.

See Also

CurrentSourcePageTypeProperty CurrentSourcePageTypeProperty CurrentSourcePageTypeProperty

Identifies the CurrentSourcePageType dependency property.

public static DependencyProperty CurrentSourcePageTypeProperty { get; }public static DependencyProperty CurrentSourcePageTypeProperty { get; }Public Static ReadOnly Property CurrentSourcePageTypeProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the CurrentSourcePageType dependency property.

Attributes

ForwardStack ForwardStack ForwardStack

Gets a collection of PageStackEntry instances representing the forward navigation history of the Frame.

public IVector<PageStackEntry> ForwardStack { get; }public IVector<PageStackEntry> ForwardStack { get; }Public ReadOnly Property ForwardStack As IVector<PageStackEntry>
Value

The forward navigation stack.

Attributes

ForwardStackProperty ForwardStackProperty ForwardStackProperty

Identifies the ForwardStack dependency property.

public static DependencyProperty ForwardStackProperty { get; }public static DependencyProperty ForwardStackProperty { get; }Public Static ReadOnly Property ForwardStackProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the ForwardStack dependency property.

Attributes

SourcePageType SourcePageType SourcePageType

Gets or sets a type reference of the current content, or the content that should be navigated to.

public TypeName SourcePageType { get; set; }public Type SourcePageType { get; set; }Public ReadWrite Property SourcePageType As Type
Value
TypeName TypeName TypeName

A type reference for the current content, or the content to navigate to.

Attributes

Remarks

CurrentSourcePageType and SourcePageType are normally the same value. However, if the frame calls Navigate and the navigation is still in progress, the CurrentSourcePageType is the value before the navigation and the SourcePageType is the value being navigated to.

Tip

If you are programming using a Microsoft .NET language (C# or Visual Basic), the TypeName type projects as System.Type. When programming using C#, it is common to use the typeof operator to get references to the System.Type of a type. In Visual Basic, use GetType.

SourcePageType can be set in XAML, using string-to-type conversion that's interpreted using XAML namespace mappings, but that's rarely done. It's a better practice to have code at the app level that tracks activation and whether a suspended app is resuming, which then uses Frame.Navigate to set the current page. The Microsoft Visual Studio templates often produce such code for you. For this same reason, it's also rare to set SourcePageType as an alternative to calling Frame.Navigate, which also specifies a Page by type reference. If you do set a value for SourcePageType in XAML, you typically need to use a prefix such as "local:" that's defined in the same XAML construct. You need the prefix to map a XAML namespace that references the code namespace where your page partial class is defined. For more info, see XAML namespaces and namespace mapping.

A more typical scenario for SourcePageType in code is to only read its value, and not set it. For example you might compare SourcePageType for the current page in the Frame with items in the navigation stacks (BackStack, ForwardStack ) to see if there are existing entries for that same Page.

See Also

SourcePageTypeProperty SourcePageTypeProperty SourcePageTypeProperty

Identifies the SourcePageType dependency property.

public static DependencyProperty SourcePageTypeProperty { get; }public static DependencyProperty SourcePageTypeProperty { get; }Public Static ReadOnly Property SourcePageTypeProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the SourcePageType dependency property.

Attributes

Methods

GetNavigationState() GetNavigationState() GetNavigationState()

Serializes the Frame navigation history into a string.

public string GetNavigationState()public string GetNavigationState()Public Function GetNavigationState() As string
Returns
string string string

The string-form serialized navigation history. See Remarks.

Attributes

Remarks

This method is useful to restore the navigation state of your app after it has been suspended and resumed. When your app is suspended, call GetNavigationState and save the return value. When your app is resumed, call SetNavigationState and pass it the saved value.

Calling this method will call Page.OnNavigatedFrom for the current page using NavigationMode.Forward. GetNavigationState is usually called when the application is being suspended, so the current page is navigated away from.

Note

The serialization format used by these methods is for internal use only. Your app should not form any dependencies on it. Additionally, this format supports serialization only for basic types like string, char, numeric and GUID types.

GoBack() GoBack() GoBack()

Navigates to the most recent item in back navigation history, if a Frame manages its own navigation history.

public void GoBack()public void GoBack()Public Function GoBack() As void
Attributes

GoBack(NavigationTransitionInfo) GoBack(NavigationTransitionInfo) GoBack(NavigationTransitionInfo)

Navigates to the most recent item in back navigation history, if a Frame manages its own navigation history, and specifies the animated transition to use.

public void GoBack(NavigationTransitionInfo transitionInfoOverride)public void GoBack(NavigationTransitionInfo transitionInfoOverride)Public Function GoBack(transitionInfoOverride As NavigationTransitionInfo) As void
Parameters
transitionInfoOverride
NavigationTransitionInfo NavigationTransitionInfo NavigationTransitionInfo

Info about the animated transition to use.

Attributes

GoForward() GoForward() GoForward()

Navigates to the most recent item in forward navigation history, if a Frame manages its own navigation history.

public void GoForward()public void GoForward()Public Function GoForward() As void
Attributes

Navigate(TypeName) Navigate(TypeName) Navigate(TypeName)

Causes the Frame to load content represented by the specified Page.

public bool Navigate(TypeName sourcePageType)public bool Navigate(TypeName sourcePageType)Public Function Navigate(sourcePageType As TypeName) As bool
Parameters
sourcePageType
TypeName TypeName TypeName

The page to navigate to, specified as a type reference to its partial class type. (A type reference is given as System.Type for Microsoft .NET, or a TypeName helper struct for Visual C++ component extensions (C++/CX)).

Returns
bool bool bool

false if a NavigationFailed event handler has set Handled to true; otherwise, true. See Remarks for more info.

Attributes

Remarks

You handle the NavigationFailed event to respond to navigation failure. You can handle the failure directly in the event handler, or you can set the NavigationFailedEventArgs.Handled property to true and use the Navigate method return value to respond to the failure.

Apps typically use GetNavigationState to serialize the frame’s state when the app suspends. You can do this directly in your app code or indirectly by using the SuspensionManager class generated by the Visual Studio templates. To enable frame state serialization using GetNavigationState, you must use only basic types for the navigation parameter, such as string, char, numeric, and GUID types. Otherwise GetNavigationState will throw an exception when the app suspends. The parameter can have other types if you do not use GetNavigationState.

The parameter value can have a complex type if you do not use GetNavigationState. However, you should still use only basic types in order to avoid excess memory usage caused by the frame’s navigation stack holding a reference to the parameter. A preferred approach is to not pass the actual object, but instead pass an identifier that you can use to look up the object in the target landing page. For example, instead of passing a Customer object, pass a reference to the CustomerID, then look up the Customer after the navigation is complete.

Tip

If you are programming using a Microsoft .NET language (C# or Microsoft Visual Basic), the TypeName type projects as System.Type. When programming using C#, it is common to use the typeof operator to get references to the System.Type of a type. In Microsoft Visual Basic, use GetType. If you're using Visual C++ component extensions (C++/CX), where you'll need to create a TypeName helper struct, you can use the typeid component extension.

Navigate(TypeName, Object) Navigate(TypeName, Object) Navigate(TypeName, Object)

Causes the Frame to load content represented by the specified Page, also passing a parameter to be interpreted by the target of the navigation.

public bool Navigate(TypeName sourcePageType, Object parameter)public bool Navigate(TypeName sourcePageType, Object parameter)Public Function Navigate(sourcePageType As TypeName, parameter As Object) As bool
Parameters
sourcePageType
TypeName TypeName TypeName

The page to navigate to, specified as a type reference to its partial class type. (A type reference is given as System.Type for Microsoft .NET, or a TypeName helper struct for Visual C++ component extensions (C++/CX)).

parameter
System.Object System.Object System.Object

The navigation parameter to pass to the target page; must have a basic type (string, char, numeric, or GUID) to support parameter serialization using GetNavigationState.

Returns
bool bool bool

false if a NavigationFailed event handler has set Handled to true; otherwise, true. See Remarks for more info.

Attributes
See Also

Navigate(TypeName, Object, NavigationTransitionInfo) Navigate(TypeName, Object, NavigationTransitionInfo) Navigate(TypeName, Object, NavigationTransitionInfo)

Causes the Frame to load content represented by the specified Page -derived data type, also passing a parameter to be interpreted by the target of the navigation, and a value indicating the animated transition to use.

public bool Navigate(TypeName sourcePageType, Object parameter, NavigationTransitionInfo infoOverride)public bool Navigate(TypeName sourcePageType, Object parameter, NavigationTransitionInfo infoOverride)Public Function Navigate(sourcePageType As TypeName, parameter As Object, infoOverride As NavigationTransitionInfo) As bool
Parameters
sourcePageType
TypeName TypeName TypeName

The page to navigate to, specified as a type reference to its partial class type. (A type reference is given as System.Type for Microsoft .NET, or a TypeName helper struct for Visual C++ component extensions (C++/CX)).

parameter
System.Object System.Object System.Object

The navigation parameter to pass to the target page; must have a basic type (string, char, numeric, or GUID) to support parameter serialization using GetNavigationState.

infoOverride
NavigationTransitionInfo NavigationTransitionInfo NavigationTransitionInfo

Info about the animated transition.

Returns
bool bool bool

false if a NavigationFailed event handler has set Handled to true; otherwise, true. See Remarks for more info.

Attributes

SetNavigationState(String) SetNavigationState(String) SetNavigationState(String)

Reads and restores the navigation history of a Frame from a provided serialization string.

public void SetNavigationState(String navigationState)public void SetNavigationState(String navigationState)Public Function SetNavigationState(navigationState As String) As void
Parameters
navigationState
System.String System.String System.String

The serialization string that supplies the restore point for navigation history.

Attributes

Remarks

This method is useful to restore the navigation state of your app after it has been suspended and resumed. When your app is suspended, call GetNavigationState and save the return value. When your app is resumed, call SetNavigationState and pass it the saved value.

Calling SetNavigationState will call Page.OnNavigatedTo for the current page, with NavigationMode.Back. SetNavigationState is usually called when the application is being resumed, so the current page is navigated to.

SetNavigationState(String, Boolean) SetNavigationState(String, Boolean) SetNavigationState(String, Boolean)

Reads and restores the navigation history of a Frame from a provided serialization string.

public void SetNavigationState(String navigationState, Boolean suppressNavigate)public void SetNavigationState(String navigationState, Boolean suppressNavigate)Public Function SetNavigationState(navigationState As String, suppressNavigate As Boolean) As void
Parameters
navigationState
System.String System.String System.String

The serialization string that supplies the restore point for navigation history.

suppressNavigate
System.Boolean System.Boolean System.Boolean

true to restore navigation history without navigating to the current page; otherwise, false.

Attributes

Remarks

If you call SetNavigationState with the suppressNavigate parameter set to true, Page.OnNavigatedTo is not called for the current page. The current page is also put into the BackStack. When suppressing the transition, also be sure to use GoBack or GoForward to navigate to the correct page in the navigation history. NavigateTo is also supported, however the forward stack will be cleared when it is used.

Events

Navigated Navigated Navigated

Occurs when the content that is being navigated to has been found and is available from the Content property, although it may not have completed loading.

public event NavigatedEventHandler Navigatedpublic event NavigatedEventHandler NavigatedPublic Event Navigated
<Frame Navigated="eventhandler" />
Attributes

Navigating Navigating Navigating

Occurs when a new navigation is requested.

public event NavigatingCancelEventHandler Navigatingpublic event NavigatingCancelEventHandler NavigatingPublic Event Navigating
<Frame Navigating="eventhandler" />
Attributes

NavigationFailed NavigationFailed NavigationFailed

Occurs when an error is raised while navigating to the requested content.

public event NavigationFailedEventHandler NavigationFailedpublic event NavigationFailedEventHandler NavigationFailedPublic Event NavigationFailed
<Frame NavigationFailed="eventhandler" />
Attributes

Remarks

Currently, you must handle NavigationFailed to respond when the Navigate method fails. You can handle the failure directly in the event handler, or you can set the NavigationFailedEventArgs.Handled property to true and use the Navigate method return value to respond to the failure.

NavigationStopped NavigationStopped NavigationStopped

Occurs when

a new navigation is requested while a current navigation is in progress.

public event NavigationStoppedEventHandler NavigationStoppedpublic event NavigationStoppedEventHandler NavigationStoppedPublic Event NavigationStopped
<Frame NavigationStopped="eventhandler" />
Attributes

See Also