API changes for Windows 8.1(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]

This document lists API deprecations, functional changes, and optimizations introduced for Windows 8.1. For other porting resources, see:

• Retarget your Windows 8 Store app to Windows 8.1–Step-by-step guidance on how to port your app from Windows 8 to Windows 8.1.
• Updated samples–Samples for Windows 8.1 that demonstrate how to use new APIs and features, and how to mitigate deprecations.
• DirectX programming–New features and improvements for games and graphic apps.

Important  For more information on API changes in Windows 8.1 related to programming with C#/VB/C++ and XAML, see API changes for Windows 8.1 (Windows Store apps using C#/VB/C++ and XAML).

Noteworthy items

These API changes have the highest impact in app porting:

WinJS improvements and new features

We’ve made significant investments in WinJS 2.0 to reduce Windows Store app start up time, improve list panning performance, and reduce memory consumption. New features such as the system scheduler, the dispose pattern, and improved support for ListView cell spanning layouts make existing scenarios faster. Compiled binding templates substantially reduce the cost of rendering multiple data bound templates into controls. Developers will notice many of these benefits without changing their WinJS 1.0 code, but some improvements require changes to the WinJS API. We encourage developers to move away from deprecated APIs, to get the best performance from their app.

In addition, new features in WinJS 2.0 further improve performance, enable enhanced platform integration, and light up new user scenarios. New controls such as the NavBar and ItemContainer enable developers to build more compelling user interfaces. For simple lists, the Repeater offers faster performance. AppBar improvements allow your app bar to scale to more device and window sizes. As you port your app from WinJS 1.0 to WinJS 2.0, consider where you can leverage new platform features to enhance and improve your Windows 8.1 app.

Application lifetime

Quick restart after closing

In Windows 8.1, if the user closes an app and then immediately restarts it, the closed app is given up to five seconds to complete its termination before it restarts. In Windows 8, the app terminates immediately upon restart.

Suspension occurs at low priority

To improve system responsiveness in Windows 8.1, apps are given lower-priority access to resources on suspension. The suspension timeout is extended by a corresponding amount so that the app has the equivalent of 5 seconds at normal priority.

WinJS Scheduler

Windows 8.1 and WinJS 2.0 introduce WinJS.Utilities.Scheduler, an object/namespace that consolidates all work queues into a single, universal queue. The new queue has a priority-based scheduling policy that lets you to prioritize your work against system work to improve responsiveness. You can schedule tasks and assign priorities so that the right thing gets done at the right time. To learn more about how the Scheduler can help you improve the performance of your code, see Asynchronous programming in JavaScript.

The Dispose Pattern

The dispose model is a new pattern that allows elements and controls to release resources at the end of their lifetime to prevent memory leaks. An element or control can optionally implement it. WinJS 2.0 controls that have resources to release now implement this API. To take advantage of the dispose model, call the control's dispose method when the control is no longer needed, such as when you're navigating away from a page or when the app is shutting down. To learn how to implement the dispose pattern in a custom control, see Quickstart: Using the dispose model in WinJS. The quickstart adds a memory-intensive custom control to a sample app, then implements the dispose model. It compares the app's memory usage before and after the dispose pattern is added.

WinJS.Binding.Templates

When processing templates, data binding and control instantiation occur in different orders. If you write code in a constructor for a custom control that assumes that data-binding has already occurred, the code may not execute in the same way as before. In WinJS 1.0, templates process all control instantiation and initialization before all data binding. In WinJS 2.0, the newly optimized templates enhance fluidity in control initialization and data-binding. You can use Template.disableOptimizedProcessing to revert to WinJS 1.0 functionality. However, the new template processing is a significant performance improvement.

ListLayout Grouping

In Windows 8.1, WinJS 2.0's ListLayout supports grouping. This means that you can display ListLayouts in groups by using the ListView.groupDataSource property. In WinJS 1.0, the groupDataSource property was ignored. To continue to have the desired UX here are the necessary changes.

WinJS 1.0:

listView.dataSource = list.dataSource;
listView.groupDataSource = grouplist.dataSource;
if(view.snapped) {
    listView.layout = new ListLayout();
}
else {
    listView.layout = new GridLayout({groupHeaderPosition: 'top'});
}

WinJS 2.0:

listView.dataSource = list.dataSource;
listView.groupDataSource = grouplist.dataSource;
if(view.snapped) {
    listView.groupDataSource = null;
    listView.layout = new ListLayout();
}
else {
    listView.layout = new GridLayout({groupHeaderPosition: 'top'});
}

ListLayout margin-collapsing not supported

In Windows 8, you use:

.win-container {
    margin-top: 10px;
    margin-bottom: 10px;
}

In Windows 8.1, we remove the margin-bottom attribute:

.win-container {
    margin-top 10px;
}

ListLayout .win-container

The ListLayout padding should move from .win-container to .win-item container. This was not originally supported in Windows 8, but didn't have any negative consequence because of the display type of the layout. In Windows 8.1, it will create a gap between the item and the selection border. Move the padding to the .win-item container and adjust the margins to the correct size to mitigate this change. This pattern is present in the Visual Studio template. Split Template, the ListView in ListLayout, Visual Studio item template, and MSDN item templates are not impacted.

ListView child combinator selectors

ListView child selectors may not work correctly due to the new Document Object Model (DOM) shape.

ListView.currentItem property

The currentItem property previously returned the current item, not taking into account header items. In Windows 8.1, it returns the current item, taking into account header items as well.

ListView.groupHeaderInvoked

In Windows 8.1, the ListView supports keyboarding to the group headers in both the GridLayout, ListLayout, and CellspanningLayout.

The ListView raises the groupHeaderInvoked event to indicate that a header has been invoked. We recommend that you move the onClick handling code to the groupHeaderInvodked event so that all inputs (touch, mouse, keyboard) are handled on group headers.

ListView .win-groupheader

Move the win-groupheader margins to the win-groupleader class. Use the new .win-groupleader class to control margins. The app's margin will be noticeably different.

Porting from IFRAME to WebView

In Windows 8.1, XAML WebView control can only receive Windows.External.Notify messages from web sites that are on the ApplicationContentURI rules and are using HTTPS. These messages are received by the app if it handles the ScriptNotify event.

IFRAME elements within Windows Store apps using JavaScript and not within WebView controls can’t navigate to HTTP web sites. An IFRAME can navigate only to packaged content or HTTPS URIs listed in the ApplicationContentURI rules. WebView can support HTTP, but not the following:

• Geoloc
• Programmatic Clipboard
• AppCache
• IndexedDB

Move from windowed WebView control to windowless

In Windows 8.1, the WebView control in Windows Store apps using XAML and Windows Store apps using JavaScript are windowless and participate in the z-order for apps. The app bar and pop-ups can appear over the top of the WebView control. Apps that used WebViewBrush to work around this limitation should remove that workaround.

This change affects Windows Store apps using XAML in Windows 8.1, and Windows Store apps using JavaScript that use the new WebView control. Windows 8 apps are unaffected, and the existing windowed mode is used.

Deprecated WinJS APIs

The following WinJS.UI elements are deprecated.

WebView.ScriptNotify event

In Windows 8, the WebView.AllowedScriptNotifyUris and WebView.AnyScriptNotifyUri properties cause the WebView.AllowedScriptNotifyUris and WebView.AnyScriptNotifyUri properties cause the ScriptNotify event to fire. Because these properties are deprecated in Windows 8.1, the ScriptNotify event can’t be inspected during app on-boarding and allows an app to easily put the real work of their app on the web instead of in their app package. Instead, check the package’s ApplicationContentUriRules from the manifest. During app on-boarding, the app can inspect the manifest, which can’t be modified at run time.

Window size model

We’ve added a new window size model in Windows 8.1 to support richer multitasking scenarios. The concept of discrete view states is removed and the snapped state is no longer required. Instead, apps can be sized continuously to any size down to their minimum size. An app can either have a minimum width of 500px or 320px. By default, the minimum size of an app is 500px.

The Windows 8 ApplicationView.Value property and ApplicationView.TryUnsnap method are deprecated, so you will receive warnings if your app uses them. An app should register for the window resize event to know when to update the layout. However, instead of calling ApplicationView.Value to find out which view state the app is in, the app developer should apply media queries for window size directly to make layout decisions. In Windows 8.1, it is up to the app designer to decide what window size thresholds and media queries the app makes to update the app layout.

Here are some possible ways to port your code.

Viewing general window size:

WWA (JavaScript)

Windows 8

function onSizeChanged() {
    // Get view state
    var currentViewState = ApplicationView.value;

    if (currentViewState === ApplicationViewState.fullScreenLandscape) {
        // Full screen Landscape layout

    } else if (currentViewState === ApplicationViewState.fullScreenPortrait) {
        // Full screen Portrait layout

    } else if (currentViewState === ApplicationViewState.filled) {
         // Filled layout

    } else if (currentViewState === ApplicationViewState.snapped) {
        // Snapped layout
    } 
}

Windows 8.1

function onSizeChanged() {
    // Get window size
    var windowWidth = document.documentElement.offsetWidth;

    // App code to change layout based on window width* 

}

WWA (media queries)

Windows 8

@media (-ms-view-state: fullscreen-landscape) {
    /* CSS styles for full screen landscape */
}

@media (-ms-view-state: fullscreen-portrait) {
    /* CSS styles for full screen portrait */
}

@media (-ms-view-state: filled) {
    /* CSS styles for filled*/
}

@media (-ms-view-state: snapped) {
    /* CSS styles for snapped */
}

Windows 8.1

@media (min-width: 500px) and (max-width: 1023px) {
    /* CSS styles to change layout based on window width */
}

@media (min-width: 1024px) {
    /* CSS styles to change layout based on window width */
}

Viewing orientation:

WWA (JavaScript)

Windows 8

function onSizeChanged() {
    // Get view state
    var currentViewState = ApplicationView.value;

    if (currentViewState == ApplicationViewState.fullScreenLandscape || currentViewState == ApplicationViewState.filled) {
        // Landscape layouts

    } else if (currentViewState == ApplicationViewState.fullScreenPortrait) {
        // Portrait layouts

    }
}

Windows 8.1

function onSizeChanged() {
    // Get the window orientation
    var winOrientation = ApplicationView.getForCurrentView().orientation;

    if (winOrientation === ApplicationViewOrientation.landscape) {
       // Landscape layouts

    } else if (winOrientation === ApplicationViewOrientation.portrait) {
       // Portrait layouts

    }
}

WWA (media quieries)

Windows 8

@media (-ms-view-state: fullscreen-landscape) or (-ms-view-state: filled)  {
    /* CSS styles for landscape layouts */
}

@media (-ms-view-state: fullscreen-portrait) {
    /* CSS styles for portrait layouts */
}

Windows 8.1

@media (orientation: landscape) {
    /* CSS styles for landscape layouts */
}

@media (orientation: portrait) {
    /* CSS styles for portrait layouts */
}

Document Object Model (DOM) improvements

The Windows 8.1 platform for JavaScript developers introduces several enhancements to improve performance and the compatibility of common frameworks of Web content. With these changes, developers will notice better performance of their existing code. They will be able to make fewer changes, to adapt their modern Web code to run in Windows 8.1 applications.

These changes also include removing several deprecated APIs in the Windows 8.1 platform for JavaScript developers, in favor of their standards-based and modern equivalents. Together, these changes help prevent common JavaScript frameworks from misidentifying the Windows 8.1 platform for JavaScript developers, as an earlier version of Internet Explorer.

Deprecated DOM APIs

The following JavaScript API elements are deprecated. For functional changes, use a web-platform based equivalent. For legacy data-binding changes, use data binding from JavaScript frameworks such as the Windows Library for JavaScript (WinJS).

These navigator object members are not deprecated, but have altered return values:

• userAgent
• appVersion
• appName
• product

Changes to pointer input events

A pointer is a generic input type with a unified event mechanism. It exposes basic info, such as screen position, on the active input source, which can be touch, touchpad, mouse, or pen. The vendor prefixes for the pointer events implementation have been removed for Windows 8.1.

MS vendor prefix removal

Behavioral updates

To remain aligned with changes to the technical details of the World Wide Web Consortium (W3C) pointer events specification, the following behavioral changes have been implemented for Windows 8.1.

Fonts for existing scripts

We are updating the Document Object Model (DOM) default fonts and UI fonts for Windows Store app using JavaScript for several languages. For more info, see the Windows Compatibility Cookbook.

Disable pseudo hit testing in IE 11 Mode

We are disabling legacy Internet Explorer functionality that allowed clicks and other touch or mouse interaction to conditionally pass through transparent backgrounds, known as “pseudo hit testing.” This functionality was often seen as inconsistent because it varied based on the content behind the transparent layer and was not used for direct manipulation like pan and zoom. This change helps to raise the default compatibility of Internet Explorer's latest mode for public web sites while improving cross-browser interoperability. In Windows 8, this functionality prevented items on some sites from being activated in response to a click because the event would "pass through" a transparent layer and fire on the wrong element.

Affected content will appear not to respond to user interaction and can be seen as being obscured by another layer when using the Select element by click feature in F12 tools or Microsoft Visual Studio. The back button no longer works for apps in Windows 8.1, as a result of this change. Changing the z-index or the bounds of the transparent layer, to avoid obscuring the affected content, usually resolves the issue. To fix back button, do one of the following:

• In your .css file, reposition the back button in front of the other controls.

  .fragment header[role=banner] .win-backbutton {
      margin-left: 39px;
      margin-top: 59px;
      prosition: relative;
      z-index: 1;
  }
  

• Use the new back button control for Windows 8.1.

  1. Replace <button class="win-backbutton" aria-label="Back" disabled type="button"></button> with <button data-win-control="WinJS.UI.BackButton"></button>.

  2. In the default.css file, replace .win-backbutton with .win-navigation-backbutton.

  3. Reposition the back button in front of the other controls.

     .fragment header[role=banner] .win-navigation-backbutton {
         margin-left: 39px;
         margin-top: 59px;
         position: relative;
         z-index: 1;
     }
     

The WinJS (WinJS) depended on this functionality when drawing the keyboard focus rectangle for an item in the ListView control. If you've embedded an older copy of WinJS in your app, upgrade to the current version when porting your app from Windows 8 to Windows 8.1.

Load dynamically added scripts asynchronously in Windows Store apps using JavaScript

Dynamically added script elements will now load asynchronously for protocols for Windows Store apps using JavaScript (ms-appx*), to align with the functionality of web protocols (http*). Previously such scripts could load synchronously and block the UI depending on the order in which their attributes were set.

Windows Store apps written for Windows 8.1 load scripts dynamically and attempt to use functions from the script immediately. Update affected content to do one of these:

• Load scripts statically in the HTML markup of the page.
• Set "script.async=false" on dynamically loaded scripts, to ensure that they execute in the order in which they are added.
• Wait for the "load" event of a script element to fire before using functions defined in the script.

We have updated the WinJS fragment loader to be compatible with this change. When you port your apps to Windows 8.1, make sure that you have the latest version of WinJS to avoid issues.

Related topics

Retarget your Windows Store app to Windows 8.1

Updated samples

DirectX programming

API changes for Windows 8.1 (Windows Store apps using C#/VB/C++ and XAML)