How to: Plugins

So you want to make a plugin for the Sphere studio, but don't know where to start? Have no fear! This guide will help you get started on the basics.

Plugin Creation

There are two types of plugins you can implement:

1. A standard plugin, IPlugin
2. An editor plugin, IEditorPlugin

A standard plugin contains the following interface, that you must implement:

• string Name
• string Author
• string Version
• string Description
• Icon Icon
• IPluginHost Host
• void Initialize()
• void Destroy()

An EditorPlugin just adds one extra method in addition to the above:

• DockContent OpenEditor(string filename)

The four string values are simple C# getters, the host just has to be present, the editor will fill in the host with a version of itself, and the only two methods need implementations.

using System.Drawing;
using Sphere.Plugins;

namespace MyPlugin
{
    class MyPlugin : IPlugin
    {
        public string Name { get { return "My Cool Plugin"; } }
        public string Author { get { return "Me"; } }
        public string Description { get { return "An awesome plugin, that's really cool!"; } }
        public string Version { get { return "1.5a"; } }
        public Icon Icon { get; set; }
        public IPluginHost Host { get; set; }

        public void Initialize()
        {
            /* ...code here... */
        }

        public void Destroy()
        {
            /* ...code here.... */
        }
    }
}

That's all there is to a simple plugin.

Example Plugin Behavior

So, we have made a plugin, but it does nothing. So, how can plugins do work? Well, in the initialize method you talk to the host. The host will then do the work of linking the functionality of your plugin to the editor. This is facilitated in two ways: by adding a filetype registration, or by adding a menu item. We'll explore the route of the menu item for now.

Let's make the plugin print '42' in a message box by clicking on the appropriate menu item. Let's examine the plugin again and add to it a ToolStripMenuItem.

using System;
using System.Drawing;
using System.Windows.Forms;
using Sphere.Plugins;

namespace MyPlugin
{
    class MyPlugin : IPlugin
    {
        public string Name { get { return "My Cool Plugin"; } }
        public string Author { get { return "Me"; } }
        public string Description { get { return "An awesome plugin, that's really cool!"; } }
        public string Version { get { return "1.5a"; } }
        public Icon Icon { get; set; }
        public IPluginHost Host { get; set; }

        private ToolStripMenuItem my_item;

        public MyPlugin()
        {
            my_item = new ToolStripMenuItem("Print Me");
            my_item.Click += new EventHandler(MyClick);
        }

        /* Custom method shows a .NET message box containing '42'. */
        private void MyClick(object sender, EventArgs args)
        {
            MessageBox.Show("42");
        }

        /* Here we talk to the host, adding a menu item */
        public void Initialize()
        {
           Host.AddMenuItem("NewMenu", my_item);
        }

        /* Here we talk to the host, removing the item */
        public void Destroy()
        {
            Host.RemoveMenuItem(my_item);
        }
    }
}

Now, when you click on the new menu item called 'NewMenu', it'll have a new item attached to it. Clicking that item will show the dialog box.

Adding a dock panel control to the editor.

So, you have added menu items to do things, but now want to add a custom widget to the editor. It can be done with the Host's DockControl() method.

using System;
using System.Drawing;
using System.Windows.Forms;
using Sphere.Plugins;

namespace MyPlugin
{
    class MyPlugin : IPlugin
    {
        public string Name { get { return "My Cool Plugin"; } }
        public string Author { get { return "Me"; } }
        public string Description { get { return "An awesome plugin, that's really cool!"; } }
        public string Version { get { return "1.5a"; } }
        public Icon Icon { get; set; }
        public IPluginHost Host { get; set; }

        // made as a WinForms UserControl in the MSVC editor:
        private MyControl my_control;

        public MyPlugin()
        {
        }

        public void Initialize()
        {
            my_control = new MyControl();

            DockContent my_content = new DockContent();
            my_content.Text = "My Control";
            my_content.DockAreas = DockAreas.Document | DockAreas.DockLeft;
            my_content.Controls.add(my_control);
        
            Host.DockControl(my_content, DockState.Document);
        }

        public void Destroy()
        {
            Host.RemoveControl("My Control");
            my_control.Dispose();
        }
    }
}

And that's how you do it. For a more complete example see the task list plugin implementation, which also shows the use of an embedded resources object (for the Icon) and a third party library: ObjectListView.