NotifierLight Plugin-Development

Introduction

For NotifierLight there are three different types of Plugins in general.

  • Event Plugins are used to determine when a light should be active
  • Light Plugins are used to control which color a device should display.
  • Device Plugins are used to control a certain type of device. You can think of it like a driver.

Plugins are implemented as a .NET assembly but there can be multiple Plugins in each assembly. To create a NotifierLight Plugin you need to create a new ClassLibrary and add a reference to the PlugInInterface.dll which is located within the NotifierLight Directory.


Event Plugins

An Event Plugin consists of two classes. The first one is the PluginFactory which provides some metadata about the plugin and creates one or more running instances of the Plugin itself. The second class is the EventPlugin which can be started, stopped and which provides Events which can be triggered to notify the user.

Plugin Factory

A simple Event Plugin looks like this:

public class MyEventFactory : IEventPluginFactory
{
    // the name of the plugin
    string IPluginMetadata.Name {
        get { return "Test Plugin"; }
    }

    // the description of the plugin
    string IPluginMetadata.Description {
        get { return "For testing and plugin creation purposes"; }
    }

    // the author of the plugin
    string IPluginMetadata.Author {
        get { return "John Doe"; }
    }

    // the version of the plugin
    string IPluginMetadata.Version {
        get { return "1.0"; }
    }

    // Return true if the plugin is allowed to be added more than once
    public bool AllowMultipleInstances {
      get { return true; }
    }

    // create a new instance of the plugin class
    public IEventPlugin CreateEventPlugin()
    {
        return new MyEventPlugin();
    }
}

If you want to add an image to the plugin just implement the PluginImageMetadata interface within the EventFactory. If that interface is not implemented a default image will be used.

Plugin Instance

A simple plugin class may look like this:

public class MyEventPlugin : IEventPlugin
{
    // create an Event instance:
    private Event TestEvent = new Event("Test");


    // Create a public property to allow the user to set which light-sequence
    // (Blink / Static light etc.) will be displayed once the TestEvent is
    // triggered.
    [Category("Test")]
    public LightSequence Test {
        get{ return TestEvent.Sequence; }
        set { TestEvent.Sequence = value; }
    }

    // return all events that could be triggered by the plugin.
    public IEnumerable< event> GetEvents()
    {
        yield return TestEvent;
    }

    // Add your code to execute when starting plugin here
    public void StartPlugin()
    {
        SystemEvents.SessionSwitch += SystemEvents_SessionSwitch;
    }

    // Add your code to execute when disposing plugin here
    public void StopPlugin()
    {
        SystemEvents.SessionSwitch -= SystemEvents_SessionSwitch;
    }

    // Add more code you need for your plugin. In this example we only check if
    // the windows session is locked or unlocked. Use the Event.IsOn property to switch on/off
    public void SystemEvents_SessionSwitch(object sender, SessionSwitchEventArgs e)
    {
        if (e.Reason == SessionSwitchReason.SessionLock)
            TestEvent.IsOn = true; // Activate the TestEvent
        else
            TestEvent.IsOn = false; // Deactivate the TestEvent
    }
}


Every public property of a plugin will be visible in the PropertyGrid. Use the CategoryAttribute, BrowsableAttribute etc to control this behavior. They are automatically saved and restored between the program sessions. If you don't want to save a property, you will need to add a reference to the Newtonsoft.Json.dll and add a JsonIgnoreAttribute to that property. Advanced plugin settings should be marked with the AdvancedBrowsableAttribute to hide it from users which have not activated the advanced settings.

Notes

The Event Plugin API should be stable for the next releases but it might be changed in future. We try our best not to break your code :)

Downloads

Get a Test-Plugin as SharpDevelop project here. You can use it as template for your NotifierLight plugin.

PlugIn_Test.zip

No comments:

Post a Comment