Executable

The code and content of a plug is stored in an executable binary. This binary has three basic goals:

1. Sub-class the abstract Pantheon.Switchboard.Plug class, which is a form of Gtk.Window. The contents of the plug class are "embedded" into the Switchboard application when the plug is launched.
2. Instantiate the plug class and register it with Switchboard.
3. Start the GTK+ main loop.

If you've worked with GTK+ before, you're probably thinking that this sounds very much like the workflow of a normal GTK+ standalone application. That's because it is :). The Switchboard API is designed to be easy to understand for GTK+ novices, yet still familiar to hardcore GTK+ veterans.

Generally speaking, plugs (and thus plug binaries) abstract a low-level settings backend, such as KeyFiles, gconf, dconf, or other APIs like ALSA and GStreamer, to a graphical user interface that is as adherent to the elementary HIG has possible.

The following is a very simple skeleton of a plug for changing the Desktop wallpaper. It is very well-commented, and provides a good starting point for just about every Plug.

// Sub-class the base plug from libpantheon.
public class WallpapersPlug : Pantheon.Switchboard.Plug {

    public WallpapersPlug () {

        // Add a normal GTK+ Label to the window.
        var l = new Gtk.Label("Wallpaper settings go here!");
        this.add(l);
    }
}

public static int main (string[] args) {

    Gtk.init (ref args);
    // Instantiate the plug, which handles
    // connecting to Switchboard.
    var plug = new WallpapersPlug ();
    // Connect to Switchboard and identify
    // as "Wallpapers". (For debugging)
    plug.register ("Wallpapers");
    plug.show_all ();
    // Start the GTK+ main loop.
    Gtk.main ();
    return 0;
}

Plugs are described (in a metadata sense) not by the binary, but rather by .plug files which reside in the same directory as the executable. Plug files are discussed in-depth in the next section.

.plug File

Switchboard uses keyfiles to store metadata about plugs.

A keyfile, if you're not familiar, is a simple plaintext syntax for storing key-value information that is both human readable and easily parse-able by various libraries. Discussing how keyfiles in-depth is out of the scope of this documentation, but a good resource is the freedesktop.org documentation on the .desktop file (which is a kind of keyfile.)

The following is an example plug keyfile that might be used to describe a plug for printing.

[printers.plug]
exec=Printers
icon=printers
title=Printers
category=hardware

All values are case sensitive!

The group header is a unique identifier for your plug. This is mainly useful when launching a specific plug in Switchboard via CLI (or by another app). It must be unique among all other plugs. It is typical to have the group header be your .plug file's filename with a company/organization prefix. For example, if you work for company "coolbeans", and you created a plug to manage your company's peripheral named "uberprinter", your group header might be something like "coolbeans-uberprinter.plug". You could then tell Switchboard to launch that plug specifically by running `switchboard -o coolbeans-uberprinter.plug`.

The exec entry must be the name of the binary (actual plug executable) that the .plug file is describing. For example, if your executable was called Printers, exec would be set to "Printers". The value must not be a path (relative or absolute). Switchboard expects the .plug file and the plug binary to be in the same directory.

The icon entry is the name of the system icon that your plug will be displayed with in the Switchboard application. The value must be the name of a valid system-wide icon. For example, if your plug was about printer settings, icon might be set to "printer", which is an alias of the printer icon in the elementary icon set. If you would like to use an icon that is not in the elementary icon set (for example, if your plug was about some third-party piece of hardware with a known logo), you should include the icon in the package that installs your .plug and have the package install it to the system icons directory. You should not install any icons to the plug directory, and don't expect to reference them in your .plug file if you do.

The title entry is the title that the Switchboard application shows to the user. It can be anything that is descriptive and logical. For example, if your plug was about printer settings, your title entry might be set to "Printers". Generally speaking, the title should be the pluralized, non-gerund form of the word (-ing word). So instead of "Device", use "Devices". Instead of "Printing, use "Printers". Don't obsess over this though -- it's a style guideline to ensure consistency, not cause hair loss.

The category entry is the category that the plug you're describing falls under. The Switchboard app shows plugs grouped together for convenience of the end-user. You can not make up your own category. Switchboard has pre-programmed valid categories, and will simply not add your plug if it's category is set to something invalid. The categories are localized into the language of the end-user's desktop, but the category entry is always in English. The valid values of the category entry are:

• personal
• hardware
• network
• system