Quickstart: Creating multiple windows for an app
Collapse the table of content
Expand the table of content
Language: HTML | XAML

Quickstart: Creating multiple windows for an app (HTML)

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

You can help your users be more productive by allowing them to view multiple independent functions in separate windows. Users can quickly switch from one part of the app in one window to another part of the app in another window. They can also compare the contents of multiple windows side-by-side, for example, to view two different documents at the same time or to view a game leader board and the game action in separate windows. The Mail app allows the user to open a message in a new window. The user can compose a new mail and also refer to a message in the Inbox by using multiple windows.

If you create multiple windows for an app, each window behaves independently. The list of recently used apps shows each window separately. Users can move, resize, show, and hide app windows independently and can switch between app windows as if they were separate apps. Each window operates in its own thread and execution context.

Mail app with two windows open

This quickstart shows you how to:

  • Create a new window for your app
  • Add content to the new window
  • Display the new window
  • Switch from one window to another
  • Close a window when it falls off the list of recently used apps

This is the JavaScript version of this quickstart. For the C# with XAML version, see Quickstart: Creating multiple windows for an app (XAML).

Creating multiple windows for an app is different from projecting a separate window of your app on another screen for display only, not for interaction. For more info about projecting a window, see Guidelines for projection manager.

Prerequisites

Create the secondary page

  1. In Solution Explorer, open the shortcut menu for the project node, and then choose Add > New Item.
  2. In the Add New Item dialog box, choose Page Control in the middle pane.
  3. In the Name box, enter a name for the page, such as secondaryView, and then choose the Add button.
  4. Add the UI elements and functionality that you want on your secondary page. For more info, see Laying out your UI and Guidelines for multiple windows.

Create a new view

Create a new thread and a new window on that thread by calling MSApp.createNewView. The pairing of a thread and window together is called a view. Other objects that you create in this view, such as UI elements, are tied to this thread.

The first view that is created when your app starts is called the main view. If the main view's window closes, the app is terminated.


var newView = MSApp.createNewView("ms-appx:///html/secondaryView.html");

This code automatically loads the specified page, secondaryView, in the new window.

Because each window operates in its own execution context, a secondary window can communicate with the main window only by using postMessage or shared files and settings. This code shows how to use postMessage to include extra state information you might need to set up the window.


newView.postMessage({ myState: 'My important state'}, thisOrigin);

Display the new window

After you create a new view, which is the pairing of a thread and a window, you can show the new window by using the ApplicationViewSwitcher.TryShowAsStandaloneAsync method. The viewId parameter in the TryShowAsStandaloneAsync method is an integer that uniquely identifies each of the views in your app. You retrieve the view ID by using either ApplicationView.Id or ApplicationView.GetApplicationViewIdForWindow.


var newView = MSApp.createNewView("ms-appx:///html/secondaryView.html");
newView.postMessage({ myState: 'My important state' }, thisOrigin);
Windows.UI.ViewManagement.ApplicationViewSwitcher.tryShowAsStandaloneAsync(newView.viewId).done(function (viewShown) {

});


We recommend that you don't automatically open a new window when a user navigates to a different part of the app. The user should initiate opening a new window. You can add the TryShowAsStandaloneAsync call to a UI element, for example, a command in the bottom app bar.

Switch from one window to another

You must provide a way for the user to navigate from a secondary window back to the main window. To do this, use the ApplicationViewSwitcher.SwitchAsync method. You call this method from the thread of the window you're switching from and pass the view ID of the window you're switching to.


Windows.UI.ViewManagement.ApplicationViewSwitcher.SwitchAsync(viewIdToShow).done();

In the Mail app, the back button on the secondary window calls SwitchAsync. The Mail app also uses SwitchAsync when a user sends or deletes the message contained in the secondary window. The Mail app replaces the secondary window with the main mail window.

When you use SwitchAsync, you can choose if you want to close the initial window and remove it from the list of recently used apps by specifying the value of ApplicationViewSwitchingOptions.

Close the new window

After you display a secondary window, it remains in the list of recently used apps until the user launches enough other apps for it to fall off the list. The consolidated event occurs when the window is removed from the list of recently used apps, provided that the app has at least one more window remaining in the list. Because each window consumes memory, we recommend that you close the window when it falls off the list.


Windows.UI.ViewManagement.ApplicationView.getForCurrentView().addEventListener("consolidated", viewConsolidated, false);

function viewConsolidated(e) {
    if (!isMainView) {
        window.close();
    }
}


Note  Don't close the main view's window because this terminates the app. The app certification process requires that you don't programmatically close an app. Only close a window that is not the main window, as in this example.
 

Summary and next steps

You learned how to create and display a multiple windows for an app. You also learned how to switch from one window to another and how and when to close an app window.

To learn about using projection manager to project a separate window of your app on another screen, see Guidelines for projection manager.

Related topics

Guidelines for multiple windows
Guidelines for projection manager
Responsive design 101 for UWP apps
Multiple views sample

 

 

Show:
© 2016 Microsoft