Quickstart: Using file or image resources (HTML)

  • Article

[ 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 add images and other file resources to your app, and reference those files from within your app. Support for selecting images based on high contrast settings or display-specific scaling is built in to Windows Runtime, if you follow the instructions below for naming your file resources and organizing them in folders.

Instructions

  1. Create tailored images or other file assets for different display configurations (DPI) and contrast settings

    Create your images at several recommended sizes, to ensure that your app looks great when Windows loads the appropriate resource. See the guidelines for scaling to pixel density.

    1. Create multiple copies of each image:

      1. Original size, which is used by a typical 96dpi device. Name this file name.scale-100.ext (For this and all subsequent instructions, name is the placeholder for your chosen resource name, ext is the filetype-specific extension. The .scale-100 is the segment of the resource name that keys the Windows Runtime scaling behavior, it's this part of the name where you should use the conventions we document here.)
      2. 140% the original size. For example, a 100x100px image should also have a 140x140px image version. Name this file name.scale-140.ext
      3. 180% the original size. For example, a 100x100px image should also have a 180x180px image version. Name this file name.scale-180.ext
      4. 240% the original size, for Windows Phone apps. For example, a 100x100px image should also have a 240x240px image version. Name this file name.scale-240.ext
      5. High contrast image with a black background and white foreground at the original size. Name this file namescale-100_contrast-black.ext
      6. High contrast image with a white background and black foreground at the original size. Name this file namescale-100_contrast-white.ext

      Note  App logo images also use resources, which are specified in the app's manifest file. If you're specifically using an image for the app logo, you should create a copy that is 80% of the original size. For example, a 100x100px logo image should also have an 80x80px image version. Name this file name.scale-80.ext. For more info, see Choosing your app images and Tile and toast visual assets.

       

    2. Place all the images in the same folder of your app structure. For example:

      1. images/logo.scale-100.png
      2. images/logo.scale-140.png
      3. images/logo.scale-180.png
      4. images/logo.scale-240.png
      5. images/logo.scale-80.png
      6. images/logo.scale-100_contrast-black.png
      7. images/logo.scale-100_contrast-white.png

  2. Refer to the images in HTML without the qualifiers

    Use the form name.ext when you refer to this file resource from markup (You are deliberately omitting the segment that specifies the scale or contrast; Windows Runtime appends this segment internally when it retrieves the appropriate resource.) For example:

    <img src="images/logo.png" />

  3. Refer to the images in code without the qualifiers

    Use the form name.ext when you refer to this file resource from code (You are deliberately omitting the segment that specifies the scale or contrast; Windows Runtime appends this segment internally when it retrieves the appropriate resource.) The difference from the markup instructions above is that markup can infer the scheme as well as a root because of the markup file's context. But code cannot infer this; the scheme and root parts of a Uniform Resource Identifier (URI) are required for code when you construct a new Uri. For example:

    var uri = new Windows.Foundation.Uri('ms-appx:///images/logo.png');
var file = Windows.Storage.StorageFile.getFileFromApplicationUriAsync(uri);

  4. For a logo file, refer to the image in the manifest without the qualifiers

    1. Open the Package.appxmanifest file in Microsoft Visual Studio. Open the Visual Assets tab.

    2. Edit the manifest reference to refer to the resource file. This is shown as a text edit field by default, and when you specify the resource file name here, omit the qualifier segment. For example there is a field for Square 150x150 Logo where the value might be:

      images\logo.png

File resources and globalization

The instructions in this topic concentrate on the resource qualifiers that enable scaling and contrast support. These use the convention of including the qualifier within the file name. But some images or other files may need to be localized for reasons other than scaling or contrast support, particularly when they contain text or culturally sensitive material. Files can also vary depending on a user's location, separate from their language. For example, a map may have different borders depending on the user's location, but the labels should follow the user's preferred language. For more info on why this might be necessary, see Guidelines for globalization and localization.

If you need different resources per language and location, Windows Runtime also supports a convention where language and location can be determined at runtime and different appropriate resources are loaded. This convention uses folder names, not file names. So you can combine the file name conventions described here along with the folder conventions to define resources that support scale/contrast and localization concerns. There's also support for RTL-specific resources, and a targetsize convention that is used for special situations such as images displayed by the system for file associations. See How to name resources using qualifiers for more info on the folder name convention for qualifying resources, and the qualifying conventions.

How to name resources using qualifiers

App images

Guidelines for scaling to pixel density

Tile image sizes