Frame 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// This API is not available in Javascript.
<Frame .../>
- Inheritance
- Attributes
| Device family |
Windows 10 (introduced v10.0.10240.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v1)
|
Inherited Members
Inherited properties
Inherited events
Inherited methods
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.
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.
Constructors
Properties
BackStack BackStack BackStack BackStack
Gets a collection of PageStackEntry instances representing the backward navigation history of the Frame.
public : IVector<PageStackEntry> BackStack { get; }public IList<PageStackEntry> BackStack { get; }Public ReadOnly Property BackStack As IList<PageStackEntry>// This API is not available in Javascript.
- Value
- IVector<PageStackEntry> IList<PageStackEntry> IList<PageStackEntry> IList<PageStackEntry>
The backward navigation stack.
BackStackDepth 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// This API is not available in Javascript.
- Value
- int int int int
The number of entries in the navigation back stack.
BackStackDepthProperty 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// This API is not available in Javascript.
The identifier for the BackStackDepth dependency property.
BackStackProperty 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// This API is not available in Javascript.
The identifier for the BackStack dependency property.
CacheSize 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// This API is not available in Javascript.
<Frame CacheSize="int" />
- Value
- int int int int
The number of pages that can be in the navigation history.
CacheSizeProperty 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// This API is not available in Javascript.
The identifier for the CacheSize dependency property.
CanGoBack CanGoBack CanGoBack CanGoBack
Gets a value that indicates whether there is at least one entry in back navigation history.
public : PlatForm::Boolean CanGoBack { get; }public bool CanGoBack { get; }Public ReadOnly Property CanGoBack As bool// This API is not available in Javascript.
- Value
- PlatForm::Boolean 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.
CanGoBackProperty 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// This API is not available in Javascript.
The identifier for the CanGoBack dependency property.
CanGoForward CanGoForward CanGoForward CanGoForward
Gets a value that indicates whether there is at least one entry in forward navigation history.
public : PlatForm::Boolean CanGoForward { get; }public bool CanGoForward { get; }Public ReadOnly Property CanGoForward As bool// This API is not available in Javascript.
- Value
- PlatForm::Boolean 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.
CanGoForwardProperty 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// This API is not available in Javascript.
The identifier for the CanGoForward dependency property.
CurrentSourcePageType 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// This API is not available in Javascript.
- Value
- TypeName Type Type Type
A type reference for the content that is currently displayed.
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 CurrentSourcePageTypeProperty
Identifies the CurrentSourcePageType dependency property.
public : static DependencyProperty CurrentSourcePageTypeProperty { get; }public static DependencyProperty CurrentSourcePageTypeProperty { get; }Public Static ReadOnly Property CurrentSourcePageTypeProperty As DependencyProperty// This API is not available in Javascript.
The identifier for the CurrentSourcePageType dependency property.
ForwardStack ForwardStack ForwardStack ForwardStack
Gets a collection of PageStackEntry instances representing the forward navigation history of the Frame.
public : IVector<PageStackEntry> ForwardStack { get; }public IList<PageStackEntry> ForwardStack { get; }Public ReadOnly Property ForwardStack As IList<PageStackEntry>// This API is not available in Javascript.
- Value
- IVector<PageStackEntry> IList<PageStackEntry> IList<PageStackEntry> IList<PageStackEntry>
The forward navigation stack.
ForwardStackProperty 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// This API is not available in Javascript.
The identifier for the ForwardStack dependency property.
SourcePageType 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// This API is not available in Javascript.
- Value
- TypeName Type Type Type
A type reference for the current content, or the content to navigate to.
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.
SourcePageTypeProperty 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// This API is not available in Javascript.
The identifier for the SourcePageType dependency property.
Methods
GetNavigationState() GetNavigationState() GetNavigationState() GetNavigationState()
Serializes the Frame navigation history into a string.
public : PlatForm::String GetNavigationState()public string GetNavigationState()Public Function GetNavigationState() As string// This API is not available in Javascript.
The string-form serialized navigation history. See Remarks.
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.
- See Also
GoBack() 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// This API is not available in Javascript.
- See Also
GoBack(NavigationTransitionInfo) 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// This API is not available in Javascript.
- transitionInfoOverride
- NavigationTransitionInfo NavigationTransitionInfo NavigationTransitionInfo NavigationTransitionInfo
Info about the animated transition to use.
- See Also
GoForward() 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// This API is not available in Javascript.
Navigate(TypeName) Navigate(TypeName) Navigate(TypeName) Navigate(TypeName)
Causes the Frame to load content represented by the specified Page.
public : PlatForm::Boolean Navigate(TypeName sourcePageType)public bool Navigate(Type sourcePageType)Public Function Navigate(sourcePageType As Type) As bool// This API is not available in Javascript.
- sourcePageType
- TypeName Type Type Type
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)).
false if a NavigationFailed event handler has set Handled to true; otherwise, true. See Remarks for more info.
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.
- See Also
Navigate(TypeName, Object) 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 : PlatForm::Boolean Navigate(TypeName sourcePageType, PlatForm::Object parameter)public bool Navigate(Type sourcePageType, Object parameter)Public Function Navigate(sourcePageType As Type, parameter As Object) As bool// This API is not available in Javascript.
- sourcePageType
- TypeName Type Type Type
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
- PlatForm::Object Object Object 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.
false if a NavigationFailed event handler has set Handled to true; otherwise, true. See Remarks for more info.
- See Also
Navigate(TypeName, Object, NavigationTransitionInfo) 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 : PlatForm::Boolean Navigate(TypeName sourcePageType, PlatForm::Object parameter, NavigationTransitionInfo infoOverride)public bool Navigate(Type sourcePageType, Object parameter, NavigationTransitionInfo infoOverride)Public Function Navigate(sourcePageType As Type, parameter As Object, infoOverride As NavigationTransitionInfo) As bool// This API is not available in Javascript.
- sourcePageType
- TypeName Type Type Type
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
- PlatForm::Object Object Object 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 NavigationTransitionInfo
Info about the animated transition.
false if a NavigationFailed event handler has set Handled to true; otherwise, true. See Remarks for more info.
- See Also
SetNavigationState(String) SetNavigationState(String) SetNavigationState(String) SetNavigationState(String)
Reads and restores the navigation history of a Frame from a provided serialization string.
public : void SetNavigationState(PlatForm::String navigationState)public void SetNavigationState(String navigationState)Public Function SetNavigationState(navigationState As String) As void// This API is not available in Javascript.
- navigationState
- PlatForm::String String String String
The serialization string that supplies the restore point for navigation history.
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) SetNavigationState(String, Boolean)
Reads and restores the navigation history of a Frame from a provided serialization string.
public : void SetNavigationState(PlatForm::String navigationState, bool suppressNavigate)public void SetNavigationState(String navigationState, Boolean suppressNavigate)Public Function SetNavigationState(navigationState As String, suppressNavigate As Boolean) As void// This API is not available in Javascript.
- navigationState
- PlatForm::String String String String
The serialization string that supplies the restore point for navigation history.
- suppressNavigate
- bool Boolean Boolean Boolean
true to restore navigation history without navigating to the current page; otherwise, false.
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
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 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// This API is not available in Javascript.
<Frame Navigated="eventhandler" />
Navigating Navigating Navigating Navigating
Occurs when a new navigation is requested.
public : event NavigatingCancelEventHandler Navigatingpublic event NavigatingCancelEventHandler NavigatingPublic Event Navigating// This API is not available in Javascript.
<Frame Navigating="eventhandler" />
NavigationFailed NavigationFailed NavigationFailed NavigationFailed
Occurs when an error is raised while navigating to the requested content.
public : event NavigationFailedEventHandler NavigationFailedpublic event NavigationFailedEventHandler NavigationFailedPublic Event NavigationFailed// This API is not available in Javascript.
<Frame NavigationFailed="eventhandler" />
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.
- See Also
NavigationStopped 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// This API is not available in Javascript.
<Frame NavigationStopped="eventhandler" />