Silverlight Object Models and Scripting to the Silverlight Plug-In

  • Article

Microsoft Silverlight-based scripting applications expose their functionality through a browser-based Document Object Model (DOM), as well as a Silverlight-specific object model. These object models enable you to create and manipulate Silverlight content.

This topic contains the following sections:

  • Document Object Model
  • Silverlight Object Model
  • Mixing Object Models
  • Scripting to the Silverlight Plug-In

Document Object Model

The Document Object Model (DOM) is a platform-neutral and language-neutral programming interface for HTML and XML documents. It provides a structured representation of a document, such as a Web page, as well as a defined way to access and manipulate the document's structure, style, and content. The DOM represents the document as a structured group of nodes and objects that have properties, methods, and events. This representation enables you to manipulate the nodes and objects by using procedural languages such as JavaScript.

The document object represents the entire HTML page and can be used to access all elements in a page. The body object represents the body of the document, which is represented as the <BODY> tag in the HTML page. The following HTML example shows how to set the content of the <BODY> tag to an HTML-formatted literal string by setting the innerHTML property.

HTML 
<html>
  <body/>
<html/>
<script language="JavaScript">
  document.body.innerHTML = '<b>Hello, world</b>';
</script>

The World Wide Web Consortium (W3C) DOM standard forms the basis of the DOM implemented in the most widely used browsers. However, most browsers offer extensions beyond the W3C standard. Therefore, developers need to be aware of these differences in order to create platform-neutral content. Silverlight can be accessed by the browser DOMs listed in the following table.

DOM Description
Gecko DOM (Mozilla, Firefox, Netscape version 6 and later, and other Mozilla-based browsers) Gecko is the software component that handles the parsing of HTML, the layout of pages, the document object model, and the rendering of the entire application. For more information, see Gecko DOM Reference.
DHTML DOM (Internet Explorer version 4 and later) The Dynamic HTML (DHTML) DOM gives authors direct, programmable access to the individual components of their Web documents, from individual elements to containers. For more information, see About the DHTML Object Model.

Silverlight Object Model

The Silverlight object model defines a set of objects that enable you to populate and adjust the content of a Silverlight-based application. The Silverlight object model is exposed through the Silverlight plug-in, which you create as the content container on a Web page. For more information about instantiating a Silverlight plug-in within a Web page, see Instantiating a Silverlight Plug-in.

The following illustration shows how the Web page, the Silverlight plug-in, and the Silverlight content interrelate.

Relationship between a Web page and Silverlight content

Relationship between a Web page and Silverlight content

This diagram shows the two object models available within the Web application: one for the HTML DOM and one for Silverlight. The Silverlight plug-in, represented in the HTML source as either an HTML Object or Embed tag, is conceptually the intermediate between the two object models. Certain properties or behavior of a Silverlight plug-in are available to either object model.

After you create the Silverlight plug-in, you can retrieve a reference to the plug-in instance by referencing its ID in the DOM for the Web page. The following JavaScript example shows how to retrieve the ID of the Silverlight plug-in by using the document.getElementById method.

JavaScript 
var plugin_1 = document.getElementById("SLPlugin_1");

Note   To retrieve the plug-in's DOM properties, you must 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.

Silverlight Hierarchy of XAML Objects

When you add XAML objects to the Silverlight plug-in, as initially declared by the Source property, you are defining a hierarchical tree structure with a root object. For example, the following XAML code creates a object hierarchy that contains a parent Canvas object and child TextBlock and Canvas objects. In this case, the first Canvas object defined is the root object for the tree structure.

XAML 
<!-- The top-most object in the XAML hierarchy is referred to as the root object. -->
<Canvas
  xmlns="https://schemas.microsoft.com/client/2007"
  Loaded="onLoaded">
  <!-- Canvas objects can be a child of another Canvas object. -->
  <Canvas
    Canvas.Left="20" Canvas.Top="20">
    <Rectangle
      Width="200" Height="35"
      Fill="PowderBlue" />
    <TextBlock
      Canvas.Left="25" Canvas.Top="5"
      Foreground="Teal" FontFamily="Verdana" FontSize="18" FontWeight="Bold"
      Text="Sample Output" />
  </Canvas>
  <TextBlock
    Canvas.Left="36" Canvas.Top="80"
    Foreground="Maroon" FontFamily="Verdana" FontSize="24" FontWeight="Bold"
    Text="Hello, world" />
</Canvas>

XAML content is converted into a a hierarchical tree structure with a root object. The following illustration shows the tree structure for the previous XAML content.

XAML content as a tree structure

XAML content as a tree structure

The tree structure determines the rendering order of Silverlight objects. The order of traversal starts with the root object, which is the topmost node in the tree structure. The root object's children are then traversed, left to right. If an object has children, its children are traversed before the object's siblings. This means that the content of a child object is rendered in front of the object's own content. The following illustration shows the rendered output and the rendering order sequence from the previous XAML example.

Rendering order of XAML content

Rendering order of XAML content

Adding XAML Objects to the Silverlight Object Hierarchy

When you create content for a Silverlight plug-in, you set the Source property of the plug-in to reference XAML content. The XAML content is parsed and converted into a Silverlight object hierarchy, which is then rendered. Setting the Source property is typically done indirectly through the use of JavaScript helper files, which provide initialization support for creating the Silverlight plug-in. For more information about using these helper files, see Instantiating a Silverlight Plug-in.

You can also add XAML content to existing objects in the XAML object hierarchy. For example, the following JavaScript example appends a TextBlock object to an existing Canvas object.

JavaScript 
// MouseLeftButtonUp event handler for the Canvas object.
function onMouseLeftButtonUp(sender, mouseEventArgs)
{
    // Retrieve a reference to the plug-in.
    var plugin = sender.getHost();
    // Create a TextBlock using a literal XAML string.
    var textblock = plugin.content.createFromXaml('<TextBlock Canvas.Top="50">Hello, again</TextBlock>');
    // Append the TextBlock to the sender, or Canvas, object.
    sender.children.add(textblock);
}

For more information about adding XAML content to existing objects, see Constructing Objects at Run Time.

Other Silverlight Objects

The Downloader object is a special-purpose Silverlight object that provides the ability to download content asynchronously, including XAML content, JavaScript content, and media assets such as illustrations. With this object, you do not have to provide all application content when the Silverlight plug-in is instantiated. Instead, you can download content on demand in response to application needs. The Downloader object provides functionality for initiating the data transfer, monitoring the progress of the data transfer, and retrieving the downloaded content. For more information about using the Downloader object, see Downloading Content on Demand.

Mixing Object Models

You can use JavaScript to bridge the DOM and the Silverlight object model. For example, suppose you have a TEXTAREA element in your HTML page (identified by id in the DOM) and you want to access the user input of that element and use the text value in your Silverlight-based application. The TEXTAREA element is declared as shown in the following code.

HTML 
...
<TextArea ID="myHTMLTextArea">Type something and Click the box below</TextArea>
...

In your XAML, you have a simple Canvas with a MouseLeftButtonDown event attached to it.

XAML 
<Canvas
  xmlns="https://schemas.microsoft.com/client/2007">
  <Canvas
    Width="200" Height="35"
    Canvas.Left="20" Canvas.Top="20"
    Background="PowderBlue"
    MouseLeftButtonDown="onMouseLeftButtonDown">
    <TextBlock
      Canvas.Left="25" Canvas.Top="5"
      Foreground="Teal" FontFamily="Verdana" FontSize="18" FontWeight="Bold"
      Text="Click" />
  </Canvas>
</Canvas>

The following JavaScript retrieves the text from the TEXTAREA and then outputs that content into the XAML. Here, value is a property of that particular object type in the DOM, which returns a string. That string is then used to set the inner text of a TextBlock, which also takes a string.

JavaScript 
function onMouseLeftButtonDown(sender, mouseEventArgs)
{
    // Retrieve the text from the TEXTAREA element in the HTML.
    var txtInput = document.getElementById("myHTMLTextArea").value;
    // Retrieve a reference to the plugin.
    var plugin = sender.getHost();
    // Create a TextBlock using a literal XAML string. Use the text from
    // the HTML object for the content of the TextBlock.
    var textblock = plugin.content.createFromXaml('<TextBlock Canvas.Top="50">' + txtInput + '</TextBlock>');
    // Append the TextBlock to the sender, or Canvas, object.
    sender.children.add(textblock);
}

This concept is illustrated by the following illustration. Although the two object models cannot access each other directly, JavaScript acts as a bridge, because the JavaScript code and variables that you set in JavaScript are accessible from either object model. The key entry points are the document object or event handlers for the DOM, and a Silverlight plug-in instance or event handlers for the Silverlight object model.

JavaScript object model map

JavaScript object model map

Scripting to the Silverlight Plug-In

The Silverlight plug-in itself has properties, methods, and events that are part of the Silverlight object model. Some of the properties were established on that particular plug-in instance when it was instantiated as an object within the DOM. In many of these cases, the property could be retrieved either from the DOM or from the Silverlight object model.

Within the Silverlight plug-in's own object model, some of the properties, methods, and events are available directly on the plug-in instance. To call these properties and methods, you would reference a variable that represented a particular instance, then add a dot, and then add the name of the property and method. Other properties, methods, and events are exposed on specific sub-objects of the Silverlight plug-in. The sub-object distinctions exist to provide some encapsulation of a Silverlight plug-in's functions and the object model in which they participate.

For more information about the APIs listed in the following tables, click the link in the Member column. This will navigate to the relevant page in the Silverlight Reference.

Accessing Plug-in Members Directly Available from the Plug-in Instance

The following table lists the properties, methods, and events that you can directly access from the Silverlight plug-in at run time.

Member Syntax Description
Content plugin.content Gets the content sub-object.
CreateObject retval = plugin.createObject(objectType) Creates a specified object and returns a reference to it.
InitParams plugin.initParams Gets the optional set of user-defined initialization parameters.
IsLoaded plugin.isLoaded Gets a value that indicates whether the Silverlight plug-in is loaded.
IsVersionSupported retval = plugin.isVersionSupported(versionString) Determines whether the installed Silverlight plug-in will support initialization if presented with a specified version string.
OnError plugin.onError = eventhandlerFunction Assigns a handler function that handles errors when the Silverlight plug-in generates a run-time error.
Settings plugin.settings Gets the settings sub-object.
Source plugin.source Gets or sets the XAML content to render.

Content Sub-Object Properties, Methods and Events

The following table lists the properties, methods, and events that are accessible as content members of the Silverlight plug-in at run time.

Member Syntax Description
Accessibility plugin.content.accessibility Gets an object that contains properties that report accessibility information to the Silverlight plug-in host.
ActualHeight plugin.content.actualHeight Gets the height of the rendering area of the plug-in.
ActualWidth plugin.content.actualWidth Gets the width of the rendering area of the plug-in.
CreateFromXaml retval = plugin.content.createFromXaml(xamlContent) Creates XAML content dynamically.
CreateFromXamlDownloader retval = plugin.content.createFromXamlDownloader(xamlContent, part) Creates XAML content dynamically by using downloader content.
FindName retval = plugin.content.findName(objectName) Returns a reference to an object in the Silverlight content object hierarchy by referencing the object's Name or x:Name attribute value.
FullScreen plugin.content.fullScreen Gets or sets a value that indicates whether the plug-in displays in full-screen mode.
OnFullScreenChange plugin.content.onFullScreenChange = eventhandlerFunction Occurs whenever the FullScreen property of the plug-in changes.
OnResize plugin.content.onResize = eventhandlerFunction Occurs whenever the ActualHeight or ActualWidth property of the plug-in changes.
Root plugin.content.root Gets the root object of XAML content.

Settings Sub-Object Properties

The following table lists the properties that are accessible by using the settings sub-object as an intermediate scripting property.

Member Syntax Description
Background plugin.settings.background Gets or sets the background color of the rectangular region that displays XAML content.
EnableFramerateCounter plugin.settings.enableFramerateCounter Gets or sets a value that determines whether to display the current frame rate in the hosting browser's status bar.
EnableRedrawRegions plugin.settings.enableRedrawRegions Gets or sets a value that determines whether to show the areas of the plug-in that are being redrawn with each frame.
EnableHtmlAccess plugin.settings.enableHtmlAccess Determines whether the hosted content in the Silverlight plug-in has access to the browser DOM.
MaxFrameRate plugin.settings.maxFrameRate Gets or sets the maximum number of frames to render per second.
Windowless plugin.settings.windowless Determines whether the Silverlight plug-in displays in windowless mode.

See Also

Object Positioning
Instantiating a Silverlight Plug-In
Silverlight Events
XAML Syntax
Overviews and How-to Topics