How to extend the splash screen (HTML)

  • Article

Display a splash screen for more time by creating an extended splash screen. This screen is often designed to imitate the splash screen shown upon app launch, but it's fully customizable. Whether you want to show real-time loading information or simply give your app extra time to prepare its initial UI, an extended splash screen lets you define the launch experience. These steps help you create an extended splash screen that's identical to the splash screen provided by the system.

To see an extended splash screen in a complete app, see the Splash screen sample.

If you want to give users the impression that the default splash screen is shown for a longer time, your extended splash screen will have to imitate the default splash screen in these ways:

  • Your extended splash screen page should use the same image as the one specified for your splash screen in your app manifest.
  • Your view should use a background color that is consistent with the background color specified for your splash screen in your app manifest.
  • Your code should use the SplashScreen class to position your app's splash screen image at the same screen coordinates as the default splash screen.
  • Windows (not Windows Phone): Your code should respond to the window resize events (like when your app is resized or the screen is rotated).

Important  If you've declared a global app control, like an AppBar, in your project's default.html file, set the control's disabled property to true when you call the function that displays your extended splash screen and set disabled back to false when you navigate away from your extended splash screen. If you need more info on how to add or style controls, see Adding controls and content.

 

Prerequisites

Step 1: Create an extended splash screen page

  1. Associate the JavaScript code, which defines your extended splash screen, with your landing page.

    The Splash screen sample adds this code to associate extendedSplash.js with default.html:

    <script src="/js/extendedSplash.js"></script>

  2. Add an extended splash screen <div> to your landing page.

    The Splash screen sample uses this HTML to add an extended splash screen <div> to the <body> of its landing page (default.html):

    <div id="extendedSplashScreen" class="extendedSplashScreen hidden">
    <img id="extendedSplashImage" src="/images/splash-sdk.png" alt="Splash screen image" />
    <!-- Optionally, add a progress ring. Note: In this sample, the progress ring is not used. -->
    <!--
    <progress id="extendedSplashProgress" style="color: white;" class="win-medium win-ring"></progress>
    -->
    <div id="extendedSplashDescription">
        <span id="extendedSplashText">The splash screen was dismissed and the image above was positioned using the splash screen API.</span>
        <button class="action" id="learnMore">Learn More</button>
    </div>
</div>

    The id and class attributes are set so they can be used for styling and manipulation. The extended splash screen <div> also sets the "hidden" class, so that it will not be visible until it is shown by the extended splash screen JavaScript code.

  3. Add CSS to style the extended splash screen markup on your landing page.

    Make sure you style the extended splash screen HTML to use the position:absolute style. Absolute positioning lets your app use the whole screen when it displays your extended splash screen. It also lets you position the splash screen image using the same screen coordinates as the default splash screen.

    The Splash screen sample adds this CSS (to default.css) to style the extended splash screen tags on its landing page:

    .extendedSplashScreen {
    background-color:#00b2f0;
    height: 100%;
    width: 100%;
    position: absolute;
    top: 0px;
    left: 0px;
    text-align: center;
}

.extendedSplashScreen.hidden {
    display: none;
}

#extendedSplashImage {
    position: absolute;
}

#extendedSplashDescription
{
    position: absolute;
    width: 100%;
    top: calc(100% - 140px);
    text-align: center;
}

#extendedSplashText
{
    font-family: 'Segoe UI Semilight';
    font-size: 11pt;
    text-align: center;
    width: 75%;
    color: #ffffff;
}

    The classes and ids that define these styles also identify the extended splash screen tags in the HTML of the landing page.

Step 2: Add code to your activated event handler that displays your extended splash screen

The Splash screen sample demonstrates how to display the extended splash screen using the activated event handler (the activated function) in the default.js file.


function activated(eventObject) {
    if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) {
        // Retrieve splash screen object
        splash = eventObject.detail.splashScreen;

        // Retrieve the window coordinates of the splash screen image.
        SdkSample.coordinates = splash.imageLocation;

        // Register an event handler to be executed when the splash screen has been dismissed.
        splash.addEventListener("dismissed", onSplashScreenDismissed, false);

        // Create and display the extended splash screen using the splash screen object.
        ExtendedSplash.show(splash);

        // Listen for window resize events to reposition the extended splash screen image accordingly.
        // This ensures that the extended splash screen is formatted properly when the window is resized.
        window.addEventListener("resize", onResize, false);

        // Use setPromise to indicate to the system that the splash screen must not be torn down
        // until after processAll and navigate complete asynchronously.
        eventObject.setPromise(WinJS.UI.processAll().then(function () {
            // Navigate to either the first scenario or to the last running scenario
            // before suspension or termination.
            var url = WinJS.Application.sessionState.lastUrl || scenarios[0].url;
            return WinJS.Navigation.navigate(url);
        }));
    }
}

The Splash screen sample uses these steps to display its extended splash screen and position the splash screen image when the app is activated (inside its activated event handler in the default.js file):

  1. Get the coordinates where the default splash screen image is displayed. These coordinates are stored in a property of the SplashScreen object, which is accessible from the event object that is passed to the activated event handler.

    The Splash screen sample gets the coordinates using the following code:

    
    if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) {
        // Retrieve splash screen object
        splash = eventObject.detail.splashScreen;

        // Retrieve the window coordinates of the splash screen image.
        SdkSample.coordinates = splash.imageLocation;

  2. Listen for the splash screen's dismissed event, then begin loading app resources. The system raises the dismissed event when it dismisses the system-provided splash screen and, in this case, transitions to display your app's extended splash screen. Start setup operations inside a dismissed event handler and navigate away from the extended splash screen when app setup is complete.

    The Splash screen sample registers its dismissed event handler (onSplashScreenDismissed) in the activated function in default.js:

            // Register an event handler to be executed when the splash screen has been dismissed.
        splash.addEventListener("dismissed", onSplashScreenDismissed, false);

    Define the dismissed event handler outside the activated event in default.js. Because the Splash screen sample doesn't need to wait for any resources to load, it removes the extended splash screen when a user clicks the "Learn More" button.

        function onSplashScreenDismissed() {
        // Include code to be executed when the system has transitioned from the splash screen to the extended splash screen (application's first view).
        SdkSample.dismissed = true;

        // Tear down the app's extended splash screen after completing setup operations here...
        // In this sample, the extended splash screen is torn down when the "Learn More" button is clicked.
        document.getElementById("learnMore").addEventListener("click", ExtendedSplash.remove, false);
        }
    }

    Create a function that removes the extended splash screen in your extendedSplash.js file.

        // Removes the extended splash screen if it is currently visible.
    function remove() {
        if(isVisible()) {
            var extendedSplashScreen = document.getElementById("extendedSplashScreen");
            WinJS.Utilities.addClass(extendedSplashScreen, "hidden");
        }
    }

  3. Position and display the extended splash screen.

    The Splash screen sample positions and displays the splash screen using the following code in its activated event handler (in default.js):

    
        // Create and display the extended splash screen using the splash screen object.
        ExtendedSplash.show(splash);

    Add a function that positions the extended splash screen image to extendedSplash.js.

    
// Displays the extended splash screen. Pass the splash screen object retrieved during activation.
function show(splash) {
    var extendedSplashImage = document.getElementById("extendedSplashImage");

    // Position the extended splash screen image in the same location as the system splash screen image.
    extendedSplashImage.style.top = splash.imageLocation.y + "px";
    extendedSplashImage.style.left = splash.imageLocation.x + "px";
    extendedSplashImage.style.height = splash.imageLocation.height + "px";
    extendedSplashImage.style.width = splash.imageLocation.width + "px";

    // Position the extended splash screen's progress ring. Note: In this sample, the progress ring is not used.
    /*
    var extendedSplashProgress = document.getElementById("extendedSplashProgress");
    extendedSplashProgress.style.marginTop = splash.imageLocation.y + splash.imageLocation.height + 32 + "px";
    */

    // Once the extended splash screen is setup, apply the CSS style that will make the extended splash screen visible.
    var extendedSplashScreen = document.getElementById("extendedSplashScreen");
    WinJS.Utilities.removeClass(extendedSplashScreen, "hidden");
}

  4. Windows (not Windows Phone): Listen for window resize events and respond by repositioning the splash screen image. This ensures that your extended splash screen will be formatted properly if your app is resized. Orientation changes will be automatically handled if you create a flexible layout or place content in a flexible control, like a ViewBox.

    Register your resize event handler inside your activated event handler (in default.js):

                // Listen for window resize events to reposition the extended splash screen image accordingly.
            // This is important to ensure that the extended splash screen is formatted properly in response to resizing, rotation, etc...
            window.addEventListener("resize", onResize, false);

    Then add code to define the event handler. This function gets the updated image location coordinates, then calls another function to update the image's location on the extended splash screen page.

    function onResize() {
    // Safely update the extended splash screen image coordinates. This function will be fired in response to snapping, unsnapping, rotation, etc...
    if (splash) {
        // Update the coordinates of the splash screen image.
        SdkSample.coordinates = splash.imageLocation;
        ExtendedSplash.updateImageLocation(splash);
    }
}

    The sample defines updateImageLocation in extendedSplash.js. If the extended splash screen is visible, it positions the extended splash screen's image in the same place as the splash screen displayed by the system.

    function updateImageLocation(splash) {
    if (isVisible()) {
        var extendedSplashImage = document.getElementById("extendedSplashImage");

        // Position the extended splash screen image in the same location as the system splash screen image.
        extendedSplashImage.style.top = splash.imageLocation.y + "px";
        extendedSplashImage.style.left = splash.imageLocation.x + "px";
        extendedSplashImage.style.height = splash.imageLocation.height + "px";
        extendedSplashImage.style.width = splash.imageLocation.width + "px";

        // Position the extended splash screen's progress ring. Note: In this sample, the progress ring is not used.
        /*
        var extendedSplashProgress = document.getElementById("extendedSplashProgress");
        extendedSplashProgress.style.marginTop = splash.imageLocation.y + splash.imageLocation.height + 32 + "px";
        */
    }
}

Remarks

Tip  If you notice a flicker during the transition to your extended splash screen, add onload="" on your <img> tag like this: <img id="extendedSplashImage" src="/images/splash-sdk.png" alt="Splash screen image" onload="" />. This helps prevent flickering by making the system wait until your image has been rendered before it switches to your extended splash screen.

 

How to activate an app

Splash screen sample

Guidelines for splash screens

How to extend the splash screen (Windows Runtime apps using C#/VB/C++ and XAML)

Reference

WinJS.Application.onactivated event

Windows.ApplicationModel.Activation namespace

Windows.ApplicationModel.Activation.splashScreen class

Windows.ApplicationModel.Activation.splashScreen.imageLocation property