• Article

Full-Screen Support

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

Silverlight provides functionality for displaying Silverlight-based applications in full-screen mode.

This topic contains the following sections.

  • Embedded Mode and Full-Screen Mode
  • Entering Full-Screen Mode
  • Returning to Embedded Mode
  • The FullScreenChanged Event
  • Version Notes
  • Related Topics

Embedded Mode and Full-Screen Mode

A Silverlight-based application can display in either embedded mode or in full-screen mode:

  • In embedded mode, the application displays within the Web browser or an out-of-browser application window.

  • In full-screen mode, the application resizes to the current resolution of the screen. By default, full-screen applications display on top of all other applications. However, you can configure them to stay in full-screen mode when other applications are active.

The following illustrations show the differences between embedded mode and full-screen mode.

Silverlight-based application in embedded mode

Embedded mode

Silverlight-based application in full-screen mode

Full-screen mode

Entering Full-Screen Mode

A Silverlight-based application enters full-screen mode when you set the IsFullScreen property to true. When the application enters full-screen mode, it briefly displays the message "Press ESC to exit full-screen mode". 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

Press ESC to exit full-screen mode.

The following code example shows how to enable and disable full-screen mode by toggling the IsFullScreen property value.

Private WithEvents rootPage As Page = New Page()
Private WithEvents htmlContent As Content
Private Sub Application_Startup(ByVal o As Object, ByVal e As StartupEventArgs) Handles Me.Startup
    Me.RootVisual = rootPage
    htmlContent = Me.Host.Content
End Sub

Private Sub ToggleFullScreen(ByVal sender As Object, _
    ByVal e As MouseButtonEventArgs) Handles rootPage.MouseLeftButtonDown
    Me.Host.Content.IsFullScreen = Not Me.Host.Content.IsFullScreen
End Sub

Private Sub DisplaySizeInformation( _
    ByVal sender As Object, ByVal e As EventArgs) _
    Handles htmlContent.FullScreenChanged, htmlContent.Resized

    Dim message As String = String.Format( _
        "ActualWidth={0}, ActualHeight={1}", _
        Me.Host.Content.ActualWidth, _
        Me.Host.Content.ActualHeight)

    rootPage.LayoutRoot.Children.Clear()
    Dim t As New TextBlock()
    t.Text = message
    rootPage.LayoutRoot.Children.Add(t)

End Sub

Page rootPage = new Page();
private void Application_Startup(object sender, StartupEventArgs e)
{
    this.RootVisual = rootPage;

    rootPage.LayoutRoot.MouseLeftButtonDown +=
        delegate(Object s, MouseButtonEventArgs args) {
            this.Host.Content.IsFullScreen =
                !this.Host.Content.IsFullScreen;
        };

    this.Host.Content.FullScreenChanged += 
        new EventHandler(DisplaySizeInformation);

    this.Host.Content.Resized += 
        new EventHandler(DisplaySizeInformation);
}

private void DisplaySizeInformation(Object sender, EventArgs e)
{
    String message = String.Format(
        "ActualWidth={0}, ActualHeight={1}",
        this.Host.Content.ActualWidth,
        this.Host.Content.ActualHeight);

    rootPage.LayoutRoot.Children.Clear();
    rootPage.LayoutRoot.Children.Add(
        new TextBlock { Text = message });
}

Limitations of Full-Screen Mode

A Silverlight-based application can enter full-screen mode only in response to a user-initiated action. This means that you can programmatically switch to full-screen mode only in a user-input event handler. If you try to set the IsFullScreen property to true in a Startup event handler, for example, 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. This limits malicious applications from spoofing the appearance of the operating system or other programs.

NoteNote:

User initiation and other requirements do not apply to trusted applications. For more information, see the next section.

By default, only one application can be in full-screen mode at a time. An application will normally exit full-screen mode when the user switches to another application.

To configure a Silverlight-based application to stay in full-screen mode regardless of whether it is active, set the FullScreenOptions property to StaysFullScreenWhenUnfocused. This enables users to view an application in full-screen mode while interacting with other applications. Users can also display multiple applications in full-screen mode.

When an application stays in full-screen mode while inactive, users can switch to other applications. This includes the original host browser or out-of-browser window, where the embedded Silverlight plug-in will display an empty area while the application is in full-screen mode.

In most cases, switching back to a full-screen application will not re-display the full-screen message. This means that malicious applications have an additional opportunity to spoof other applications. To help prevent this, the StaysFullScreenWhenUnfocused setting causes the application to display a user-consent dialog box before entering full-screen mode. If the user does not provide consent, then the application uses the default full-screen behavior.

The user-consent dialog box includes a check box that enables users to save their preferences. Users can modify their preferences in the Microsoft Silverlight Configuration Dialog Box.

When a Silverlight-based application is in full-screen mode, most keyboard events are disabled. 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. In full-screen mode, the only input allowed is through the following keys:

  • UP ARROW

  • DOWN ARROW

  • LEFT ARROW

  • RIGHT ARROW

  • SPACEBAR

  • TAB

  • PAGE UP

  • PAGE DOWN

  • HOME

  • END

  • ENTER

Silverlight does not support dialog boxes in full-screen mode. This includes the OpenFileDialog and SaveFileDialog classes in addition to user-consent dialog boxes. In most cases, displaying a dialog box in full-screen mode will cause the application to revert to embedded mode. However, to avoid issues on some browsers, you should exit full-screen mode before using a feature that displays a dialog box.

Full-screen mode does not support drag-and-drop or multitouch input. If your application uses these features, you should provide user guidance on alternatives when the application enters full-screen mode.

Full-Screen Mode with Trusted Applications

The full-screen message, user-initiation requirement, keyboard restrictions, and dialog-box restrictions do not apply to trusted applications. Additionally, trusted applications do not display the user-consent dialog box when using the StaysFullScreenWhenUnfocused setting.

In trusted applications, you can enter full-screen mode in a Application.Startup or FrameworkElement.Loaded event handler. However, you must do so by setting the IsFullScreen property in a delegate passed to the Dispatcher.BeginInvoke method.

Because the ESC key has no built-in effect for trusted applications, you can use it for your own purposes. In this case, you should implement and document an alternative so that users can exit full-screen mode.

For more information, see Trusted Applications.

The Size of the Application in Full-Screen Mode

When a Silverlight-based application is in full-screen mode, its size is equal to the current resolution of the screen. However, the values of the plug-in width and height properties are not affected during the switch to full-screen mode. To determine the true size of the application in full-screen mode, use the Content.ActualWidth and Content.ActualHeight properties. In full-screen mode, these properties are set to the current resolution of the screen.

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

For more information about the width and height properties, see Property Values of the HTML Object Element.

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 application. This means, in most cases, that the playback of audio or video content is seamless.

NoteNote:

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

Full-Screen Windowless Applications

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

Windowless HTML overlay effects are not supported in full-screen mode. However, out-of-browser applications can use the WebBrowser control to display HTML in full-screen mode.

Returning to Embedded Mode

A Silverlight-based application 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 press ESC or use one of the following keystroke combinations:

  • Windows users can press ALT+F4.

  • Macintosh users can press COMMAND+ESC.

In addition, if an application in full-screen mode loses focus, it returns to embedded mode unless the StaysFullScreenWhenUnfocused setting is in effect. An application in full-screen mode can lose focus when another application 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 IsFullScreen Property to False

A Silverlight-based application exits full-screen mode when you set the IsFullScreen property to false. When the application switches back to embedded mode, its size reverts to the values of the plug-in width and height properties.

The FullScreenChanged Event

The Content.FullScreenChanged event occurs whenever the IsFullScreen property changes. You can handle this event to change your user interface in full-screen mode.

NoteNote:

The Resized event does not occur when the application enters full-screen mode. However, you typically perform similar layout changes in handlers for both the Resized and FullScreenChanged events.

Version Notes

Silverlight 3 does not support the following features mentioned in this topic: