Silverlight Splash Screens
Microsoft Silverlight will reach end of support after October 2021. Learn more.
In the Silverlight managed API, the client requires assemblies referenced in the manifest to be downloaded and loaded into the application’s AppDomain before the application is instantiated. Also, your application design may want to preload certain resources and assure that these are available before the application is ready for interaction, even if that means not displaying the application until the download is complete. The splash screen is an initial content area that can display to the user while other content is still loading.
This topic contains the following sections.
- Splash Screen Scenarios
- The JavaScript API for Silverlight
- The Default Splash Screen Experience
- A Basic Splash Screen in an Application Project
- Splash Screen Scenarios in Detail
- Using OnSourceDownloadComplete
- Related Topics
Splash Screen Scenarios
The feature set that is available for constructing a splash screen for Silverlight is intended to address the following scenarios, but is not necessarily limited to them:
Show download progress
Show animations, even if not necessarily using them to display the download progress
Provide branding, which might include text, vector graphics, or even video
Display product information, such as disclaimers
These scenarios are discussed further in the section of this topic. The feature set that is available is the same feature set that is available to the JavaScript API for Silverlight in general, along with APIs that support the splash screen feature specifically.
You cannot use this splash screen model effectively if your main source content is using the JavaScript API also. This is because the splash screen model relies on the notification that comes from a loaded managed AppDomain as the signal to stop displaying SplashScreenSource and start displaying Source. You could simulate the same apparent transitional behavior by the following sequence:
Load an initial Source XAML page that is the "splash screen".
Initiate the download of the main source XAML page and any initial resources such as images or videos that the page requires, using Downloader.
As soon as each Downloader raises Completed for all content, change the actual Source value at the HTML DOM level, which unloads the "splash screen" and loads your primary content. The transition is instant at this point because each required element is already preloaded into the browser cache.
The JavaScript API for Silverlight
If you have previously developed for Silverlight 1.0, you are probably already familiar with the JavaScript API for Silverlight. If you have not previously developed for Silverlight 1.0, see JavaScript API for Silverlight. The JavaScript API for Silverlight is similar to programming for the HTML DOM, and in fact is executed in the host's scripting engine just like scripting to the DOM, but the Silverlight API extends into the object tree that is created when a XAML page is loaded as content for the Silverlight plug-in. This enables you to handle events on specific objects, set property values, replace parts of the object tree at run-time, etc.
The Default Splash Screen Experience
The default experience that is defined for Silverlight under the managed API is that any load that exceeds a certain time threshold (approximately 0.5 seconds) 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 element in HTML.
A Basic Splash Screen in an Application Project
The basic support for a splash screen in Silverlight is defined at the level of the Silverlight plug-in codebase. This is exposed to the browser host in either the COM or NPAPI control model (depending on the specific browser), and exposed to the HTML DOM and HTML in general through the object element that instantiates a Silverlight plug-in.
The following params options for the Silverlight plug-in are specifically for splash screen support:
Parameter |
Description |
|---|---|
Sets the URI of the XAML page that provides the visuals for the splash screen. This page loads as the initial Silverlight content, under the JavaScript API. |
|
Sets the name of an event handler that is called at increments during the time that the Source is being downloaded. |
|
Sets the name of an event handler that is called once when the Source download is completed. |
If you specify a handler for either OnSourceDownloadProgressChanged or OnSourceDownloadComplete, then the function referenced must be available to the browser scripting engine at run-time. Usually this is accomplished by defining the function in a separate JavaScript file. You then include the script for the HTML page that hosts the Silverlight plug-in's defining object element. Documentation for the event handler prototypes is available in the following reference topics: OnSourceDownloadProgressChanged, OnSourceDownloadComplete.
The XAML page for SplashScreenSource should be obtainable from a Web server. This XAML page is served to a Silverlight client browser host, just as other content such as images or the managed XAP package are served. Your Web server should be configured such that the .xaml extension and the appropriate MIME type for XAML are permitted as served content.
Splash screens have security considerations because they involve a transition across API modes, as well as the Silverlight initialization within the HTML page. To make these transitions more secure, you must serve all three elements of the splash screen process (the hosting HTML page, the splash screen XAML, the XAP package that is being downloaded while the splash screen displays) from the same domain. You can choose to serve these elements through HTTPS, but if you do so you must serve all elements as HTTPS.
The splash screen source must be a XAML file. Specifying a XAP as the splash screen source will generate an error.
A basic procedure for defining and packaging a simple Silverlight splash screen is described in the topic How to: Define a Simple Silverlight Splash Screen.
Splash Screen Scenarios in Detail
Download Progress
A common scenario for a splash screen is to display a visual progress indicator. The most basic and familiar progress indicator to many users is the progress bar. A typical progress bar design shows a horizontally extended rectangular area that initially appears white or empty. As a download or action progresses, the empty area is gradually filled by a darker bar, and progress is complete as soon as the darker bar totally fills the rectangle. Sometimes this visual is accompanied by a text area that displays a numeric percentage.
In the Silverlight splash screen model, the means to determine the download progress is by reading the value of the Progress property from within a OnSourceDownloadProgressChanged handler's event data.
Although a progress bar might visually appear similar to an animation, you do not generally need to use the Silverlight animation API in order to build a progress bar. Instead, you simply use some factor of Progress from each iteration of OnSourceDownloadProgressChanged to update some property.
For instance, the following XAML defines a simple version of such a bar:
<Canvas Background="Black" Width="302" Height="52">
<Rectangle Canvas.Left="1" Canvas.Top="1" Width="300" Height="30" Fill="White"/>
<Rectangle x:Name="progressBarFill" Canvas.Left="1" Canvas.Top="1" Height="30" Fill="Blue"/>
</Canvas>
To produce the progress visual, you would reset the value of the fill bar on each iteration of by setting the width of progressBarFill in the handler. progress is a value between 0 and 1, so you use it as a factor against the total possible width of the progress bar area.
function onProgressChanged(sender, eventArgs)
{
var slPlugin = sender.getHost();
slPlugin.content.findName("progressBarFill").width = eventArgs.progress * 300;
}
Animation is not required, because the Silverlight rendering system detects run-time changed property values in the object tree and redraws the visuals accordingly.
Animations
Another common scenario for a splash screen is to display a cycling animation. The intention of the cycling animation is to indicate to the user that the application and the browser are still running and capable of rendering updates, and that nothing unexpected has happened (browser crash, connection error, etc.).
For these types of animations, the total animation duration is indeterminate, because the intention is to run the animation during the time the user waits for the download to complete. Therefore the best type of animation to use is one that has a natural cycling behavior and one that has a run time of Forever. The animation will "stop" when the entire XAML page is unloaded, and the Silverlight plug-in loads the content from the download-complete package.
Animations can generally be composed entirely in XAML. To run the animation, you can use EventTrigger containment of the Storyboard in the XAML markup to run the animation when it is first loaded. Or you can handle an object lifetime event such as Loaded on the root element, under the JavaScript API, retrieve the relevant Storyboard from a Resources collection, and call Storyboard.Begin on the Storyboard to start the animation.
For more information on how to compose animations and how animations work in general, see Animation Overview. Note that the Animation Overview topic is written primarily for users of the managed API, and may not have code examples or specific information that address the JavaScript API scenarios. Read the overview for a conceptual understanding. Some of the XAML examples provided in the overviews are probably useful after some minimal work to remove managed API specifics such as x:Class. Then, if necessary, you can learn more from the following topics in JavaScript API for Silverlight Reference:
You can also use key-frame animations for more fine-tuned animations with nonlinear interpolations for position and speed. These might be useful for very simple physics simulations in a splash screen, such as a bouncing ball. For more information, see Key-Frame Animations. The same provisos apply as far as the emphasis on managed programming and possible application of XAML samples. See also the following topics from JavaScript API for Silverlight Reference:
Branding
A traditional splash screen in many application models displays nothing more than a single large bitmap, and perhaps a progress indicator as a smaller part of the UI. The usual goal of such a splash screen is to prominently display the product branding information. There is nothing preventing you from employing this approach for a Silverlight splash screen. At the simplest level, your splash screen XAML could consist of nothing more than a single Image element that displays a bitmap. This might not be the ideal approach though, because if the bitmap is large, the image source downloads asynchronously and then even your splash screen might have a slight delay before it is displayed.
A better approach that uses the feature strengths of Silverlight is to compose your splash screen as vector graphics. You can import existing vector information in some cases using the pathway described in the topic Path Markup Syntax. Or you can use design tools that produce XAML markup that is compatible with Silverlight, such as Microsoft Expression Design. Also, you can either integrate any animations produced at design-time by such a tool, or add animations to the graphics later, by targeting certain properties of the fixed vector graphics set and animating those with storyboards.
Product Information
Your splash screen may want to display an area that primarily contains text. To simplify localization, you might want to keep that text out of the vector graphics portion of your content. The JavaScript API does not have as mature of a localization framework as the managed API does, but even so it will be useful to isolate the localization requirements to certain controls in the overall markup.
When you display text for a splash screen, you are limited to the text elements that are available to the JavaScript API. There are two possible techniques for read-only text: TextBlock, or Glyphs.
TextBlock is probably the lighter-weight technique, particularly if you are only targeting Latin alphabet cultures. You specify the TextBlock content as a string. Within the TextBlock, you can do some basic text formatting such as sizing, applying colors or brushes, as well as block-level formatting using LineBreak. If you want to use fonts beyond the defaults described in TextBlock, you must download the font; see SetFontSource.
Glyphs is a more versatile technique because you can supply a subsetted font as well as a UnicodeString, which makes it easier to use East Asian fonts and character strings. The only complication is that you do need tools that can produce both subsetted fonts and compatible Unicode indices/strings. A technique for using XPS output from Microsoft Word is described in Glyphs.
Using OnSourceDownloadComplete
The moment that OnSourceDownloadComplete is raised is also the moment that the splash screen XAML is unloaded, in preparation for loading the package. Therefore it generally does not make sense to take any action that affects the Silverlight object tree. Instead, you might use OnSourceDownloadComplete as a cue to update the UI in the surrounding HTML, or possibly to change any HTML overlays that you render over the Silverlight content area if you use that technique.
If you are referencing a Source that is cross-domain from the hosting HTML, handlers for OnSourceDownloadComplete or OnSourceDownloadProgressChanged are never invoked. Therefore you can only display indeterminate splash screens. The hosting HTML may wish to assign a handler for OnLoad in this case, as it is the best available object lifetime event for resetting state after the source XAP loads.