Using a Silverlight Plug-in

When you install the Microsoft Silverlight run-time components, you install a browser plug-in. The Silverlight plug-in is packaged differently on different platforms. On the Windows operating system, Internet Explorer uses ActiveX technology to host Silverlight plug-ins, whereas all other browser and platform combinations use the Netscape plug-in technology.

This topic contains the following sections:

• The Silverlight Plug-in in Context
• Using JavaScript Helper Files to Create a Silverlight Plug-in
• Referencing the Plug-in Instance at Run Time
• Referencing the Plug-in's Properties, Methods, and Events at Run Time

The Silverlight Plug-in in Context

There are a number of components that make up a typical Web page with embedded Silverlight content. The diagram below summarizes these components:

Each of these components is summarized below:

• Web Page: The Web page in which the Silverlight-based application is embedded (or hosted).
• HTML Placeholder Element: The block-level HTML element (usually a <DIV> tag) that is used to contain the Silverlight plug-in and that therefore determines where in the Web page the Silverlight-based application is rendered.
• Silverlight Plug-in: The Silverlight plug-in that renders the Silverlight content. This plug-in is defined in an HTML page by creating an <OBJECT> or <EMBED> tag and setting its parameter values. Functions in the Silverlight.js helper file produce this <OBJECT> or <EMBED> tag output. See Using JavaScript Helper Files to Create a Silverlight Plug-in below. As will be discussed in this overview, you can access this plug-in and reference its properties, methods, and events at run time.
• Silverlight Content: The XAML content that makes up the presentation of your Silverlight-based application.

Note: If you would like to walkthrough using these components to create a Silverlight-based application, see parts 1 and 2 of the Silverlight 1.0 QuickStart.

Using JavaScript Helper Files to Create a Silverlight Plug-in

The Silverlight samples available on the Microsoft Silverlight Web site and in the SDK use a pair of JavaScript helper files, CreateSilverlight.js and Silverlight.js, to initialize and create Silverlight plug-ins on a Web page. A Silverlight plug-in is defined in an HTML page by creating an <OBJECT> or <EMBED> tag and setting its parameter values. Functions in Silverlight.js produce this <OBJECT> or <EMBED> tag output. They also provide installation or upgrade dialog boxes that will display in case the requested version of the Silverlight runtime is not available on the user's computer.

Using the Silverlight.js file is the required technique for using Silverlight plug-ins in an application. The CreateSilverlight.js file is a convenience file that lets you package and provide specific parameters to the methods that are defined in Silverlight.js.

For more information about using Silverlight.js and CreateSilverlight.js to instantiate a Silverlight plug-in or to check for version information, see Using CreateSilverlight.js and Silverlight.js.

Referencing the Plug-in Instance at Run Time

The GetHost method can be used by any UIElement-derived object to retrieve the Silverlight plug-in that contains the object. This method is especially useful for retrieving the Silverlight plug-in in an event-handling function in which the sender parameter identifies a UIElement-derived object.

The following JavaScript example shows how to retrieve a Silverlight plug-in in a KeyUp event-handler function.

function onKeyUp(sender, keyEventArgs)
{
    // Determine whether the keystroke combination CTRL+V was detected.
    if ((keyEventArgs.key == 51) && (keyEventArgs.ctrl == true))
    {
        // Retrieve a reference to the plug-in.
        var plugin = sender.getHost();

        // Determine whether the 1.0 version of Silverlight is available.
        alert("Silverlight 1.0: " + plugin.isVersionSupported("1.0"));
    }
}

If you need access to the plug-in's Document Object Model (DOM) values, such as width and height, you can retrieve a reference to the Silverlight plug-in by using its ID in the DOM for the Web page. The following JavaScript example shows how to retrieve a reference to the Silverlight plug-in by using the document.getElementById method.

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

For more information on the DOM and the Silverlight Object Model, see Object Models.

Referencing the Plug-in's Properties, Methods, and Events at Run Time

You can access the members of a Silverlight plug-in at run time in three ways:

• By referencing the Silverlight plug-in object.
• By referencing the Silverlight plug-in's settings property, which is a sub-object that groups certain properties and methods.
• By referencing the Silverlight plug-in's content property, which is a sub-object that groups certain properties and methods.

The following diagram illustrates how a Silverlight plug-in's properties, methods, and events are grouped at run time.

Silverlight plug-in settings and content groups

Accessing Plug-in Members Directly

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

Accessing Plug-in Members by Using the Settings Property

The following table lists the properties that are accessible as settings members of the Silverlight plug-in at run time.

Accessing Plug-in Members by Using the Content Property

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

See Also