Silverlight SDK

[This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]

Silverlight Object Models

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

This topic contains the following section:

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 allows you to manipulate the nodes and objects 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 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, so developers need to be aware of these differences in order to create platform-neutral content. Silverlight can be accessed by the following browser DOMs:

DOM Description
Gecko DOM (Mozilla, Firefox, Netscape 6+, 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 Object Model (Internet Explorer 4+) The Dynamic HTML (DHTML) Document Object Model (DOM) allows 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 allow you to create a Silverlight application. The Silverlight object model is exposed through the Silverlight control, which you create as the host container on a Web page. For more information on hosting a Silverlight control on a Web page, see Using a Silverlight Control.

The following diagram shows the relationship of the Web page, the Silverlight control host, and the Silverlight content:


Relationship of Web page to Silverlight content

Once you have created the Silverlight control, you can retrieve a reference to the Silverlight control by using its id value in the Document Object Model (DOM) for the Web page. The following JavaScript example shows how to retrieve the id value of the Silverlight control by using the document.getElementById method:

JavaScript
var control = document.getElementById("myControl");

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.

For more information on referencing a Silverlight control and its content, see Using a Silverlight Control.

Silverlight Hierarchy of XAML Objects

When you add XAML objects to the Silverlight control, you are defining a hierarchical tree structure with a root object. For example, the following XAML example creates a object hierarchy containing a parent Canvas object and a child TextBlock and Canvas object. 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="http://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. For example, the content in the previous XAML example is converted into the following tree structure:


XAML content as a tree structure
 

The tree structure determines the rendering ordering of Silverlight objects. The order of traversal starts with the root object, which is the top-most 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 the content of a child object is rendered in front of the object's own content. Here is the rendered output from the previous XAML example, showing the rendering order sequence:

XAML output
Rendering order of XAML content

Adding XAML Objects to the Silverlight Object Hierarchy

When you create content for a Silverlight control, you set the Source property of the control 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 control. For more information on using these helper files, see Using CreateSilverlight.js and Silverlight.js.

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 control.
    var control = sender.getHost();

    // Create a TextBlock using a literal XAML string.
    var textblock = control.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 on adding XAML content to existing objects, see Using the CreateFromXaml Method.

Other Silverlight Objects

The Downloader object is a special-purpose Silverlight object that provides the ability to download content, such as XAML content, JavaScript content, or media assets, such as images. By using the Downloader object you do not have to provide all application content when the Silverlight control is instantiated. Rather, 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 on using the Downloader object, see Using a Downloader Object.

See Also

Using a Silverlight Control, Using CreateSilverlight.js and Silverlight.js, Silverlight Events