• Article

How to: Define a Simple Silverlight Splash Screen

Microsoft Silverlight will reach end of support after October 2021. Learn more.

The managed API for Silverlight requires that the packages referenced as source for the Silverlight plug-in be entirely present on the client computer before any content is loaded. When these packages are small in size, the user will not experience a significant load time lag. However, in cases where the packages are particularly large, you might want to display an initial splash screen that occupies the Silverlight client area while the package download completes in the background. The splash screen itself can only use the JavaScript API for Silverlight. When the download is complete and the package is loaded and available, the programming model typically transitions from JavaScript to managed and then remains managed for the duration of the application lifetime.

Download Progress and Completion Events

The Silverlight splash screen model relies on three properties that are exposed by the Silverlight plug-in:

  • splashscreensource: The URI of a XAML page that displays while the primary package (source) is being downloaded.

  • onsourcedownloadprogresschanged: References a JavaScript event handler that will be invoked continuously while the source is being downloaded.

  • onsourcedownloadcomplete: References a JavaScript event handler that will be invoked once, when the source download is complete. (This event is not illustrated in this topic.)

Setting up the Project Files

There are other ways to set up this kind of project, but in this example you will start with a basic Visual Studio-generated Silverlight project. If you want to see a functioning result application, you also should add some spurious megabytes to your assembly in the package, because you want the download to take long enough to show your splash screen for at least a few seconds. Initially, you will start with the default splash screen behavior.

To set up project files

  1. Open Visual Studio. Start from a Silverlight project for an application. For this example, name the project SplashScreenSource

    Important noteImportant Note:

    Choose the option that creates a Web site for your project. Leave the checkbox Host the Silverlight Application in a new Web site checked; this is also the default. You must do this in order to see download progress; the other option views an HTML page in the file system and the file transfer will happen too quickly to see the splash screen.

  2. To introduce enough download time to make your splash screen testable, make your package deliberately large. The quickest way to do this is to pack the primary assembly with large embedded resource files (these will increase the size even if you do not actually reference them). Your project is already producing the assembly as part of the package. Find some large files somewhere on your computer, which will not compress when packaged into the assembly and the XAP package (photographic images are good for this purpose, or multi-page binary-format documents). Copy and paste them into the project directory, and add them to the project as existing items. Set the build action for each of these files to Resource. The goal is to introduce at least 5 MB of resources into your assembly and package.

  3. (Optional.) Add a TextBlock or some other visible UI element to mainpage.xaml (the initial page of your managed API application) so that you can easily see that the source has completed downloading and you are now displaying XAML that came from the main application package.

  4. Build your project and make sure that it compiles. The start action at this point will just play the default splash screen. Next, you will replace the default behavior.

Adding the Custom Splash Screen

To replace the default behavior, you will be changing the SplashScreenSource_Web project, not the SplashScreenSource project. This is because the XAML page for the splash screen must be outside of the package. Otherwise, it wouldn't be available while the package itself was downloading.

To add the custom splash screen

  1. Right-click SplashScreenSource.Web in the Solution Explorer and choose Properties. Click the Web tab. Change the Start Action default page from SplashScreenSourceTestPage.aspx to SplashScreenSourceTestPage.html.

  2. Right-click SplashScreenSource.Web in the Solution Explorer and choose Add, New Item. Select the Silverlight option in the Categories tree view. Choose the Silverlight JScript Page option. Name the page SplashScreen.xaml. Click Add.

  3. Open SplashScreen.xaml for editing, if it is not already open. This is where you will author your splash screen. Select All, and Paste over the existing code with the following, then save the file:

    <Canvas
        xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation" 
        xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml" 
        x:Name="parentCanvas" 
        Width="850"
        Height="600"
        Background="OldLace"
        >
  <Canvas Canvas.Top="228.834" Canvas.Left="246.329" Width="357" Height="31.379">
    <Rectangle Width="27.545" Height="1" x:Name="uxProgress" Canvas.Top="29.545" Canvas.Left="1.4">
    <Rectangle.RenderTransform>
      <TransformGroup>
        <ScaleTransform x:Name="uxProgressBar" ScaleX="1" ScaleY="0"/>
        <SkewTransform AngleX="0" AngleY="0"/>
        <RotateTransform Angle="270"/>
        <TranslateTransform X="0" Y="0"/>
      </TransformGroup>
    </Rectangle.RenderTransform>
    <Rectangle.Fill>
      <LinearGradientBrush EndPoint="1,0.5" StartPoint="0,0.5">
        <GradientStop Color="#FFFFFFFF" Offset="1"/>
        <GradientStop Color="#FFFFFFFF" Offset="0"/>
        <GradientStop Color="#FF2975D0" Offset="0.28"/>
        <GradientStop Color="#FF2975D0" Offset="0.72"/>
      </LinearGradientBrush>
    </Rectangle.Fill>
  </Rectangle>

  <TextBlock x:Name="uxStatus" Height="25" Canvas.Left="125" Text="Loading..." TextWrapping="Wrap" Canvas.Top="4.16"/>

  <Path Width="356.85" Height="1" Fill="#FF3A3A3A" Stretch="Fill" Stroke="#FF000000" Canvas.Top="0" Data="M0,170.5 L356.84209,170.5" Opacity="0.35"/>
  <Path Width="1.662" Height="29.03" Fill="#FF3A3A3A" Stretch="Fill" Stroke="#FF000000" Canvas.Top="0.48" Canvas.Left="0.2" Data="M360,168 L360,0" Opacity="0.35" />

  <Path Width="357.84" Height="1" Fill="#FF3A3A3A" Stretch="Fill" Stroke="#FF000000" Canvas.Top="29" Data="M0,170.5 L356.84209,170.5" Opacity="0.35"/>
  <Path Width="358.85" Height="1" Fill="#FFA2A2A2" Stretch="Fill" Stroke="#FF000000" Canvas.Top="30" Data="M0,170.5 L356.84209,170.5" Opacity="0.25"/>
  <Path Width="1.662" Height="30" Fill="#FF3A3A3A" Stretch="Fill" Stroke="#FF000000" Canvas.Left="356.01" Data="M360,168 L360,0" Opacity="0.35" Canvas.Top="-0.498"/>
  <Path Width="1" Height="31" Fill="#FFA2A2A2" Stretch="Fill" Stroke="#FF000000" Canvas.Left="357.333" Data="M360,168 L360,0" Opacity="0.245" Canvas.Top="-0.498" />      
</Canvas>
</Canvas>
    NoteNote:

    For purposes of this example, we will provide you with the splash screen animation, but you could put your own animation here as well. For more information about possible animation techniques, see Silverlight Splash Screens.

  4. Return to the Silverlight object element area of SplashScreenSourceTestPage.html for editing. Notice that there are a number of "params" elements as child elements of object already. You will now add several params elements to add your custom splash screen information. Add the following params elements:

    <param name="splashscreensource" value="SplashScreen.xaml"/>
<param name="onSourceDownloadProgressChanged" value="onSourceDownloadProgressChanged" />

  5. The second params element is referencing a JavaScript event handler, which you must now define. Right-click SplashScreenSource.Web in the Solution Explorer. Find the file SplashScreen.js in the solution's file list (this file was added when you added SplashScreen.xaml in a previous step. Open SplashScreen.js for editing.

  6. Delete all pre-existing content of SplashScreen.js. Paste in the following onSourceDownloadProgressChanged function, which will update the progress bar in SplashScreen.xaml.

    function onSourceDownloadProgressChanged(sender, eventArgs)
{
    sender.findName("uxStatus").Text =  "Loading: " + Math.round((eventArgs.progress * 1000)) / 10 + "%";
    sender.findName("uxProgressBar").ScaleY = eventArgs.progress * 356;
}

  7. Return to SplashScreenSourceTestPage.html for editing. You still need to reference the JavaScript file you just created. Just after the head element in the HTML, add the following:

    <script type="text/javascript" src="splashscreen.js"></script>

  8. Build your project and make sure that it compiles. The start action at this point will now load SplashScreenSourceTestPage.html and first load your splash screen, and then the source.

  9. Clear your browser cache (otherwise, the assembly might still be cached as content by the browser, and you will not experience the load time). Run the application again.

TipTip:

A best practice is to use the same Background color for the splash screen XAML as for the general color scheme of your application. This provides a better visual transition for the user.

See Also

Concepts

Silverlight Splash Screens