HowToWritePlugins

Intro

Plugins are simple python scripts which use the API from Ubuntu Tweak. They are easy to write and well integrated with Ubuntu Tweak.

Currently the API is not stable yet, but I hope you can start to write something and give some feedback to me so I can improve Ubuntu Tweak.

Prerequisites

Tips

  • To test plugins more quickly, use this command to load from terminal:

Get Started

As you can see from the screenshot, Ubuntu Tweak consists of four main parts: "Overview", "Tweaks", "Admins" and "Janitor".

Every part is plug-able, this enables Ubuntu Tweak as a powerful and flexible system/desktop utility.

Ubuntu Tweak 0.6.0.png

Clip

The "Overview" page is the place to show some quick informations and tips, it is called "Clip". Each clip shows only one kind of information, such as "Hardware Info", "Desktop Info". Users can manage the clips which he/she want to see when start with Ubuntu Tweak, and developer can write a new Clip.

In the Preference Dialog, you can enable/disable the clips, adjust the order of Clips, or install a new clip.

Ubuntu Tweak 0.6.0 Clip Preference.png

Tweaks/Admins

The Tweaks/Admins page is the place where you can find the things to "tweak" your system.

If your plugin is making configuration changes (for example by exposing keys in GConf), you should add it to 'Tweaks'. If it is doing some other task (such as backups, updates and so on), it should be put under 'Admins'.

Ubuntu Tweak 0.6.0 Tweaks.png

Just like the Preferences of Overview, there are preferences for Tweaks/Admins too. Currently you can only enable/disable the third-party plugins.

Ubuntu Tweak 0.6.0 Tweaks Preferences.png

Janitor

Ubuntu Tweak 0.6.0 comes with a powerful "Computer Janitor" to replace the formal old pre-installed computer-janitor, but with a more simple and easy-to-use user interface.

Ubuntu Tweak 0.6.0 Janitor.png

Let's start with an example.

Examples of Plugin

Example 1 (Tweaks/Admins)

In the first example, I will add some options that deal with bluetooth file sharing.

If you've run Ubuntu Tweak 0.6 before, two folders will be created under $HOME/.config/ubuntu-tweak, they are "tweaks", "admins". These are the user plugin folders.

Create a file named "bluetoothsettings.py"(or click to download it) and put it into $HOME/.config/ubuntu-tweak/tweaks/, then fill it with the following:

# Your name, email and other copyright information

from gi.repository import Gtk #Don't support PyGtk

from ubuntutweak.gui.containers import TablePack # TablePack is a container to pack any numbers of widgets
from ubuntutweak.modules  import TweakModule # Subclass this Module then it will become a plugin of Ubuntu Tweak
from ubuntutweak.factory import WidgetFactory # Use to create the setting related widget easily

class BluetoothSettings(TweakModule):
    __title__ = _('Bluetooth Settings')
    __desc__ = _('Tweak some hidden bluetooth settings')
    __icon__ = 'bluetooth' # The icon name, currently don't support path to image
    __category__ = 'system' # the category

    __author__ = 'Your Name <your@mail.com>'
    __url__ = 'Your home page'
    __url_title__ = 'The title of Home page'

    def __init__(self):
        TweakModule.__init__(self)

        # WidgetFactory will return a tuple of widgets 
        box = TablePack(_("Bluetooth Options"), (
                    WidgetFactory.create("CheckButton",
                                         label=_('Share Public directory over Bluetooth'),
                                         key="/desktop/gnome/file_sharing/bluetooth_enabled",
                                         backend='gconf', # GSettings will support in the future
                                         enable_reset=True),
                    WidgetFactory.create("CheckButton",
                                         label=_("Whether to notify about newly received files"),
                                         key="/desktop/gnome/file_sharing/bluetooth_notify",
                                         backend='gconf',
                                         enable_reset=True),
                    WidgetFactory.create("CheckButton",
                                         label=_("Whether to allow Bluetooth clients to write files."),
                                         key="/desktop/gnome/file_sharing/bluetooth_allow_write",
                                         backend='gconf',
                                         enable_reset=True),
                    WidgetFactory.create('ComboBox',
                                         label=_('When to accept files sent over Bluetooth'),
                                         key='/desktop/gnome/file_sharing/bluetooth_accept_files',
                                         enable_reset=True,
                                         backend='gconf',
                                         texts=[_('Always'), _('Bonded'), _('Ask')],
                                         values=["always", "bonded", "ask"]),
            ))

        self.add_start(box, False, False, 0)

Now save the file, open Ubuntu Tweak, and you see what has been added? Yes, the Bluetooth Settings!

BluetoothSettings-01.png

Click it! See what you have done with just a few lines of code? A complete Bluetooth tweaking feature is almost there.

Each option automatically has a "Reset" button on the right side, so that the user can reset that option to its default value.

BluetoothSettings-02.png

I'm not good at the API design, so if you have some suggestions, please tell me, let's make it better. You can find my contact information here: http://blog.ubuntu-tweak.com/about

UbuntuTweak/HowToWritePlugins (last edited 2011-11-15 00:49:32 by tualatrix)