Guide to developing CKAN GUI plugins - HebaruSan/CKAN GitHub Wiki

As of version 1.5.5, the CKAN-GUI supports external plugins which can modify and extend the interface and the behavior of the client. This guide is intended for .NET developers who wish to create their own plugins for ckan.exe.

This guide uses code from the WebBrowser plugin sample, if you are ever in doubt look there first.

Setting up your development environment

Windows users should use the latest available Visual Studio version (free edition is fine), Linux/ OSX users should use MonoDevelop. Compiling CKAN plugins requires the same setup as CKAN itself, so please follow this cross- platform CKAN build guide to finish setting everyting up.

Creating a new project

After setting up your IDE, you should create a new C# .NET 4.0 project, please turn to either VS or MonoDevelop's documentation if you're unsure how to do this. You should name your project properly, plugin names should follow the CKAN identifier specification (i.e. ASCII, no spaces, no special characters except -). For this guide we've chosen WebBrowserPlugin.

At this point you should have an empty (or almost empty) project. You should add two references now - one to ckan.exe and another to System.Windows.Forms. That's it, we're ready to write some code.

The IGUIPlugin class

All plugins inherit from the abstract IGUIPlugin class. It's a very simple interface and is short enough to be listed here in full:

public abstract class IGUIPlugin
{
    public abstract string GetName();
    public abstract Version GetVersion();
    public abstract void Initialize();
    public abstract void Deinitialize();
}

For this guide we'll need only one source file which we'll call WebBrowserPlugin.cs. The first thing to do it to setup our plugin class.

using System.Windows.Forms;
using CKAN;

namespace WebBrowserPlugin
{
    public class WebBrowserPlugin : CKAN.IGUIPlugin
    {
        private readonly string NAME = "Web Browser";
        private readonly CKAN.Version VERSION = new CKAN.Version("v1.0.0");
       
        public override void Initialize() { }
        public override void Deinitialize() { }
        public override string GetName() { return NAME; }
        public override CKAN.Version GetVersion() { return VERSION; }

    }
}

This is the basic plugin setup. A few important points:

• The name of the namespace and the class should match the name of your plugin DLL e.g. FooBar.dll should contain class FooBar.FooBar : IGUIPlugin
• The name returned by GetName() is what's displayed to the user and can be any string
• The version string passed to CKAN.Version() should be in the format "vX.Y.Z" where X, Y and Z are integers.

If we compile this now and add WebBrowserPlugin.dll to CKAN (either from the GUI or by copying it to KSP/CKAN/Plugins) it should detect it but as we have an empty Initialize() method our plugin still does nothing. Let's change that by adding some code:

public override void Initialize()
{
    var webBrowser = new WebBrowser(); // creates a new WebBrowser control
    webBrowser.Dock = System.Windows.Forms.DockStyle.Fill; // docks the control fully in the parent control
    webBrowser.Url = new System.Uri("http://kerbalstuff.com", System.UriKind.Absolute); // we want to open KerbalStuff

    var tabPage = new TabPage(); 
    tabPage.Name = "KerbalStuffBrowserTabPage"; // name our TabPage to something unique
    tabPage.Text = "KerbalStuff"; // this is the tab name in the GUI

    tabPage.Controls.Add(webBrowser); // add our WebBrowser control to the tab

    // here's where the magic happens
    // we add our tab page to CKAN's TabController
    // and we then we show it to the user
    // index 1 means this will be the second tab from left to right
    Main.Instance.m_TabController.m_TabPages.Add("KerbalStuffBrowser", tabPage);
    Main.Instance.m_TabController.ShowTab("KerbalStuffBrowser", 1, false);
}

At this point feel free to compile and test out the code above. You should see a second tab named "KerbalStuff" in CKAN which embeds a working browser with kerbalstuff.com open. The last thing left to do is clean- up after ourselves properly by implementing the Deinitialize method.

public override void Deinitialize()
{
    // hide our tab if it's open currently
    Main.Instance.m_TabController.HideTab("KerbalStuffBrowser");
    // and remove it from the TabController
    Main.Instance.m_TabController.m_TabPages.Remove("KerbalStuffBrowser");
}

That's it, you now have a working CKAN plugin that you can publish on the forums for rep. If you have any questions or encounter any difficulties, post an issue here and tag @AlexanderDzhoganov.

More plugin samples can be found here.