- Embedding the Silverlight Control Manually
- Letting Silverlight.js Handle the Dirty Work
- Understanding Your Hosting Options
- Interacting with the Silverlight Control Programmatically
- Conclusion
This chapter is from the book
This chapter is from the book
This chapter is from the book
Interacting with the Silverlight Control Programmatically
The OBJECT or EMBED element representing the Silverlight control (whether part of the static HTML document or dynamically injected by Silverlight.js) has an HTML id, so you can write JavaScript to retrieve the element and get or set properties on it just like any other HTML element. For example,
// Retrieve the element via a standard HTML DOM function:
var element = document.getElementById("silverlightControl");
// Set properties on the element:
element.width = 500;
element.style.zIndex = 2;
Because this element is an instance of the ActiveX object (or Netscape plug-in), it provides a number of useful properties, functions, and events specific to silverlight. This element returned by document.getElementById is the same object passed as the first parameter to the onLoad event handler. However, you should avoid accessing any Silverlight-specific members on this object before the control has finished loading (and its onLoad event is raised).
The Silverlight control exposes most of its functionality via two properties: Settings and Content.
The Settings Property
Most relevant to this chapter is the control's Settings property, which defines a number of subproperties for getting or setting a number of attributes (many of which could have alternatively been set via createObject, createObjectEx, or directly on the OBJECT/EMBED element):
- Background—The same property discussed earlier. However, this makes it easy to change the background color at any time.
- EnableFramerateCounter—A Boolean property that toggles the display of the current frame rate in the browser's status bar. (This is potentially useful for debugging purposes.)
- EnableRedrawRegions—Another Boolean property meant for debugging, this highlights regions of the screen that are redrawn on each frame, when set to true.
- EnableHtmlAccess—The same property discussed earlier.
- MaxFrameRate—The same property discussed earlier.
- Windowless—The same as the isWindowless property discussed earlier.
For example, the EnableRedrawRegions and Background properties can be set in a Silverlight onLoad event handler as follows:
function myFunction(control, context, rootElement)
{
control.Settings.EnableRedrawRegions = true;
control.Settings.Background = "Red";
}
These properties, and all other members exposed on the control object, are pretty flexible. For example, they are not case sensitive. Many people prefer using lowercase names because it matches JavaScript conventions, as in the following code that produces the same result as the preceding snippet:
function myFunction(control, context, rootElement)
{
control.settings.enableRedrawRegions = true;
control.settings.background = "Red";
}
In addition, the Boolean properties can be set to a true or false string or to a true or false Boolean literal, and they work correctly either way.
None of the Settings members are extremely compelling, however, as it's rare you would need to retrieve or change the data after the control has loaded.
The Content Property
The most commonly used member on the Silverlight control is its Content property, which represents the XAML content hosted by the control and exposes some interesting functionality. It has the following subproperties:
- ActualWidth and ActualHeight—Report the dimensions of the Silverlight control. You can discover the same information by using the HTML DOM, although these Silverlight properties give different values than the corresponding HTML properties when the browser zoom level (an Internet Explorer feature) is not 100%. These Silverlight properties always report the real dimensions, whereas the HTML properties report the virtual dimensions (in essence, hiding the zoom level).
- Root—The instance of the root element in the current XAML content. This is the same object passed to onLoad as the rootElement parameter. (This property makes the rootElement parameter unnecessary because the handler can always use control.Content.Root instead.)
- FullScreen—Enables the Silverlight content to fill the entire screen. To prevent hostile Silverlight applications from holding your screen hostage, full-screen mode must be initiated by a user action (such as a mouse click or key press). Therefore, this functionality is covered in Chapter 7, "Responding to Input Events."
- Accessibility—Enables you to customize how the Silverlight control appears to accessibility software. The Accessibility object contains three settable properties: Title, Description, and ActionDescription (see Chapter 7 for more information).
Content exposes three functions explained in Chapter 2, "XAML," and Chapter 8, "Downloading Content on Demand":
- CreateFromXaml—Dynamically creates Silverlight content specified in XAML in a JavaScript string.
- CreateFromXamlDownloader—Dynamically creates Silverlight content specified in a XAML file downloaded on demand.
- FindName—Finds the instance of a Silverlight object defined in XAML based on an assigned name.
Content even exposes two unique events that cannot be consumed any other way. For example, you cannot specify either of these in the events array passed to createObject and createObjectEx. These two events are
- OnResize—Raised whenever the value of Content's ActualWidth or ActualHeight property changes
- OnFullScreenChange—Raised whenever the value of Content's FullScreen property changes
A handler can be attached to either event by assigning a function reference. Listing 1.11 demonstrates this for the OnResize event.
Listing 1.11. CreateSilverlight.js—Assigning an OnResize Handler
function createSilverlight()
{
Silverlight.createObjectEx(
{
source: "Chapter1.xaml",
parentElement: document.getElementById("placeholder"),
id: "silverlightControl",
properties:
{ width: "390", height: "100", version: "1.0", background: "Yellow" },
events: { onLoad: myFunction }
}
);
}
function myFunction(control, context, rootElement)
{
control.Content.OnResize = function()
{
var htmlElement = document.getElementById("silverlightControl");
alert("Actual Dimensions: " + control.Content.ActualWidth + "x" +
control.Content.ActualHeight);
alert("Virtual Dimensions: " + htmlElement.offsetWidth + "x" +
htmlElement.offsetHeight);
};
}
In this example, OnResize is set to a JavaScript closure (a function defined inside another function), which displays the control's dimensions according to Silverlight and according to the HTML DOM. If you try this with any of the examples in this chapter and change Internet Explorer's zoom level to 200%, you'll see that the HTML DOM still reports dimensions of 390x100 but Silverlight reports dimensions of 780x200. Although Internet Explorer doesn't want web pages to know when they are being zoomed (because they could do weird things that interfere with proper zooming), leveraging this information can be critical for Silverlight content because the visual elements inside the control do not get scaled automatically. Chapter 6, "Positioning and Transforming Elements," discusses the resizing of Silverlight content.
Other Members
In addition to the Settings and Content properties, the Silverlight control defines three more properties:
- InitParams—Gives whatever string was set (if any) for the initParams parameter to createObject or createObjectEx (or directly on the OBJECT/EMBED element). Although InitParams is always exposed to JavaScript as a single string, a comma-delimited list will be split into an array of strings passed to .NET code in future versions of Silverlight.
- IsLoaded—Reports whether the Silverlight content has been loaded.
- Source—Gives the control's source URL or #id value. This property can also be set to a new URL or #id value. This causes the control to reload with the new content, and the onLoad event will be raised again.
The control also directly defines two functions:
- CreateObject—Enables you to create an instance of the downloader object described in Chapter 8.
- IsVersionSupported—Given an input string containing a version number such as 1.0, this function tells you whether the installed version of Silverlight is compatible with that version. Silverlight.js uses this internally to perform its version checking.
The control also defines a single event—OnError—that is the same as the onError event described earlier. By assigning a function reference to the control's OnError member, you can change the default error handler at any time. Note that the control does not have an OnLoad member. You can only assign a handler for the onLoad event using the approaches discussed earlier.