Writing Docklets

From Docky
Jump to: navigation, search

Writing Docky Extensions

Docky has two methods with which 3rd party developers can create new extensions. The first, and more traditional, method is through mono based plugins using Mono.Addins as a plugin infrastructure. The second method is over a dbus interface, for which a convenience python wrapper has been written. The dbus interface can be accessed through any language however.

Which Interface Should I Use?

Generally speaking, use the dbus interface unless you really need to use the more robust mono interface. As the interfaces progress, the dbus interface may almost completely replace the mono interface. They do however have a couple differences.

  • Only the dbus interface (helpers) can add new menu items to dock items it does not own
  • Only the mono interface (docklets) can add entirely new items to the dock or add dock painters to draw on the dock (like weather/calendar do)

So in short. If you wish to modify existing items, use the dbus interface. If you wish to add new items, use the mono interface.

Mono Interface (Docklets)

There are two parts to writing a docklet. The first is the make the class(es) for the item(s) you want to add to the dock. Let's look at a very simple example.

 public class DesktopDockItem : IconDockItem
 {
    public DesktopDockItem ()
    {
       HoverText = Catalog.GetString ("Show Desktop");
       Icon = "desktop";
    }
 
    public override string UniqueID ()
    {
       return "Desktop";
    }
 
    protected override ClickAnimation OnClicked (uint button, Gdk.ModifierType mod, double xPercent, double yPercent)
    {
       if (button == 1) {
          Wnck.Screen.Default.ToggleShowingDesktop (!Wnck.Screen.Default.ShowingDesktop);
          return ClickAnimation.Bounce;
       }
       return ClickAnimation.None;
    }
 }

This is the code for the DesktopDockItem. The constructor sets the hover text and the name of the icon to display. Since this is an IconDockItem, we can specify the icon name otherwise we would have to draw the icon ourselves.

The UniqueID is used for serializing the dock to the configuration backend (GConf). This must be unique for each item created! If you want 3 items of this type on a dock, they all must have unique identifiers!

The OnClicked method handles clicks. If it is a left click (button == 1) then we perform our action. The return type states what type of animation to do.

The other thing your docklet must have is an item provider.

 public class DesktopItemProvider : AbstractDockItemProvider
 {
    public override string Name { get { return "Desktop"; } }
 
    public override string Icon { get { return "desktop"; } }
 
    DesktopDockItem desktop;
 
    public DesktopItemProvider ()
    {
       desktop = new DesktopDockItem ();
       Items = desktop.AsSingle<AbstractDockItem> ();
    }
 
    public override void Dispose ()
    {
       desktop.Dispose ();
    }
 }

Item providers need a name, an icon (which is used as the icon for the docklet in the configuration dialog) and takes care of listing all Items it provides. Items is an enumeration, which you set to your list of icons to show. This example creates exactly one item (desktop).

Class Specifications

Item class hierarchy

+ AbstractDockItem
  + IconDockItem
    + ColoredIconDockItem
  + FileDockItem
  + WnckDockItem
    + ApplicationDockItem
    + WindowDockItem

Item Provider class hierarchy

+ AbstractDockItemProvider