Silverlight Full-Screen Support

Microsoft Silverlight provides functionality for displaying the Silverlight plug-in in full-screen mode.

This topic contains the following sections:

• Embedded Mode and Full-Screen Mode
• Setting Full-Screen Mode
• Returning to Embedded Mode
• Using the OnFullScreenChange Event
• Differences Between the OnResize and OnFullScreenChange Events

Embedded Mode and Full-Screen Mode

The Silverlight plug-in can display in either embedded mode or in full-screen mode:

• In embedded mode, the plug-in displays within the Web browser.
• In full-screen mode, the plug-in displays on top of all other applications.

When the Silverlight plug-in displays in embedded mode, the plug-in is contained within the browser window. When the Silverlight plug-in displays in full-screen mode, the plug-in resizes to the current resolution of the display and overlays all other applications, including the browser. The following illustrations show the differences between embedded mode and full-screen mode.

Silverlight plug-in displaying in embedded and full-screen mode

The Size of the Plug-in in Full-Screen Mode

When a Silverlight plug-in is displayed in full-screen mode, the plug-in's size is equal to the current resolution of the display. However, the values of the width and height properties of the plug-in are not affected during the switch to full-screen mode. To determine the true size of the plug-in in full-screen mode, use the ActualWidth and ActualHeight properties. These properties are set to the current resolution of the display.

When a Silverlight plug-in in full-screen mode switches back to embedded mode, the plug-in size reverts to the values of the width and height properties.

Setting Full-Screen Mode

The FullScreen property determines whether the Silverlight plug-in displays as a full-screen plug-in or as an embedded plug-in. If the FullScreen property is set to true, the Silverlight plug-in displays as a full-screen plug-in. If FullScreen is set to false, the Silverlight plug-in displays as an embedded plug-in. In cases where a page contains multiple Silverlight plug-ins, only one Silverlight plug-in can be in full-screen mode at one time.

When a Silverlight plug-in is displayed in full-screen mode, the following message appears briefly. This message alerts the user that the application is now in full-screen mode, and provides information about how to return to embedded mode.

Full-screen mode message

A Silverlight plug-in can enable full-screen mode only in response to a set of user-initiated actions. These actions correspond to the MouseLeftButtonDown, MouseLeftButtonUp, KeyDown, and KeyUp events. If you try to set the FullScreen property to true in a Loaded event, the property setting is ignored. Limiting the actions that enable full-screen mode ensures that the user is always the initiator of full-screen mode behavior.

When a Silverlight plug-in is displayed in full-screen mode, keyboard events are prevented from being passed to keyboard event handlers in the application. The only valid keyboard input that is acted upon is the set of keystrokes that return the Silverlight plug-in to embedded mode. This limitation of keyboard input during full-screen mode is a security feature, and is intended to minimize the possibility of unintended information being entered by a user.

The following JavaScript example shows how to enable and disable full-screen mode for a Silverlight plug-in by using a MouseLeftButtonUp event-handling function.

// Event handler for clicking the full-screen mode button.
function onMouseLeftButtonUp(sender, eventArgs)
{
    // Toggle between embedded mode and full-screen mode.
    plugin.content.fullScreen = !plugin.content.fullScreen;
}

When the Silverlight plug-in is in full-screen mode, the ActualWidth and ActualHeight properties are set to the current resolution of the display.

Performance Characteristics During a Mode Change

Switching between embedded and full-screen modes has minimal effect on performance for content that is contained within the Silverlight plug-in. This means, in most cases, that playback of audio or video content is seamless.

Note   For best performance, when your application goes into full-screen mode, hide or disconnect from the tree all objects that not being rendered in full-screen mode. You can hide an object by setting its Visibility property to Collapsed.

Full-Screen Windowless Silverlight Plug-Ins

A Silverlight plug-in whose Windowless property is set to true always draws its background color at full opacity when displayed in full-screen mode. However, when the Silverlight plug-in returns to embedded mode, the background color reverts to its previous opacity value.

Returning to Embedded Mode

A Silverlight plug-in that is in full-screen mode can return to embedded mode in several ways. The simplest way to leave full-screen mode is for the user to enter a keystroke or keystroke combination:

• Windows users should press ESC, CTRL+W, or ALT+F4.
• Macintosh users should press ESC.

In addition, if a Silverlight plug-in that is in full-screen mode loses focus, it returns to embedded mode. A Silverlight plug-in in full-screen mode can lose focus in a multimonitor configuration when another window gains focus through a user action. For example, switching between tasks in Windows by using the ALT+TAB key combination causes the current application to lose focus and the next application to gain focus.

Setting the FullScreen Property to False

When a Silverlight plug-in is displayed in full-screen mode, setting the FullScreen property to false returns the plug-in to embedded mode. When a Silverlight plug-in switches back to embedded mode from full-screen mode, the plug-in size reverts to the values of the width and height properties.

Using the OnFullScreenChange Event

The OnFullScreenChange event occurs whenever the FullScreen property changes. The following JavaScript example shows how to define a OnFullScreenChange event for a Silverlight plug-in.

var plugin;
function onLoaded(sender, args)
{
    // Retrieve a reference to the plug-in.
    plugin = sender.getHost();
    // Set the event handler function for the OnFullScreenChange event.
    plugin.content.onFullScreenChange = onFullScreenChanged;
    // Do initial layout of the app based on initial size.
    updateLayout(plugin.content.actualWidth, plugin.content.actualHeight);
}
function onFullScreenChanged(sender, eventArgs)
{
    // Do layout resizing of the app whenever the FullScreen property changes.
    updateLayout(plugin.content.actualWidth, plugin.content.actualHeight);
}
// Resize and reposition application elements.
function updateLayout(width, height)
{
    // Perform layout tasks based on width and height.
}

Note   Silverlight does not support automatic layout of elements. This means that applications have to provide logic to resize themselves appropriately when the plug-in size changes.

Differences Between the OnResize and OnFullScreenChange Events

The OnFullScreenChange event occurs whenever the FullScreen property of the Silverlight plug-in changes. When the FullScreen property is set to true, the Silverlight plug-in displays in full-screen mode. When the FullScreen property is set to false, the Silverlight plug-in displays in embedded mode.

If a change in the Silverlight plug-in size triggers the OnFullScreenChange event, the OnResize event does not occur. In addition, the OnResize event does not occur when the Silverlight plug-in is in full-screen mode. The OnResize and OnFullScreenChange events are discrete events that are independent of each other, and never occur at the same time.

See Also

ActualHeight
ActualWidth
OnFullScreenChange
OnResize
Overviews and How-to Topics