Writing Plugins

Plugins Introduction

If this is your first time writing a plugin for GNOME Do, you may want to take a look at our guide to Getting_started_with_writing_plugins. A working knowledge of C# is assumed in this guide, there are plenty of resources for help with C# if you need more.

What is a GNOME Do plugin?

Plugins are the essence of Do, they provide actions and items for you to do things with.

Items

All classes that we touch in guide will inherit from IItem, IItem contains three properties that you must implement. Item is an implementation of IItem which you should extend when writing your own kind of Item.

string Name

The name of your Item

string Description

A short description of your item

string Icon

The icon for your item.

Actions

Actions are the do in Do. Writing an action is as simple as implementing the Act abstract class.

Example Plugin

using System;
using System.Linq;
using System.Collections.Generic;
 
using Do.Universe;
 
namespace AptURL {
 
    public class AptAction : Act {
 
        public override string Name {
            get { return "Install";  }
        }
 
        public override string Description {
            get { return "Use apturl to install a package"; }
        }
 
        public override string Icon {
            get { return "update-manager"; }
        }
 
        public override IEnumerable<Type> SupportedItemTypes {
            get {
                return new Type[] {
                    typeof(ITextItem)
                };
            }
        }
 
        public override IEnumerable<Item> Perform (IEnumerable<Item> items, IEnumerable<Item> modItems)
        {
            string package = (items.First () as ITextItem).Text;
 
            System.Diagnostics.Process.Start ("apturl apt:" + package);
            return null;
        }
    }
}

IEnumerable<Type> SupportedItemTypes

This property should return a set of supported types, our example action only accepts text, so you'll notice it only supports one type. Supporting other types is as simple as adding other yield statements. yield break, or null are also acceptable return values, they signify that no types are supported. This effectively renders your action useless.

IEnumerable<Type> SupportedModifierItemTypes

This method is virtual and defaults to null. if you don't support modifier items, you don't need to implement this. This is the analog to SupportedItemTypes for the third pane.

bool ModifierItemsOptional

This method is virtual and defaults to false. This determines if the third pane will be shown by default (or not at all if there are no supported types).

bool SupportsItem (Item item)

This method is virtual and defaults to true. If there is some special condition an item needs to meet for your action, this is where it should get checked.

bool SupportsModifierItemForItems (IEnumerable<Item> items, Item modItem)

This method is virtual and defaults to true. Similar to SupportsItem, but uses an array of Items as a context for determining whether or not a modifier item is supported. Items will have already been accepted by SupportsItem. The modifier Item is guaranteed to be a subtype of a type defined in SupportedModifierItemTypes. If the Act class implementing this interface does not support any modifier item types, this method will never be called.

IEnumerable<Item> DynamicModifierItemsForItem (Item item)

This method is virtual and defaults to null. If you would like to supply possible modifier items dynamically, you should do so here.

IEnumerable<Item> Perform (IEnumerable<Item> items, IEnumerable<Item> modItems)

Your perform method is where the work gets done. You are given the items and the modifier items selected by the user, and you can then return a new item, like the tinyurl plugin does, or simply return nothing.