Silverlight.net > Learn > QuickStarts
QUICKSTARTS

[This topic is pre-release documentation and is subject to change in future releases of Microsoft Silverlight.]

Displaying a Splash Screen While Loading a Silverlight-Based Application

Introduction

The Microsoft Silverlight managed code model requires that the assemblies or packages referenced in Extensible Application Markup Language (XAML) be present on the client computer before the XAML can be 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.

Run View

Language: C#

Prerequisites (available from the Silverlight download site):

Silverlight version 2 Beta 1.
Microsoft Visual Studio 2008.
Silverlight Tools Beta 1 for Visual Studio 2008.

Changes to the Splash Screen Model since 1.1 Alpha

The splash screen model has undergone changes since Silverlight 1.1 Alpha. Support for splash screens is now built in to the plug-in API. You do not have to initiate the package download from the splash screen in user code. Instead, the splash screen source and the primary source (the package) are each specified as discrete values for initialization, and transitions are handled automatically by the plug-in. In addition, the plug-in itself provides a default splash screen experience and behavior, even if you do not specify a splash screen source.

One aspect that does remain the same for Silverlight version 2 Beta 1 is that the programming model for any code-behind used for the splash screen remains the JavaScript unmanaged programming model, even if the eventual primary application pages in your Silverlight-based application use the managed programming model throughout. When the download is complete and the package is loaded and available, the programming model typically transitions from unmanaged 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. This event happens often enough to get granularity of about 0.5% of the total download.

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.)

The Default Splash Screen Experience

The default experience is that any load that exceeds a certain time threshold (500ms) will display a XAML-based animation in the content area. The XAML that displays the default animation and the initiation sequence are hard-coded into the Silverlight plug-in.

To replace the default splash screen, you provide a value for the splashScreenSource parameter of the Silverlight plug-in's defining OBJECT tag in HTML. Or, if you are using Silverlight.js functions for instantiation, you specify a value for the splashScreenSource parameter of the CreateObject / CreateObjectEx function call.

Setting up the Project Files

There are other ways to set up this kind of project, but in this example you will start with the basic Silverlight project. You also should add some spurious megabytes to your DLL, 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

Open Visual Studio 2008. Start from a Silverlight project for an application, as described in Creating an Application for Silverlight. For this example, name the project SplashScreenSource

important
Choose the option Create a Web Site, which is the default debugging option. 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.
To introduce enough download time to make your splash screen testable, create a package of enormous size. The quickest way to do this is to pack the primary assembly with large embedded resource files that you will not actually reference. Your project is already producing the assembly. Find some large files somewhere on your computer, which will not compress when packaged. 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 Embedded Resource. The goal is to introduce at least 5 MB of resources into your assembly and package.
(Optional.) Add a TextBlock or some other visible UI element to page.xaml 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.
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

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.
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.

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:

cs

<Canvas
        xmlns="http://schemas.microsoft.com/client/2007" 
        xmlns:x="http://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>

note

For purposes of this example, we will provide you with the splash screen animation, but you could put your own animation here as well.

Open SplashScreenSourceTestPage.html for editing. Find the <object data="data:application/x-silverlight," type="application/x-silverlight-2-b1" ... section of the HTML. This is the object tag that instantiates the Silverlight plug-in. Edit the tag <param name="source" value="ClientBin/SplashScreenSource.xap"/> to remove ClientBin/ from the path. This should now read <param name="source" value="SplashScreenSource.xap"/>. Save the file and keep it open.
In Solution Explorer, drag the file SplashScreenSource.xap out of the ClientBin/ directory to the root of SplashScreenSource_Web.
Return to the Silverlight object tag area of SplashScreenSourceTestPage.html for editing. Notice that there are a number of "params" tags as child elements of object already. You will now add several "params" tags to add your custom splash screen information. Add the following params tags:
```
<param name="splashscreensource" value="SplashScreen.xaml"/>
<param name="onSourceDownloadProgressChanged" value="onSourceDownloadProgressChanged" />
```
The second params tag 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.

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

cs

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

Return to SplashScreenSourceTestPage.html for editing. You still need to reference the JavaScript file you just created. Just after the head tag in the HTML, add the following:
```
<script type="text/javascript" src="splashscreen.js"></script>
```
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.