Page Page Page Class

Represents content that a Frame control can navigate to.

Syntax

Declaration

public class Pagepublic class PagePublic Class Page
<Page .../>
-or-
<Page ...>
  singleRootElement
</Page>

Inheritance Hierarchy

Inherited Members

Inherited properties

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,
Tag
Tag
Tag
, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Inherited events

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Inherited methods

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Remarks

The Page class encapsulates content that the Frame control can navigate to. You will generally create your own page types that derive from the Page class, and use Page (or a custom type) as the root element for the XAML-declared content.

Page is a UserControl, therefore you can declare a single XAML object element as Content for the Page. Most pages contain more than one UI element in total. You typically use a panel or items control as the immediate child of a Page, so that you can have the page contain and compose multiple elements of a UI.

You can also specify app bars, with the TopAppBar and BottomAppBar properties. You must use property element syntax for these properties to contain the AppBar values in XAML.

You can create new pages using the Add | New Item menu option for your project in Microsoft Visual Studio. These all create XAML files where the root is a Page class, and the code-behind class derives from Page. Some page item templates add navigation support and additional features. For more info on the Microsoft Visual Studio item templates, see C#, VB, and C++ item templates for .

Create as many pages as you need to present the content in your app, and then navigate to those pages by calling the Navigate(TypeName, Object, NavigationTransitionInfo) method and passing in a type reference for the page to navigate to. By type reference, we mean an instance of a class that identifies a type in the type system, for the language you are using. For Microsoft .NET that type is System.Type, and you can get a System.Type reference from a page class' name by using the operators typeof (C#) or GetType (Visual Basic). For Visual C++ component extensions (C++/CX), use TypeName. Initialize a TypeName by using the typeid of a class. typeid is a component extension that can be called for any runtime class.

Through Navigate(TypeName, Object, NavigationTransitionInfo), you can also pass in a parameter object to initialize the page to a particular state. The parameter object is loosely typed but serialization of navigation history only works for basic types (see Remarks in Navigate(TypeName, Object) ). Pages that are navigated to as part of an activation generally pass data from the activation. Other navigation scenarios such as search result pages also have expectations of what info will be contained in the parameter.

By default, each navigation creates a new instance of the specific Page (or 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 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.

You can override the page OnNavigatedTo(NavigationEventArgs), OnNavigatingFrom(NavigatingCancelEventArgs), and OnNavigatedFrom(NavigationEventArgs) methods to perform tasks such as initializing and saving the page state. OnNavigatingFrom(NavigatingCancelEventArgs) can be used to cancel a navigation by setting a Cancel property in the event data from your handler.

Examples

The following code example shows an abridged version of the OnLaunched(LaunchActivatedEventArgs) method override generated for the blank application template in Visual Studio. This code shows how the content of the app window is set to a new Frame, which is then navigated to the default initial Page.

        protected override void OnLaunched(LaunchActivatedEventArgs e)
        {
            Frame rootFrame = Window.Current.Content as Frame;
            if (rootFrame == null)
            {
                // Create a Frame to act as the navigation context and navigate to the first page
                rootFrame = new Frame();
                // 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();
        }
    Protected Overrides Sub OnLaunched(e As Windows.ApplicationModel.Activation.LaunchActivatedEventArgs)
        Dim rootFrame As Frame = TryCast(Window.Current.Content, Frame)
        If rootFrame Is Nothing Then
            ' Create a Frame to act as the navigation context and navigate to the first page
            rootFrame = New Frame()
            ' 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
void App::OnLaunched(Windows::ApplicationModel::Activation::LaunchActivatedEventArgs^ e)
{
    auto rootFrame = dynamic_cast<Frame^>(Window::Current->Content);
    if (rootFrame == nullptr)
    {
        rootFrame = ref new Frame();
        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 case omitted
}

For example code that adds an AppBar to a page, see Quickstart: adding app bars or How to share an app bar across pages. For example code that uses NavigationCacheMode, see Navigation or XAML Navigation sample.

Constructors summary

Initializes a new instance of the Page class.

Properties summary

Gets a reference to an AppBar displayed at the bottom of the page, if any.

Identifies the BottomAppBar dependency property.

Gets the controlling Frame for the Page content.

Identifies the Frame dependency property.

Gets or sets the navigation mode that indicates whether this Page is cached, and the period of time that the cache entry should persist.

Gets a reference to an AppBar displayed at the top of the page, if any.

Identifies the TopAppBar dependency property.

Methods summary

Invoked immediately after the Page is unloaded and is no longer the current source of a parent Frame.

Invoked when the Page is loaded and becomes the current source of a parent Frame.

Invoked immediately before the Page is unloaded and is no longer the current source of a parent Frame.

Constructors

  • Page()
    Page()
    Page()
    Page()

    Initializes a new instance of the Page class.

    public Page()public New()Public Sub New()public Page()

Properties

  • BottomAppBar
    BottomAppBar
    BottomAppBar
    BottomAppBar

    Gets a reference to an AppBar displayed at the bottom of the page, if any.

    public AppBar BottomAppBar { get; set; }public AppBar BottomAppBar { get; set; }Public ReadWrite Property BottomAppBar As AppBarpublic AppBar BottomAppBar { get; set; }
    <Page ...>
      <Page.BottomAppBar>
        <AppBar .../>
      </Page.BottomAppBar>
    </Page>
    

    Property Value

    Remarks

    In XAML, make sure you specify the Page.BottomAppBar property element in the same area as other property elements that may already be defined, like Page.TopAppBar or Page.Resources. The XAML language enforces that you can't mix the property elements between the XAML content that is setting Content, such as the typical root Grid element. For more info on XAML syntax, see XAML syntax guide.

    Examples

    For example code that adds an AppBar to a page, see Quickstart: adding app bars or How to share an app bar across pages. For a complete sample that uses many of the Page and Frame features together, see XAML Navigation sample.

  • BottomAppBarProperty
    BottomAppBarProperty
    BottomAppBarProperty
    BottomAppBarProperty

    Identifies the BottomAppBar dependency property.

    public static DependencyProperty BottomAppBarProperty { get; }public static DependencyProperty BottomAppBarProperty { get; }Public Static ReadOnly Property BottomAppBarProperty As DependencyPropertypublic static DependencyProperty BottomAppBarProperty { get; }

    Property Value

  • Frame
    Frame
    Frame
    Frame

    Gets the controlling Frame for the Page content.

    public Frame Frame { get; }public Frame Frame { get; }Public ReadOnly Property Frame As Framepublic Frame Frame { get; }

    Property Value

  • FrameProperty
    FrameProperty
    FrameProperty
    FrameProperty

    Identifies the Frame dependency property.

    public static DependencyProperty FrameProperty { get; }public static DependencyProperty FrameProperty { get; }Public Static ReadOnly Property FrameProperty As DependencyPropertypublic static DependencyProperty FrameProperty { get; }

    Property Value

  • NavigationCacheMode
    NavigationCacheMode
    NavigationCacheMode
    NavigationCacheMode

    Gets or sets the navigation mode that indicates whether this Page is cached, and the period of time that the cache entry should persist.

    public NavigationCacheMode NavigationCacheMode { get; set; }public NavigationCacheMode NavigationCacheMode { get; set; }Public ReadWrite Property NavigationCacheMode As NavigationCacheModepublic NavigationCacheMode NavigationCacheMode { get; set; }
    <page NavigationCacheMode="navigationCacheModeMemberName" />
    

    Property Value

    Remarks

    To enable a page to be cached, set NavigationCacheMode to either Enabled or Required. The difference in behavior is that Enabled might not be cached if the frame's cache size limit (CacheSize ) is exceeded, whereas Required always generates an entry no matter the size limit.

    If you want to change the value of NavigationCacheMode programmatically to Enabled or Required, you can only set these values in the constructor for the page.

    If you change the value of NavigationCacheMode from Required or Enabled to Disabled, the page is flushed from the cache. The page is not simply marked as available to be flushed when the configured CacheSize is exceeded.

    Examples

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

  • TopAppBar
    TopAppBar
    TopAppBar
    TopAppBar

    Gets a reference to an AppBar displayed at the top of the page, if any.

    public AppBar TopAppBar { get; set; }public AppBar TopAppBar { get; set; }Public ReadWrite Property TopAppBar As AppBarpublic AppBar TopAppBar { get; set; }
    <Page ...>
      <Page.TopAppBar>
        <AppBar .../>
      </Page.TopAppBar>
    </Page>
    

    Property Value

    Remarks

    In XAML, make sure you specify the Page.TopAppBar property element in the same area as other property elements that may already be defined, like Page.BottomAppBar or Page.Resources. The XAML language enforces that you can't mix the property elements between the XAML content that is setting Content, such as the typical root Grid element. For more info on XAML syntax, see XAML syntax guide.

    Examples

    For example code that adds an AppBar to a page, see Quickstart: adding app bars or How to share an app bar across pages. For a complete sample that uses many of the Page and Frame features together, see XAML Navigation sample.

  • TopAppBarProperty
    TopAppBarProperty
    TopAppBarProperty
    TopAppBarProperty

    Identifies the TopAppBar dependency property.

    public static DependencyProperty TopAppBarProperty { get; }public static DependencyProperty TopAppBarProperty { get; }Public Static ReadOnly Property TopAppBarProperty As DependencyPropertypublic static DependencyProperty TopAppBarProperty { get; }

    Property Value

Methods

  • OnNavigatedFrom(NavigationEventArgs)
    OnNavigatedFrom(NavigationEventArgs)
    OnNavigatedFrom(NavigationEventArgs)
    OnNavigatedFrom(NavigationEventArgs)

    Invoked immediately after the Page is unloaded and is no longer the current source of a parent Frame.

    protected virtual void OnNavigatedFrom(NavigationEventArgs e)protected virtual void OnNavigatedFrom(NavigationEventArgs e)Protected Overridable Function OnNavigatedFrom(e As NavigationEventArgs) As voidprotected virtual void OnNavigatedFrom(NavigationEventArgs e)

    Parameters

  • OnNavigatedTo(NavigationEventArgs)
    OnNavigatedTo(NavigationEventArgs)
    OnNavigatedTo(NavigationEventArgs)
    OnNavigatedTo(NavigationEventArgs)

    Invoked when the Page is loaded and becomes the current source of a parent Frame.

    protected virtual void OnNavigatedTo(NavigationEventArgs e)protected virtual void OnNavigatedTo(NavigationEventArgs e)Protected Overridable Function OnNavigatedTo(e As NavigationEventArgs) As voidprotected virtual void OnNavigatedTo(NavigationEventArgs e)

    Parameters

    Remarks

    Unlike in prior XAML platforms, the OnNavigatedTo(NavigationEventArgs) method is called before the visual tree is loaded. This has the following implications:

    • You cannot access a valid Parent property value from an override of OnNavigatedTo(NavigationEventArgs). If you need to access the Parent property, do so in a Loaded event handler.
    • You cannot use OnNavigatedTo(NavigationEventArgs) for element manipulation or state change of controls on the destination page. Instead, attach a Loaded event handler at the root of the newly loaded page's content, and perform any element manipulations, state changes, event wiring and so on in the Loaded event handler.
  • OnNavigatingFrom(NavigatingCancelEventArgs)
    OnNavigatingFrom(NavigatingCancelEventArgs)
    OnNavigatingFrom(NavigatingCancelEventArgs)
    OnNavigatingFrom(NavigatingCancelEventArgs)

    Invoked immediately before the Page is unloaded and is no longer the current source of a parent Frame.

    protected virtual void OnNavigatingFrom(NavigatingCancelEventArgs e)protected virtual void OnNavigatingFrom(NavigatingCancelEventArgs e)Protected Overridable Function OnNavigatingFrom(e As NavigatingCancelEventArgs) As voidprotected virtual void OnNavigatingFrom(NavigatingCancelEventArgs e)

    Parameters

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ComposableAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute

Details

Assembly

Windows.UI.Xaml.Controls.dll