How to: Define a Simple Silverlight Splash Screen

Switch View

How to: Define a Simple Silverlight...

Collapse All

Silverlight

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

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

Important Note:
Choose the option that creates a Web site for your project. The Visual Studio UI in the projects dialogs for this action vary depending on which version of the Silverlight Tools for Visual Studio you have installed. For Version 2 of the tools, choose Create a Web Site, which is the default debugging/startpage option. For Version 3 of the tools, 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.

Important Note:

Choose the option that creates a Web site for your project. The Visual Studio UI in the projects dialogs for this action vary depending on which version of the Silverlight Tools for Visual Studio you have installed. For Version 2 of the tools, choose Create a Web Site, which is the default debugging/startpage option. For Version 3 of the tools, 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.

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

XAML

<Canvas
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
        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. For more information about possible animation techniques, see Silverlight Splash Screens.

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" />
```
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.

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;
}

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

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

Concepts

Silverlight Splash Screens

Tags

: Add a tag

Community Content

Add new content

Annotations

changes for silverlight 2.0 Silverlight Splash Screen

Prasad Pathak ... Wolf Schmidt - MSFT | Edit | Show History

1) use OnPluginSourceDownloadProgressChanged event in silverlight 2.0 in place of onSourceDownloadProgressChanged

2) and use this to show progress bar

sender.get_element().content.findName("brdRect").Width = Math.round(eventArgs.get_progress() * 300);

[Edit by Wolf Schmidt - MSFT]: This comment is outdated. As of v3 there no longer is an asp:Silverlight control that supports the version 3 specific features of the underlying plugin. Unless you have legacy reasons for using the asp:Silverlight control, new projects should generally use HTML for the object initialization.

Tags

: changes (x) silverlight2.0 (x) Add a tag

Flag as ContentBug

Not an example for ASPNET Silverlight control

Wolf Schmidt - MSFT | Edit | Show History

This is deliberately NOT an example for the ASP.NET Silverlight control. In Version 3, the ASP.NET control is deprecated, and most examples on MSDN and elsewhere will now show object tag construction for v3 apps. You can still use it if you have the relevant server side DLL, but its functionality does not account for new object-level API on the Silverlight ActiveX control/NPAPI plugin that instantiates on the client.

Tags

: Add a tag

Flag as ContentBug

Good sample

DotBlog | Edit | Show History

Thanks for this good code sample.
Very clear and giving the expected result.

Just a question : I built my own splash but the canvas appears to be displayed in left upper corner. The application is well displayed centered but not the splash. How to make the main canvas of the splash to be displayed centered ?

Tags

: Add a tag

Flag as ContentBug

Not able to See the SplashScreen

Satish.Neelakantam | Edit | Show History

Hi,

Thanks for the article. I am working on SL 3.0. I tried the same what ever there in the above article. But I can't able to see the SpashScreen. It showing the MainPage.xaml instead of SplashScreen.

Anbody can please help me on this ASAP. If possible can you please provide me some Silverlight Splash Screen Sample.

Regards
Satish

Tags

: Add a tag

Flag as ContentBug