WinForms Visual Plugins (.NET Framework)

In this article we will describe how to create a new .NET WinForms visual plugin, and talk about what features it provides and how they can be used.

Getting Started

Before we start to create our first plugin, let's take a look at a whole Hydra plugin project.

The Hydra plugin project consists of three parts:

• Plugin Module - A Class Library project that acts as a container for the module controller and can hold a set of plugins.
• Module Controller - Entry point of the module. The module controller supplies the host with information about stored plugins and provides methods that allow the host to instantiate and work with plugins.
• Plugins - Special classes that are stored inside the plugin module.

Now we can learn how to create and set up a Hydra plugin project and add a visual WinForms plugin to it.

Working with Wizards

First we need to create a new module, to do this select File -> New -> Project in the Visual Studio menu, choose the language you need (we provide templates for C#, VB.NET and Oxygene for .NET), then, in the RemObjects Hydra category, choose Plugin Module:

In this dialog you also need to enter a project name and destination folder.

After you press OK, the wizard will create a new plugin module and add a module controller to the project. We will describe how to set up the module controller later in this article.

Now that we have a plugin module, we can add a plugin to it. Select Project -> Add New Item from the VS menu and then select Visual Plugin:

Select a name for the new plugin and press Add. And we are done, the wizard will now add a new visual plugin to the project.

The plugin module can contain as many plugins as you want, and you can also have visual and non-visual plugins in the same project.

Review the resulting project

Now let's review the resulting project. There are three parts:

Plugin Module

The plugin module is a Class Library project that will produce an assembly file that can be used by any of the supported host platforms.

The wizard automatically adds a reference to the RemObject.Hydra.dll assembly that contains the Hydra core classes; if you use this plugin module with Delphi (VCL or FireMonkey) hosts, you will need this file to be present in the same folder as your plugin, so you may want to tune your project so it will automatically copy the core dll into the destination folder. To do so select Properties of the RemObjects.Hydra.dll:

On the Properties page set CopyLocal to true:

In the AssemblyInfo.cs set the following assembly attribute:

[assembly: ComVisible(true)]

Please do not change this attribute, it will allow the host application to access the interfaces exposed by the plugin.

Module Controller

The module controller is a class that acts as an entry point for the plugin module. The host will instantiate this class on module load to get information about the plugins.

The wizard generates the following code for the module controller:

[ModuleController]
TheModuleController = public partial class(RemObjects.Hydra.ModuleController)
private
protected
  method Dispose(aDisposing: boolean); override;
public
  constructor;
end;

The module controller is inherited from the ModuleController, which itself descends from System.ComponentModule.Component. By default the controller holds two image lists that can be shared with the host application.

Also please note the ModuleControllerAttribute, it allows you to set additional meta-data, for example:

[ModuleController(Name := 'Controller', Description := 'My module controller', UserData := 'Data')]
TheModuleController = public partial class(RemObjects.Hydra.ModuleController)
[..]

[ModuleController(Name = "Controller", Description = "My module controller", UserData = "Data")]
public partial class TheModuleController : ModuleController
[..]

Visual Plugin

The Visual Plugin is the control that can be embedded into the host application. It is inherited from the RemObjects.Hydra.VisualPlugin class that allows it to be used in a cross-platform environment; this control is inherited from System.Windows.Forms.UserControl, so it provides the same design surface as the regular UserControl does.

The code that was generated by the wizard looks like this:

[Plugin, VisualPlugin]
Plugin1 = public partial class(RemObjects.Hydra.VisualPlugin)
protected
  method Dispose(aDisposing: boolean); override;
public
  constructor;
end;

[Plugin, VisualPlugin]
public partial class Plugin1 : VisualPlugin
{
    public Plugin1()
    {
        InitializeComponent();
    }
}

Please do not remove the PluginAttribute and the VisualPluginAttribute, as they are used by the host application to indicate that the class is indeed a plugin and also used to read plugin meta-data.

As in the module controller you can set the meta-data manually:

[Plugin(Name := 'SamplePlugin', Description := 'This is sample plugin', UserData := 'Data'), VisualPlugin]
Plugin1 = public partial class(RemObjects.Hydra.VisualPlugin)
[..]

[Plugin(Name = "SamplePlugin", Description = "This is sample plugin", UserData = "Data"), VisualPlugin]
public partial class Plugin1 : VisualPlugin
[..]

Using the plugin

By now you will have a complete project that, without any additional work, can be loaded by all supported host platforms.

Both module controller and visual plugin provide a set of internal methods that are used by the Hydra framework to perform specific tasks, however, they also provide some useful methods/properties which can be used in your own application.

Below we will describe the most common way to use the module controller and plugin, but first, let's talk about custom interfaces. One of the major parts of the Hydra framework are custom interfaces. Custom interfaces are user-defined interfaces that can be used in the cross-platform environment (they can, for example, be shared between a FireMonkey host and a .NET plugin) to receive access to data or to call host or plugin methods. When we talk about things like "accessing host methods" we refer to the custom interfaces, but since this is a large topic, we can't cover it in this article, so if you feel like you need to use them, please take a look at thise article: Passing Interfaces between Host and Plugins

Before we start to describe the visual plugin itself, let's look at how you can use the module controller.

How to use Module Controller

While the main purpose of the module controller is to provide information about plugins to the host, it can also be useful with some specific tasks.

The host will instantiate the module controller only once on module load, so it can be used to initialize some global data or allow the host to gain access to global methods via custom interfaces.

By default the module controller holds two ImageList controls, assigned to the SmallImages and LargeImages properties. These image lists will be passed to the host application, so you can use them to store shared images.

ModuleController also has an event called HostChanged. This is an important event if you need to be able to access host methods or data. Since the controller is initialized on module load, it doesn't have access to the Host property at the time when its constructor is executed. When the host assigns its reference to the module controller, the HostChanged event is fired and you can safely get access to the host. One thing that you need to consider is that this event can be called with a null host reference (when the host unloads a module) so you need to check this before accessing host members.

The last thing that is available to the module controller is the Host property; this property holds the reference to the host object, and can be used to access host methods or data.

How to use the Visual Plugin

WinForms visual plugins are derived from UserControl and provide exactly the same design surface. You can use them in the same way as your regular user controls. The biggest difference of course being that you can load and embed these plugins into any supported host application.

Like module controller, RemObjects.Hydra.VisualPlugin provides access to the Host property and HostChanged events, so everything that was said above for the module controller also applies to the visual plugin.

Visual plugins also provides the ability to define a set of actions that can be accessed and executed from the host; the Actions property holds this list, and you can edit it in design time by using the embedded editor:

Each Action provides the ability to set things like caption, hint and assign an has to events OnExecute and OnUpdate.

You can also assign an image to each action; for this purpose the visual plugin provides an Images property that takes regular ImageList.

If plan to you use a WinForms visual plugin in a Delphi host, you can also use its ability to work with menus and toolbars. To do this, you need to define a set of menus or toolbars in the Toolbars property, the next screenshot shows the design time editor:

If you need more information about how to work with actions, menus and tool-bars, please refer to the Hydra support for Menus and Toolbars article.