Silverlight provides a set of properties to retrieve the actual size of a Silverlight control, as well as an event that allows you to determine when the control was resized.

This topic contains the following sections:

• Setting the Size of a Silverlight Control
• Getting the Actual Size of a Silverlight Control
• Using the OnResize Event
• Differences Between the OnResize and OnFullScreenChange Events

Setting the Size of a Silverlight Control

When you define a Silverlight control, you specify the width and height of the rectangular region that contain the control's content. You can define the width and height of a Silverlight control directly by specifying the values using the OBJECT and EMBED tags, or indirectly by specifying the values using the CreateSilverlight.js helper file. For more information on using JavaScript helper files to create a control, see Using CreateSilverlight.js and Silverlight.js.

The default unit of measurement for width and height is pixels. This means a width value of "300" displays a Silverlight control with a width of 300 pixels.

You can also specify the width or height of a Silverlight control 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 resize any control whose width or height is specified as a percentage value. The following JavaScript example shows the Silverlight control defined in the CreateSilverlight.js as a percentage value for both width and height:

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

When you resize the browser window, the Silverlight control, 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 control content. This means that applications have to provide logic to resize, or scale, themselves appropriately when the size of the Silverlight control changes:

Silverlight control with width and height properties set to 75%
 

You can set the width and height properties of the Silverlight control at run time, since they are inherited by the control from the HTML DOM. The following JavaScript example shows how to set the Silverlight control size at run time:

// Set the control to a new size.
function setNewSize(newWidth, newHeight)
{
    // Retrieve a reference to the control via the DOM.
    var control = document.getElementById("myControl");

    // Set the new size values;
    control.width = newWidth;
    control.height = newHeight;

    // Perform layout tasks for control content.
}

Note:  In order to retrieve the control's DOM properties, such as width and height, the GetElementById method needs to be used to return a reference to a DOM-accessible object. The GetHost method does not return an object from which DOM values can be retrieved.

Getting the Actual Size of a Silverlight Control

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

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

function onResizeStatus(sender, eventArgs)
{
    // Concatenate the size values as a formatted message string.
    var msgString  = " actualWidth: " + control.content.actualWidth;
        msgString += " actualHeight: " + control.content.actualHeight;

    // Display an alert dialog box with a formatted message string.
    var textBlock = sender.findName("Status");
    textBlock.text = msgString;
}

The following screen shot shows the results of invoking the OnResize event handler function that is defined in the preceding code sample. In this case, the control'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 control size values as pixel values:

                     Displaying size properties on OnResize event

Using the OnResize Event

The OnResize event occurs whenever the Silverlight control changes its ActualHeight or ActualWidth property when in embedded mode:

• embedded mode --control displays within the Web browser.
• full-screen mode--control displays on top of all other applications.

The following JavaScript example shows how to define a OnResize event for a Silverlight control.

var control;

function onLoaded(sender, args)
{
    // Retrieve a reference to the control.
    control = sender.getHost();

    // Set the event handler function to the OnResize event.
    control.content.onResize = "onResize";

    // Do initial layout of the app based on initial size.
    updateLayout(control.content.actualWidth, control.content.actualHeight);
}

function onResize(sender, eventArgs)
{
    // Do layout resizing of the app whenever the FullScreen property changes.
    updateLayout(control.content.actualWidth, control.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 control elements. This means that applications have to provide logic to resize themselves appropriately when the size of the Silverlight control changes.

Performance Characteristics During a Size Change

When a browser window is resized, there is minimal impact to performance on Silverlight controls contained within the browser page. This means, in most cases, 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 control changes. When the FullScreen property is set to false, the Silverlight control displays in embedded mode--the control is contained within the browser window. When the FullScreen property is set to true, the Silverlight control displays in full-screen mode--the control resizes to the current resolution of the display and overlays all other applications, including the browser. The following images show the differences between embedded mode and full-screen mode:

 
                                             Silverlight control displaying as embedded and full-screen mode

If a change in the Silverlight control size triggers the OnFullScreenChange event, the OnResize event does not occur. In addition, the OnResize event does not occur when the Silverlight control 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, Using Silverlight Controls