Resizing a Silverlight Plug-In

Article
11/08/2007

Microsoft Silverlight provides a set of properties to retrieve the size of a Silverlight plug-in. It also provides an event that is raised whenever the plug-in is resized.

This topic contains the following sections:

Setting the Size of a Silverlight Plug-In
Getting the Actual Size of a Silverlight Plug-In
Using the OnResize Event
Differences Between the OnResize and OnFullScreenChange Events

Setting the Size of a Silverlight Plug-In

When you define a Silverlight plug-in, you specify the width and height of the rectangular region that contains the plug-in's content. You can define the width and height of a Silverlight plug-in by specifying the values in the CreateSilverlight.js and Silverlight.js helper files.

The default unit of measurement for width and height is pixels. This means that a width value of "300" displays a Silverlight plug-in that has a width of 300 pixels.

You can also specify the width or height of a Silverlight plug-in as a percentage of the displayable area of the tag, for example, 75%. The percentage value is relative to the current size of the browser window. If you resize the browser window width, you will also resize any plug-in whose width or height is specified as a percentage value. The following JavaScript example shows the Silverlight plug-in defined in the CreateSilverlight.js file as a percentage value for both width and height.

JavaScript
function createSilverlightEx() { Silverlight.createObjectEx({ source: 'xamlContent', // Source property value. parentElement:parentElement, // DOM reference to hosting DIV tag. id:'myPlugin', // Unique plug-in ID value. properties:{ // Plug-in properties. width:'75%', // Width of rectangular region of plug-in, in pixels. height:'75%', // Height of rectangular region of plug-in, in pixels. background:'oldlace', // Background color of plug-in. version:'1.0'}, // Plug-in version. events:{ onLoad:null}}); // OnLoad property value -- event-handler function name. }

function createSilverlightEx()
{  
    Silverlight.createObjectEx({
        source: 'xamlContent',          // Source property value.
        parentElement:parentElement,    // DOM reference to hosting DIV tag.
        id:'myPlugin',                  // Unique plug-in ID value.
        properties:{                    // Plug-in properties.
            width:'75%',                // Width of rectangular region of plug-in, in pixels.
            height:'75%',               // Height of rectangular region of plug-in, in pixels.
            background:'oldlace',       // Background color of plug-in.
            version:'1.0'},             // Plug-in version.
        events:{
            onLoad:null}});             // OnLoad property value -- event-handler function name.
}

When you resize the browser window, the Silverlight plug-in, as defined in the preceding code, is automatically resized so that its width and height are still 75% of the displayable area of the tag. Notice, however, that the Ellipse object retains its original size; Silverlight does not support automatic layout of content. This means that applications have to provide logic to resize or scale themselves appropriately when the size of the Silverlight plug-in changes.

Silverlight plug-in with width and height properties set to 75%

Silverlight plug-in with width and height properties set to 75%

The width and height properties of the Silverlight plug-in are inherited by the plug-in from the HTML Document Object Model (DOM), so you can set these properties at run time. The following JavaScript example shows how to set the Silverlight plug-in size at run time.

JavaScript
// Set the plug-in to a new size. function setNewSize(newWidth, newHeight) { // Retrieve a reference to the plug-in via the DOM. var slPlugin = document.getElementById("slPlugin"); alert(slPlugin); // Set the new size values; slPlugin.width = newWidth; slPlugin.height = newHeight; // Perform layout tasks for plug-in content. }

// Set the plug-in to a new size.
function setNewSize(newWidth, newHeight)
{
    // Retrieve a reference to the plug-in via the DOM.
    var slPlugin = document.getElementById("slPlugin");
    alert(slPlugin);
    // Set the new size values;
    slPlugin.width = newWidth;
    slPlugin.height = newHeight;
    // Perform layout tasks for plug-in content.
}

Note To retrieve the plug-in's DOM properties, such as width and height, use the GetElementById method to return a reference to a DOM-accessible object. The GetHost method does not return an object from which DOM values can be retrieved.

Instead of embedding the plug-in within a larger HTML page, you might want the plug-in to take up the entire Web page. In the following HTML, the width and height are set to 100% for the HTML element, BODY element, and the DIV that contains the plug-in.

HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="https://www.w3.org/1999/xhtml" > <head> <title>My Silverlight Application</title> <!-- Helper files for initializing and creating the Silverlight plug-in --> <script type="text/javascript" src="Silverlight.js"></script> <script type="text/javascript" src="CreateSilverlight.js"></script> <style> html,body { height:100%; margin:0; padding:0;} </style> </head> <body> <div id="slPluginHost" style="width:100%;height:100%" > <script type="text/javascript"> // Create a variable that references the HTML element that hosts the plug-in. var parentElement = document.getElementById("slPluginHost"); // Initialize and create the plug-in. createSilverlight(); </script> </div> </body> </html>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="https://www.w3.org/1999/xhtml" >
<head>
  <title>My Silverlight Application</title>
  <!-- Helper files for initializing and creating the Silverlight plug-in -->
  <script type="text/javascript" src="Silverlight.js"></script>
  <script type="text/javascript" src="CreateSilverlight.js"></script>
  
    <style>
     html,body { height:100%; margin:0; padding:0;}
    </style> 
 
 </head>
<body>
  <div id="slPluginHost" style="width:100%;height:100%" >
    <script type="text/javascript">
      // Create a variable that references the HTML element that hosts the plug-in.
      var parentElement = document.getElementById("slPluginHost");
      
      // Initialize and create the plug-in.
      createSilverlight();
    </script>
  </div>
</body>
</html>

In addition to setting the height and width to 100% in the HTML page, set the height and width to 100% in the CreateSilverlight.js file, as shown in the following code.

JavaScript
function createSilverlight() { Silverlight.createObject( "position_inside_html2.xaml", // Source property value. parentElement, // DOM reference to hosting DIV tag. "myPlugin", // Unique plug-in ID value. { // Plug-in properties. width:'100%', // Width of rectangular region of plug-in. height:'100%', // Height of rectangular region of plug-in. inplaceInstallPrompt:false, // Determines whether to display in-place install prompt if invalid version is detected. background:'white', // Background color of plug-in. isWindowless:'false', // Determines whether to display plug-in in windowless mode. framerate:'24', // MaxFrameRate property value. version:'1.0' // Silverlight version. }, { onError:null, // OnError property value -- event-handler function name. onLoad:null // OnLoad property value -- event-handler function name. }, null, // initParams -- user-settable string for information passing. null); // Context value -- passed to Silverlight.js onLoad event handlers. }

function createSilverlight()
{  
    Silverlight.createObject(
        "position_inside_html2.xaml",       // Source property value.
        parentElement,                      // DOM reference to hosting DIV tag.
        "myPlugin",                         // Unique plug-in ID value.
        {                                   // Plug-in properties.
            width:'100%',                   // Width of rectangular region of plug-in.
            height:'100%',                  // Height of rectangular region of plug-in.
            inplaceInstallPrompt:false,     // Determines whether to display in-place install prompt if invalid version is detected.
            background:'white',             // Background color of plug-in.
            isWindowless:'false',           // Determines whether to display plug-in in windowless mode.
            framerate:'24',                 // MaxFrameRate property value.
            version:'1.0'                   // Silverlight version.
        },
        {
            onError:null,                   // OnError property value -- event-handler function name.
            onLoad:null                     // OnLoad property value -- event-handler function name.
        },
        null,                               // initParams -- user-settable string for information passing.
        null);                              // Context value -- passed to Silverlight.js onLoad event handlers.
}

Getting the Actual Size of a Silverlight Plug-in

The width and height properties of the Silverlight plug-in that are defined in the OBJECT and EMBED tags do not always reflect the true pixel size of the plug-in. For example, in cases where the width is defined as 75%, the actual width in pixels is unknown. However, the Silverlight plug-in provides two properties, ActualWidth and ActualHeight, that enable you to retrieve values that are always specified as pixel values.

The following JavaScript example shows how to use the ActualWidth and ActualHeight properties. If the width is defined as a percentage value, the ActualWidth value represents a width value in pixels.

JavaScript
function onResizeStatus(sender, eventArgs) { // Concatenate the size values as a formatted message string. var msgString = " actualWidth: " + slPlugin.content.actualWidth; msgString += " actualHeight: " + slPlugin.content.actualHeight; // Display an alert dialog box with a formatted message string. var textBlock = sender.findName("Status"); textBlock.text = msgString; }

function onResizeStatus(sender, eventArgs)
{
    // Concatenate the size values as a formatted message string.
    var msgString  = " actualWidth: " + slPlugin.content.actualWidth;
        msgString += " actualHeight: " + slPlugin.content.actualHeight;
    // Display an alert dialog box with a formatted message string.
    var textBlock = sender.findName("Status");
    textBlock.text = msgString;
}

The following illustration shows the results of invoking the OnResize event-handler function that is defined in the preceding code sample. In this case, the plug-in's width and height are set to 100% and remain at 100% regardless of the size of the browser window. However, the ActualWidth and ActualHeight properties display the Silverlight plug-in size values as pixel values.

Displaying size properties on the OnResize event

Displaying size properties on the OnResize event

Using the OnResize Event

The OnResize event occurs whenever the Silverlight plug-in changes its ActualHeight or ActualWidth property in embedded 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.

The following JavaScript example shows how to define a OnResize event for a Silverlight plug-in.

JavaScript
var plugin; function onLoaded(sender, args) { // Retrieve a reference to the plug-in. var slPlugin = sender.getHost(); // Set the event handler function to the OnResize event. slPlugin.content.onResize = onResized; // Do initial layout of the application based on initial size. updateLayout(slPlugin.content.actualWidth, slPlugin.content.actualHeight); } function onResized(sender, eventArgs) { // Do layout resizing of the application whenever the plug-in actualwidth or actualheight changes. updateLayout(slPlugin.content.actualWidth, slPlugin.content.actualHeight); } // Resize and reposition application elements. function updateLayout(width, height) { // Perform layout tasks based on width and height. }

var plugin;
function onLoaded(sender, args)
{
    // Retrieve a reference to the plug-in.
    var slPlugin = sender.getHost();
    // Set the event handler function to the OnResize event.
    slPlugin.content.onResize = onResized;
    // Do initial layout of the application based on initial size.
    updateLayout(slPlugin.content.actualWidth, slPlugin.content.actualHeight);
}
function onResized(sender, eventArgs)
{
    // Do layout resizing of the application whenever the plug-in actualwidth or actualheight changes.
    updateLayout(slPlugin.content.actualWidth, slPlugin.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 user interface elements. This means that applications have to provide logic to resize themselves appropriately when the size of the Silverlight plug-in changes.

Note Use OnResize to make sizing decisions instead of using OnLoad. This is because the ActualHeight/ActualWidth values of the Silverlight plug-in are not guaranteed to be set at the time the OnLoad event fires. OnResize fires whenever the ActualHeight or ActualWidth properties change, including the time the plug-in first loads.

Performance Characteristics During a Size Change

Resizing a browser window has minimal effect on performance for Silverlight plug-ins that are contained within the browser page. This means, in most cases, that playback of audio or video content is seamless.

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 false, the Silverlight plug-in displays in embedded mode, that is, the plug-in is contained within the browser window. When the FullScreen property is set to true, the Silverlight plug-in displays in full-screen mode, that is, 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

Silverlight plug-in displaying in embedded and full-screen 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.

Share via