Requirements for Main Plug-in Objects (Windows Embedded CE 6.0)

Article
01/05/2012

1/6/2010

In a plug-in based on the Remote Tools Framework, the implementation of the main plug-in object is contained in the MyPlugin.cs file. Each time the Remote Tools Framework loads a plug-in, an instance of this main plug-in object is created.

The main plug-in object must be derived from the Microsoft.RemoteToolSdk.PluginComponents.PluginComponent class, and the following two methods must be implemented in the derived class.

public abstract string Description { get; }
public abstract void OnInit();

Description

The Description property provides a description of your plug-in for the Remote Tools Shell to display at the top level in TreeView. For more information, see the Remote Tools Shell.

OnInit()

The OnInit method must perform the following tasks for your plug-in.

Build plug-in data objects and place them in an array supplied by the Remote Tools Framework.
Build plug-in data view objects if the custom views associated with the objects are implemented for the plug-in.
Define the nodes that the Remote Tools Shell displays in TreeView.

Building Plug-in Data Objects

A typical plug-in includes TreeView nodes that either contain data or supply a label that organizes the data into a hierarchy.

A developer typically creates one plug-in data object for each TreeView node that contains data. Each data object is assigned the same GUID, and that GUID is identical to the GUID for the plug-in node.

After the data object is created, you can use it to populate an array of data objects. The Remote Tools Framework supplies the empty array that you use to hold the data objects. You can gain access to the empty array through the *base.*DataArray property of the plug-in object.

The following code example from the SimplePlugin sample plug-in shows an array that is populated by using the DataArray property.

public override void OnInit()
{
    // Build the data object
    this.data = new MyData(this, guidChildNode1);
    base.DataArray.Add(this.data);
}

For more information about plug-in data objects, see Requirements for Plug-in Data Objects.

Building Custom Views

If there are any custom view implementations, OnInit builds them. For more information about custom views and how to implement them, see Requirements for Plug-in Data View Objects.

The following code example from the SimplePlugin sample plug-in uses OnInit to build a custom view.

this.view = new MyView (this.data);

Defining Shell TreeView Nodes

Regardless of whether a given node contains data or is a label, OnInit defines that node. To define a node, create an object of the type PluginNode, and add it to the base.Nodes array.

For more information, see PluginNode in the Remote Tools Framework Native API.

You only need to define nodes for the plug-in itself because the Standalone property of the PluginComponent class indicates whether the plug-in is loaded into a standalone host and not with other plug-ins. Typically, when a plug-in is added as a standalone plug-in, the caption for the main form already displays the plug-in name, making a top-level node redundant.

For more information, see Standalone property in the Remote Tools Framework Native API.

The constructor for the PluginNode object takes a GUID, a parent GUID for setting up the hierarchy, a data object, and a view object. The configuration for these varies depending on the type of node that you want to define.

The following table shows the configuration for each type of node.

Type of node	Configuration
Label	Set the data and view objects to null.
View with no data	Leave the data object null, and set a view object. An example of this is a splash screen with a logo.
Data, using the default Generic View in the Remote Tools Shell	Set the data object and leave the view object null.
Data, using a custom view	Set both the data and view objects.

Code Example

The following code example shows how to implement a two-node setup in the SimplePlugin sample plug-in or a single-node setup in a standalone plug-in.

if (base.Standalone)
{
    guidTopLevelNode = null;
}
else
{
    // Add a top-level node by setting the GUID 
    // for the parent to null. No data or view 
    // is associated with this node
    base.Nodes.Add(
        new PluginNode(
            Description,      // description
            guidTopLevelNode, // guidNode
            null,        // guidParent
            null,       // data
            null,       // view
            this,       // hostPlugin
            // Use the built-in icon to indicate that
            // this node is a plug-in
            BuiltInIcon.Plugin
        )
    );
}
//
// Add the actual node for the data. Specify the GUID
// for the parent, and specify the data or view from the
// associated data type.
base.Nodes.Add(
    new PluginNode(
        "Child Node",....  // description
        guidChildNode1,....// guidNode
        guidTopLevelNode,..// guidParent
        this.data, ........// data
        this.view,         // view
        this,............  // hostPlugin
    // Use the built-in icon to indicate whether
    // this node contains data or is a view
    BuiltInIcon.NodeData
    )
);

Share via